Metadata-Version: 2.4
Name: pyneedy
Version: 1.0.0
Summary: A minimal library for writing tests with optional dependencies.
Project-URL: Homepage, https://pytooling.gitlab.io/needy/
Project-URL: Repository, https://gitlab.com/pytooling/needy
Project-URL: Documentation, https://pytooling.gitlab.io/needy/
Project-URL: Bug Tracker, https://gitlab.com/pytooling/needy/-/issues
Project-URL: Changelog, https://gitlab.com/pytooling/needy/-/blob/main/CHANGELOG.md
Author-email: Zurab Mujirishvili <zurab.mu@gmail.com>
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# Needy

A minimal library for writing tests with optional dependencies.

## Installation

Python 3.11+ is required.

```bash
pip install pyneedy
```

## Quick Start

Define "probes" for the optional dependencies you want to use, e.g. JAX.

```python
class check:
    @staticmethod
    def jax() -> None:
        # A probe just tries to import the optional dependency.
        import jax as jax
```

Then wrap imports related to the optional dependency in a `needs.modules(...)` scope like this:

```python
from needy import needs

from pytest import mark

with needs.modules(check.jax):
    import jax.numpy as jnp

@mark.parametrize(
    ["array", "expected_sum"],
    [
        (
            array := jnp.array([1.0, 2.0]),
            expected_sum := 3.0
        ),
        (
            array := jnp.array([]),
            expected_sum := 0.0
        )
    ]
)
def test_that_a_sum_is_computed(array, expected_sum) -> None:
    assert array.sum() == expected_sum
```

If `jax` is installed, the imports inside the `with` block resolve normally. If it isn't, every missing import inside the block is replaced with a proxy, and only the first real use of the missing modules will raise an error.

See the [docs](https://pytooling.gitlab.io/needy/) for more.

## Development

### Prerequisites

- Python >= 3.11
- [uv](https://docs.astral.sh/uv/) (recommended) or pip
- [just](https://github.com/casey/just) (optional, for convenience)

### Getting Started

1. Clone the repository:

   ```bash
   git clone https://gitlab.com/pytooling/needy.git
   cd needy
   ```

1. Create a virtual environment and install dependencies:

   ```bash
   uv sync
   ```

1. Install pre-commit hooks:

   ```bash
   uv run pre-commit install
   ```

### Running Checks

```bash
just check
```

Or manually:

```bash
uv run ruff check --fix && uv run ruff format && uv run pyright && uv run pytest
```

## License

This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.
