Add custom environment collector (#622)

Author: ofek

docs/history/hatch.md

@@ -15,9 +15,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ***Added:***
 
+- Add `custom` environment collector
 - Increase the timeout for and add retries to the `index` publisher
 - Expand home and environment variables in configured cache and data directories
-- Retroactively support `License-Expression` core metadata starting at version 2.1
 - Update project templates
 
 ***Fixed:***

docs/history/hatchling.md

@@ -11,6 +11,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 ***Added:***
 
 - Add `extra_metadata` build data to the `wheel` target
+- Retroactively support `License-Expression` core metadata starting at version 2.1
 - Add more type hints
 - Store Hatchling's metadata in `pyproject.toml`
 

docs/plugins/environment-collector/custom.md

@@ -0,0 +1,44 @@
+# Custom environment collector
+
+-----
+
+This is a custom class in a given Python file that inherits from the [EnvironmentCollectorInterface](reference.md#hatch.env.collectors.plugin.interface.EnvironmentCollectorInterface).
+
+## Configuration
+
+The environment collector plugin name is `custom`.
+
+=== ":octicons-file-code-16: pyproject.toml"
+
+    ```toml
+    [tool.hatch.env.collectors.custom]
+    ```
+
+=== ":octicons-file-code-16: hatch.toml"
+
+    ```toml
+    [env.collectors.custom]
+    ```
+
+## Options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `path` | `hatch_plugins.py` | The path of the Python file |
+
+## Example
+
+=== ":octicons-file-code-16: hatch_plugins.py"
+
+    ```python
+    from hatch.env.collectors.plugin.interface import EnvironmentCollectorInterface
+
+
+    class CustomEnvironmentCollector(EnvironmentCollectorInterface):
+        ...
+    ```
+
+If multiple subclasses are found, you must define a function named `get_environment_collector` that returns the desired environment collector.
+
+!!! note
+    Any defined [PLUGIN_NAME](reference.md#hatch.env.collectors.plugin.interface.EnvironmentCollectorInterface.PLUGIN_NAME) is ignored and will always be `custom`.

docs/plugins/environment-collector/default.md

@@ -6,7 +6,7 @@ This adds the `default` environment with [type](../../config/environment/overvie
 
 ## Configuration
 
-The environment plugin name is `default`.
+The environment collector plugin name is `default`.
 
 === ":octicons-file-code-16: pyproject.toml"
 

mkdocs.yml

@@ -90,6 +90,7 @@ nav:
       - Virtual: plugins/environment/virtual.md
     - Environment collector:
       - Reference: plugins/environment-collector/reference.md
+      - Custom: plugins/environment-collector/custom.md
       - Default: plugins/environment-collector/default.md
     - Publisher:
       - Reference: plugins/publisher/reference.md

src/hatch/env/collectors/custom.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from hatch.env.collectors.plugin.interface import EnvironmentCollectorInterface
+from hatch.plugin.constants import DEFAULT_CUSTOM_SCRIPT
+from hatchling.plugin.utils import load_plugin_from_script
+
+
+class CustomEnvironmentCollector(EnvironmentCollectorInterface):
+    PLUGIN_NAME = 'custom'
+
+    def __new__(cls, root: str, config: dict[str, Any], *args: Any, **kwargs: Any) -> EnvironmentCollectorInterface:
+        custom_script = config.get('path', DEFAULT_CUSTOM_SCRIPT)
+        if not isinstance(custom_script, str):
+            raise TypeError(f'Option `path` for environment collector `{cls.PLUGIN_NAME}` must be a string')
+        elif not custom_script:
+            raise ValueError(
+                f'Option `path` for environment collector `{cls.PLUGIN_NAME}` must not be empty if defined'
+            )
+
+        path = os.path.normpath(os.path.join(root, custom_script))
+        if not os.path.isfile(path):
+            raise OSError(f'Plugin script does not exist: {custom_script}')
+
+        hook_class = load_plugin_from_script(
+            path, custom_script, EnvironmentCollectorInterface, 'environment_collector'
+        )
+        hook = hook_class(root, config, *args, **kwargs)
+
+        # Always keep the name to avoid confusion
+        hook.PLUGIN_NAME = cls.PLUGIN_NAME
+
+        return hook

src/hatch/env/collectors/plugin/hooks.py

@@ -1,7 +1,8 @@
+from hatch.env.collectors.custom import CustomEnvironmentCollector
 from hatch.env.collectors.default import DefaultEnvironmentCollector
 from hatchling.plugin import hookimpl
 
 
 @hookimpl
 def hatch_register_environment_collector():
-    return DefaultEnvironmentCollector
+    return [CustomEnvironmentCollector, DefaultEnvironmentCollector]

src/hatch/plugin/constants.py

@@ -0,0 +1 @@
+DEFAULT_CUSTOM_SCRIPT = 'hatch_plugins.py'

tests/env/collectors/__init__.py

@@ -0,0 +1,103 @@
+import re
+
+import pytest
+
+from hatch.env.collectors.custom import CustomEnvironmentCollector
+from hatch.plugin.constants import DEFAULT_CUSTOM_SCRIPT
+
+
+def test_no_path(isolation):
+    config = {'path': ''}
+
+    with pytest.raises(
+        ValueError, match='Option `path` for environment collector `custom` must not be empty if defined'
+    ):
+        CustomEnvironmentCollector(str(isolation), config)
+
+
+def test_path_not_string(isolation):
+    config = {'path': 3}
+
+    with pytest.raises(TypeError, match='Option `path` for environment collector `custom` must be a string'):
+        CustomEnvironmentCollector(str(isolation), config)
+
+
+def test_nonexistent(isolation):
+    config = {'path': 'test.py'}
+
+    with pytest.raises(OSError, match='Plugin script does not exist: test.py'):
+        CustomEnvironmentCollector(str(isolation), config)
+
+
+def test_default(temp_dir, helpers):
+    config = {}
+
+    file_path = temp_dir / DEFAULT_CUSTOM_SCRIPT
+    file_path.write_text(
+        helpers.dedent(
+            """
+            from hatch.env.collectors.plugin.interface import EnvironmentCollectorInterface
+
+            class CustomHook(EnvironmentCollectorInterface):
+                def foo(self):
+                    return self.PLUGIN_NAME, self.root
+            """
+        )
+    )
+
+    with temp_dir.as_cwd():
+        hook = CustomEnvironmentCollector(str(temp_dir), config)
+
+    assert hook.foo() == ('custom', str(temp_dir))
+
+
+def test_explicit_path(temp_dir, helpers):
+    config = {'path': f'foo/{DEFAULT_CUSTOM_SCRIPT}'}
+
+    file_path = temp_dir / 'foo' / DEFAULT_CUSTOM_SCRIPT
+    file_path.ensure_parent_dir_exists()
+    file_path.write_text(
+        helpers.dedent(
+            """
+            from hatch.env.collectors.plugin.interface import EnvironmentCollectorInterface
+
+            class CustomHook(EnvironmentCollectorInterface):
+                def foo(self):
+                    return self.PLUGIN_NAME, self.root
+            """
+        )
+    )
+
+    with temp_dir.as_cwd():
+        hook = CustomEnvironmentCollector(str(temp_dir), config)
+
+    assert hook.foo() == ('custom', str(temp_dir))
+
+
+def test_no_subclass(temp_dir, helpers):
+    config = {'path': f'foo/{DEFAULT_CUSTOM_SCRIPT}'}
+
+    file_path = temp_dir / 'foo' / DEFAULT_CUSTOM_SCRIPT
+    file_path.ensure_parent_dir_exists()
+    file_path.write_text(
+        helpers.dedent(
+            """
+            from hatch.env.collectors.plugin.interface import EnvironmentCollectorInterface
+
+            foo = None
+            bar = 'baz'
+
+            class CustomHook:
+                pass
+            """
+        )
+    )
+
+    with pytest.raises(
+        ValueError,
+        match=re.escape(
+            f'Unable to find a subclass of `EnvironmentCollectorInterface` in `foo/{DEFAULT_CUSTOM_SCRIPT}`: {temp_dir}'
+        ),
+    ):
+        with temp_dir.as_cwd():
+            CustomEnvironmentCollector(str(temp_dir), config)