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


## Framework registration

Register render_partial with your web framework once at app startup.


register_extensions(app: 'Flask') -> None

Register jinja_partials with a Flask application.

Makes render_partial available as a global function in the app's Jinja
templates, rendering with flask.render_template.

Args:
    app: The Flask application instance.

Raises:
    PartialsException: If Flask is not installed.

register_fastapi_extensions(app: 'FastAPI', templates: 'FastAPIJinja2Templates', max_workers: int = 4) -> None

Register jinja_partials with a FastAPI application.

This creates a dedicated ThreadPoolExecutor for rendering partials in async
environments. The executor is created when the app's lifespan starts and is
shut down when the lifespan exits - even if startup or shutdown raises - so
the app can be started and stopped repeatedly (e.g. multiple TestClient
cycles). Outside a lifespan cycle, partials render directly for sync
environments, or via a per-registration fallback executor with the same
max_workers for async (enable_async=True) environments.

Args:
    app: The FastAPI application instance.
    templates: The Jinja2Templates instance used for rendering.
    max_workers: Maximum number of worker threads for rendering partials.
                 Defaults to 4.

Raises:
    PartialsException: If FastAPI is not installed.

Example:
    Register during app setup:

        from fastapi import FastAPI
        from fastapi.templating import Jinja2Templates
        import jinja_partials

        app = FastAPI()
        templates = Jinja2Templates(directory="templates")
        jinja_partials.register_fastapi_extensions(app, templates)

register_starlette_extensions(templates: 'Jinja2Templates', app: ForwardRef('Starlette') | None = None, max_workers: int = 4) -> None

Register jinja_partials with Starlette templates.

If an app is provided, creates a dedicated ThreadPoolExecutor when the
app's lifespan starts and shuts it down when the lifespan exits - even if
startup or shutdown raises - so the app can be started and stopped
repeatedly; outside lifespan cycles, async renders use a per-registration
fallback executor with the same max_workers. Without an app, partials
render directly for sync environments, or via a shared module-level
executor for async (enable_async=True) environments.

Args:
    templates: The Jinja2Templates instance used for rendering.
    app: Optional Starlette application instance for lifecycle management.
    max_workers: Maximum number of worker threads for rendering partials.
                 Only used when app is provided. Defaults to 4.

Raises:
    PartialsException: If Starlette is not installed.

Example:
    With lifecycle management:

        from starlette.applications import Starlette
        from starlette.templating import Jinja2Templates
        import jinja_partials

        templates = Jinja2Templates(directory="templates")
        app = Starlette(...)
        jinja_partials.register_starlette_extensions(templates, app=app)

    Without lifecycle management (backwards compatible):

        jinja_partials.register_starlette_extensions(templates)

register_quart_extensions(app: 'Quart', max_workers: int = 4) -> None

Register jinja_partials with a Quart application.

This creates a dedicated ThreadPoolExecutor for rendering partials in async
environments. The executor is created when the app starts serving and shut
down when it stops, so the app can be started and stopped repeatedly (an
executor left behind by a failed startup is replaced on the next start).
Outside a serving cycle, partials render via a per-registration fallback
executor with the same max_workers.

Args:
    app: The Quart application instance.
    max_workers: Maximum number of worker threads for rendering partials.
                 Defaults to 4.

Raises:
    PartialsException: If Quart is not installed.

register_environment(env: jinja2.environment.Environment, markup: bool = False) -> None

Register jinja_partials with a plain Jinja2 environment.

Use this for standalone Jinja2 usage or frameworks without dedicated support.
Handles both sync and async (enable_async=True) environments.

Args:
    env: The Jinja2 Environment to make render_partial available in.
    markup: When True, wrap rendered partials in markupsafe.Markup.
            Defaults to False.


## Rendering

Render partial templates directly or build framework-specific renderers.


render_partial(template_name: str, renderer: Callable[..., Any] | None = None, markup: bool = True, **data: Any) -> markupsafe.Markup | str

Render a partial template and return the resulting HTML fragment.

Args:
    template_name: Path of the template within the templates folder,
        e.g. `shared/partials/video_image.html`.
    renderer: Callable that renders the template with the given keyword
        arguments. Defaults to flask.render_template when Flask is installed.
    markup: When True (the default), wrap the result in markupsafe.Markup
        so it is not re-escaped when inserted into another template.
    **data: Model data passed to the template as keyword arguments.

Returns:
    The rendered fragment as Markup, or str when markup=False.

Raises:
    PartialsException: If no renderer is specified and Flask is not installed.

generate_render_partial(renderer: Callable[..., Any], markup: bool = True) -> Callable[..., markupsafe.Markup | str]

Create a render_partial function bound to a specific renderer.

Args:
    renderer: Callable that renders a template name plus keyword arguments to a string.
    markup: When True (the default), results are wrapped in markupsafe.Markup.

Returns:
    A callable with the same signature as render_partial that uses the bound renderer.


## Jinja2 extension

Declarative registration via the Jinja2 extension mechanism.


PartialsJinjaExtension(environment: jinja2.environment.Environment) -> None

Jinja2 extension that automatically registers render_partial functionality.

The extension automatically makes render_partial available as a global
function in templates. By default, markup is enabled.

Note:
    Partials registered this way render directly through the Jinja2
    environment rather than flask.render_template, so Flask context
    processors do not apply inside partials. Flask apps that rely on
    context processors should use register_extensions instead.

Args:
    environment: The Jinja2 environment the extension is loaded into.
        Jinja2 passes this automatically when the class is listed in
        extensions=[...].

Example:
    Enable the extension on a Jinja2 environment:

        from jinja2 import Environment
        env = Environment(extensions=["jinja_partials.PartialsJinjaExtension"])


## Exceptions

Errors raised by jinja_partials.


PartialsException

Raised when jinja_partials is misconfigured or a required web framework is not installed.