Metadata-Version: 2.4
Name: optional-dependency-hint
Version: 0.1.0
Summary: Print a hint when one of optional dependencies of a package not found
Author-email: Jiaqi Guo <gjq@tongji.edu.cn>
License-Expression: MIT
Project-URL: Repository, https://github.com/GjQAQ/PyOptionalDependencyHint
Keywords: optional-dependency,import,dependency
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Optional Dependency Hint

This package gives a clearer `ImportError` message when an
optional dependency is missing, including an install hint like
`pip install mypkg[extra]`.

## Installation

```bash
pip install optional-dependency-hint
```

## Requirements

- Python `>=3.8`

## Quick Start

```python
import optdep

# Declare `tqdm` as an optional dependency of `mypkg`
# and tell users how to install it.
optdep.add("tqdm", "mypkg", "progbar")

import tqdm
# If `tqdm` is missing:
# ImportError: Optional dependency tqdm is not installed.
# You may install it with mypkg by: `pip install mypkg[progbar]`
```

If you only want the default message without install instructions:

```python
import optdep

optdep.add("tqdm")

import tqdm
# If `tqdm` is missing:
# ImportError: Optional dependency tqdm is not installed.
```

## API

### `optdep.add(module_name, this_pkg_name=None, extra=None, exist_behavior="skip")`

- `module_name` (`str`): target optional dependency module name.
- `this_pkg_name` (`str | None`): your package name shown in hint message.
- `extra` (`str | None`): extra name shown as `pkg[extra]`.
- `exist_behavior` (`"skip" | "overwrite" | "error"`): behavior when the module
  was already registered.

## `exist_behavior` semantics

- `skip` (default): keep old registration.
- `overwrite`: replace old registration with the new one.
- `error`: raise `RuntimeError`.

## Notes

- Call `optdep.add(...)` before importing the optional module.
- This package registers an import hook via `sys.meta_path` at import time.

## License

MIT
