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
js
Any
- JavaScript dependency declarations.
css
Any
- CSS dependency declarations.
extend
bool | list[type[Component]]
- Whether to inherit dependencies, or which component classes to
inherit them from.
local_files
str
- 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:
PathLike or a resolvable string) - resolved to PathScript/Style objects - unchanged__html__) - unchangedThe entry's type is what tells the emission step what
to do with it (inline the file content, emit a src/href tag, or
output the tag verbatim; see emission.py).
Attributes
js
tuple[Any, ...]
- JS entries, base classes' entries first, then the class's own,
de-duplicated.
css
Mapping[str, tuple[Any, ...]]
- CSS entries per media type ("all", "print", ...), same
ordering per list.
Dependency
class
Shared base of :class:Script and :class: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; see :data:DependencyKind.
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.
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 | NoneHash of the instance's js_data() result, or None when it has none.
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"}, wrap=False)
# <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 loading half reads each component or reusable definition base's
preserved Dependencies declaration, resolves and merges declarations
lazily in :meth:resolve, and drops a class's derived state when its files
are reset or its final registry alias is removed.
The emission half (docs/design/dependencies.md): records each component
render (on_component_data), bubbles the records up as nested renders
are consumed (on_render_context_merge), and at serialize time turns them into
<script>/<style>/<link> tags placed into the page
(on_serialize, implemented in emission.py).
on_component_unregistered
function
on_component_unregistered(ctx: OnComponentUnregisteredContext) -> Noneon_render_context_merge
function
on_render_context_merge(ctx: OnRenderContextMergeContext) -> Noneexport_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 (docs/design/asset_loading.md section 7.3).
Component.Dependencies.extend picks the bases:
True - inherit JS/CSS from Component.Dependencies of Component's base classesFalse - no inheritance; only the class's own entries (if any)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.
strategy
attribute
strategy: strThe serialize(deps_strategy=...) value this emission runs under
("document", "simple", or "fragment").
before_manifest
attribute
before_manifest: list[Dependency]Entries rendered as tags immediately before the data-citry page
manifest tag (mutable). For anything that must already be in the DOM when
the client-side manager processes the manifest, e.g. the events
extension's own manifest tag. Only the strategies that emit the page
manifest render these ("document" and "fragment"); under
"simple" they are not emitted.
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().