Skip to content

Latest commit

 

History

History
327 lines (240 loc) · 15.6 KB

change-log.md

File metadata and controls

327 lines (240 loc) · 15.6 KB

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

1.1.0 - 2026-11-06

Fixed

  • websites() / websites_async() returned only the first page of Umami's paged /api/websites listing, silently truncating the list for accounts with more websites than one page. They now follow the page parameter until the reported count is reached (or a page adds nothing new, so a server that ignores page cannot loop) and return the complete list. Single-page accounts still make one request.
  • Self-hosted sends (new_event(), new_page_view(), new_revenue_event() and async twins) sent the literal header Authorization: Bearer None when nobody had called login(). The header is now omitted unless a token is present; Umami's /api/send ignores it either way, so recorded data is unchanged.
  • login() / login_async() now reject whitespace-only usernames and passwords with ValidationError, matching set_url_base() and set_cloud_api_key(); before, they went to the server and came back as a 401. The empty-username message also now says Username cannot be empty instead of Email.

Documentation

  • New user guide on the docs site: Getting started, Sending events, Authentication, Querying stats, Troubleshooting, Testing and CI, Configuration, How it works, and FAQ. The guide pages are also appended to llms-full.txt.
  • The agent skill (skill.md, .well-known/agent-skills/umami-analytics/SKILL.md, .well-known/skills/default/SKILL.md) is now hand-written from umami/skills/umami-analytics/SKILL.md and teaches the rules of the package (setup order, self-hosted vs Cloud, what disable() silences, distinct_id, the bot filter, what each error means) instead of listing API names. The skill is renamed from umami to umami-analytics, so its .well-known path changed. umami/skill_extra_body.md is folded into it and removed.
  • Every public function, model, and exception now has an Example: section in its docstring, rendered on the reference pages and in llms-full.txt. The package docstring states that there is no CLI and no environment variables are read, and names the three exception types callers see.
  • Docstring Raises: sections for new_event(), new_revenue_event(), and their async twins now list a blank event_name as a ValidationError cause.
  • README: install shows uv add and pip install and warns about the unrelated umami package; the Documentation section links each guide page; the tracking-disabled bullets say exactly what still contacts the server and that the send functions return {}; the Cloud section says the two modes are exclusive; the "Login" feature bullet no longer implies username/password login works on Cloud.
  • scripts/build_docs.py now fails the build when llms.txt, llms-full.txt, skill.md, the .well-known skill copies, the user guide, sitemap.xml, robots.txt, or search.json are missing from the output, or when llms-full.txt lacks a guide page. The post-build patch of the generated skill's install command is removed; Great Docs fixed that in 0.16.0 and the skill is hand-written now. The great-docs dev dependency is floored at 0.17.0, the version the build was verified on, in both the [dev] extra and a new umami/requirements-dev.txt that mirrors it.

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.

Deprecated

Removed

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).

Security


0.6.25 - 2026-06-07

Added

  • distinct_id support in new_event, new_page_view, and new_revenue_event payloads (sync and async), sent to Umami as payload field id
  • Umami Cloud API-key authentication via set_cloud_api_key(key, region=None) and clear_cloud_api_key(). In Cloud mode, data/management calls route to https://api.umami.is/v1[/region] with an x-umami-api-key header, and events are sent to https://cloud.umami.is/api/send — no set_url_base() or login() required. Existing self-hosted (login() + token) usage is byte-for-byte unchanged. Added urls.me for Cloud key validation in verify_token/verify_token_async. In Cloud mode, heartbeat() / heartbeat_async() check liveness via the authenticated /me endpoint (Cloud has no /api/heartbeat), and login() / login_async() raise OperationNotAllowedError to fail fast (the API key is the credential — there is no username/password login on Cloud).

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.

Deprecated

Removed

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.

Security


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

Notes

  • Motivated by supply-chain/maintainer-governance concerns around httpx (stalled releases, locked-down issues/discussions). Confirm httpx2 is the intended, API-compatible fork before publishing this release.

0.4.23 - 2026-03-12

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

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

Removed

  • Unused base64 and json imports from umami/impl/__init__.py

[0.3.21] - 2025-12-12

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

[0.2.20] - 2025-05-30

Added

  • Development and testing tracking options to disable tracking for dev/test environments
  • When tracking is disabled: no HTTP requests are made, API calls still validate parameters, all other functions work normally, functions return appropriate values for compatibility
  • Documentation for heartbeat check feature and new methods (get_heartbeat, enable/disable)

Changed

  • Sorted imports in various files to improve code organization and readability
  • Fixed minor typo in documentation

[0.2.19] - 2025-05-30

Added

  • Asynchronous (heartbeat_async) and synchronous (heartbeat) versions of the heartbeat function for improved import flexibility
  • Website stats and active users functions (website_stats, active_users) - Thanks @orangethewell

Fixed

  • Login API data handling corrected from data to json parameter

Changed

  • Optimized heartbeat function execution flow for improved performance

[0.2.18] - 2025-05-30

Added

  • Python 3.13 and 3.14 support

Fixed

  • API call method fix: corrected the use of data instead of json in login API calls

[0.2.17] - 2024-04-18

Added

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

[0.2.15] - 2024-02-29

Added

  • Heartbeat function (from 0.1.14 release)

Fixed

  • Schema change compatibility from Umami 2.9 to 2.10 on websites response

[0.1.14] - 2024-02-29

Added

  • Heartbeat API endpoint

[0.1.13] - 2024-02-13

Added

  • IP address support in new_event and new_page_view payloads (and async variants)
  • Prepares for Umami IP data field feature (see umami-software/umami#2479)

[0.1.12] - 2024-01-27

Added

  • Ability to pass alternative user agent to events (note: Umami blocks what it perceives as bots)

[0.1.11] - 2024-01-24

Added

  • new_page_view() and new_page_view_async() methods

Changed

  • Dropped auth requirement for new event (not needed, see #1)

[0.1.10] - 2024-01-22

Added

  • Platform type (e.g. Windows) to user agent
  • Doc strings to most methods
  • Better validation for some functions
  • Custom error types for validation


Template for Future Entries