Plugins

django-bird uses a plugin system based on pluggy to allow extending its functionality.

Available Hooks

collect_component_assets(template_path: pathlib.Path) → collections.abc.Iterable[django_bird.staticfiles.Asset]

Collect all assets associated with a component.

This hook is called for each component template to gather its associated static assets. Implementations should scan for and return any CSS, JavaScript or other static files that belong to the component and return a list/set/other iterable of Asset objects.

get_template_directories() → list[pathlib.Path]

Return a list of all directories containing templates for a project.

This hook allows plugins to provide additional template directories beyond the default Django template directories. Implementations should return a list of Path objects pointing to directories that contain Django templates.

The template directories returned by this hook will be used by django-bird to discover components and their associated templates.

pre_ready() → None

Called before django-bird begins its internal setup.

This hook runs at the start of django-bird’s initialization, before any internal components are configured or discovered. Plugins can use this hook to perform early configuration of:

  • Django settings

  • Template directories

  • Template builtins

ready() → None

Called after django-bird application has completed its internal setup and is ready.

This hook is called during Django’s application ready phase, after django-bird’s own initialization is complete. Plugins can:

  • Access fully configured components

  • Register additional features that depend on django-bird being ready

  • Perform cleanup or post-initialization tasks

register_asset_types(register_type: collections.abc.Callable[[django_bird.staticfiles.AssetType], None]) → None

Register a new type of asset.

This hook allows plugins to register additional asset types beyond the default CSS and JS types. Each asset type defines how static assets should be rendered in HTML, what file extension it uses, and what django-bird asset templatetag it should be rendered with.

Creating a Plugin

To create a plugin:

  1. Create a Python package for your plugin

  2. Import the django_bird.hookimpl marker:

    from django_bird import hookimpl

  3. Implement one or more hooks using the @hookimpl decorator.

  4. Register your plugin in your package’s entry points:

    [project.entry-points."django_bird"]
my_plugin = "my_plugin.module"

See the pluggy documentation for more details.