Theme
Version
GitHub PyPI Discord
On this page

Versioning and support

What each Citry release may change in your project, which versions get fixes, and how to pin Citry.

Pin and upgrade

Citry follows semantic versioning. Allow any 1.x release:

# pyproject.toml
[project]
dependencies = [
    "citry>=1.0.0,<2",
]

What each kind of release does:

  • Patch (1.0.0 to 1.0.1): bug fixes. Code that uses covered parts needs no changes, except for a security fix that refuses input your code relied on. An open page's next event call may fail with the error code stale_state, which means the page is out of date (see Rolling deploys).
  • Minor (1.0.0 to 1.1.0): new features. Code that uses covered parts keeps working. A minor release may also:
    • deprecate a feature (it warns but still works, see Deprecations);
    • change an experimental feature;
    • add a check rule;
    • drop an end-of-life Python version, raise the oldest supported Django, FastAPI or Flask version, or move to a newer Vue minor version (see Python and browsers);
    • change the State token format, so an open page's next event call fails with stale_state (see Rolling deploys).
  • Major (1.x to 2.0.0): may remove deprecated features and make other breaking changes. The release notes say what to change.

Depend on citry, not citry-core. Each citry release installs the one citry-core version it needs.

Supported versions

  • Bug and security fixes go to the newest 1.x minor release only. Once 1.2.0 is out, a fix ships as 1.2.1, not as a 1.1.x release.
  • With citry>=1.0.0,<2, upgrading gives you the newest 1.x release, the one that gets fixes.
  • After 2.0.0 comes out, the last 1.x minor release gets security fixes only, for 12 months.
  • 0.x releases get no fixes.

Other packages:

PackageVersionsWhich releases get fixes
citry-lsp (editor support)1.xThe newest release
VS Code extension1.xThe newest release
pygments-citry (syntax highlighting)1.xThe newest release
citry-coreIts own numbersThe version a supported citry release installs
citry-ui0.x, alphaThe newest release
  • citry-ui: not covered by the 1.x rules, so a minor release may break your code. Pin one minor release, for example "citry-ui>=0.6.0,<0.7".
  • citry-lsp: every 1.x works with every citry 1.x, so you can upgrade either one first.
  • VS Code extension: it runs the citry-lsp installed in your project and does not install it. Extension 1.x accepts citry-lsp 0.1.x to 0.4.x and any 1.x, and for another version it shows "Citry unavailable" with the versions it accepts. Each extension release is tested with one citry-lsp release (extension 1.0.0 with citry-lsp 1.0.0). No other pairing is promised, so keep both on their newest release.
  • pygments-citry: the citry and citry-html lexer names keep working in every 1.x release.

Python and browsers

The Compatibility page lists the exact Python versions, operating systems and wheels. How that list changes:

  • CPython: every version still maintained upstream. A minor release may add a new version, and may drop one after its end of life (the release notes say so).
  • PyPy and free-threaded CPython: best effort. Tested weekly, not on every change. The Compatibility page lists the known differences.
  • Django, FastAPI and Flask: a minor release may raise the oldest supported version, for example after Django ends support for it. A patch release never does, and the release notes name every change.
  • Browsers: the latest two versions of Chrome, Edge, Firefox and Safari, tested in Chromium, Firefox and WebKit.
  • Vue: Citry ships one exact Vue version. A minor release may move to a newer Vue minor version; a new Vue major version needs a new Citry major version.

Deprecations

A deprecated feature keeps working for the rest of 1.x and is removed no earlier than 2.0.0. Each use issues a CitryDeprecationWarning that names the line in your code and what to use instead.

CitryDeprecationWarning is a DeprecationWarning, which Python hides unless the line is in the script you ran directly. In a web server you usually will not see it. To find every use, make it an error in your tests:

# pyproject.toml
[tool.pytest.ini_options]
filterwarnings = [
    "error::citry.CitryDeprecationWarning",
]

To see it in a running server, add this to your startup code:

import warnings

from citry import CitryDeprecationWarning

warnings.simplefilter("default", CitryDeprecationWarning)

New check rules

A minor release may add a citry check rule, so a CI job that passed before can fail without a code change.

  • The release notes list each new rule.
  • A new rule never stops a template that renders today from rendering. It only reports in citry check and the editor.
  • A rule that projects may reasonably disagree about gets a rule_* setting on LintSettings, so you can make it a warning (which never fails citry check) or turn it off (see Change rule severity).

Some rules have no setting. The Diagnostics page marks each rule you can change with "Your application can change this severity".

Rolling deploys

