Skip to content

Environment collector plugins

Environment collectors allow for dynamically modifying environments or adding environments beyond those defined in config. Users can override default values provided by each environment.

Known third-party

Installation

Any required environment collectors that are not built-in must be manually installed alongside Hatch or listed in the tool.hatch.env.requires array for automatic management:

[tool.hatch.env]
requires = [
  "...",
]

[env]
requires = [
  "...",
]

EnvironmentCollectorInterface

Example usage:

    from hatch.env.collectors.plugin.interface import EnvironmentCollectorInterface


    class SpecialEnvironmentCollector(EnvironmentCollectorInterface):
        PLUGIN_NAME = 'special'
        ...

    from hatchling.plugin import hookimpl

    from .plugin import SpecialEnvironmentCollector


    @hookimpl
    def hatch_register_environment_collector():
        return SpecialEnvironmentCollector
Source code in src/hatch/env/collectors/plugin/interface.py 
class EnvironmentCollectorInterface:
    """
    Example usage:

    ```python tab="plugin.py"
        from hatch.env.collectors.plugin.interface import EnvironmentCollectorInterface


        class SpecialEnvironmentCollector(EnvironmentCollectorInterface):
            PLUGIN_NAME = 'special'
            ...
    ```

    ```python tab="hooks.py"
        from hatchling.plugin import hookimpl

        from .plugin import SpecialEnvironmentCollector


        @hookimpl
        def hatch_register_environment_collector():
            return SpecialEnvironmentCollector
    ```
    """

    PLUGIN_NAME = ''
    """The name used for selection."""

    def __init__(self, root, config):
        self.__root = root
        self.__config = config

    @property
    def root(self):
        """
        The root of the project tree as a path-like object.
        """
        return self.__root

    @property
    def config(self) -> dict:
        """
        ```toml config-example
        [tool.hatch.env.collectors.<PLUGIN_NAME>]
        ```
        """
        return self.__config

    def get_initial_config(self) -> dict[str, dict]:  # noqa: PLR6301
        """
        Returns configuration for environments keyed by the environment or matrix name.
        """
        return {}

    def finalize_config(self, config: dict[str, dict]):
        """
        Finalizes configuration for environments keyed by the environment or matrix name. This will override
        any user-defined settings and any collectors that ran before this call.

        This is called before matrices are turned into concrete environments.
        """

    def finalize_environments(self, config: dict[str, dict]):
        """
        Finalizes configuration for environments keyed by the environment name. This will override
        any user-defined settings and any collectors that ran before this call.

        This is called after matrices are turned into concrete environments.
        """

PLUGIN_NAME = '' class-attribute instance-attribute

The name used for selection.

root property

The root of the project tree as a path-like object.

config: dict property 

[tool.hatch.env.collectors.<PLUGIN_NAME>]

[env.collectors.<PLUGIN_NAME>]

get_initial_config() -> dict[str, dict]

Returns configuration for environments keyed by the environment or matrix name.

Source code in src/hatch/env/collectors/plugin/interface.py 
def get_initial_config(self) -> dict[str, dict]:  # noqa: PLR6301
    """
    Returns configuration for environments keyed by the environment or matrix name.
    """
    return {}

finalize_config(config: dict[str, dict])

Finalizes configuration for environments keyed by the environment or matrix name. This will override any user-defined settings and any collectors that ran before this call.

This is called before matrices are turned into concrete environments.

Source code in src/hatch/env/collectors/plugin/interface.py 
def finalize_config(self, config: dict[str, dict]):
    """
    Finalizes configuration for environments keyed by the environment or matrix name. This will override
    any user-defined settings and any collectors that ran before this call.

    This is called before matrices are turned into concrete environments.
    """

finalize_environments(config: dict[str, dict])

Finalizes configuration for environments keyed by the environment name. This will override any user-defined settings and any collectors that ran before this call.

This is called after matrices are turned into concrete environments.

Source code in src/hatch/env/collectors/plugin/interface.py 
def finalize_environments(self, config: dict[str, dict]):
    """
    Finalizes configuration for environments keyed by the environment name. This will override
    any user-defined settings and any collectors that ran before this call.

    This is called after matrices are turned into concrete environments.
    """