Theme
Version
GitHub PyPI Discord
On this page

Component libraries

You want to publish reusable components as a Python package, such as a design system other teams install with pip. An ordinary component belongs to one Citry instance, but your package cannot know which instance each application uses.

A component library solves this. The package defines its components once, and each application installs them into its own Citry instance.

For components that belong to one application, register them as usual. A library adds nothing there.

Lay out the package

A small library keeps its components in one package and lists them in one place:

acme-ui/
  pyproject.toml
  src/
    acme_ui/
      __init__.py
      py.typed
      components/
        __init__.py
        badge.py

Add Citry as a normal package dependency. If a component loads its template, JavaScript, or CSS from a file, include those files in the built distribution as package data.

Define a component

Subclass LibraryComponent instead of Component. You write it exactly like a component, but defining it does not register it with any Citry instance:

# src/acme_ui/components/badge.py
from citry import LibraryComponent

class AcmeBadge(LibraryComponent):
    class Kwargs:
        label: str
        tone: str = "neutral"

    template = """
      <span c-class="['badge', 'badge--' + tone]">
        {{ label }}
      </span>
    """

    css = """
      .badge {
        border-radius: 999px;
        padding: 0.25rem 0.6rem;
      }
    """

Do not set citry on a library component. Each application that installs the library gets its own copy of the class, bound to its own instance.

Write the manifest

The manifest is a ComponentLibrary object that names the library and lists its components, in the order Citry should register them. Store it as __citry_library__ in the package:

# src/acme_ui/__init__.py
from citry import ComponentLibrary

from acme_ui.components.badge import AcmeBadge

__citry_library__ = ComponentLibrary(
    name="acme-ui",
    components=(AcmeBadge,),
)

If the components need a custom extension, list its name. Installing the library then fails if the application has not added that extension:

__citry_library__ = ComponentLibrary(
    name="acme-ui",
    components=(AcmeBadge,),
    required_extensions=("acme_theme",),
)

Install the library

An application passes the package, or its manifest, to register_library():

import acme_ui
from citry import Citry

app = Citry()
installed = app.register_library(acme_ui)

The components then work in templates like any other registered component:

<c-acme-badge label="Ready" tone="success" />

Use components in Python

Calling a library component records its inputs. Citry builds the actual component when a template inserts the value, using the Citry instance that renders that template:

from citry import Component

from acme_ui import AcmeBadge

class Receipt(Component):
    citry = app

    class Kwargs:
        status: str

    def template_data(self, kwargs: Kwargs, slots):
        return {
            "badge": AcmeBadge(
                label=kwargs.status,
                tone="success",
            ),
        }

    template = """
      <p>Status: {{ badge }}</p>
    """

Here badge renders through Receipt's Citry instance. To render a library component on its own, outside any template, pass the instance:

badge = AcmeBadge(label="Ready")
html = str(badge.render(citry=app))

Citry checks the inputs against Kwargs when it builds the component, not when you call AcmeBadge(...). Your editor also cannot check the inputs of that call, because its signature accepts any keyword arguments.

Your own Python objects can turn into components the same way. See Render custom values.

Get the bound class

Templates and library calls cover most code. When you need the actual component class bound to your Citry instance, look it up on the value register_library() returned:

Badge = installed[AcmeBadge]
badge = Badge(label="Ready")
html = str(badge)

Set up VS Code

The Citry VS Code extension can read the manifest directly. Point citry.app at it:

{
  "citry.app": "acme_ui:__citry_library__"
}

The editor then knows Citry's built-in components and the library's components, but nothing from an application. If the manifest lists required_extensions, point citry.app at a configured Citry instance that installs the library instead.

Check the library

citry check leaves out findings in a registered library's components, because an app that installs the library cannot change them. To check the library itself, for example in its own tests, register it in a small app and ask for those findings:

citry --app tests.app:engine check --include-libraries

See Library components.

Publishing rules

Edit classes first

Creating the manifest locks its components. Setting or deleting a class attribute afterwards raises AttributeError. Values stored inside an attribute, such as a list, are not locked, so treat the whole component as read-only from then on. Apply class decorators before you create the manifest.

Failed installs

If validation, a name clash, or an extension hook raises during register_library(), Citry removes every component the call had registered. It cannot undo side effects outside Citry, such as a file an import or a hook wrote.

Installing again

Registering the same manifest again returns the existing installation. To install a changed or reloaded version under the same name, call Citry.clear() and run your normal application startup again. Without the clear, register_library() raises LibraryManifestChanged.

Old handles expire

After Citry.clear(), the value register_library() returned earlier no longer gives out classes. Looking one up raises LibraryInstallationStale, so you never get a class from a library that is no longer installed.