fix coversioning tests and document (#11)

Hatch only runs hooks if there's something dynamic in the project table,
so add an arbitrary element to the project table in the test
pyproject.tomls. Also, add some docs about making sure dynamic is in
there, and add some little stuff found from online examples.

Author: sfoster1

hatch-dependency-coversion/DEVELOPING.md

@@ -0,0 +1,40 @@
+# Development Documentation
+
+`hatch-dependency-coversion`is a python package developed using [Hatch](https://github.com/pypa/hatch) as its environment manager, task runner, and build frontend. Generally, any command that inspects or interacts with the package source is done through hatch.
+
+## Contributing
+
+Contributions should come through pull request. If done via a fork, a maintainer will run the CI checks after a quick review. Open source contributions are welcome! 
+
+Pull requests should contain
+- A descriptive title
+   - that is prefixed with `hatch-dependency-coversion:`, since this repository has multiple packages
+- A descriptive body that notes what the problem/missing feature is that the PR fixes and how the PR fixes it
+- A note on how the PR should be tested, if testing is required, and descriptions of how you tested it
+- A news fragment in `changelog.d` that adheres to [towncrier news fragment format](https://towncrier.readthedocs.io/en/stable/tutorial.html#creating-news-fragments) describing your change
+- If you're not already in it and you want to be, an addition of yourself to CONTRIBUTORS.md
+
+## Linting/formatting/typechecking
+
+Static analysis tools are run from the default hatch environment. Typechecking is via [mypy](http://mypy-lang.org/), linting and formatting is via [ruff](https://github.com/astral-sh/ruff). You can run these commands with `hatch run` without further qualification:
+- Typecheck: `hatch run check`
+- Format: `hatch run format`
+- Lint: `hatch run lint`
+  - Auto lint fixes: `hatch run lint --fix`
+  
+These all must pass in CI before a PR can be merged.
+  
+## Tests
+
+Tests are defined both in the default environment (in which case they will run just in whatever python environment and dependency set you happen to have installed) and in a special `test` environment endowed with matrix definitions for multiple python versions and multiple versions of the `hatch-vcs` plugin that `hatch-dependency-coversion` extends.
+
+- Run quick tests: `hatch run test`
+- Run full test matrix: `hatch run test:test`
+
+Tests must pass in CI before a PR can be merged.
+
+## Maintenance and Releasing
+
+Changelogs are generated using [towncrier](https://towncrier.readthedocs.io/en/stable/index.html). When opening a PR that has a newsworthy change, that PR should include a news fragment in `changelog.d`. Changelog generation happens during the release flow, which is automated via github actions that can be run by project maintainers.
+
+

hatch-dependency-coversion/README.md

@@ -31,6 +31,14 @@ dependencies = [
     # 0.0.0 is chosen at random and will be overwritten
     "my-dependency==0.0.0"
 ]
+# the dynamic entry must be present and the array must not be empty, otherwise hatch
+# will not invoke the plugin. however, something in dynamic cannot be in the rest of
+# the metadata, and only top-level keys can appear here - so if you did
+# dynamic = ['dependencies'], then it (a) would not be true since it's not all the
+# dependencies, just the versions of some of them and (b) you couldn't have a 
+# dependencies entry in the project table. so put an arbitrary string here, and the
+# name of the plugin is as good an arbitrary string as any.
+dynamic = ['dependency-coversioning']
 [tool.hatch.metadata.hooks.dependency-coversion]
 # this list contains the names of dependencies to override
 override-versions-of = ["my-dependency"]

hatch-dependency-coversion/changelog.d/1-new-project-added.md

@@ -0,0 +1,27 @@
+# Added new project hatch-dependency-coversion
+
+`hatch-dependency-coversion` is a plugin for [Hatch](https://github.com/pypa/hatch) that that allows you to rewrite the versions in selected dependency specifiers to be exactly the same as the current version of the project configured in `pyproject.toml`'s `[project]` table, requiring exact coversioning of those dependencies with the project. This is useful for projects that are developed in lockstep but distributed as independent python packages rather than as subcomponents of the same namespace package.
+
+To install `hatch-dependency-coversion`, list it as a PEP-517 dependency in your `pyproject.toml`'s `build-system` section alongside `hatchling` (you have to be using `hatchling` as your builder for this plugin to work):
+
+```
+[build-system]
+requires = ["hatchling", "hatch-dependency-coversion"]
+build-backend = "hatchling.build"
+```
+
+From there, you can configure the plugin by
+- adding a `dynamic` entry to project metadata (containing an arbitrary string, such as the plugin name - the `dynamic` entry just needs to exist for hatch to call the plugin:
+```toml
+[project]
+dynamic = ['hatch-dependency-coversion']
+```
+- The plugin name is `dependency-coversion`, and you set which dependency versions should be controlled with the config element `override-versions-of`, which should be an array of package names of dependencies from your `project.dependencies`:
+``` toml
+
+[project]
+dependencies = ['my-favorite-package==0.1.0']
+
+[tool.hatch.build.hooks.dependency-coversion]
+override-versions-of=['my-favorite-package']
+```

hatch-dependency-coversion/src/hatch_dependency_coversion/hooks.py

@@ -4,10 +4,11 @@
 
 """Registers a hatch metadata hook for altering dependency versions."""
 
+from typing import Type
 from hatchling.plugin import hookimpl
 from .metadata_hook import DependencyCoversionMetadataHook
 
 
 @hookimpl
-def hatch_register_metadata_hook():
+def hatch_register_metadata_hook() -> Type[DependencyCoversionMetadataHook]:
     return DependencyCoversionMetadataHook

hatch-dependency-coversion/src/hatch_dependency_coversion/metadata_hook.py

@@ -4,6 +4,7 @@
 
 """A metadata hook for hatchling that can force dependencies to be coversioned."""
 from __future__ import annotations
+import inspect
 from typing import Any
 
 from packaging.requirements import Requirement, SpecifierSet
@@ -14,6 +15,8 @@
 
 class DependencyCoversionMetadataHook(MetadataHookInterface):
     PLUGIN_NAME = _PLUGIN_NAME
+    root: str
+    config: dict
 
     def _maybe_update_dep(
         self, depspec: str, version: str, which_dependencies: list[str]
@@ -38,8 +41,23 @@ def _update_dependency_versions(
 
     def update(self, metadata: dict[str, Any]) -> None:
         """Update metadata for coversioning."""
+        # this is from https://github.com/flying-sheep/hatch-docstring-description/blob/main/src/hatch_docstring_description/read_description.py
+        # and would prevent surprise recursions, and if that author is worried about it then so am I
+        if ("update", __file__) in (
+            (frame.function, frame.filename) for frame in inspect.stack()[1:]
+        ):
+            return
+        if "override-versions-of" not in self.config:
+            return
+        if not isinstance(self.config["override-versions-of"], list):
+            raise RuntimeError(
+                "tool.hatch.metadata.hooks.dependency-coversion.override-versions-of must be an array of strings"
+            )
+        override_of: list[str] = self.config["override-versions-of"]
         metadata["dependencies"] = self._update_dependency_versions(
-            metadata.get("dependencies", []),
-            metadata["version"],
-            self.config.get("override-versions-of", []),
+            metadata.get("dependencies", []), metadata["version"], override_of
         )
+
+    def get_known_classifiers(self) -> list[str]:
+        """Dummy function that is part of the hook interface."""
+        return []

hatch-dependency-coversion/tests/conftest.py

@@ -29,6 +29,7 @@ def unconfigured_project(tmp_path: Path, static_requirements: list[str]) -> Path
         name = "unconfigured-project"
         version = "0.1.0"
         dependencies = [{','.join([f'"{requirement}"' for requirement in static_requirements])}]
+        dynamic = ['dependency-coversion']
         [tool.hatch.metadata.hooks.dependency-coversion]
         """
         )
@@ -52,6 +53,7 @@ def requests_zero_coversions_project(
         name = "zero-coversions-project"
         version = "0.1.0"
         dependencies = [{','.join([f'"{requirement}"' for requirement in static_requirements])}]
+        dynamic = ['dependency-coversion']
         [tool.hatch.metadata.hooks.dependency-coversion]
         override-versions-of=[]
         """
@@ -76,6 +78,7 @@ def requests_coversion_of_open_version_project(
         name = "coversion-of-open-version-project"
         version = "0.1.0"
         dependencies = [{','.join([f'"{requirement}"' for requirement in static_requirements])}]
+        dynamic = ['dependency-coversion']
         [tool.hatch.metadata.hooks.dependency-coversion]
         override-versions-of=["dependency1"]
         """
@@ -100,6 +103,7 @@ def requests_coversion_of_specified_version_project(
         name = "coversion-of-specified-version-project"
         version = "0.1.0"
         dependencies = [{','.join([f'"{requirement}"' for requirement in static_requirements])}]
+        dynamic = ['dependency-coversion']
         [tool.hatch.metadata.hooks.dependency-coversion]
         override-versions-of=["dependency2"]
         """
@@ -124,6 +128,7 @@ def requests_coversion_of_marked_version_project(
         name = "coversion-of-marked-version-project"
         version = "0.1.0"
         dependencies = [{','.join([f'"{requirement}"' for requirement in static_requirements])}]
+        dynamic = ['dependency-coversion']
         [tool.hatch.metadata.hooks.dependency-coversion]
         override-versions-of=["dependency3"]
         """
@@ -146,6 +151,7 @@ def requests_multiple_project(tmp_path: Path, static_requirements: list[str]) ->
         name = "coversion-of-multiple-project"
         version = "0.1.0"
         dependencies = [{','.join([f'"{requirement}"' for requirement in static_requirements])}]
+        dynamic = ['dependency-coversion']
         [tool.hatch.metadata.hooks.dependency-coversion]
         override-versions-of=["dependency2", "dependency1", "dependency3"]
         """