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.DictConfiginstances 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 theconf.pyfile. 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_templatesare 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.jinja2and would be using theimagedirective to embed it. If found, the path to the template is returned.See also
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 notemplatemetadata 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