# Fideslog: Python SDK
[![Latest Release Version][release-image]][release-url]
[![Latest Deployment][deploy-image]][actions-url]
[![License][license-image]][license-url]
[![Code style: black][black-image]][black-url]
[![Checked with mypy][mypy-image]][mypy-url]
[![Twitter][twitter-image]][twitter-url]
## Overview
Fideslog is the [API server](../../api/), [developer SDK](../../sdk/), and [supporting infrastructure](../../../.github/workflows/deploy.yml) intended to provide Ethyca with an understanding of user interactions with fides tooling. Analytics are only used either as a factor in Ethyca's internal product roadmap determination process, or as insight into product adoption. Information collected by fideslog is received via HTTPs request, stored in a secure database, and never shared with third parties for any reason unless required by law.
This library is the recommended means by which to automate the submission of analytics data to the fideslog API server from a Python application.
## Installation
Install the fideslog Python SDK using a package manager. It is available via [PyPI](https://pypi.org/project/fideslog/). For a complete list of available release versions and their associated release notes, see [the Releases tab](https://github.com/ethyca/fideslog/releases) in the repository.
```sh
pip install fideslog
```
## Usage
### Establishing User Consent
| :memo: Note | See Ethyca's [guidelines for establishing user consent](../../../README.md#using-fideslog) for a list of requirements for collecting analytics. |
|:-----------:|:---|
It is recommended to display the content of the `OPT_OUT_COPY` constant exposed by [the `utils.py` file](./utils.py) as a means of informing users of the application's intent to collect analytics data **as early as possible within the usage workflow of the application**. If the application uses a CLI interface, the content of the `OPT_OUT_PROMPT` constant (also exposed by [the `utils.py` file](./utils.py)) can be displayed to collect explicit consent.
If the application is stateful, store the user's response within the top-level state-maintaining mechanism.
If the application is stateless, store the user's response within the application's configuration. If the application is configured with a TOML file, it is recommended to enable a `[user]` section, and store the consent within an `analytics_opt_out` configuration option. For example:
```toml
[user]
analytics_opt_out = false
```
### Identifying the Sending Application
The SDK exposes an `AnalyticsClient` class from [the `client.py` file](./client.py). Ideally only a single instance of `AnalyticsClient` will be necessary to establish the application-level details of all analytics event data emitted by the application.
The `utils.py` file exposes [the `generate_client_id()` function](https://github.com/ethyca/fideslog/blob/3dcebe735a64286d8638435a55094fbd020c153b/fideslog/sdk/python/utils.py#L22-L32), which should be used only once per application instance in order to safely generate a fully anonymized, globally unique identifier. For stateless applications, it is recommended to store this value in an `analytics_id` configuration option, or in an instance-specific database.
#### Example
```python
from platform import system
from fideslog.sdk.python.client import AnalyticsClient
from fideslog.sdk.python.utils import generate_client_id
CLIENT_ID: str = generate_client_id(b"a_fides_tool") # utils.py also exposes some helpful bytestrings
def get_version() -> str:
return "1.0.0"
def in_developer_mode() -> bool:
return False
client = AnalyticsClient(
client_id=CLIENT_ID,
developer_mode=in_developer_mode(),
extra_data={
"this data": "will be included with every event sent by this client",
"include": "any context that every event requires",
"never include": "identifying information of any kind",
},
os=system(),
product_name="a_fides_tool",
production_version=get_version(),
)
```
### Sending Analytics Data
The SDK exposes an `AnalyticsEvent` class from [the `event.py` file](./event.py). Create a new instance of `AnalyticsEvent` for every discrete event that should be persisted. Then, use the `AnalyticsClient.send()` method to make a request to the fideslog API server and persist the event.
#### Example
Building on the example from the previous section:
```python
from datetime import datetime, timezone
from platform import system
from fideslog.sdk.python.client import AnalyticsClient
from fideslog.sdk.python.event import AnalyticsEvent
from fideslog.sdk.python.utils import generate_client_id
CLIENT_ID: str = generate_client_id(b"a_fides_tool") # utils.py exposes some helpful bytestrings
def get_version() -> str:
return "1.0.0"
def in_developer_mode() -> bool:
return False
def in_docker_container() -> bool:
return True
def running_on_local_host() -> bool:
return False
client = AnalyticsClient(
client_id=CLIENT_ID,
developer_mode=in_developer_mode(),
extra_data={
"this data": "will be included with every event sent by this client",
"include": "any context that every event requires",
"never include": "identifying information of any kind",
},
os=system(),
product_name="a_fides_tool",
production_version=get_version(),
)
cli_command_event = AnalyticsEvent(
command="cli_command_name sub_command_name",
docker=in_docker_container(),
event="cli_command_executed",
error=None,
event_created_at=datetime.now(tz=timezone.utc),
extra_data={
"this data": "will be included only on this event",
"it will": "overwrite keys included in the client's extra_data",
"include": "any context that this event requires",
"never include": "identifying information of any kind",
},
flags=["--dry", "-v"],
local_host=running_on_local_host(),
resource_counts={
"datasets": 7,
"policies": 26,
"systems": 9,
},
status_code=0,
)
client.send(cli_command_event)
```
### Handling Exceptions
The SDK exposes an `AnalyticsError` type from [the `exceptions.py` file](./exceptions.py). In the event that an exception is raised by this library, it will either be a literal `AnalyticsError`, or inherit from `AnalyticsError`. In general, it is not recommended to raise these exceptions within application code, to prevent breaking the application and/or user workflow; these exceptions are intended to be written to log output, and otherwise ignored.
#### Example
Building on the example from the previous section:
```python
from datetime import datetime, timezone
from platform import system
from fideslog.sdk.python.client import AnalyticsClient
from fideslog.sdk.python.event import AnalyticsEvent
from fideslog.sdk.python.exceptions import AnalyticsError
from fideslog.sdk.python.utils import generate_client_id
CLIENT_ID: str = generate_client_id(b"a_fides_tool") # utils.py exposes some helpful bytestrings
def get_version() -> str:
return "1.0.0"
def in_developer_mode() -> bool:
return False
def in_docker_container() -> bool:
return True
def running_on_local_host() -> bool:
return False
try:
client = AnalyticsClient(
client_id=CLIENT_ID,
developer_mode=in_developer_mode(),
extra_data={
"this data": "will be included with every event sent by this client",
"include": "any context that every event requires",
"never include": "identifying information of any kind",
},
os=system(),
product_name="a_fides_tool",
production_version=get_version(),
)
cli_command_event = AnalyticsEvent(
command="cli_command_name sub_command_name",
docker=in_docker_container(),
event="cli_command_executed",
error=None,
event_created_at=datetime.now(tz=timezone.utc),
extra_data={
"this data": "will be included only on this event",
"it will": "overwrite keys included in the client's extra_data",
"include": "any context that this event requires",
"never include": "identifying information of any kind",
},
flags=["--dry", "-v"],
local_host=running_on_local_host(),
resource_counts={
"datasets": 7,
"policies": 26,
"systems": 9,
},
status_code=0,
)
client.send(cli_command_event)
except AnalyticsError as err: # It is not recommended to raise this exception,
print(err) # to prevent interrupting the application workflow.
else:
print("Analytics event sent")
```
### Registering Users
The SDK exposes a `Registration` class from [the `registration.py` file](./registration.py). Create a new instance of `Registration` for every user that should be registered. Then, use the `AnalyticsClient.register()` method to make a request to the fideslog API server and register the user.
#### Example
Building on the example from a previous section:
```python
from platform import system
from fideslog.sdk.python.client import AnalyticsClient
from fideslog.sdk.python.registration import Registration
from fideslog.sdk.python.utils import generate_client_id
CLIENT_ID: str = generate_client_id(b"a_fides_tool") # utils.py exposes some helpful bytestrings
def get_version() -> str:
return "1.0.0"
def in_developer_mode() -> bool:
return False
client = AnalyticsClient(
client_id=CLIENT_ID,
developer_mode=in_developer_mode(),
extra_data={
"this data": "will be included with every event sent by this client",
"include": "any context that every event requires",
"never include": "identifying information of any kind",
},
os=system(),
product_name="a_fides_tool",
production_version=get_version(),
)
user_registration = Registration(
email="user@example.com",
organization="Example Organization, LLC",
)
client.register(user_registration)
```
## Contributing
We welcome and encourage all types of contributions and improvements! Please see our [contribution guide](https://ethyca.github.io/fides/development/overview/) to opening issues for bugs, new features, and security or experience enhancements.
Read about the [Fides community](https://ethyca.github.io/fides/community/hints_tips/) or dive into the [development guides](https://ethyca.github.io/fides/development/overview) for information about contributions, documentation, code style, testing and more. Ethyca is committed to fostering a safe and collaborative environment, such that all interactions are governed by the [Fides Code of Conduct](https://ethyca.github.io/fides/community/code_of_conduct/).
### Support
Join the conversation on [Slack](https://fid.es/join-slack) and [Twitter](https://twitter.com/ethyca)!
## License
Fideslog and the fides ecosystem of tools are licensed under the [Apache Software License Version 2.0](https://www.apache.org/licenses/LICENSE-2.0).
Fides tools are built on [fideslang](https://github.com/ethyca/privacy-taxonomy), the fides language specification, which is licensed under [CC by 4](https://github.com/ethyca/privacy-taxonomy/blob/main/LICENSE).
Fides is created and sponsored by [Ethyca](https://ethyca.com/): a developer tools company building the trust infrastructure of the internet. If you have questions or need assistance getting started, let us know at fides@ethyca.com!
[release-image]:https://img.shields.io/github/v/release/ethyca/fideslog
[release-url]: https://github.com/ethyca/fideslog/releases
[deploy-image]: https://github.com/ethyca/fideslog/actions/workflows/deploy.yml/badge.svg
[actions-url]: https://github.com/ethyca/fideslog/actions
[license-image]: https://img.shields.io/:license-Apache%202-blue.svg
[license-url]: https://www.apache.org/licenses/LICENSE-2.0.txt
[black-image]: https://img.shields.io/badge/code%20style-black-000000.svg
[black-url]: https://github.com/psf/black/
[mypy-image]: http://www.mypy-lang.org/static/mypy_badge.svg
[mypy-url]: http://mypy-lang.org/
[twitter-image]: https://img.shields.io/twitter/follow/ethyca?style=social
[twitter-url]: https://twitter.com/ethyca
Raw data
{
"_id": null,
"home_page": "https://github.com/ethyca/fideslog",
"name": "fideslog",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8, <4",
"maintainer_email": "",
"keywords": "",
"author": "Ethyca, Inc.",
"author_email": "fidesteam@ethyca.com",
"download_url": "https://files.pythonhosted.org/packages/5d/df/718b6b3fb1e107dc38e81ade6f914e867c60bf3bc709c3f41df0a425c878/fideslog-1.2.11.tar.gz",
"platform": null,
"description": "# Fideslog: Python SDK\n\n[![Latest Release Version][release-image]][release-url]\n[![Latest Deployment][deploy-image]][actions-url]\n[![License][license-image]][license-url]\n[![Code style: black][black-image]][black-url]\n[![Checked with mypy][mypy-image]][mypy-url]\n[![Twitter][twitter-image]][twitter-url]\n\n![Fideslog banner](../../../assets/fideslog.png \"Fideslog banner\")\n\n## Overview\n\nFideslog is the [API server](../../api/), [developer SDK](../../sdk/), and [supporting infrastructure](../../../.github/workflows/deploy.yml) intended to provide Ethyca with an understanding of user interactions with fides tooling. Analytics are only used either as a factor in Ethyca's internal product roadmap determination process, or as insight into product adoption. Information collected by fideslog is received via HTTPs request, stored in a secure database, and never shared with third parties for any reason unless required by law.\n\nThis library is the recommended means by which to automate the submission of analytics data to the fideslog API server from a Python application.\n\n## Installation\n\nInstall the fideslog Python SDK using a package manager. It is available via [PyPI](https://pypi.org/project/fideslog/). For a complete list of available release versions and their associated release notes, see [the Releases tab](https://github.com/ethyca/fideslog/releases) in the repository.\n\n```sh\npip install fideslog\n```\n\n## Usage\n\n### Establishing User Consent\n\n| :memo: Note | See Ethyca's [guidelines for establishing user consent](../../../README.md#using-fideslog) for a list of requirements for collecting analytics. |\n|:-----------:|:---|\n\nIt is recommended to display the content of the `OPT_OUT_COPY` constant exposed by [the `utils.py` file](./utils.py) as a means of informing users of the application's intent to collect analytics data **as early as possible within the usage workflow of the application**. If the application uses a CLI interface, the content of the `OPT_OUT_PROMPT` constant (also exposed by [the `utils.py` file](./utils.py)) can be displayed to collect explicit consent.\n\nIf the application is stateful, store the user's response within the top-level state-maintaining mechanism.\n\nIf the application is stateless, store the user's response within the application's configuration. If the application is configured with a TOML file, it is recommended to enable a `[user]` section, and store the consent within an `analytics_opt_out` configuration option. For example:\n\n```toml\n[user]\nanalytics_opt_out = false\n```\n\n### Identifying the Sending Application\n\nThe SDK exposes an `AnalyticsClient` class from [the `client.py` file](./client.py). Ideally only a single instance of `AnalyticsClient` will be necessary to establish the application-level details of all analytics event data emitted by the application.\n\nThe `utils.py` file exposes [the `generate_client_id()` function](https://github.com/ethyca/fideslog/blob/3dcebe735a64286d8638435a55094fbd020c153b/fideslog/sdk/python/utils.py#L22-L32), which should be used only once per application instance in order to safely generate a fully anonymized, globally unique identifier. For stateless applications, it is recommended to store this value in an `analytics_id` configuration option, or in an instance-specific database.\n\n#### Example\n\n```python\nfrom platform import system\n\nfrom fideslog.sdk.python.client import AnalyticsClient\nfrom fideslog.sdk.python.utils import generate_client_id\n\nCLIENT_ID: str = generate_client_id(b\"a_fides_tool\") # utils.py also exposes some helpful bytestrings\n\n\ndef get_version() -> str:\n return \"1.0.0\"\n\ndef in_developer_mode() -> bool:\n return False\n\nclient = AnalyticsClient(\n client_id=CLIENT_ID,\n developer_mode=in_developer_mode(),\n extra_data={\n \"this data\": \"will be included with every event sent by this client\",\n \"include\": \"any context that every event requires\",\n \"never include\": \"identifying information of any kind\",\n },\n os=system(),\n product_name=\"a_fides_tool\",\n production_version=get_version(),\n)\n```\n\n### Sending Analytics Data\n\nThe SDK exposes an `AnalyticsEvent` class from [the `event.py` file](./event.py). Create a new instance of `AnalyticsEvent` for every discrete event that should be persisted. Then, use the `AnalyticsClient.send()` method to make a request to the fideslog API server and persist the event.\n\n#### Example\n\nBuilding on the example from the previous section:\n\n```python\nfrom datetime import datetime, timezone\nfrom platform import system\n\nfrom fideslog.sdk.python.client import AnalyticsClient\nfrom fideslog.sdk.python.event import AnalyticsEvent\nfrom fideslog.sdk.python.utils import generate_client_id\n\nCLIENT_ID: str = generate_client_id(b\"a_fides_tool\") # utils.py exposes some helpful bytestrings\n\n\ndef get_version() -> str:\n return \"1.0.0\"\n\ndef in_developer_mode() -> bool:\n return False\n\ndef in_docker_container() -> bool:\n return True\n\ndef running_on_local_host() -> bool:\n return False\n\nclient = AnalyticsClient(\n client_id=CLIENT_ID,\n developer_mode=in_developer_mode(),\n extra_data={\n \"this data\": \"will be included with every event sent by this client\",\n \"include\": \"any context that every event requires\",\n \"never include\": \"identifying information of any kind\",\n },\n os=system(),\n product_name=\"a_fides_tool\",\n production_version=get_version(),\n)\n\ncli_command_event = AnalyticsEvent(\n command=\"cli_command_name sub_command_name\",\n docker=in_docker_container(),\n event=\"cli_command_executed\",\n error=None,\n event_created_at=datetime.now(tz=timezone.utc),\n extra_data={\n \"this data\": \"will be included only on this event\",\n \"it will\": \"overwrite keys included in the client's extra_data\",\n \"include\": \"any context that this event requires\",\n \"never include\": \"identifying information of any kind\",\n },\n flags=[\"--dry\", \"-v\"],\n local_host=running_on_local_host(),\n resource_counts={\n \"datasets\": 7,\n \"policies\": 26,\n \"systems\": 9,\n },\n status_code=0,\n)\n\nclient.send(cli_command_event)\n```\n\n### Handling Exceptions\n\nThe SDK exposes an `AnalyticsError` type from [the `exceptions.py` file](./exceptions.py). In the event that an exception is raised by this library, it will either be a literal `AnalyticsError`, or inherit from `AnalyticsError`. In general, it is not recommended to raise these exceptions within application code, to prevent breaking the application and/or user workflow; these exceptions are intended to be written to log output, and otherwise ignored.\n\n#### Example\n\nBuilding on the example from the previous section:\n\n```python\nfrom datetime import datetime, timezone\nfrom platform import system\n\nfrom fideslog.sdk.python.client import AnalyticsClient\nfrom fideslog.sdk.python.event import AnalyticsEvent\nfrom fideslog.sdk.python.exceptions import AnalyticsError\nfrom fideslog.sdk.python.utils import generate_client_id\n\nCLIENT_ID: str = generate_client_id(b\"a_fides_tool\") # utils.py exposes some helpful bytestrings\n\n\ndef get_version() -> str:\n return \"1.0.0\"\n\ndef in_developer_mode() -> bool:\n return False\n\ndef in_docker_container() -> bool:\n return True\n\ndef running_on_local_host() -> bool:\n return False\n\ntry:\n client = AnalyticsClient(\n client_id=CLIENT_ID,\n developer_mode=in_developer_mode(),\n extra_data={\n \"this data\": \"will be included with every event sent by this client\",\n \"include\": \"any context that every event requires\",\n \"never include\": \"identifying information of any kind\",\n },\n os=system(),\n product_name=\"a_fides_tool\",\n production_version=get_version(),\n )\n\n cli_command_event = AnalyticsEvent(\n command=\"cli_command_name sub_command_name\",\n docker=in_docker_container(),\n event=\"cli_command_executed\",\n error=None,\n event_created_at=datetime.now(tz=timezone.utc),\n extra_data={\n \"this data\": \"will be included only on this event\",\n \"it will\": \"overwrite keys included in the client's extra_data\",\n \"include\": \"any context that this event requires\",\n \"never include\": \"identifying information of any kind\",\n },\n flags=[\"--dry\", \"-v\"],\n local_host=running_on_local_host(),\n resource_counts={\n \"datasets\": 7,\n \"policies\": 26,\n \"systems\": 9,\n },\n status_code=0,\n )\n\n client.send(cli_command_event)\n\nexcept AnalyticsError as err: # It is not recommended to raise this exception,\n print(err) # to prevent interrupting the application workflow.\nelse:\n print(\"Analytics event sent\")\n```\n\n### Registering Users\n\nThe SDK exposes a `Registration` class from [the `registration.py` file](./registration.py). Create a new instance of `Registration` for every user that should be registered. Then, use the `AnalyticsClient.register()` method to make a request to the fideslog API server and register the user.\n\n#### Example\n\nBuilding on the example from a previous section:\n\n```python\nfrom platform import system\n\nfrom fideslog.sdk.python.client import AnalyticsClient\nfrom fideslog.sdk.python.registration import Registration\nfrom fideslog.sdk.python.utils import generate_client_id\n\nCLIENT_ID: str = generate_client_id(b\"a_fides_tool\") # utils.py exposes some helpful bytestrings\n\n\ndef get_version() -> str:\n return \"1.0.0\"\n\ndef in_developer_mode() -> bool:\n return False\n\nclient = AnalyticsClient(\n client_id=CLIENT_ID,\n developer_mode=in_developer_mode(),\n extra_data={\n \"this data\": \"will be included with every event sent by this client\",\n \"include\": \"any context that every event requires\",\n \"never include\": \"identifying information of any kind\",\n },\n os=system(),\n product_name=\"a_fides_tool\",\n production_version=get_version(),\n)\n\nuser_registration = Registration(\n email=\"user@example.com\",\n organization=\"Example Organization, LLC\",\n)\n\nclient.register(user_registration)\n```\n\n## Contributing\n\nWe welcome and encourage all types of contributions and improvements! Please see our [contribution guide](https://ethyca.github.io/fides/development/overview/) to opening issues for bugs, new features, and security or experience enhancements.\n\nRead about the [Fides community](https://ethyca.github.io/fides/community/hints_tips/) or dive into the [development guides](https://ethyca.github.io/fides/development/overview) for information about contributions, documentation, code style, testing and more. Ethyca is committed to fostering a safe and collaborative environment, such that all interactions are governed by the [Fides Code of Conduct](https://ethyca.github.io/fides/community/code_of_conduct/).\n\n### Support\n\nJoin the conversation on [Slack](https://fid.es/join-slack) and [Twitter](https://twitter.com/ethyca)!\n\n## License\n\nFideslog and the fides ecosystem of tools are licensed under the [Apache Software License Version 2.0](https://www.apache.org/licenses/LICENSE-2.0).\nFides tools are built on [fideslang](https://github.com/ethyca/privacy-taxonomy), the fides language specification, which is licensed under [CC by 4](https://github.com/ethyca/privacy-taxonomy/blob/main/LICENSE).\n\nFides is created and sponsored by [Ethyca](https://ethyca.com/): a developer tools company building the trust infrastructure of the internet. If you have questions or need assistance getting started, let us know at fides@ethyca.com!\n\n\n\n[release-image]:https://img.shields.io/github/v/release/ethyca/fideslog\n[release-url]: https://github.com/ethyca/fideslog/releases\n[deploy-image]: https://github.com/ethyca/fideslog/actions/workflows/deploy.yml/badge.svg\n[actions-url]: https://github.com/ethyca/fideslog/actions\n[license-image]: https://img.shields.io/:license-Apache%202-blue.svg\n[license-url]: https://www.apache.org/licenses/LICENSE-2.0.txt\n[black-image]: https://img.shields.io/badge/code%20style-black-000000.svg\n[black-url]: https://github.com/psf/black/\n[mypy-image]: http://www.mypy-lang.org/static/mypy_badge.svg\n[mypy-url]: http://mypy-lang.org/\n[twitter-image]: https://img.shields.io/twitter/follow/ethyca?style=social\n[twitter-url]: https://twitter.com/ethyca\n\n\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "The fideslog analytics collection mechanism",
"version": "1.2.11",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5ddf718b6b3fb1e107dc38e81ade6f914e867c60bf3bc709c3f41df0a425c878",
"md5": "121dfbb86aa02f6e32f1ef074adc0c25",
"sha256": "286eed57706379fa360922df8ef91ec526836dc7cdf53e9f4ff2209619e688cb"
},
"downloads": -1,
"filename": "fideslog-1.2.11.tar.gz",
"has_sig": false,
"md5_digest": "121dfbb86aa02f6e32f1ef074adc0c25",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8, <4",
"size": 39579,
"upload_time": "2023-01-24T00:19:21",
"upload_time_iso_8601": "2023-01-24T00:19:21.387677Z",
"url": "https://files.pythonhosted.org/packages/5d/df/718b6b3fb1e107dc38e81ade6f914e867c60bf3bc709c3f41df0a425c878/fideslog-1.2.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-24 00:19:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "ethyca",
"github_project": "fideslog",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "fideslog"
}
JSON
