switch to dep groups (PEP 735)

.github/workflows/main.yml

@@ -18,10 +18,10 @@ jobs:
         python-version: ["3.10", "3.13"]
 
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v4
+      - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v4
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v5
+        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v5
         with:
           python-version: ${{ matrix.python-version }}
 

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+### Changed
+* Migrate from `optional-dependencies` to PEP 735 `dependency-groups` for hatch environments (@mathematicalmichael, #145)
+  * All development dependencies now use the standard `[dependency-groups]` table instead of `[project.optional-dependencies]`
+  * Hatch environments now use `dependency-groups = [...]` instead of `features = [...]`
+  * This change requires Hatch 1.16+ (which supports dependency groups in builder and non-dev environments)
+  * When `use_hatch_envs=False`, optional-dependencies are still used for backward compatibility
+
 ## [v0.6.8]
 
 ### Fixed

template/pyproject.toml.jinja

@@ -69,21 +69,18 @@ Documentation = "{{ dev_platform_url }}/{{ username }}/{{ project_slug }}/blob/m
 {%- endif %}
 Download = "https://pypi.org/project/{{ project_slug }}/#files"
 
+{%- if not use_hatch_envs %}
 [project.optional-dependencies]
-# The groups below should be in the [development-groups] table
-# They are here now because hatch hasn't released support for them but plans to
-# in Mid November 2025.
+# When not using hatch environments, we keep optional-dependencies for backward compatibility
 dev = [
     "hatch",
     "pre-commit",
-    {%- if not use_hatch_envs %}
     "{{ package_name }}[
         {%- if documentation!="" %}docs,{% endif -%}
         {%- if use_test %}tests,{% endif -%}
         {%- if use_lint %}style,{% endif -%}
         {%- if use_types %}types,{% endif -%}
     audit]",
-    {%- endif %}
 ]
 
 docs = [
@@ -104,7 +101,6 @@ docs = [
 
 build = [
     "pip-audit",
-    "twine",
 ]
 
 {%- if use_test %}
@@ -129,6 +125,67 @@ types = [
     "mypy",
 ]
 {%- endif %}
+{%- endif %}
+
+{%- if use_hatch_envs %}
+################################################################################
+# Dependency Groups (PEP 735)
+################################################################################
+
+[dependency-groups]
+# Development tools that are used across multiple environments
+dev = [
+    "hatch",
+    "pre-commit",
+]
+
+{%- if documentation != "no" %}
+docs = [
+{%- if documentation == "sphinx" %}
+    "sphinx~=8.0",
+    "myst-parser>=4.0",
+    "pydata-sphinx-theme~=0.16",
+    "sphinx-autobuild>=2024.10.3",
+    "sphinx-autoapi>=3.6.0",
+    "sphinx_design>=0.6.1",
+    "sphinx-copybutton>=0.5.2",
+{%- elif documentation == "mkdocs" %}
+    "mkdocs-material ~=9.5",
+    "mkdocstrings[python] ~=0.24",
+    "mkdocs-awesome-pages-plugin ~=2.9",
+{% endif %}
+]
+
+{%- endif %}
+build = [
+    "pip-audit",
+    "twine",
+]
+
+{%- if use_test %}
+tests = [
+    "pytest",
+    "pytest-cov",
+    "pytest-raises",
+    "pytest-randomly",
+    "pytest-xdist",
+]
+
+{%- endif %}
+{%- if use_lint %}
+style = [
+    "pydoclint",
+    "ruff",
+]
+
+{%- endif %}
+{%- if use_types %}
+types = [
+    "mypy",
+]
+
+{%- endif %}
+{%- endif %}
 
 
 ################################################################################
@@ -276,9 +333,16 @@ installer = "uv"
 # This table installs the tools you need to test and build your package
 [tool.hatch.envs.build]
 description = """Test the installation the package."""
-features = [
+builder = true
+dependency-groups = [
     "build",
 ]
+# Explicit dependencies are required as a workaround for dependency-groups
+# not being installed in builder environments (see https://github.com/pypa/hatch/issues/2152)
+# This ensures twine is available when scripts run
+dependencies = [
+    "twine",
+]
 detached = true
 
 # This table installs created the command hatch run install:check which will build and check your package.
@@ -293,7 +357,7 @@ check = [
 {%- if use_test %}
 [tool.hatch.envs.test]
 description = """Run the test suite."""
-features = [
+dependency-groups = [
     "tests",
 ]
 
@@ -309,8 +373,8 @@ run = "pytest {args:--cov={{ package_name }} --cov-report=term-missing --cov-rep
 # This sets up a hatch environment with associated dependencies that need to be installed
 [tool.hatch.envs.docs]
 description = """Build or serve the documentation."""
-# Install optional dependency test for docs
-features = [
+# Install dependency group for docs
+dependency-groups = [
     "docs",
 ]
 
@@ -333,7 +397,7 @@ serve = ["sphinx-autobuild docs --watch src/{{ package_name }} {args:-b html doc
 
 [tool.hatch.envs.style]
 description = """Check the code and documentation style."""
-features = [
+dependency-groups = [
     "style",
 ]
 detached = true
@@ -349,7 +413,7 @@ check = ["docstrings", "code"]
 
 [tool.hatch.envs.audit]
 description = """Check dependencies for security vulnerabilities."""
-features = [
+dependency-groups = [
     "build",
 ]
 
@@ -361,7 +425,7 @@ check = ["pip-audit"]
 #--------------- Typing ---------------#
 [tool.hatch.envs.types]
 description = """Check the static types of the codebase."""
-features = ["types"]
+dependency-groups = ["types"]
 
 [tool.hatch.envs.types.scripts]
 check = "mypy src/{{ package_name }}"

tests/test_template_init.py

@@ -166,10 +166,14 @@ def test_template_suite(
     generated: Callable[..., Path],
 ) -> None:
     """Expect that the test suite passes for the initialized template."""
-    project_dir = generated()
+    # Explicitly enable hatch environments to ensure build environment exists
+    project_dir = generated(use_hatch_envs=True)
 
     # Run the local test suite.
-    run_command("hatch build --clean", project_dir)
+    # Use hatch run build:check to ensure we use the build environment
+    # (Hatch 1.16+ requires builder environments to have builder=true)
+    # This runs "hatch build --clean" and "twine check" in the build environment
+    run_command("hatch run build:check", project_dir)
     run_command(f"hatch run +py={sys.version_info.major}.{sys.version_info.minor} test:run", project_dir)
     run_command("hatch run style:check", project_dir)
 
@@ -254,3 +258,50 @@ def test_non_hatch_deps(
     if documentation != "no":
         assert "docs" in optional_deps
         assert any(dep.startswith(documentation) for dep in optional_deps["docs"])
+
+
+def test_hatch_deps_groups(
+    documentation: str,
+    generated: Callable[..., Path],
+) -> None:
+    """When using hatch environments, we should use dependency-groups (PEP 735)."""
+    project = generated(
+        use_hatch_envs=True,
+        use_lint=True,
+        use_types=True,
+        use_test=True,
+        use_git=False,
+        documentation=documentation,
+    )
+
+    pyproject_file = project / "pyproject.toml"
+    with pyproject_file.open("rb") as pfile:
+        pyproject = tomllib.load(pfile)
+
+    # validate pyproject.toml file if present
+    validator_api.Validator()(pyproject)
+
+    # When using hatch_envs, dependencies should be in dependency-groups, not optional-dependencies
+    assert "dependency-groups" in pyproject
+    dep_groups = pyproject["dependency-groups"]
+
+    # Check that expected groups exist
+    groups = ("dev", "tests", "style", "types", "build")
+    assert all(group in dep_groups for group in groups)
+
+    # Check that docs group exists if documentation is enabled
+    if documentation != "no":
+        assert "docs" in dep_groups
+        assert any(dep.startswith(documentation) for dep in dep_groups["docs"])
+
+    # Verify that hatch environments use dependency-groups
+    if "tool" in pyproject and "hatch" in pyproject["tool"]:
+        hatch_envs = pyproject["tool"]["hatch"].get("envs", {})
+        for env_name, env_config in hatch_envs.items():
+            if env_name != "default" and isinstance(env_config, dict):
+                # Check that environments use dependency-groups instead of features
+                if "dependency-groups" in env_config:
+                    # Verify the dependency-groups reference valid groups
+                    env_dep_groups = env_config["dependency-groups"]
+                    for group in env_dep_groups:
+                        assert group in dep_groups, f"Environment {env_name} references unknown dependency group: {group}"