Metadata-Version: 2.4
Name: requireit
Version: 0.3.0
Summary: Tiny runtime validators for explicit precondition checks
Author-email: Eric Hutton <mcflugen@gmail.com>
Maintainer-email: Eric Hutton <mcflugen@gmail.com>
License-Expression: MIT
Project-URL: homepage, https://github.com/mcflugen/requireit
Project-URL: documentation, https://github.com/mcflugen/requireit/blob/main/README.md
Project-URL: repository, https://github.com/mcflugen/requireit
Project-URL: changelog, https://github.com/mcflugen/requireit/blob/main/CHANGES.md
Keywords: preconditions,runtime-checks,utilities,validation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: numpy
Provides-Extra: dev
Requires-Dist: nox; extra == "dev"
Dynamic: license-file

# requireit

**Tiny, numpy-aware runtime validators for explicit precondition checks.**

`requireit` provides a small collection of lightweight helper functions such as
`require_positive`, `require_between`, and `require_array` for validating values
and arrays at runtime.

It is intentionally minimal and dependency-light (*numpy* only).

## Why `requireit`?

* **Explicit** – reads clearly
* **numpy-aware** – works correctly with scalars *and* arrays
* **Fail-fast** – raises immediately with clear error messages
* **Lightweight** – just a bunch of small functions
* **Reusable** – avoids copy-pasted validation code across projects

```python
from requireit import require_one_of
from requireit import require_positive

require_positive(dt)
require_one_of(method, allowed={"foo", "bar"})
```

## Design principles

* Prefer small, single-purpose functions
* Raise standard exceptions (`ValidationError`)
* Never coerce or "fix" invalid inputs
* Validate *all* elements for array-like inputs
* Keep the public API small

## Non-goals

`requireit` is **not**:

* a schema or data-modeling system
* a replacement for static typing
* a validation framework
* a substitute for unit tests
* a coercion or parsing library

If you need structured validation, transformations, or user-facing error
aggregation, you probably want something heavier.

## Installation

```bash
pip install requireit
```

## API overview

All validators:

* return the original value/array on success
* raise `ValidationError` on failure

### Membership validation

```python
require_one_of(value, *, allowed)
```

Validate that a value is one of a set of allowed values.

```python
require_one_of("foo", allowed=("foo", "bar"))  # ok, returns "foo"
require_one_of("baz", allowed=("foo", "bar"))  # raises ValidationError
```

### Range validation

```python
require_between(
    value,
    a_min=None,
    a_max=None,
    *,
    inclusive_min=True,
    inclusive_max=True,
)
```

Validate that a scalar or array lies within specified bounds.

* Bounds may be inclusive or strict
* Validation fails if **any element** violates the constraint

```python
require_between([0, 1], a_min=0.0) # ok, returns [0, 1]
require_between([0, 1], a_min=0.0, inclusive_min=False) # raises
```

### Sign-based helpers

Convenience wrappers around `require_between`:

```python
require_positive(value)  # > 0
require_nonnegative(value)  # >= 0
require_negative(value)  # < 0
require_nonpositive(value)  # <= 0
```

All accept scalars or array-like inputs.


### Array validation

```python
require_array(
    array,
    *,
    dtype=None,
    shape=None,
    writable=None,
    contiguous=None,
)
```

Validate NumPy array properties without copying or modifying the array.

```python
require_array(x, dtype=np.float64, shape=(100,))
require_array(x, writable=True, contiguous=True)
```

Checks are applied only if the corresponding keyword is provided.


## Errors

All validation failures raise:

```python
requireit.ValidationError
```

This allows callers to catch validation failures distinctly from other errors.


## Contributing

This project is intentionally small.

Contributions should preserve:

* minimal surface area
* explicit semantics
* no additional dependencies

If a proposed change needs much explanation, it probably doesn’t belong here.

# Credits

## Development Leads

- [Eric Hutton](https://github.com/mcflugen)

# Release Notes

## 0.3.0 (2026-03-23)

### Features

* Added `require_not_one_of` validator to ensure a value is not in a forbidden set
  [#15](https://github.com/mcflugen/requireit/issues/15)
* Added length validators to check that an object’s length is exactly, at most, or at least
  a given value [#16](https://github.com/mcflugen/requireit/issues/16)
* Added `require_length_between` validator to check that an object’s length is within
  a specified range [#19](https://github.com/mcflugen/requireit/issues/19)
* Added `require_contains` validator to ensure a collection contains required values
  [#21](https://github.com/mcflugen/requireit/issues/21)
* Added `import_package` validator to check for and import a package
  [#22](https://github.com/mcflugen/requireit/issues/22)
* Added `argparse_type` to allow *requireit* validators to be used as
  `argparse` `type=` callables
  [#17](https://github.com/mcflugen/requireit/issues/17)

### Changes

* Renamed length validators for consistency:
  `require_length_is` → `require_length`,
  `require_length_is_at_least` → `require_length_at_least`,
  `require_length_is_at_most` → `require_length_at_most`
  [#20](https://github.com/mcflugen/requireit/issues/20)

### Tests

* Added unit tests to verify that validators return the input value (not a copy)
  on success [#18](https://github.com/mcflugen/requireit/issues/18)


## 0.2.0 (2026-01-16)

- Standardized validation error messages [#8](https://github.com/mcflugen/requireit/issues/8)
- Renamed ``validate_array`` to ``require_array`` [#9](https://github.com/mcflugen/requireit/issues/9)
- Added optional ``name`` keyword to require functions to make error messages
  easier to read [#10](https://github.com/mcflugen/requireit/issues/10)
- Added new validator, ``require_path_string``, that checks if a value could be used
  as a file path [#11](https://github.com/mcflugen/requireit/issues/11)
- Added new validator, ``require_less_than``, that checks if one value is less than
  another [#12](https://github.com/mcflugen/requireit/issues/12)

## 0.1.0 (2026-01-12)

- Added documentation to the README [#1](https://github.com/mcflugen/requireit/issues/1)
- Added project metadata files [#2](https://github.com/mcflugen/requireit/issues/2)
- Added the `requireit` module [#3](https://github.com/mcflugen/requireit/issues/3)
- Added `pyproject.toml` file [#4](https://github.com/mcflugen/requireit/issues/4)
- Added `noxfile.py` file and linters [#5](https://github.com/mcflugen/requireit/issues/5)
- Added unit tests for `requireit` [#6](https://github.com/mcflugen/requireit/issues/6)
- Added GitHub Actions for CI [#7](https://github.com/mcflugen/requireit/issues/7)
