Dependencies
The JS/CSS dependency types collected and placed at serialize time, and the built-in citry.ext.dependencies extension that owns them.
DependenciesConfig class
Bases: ExtensionConfig
Typed runtime view of one component's Dependencies declaration.
Citry creates this value from the component's nested Dependencies class. Read it through component.dependencies while the component is rendering. Use Component.get_dependencies() when you need the resolved, inherited asset list.
Attributes
jsAny- JavaScript dependency declarations.cssAny- CSS dependency declarations.extendbool | list[type[Component]]- Whether to inherit dependencies, or which component classes to inherit them from.local_filesstr- Whether local dependency files are inlined or served from Citry's asset routes.
CitryDependencies class
A component's merged secondary assets (from the nested Dependencies classes).
Holds resolved entries:
- a local file (declared with
PathLikeor a resolvable string) - resolved toPath - URLs (plain strings) - unchanged
Script/Styleobjects - unchanged- Pre-rendered tags (
__html__) - unchanged
The entry's type tells Citry what to do with it when it writes the page: inline the file content, emit a src/href tag, or output the tag verbatim.
Attributes
jstuple[Any, ...]- JS entries, base classes' entries first, then the class's own, de-duplicated.cssMapping[str, tuple[Any, ...]]- CSS entries per media type ("all","print", ...), same ordering per list.
Dependency class
Shared base of Script and Style.
Holds either inline content or a url, never both; rendering raises when neither or both are set.
content attribute
content: str | NoneText inside the <script> or <style> tag. None for url-based dependencies.
url attribute
url: str | NoneIf set, renders as <script src="..."> / <link rel="stylesheet" href="..."> instead of an inline tag.
kind attribute
kind: DependencyKindWhat this dependency is for: "core" (scripts Citry adds itself to run its browser runtime, such as the runtime, the script that loads it for a fragment, and the data it reads to mount components), "component" (a component's own js or css), "variables" (a generated stylesheet carrying css_data() values), or "extra" (anything else, such as a Dependencies entry).
origin_class_id attribute
origin_class_id: str | Noneclass_id of the component class this dependency came from, when known. Used in error messages and for per-component hooks.
render_json function
Render as a JSON-ready dict with tag, attrs, and content.
This is the shape the client-side manager consumes when it constructs the element in the browser.
DependencyRecord class
Bases: tuple
One "this component instance rendered" note, collected during a render.
The dependencies extension appends one of these to the render-scoped CitryContext.extra per component render, and the notes bubble up to the root as nested renders are consumed. At serialize time the collected records are resolved into the actual Script/Style tags. The exact class is retained until serialization so hot replacement cannot mix a rendered old body with a new class's assets; heavy content lives in the cache.
component_id attribute
component_id: strThe render id of the component instance (component.id).
js_vars_hash attribute
js_vars_hash: str | NoneAlways None: js_data() values reach the browser inside the page's Vue app data.
css_vars_hash attribute
css_vars_hash: str | NoneHash of the instance's css_data() result, or None when it has none.
component_class attribute
Exact class version that produced the record, retained for delayed serialization.
Script class
Bases: Dependency
One <script> tag.
With url set, renders <script src="...">; otherwise renders the content inline as <script>...</script>.
Example::
Script(
content="console.log('hi');",
attrs={"type": "module"},
)
# <script type="module">console.log('hi');</script>
wrap attribute
wrap: boolWrap inline content in a self-executing function, so its top-level variables do not leak into (or collide with) other scripts on the page::
(function() {
console.log('hi');
})();
Only applies to classic scripts (no type attribute or a JS MIME type); module/importmap/other types are never wrapped.
Style class
Bases: Dependency
One stylesheet tag.
With url set, renders <link rel="stylesheet" href="..."/>; otherwise renders the content inline as <style>...</style>.
Example::
Style(url="/static/print.css", attrs={"media": "print"})
# <link media="print" rel="stylesheet" href="/static/print.css"/>
DependenciesExtension class
Bases: Extension
The built-in extension owning the Dependencies secondary-asset class.
The first time resolve() is called for a class, the extension reads its Dependencies declaration, merges it with its bases' declarations, and caches the result. It drops that result when the class's files are reset or its last registered name is removed.
During a render, the extension records each component render (on_component_data) and passes the records up to the parent as nested renders finish (on_render_context_merge). When the page is serialized (on_serialize), it turns the records into <script>/<style>/<link> tags placed into the page.
on_component_unregistered function
on_component_unregistered(ctx: OnComponentUnregisteredContext) -> None on_render_context_merge function
on_render_context_merge(ctx: OnRenderContextMergeContext) -> None export_render_cache function
Detach selected dependency records and exact variable-script values.
stage_render_cache function
stage_render_cache(ctx: OnRenderCacheStageContext) -> StagedRenderCacheContributionValidate dependency payloads and prepare exact cache repairs.
resolve function
resolve(comp_cls: type[Component]) -> CitryDependenciesResolve and merge comp_cls's secondary assets, cached per class.
Merge order is bases first, own entries last: list order becomes document order at emission and CSS breaks equal-specificity ties by document order, so the more specialized class's styles must come later to win.
Component.Dependencies.extend picks the bases:
True- inherit JS/CSS fromComponent.Dependenciesof Component's base classesFalse- no inheritance; only the class's own entries (if any)- a list - exactly those classes + their bases, in the order given
An explicit Dependencies = None declaration means no own entries and no inheritance.
OnDependenciesContext class
Context for the on_dependencies hook, owned by the dependencies extension (not a "core" hook: any extension that defines an on_dependencies method receives it, via the manager's emit).
Fires at serialize time with the final, deduplicated tag lists (possibly empty), just before they are rendered into the page. Mutate the lists in place to add, remove, or reorder entries.
scripts attribute
scripts: list[Dependency]The <script> entries about to be emitted, in document order (mutable).
styles attribute
styles: list[Dependency]The stylesheet entries about to be emitted, in document order (mutable).
context attribute
context: CitryContextThe root render's CitryContext. Its extra carries everything that bubbled up during the render, so an extension can read back what its render-time hooks collected.
selected_render attribute
selected_render: CitryRenderThe exact render selected for serialization and asset filtering.
strategy attribute
strategy: strThe serialize(deps_strategy=...) value this emission runs under ("document", "simple", or "fragment").
early_scripts attribute
early_scripts: list[Dependency]Scripts that must run before the other dependency scripts (mutable). Static output writes them as tags ahead of the dependency scripts; under simple they are emitted with the other direct dependency tags. On an interactive page the Vue app loads them after the Vue runtime and ahead of scripts, in list order, under the same rules as any entry in scripts. When the page loads, these scripts run before Citry creates the page's first Vue app, so one of them can call Citry.vue.use() to install a Vue plugin for that app.
get_dependencies function
get_dependencies(comp_cls: type[Component]) -> CitryDependenciesThe merged secondary assets of a component class.
Routes through the class's Citry instance to its built-in dependencies extension. Users reach this through Card.get_dependencies().