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:
| Package | Versions | Which releases get fixes |
|---|---|---|
citry-lsp (editor support) | 1.x | The newest release |
| VS Code extension | 1.x | The newest release |
pygments-citry (syntax highlighting) | 1.x | The newest release |
citry-core | Its own numbers | The version a supported citry release installs |
citry-ui | 0.x, alpha | The 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 everycitry1.x, so you can upgrade either one first.- VS Code extension: it runs the
citry-lspinstalled in your project and does not install it. Extension 1.x acceptscitry-lsp0.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 onecitry-lsprelease (extension 1.0.0 withcitry-lsp1.0.0). No other pairing is promised, so keep both on their newest release. pygments-citry: thecitryandcitry-htmllexer 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 checkand the editor. - A rule that projects may reasonably disagree about gets a
rule_*setting onLintSettings, so you can make it a warning (which never failscitry 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 answersprotocol_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.registerTransportkeeps working across 1.x. - A change that
citry-events/1cannot carry arrives ascitry-events/2, added beside it in a 1.x release. - Running calls from your own server code with
EventsDispatcherandTransportContextis 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_ageto a longertimedelta. 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 eachcitry.ext.<name>package and eachcitry.contrib.<name>module; - the names in
citry.reload.
- every name in
- 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,StateandLint. - 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 namescitryexports, such asNode,ComponentNodeandIfNode, and the attributes extensions read. - Command line: the
citrycommands and options, the JSON fromcitry check --format json, and rule names such ascitry.template.unknown-component. - VS Code extension: its settings and commands, such as
citry.appand 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.Citryand its documented members;$component(...)in component JavaScript;- the
onServerRendercallback; - the Events helpers such as
$stateand$sendEvent, and$i18n; - the
citry:events:*DOM events andcitry: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>orcitry.contrib.<name>, not from modules such ascitry.ext.events.handlersorcitry.nodes. - Browser internals: globals, attributes and members no docs page teaches, such as
window.__citryRuntime, thedata-citry-*attributes in rendered HTML, and component members starting with$citry. citry-core's own API: onlycitryis 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 asComponentGraphNode, andCitry.inspect_component_graph()- the template analysis API behind
citry check,citry formatand the editor:Citry.template_analysis(),TemplateAnalysis,TemplateLintInfo,TemplateVariableInfo,TemplateLintConsumer,TemplateLintFinding,ComponentSourceLint,lint_unknown_template_variables();- names containing
PythonTemplate,python_templates,PythonComponentAssetorpython_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
ForeignorOnTemplateForeign; CompiledBody,render_compiled_body(),collect_compiled_body_fills()
- component previews (
citry.ext.preview) - the
"payload"render cache mode, withExtension.export_render_cache()andExtension.stage_render_cache() Extension.browser_plugin()andExtension.prepare_browser_render()- the Events extension hooks
on_event,on_event_result,on_event_error EventsDispatcherandTransportContext(running event calls from server code instead of Citry's HTTP routes)- the
event_result_resolversandevent_payload_codecssettings RenderFrameandCitryRender.frame