Changelog

This changelog is generated automatically from GitHub Releases.

v1.0.0

2026-06-11 · GitHub

[1.0.0]

First stable release. The package is now marked Development Status :: 5 - Production/Stable (it has been used in production at Talk Python Training for some time) and follows SemVer from here forward.

Changed

  • Promoted the trove classifier from 4 - Beta to 5 - Production/Stable, and added the Typing :: Typed classifier to advertise the bundled py.typed marker.
  • Expanded the PyPI keyword set (added web-analytics, privacy, tracking, metrics, events, page-views, telemetry, statistics, self-hosted, async, httpx, pydantic, sdk, api-client) for better discoverability.

Added

  • pydantic.Field(description=...) metadata on every response-model field, plus a griffe-pydantic dev dependency, enriching the response models for IDEs, JSON schema, and future API-reference rendering. Note: the current Great Docs version (0.13.0) does not load griffe extensions, so the rendered field docs still come from the docstring Attributes: sections; the Field descriptions will surface on the docs site once the generator loads the extension.

Changed

  • Synchronous send functions now return the Umami API’s JSON response as a dict (and {} when tracking is disabled), matching their async twins. Previously new_event(), new_revenue_event(), and new_page_view() returned None; new_page_view_async() also now returns the response dict instead of None.
  • Missing or blank required event fields (hostname, website_id, event_name) now raise umami.errors.ValidationError instead of a bare Exception, so they can be caught alongside the SDK’s other validation errors.
  • Website.shareId, Website.resetAt, and Website.deletedAt are now optional (default None), so a websites response that omits those keys no longer raises pydantic.ValidationError.
  • README now points to the new documentation site at https://mkennedy.codes/docs/umami-python/ (added status badges, a documentation pointer near the top, and a “Documentation” section linking the full API reference). Docs-only change — no code or packaging changes.
  • Docstrings across the public API were expanded and corrected for the generated documentation site (Great Docs renders them verbatim, and they feed llms.txt). Added Raises: sections to every raising function; fixed website_stats() / website_stats_async() to document their real return type (models.WebsiteStats, not the nonexistent WebsiteStatsResponse); removed unprofessional/inaccurate prose from verify_token (the “minutes, hours, or years” hedge) and new_event (the “not sure how this is different” aside); corrected new_page_view wording (visitor; the ua user-agent string); clarified that disable() still validates before skipping the HTTP request and that both affect only the send functions; documented all response models and exception classes; added a package module docstring; and added runnable usage examples. Docstring-only — no code or behavior changes.

Fixed

  • validate_event_data no longer lets a whitespace-only event_name through (the check used and, so whitespace bypassed it; it now uses or).

v0.6.25

2026-06-07 · GitHub

[0.6.25] - 2026-06-07

Added

Changed

  • validate_state error messages now mention set_cloud_api_key() alongside set_url_base() / login(). Same exception type (OperationNotAllowedError) and trigger conditions; text only.
  • Response models are more tolerant of variant/partial responses: WebsiteStats.comparison and Website.user are now optional, and Website accepts createUser (returned by team-website listings, where userId is null). Successful responses today are unaffected.
  • Internal: expanded the unit test suite (now 128 tests) following a suite review — added behavioral coverage for set_url_base validation, the validate_state guards, the login/login_async happy path and response-model deserialization (LoginResponse, WebsitesResponse), websites/websites_async, the disable() no-op (asserting no HTTP request is made), ip_address payload inclusion/omission, explicit-arg-overrides-defaults precedence, heartbeat_async self-hosted, and the verify_token/heartbeat failure branches. Added a sync/async parity harness and consolidated the per-file HTTP mock builders into a shared tests/_mocks.py (net ~210 fewer lines). No production behavior changed.

