diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | python-humbug.spec | 615 | ||||
| -rw-r--r-- | sources | 1 |
3 files changed, 617 insertions, 0 deletions
@@ -0,0 +1 @@ +/humbug-0.3.1.tar.gz diff --git a/python-humbug.spec b/python-humbug.spec new file mode 100644 index 0000000..83e82d6 --- /dev/null +++ b/python-humbug.spec @@ -0,0 +1,615 @@ +%global _empty_manifest_terminate_build 0 +Name: python-humbug +Version: 0.3.1 +Release: 1 +Summary: Humbug: Do you build developer tools? Humbug helps you know your users. +License: Apache Software License +URL: https://github.com/bugout-dev/humbug +Source0: https://mirrors.nju.edu.cn/pypi/web/packages/39/88/188290a6b580b63db943bf26df716e463d6b76860827a18d82e3fabd330a/humbug-0.3.1.tar.gz +BuildArch: noarch + +Requires: python3-requests +Requires: python3-dataclasses +Requires: python3-black +Requires: python3-mypy +Requires: python3-wheel +Requires: python3-types-pkg-resources +Requires: python3-types-requests +Requires: python3-types-dataclasses +Requires: python3-types-psutil +Requires: python3-setuptools +Requires: python3-twine +Requires: python3-wheel +Requires: python3-psutil +Requires: python3-GPUtil +Requires: python3-types-psutil + +%description +# Humbug Python + +The Humbug Python library. + +## Installation + +### Using pip + +```bash +pip install humbug +``` + +### From source + +Clone this repository and enter this directory. Make sure you are in your desired Python environment +and then run: + +```bash +python setup.py install +``` + +## Integration + +To add Humbug to your project, first create a Bugout access token and journal [following these +instructions](../README.md#trying-it-out). + +You can follow the recipes below to integrate Humbug into your codebase: + +1. [Error reporting](./recipes/error_reporting.py) +1. [System reporting](./recipes/system_reporting.py) + +All reports are generated (and published) by a Humbug reporter. By default, Humbug publishes all +reports asynchronously and in the background. If you would like to publish selected reports +synchronously, all reporter methods take a `wait=True` argument. + +If you plan to _only_ use a reporter synchronously or to do your own thread management, you can +instantiate the reporter in synchronous mode: + +```python +from humbug.report import Reporter, Modes + +reporter = Reporter( + "<name>", + client_id="<client_id>", + session_id="<session_id>", + bugout_token="<bugout_token>", + bugout_journal_id="<bugout_journal_id>", + mode=Modes.SYNCHRONOUS, +) +``` + +Using Modes.SYNCHRONOUS in this manner skips the creation of the thread from which the reporter +publishes reports. + +### Consent + +Humbug cares deeply about consent. The innocuous `HumbugConsent` from the snippet above supports +a wide range of consent flows. + +#### Opting in with environment variables + +For example, if you would like your users to be able to opt in by setting an environment variable +`MY_APP_CONSENT=true`: + +```python +from humbug.consent import environment_variable_opt_in, HumbugConsent +from humbug.report import Reporter + +consent = HumbugConsent(environment_variable_opt_in("MY_APP_CONSENT", ["true"])) +reporter = Reporter( + "<name of your project>", + consent, + bugout_token="<your Bugout token>", + bugout_journal_id="<your Bugout journal ID>", +) +``` + +If you use this configuration, unless your user uses your tool with `MY_APP_CONSENT=true`, no +reports will ever get sent to your knowledge base. + +#### Opting out with environment variables + +If, [like `homebrew`](https://docs.brew.sh/Analytics#opting-out), you would like users to be able to +opt out by setting an environment variable `MY_APP_NO_CONSENT=1`: + +```python +from humbug.consent import environment_variable_opt_out, HumbugConsent +from humbug.report import Reporter + +consent = HumbugConsent(environment_variable_opt_out("MY_APP_NO_CONSENT", ["1"])) +reporter = Reporter( + "<name of your project>", + consent, + bugout_token="<your Bugout access token>", + bugout_journal_id="<your Bugout journal ID>", +) +``` + +In this case, reports are sent by default unless the user sets `MY_APP_NO_CONSENT=1` in which +case reports will never be sent. + +#### Composing consent mechanisms + +Humbug allows you to combine multiple consent mechanisms. For example: + +```python +from humbug.consent import environment_variable_opt_in, environment_variable_opt_out, HumbugConsent +from humbug.report import Reporter + +consent = HumbugConsent( + environment_variable_opt_in("MY_APP_CONSENT", ["true"]), + environment_variable_opt_out("MY_APP_NO_CONSENT", ["1"]), +) +reporter = Reporter( + "<name of your project>", + consent, + bugout_token="<your Bugout access token>", + bugout_journal_id="<your Bugout journal ID>", +) +``` + +If your users do not set `MY_APP_CONSENT` or give it a value other than `true`, Humbug won't even +bother to send you any reports. If `MY_APP_CONSENT` is indeed set to `true`, but the user has +set `MY_APP_NO_CONSENT=1`, then again no reports will get sent back. + +On the other hand, if the user has set `MY_APP_CONSENT=true` and left `MY_APP_NO_CONSENT` unset or +set to a value other than `1`, Humbug will send you any reports you have configured. + +### Blacklisting parameters in feature reports + +Arguments to functions and other callables can sometimes contain sensitive information which you may +not want to include in Humbug reports. + +Blacklist functions allow you to specify which parameters from an argument list to filter out of your +feature reports. + +#### `blacklist.generate_filter_parameters_by_key_fn` + +If you would just like to filter out all paramters with a given name, you can use the `blacklist.generate_filter_parameters_by_key_fn`. + +For example, to ignore all parameters named `token` (case insensitive), you would instantiate your +`HumbugReporter` as follows: + +```python +reporter = HumbugReporter( + ..., + blacklist_fn=blacklist.generate_filter_parameters_by_key_fn(["token"]), +) +``` + +#### Custom blacklist functions + +You could also implement a custom blacklist function to remove all parameters that contained the substring +`token` (case insensitive): + +```python +def blacklist_token_parameters_fn(params: Dict[str, Any]) -> Dict[str, Any]: + admissible_params = {k:v for k, v in params.items() if "token" not in k} + return admissible_params + +reporter = HumbugReporter( + ..., + blacklist_fn=blacklist_token_parameters_fn +) +``` + +### Case study: activeloopai/deeplake + +[This pull request](https://github.com/activeloopai/deeplake/pull/624) shows how +[Activeloop](https://www.activeloop.ai/) integrated Humbug into their popular +[`deeplake`](https://github.com/activeloopai/deeplake) tool. + +This example shows how to use Humbug to record consent in a configuration file that the user +can modify at will. It also shows how to add custom tags to your Humbug reports. + + + + +%package -n python3-humbug +Summary: Humbug: Do you build developer tools? Humbug helps you know your users. +Provides: python-humbug +BuildRequires: python3-devel +BuildRequires: python3-setuptools +BuildRequires: python3-pip +%description -n python3-humbug +# Humbug Python + +The Humbug Python library. + +## Installation + +### Using pip + +```bash +pip install humbug +``` + +### From source + +Clone this repository and enter this directory. Make sure you are in your desired Python environment +and then run: + +```bash +python setup.py install +``` + +## Integration + +To add Humbug to your project, first create a Bugout access token and journal [following these +instructions](../README.md#trying-it-out). + +You can follow the recipes below to integrate Humbug into your codebase: + +1. [Error reporting](./recipes/error_reporting.py) +1. [System reporting](./recipes/system_reporting.py) + +All reports are generated (and published) by a Humbug reporter. By default, Humbug publishes all +reports asynchronously and in the background. If you would like to publish selected reports +synchronously, all reporter methods take a `wait=True` argument. + +If you plan to _only_ use a reporter synchronously or to do your own thread management, you can +instantiate the reporter in synchronous mode: + +```python +from humbug.report import Reporter, Modes + +reporter = Reporter( + "<name>", + client_id="<client_id>", + session_id="<session_id>", + bugout_token="<bugout_token>", + bugout_journal_id="<bugout_journal_id>", + mode=Modes.SYNCHRONOUS, +) +``` + +Using Modes.SYNCHRONOUS in this manner skips the creation of the thread from which the reporter +publishes reports. + +### Consent + +Humbug cares deeply about consent. The innocuous `HumbugConsent` from the snippet above supports +a wide range of consent flows. + +#### Opting in with environment variables + +For example, if you would like your users to be able to opt in by setting an environment variable +`MY_APP_CONSENT=true`: + +```python +from humbug.consent import environment_variable_opt_in, HumbugConsent +from humbug.report import Reporter + +consent = HumbugConsent(environment_variable_opt_in("MY_APP_CONSENT", ["true"])) +reporter = Reporter( + "<name of your project>", + consent, + bugout_token="<your Bugout token>", + bugout_journal_id="<your Bugout journal ID>", +) +``` + +If you use this configuration, unless your user uses your tool with `MY_APP_CONSENT=true`, no +reports will ever get sent to your knowledge base. + +#### Opting out with environment variables + +If, [like `homebrew`](https://docs.brew.sh/Analytics#opting-out), you would like users to be able to +opt out by setting an environment variable `MY_APP_NO_CONSENT=1`: + +```python +from humbug.consent import environment_variable_opt_out, HumbugConsent +from humbug.report import Reporter + +consent = HumbugConsent(environment_variable_opt_out("MY_APP_NO_CONSENT", ["1"])) +reporter = Reporter( + "<name of your project>", + consent, + bugout_token="<your Bugout access token>", + bugout_journal_id="<your Bugout journal ID>", +) +``` + +In this case, reports are sent by default unless the user sets `MY_APP_NO_CONSENT=1` in which +case reports will never be sent. + +#### Composing consent mechanisms + +Humbug allows you to combine multiple consent mechanisms. For example: + +```python +from humbug.consent import environment_variable_opt_in, environment_variable_opt_out, HumbugConsent +from humbug.report import Reporter + +consent = HumbugConsent( + environment_variable_opt_in("MY_APP_CONSENT", ["true"]), + environment_variable_opt_out("MY_APP_NO_CONSENT", ["1"]), +) +reporter = Reporter( + "<name of your project>", + consent, + bugout_token="<your Bugout access token>", + bugout_journal_id="<your Bugout journal ID>", +) +``` + +If your users do not set `MY_APP_CONSENT` or give it a value other than `true`, Humbug won't even +bother to send you any reports. If `MY_APP_CONSENT` is indeed set to `true`, but the user has +set `MY_APP_NO_CONSENT=1`, then again no reports will get sent back. + +On the other hand, if the user has set `MY_APP_CONSENT=true` and left `MY_APP_NO_CONSENT` unset or +set to a value other than `1`, Humbug will send you any reports you have configured. + +### Blacklisting parameters in feature reports + +Arguments to functions and other callables can sometimes contain sensitive information which you may +not want to include in Humbug reports. + +Blacklist functions allow you to specify which parameters from an argument list to filter out of your +feature reports. + +#### `blacklist.generate_filter_parameters_by_key_fn` + +If you would just like to filter out all paramters with a given name, you can use the `blacklist.generate_filter_parameters_by_key_fn`. + +For example, to ignore all parameters named `token` (case insensitive), you would instantiate your +`HumbugReporter` as follows: + +```python +reporter = HumbugReporter( + ..., + blacklist_fn=blacklist.generate_filter_parameters_by_key_fn(["token"]), +) +``` + +#### Custom blacklist functions + +You could also implement a custom blacklist function to remove all parameters that contained the substring +`token` (case insensitive): + +```python +def blacklist_token_parameters_fn(params: Dict[str, Any]) -> Dict[str, Any]: + admissible_params = {k:v for k, v in params.items() if "token" not in k} + return admissible_params + +reporter = HumbugReporter( + ..., + blacklist_fn=blacklist_token_parameters_fn +) +``` + +### Case study: activeloopai/deeplake + +[This pull request](https://github.com/activeloopai/deeplake/pull/624) shows how +[Activeloop](https://www.activeloop.ai/) integrated Humbug into their popular +[`deeplake`](https://github.com/activeloopai/deeplake) tool. + +This example shows how to use Humbug to record consent in a configuration file that the user +can modify at will. It also shows how to add custom tags to your Humbug reports. + + + + +%package help +Summary: Development documents and examples for humbug +Provides: python3-humbug-doc +%description help +# Humbug Python + +The Humbug Python library. + +## Installation + +### Using pip + +```bash +pip install humbug +``` + +### From source + +Clone this repository and enter this directory. Make sure you are in your desired Python environment +and then run: + +```bash +python setup.py install +``` + +## Integration + +To add Humbug to your project, first create a Bugout access token and journal [following these +instructions](../README.md#trying-it-out). + +You can follow the recipes below to integrate Humbug into your codebase: + +1. [Error reporting](./recipes/error_reporting.py) +1. [System reporting](./recipes/system_reporting.py) + +All reports are generated (and published) by a Humbug reporter. By default, Humbug publishes all +reports asynchronously and in the background. If you would like to publish selected reports +synchronously, all reporter methods take a `wait=True` argument. + +If you plan to _only_ use a reporter synchronously or to do your own thread management, you can +instantiate the reporter in synchronous mode: + +```python +from humbug.report import Reporter, Modes + +reporter = Reporter( + "<name>", + client_id="<client_id>", + session_id="<session_id>", + bugout_token="<bugout_token>", + bugout_journal_id="<bugout_journal_id>", + mode=Modes.SYNCHRONOUS, +) +``` + +Using Modes.SYNCHRONOUS in this manner skips the creation of the thread from which the reporter +publishes reports. + +### Consent + +Humbug cares deeply about consent. The innocuous `HumbugConsent` from the snippet above supports +a wide range of consent flows. + +#### Opting in with environment variables + +For example, if you would like your users to be able to opt in by setting an environment variable +`MY_APP_CONSENT=true`: + +```python +from humbug.consent import environment_variable_opt_in, HumbugConsent +from humbug.report import Reporter + +consent = HumbugConsent(environment_variable_opt_in("MY_APP_CONSENT", ["true"])) +reporter = Reporter( + "<name of your project>", + consent, + bugout_token="<your Bugout token>", + bugout_journal_id="<your Bugout journal ID>", +) +``` + +If you use this configuration, unless your user uses your tool with `MY_APP_CONSENT=true`, no +reports will ever get sent to your knowledge base. + +#### Opting out with environment variables + +If, [like `homebrew`](https://docs.brew.sh/Analytics#opting-out), you would like users to be able to +opt out by setting an environment variable `MY_APP_NO_CONSENT=1`: + +```python +from humbug.consent import environment_variable_opt_out, HumbugConsent +from humbug.report import Reporter + +consent = HumbugConsent(environment_variable_opt_out("MY_APP_NO_CONSENT", ["1"])) +reporter = Reporter( + "<name of your project>", + consent, + bugout_token="<your Bugout access token>", + bugout_journal_id="<your Bugout journal ID>", +) +``` + +In this case, reports are sent by default unless the user sets `MY_APP_NO_CONSENT=1` in which +case reports will never be sent. + +#### Composing consent mechanisms + +Humbug allows you to combine multiple consent mechanisms. For example: + +```python +from humbug.consent import environment_variable_opt_in, environment_variable_opt_out, HumbugConsent +from humbug.report import Reporter + +consent = HumbugConsent( + environment_variable_opt_in("MY_APP_CONSENT", ["true"]), + environment_variable_opt_out("MY_APP_NO_CONSENT", ["1"]), +) +reporter = Reporter( + "<name of your project>", + consent, + bugout_token="<your Bugout access token>", + bugout_journal_id="<your Bugout journal ID>", +) +``` + +If your users do not set `MY_APP_CONSENT` or give it a value other than `true`, Humbug won't even +bother to send you any reports. If `MY_APP_CONSENT` is indeed set to `true`, but the user has +set `MY_APP_NO_CONSENT=1`, then again no reports will get sent back. + +On the other hand, if the user has set `MY_APP_CONSENT=true` and left `MY_APP_NO_CONSENT` unset or +set to a value other than `1`, Humbug will send you any reports you have configured. + +### Blacklisting parameters in feature reports + +Arguments to functions and other callables can sometimes contain sensitive information which you may +not want to include in Humbug reports. + +Blacklist functions allow you to specify which parameters from an argument list to filter out of your +feature reports. + +#### `blacklist.generate_filter_parameters_by_key_fn` + +If you would just like to filter out all paramters with a given name, you can use the `blacklist.generate_filter_parameters_by_key_fn`. + +For example, to ignore all parameters named `token` (case insensitive), you would instantiate your +`HumbugReporter` as follows: + +```python +reporter = HumbugReporter( + ..., + blacklist_fn=blacklist.generate_filter_parameters_by_key_fn(["token"]), +) +``` + +#### Custom blacklist functions + +You could also implement a custom blacklist function to remove all parameters that contained the substring +`token` (case insensitive): + +```python +def blacklist_token_parameters_fn(params: Dict[str, Any]) -> Dict[str, Any]: + admissible_params = {k:v for k, v in params.items() if "token" not in k} + return admissible_params + +reporter = HumbugReporter( + ..., + blacklist_fn=blacklist_token_parameters_fn +) +``` + +### Case study: activeloopai/deeplake + +[This pull request](https://github.com/activeloopai/deeplake/pull/624) shows how +[Activeloop](https://www.activeloop.ai/) integrated Humbug into their popular +[`deeplake`](https://github.com/activeloopai/deeplake) tool. + +This example shows how to use Humbug to record consent in a configuration file that the user +can modify at will. It also shows how to add custom tags to your Humbug reports. + + + + +%prep +%autosetup -n humbug-0.3.1 + +%build +%py3_build + +%install +%py3_install +install -d -m755 %{buildroot}/%{_pkgdocdir} +if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi +if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi +if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi +if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi +pushd %{buildroot} +if [ -d usr/lib ]; then + find usr/lib -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/lib64 ]; then + find usr/lib64 -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/bin ]; then + find usr/bin -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/sbin ]; then + find usr/sbin -type f -printf "/%h/%f\n" >> filelist.lst +fi +touch doclist.lst +if [ -d usr/share/man ]; then + find usr/share/man -type f -printf "/%h/%f.gz\n" >> doclist.lst +fi +popd +mv %{buildroot}/filelist.lst . +mv %{buildroot}/doclist.lst . + +%files -n python3-humbug -f filelist.lst +%dir %{python3_sitelib}/* + +%files help -f doclist.lst +%{_docdir}/* + +%changelog +* Mon Apr 10 2023 Python_Bot <Python_Bot@openeuler.org> - 0.3.1-1 +- Package Spec generated @@ -0,0 +1 @@ +0fb19d12e457d7a7b46c91066b6de186 humbug-0.3.1.tar.gz |