Theme
Version
GitHub PyPI Discord
On this page

v1.0.0

Citry 1.0.0 is the first stable release. Code that uses what the docs describe keeps working in every 1.x release, apart from experimental features and security fixes, so you can allow any 1.x with citry>=1.0.0,<2. Versioning and support says what this covers, what is experimental, which versions get fixes, and how deprecations work.

The upgrade from 0.9.x is small. Most apps notice two changes: the signed State token that Citry sends to the page now expires after 24 hours, and in production Citry no longer asks visitors to reload an out-of-date page, so add your own message for them.

If you use citry-lsp or the VS Code extension, upgrade them to 1.0.0 together with Citry, because an older extension refuses citry-lsp 1.x. After that, any citry-lsp 1.x works with any Citry 1.x, so you can upgrade either one first. citry-ui 0.6.0 is released alongside and needs Citry 1.0.0 or later.

Upgrading from 0.9.x

If you are on a release older than 0.9.x, upgrade to 0.9.x before you start. Upgrade to Citry 1.0.0 lists the steps in order.

  • State sent to the page now expires after 24 hours by default: Citry sends each component's State to the page as a signed string, the State token. The token of a component whose State sets no _max_age used to work until you changed the signing secret. Now it stops working 24 hours after Citry issues it, as server-stored State already did. Citry issues a new token when it renders the component and after a call that changes State, so the pages affected are those whose State has not changed for more than 24 hours. A call with an expired token does not run its handler: it gets a stale_state error (see the next entry). Tokens issued before the upgrade also expire 24 hours after Citry issued them. No setting turns expiry off; to keep a token working for longer, set a longer _max_age:

    from datetime import timedelta
    
    class State:
        _max_age = timedelta(days=7)
    
  • Citry no longer asks visitors to reload an out-of-date page in production: when a call fails with stale_state, most often because the page's State token expired, a visitor whose call failed got a confirm dialog asking whether to reload, once per page. Now only a page that Citry(mode="development") rendered asks. In production Citry asks nothing, never reloads by itself, and writes one console warning per page, so calls from that component keep failing until the visitor reloads the page. Show your own message from a listener, as Handle out-of-date pages shows:

    document.addEventListener("citry:events:stale", (event) => {
      if (event.detail.reason !== "version") return;
      event.preventDefault();
      showReloadBanner();
    });
    document.addEventListener("citry:fragments:stale", (event) => {
      event.preventDefault();
      showReloadBanner();
    });
    
  • State._max_age must be at least one second: a shorter value, including timedelta(0), made every token expire as soon as Citry issued it, and now raises ValueError when the class is defined.

  • A c-bind key may not use an attribute name Citry reserves: on an HTML element, a key such as c-render-id, data-cid-x, data-ccss-x, or data-citry-key now raises ValueError, in any letter case. Citry uses these names to find its own elements and placeholders in the page, so a name taken from request data could make the server copy another component's HTML into the page. <c-element> with c-is or c-bind refuses them even when you write them in the template. Rename such an attribute to a data- name of your own; the full list is under Names Citry reserves.

Fixes

  • When the installed citry-lsp does not match your citry release, citry check --types now names the citry-lsp versions to install, rather than always asking you to upgrade it.
  • With security_javascript="omit", Citry now drops a Script or Style dependency whose URL is a javascript: URL written as Markup with a character reference, such as Style(url=Markup("java&#115;cript:x")), and removes such a URL from a dependency's attributes, as it already did for a plain string. Before, Citry reported it but left it on the page.
  • Server-stored State works on PyPy: a component whose State sets _storage = "server" no longer fails to render on PyPy when the cache is an InMemoryCache, including the default cache. The error was a TypeError from sys.getsizeof. CPython is unchanged.
  • Pydantic classes work with Events on PyPy: with Pydantic 2.13.0 or newer installed, Events now accepts Pydantic State and event data classes on PyPy. Before, it refused every one of them with "Events needs Pydantic 2.13.0 or newer".
  • Lookalike javascript: letters are no longer reported: security_csp, security_javascript and citry check no longer report a link that spells javascript: with ſ, ı or İ, such as href="java&#383;cript:x". Browsers read such a link as a relative URL and run nothing.

Added

  • You can now find out when the page gets a Vue fragment from another Citry release: the page fires the new citry:fragments:stale event and does not start the fragment. Before, the fragment failed with only a console error.

Changed

  • If a later Citry release changes the State token format, a page from the other release gets stale_state (409) during a deploy, and Citry fires citry:events:stale. Before, it got invalid_state (403) and an error.
  • During a later deploy, a page that Citry 1.0.0 rendered now fails an event call with stale_state, as an expired State token does, when the response comes from another release and the page's browser code cannot read it. Before, the call failed with a plain error.
Citry version: 1.0.0