Versioning¶
PyFly uses Calendar Versioning (CalVer) to stay aligned with the rest of the Firefly Framework family (Java, .NET, Go) which all adopted CalVer in May 2026.
Version Format¶
All PyFly versions follow the YY.MM.PATCH scheme:
| Component | Meaning | Example |
|---|---|---|
YY |
Two-digit year | 26 (2026) |
MM |
Two-digit month of the release | 05 (May) |
PATCH |
Patch number within the month | 01, 02, 03, … |
Examples: 26.05.01, 26.05.02, 26.06.01, 27.01.01.
A new patch within the same month bumps PATCH (26.05.01 → 26.05.02). The
first release of the next month resets PATCH to 01 and advances MM
(26.05.02 → 26.06.01). January of a new year advances YY
(26.12.04 → 27.01.01).
Two notations¶
Because PEP 440 normalises numeric components by stripping leading zeros, PyFly carries the version in two notations that always reference the same release:
| Surface | Notation | Example |
|---|---|---|
Git tag, GitHub release, README badge, banner, __version__ |
leading-zero (matches Java/.NET/Go siblings) | v26.05.01 / 26.05.01 |
pyproject.toml, wheel filename, Python tooling (uv, pip, hatchling) |
PEP 440 normalised | 26.5.1 / pyfly-26.5.1-py3-none-any.whl |
Both forms are interchangeable when filling in URLs and dependency specifiers — the normalised form lands on the wheel filename, the leading-zero form lands on the tag. Tools that accept PEP 440 specifiers treat them identically.
Pre-release suffixes (optional)¶
If a release is published before all month-end testing has finished, PyFly appends a PEP 440 pre-release suffix to the package version:
| Stage | Tag | Package version |
|---|---|---|
| Alpha | v26.05.01-alpha.1 |
26.5.1a1 |
| Beta | v26.05.01-beta.1 |
26.5.1b1 |
| Release Candidate | v26.05.01-rc.1 |
26.5.1rc1 |
| Final | v26.05.01 |
26.5.1 |
Most months ship a single final release; the pre-release stages exist for the rare case where a substantial change needs an additional review window.
Release history¶
| Version | Date | Notes |
|---|---|---|
26.10.11 |
2026-10-24 | Preserve supported dependency floors, use lockfile-only project updates and refresh book tooling and both editions. |
26.10.10 |
2026-10-24 | Monty 0.0.23 worker-backed execution, preserved Code Mode API and updated EN/ES tutorials. |
26.10.09 |
2026-10-24 | Native regex redaction replaces Presidio; dependency hotfix and smaller admin branding. |
26.10.08 |
2026-10-24 | Native optional Agentic module, application-owned runtime and matching EN/ES book chapters; namespace migration required. |
26.10.07 |
2026-10-21 | Security header defaults preserve explicit application policies without duplicating headers in either public adapter. |
26.10.06 |
2026-10-14 | OpenTelemetry resource environment variables identify newly created trace and metric providers; explicit PyFly service-name overrides retain precedence. |
26.10.05 |
2026-10-14 | Refreshed dependencies, pinned Python setup workflows, and synchronized release metadata and book downloads. |
26.10.04 |
2026-10-14 | Revised OAuth references and EN/ES books included in the software release; synchronized release metadata. |
26.10.03 |
2026-10-14 | HTTP authorization-code/PKCE redemption and interoperable OAuth Basic credentials. |
26.10.02 |
2026-10-13 | Bounded token refresh and explicit code-exchange authentication/resource indicators. |
26.10.01 |
2026-10-06 | Feature flags on OpenFeature and flagd, with a shared PyFly/LaraFly contract. |
26.09.15 |
2026-09-30 | Public JWKS fetch seam and caller budgets; bounded OAuth2 client credentials. |
26.09.14 |
2026-09-30 | Opt-in S256 PKCE for device authorization and token polling. |
26.09.13 |
2026-09-30 | Deterministic OpenAPI references for constrained named aliases across processes. |
26.09.12 |
2026-09-30 | Offline OpenAPI contracts, rich schema inference and explicit operation overrides. |
26.09.11 |
2026-09-30 | Scheduled-method discovery avoids evaluating Pydantic and custom descriptors. |
26.09.10 |
2026-09-29 | Bounded identity and HTTP primitives, lifecycle ownership, substitutable observability and exact-byte webhooks. |
26.09.09 |
2026-09-28 | A restarted context drops the previous run's interface bindings with its registrations, so a second start() of the same context no longer fails with a KeyError (a test suite whose modules share an application). |
26.09.08 |
2026-09-28 | The data layer on a unit of work: Spring @transactional semantics on every backend, one DataSourceRegistry for every engine, repositories that commit per call outside a transaction, the framework stores in the business transaction, MongoDB transactions, and a backend matrix (SQLite, PostgreSQL, MySQL, MariaDB, MongoDB replica set). Several breaking changes: see the changelog. |
26.09.07 |
2026-09-24 | Identifiers survive PII redaction and PHONE means a phone number; the Postgres outbox DDL runs only when the tables are missing; the CQRS cache bridge subscribes one handler per rule instead of the wildcard. |
26.09.06 |
2026-09-24 | Deferred user @bean factories, Kafka partition keys and dead-letter topics, cross-runtime event envelopes, ManagementRoutesContributor and @write_operation, mounted routes in /openapi.json, a real MeterProvider, and a transient AsyncSession. |
26.09.05 |
2026-09-23 | Native webapps, branded welcome/errors, existing-model administration, and bilingual book appendices. |
26.05.01 |
2026-05-07 | CalVer migration. Full Java framework parity: rewritten transactional engine (Saga + Workflow + TCC), nine new modules (eventsourcing, callbacks, webhooks, notifications, IDP, ECM, plugins, rule engine, config server), 12 new third-party adapters, four new client protocols (SOAP/gRPC/GraphQL/WebSocket), 16 domain validators. |
0.3.0-M1 |
2026-05-07 | (Superseded by 26.05.01.) Initial v0.3.0 milestone — same payload as 26.05.01 under the previous SemVer scheme. |
0.2.0-M11 |
2026-03-01 | Thread-safety, correctness, and robustness audit: 18 fixes across DI, web, resilience, security, data. |
0.2.0-M10 |
2026-02-28 | uv-first tooling: PEP 735 dependency-groups, uv-native CI/templates/installer, tool-neutral error messages. |
0.2.0-M9 |
2026-02-20 | Method security, @transactional, K8s probes, Pydantic config, soft delete/versioning. |
0.2.0-M8 |
2026-02-20 | HttpSecurity DSL, OAuth2 login flow, data auditing, @query for MongoDB, SSE. |
0.2.0-M7 |
2026-02-19 | Comprehensive audit: WebSocket, OAuth2, session, i18n, XML, bug fixes. |
0.2.0-M6 |
2026-02-19 | ASGI pathsend extension fix for Granian. |
0.2.0-M5 |
2026-02-19 | Auto-configuration audit (8 new auto-config classes), stdlib logging fallback, post-processor deduplication. |
0.2.0-M4 |
2026-02-18 | Admin dashboard overhaul, pure ASGI middleware (anyio fix), built-in metrics, bean categories, mapping/trace/logger enhancements. |
0.2.0-M3 |
2026-02-18 | Clean server startup, graceful shutdown, admin dashboard enhancements, mypy strict compliance. |
0.2.0-M2 |
2026-02-18 | Application server architecture, FastAPI adapter, Granian/Hypercorn support. |
The 0.x → CalVer migration was a one-time renumbering that does not
change the package contents — 26.05.01 ships exactly what 0.3.0-M1
shipped, with the version metadata updated.
Reading the version at runtime¶
The CLI reads the installed distribution metadata and reports the normalized package version:
The startup banner displays the leading-zero form:
Why CalVer?¶
The Firefly Framework family (Java, .NET, Go, Python) ships from a single multi-repo release cadence — every port snaps to the same monthly version so operators running heterogeneous services can identify "which Firefly month" each one is on at a glance. SemVer's "is this a breaking change?" semantics remain valuable inside individual modules but at the framework level the month-based promise (regular releases, predictable cadence) is the more useful contract.