hatchling-autoextras-hook 0.1.0

Hatchling metadata hook to generate all extras

hatchling-autoextras-hook

Hatchling metadata hook to automatically generate an all extra that combines all optional dependencies.

Overview

This package provides a Hatchling metadata hook that automatically creates an all extra in your project's optional dependencies. The all extra will contain all dependencies from all other extras, making it easy for users to install all optional features at once.

Installation

Add this package as a build dependency in your pyproject.toml:

[build-system]
requires = ["hatchling>=1.18.0", "hatchling-autoextras-hook"]
build-backend = "hatchling.build"

Usage

Enable the hook in your pyproject.toml:

[tool.hatch.metadata.hooks.autoextras]

Important: Hatchling metadata hooks are only triggered when there is at least one dynamic field in your project metadata. If you don't already have any dynamic fields, you can add version as a dynamic field:

[project]
name = "your-package"
dynamic = ["version"]

[tool.hatch.version]
path = "src/your_package/__init__.py"

Then add __version__ = "x.y.z" to your __init__.py file.

Example

Given this configuration:

[build-system]
requires = ["hatchling>=1.18.0", "hatchling-autoextras-hook"]
build-backend = "hatchling.build"

[project]
name = "my-package"
dynamic = ["version"]

[project.optional-dependencies]
dev = ["pytest>=7.0", "black>=22.0"]
docs = ["sphinx>=5.0", "sphinx-rtd-theme>=1.0"]
typing = ["mypy>=1.0"]

[tool.hatch.version]
path = "src/my_package/__init__.py"

[tool.hatch.metadata.hooks.autoextras]

The hook will automatically generate an all extra combining all dependencies:

[project.optional-dependencies]
all = [
    "black>=22.0",
    "mypy>=1.0",
    "pytest>=7.0",
    "sphinx-rtd-theme>=1.0",
    "sphinx>=5.0",
]
# ... dev, docs, typing remain unchanged

Users can then install all optional dependencies with:

pip install your-package[all]

Features

• Automatically combines all optional dependencies
• Removes duplicates across extras
• Sorts dependencies alphabetically for consistency
• Works seamlessly with the Hatchling build system
• Zero configuration required - just enable the hook
• Compatible with all Hatchling build targets (wheel, sdist)

Configuration

The hook requires minimal configuration. Simply add it to your pyproject.toml:

[tool.hatch.metadata.hooks.autoextras]

Currently, the hook does not support any additional configuration options. It automatically:

• Creates an all extra containing all dependencies from all other extras
• Excludes any pre-existing all extra from being included in the new all extra
• Maintains all original extras unchanged

Advanced Usage

Excluding the Hook from Certain Extras

If you want to manually manage your all extra or prevent certain extras from being included, you can work around this by using a different extra name (like all-deps) and then creating your own all extra manually.

Using with Other Metadata Hooks

This hook is compatible with other Hatchling metadata hooks. They will run in the order specified in your configuration.

Troubleshooting

Hook Not Triggering

Problem: The all extra is not being generated.

Solutions:

1. Ensure you have at least one dynamic field in your [project] section:

   [project]
   dynamic = ["version"]
   

   Hatchling metadata hooks only run when there are dynamic fields.

2. Verify the hook is properly registered in your [build-system]:

   [build-system]
   requires = ["hatchling>=1.18.0", "hatchling-autoextras-hook"]
   

3. Check that the hook configuration exists:

   [tool.hatch.metadata.hooks.autoextras]
   

all Extra Missing Dependencies

Problem: Some dependencies are missing from the generated all extra.

Solution: Ensure all your extras are defined in [project.optional-dependencies]. The hook only processes extras defined there.

Build Failures

Problem: Build fails with errors related to the hook.

Solutions:

1. Verify you're using Hatchling >= 1.18.0
2. Check that your pyproject.toml syntax is correct
3. Try building with verbose output: python -m build -v

FAQ

Q: Will this hook override my manually defined all extra?

A: Yes, if you have a manually defined all extra in your [project.optional-dependencies], it will be replaced with the auto-generated one. The hook regenerates the all extra from all other extras each time the build runs.

Q: Can I exclude specific extras from being included in all?

A: Not currently. The hook includes all extras by default. If you need this functionality, please open a feature request on GitHub.

Q: Does this work with dependency groups (PEP 735)?

A: This hook specifically works with optional dependencies defined in [project.optional-dependencies]. It does not process dependency groups defined in [dependency-groups] as those are not part of the package metadata.

Q: Will this slow down my build process?

A: No, the performance impact is negligible. The hook simply collects and sorts dependency strings, which is a fast operation even for projects with many extras.

Q: Can I use this with Poetry or PDM?

A: This hook is specifically designed for Hatchling. It won't work with Poetry or PDM's build systems. Those tools have their own mechanisms for managing extras.

Q: How do I verify the hook is working?

A: Build your package and inspect the generated wheel's metadata:

python -m build
unzip -p dist/your_package-*.whl '*/METADATA' | grep -A 10 "Provides-Extra: all"

Q: Does this hook modify my source files?

A: No, the hook only modifies the package metadata during the build process. Your source files, including pyproject.toml, remain unchanged.

Development

This project uses uv for dependency management.

Dependencies

batcharray	hatchling	python
main	>=1.18,<2.0	>=3.10
0.1.0	>=1.18,<2.0	>=3.10
0.0.2	>=1.18,<2.0	>=3.10,<3.15
0.0.1	>=1.18,<2.0	>=3.10,<3.15

Contributing

Please check the instructions in CONTRIBUTING.md.

Suggestions and Communication

Everyone is welcome to contribute to the community. If you have any questions or suggestions, you can submit Github Issues. We will reply to you as soon as possible. Thank you very much.

API stability

:warning: While hatchling-autoextras-hook is in development stage, no API is guaranteed to be stable from one release to the next. In fact, it is very likely that the API will change multiple times before a stable 1.0.0 release. In practice, this means that upgrading hatchling-autoextras-hook to a new version will possibly break any code that was using the old version of hatchling-autoextras-hook.

Security

For information about security policies and how to report vulnerabilities, please see our Security Policy.

License

hatchling-autoextras-hook is licensed under BSD 3-Clause "New" or "Revised" license available in LICENSE file.