| Name | umami-analytics-py JSON |
| Version |
0.2.22
JSON |
| download |
| home_page | None |
| Summary | Umami Analytics Client for Python |
| upload_time | 2025-07-18 02:44:09 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
analytics
umami
website
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Umami Analytics Client for Python
Client for privacy-preserving, open source [Umami analytics platform](https://umami.is) based on
`httpx` and `pydantic`.
`umami-analytics` is intended for adding custom data to your Umami instance (self-hosted or SaaS). Many umami events can supplied directly from HTML via their `data-*` attributes. However, some cannot. For example, if you have an event that is triggered in your app but doesn't have a clear HTML action you can add custom events. These will appear at the bottom of your Umami analtytics page for a website.
One example is a **purchase-course** event that happens deep inside the Python code rather than in HTML at [Talk Python Training](https://training.talkpython.fm). This is what our events section looks like for a typical weekend day (US Pacific Time):
## Focused on what you need, not what is offered
The [Umami API is extensive](https://umami.is/docs/api) and much of that is intended for their frontend code to be able to function. You probably don't want or need that. `umami-analytics` only covers the subset that most developers will need for common SaaS actions such as adding [custom events](https://umami.is/docs/event-data). That said, PRs are weclome.
## Core Features
* ➕ **Add a custom event** to your Umami analytics dashboard.
* 📄 **Add a page view** to your Umami analytics dashboard.
* 🌐 List all websites with details that you have registered at Umami.
* 📊 **Get website statistics** including page views, visitors, bounce rate, and more.
* 👥 **Get active users** count for real-time monitoring.
* 💓 **Heartbeat check** to verify Umami server connectivity.
* 🔀 Both **sync** and **async** programming models.
* ⚒️ **Structured data with Pydantic** models for API responses.
* 👩💻 **Login / authenticate** for either a self-hosted or SaaS hosted instance of Umami.
* 🥇Set a **default website** for a **simplified API** going forward.
* 🔧 **Enable/disable tracking** for development and testing environments.
## Development and Testing Support
🔧 **Disable tracking in development**: Use `umami.disable()` to disable all event and page view tracking without changing your code. Perfect for development and testing environments where you don't want to pollute your analytics with test data.
```python
import umami
# Configure as usual
umami.set_url_base("https://umami.hostedbyyouorthem.com")
umami.set_website_id('cc726914-8e68-4d1a-4be0-af4ca8933456')
umami.set_hostname('somedomain.com')
# Disable tracking for development/testing
umami.disable()
# These calls will return immediately without sending data to Umami
umami.new_event('test-event') # No HTTP request made
umami.new_page_view('Test Page', '/test') # No HTTP request made
# Re-enable when needed (default state is enabled)
umami.enable()
```
When tracking is disabled:
- ✅ **No HTTP requests** are made to your Umami server
- ✅ **API calls still validate** parameters (helps catch configuration issues)
- ✅ **All other functions work normally** (login, websites, stats, etc.)
- ✅ **Functions return appropriate values** for compatibility
See the usage example below for the Python API around these features.
## Async or sync API? You choose
🔀 **Async is supported but not required** for your Python code. For functions that access the network, there is a `func()` and `func_async()` variant that works with Python's `async` and `await`.
## Installation
Just `pip install umami-analytics`
## Usage
```python
import umami
umami.set_url_base("https://umami.hostedbyyouorthem.com")
# Auth is NOT required to send events, but is for other features.
login = umami.login(username, password)
# Skip the need to pass the target website in subsequent calls.
umami.set_website_id('cc726914-8e68-4d1a-4be0-af4ca8933456')
umami.set_hostname('somedomain.com')
# Optional: Disable tracking for development/testing
# umami.disable() # Uncomment to disable tracking
# List your websites
websites = umami.websites()
# Create a new event in the events section of the dashboards.
event_resp = umami.new_event(
website_id='a7cd-5d1a-2b33', # Only send if overriding default above
event_name='Umami-Test',
title='Umami-Test', # Defaults to event_name if omitted.
hostname='somedomain.com', # Only send if overriding default above.
url='/users/actions',
custom_data={'client': 'umami-tester-v1'},
referrer='https://some_url')
# Create a new page view in the pages section of the dashboards.
page_view_resp = umami.new_page_view(
website_id='a7cd-5d1a-2b33', # Only send if overriding default above
page_title='Umami-Test', # Defaults to event_name if omitted.
hostname='somedomain.com', # Only send if overriding default above.
url='/users/actions',
referrer='https://some_url')
# Get website statistics for a date range
from datetime import datetime, timedelta
end_date = datetime.now()
start_date = end_date - timedelta(days=7) # Last 7 days
stats = umami.website_stats(
start_at=start_date,
end_at=end_date,
website_id='a7cd-5d1a-2b33' # Only send if overriding default above
)
print(f"Page views: {stats.pageviews}")
print(f"Unique visitors: {stats.visitors}")
print(f"Bounce rate: {stats.bounces}")
# Get current active users count
active_count = umami.active_users(
website_id='a7cd-5d1a-2b33' # Only send if overriding default above
)
print(f"Currently active users: {active_count}")
# Check if Umami server is accessible
server_ok = umami.heartbeat()
print(f"Umami server is {'accessible' if server_ok else 'not accessible'}")
# Call after logging in to make sure the auth token is still valid.
umami.verify_token()
```
This code listing is very-very high fidelity psuedo code. If you want an actually executable example, see the [example client](./umami/example_client) in the repo.
## Want to contribute?
See the [API documentation](https://umami.is/docs/api) for the remaining endpoints to be added. PRs are welcome. But please open an issue first to see if the proposed feature fits with the direction of this library.
Enjoy.
Raw data
{
"_id": null,
"home_page": null,
"name": "umami-analytics-py",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "analytics, umami, website",
"author": null,
"author_email": "Michael Kennedy <michael@talkpython.fm>",
"download_url": "https://files.pythonhosted.org/packages/f9/02/39d2718b6f17bf42d401189fd9d04ade883a6cbfee035d0ded427bb5de9a/umami_analytics_py-0.2.22.tar.gz",
"platform": null,
"description": "# Umami Analytics Client for Python\n\nClient for privacy-preserving, open source [Umami analytics platform](https://umami.is) based on \n`httpx` and `pydantic`. \n\n`umami-analytics` is intended for adding custom data to your Umami instance (self-hosted or SaaS). Many umami events can supplied directly from HTML via their `data-*` attributes. However, some cannot. For example, if you have an event that is triggered in your app but doesn't have a clear HTML action you can add custom events. These will appear at the bottom of your Umami analtytics page for a website.\n\nOne example is a **purchase-course** event that happens deep inside the Python code rather than in HTML at [Talk Python Training](https://training.talkpython.fm). This is what our events section looks like for a typical weekend day (US Pacific Time):\n\n\n\n## Focused on what you need, not what is offered\n\nThe [Umami API is extensive](https://umami.is/docs/api) and much of that is intended for their frontend code to be able to function. You probably don't want or need that. `umami-analytics` only covers the subset that most developers will need for common SaaS actions such as adding [custom events](https://umami.is/docs/event-data). That said, PRs are weclome.\n\n## Core Features\n\n* \u2795 **Add a custom event** to your Umami analytics dashboard.\n* \ud83d\udcc4 **Add a page view** to your Umami analytics dashboard.\n* \ud83c\udf10 List all websites with details that you have registered at Umami.\n* \ud83d\udcca **Get website statistics** including page views, visitors, bounce rate, and more.\n* \ud83d\udc65 **Get active users** count for real-time monitoring.\n* \ud83d\udc93 **Heartbeat check** to verify Umami server connectivity.\n* \ud83d\udd00 Both **sync** and **async** programming models.\n* \u2692\ufe0f **Structured data with Pydantic** models for API responses.\n* \ud83d\udc69\u200d\ud83d\udcbb **Login / authenticate** for either a self-hosted or SaaS hosted instance of Umami.\n* \ud83e\udd47Set a **default website** for a **simplified API** going forward.\n* \ud83d\udd27 **Enable/disable tracking** for development and testing environments.\n\n## Development and Testing Support\n\n\ud83d\udd27 **Disable tracking in development**: Use `umami.disable()` to disable all event and page view tracking without changing your code. Perfect for development and testing environments where you don't want to pollute your analytics with test data.\n\n```python\nimport umami\n\n# Configure as usual\numami.set_url_base(\"https://umami.hostedbyyouorthem.com\")\numami.set_website_id('cc726914-8e68-4d1a-4be0-af4ca8933456')\numami.set_hostname('somedomain.com')\n\n# Disable tracking for development/testing\numami.disable()\n\n# These calls will return immediately without sending data to Umami\numami.new_event('test-event') # No HTTP request made\numami.new_page_view('Test Page', '/test') # No HTTP request made\n\n# Re-enable when needed (default state is enabled)\numami.enable()\n```\n\nWhen tracking is disabled:\n- \u2705 **No HTTP requests** are made to your Umami server\n- \u2705 **API calls still validate** parameters (helps catch configuration issues)\n- \u2705 **All other functions work normally** (login, websites, stats, etc.)\n- \u2705 **Functions return appropriate values** for compatibility\n\nSee the usage example below for the Python API around these features.\n\n## Async or sync API? You choose\n\n\ud83d\udd00 **Async is supported but not required** for your Python code. For functions that access the network, there is a `func()` and `func_async()` variant that works with Python's `async` and `await`.\n\n## Installation\n\nJust `pip install umami-analytics`\n\n## Usage\n\n```python\n\nimport umami\n\numami.set_url_base(\"https://umami.hostedbyyouorthem.com\")\n\n# Auth is NOT required to send events, but is for other features.\nlogin = umami.login(username, password)\n\n# Skip the need to pass the target website in subsequent calls.\numami.set_website_id('cc726914-8e68-4d1a-4be0-af4ca8933456')\numami.set_hostname('somedomain.com')\n\n# Optional: Disable tracking for development/testing\n# umami.disable() # Uncomment to disable tracking\n\n# List your websites\nwebsites = umami.websites()\n\n# Create a new event in the events section of the dashboards.\nevent_resp = umami.new_event(\n website_id='a7cd-5d1a-2b33', # Only send if overriding default above\n event_name='Umami-Test',\n title='Umami-Test', # Defaults to event_name if omitted.\n hostname='somedomain.com', # Only send if overriding default above.\n url='/users/actions',\n custom_data={'client': 'umami-tester-v1'},\n referrer='https://some_url')\n\n# Create a new page view in the pages section of the dashboards.\npage_view_resp = umami.new_page_view(\n website_id='a7cd-5d1a-2b33', # Only send if overriding default above\n page_title='Umami-Test', # Defaults to event_name if omitted.\n hostname='somedomain.com', # Only send if overriding default above.\n url='/users/actions',\n referrer='https://some_url')\n\n# Get website statistics for a date range\nfrom datetime import datetime, timedelta\n\nend_date = datetime.now()\nstart_date = end_date - timedelta(days=7) # Last 7 days\n\nstats = umami.website_stats(\n start_at=start_date,\n end_at=end_date,\n website_id='a7cd-5d1a-2b33' # Only send if overriding default above\n)\nprint(f\"Page views: {stats.pageviews}\")\nprint(f\"Unique visitors: {stats.visitors}\")\nprint(f\"Bounce rate: {stats.bounces}\")\n\n# Get current active users count\nactive_count = umami.active_users(\n website_id='a7cd-5d1a-2b33' # Only send if overriding default above\n)\nprint(f\"Currently active users: {active_count}\")\n\n# Check if Umami server is accessible\nserver_ok = umami.heartbeat()\nprint(f\"Umami server is {'accessible' if server_ok else 'not accessible'}\")\n\n# Call after logging in to make sure the auth token is still valid.\numami.verify_token()\n```\n\nThis code listing is very-very high fidelity psuedo code. If you want an actually executable example, see the [example client](./umami/example_client) in the repo.\n\n## Want to contribute?\n\nSee the [API documentation](https://umami.is/docs/api) for the remaining endpoints to be added. PRs are welcome. But please open an issue first to see if the proposed feature fits with the direction of this library.\n\nEnjoy.",
"bugtrack_url": null,
"license": null,
"summary": "Umami Analytics Client for Python",
"version": "0.2.22",
"project_urls": {
"Homepage": "https://github.com/mikeckennedy/umami-python",
"Source": "https://github.com/mikeckennedy/umami-python",
"Tracker": "https://github.com/mikeckennedy/umami-python/issues"
},
"split_keywords": [
"analytics",
" umami",
" website"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "27a64f9f5af5f9fbf27a3b910855d343a809a58f91a93d73cac4862cdcf506ed",
"md5": "64927dfd7fb961cf4fa8a7534239f355",
"sha256": "1800e50980bf2131bec7ce1c748ed73791cc2a61b73e725274cfb08be231a4e3"
},
"downloads": -1,
"filename": "umami_analytics_py-0.2.22-py3-none-any.whl",
"has_sig": false,
"md5_digest": "64927dfd7fb961cf4fa8a7534239f355",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 10923,
"upload_time": "2025-07-18T02:44:07",
"upload_time_iso_8601": "2025-07-18T02:44:07.912209Z",
"url": "https://files.pythonhosted.org/packages/27/a6/4f9f5af5f9fbf27a3b910855d343a809a58f91a93d73cac4862cdcf506ed/umami_analytics_py-0.2.22-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f90239d2718b6f17bf42d401189fd9d04ade883a6cbfee035d0ded427bb5de9a",
"md5": "c33c2cf27678a42bd3ce97773a04e34a",
"sha256": "dd143cb3710e93513b8f9f1f55fb5d25c9deeb81b8ea44c3223aeddf540d15d9"
},
"downloads": -1,
"filename": "umami_analytics_py-0.2.22.tar.gz",
"has_sig": false,
"md5_digest": "c33c2cf27678a42bd3ce97773a04e34a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 9900,
"upload_time": "2025-07-18T02:44:09",
"upload_time_iso_8601": "2025-07-18T02:44:09.209413Z",
"url": "https://files.pythonhosted.org/packages/f9/02/39d2718b6f17bf42d401189fd9d04ade883a6cbfee035d0ded427bb5de9a/umami_analytics_py-0.2.22.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-18 02:44:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mikeckennedy",
"github_project": "umami-python",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "umami-analytics-py"
}
