hatchling-autoextras-hook 0.1.3
Hatchling metadata hook to generate all extras
Requires Python: >=3.10
Keywords: automation, hatchling, hook, metadata, optional-dependencies

# hatchling-autoextras-hook

<p align="center">
    <a href="https://github.com/durandtibo/hatchling-autoextras-hook/actions/workflows/ci.yaml">
        <img alt="CI" src="https://github.com/durandtibo/hatchling-autoextras-hook/actions/workflows/ci.yaml/badge.svg">
    </a>
    <a href="https://github.com/durandtibo/hatchling-autoextras-hook/actions/workflows/nightly-tests.yaml">
        <img alt="Nightly Tests" src="https://github.com/durandtibo/hatchling-autoextras-hook/actions/workflows/nightly-tests.yaml/badge.svg">
    </a>
    <a href="https://github.com/durandtibo/hatchling-autoextras-hook/actions/workflows/nightly-package.yaml">
        <img alt="Nightly Package Tests" src="https://github.com/durandtibo/hatchling-autoextras-hook/actions/workflows/nightly-package.yaml/badge.svg">
    </a>
    <a href="https://codecov.io/gh/durandtibo/hatchling-autoextras-hook">
        <img alt="Codecov" src="https://codecov.io/gh/durandtibo/hatchling-autoextras-hook/branch/main/graph/badge.svg">
    </a>
    <br/>
    <a href="https://github.com/psf/black">
        <img  alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg">
    </a>
    <a href="https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings">
        <img  alt="Doc style: google" src="https://img.shields.io/badge/%20style-google-3666d6.svg">
    </a>
    <a href="https://github.com/astral-sh/ruff">
        <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff" style="max-width:100%;">
    </a>
    <a href="https://github.com/guilatrova/tryceratops">
        <img  alt="Doc style: google" src="https://img.shields.io/badge/try%2Fexcept%20style-tryceratops%20%F0%9F%A6%96%E2%9C%A8-black">
    </a>
    <br/>
    <a href="https://pypi.org/project/hatchling-autoextras-hook/">
        <img alt="PYPI version" src="https://img.shields.io/pypi/v/hatchling-autoextras-hook">
    </a>
    <a href="https://pypi.org/project/hatchling-autoextras-hook/">
        <img alt="Python" src="https://img.shields.io/pypi/pyversions/hatchling-autoextras-hook.svg">
    </a>
    <a href="https://opensource.org/licenses/BSD-3-Clause">
        <img alt="BSD-3-Clause" src="https://img.shields.io/pypi/l/hatchling-autoextras-hook">
    </a>
    <br/>
    <a href="https://pepy.tech/project/hatchling-autoextras-hook">
        <img  alt="Downloads" src="https://static.pepy.tech/badge/hatchling-autoextras-hook">
    </a>
    <a href="https://pepy.tech/project/hatchling-autoextras-hook">
        <img  alt="Monthly downloads" src="https://static.pepy.tech/badge/hatchling-autoextras-hook/month">
    </a>
    <br/>

</p>

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

## Overview

This package provides a [Hatchling](https://pypi.org/project/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`:

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

## Usage

Enable the hook in your `pyproject.toml`:

```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:

```toml
[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:

```toml
[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:

```toml
[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:

```bash
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`:

```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:
   ```toml
   [project]
   dynamic = ["version"]
   ```
   Hatchling metadata hooks only run when there are dynamic fields.

2. Verify the hook is properly registered in your `[build-system]`:
   ```toml
   [build-system]
   requires = ["hatchling>=1.18.0", "hatchling-autoextras-hook"]
   ```

3. Check that the hook configuration exists:
   ```toml
   [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:

```bash
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

| `hatchling-autoextras-hook` | `hatchling`   | `python`       |
|-----------------------------|---------------|----------------|
| `main`                      | `>=1.18,<2.0` | `>=3.10`       |
| `0.1.3`                     | `>=1.18,<2.0` | `>=3.10`       |
| `0.1.2`                     | `>=1.18,<2.0` | `>=3.10`       |
| `0.1.1`                     | `>=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](.github/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](https://github.com/durandtibo/hatchling-autoextras-hook/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](SECURITY.md).

## License

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