Plugin Architecture

Pharaoh may be extended using pluggy. Just import the impl decorator from pharaoh.plugins.api and implement one of the specs documented below.

If you like to extend other parts of the library please open up a discussion on GitHub or raise a PR directly.

Here an example on how to extend the Sphinx configuration programmatically:

from pharaoh.plugins.api import impl

@impl
def pharaoh_configure_sphinx(project: PharaohProject, config: dict, confdir: Path):
    config["extensions"].append("sphinxcontrib.confluencebuilder")
    config["html_style"] = "sphinx_rtd_theme_overrides.css"

Custom project class

Implement pharaoh_get_project_class to select a PharaohProject subclass for CLI project creation, project discovery, asset generation, and Sphinx builds:

from pharaoh.plugins.api import impl

@impl
def pharaoh_get_project_class():
    from my_plugin.project import CustomProject
    return CustomProject

Define CustomProject in your plugin package as a subclass of pharaoh.project.PharaohProject. Keep the import inside the hook: plugins are discovered while Pharaoh’s modules are being imported. Use the normal project constructor arguments so that the CLI can instantiate the subclass.

The first non-None hook result is used, following pluggy’s hook ordering; @impl(tryfirst=True) can give an implementation priority. Without a result, the standard class is used. Returning an unrelated class or an instance raises TypeError. Direct calls to PharaohProject(...) still construct that class.

Use get_project(path) to discover an existing project with the selected class. The no-argument get_project() still returns the most recently created instance. For worker processes and notebooks, install the plugin through the existing plugin entry point or PHARAOH_PLUGINS discovery mechanism; in-memory registrations made only in the parent process are not inherited by a fresh Python interpreter.

Hookspec Markers

pharaoh_add_cli_commands(cli: click.Group)[source]

This hook is called after all click CLI commands have been added to add you own CLI commands. Example:

from pharaoh.plugins.api import impl

@impl
def pharaoh_add_cli_commands(cli: click.Group):
    @cli.command()
    @click.pass_context
    def my_cli_command(ctx):
        project = ctx.obj["project"]
        project.do_something
pharaoh_asset_gen_prepare_resources(project: PharaohProject, resources: dict[str, Resource])[source]

This hook is called before asset generation for each component that is selected.

Example:

@impl
def pharaoh_asset_gen_prepare_resources(project: PharaohProject, resources: dict[str, Resource]):
    from .resources import RemoteResource

    # Transform resources
    for r in resources.values():
        if isinstance(r, RemoteResource):
            r.download(
                url=project.get_setting("cloud.url"),
                auth_credentials=project.get_setting("cloud.auth_credentials", to_container=True) or None,
            )
Parameters:
  • project – The Pharaoh project instance

  • resources – A mapping of all resources that are defined for the current component.

pharaoh_asset_gen_started(project: PharaohProject)[source]

This hook is called when the asset generation is executed.

Parameters:

project – The Pharaoh project instance

pharaoh_build_finished(project: PharaohProject, exc_info: tuple[type[BaseException], BaseException, TracebackType] | None)[source]

This hook is called after a Sphinx build ended with or without error.

Parameters:
  • project – The Pharaoh project instance

  • exc_info – An optional value that is returned by sys.exc_info() in case the build raised an Exception.

pharaoh_build_started(project: PharaohProject, builder: str)[source]

This hook is called before a Sphinx build is started.

Parameters:
  • project – The Pharaoh project instance

  • builder – The name of the configured builder

pharaoh_collect_default_settings() → Path | dict[source]

This hook is called when scaffolding a new Pharaoh project. It collects all default settings either as a path to a YAML file or a dictionary. The collected results are loaded into omegaconf.dictconfig.DictConfig instances and merged in the same order as they are collected (first discovered may get overwritten, last discovered always wins).

Example:

@impl
def pharaoh_collect_default_settings():
    return Path(__file__).with_name("my_own_setting.yaml")
Returns:

A path to a YAML file or a dictionary

pharaoh_collect_l1_templates() → list[L1Template][source]

Collects all first-level templates.

Example:

@impl
def pharaoh_collect_l1_templates():
    return [
        L1Template(
            name="myorg.default_project",
            path=Path(__file__).parent / "templates" / "level_1" / "default_project",
        ),
    ]
pharaoh_collect_l2_templates() → list[str | Path][source]

Collects paths to all second-level template directories.

pharaoh_collect_resource_types() → list[type[Resource]][source]

Allows registering custom resource types.

Example:

@impl
def pharaoh_collect_resource_types():
    from .resources import RemoteResource

    return [RemoteResource]
pharaoh_configure_sphinx(project: PharaohProject, config: dict[str, Any], confdir: Path)[source]

This hook is called at the end of pharaoh.project.PharaohProject.get_default_sphinx_configuration() when Sphinx is reading the conf.py file. It can update the default Sphinx configuration in-place.

Example:

@impl
def pharaoh_configure_sphinx(project: PharaohProject, config: dict, confdir: Path):
    config["extensions"].append("sphinxcontrib.confluencebuilder")
    config["html_style"] = "sphinx_rtd_theme_overrides.css"
Parameters:
  • project – The Pharaoh project instance

  • config – The default Sphinx config defined by Pharaoh.

  • confdir – The parent directory of conf.py

pharaoh_find_asset_render_template(template_name: str) → str | Path[source]

This hook is called when an asset template is looked up by name and can customize the search behavior. Per default the templates in package pharaoh.templating.second_level.sphinx_ext.asset_ext_templates are used.

This template is used to include an asset into a Sphinx document, e.g. the template for a picture asset may be called image.rst.jinja2 and would be using the image directive to embed it. If found, the path to the template is returned.

See also

Asset Templates

Note

The template’s file name should end with .jinja2.

Parameters:

template_name – The name of the template

pharaoh_get_asset_render_template_mappings() → dict[str, str][source]

This hook maps file extensions of assets to names of templates (see hook pharaoh_find_asset_render_template) that are used to embed the asset into the Sphinx document. The file extension is only taken into account if no template metadata key is present in the asset’s metadata.

Pharaoh provides a default mapping (see Asset Templates) which may be updated by this hook.

pharaoh_get_project_class() → type[PharaohProject] | None[source]

Return a PharaohProject subclass for CLI creation and project discovery.

The first non-None result is used. Without an implementation, PharaohProject remains the default. Import the project class inside the hook to avoid circular imports during plugin discovery.

pharaoh_modify_gitignore(gitignore_lines: list[str])[source]

This hook can be used to modify the content on the .gitignore file that is included in the generated Pharaoh project inplace.

Parameters:

gitignore_lines – A list of lines to add to the .gitignore file

pharaoh_project_created(project: PharaohProject)[source]

This hook is called whenever a Pharaoh report has been generated

Parameters:

project – The Pharaoh project instance

pharaoh_sphinx_app_inited(app: PharaohSphinx)[source]

This hook is after the Sphinx application is initialized.

Parameters:

app – The Pharaoh-specific Sphinx application