During a deploy that upgrades one server at a time, a page from an old server talks to a new server, and the other way round. Citry supports this between any two 1.x releases, not across 1.x and 2.x. What can happen:

  • Event calls:
    • old page to new server: accepted;
    • new page to old server: accepted, unless the new release added citry-events/2; then the old server answers protocol_mismatch.
  • Data an old page cannot read: a State token (the signed copy of a component's State in the page), a render or a fragment written by another release. The page's next event call fails with the error code stale_state, or the fragment does not start. Citry fires events your app can use to tell the visitor (see Handle out-of-date pages). After a reload the page works with the new release.
  • Render cache: every upgrade, patch releases too, ignores entries that another Citry version wrote. While old and new servers share one cache, expect slower renders until the deploy finishes.
  • Browser runtime: an old page loads the old runtime file. Clear whole-page caches and give every server one shared cache (see Deploy a Citry upgrade).

Events protocol

Server events exchange data in the citry-events/1 protocol.

  • No 1.x release changes or removes it, apart from the security exception.
  • A custom transport registered with Citry.events.registerTransport keeps working across 1.x.
  • A change that citry-events/1 cannot carry arrives as citry-events/2, added beside it in a 1.x release.
  • Running calls from your own server code with EventsDispatcher and TransportContext is experimental.

State token lifetime

Unless you keep State on the server (State._storage = "server"), Citry sends each component's State to the page as a signed State token.

  • Signed tokens and State kept on the server both expire 24 hours after Citry issues them, unless you set State._max_age.
  • An expired token fails the call with stale_state. Show visitors a message for it, as Handle out-of-date pages shows.
  • For a longer lifetime, set State._max_age to a longer timedelta. Treat State as input explains why tokens expire.

What the promise covers

A covered part keeps working, as the docs describe it, in every 1.x release. Covered, unless marked experimental:

  • Python names:
    • every name in citry.__all__;
    • the __all__ of each citry.ext.<name> package and each citry.contrib.<name> module;
    • the names in citry.reload.
  • Options that start with _ (the _ keeps them from clashing with your handler and field names), when the docs or the API reference tell you to set them:
    • class Events: _guard, _context, _csrf, _methods, _debounce, _throttle;
    • class State: _public, _model, _storage, _max_bytes, _max_age;
    • set in extensions_defaults["events"] (app-wide): _max_body_bytes, _max_form_fields, _csrf_field_names, _csp_nonce.
  • Components and templates: the template syntax, component class attributes, and nested classes such as Kwargs, Slots, State and Lint.
  • Settings and extension hooks: every setting and every documented hook.
  • Node classes: the node objects Citry builds from a template, which extension hooks read as ctx.nodes (see Walk deep node lists): the class names citry exports, such as Node, ComponentNode and IfNode, and the attributes extensions read.
  • Command line: the citry commands and options, the JSON from citry check --format json, and rule names such as citry.template.unknown-component.
  • VS Code extension: its settings and commands, such as citry.app and Citry: Restart Language Server (listed on the VS Code page).
  • Browser JavaScript API: what the docs teach, with the meaning they give, mostly on the Browser APIs page:
    • window.Citry and its documented members;
    • $component(...) in component JavaScript;
    • the onServerRender callback;
    • the Events helpers such as $state and $sendEvent, and $i18n;
    • the citry:events:* DOM events and citry:fragments:stale.
  • HTTP routes under Citry's prefix, such as the event routes and the runtime script addresses: paths, methods and meaning, so your forwarding or proxy rules keep working. Preview server routes are experimental.
  • Server events: the Events protocol.

Security fixes

The one exception for every covered part: a 1.x release may refuse input it used to accept, such as an Events call or a template value, when that is needed to close a security hole. The changelog says so.

What is not covered

These may change in any release, even a patch release. If you rely on one, pin the exact Citry version and read the release notes before each upgrade.

  • Node constructor arguments: Citry creates nodes itself.
  • Data in browser-only routes: what the routes that only Citry's own browser code calls carry, such as event definition scripts and translated messages. Their paths and methods are covered.
  • Other _ names: any module, function, attribute or option that starts with _, except the options above.
  • Deeper modules: import from citry, citry.reload, citry.ext.<name> or citry.contrib.<name>, not from modules such as citry.ext.events.handlers or citry.nodes.
  • Browser internals: globals, attributes and members no docs page teaches, such as window.__citryRuntime, the data-citry-* attributes in rendered HTML, and component members starting with $citry.
  • citry-core's own API: only citry is meant to call it.
  • Generated output: the Python code the template compiler writes, the exact whitespace of rendered HTML, and error message text. Test what a page shows, and match errors by class, not message.

Experimental features

Experimental features work and are tested, but their design is not settled. They may change in a minor release; the release notes say so. Each has an Experimental box on its API reference page, and a guide says so where it teaches one.

The release notes say when this list changes. Experimental now:

  • ComponentGraph, its helper types such as ComponentGraphNode, and Citry.inspect_component_graph()
  • the template analysis API behind citry check, citry format and the editor:
    • Citry.template_analysis(), TemplateAnalysis, TemplateLintInfo, TemplateVariableInfo, TemplateLintConsumer, TemplateLintFinding, ComponentSourceLint, lint_unknown_template_variables();
    • names containing PythonTemplate, python_templates, PythonComponentAsset or python_component_assets
  • hooks that let another template engine, such as Django templates, embed Citry tags:
    • Extension.on_template_foreign_spans(), Extension.on_template_foreign_compiled();
    • classes starting with Foreign or OnTemplateForeign;
    • CompiledBody, render_compiled_body(), collect_compiled_body_fills()
  • component previews (citry.ext.preview)
  • the "payload" render cache mode, with Extension.export_render_cache() and Extension.stage_render_cache()
  • Extension.browser_plugin() and Extension.prepare_browser_render()
  • the Events extension hooks on_event, on_event_result, on_event_error
  • EventsDispatcher and TransportContext (running event calls from server code instead of Citry's HTTP routes)
  • the event_result_resolvers and event_payload_codecs settings
  • RenderFrame and CitryRender.frame