Fixed

  • website_stats_async() sent its date range as snake_case start_at/end_at query params, which the Umami API ignores — it silently returned all-time stats regardless of the requested window. Now sends camelCase startAt/endAt, matching the sync website_stats(). (#18)
  • active_users() and active_users_async() read the active-visitor count from a non-existent x key, so they always returned 0. They now read Umami’s current visitors key (falling back to the legacy x key for compatibility). (#19)
  • website_stats() / website_stats_async() sent their url and host filters under the old query-param names, which Umami renamed on 2025-10-07 (url → path, host → hostname) — so filtering stats by URL or hostname was a silent no-op. The public url/host keyword arguments are unchanged; they now map to the current path/hostname wire names. (#20)
  • heartbeat() / heartbeat_async() issued a POST to /api/heartbeat, which current Umami answers with 405 Method Not Allowed; the broad exception handler swallowed the error so the call always returned False even against a healthy server. They now issue a GET (the endpoint returns {"ok": true}).
  • new_event() and new_revenue_event() (sync) defaulted url to '/event-api-endpoint' while their async twins used '/'. All four now default to '/', so the sync/async twins agree and no placeholder path appears in dashboards.

v0.5.24

2026-06-04 · GitHub

[0.5.24] - 2026-06-04

Changed

  • Migrated HTTP backend from httpx to httpx2, imported as import httpx2 as httpx so all call sites remain unchanged
  • Files: umami/umami/impl/__init__.py, umami/requirements.txt, umami/pyproject.toml, pyrefly.toml, README.md, umami/README.md

v0.4.23

2026-03-13 · GitHub

[0.4.23]

Added

  • new_revenue_event() and new_revenue_event_async() for tracking revenue with Umami’s new revenue feature
  • Revenue events automatically inject revenue (float) and currency (ISO 4217 string) into event custom data
  • Input validation: revenue must be a number >= 0, currency must be a non-empty string
  • Defaults to event_name='revenue' and currency='USD' for simple usage
  • 15 new tests covering sync/async revenue events, validation, and edge cases

v0.3.22

2026-02-03 · GitHub

[0.3.22] - 2026-02-02

Fixed

  • new_event_async crashed with binascii.Error due to erroneous base64.b64decode / json.loads calls on the plain-JSON API response; now returns resp.json() directly, matching the other event and page-view methods

v0.3.21

2025-12-12 · GitHub

Added

  • Change-log preservation section for tracking historical release details
  • Pyrefly configuration file treating umami/umami package as type-resolution root

Changed

  • Centralized all version information into a single location for easier maintenance
  • Updated Python requirement to 3.10+ (dropped support for Python 3.8 and 3.9)
  • Refactored WebsiteStats to use plain integers instead of custom Metric type - Thanks @rubitcat (#15)
  • Updated ruff.toml to enforce consistent import ordering

Fixed

  • Suppressed and cleaned up unnecessary type-checking warnings

v0.2.20

2025-05-31 · GitHub

Umami-Python Release Notes

Since 5fa35183 (7 commits)

🚀 New Features

  • Development and Testing Tracking: Added options to disable tracking for development and testing environments. This allows users to control data collection based on their needs.

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

📚 Documentation

  • Documented the heartbeat check feature for monitoring system health.
  • Added documentation for new methods in the Umami API: get_heartbeat and enabled/disable.

🧹 Maintenance

  • Sorted some imports in various files to improve code organization and readability.
  • Fixed a minor typo in the documentation, ensuring consistency across the project.

v0.2.19

2025-05-31 · GitHub

Umami-Python Release Notes

Since 1d17c014 (16 commits)

🚀 New Features

🐛 Bug Fixes

  • Login Fix: Corrected the API data handling from data to json in the login process. Originally, this was not a problem with the server, but it has started failing. If you have encountered login errors, this may fix it.

⚡ Performance

  • Heartbeat Function Optimization: Improved the performance of the heartbeat function by optimizing its execution flow.

v0.2.18

2025-05-31 · GitHub

Umami-Python Release Notes

Since 3a08f77a (2 commits)

🚀 New Features

  • Python Version Update: Upgraded to Python 3.13 and 3.14, providing better support for modern applications.

🐛 Bug Fixes

  • API Call Method Fix: Corrected the use of data instead of json in login API calls, ensuring proper data transmission.

Originally, this was not a problem with the server, but it has started failing. If you have encountered login errors, this may fix it.

v0.2.17

2024-04-19 · GitHub

Adds is_logged_in() -> bool method to check whether login has been called and was successful.

v0.2.15

2024-03-01 · GitHub

  • Fixes schema change from Umami 2.9 to 2.10 on websites response
  • Includes new heartbeat function from 0.1.14 release

v0.1.14

2024-03-01 · GitHub

Add heartbeat API endpoint.

v0.1.13

2024-02-13 · GitHub

Support IP address in new_event and new_page_view payloads, see issue #2.

It looks like Umami added the IP data field in the payload (see https://github.com/umami-software/umami/pull/2479 ). It’s not clear when the feature will be released in a new build ( https://github.com/umami-software/umami/releases ). But in preparation, I added the id_address parameter to both new_event and new_page_view as well as their async twins.

This is out in version 0.1.13 and on PyPI at https://pypi.org/project/umami-analytics/0.1.13/ Thanks for the idea @ddxv

v0.1.12

2024-01-27 · GitHub

Add ability to pass alternative user agent to events (but be careful, umami blocks what it perceives as bots).

v0.1.11

2024-01-24 · GitHub

v0.1.10

2024-01-22 · GitHub

  • Added platform type (e.g. Windows) to user agent.
  • Added doc strings to most methods.
  • Bump the version for next release.
  • Added better validation for some functions.
  • Added custom error types for validation.

v0.1.9

2024-01-21 · GitHub

First real release outside our own apps. Enjoy!