https://github.com/galacticdynamics/optional_dependencies
Construct Checks for Optional Dependencies
https://github.com/galacticdynamics/optional_dependencies
Last synced: about 1 year ago
JSON representation
Construct Checks for Optional Dependencies
- Host: GitHub
- URL: https://github.com/galacticdynamics/optional_dependencies
- Owner: GalacticDynamics
- License: mit
- Created: 2024-06-11T15:55:04.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-04-07T19:51:15.000Z (about 1 year ago)
- Last Synced: 2025-04-07T20:41:09.803Z (about 1 year ago)
- Language: Python
- Homepage:
- Size: 48.8 KB
- Stars: 2
- Watchers: 2
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
optional_dependencies
Construct Checks for Optional Dependencies
## Installation
[![PyPI version][pypi-version]][pypi-link]
[![PyPI platforms][pypi-platforms]][pypi-link]
```bash
pip install optional_dependencies
```
## Documentation
### High-Level API
This package allows for easy construction of checks for optional dependencies.
As every Python project can have its own unique set of optional dependencies,
`optional_dependencies` provides the [`enum.Enum`][Enum-link] base class
`OptionalDependencyEnum` for enumerating the optional dependencies.
A constructed `OptionalDependencyEnum` [`enum.Enum`][Enum-link] has members that
are the package names with values that are either a
[`packaging.Version`][Version-link] or a `NOT_INSTALLED` sentinel value.
As an example:
```python
# Note that `auto` is a convenience re-export of enum.auto
from optional_dependencies import OptionalDependencyEnum, auto
class OptDeps(OptionalDependencyEnum):
PACKAGING = auto()
THIS_IS_NOT_INSTALLED = auto()
OptDeps.PACKAGING
# >
OptDeps.PACKAGING.installed
# True
OptDeps.PACKAGING.version
#
OptDeps.THIS_IS_NOT_INSTALLED
# >
```
`enum.auto` on a `OptionalDependencyEnum` passes version parsing to
[`packaging.utils.canonicalize_name`](https://packaging.pypa.io/en/stable/utils.html#packaging.utils.canonicalize_name)
then
[`importlib.metadata.version`](https://docs.python.org/3/library/importlib.metadata.html)
then [`packaging.version.parse`][Version-link]. If the package cannot be found
then it is considered `InstalledState.NOT_INSTALLED`
`InstalledState.NOT_INSTALLED` is an [`enum.Enum`][Enum-link] member that has a
truthy value of `False`. This can be useful for boolean checks, as
[`packaging.Version`][Version-link] always has a truthy value of `True`.
```python
if not OptDeps.THIS_IS_NOT_INSTALLED:
print("NOT_INSTALLED has a truthy value of False")
# NOT_INSTALLED has a truthy value of False
if OptDeps.PACKAGING: # truthy value of `True`
print(OptDeps.PACKAGING)
# OptDeps.PACKAGING
```
### Low-Level API
Sometimes the high-level API is insufficient to determine whether an optional
dependency is present. For example, this can sometimes happen with compiled
packages, where the package appears to be installed, but something is wrong. In
these cases you can customize the enum members using the low-level API.
The low-level functions are:
- `optional_dependencies.utils.is_installed(pkg_name: str, /) -> bool`: a
regularized form of
[`importlib.util.find_spec`](https://docs.python.org/3/library/importlib.html#importlib.util.find_spec).
- `optional_dependencies.utils.get_version(pkg_name: str, /) -> Version | Literal[InstalledState.NOT_INSTALLED]`:
for getting the [`packaging.Version`][Version-link] of a package if it is
installed, or returning `NOT_INSTALLED` otherwise.
- `optional_dependencies.utils.chain_checks(version: Version, /, *checks: bool)`:
for chaining checks together and ensuring the returned value is still a
[`packaging.Version`][Version-link] or `NOT_INSTALLED`.
As a pseudo-code example of a package with c-compiled code that :
```python
from optional_dependencies.utils import is_installed, get_version, chain_checks
# A subpackage needs to be checked.
chain_checks(get_version("package1"), is_installed("package1.subpackage"))
#
# This package is not installed correctly
chain_checks(get_version("package2"), is_installed("package2.subpackage"))
#
```
The low-level API can be used with `OptionalDependencyEnum`
```python
class OptDeps(OptionalDependencyEnum):
PACKAGING = auto()
THIS_IS_NOT_INSTALLED = chain_checks(
get_version("package2"), is_installed("package2.subpackage")
)
```
## Citation
[![DOI][zenodo-badge]][zenodo-link]
If you found this library to be useful and want to support the development and
maintenance of lower-level code libraries for the scientific community, please
consider citing this work.
## Development
[![codecov][codecov-badge]][codecov-link]
[![Actions Status][actions-badge]][actions-link]
We welcome contributions!
[Enum-link]: https://docs.python.org/3/library/enum.html
[Version-link]: https://packaging.pypa.io/en/stable/version.html#packaging.version.Version
[actions-badge]: https://github.com/GalacticDynamics/optional_dependencies/workflows/CI/badge.svg
[actions-link]: https://github.com/GalacticDynamics/optional_dependencies/actions
[codecov-badge]: https://codecov.io/gh/GalacticDynamics/optional_dependencies/graph/badge.svg
[codecov-link]: https://codecov.io/gh/GalacticDynamics/optional_dependencies
[pypi-link]: https://pypi.org/project/optional_dependencies/
[pypi-platforms]: https://img.shields.io/pypi/pyversions/optional_dependencies
[pypi-version]: https://img.shields.io/pypi/v/optional_dependencies
[zenodo-badge]: https://zenodo.org/badge/DOI/10.5281/zenodo.13738124.svg
[zenodo-link]: https://zenodo.org/doi/10.5281/zenodo.13738123