----------------------------------------------------------------------
This is the API documentation for the chameleon_partials library.
----------------------------------------------------------------------


## Setup

Register chameleon_partials with Chameleon. Call this once at application startup.


register_extensions(template_folder: str, auto_reload: bool = False, cache_init: bool = True) -> None

Register chameleon_partials with Chameleon so partials can be rendered.

Call this once during application startup, before any template is rendered. It builds a
Chameleon `PageTemplateLoader` rooted at `template_folder` and stores it in module-level
state that `render_partial` uses to locate templates. Registration is process-wide and is
not guarded by a lock, so call it from normal single-threaded startup code rather than
from concurrent request handlers.

Args:
    template_folder: Path to the root folder containing your Chameleon templates (with a
        `partials` subfolder by convention). Must be an existing directory. Partials are
        later looked up by path relative to this folder.
    auto_reload: When `True`, Chameleon reloads a template from disk whenever the file
        changes. Useful during development; leave `False` in production.
    cache_init: When `True` (the default), calling this again after a previous
        successful registration is a no-op, which makes repeated startup calls safe.
        Pass `False` to force re-registration, for example to point at a different
        template folder in tests.

Raises:
    PartialsException: If `template_folder` is empty or is not an existing directory.

Examples:
    ```python
    import chameleon_partials

    # At startup; use auto_reload=True while developing.
    chameleon_partials.register_extensions('path/to/templates', auto_reload=True)
    ```


## Rendering partials

Render partial templates and expose render_partial to your view models.


render_partial(template_file: str, **template_data: Any) -> chameleon_partials.HTML

Render a partial template to an HTML fragment.

Looks up `template_file` in the folder registered with `register_extensions` and renders
it with the supplied keyword arguments as its model. `render_partial` is injected into the
model automatically, so a partial can render further nested partials. The fragment is
rendered as text (`str`); any `bytes` values in the model are decoded as UTF-8.

Args:
    template_file: Path to the partial, relative to the registered templates folder, for
        example `shared/partials/video_image.pt`.
    **template_data: Keyword arguments passed to the template as its model (the variables
        the template can reference). Values may be any Python objects your template
        expressions use. The name `encoding` is reserved and cannot be used; `translate`,
        `target_language`, and `repeat` have special meaning to Chameleon.

Returns:
    An `HTML` wrapper whose `__html__` method yields the rendered markup as safe, pre-escaped HTML.

Raises:
    PartialsException: If `register_extensions` has not been called yet.
    ValueError: Propagated from Chameleon if `template_file` does not exist under the registered folder.

Examples:
    ```python
    import chameleon_partials

    chameleon_partials.register_extensions('path/to/templates')
    html = chameleon_partials.render_partial('shared/partials/user_card.pt', name='Sarah', age=32)
    print(html.html_text)
    ```

extend_model(model: Dict[str, Any] | None) -> Dict[str, Any]

Add `render_partial` to a view model so templates can call it.

Use this in frameworks where a view returns a model dictionary (for example FastAPI) and
you need `render_partial` available inside the template. For Pyramid, prefer the
`BeforeRender` middleware shown in the README instead. Any existing `render_partial` key
in the model is replaced.

Args:
    model: The view model dictionary to extend. `None` is treated as an empty model.

Returns:
    The same dictionary with a `render_partial` key added, or a new dictionary when `model` is `None`.

Raises:
    PartialsException: If `model` is not a dictionary (and not `None`).

Examples:
    ```python
    import chameleon_partials

    model = {'name': 'Sarah'}
    model = chameleon_partials.extend_model(model)
    # model['render_partial'] is now callable from the template.
    ```


## Exceptions

Errors raised by the library.


PartialsException

Raised when chameleon_partials is configured or used incorrectly.

Examples include registering with a missing template folder, rendering a partial
before calling `register_extensions`, or passing a non-dictionary model to
`extend_model`. Errors raised by Chameleon itself, such as the `ValueError` for a
missing template file, are propagated unchanged rather than wrapped in this type.