{"id":19849557,"url":"https://github.com/astrolytics-io/nucleus-python","last_synced_at":"2026-01-29T11:35:51.556Z","repository":{"id":57447192,"uuid":"217088379","full_name":"astrolytics-io/nucleus-python","owner":"astrolytics-io","description":"The easy way to track users in your Python application","archived":false,"fork":false,"pushed_at":"2020-04-15T14:43:28.000Z","size":24,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-10T11:37:45.681Z","etag":null,"topics":["analytics","bug-tracker","desktop","python3"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/astrolytics-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-10-23T15:14:59.000Z","updated_at":"2023-08-28T04:10:01.000Z","dependencies_parsed_at":"2022-09-02T23:41:17.390Z","dependency_job_id":null,"html_url":"https://github.com/astrolytics-io/nucleus-python","commit_stats":null,"previous_names":["astrolytics-io/nucleus-python","nucleus-sh/nucleus-python"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astrolytics-io%2Fnucleus-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astrolytics-io%2Fnucleus-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astrolytics-io%2Fnucleus-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astrolytics-io%2Fnucleus-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/astrolytics-io","download_url":"https://codeload.github.com/astrolytics-io/nucleus-python/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251954776,"owners_count":21670870,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analytics","bug-tracker","desktop","python3"],"created_at":"2024-11-12T13:21:39.839Z","updated_at":"2026-01-29T11:35:46.516Z","avatar_url":"https://github.com/astrolytics-io.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nucleus-python ![PyPI](https://img.shields.io/pypi/v/nucleus-python) ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/nucleus-python) \n\nWe tried to make it as simple as possible to report the data you need to analyze your app usage and improve it.\n\nThis module is compatible with Python 3+.\n\nTo start using this module, sign up and get an app ID on [Nucleus.sh](https://nucleus.sh). \n\n## Installation\n\n```bash\n$ pip install nucleus-python\n```\n\n## Basic usage\n\nAdd the following code to import Nucleus and init the analytics.\n\nDon't use the `import ... from` syntax as you won't be able to set the module options like `app_id`.\n\n\n```python\nimport nucleus\n\nnucleus.app_id = 'your app id'\n\nnucleus.set_props({\n\t'version': '0.5.0', # Set app version (Nucleus cannot detect it)\n\t'userId': 'richard_hendrix'\n})\n\nnucleus.app_started()\n```\n\n**Only use `app_started()` once per session, if you are using Nucleus in several files call app_started() the earliest possible.**\n\nSign up and get a tracking ID for your app [here](https://nucleus.sh).\n\n### Options\n\nYou can init Nucleus with options:\n\n```python\nnucleus.report_interval = 20 # interval (in seconds) between server com\nnucleus.disable_tracking = False # completely disable tracking\nnucleus.debug = False # Show internal logs to help debug\nnucleus.auto_user_id = False # Assign the user an ID\n```\n\n### Identify users\n\nYou can track specific users actions on the 'User Explorer' section of your dashboard by assigning an user ID. \n\nIt can be any value as long as it is a *string*.\n\n```python\nnucleus.set_user_id('someUniqueUserId')\n```\n\nAlternatively, set the `auto_user_id` option of the module to `True` to automatically assign the user an ID based on his username and hostname.\n\n### Modify automatic data\n\nYou can overwrite some properties or fill data that wasn't detected.\n\n*You have to do it before calling `app_started()` for this to work*\n\nIt is a good idea to set your app version directly as Nucleus **cannot detect it** for the moment.\n\n```python\nnucleus.set_props({\n\t'version': '0.5.0',\n\t'locale': 'en_US'\n})\n```\n\n### Track custom data\n\nYou can also add custom data along with the automatic data.\n \nThose will be visible in your user dashboard *if you previously set an user ID*.\n\nThe module will remember past properties so you can use `nucleus.set_props` multiple times without overwriting past props.\n\nProperties can either **numbers**, **strings** or **booleans**. \nNested properties or arrays aren't supported at the moment.\n\n```python\nnucleus.set_props({\n\t\"age\": 34,\n\t\"name\": 'Richard Hendricks',\n\t\"job\": 'CEO'\n})\n```\n\nTo overwrite past properties, set the second parameter to `True`. \n\n```python\nnucleus.set_props({\n\t\"age\": 23\n}, True)\n```\n\n### Errors\n\nTo catch errors with Nucleus, simply add the tracking code to an exception and pass the exception as the unique parameter. \n\nNucleus will extract the relevant informations and show them in your dashboard.\n\n```python\ntry:\n    my_app()\nexcept Exception as e:\n\tnucleus.track_error(e)\n```\n\nAdd this at the outermost level of your code to handle any otherwise uncaught exceptions before terminating.\n\nThe advantage of except Exception over the bare except is that there are a few exceptions that it wont catch, most obviously KeyboardInterrupt and SystemExit.\n\n\n### Events\n\nAfter initializing Nucleus, you can send your own custom events.\n\n```python\nnucleus.track(\"PLAYED_TRACK\")\n```\n\nThey are a couple event names that are reserved by Nucleus: `init`, `error:` and `nucleus:`.\n\nYou shouldn't report events containing these strings.\n\n#### Tracking with data\n\nYou can add extra information to tracked events, as an object.\n\nProperties can either **numbers**, **strings** or **booleans**. \n\nNested properties or arrays aren't supported at the moment.\n\nExample:\n\n```python\nnucleus.track(\"PLAYED_TRACK\", data = {\n\t\"trackName\": 'My Awesome Song',\n\t\"duration\": 120\n})\n```\n\n### Toggle tracking\n\nThis will completely disable any communication with Nucleus' servers.\n\nTo opt-out your users from tracking:\n\n```python\nnucleus.disable_tracking()\n```\n\nand to opt back in:\n\n```python\nnucleus.enable_tracking()\n```\n\nThis doesn't persist after restarts so you have to handle saving the setting.\n\n---\nContact **hello@nucleus.sh** for any inquiry\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fastrolytics-io%2Fnucleus-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fastrolytics-io%2Fnucleus-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fastrolytics-io%2Fnucleus-python/lists"}