Theme
GitHub PyPI Discord
On this page

Citry 1.0.0 is stable

Citry 1.0.0 is out. What the stable release promises, what is still experimental, how to upgrade, and what comes next.

By Juro Oravec About 3 min read
  • Releases
  • Project updates

Citry 1.0.0 is out: the first stable release of the fully typed frontend framework for Python. Install or upgrade:

python -m pip install -U "citry>=1.0.0,<2"

Also at 1.0.0:

  • citry-lsp, the language server;
  • the VS Code extension;
  • pygments-citry, Citry syntax highlighting for Pygments.

What "stable" means

Upgrades within 1.x keep what the docs describe working:

  • Patch (1.0.1): bug fixes.
  • Minor (1.1.0): new features. Deprecated features keep working, with a warning, at least until 2.0.0.
  • Major (2.0.0): the only release that may remove or break what 1.x documents.

Exceptions: experimental features, and fixes that close a security hole. While you upgrade servers one at a time between two 1.x releases, an open page may need one reload.

The exact rules, including what counts as a breaking change and how to pin Citry: Versioning and support.

What 1.x covers

Covered: what the docs teach.

  • the public Python names;
  • the template syntax;
  • settings and extension hooks;
  • the citry command line;
  • the browser JavaScript API;
  • citry-events/1, the protocol server events use.

Full list: What the promise covers.

Experimental: may change in a minor release. These work and are tested, but their design is not settled.

  • component previews;
  • the template analysis API, behind citry check and the editor;
  • calling event handlers from your own server code with EventsDispatcher.

Full list: Experimental features.

Not covered: the UI library. citry-ui stays on 0.x as an alpha, so pin one minor release, such as "citry-ui>=0.6.0,<0.7".

Upgrade to 1.0.0

  1. Upgrade to 0.9.x and follow its upgrade notes.
  2. Install 1.0.0 (command at the top).

0.9.0 made the last large set of breaking changes. 1.0.0 adds a few more, all small, listed in the upgrade guide. The one most apps notice: the State token, the signed string that carries a component's State (the values its event handlers need between calls) to the page, now expires after 24 hours.

  • Who is affected: components that set no _max_age.
  • What happens: a call with an expired token does not run its handler, and calls from that component keep failing until the visitor reloads the page. In production Citry shows visitors nothing, so show your own message, as Handle out-of-date pages shows.
  • To change it: set a longer _max_age on the component.

Step by step: Upgrade to Citry 1.0.0. Every change: the changelog.

Which versions get fixes

  • 0.x: no more fixes.
  • 1.x: bug and security fixes go to the newest minor release, so stay current.
  • After 2.0.0: the last 1.x minor gets security fixes for 12 months.

What comes next

More 1.x minor releases. The Roadmap tracks what is planned. Tell me what you need most, there or on Discord.

Thank you

Thank you to everyone who tried Citry during the beta, filed issues, asked questions on Discord, and sent pull requests. Your bug reports shaped what 1.0.0 promises. And thank you to the sponsors who fund the work.

If you build something with Citry, I'd love to see it.