Upgrade to Citry 1.0.0
How to move a project to Citry 1.0.0, the first stable release. Citry 0.9.0 made the last large set of breaking changes, so most projects need no code changes. The one change most projects notice: State tokens (the signed strings that carry a component's State to the page) expire after 24 hours.
Upgrade steps
- Upgrade to the newest 0.9.x and follow its upgrade notes.
- Make
CitryDeprecationWarning(Citry's warning for a feature that is going away) an error in your tests. - Upgrade the packages and pin
citry>=1.0.0,<2. - Set a longer
State._max_agewhere a page must work after 24 hours or sits in a whole-page cache for longer than that. Keep every_max_ageat one second or more. - Add a listener for out-of-date pages, so visitors see a message when a call fails with
stale_state. - Find
c-bindand Citry UIattrs=dicts whose keys use a reserved name, and rename those keys. - Run your tests on 1.0.0.
- Deploy with fresh whole-page caches.
- Check whether your code uses an experimental feature, and read the other changes.
Skip steps 4 and 5 if no component uses server events.
Upgrade to 0.9.x first
Move to the newest 0.9.x. Already on 0.9.x: do only step 2 of this list. On an older release:
- Follow the "Upgrading from" notes of each release you skip, oldest first, in the release notes. From 0.8.x: Upgrading from 0.8.x.
- Run your tests and your app on 0.9.x, and fix what fails.
One release line at a time keeps each failure next to the notes that explain it.
Fix deprecation warnings
Make CitryDeprecationWarning an error in your tests:
# pyproject.toml
[tool.pytest.ini_options]
filterwarnings = [
"error::citry.CitryDeprecationWarning",
]
- Citry 0.9.x deprecates nothing, so expect no failures today.
- Why add it anyway: a 1.x minor release may deprecate a feature, and Python hides the warning in most programs. The setting turns each use into a failing test.
- To see the warning in a running server: Deprecations.
Upgrade the packages
python -m pip install -U "citry>=1.0.0,<2"
Add the packages you use to the same command:
"citry-lsp>=1.0.0,<2": the language server behind editor support. If you use the VS Code extension, update it to 1.0.0 at the same time."pygments-citry>=1.0.0,<2": Citry syntax highlighting for Pygments."citry-ui>=0.6.0,<0.7": the UI library.- 0.6.0 needs Citry 1.0.0 or later.
- Still 0.x, so pin one minor release.
Then:
- Change the Citry entry in
pyproject.tomlor your requirements file tocitry>=1.0.0,<2, so later installs stay on 1.x (see Pin and upgrade). - Depend on
citry, notcitry-core. Citry installs thecitry-coreversion it needs.
Handle State expiry
If a component's State sets no _max_age and its page's State has not changed for 24 hours:
- the next event call fails with
stale_state, without running its handler; - in production Citry shows the visitor nothing and writes a console warning; only a page rendered in development mode asks whether to reload;
- until the visitor reloads, every call from that component fails the same way.
Fix: set a longer _max_age in the State class inside the component. No setting turns expiry off.
from datetime import timedelta
class State:
_max_age = timedelta(days=7)
Details:
- New tokens: Citry issues a new token on every render of the component and after every call that changes State.
- A longer
_max_ageapplies to tokens Citry issues after the upgrade. - Tokens issued before the upgrade: expire 24 hours after Citry issued them, whatever
_max_agesays. - Whole-page caches (in your CDN or web framework): a cached page carries the token it was rendered with. If the cache keeps pages longer than 24 hours, set
_max_ageat least that long. Otherwise visitors get an expired token from the cache, and reloading does not help. - Render cache: an entry whose token has expired is rendered again, so a
ttlover 24 hours needs a matching_max_ageto save any work.
Why: unless a component sets State._storage = "server", Citry sends its State to the page as a signed string, the State token. In 0.9.x, a token from a component with no _max_age worked until you changed the secret Citry signs it with. Now it expires after 24 hours, like server-stored State. See State token lifetime and Treat State as input.
Set a valid _max_age
- Minimum: one second.
- A shorter value,
timedelta(0)included, raisesValueErrorwhen Python imports the component. - In 0.9.x, a shorter value made every token expire as soon as Citry issued it.
Tell visitors about out-of-date pages
In 1.0.0, Citry shows a production visitor nothing when an event call fails with stale_state. That covers an expired token, but also State the server dropped, a changed secret, and a deploy. Calls from that component keep failing until the visitor reloads the page. So in every app that uses server events, add a listener that tells visitors the page is out of date, as Handle out-of-date pages shows.
Rename reserved names
Citry and Citry UI use some attribute names to find their own elements in the page. A dict key with one of these names now raises ValueError when the page renders, in any letter case. Two places are affected:
c-bindon an HTML tag, such as<div c-bind="attrs">: a key such asc-render-idordata-ccss-xraisesValueError. Rename the key, for example todata-my-key. The full list is under Names Citry reserves. A<c-element>withc-isorc-bindalso refuses these names when you write them in the template.- Citry UI
attrs=inputs (citry-ui 0.6.0), such asCButtonattrs=orCSplitButtonprimary_attrs=: a key that starts withdata-citry-,data-cui-,data-cevordata-cidraisesValueError. Rename it, for example todata-my-key. Attrs a Citry UI component hands you, such asactivator_attrs, still work when you pass them on as you got them, with your own keys added.
Deploy the upgrade
Follow Deploy a Citry upgrade:
- clear cached copies of whole pages (in your CDN or web framework);
- give every server one shared cache while you upgrade servers one at a time (a rolling deploy).
Open pages keep working during a rolling deploy only between two 1.x releases (see Rolling deploys). A page opened on 0.9.x may show components that do not start until the visitor reloads it.
Check experimental APIs
Experimental features may change in a minor release.
- The list: Experimental features.
- Example: calling event handlers from your own server code with
EventsDispatcherandTransportContext. - Not experimental: the
citry-events/1protocol and the transports you register in the browser (see Events protocol). - If your code uses one, read the release notes before each minor upgrade.
Other changes in 1.0.0
No action needed in most projects:
javascript:URLs written with character references:- with
security_javascript="omit", Citry removes aScriptorStyledependency whose URL is, for example,Markup("javascript:x"), and removes such a URL from a dependency's attributes; - before, Citry reported it but left it on the page;
- citry-ui 0.6.0:
CButtonhref,CFormaction, and aformactioninCButtonattrsorCSplitButtonprimary_attrsraiseValueErrorfor it; - Citry and citry-ui already refused the same URL written as a plain string.
- with
- Unknown State token version: nothing changes today. If a later 1.x release changes the token format, a server that does not know the new version answers
stale_state(HTTP 409) instead ofinvalid_state(HTTP 403), and Citry firescitry:events:stale.
Every change: the 1.0.0 release notes.