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, with no required dependencies. NumPy is optional for array validation.

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

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

pip install requireit

Numeric checks work with Python real scalars (including integers and floats) without NumPy. For array-like inputs and array validators, install the NumPy extra:

pip install 'requireit[numpy]'

API Summary

All validators:

• validate the first argument
• return the original value/array on success
• raise ValidationError on failure

Arrays

• require_array: Validate an array to satisfy requirements.
• require_dtype: Validate that an array has a required dtype or can be safely cast to it.
• require_like: Validate that an array has the same shape and/or dtype as another.
• require_ndim: Validate that an array has a specific number of dimensions.
• require_shape: Validate that an array has the specified shape.
• require_sorted: Validate that an array is sorted.

General

• require_contains: Require collection contains required values.
• require_contains_exactly: Require collection contains exactly the expected members.
• require_does_not_contain: Require collection contains no forbidden members.
• require_instance: Require value is an instance of one or more types.
• require_members: Require collection contains/does not contain members.
• require_none: Require value is None.
• require_not_none: Require value is not None.
• require_not_one_of: Require value is not contained in forbidden
• require_one_of: Require value is contained in allowed

Length

• require_length: Require len(value) == length
• require_length_at_least: Require len(value) >= length
• require_length_at_most: Require len(value) <= length
• require_length_between: Require len(value) falls within a specified range.

Numeric

Numeric validators accept real scalar values or, with NumPy installed, array-like values. For arrays, every element must satisfy the check. Bounds must be real scalars, including NumPy integer and floating scalars; array-valued bounds are not supported. In require_between, None means that a bound is omitted.

NaN input values raise ValidationError. NaN or non-real-scalar bounds raise ValueError.

• require_between: Validate that a value lies within a specified interval.
• require_greater_than: Require value > lower
• require_greater_than_or_equal: Require value >= lower
• require_less_than: Require value < upper
• require_less_than_or_equal: Require value <= upper
• require_negative: Require value < 0
• require_nonnegative: Require value >= 0
• require_nonpositive: Require value <= 0
• require_positive: Require value > 0

Paths

• require_path_string: Validate that a value is a string intended to be used as a path.

Command-line integration

• argparse_type: Adapt a requireit validator for use as an argparse type= callable.

import argparse
from requireit import argparse_type, require_positive


def parse_positive_int(value: str) -> int:
    return require_positive(int(value))


parser = argparse.ArgumentParser()
parser.add_argument("--count", type=argparse_type(parse_positive_int))

Converts ValidationError into argparse.ArgumentTypeError, allowing requireit validators to produce clean command-line error messages.

Errors

All validation failures raise ValidationError, which inherits from both RequireItError and the standard ValueError:

requireit.ValidationError

This allows callers to catch validation failures distinctly from other errors. To adapt validation errors to another exception type, use raise_as:

from requireit import raise_as
from requireit import require_positive

with raise_as(ValueError):
    require_positive(-1)

This raises:

ValueError: value must be positive

Useful when integrating requireit into APIs that already expose a specific exception type.

raise_as also accepts an optional note, attached to the raised exception via add_note:

with raise_as(ValueError, note="while parsing config.toml"):
    require_positive(-1)

To attach a note without changing the exception type, use add_note directly:

from requireit import add_note

with add_note("while parsing config.toml"):
    require_positive(-1)

This still raises ValidationError, with the note included in the traceback.

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

Release Notes

0.12.0 (2026-10-05)

Features

• Added require_members to combine required, allowed, and forbidden membership constraints. #63
• Added require_contains_exactly and require_does_not_contain. #63

Changes

• require_one_of and require_not_one_of no longer support unhashable values or unhashable items in allowed or forbidden. These inputs now raise TypeError. #64
• NumPy is now optional. Numeric validators support Python real scalars without NumPy, and array validation loads NumPy only when needed. Install requireit[numpy] to use array-like inputs or array validators. #62

Fixes

• require_between and the numeric validators built on it now reject NaN bounds with ValueError for both scalar and array inputs. #62

0.11.0 (2026-08-14)

Changes

• ValidationError now also inherits from the standard ValueError, allowing callers to handle requireit validation failures with other invalid values. #58
• require_length, require_length_at_least, require_length_at_most, and require_length_between now raise TypeError when passed a value that does not have a length. #58

0.10.1 (2026-08-13)

Fixes

• require_between, and the validators built on it (require_positive, require_negative, require_nonnegative, require_nonpositive, require_greater_than, require_greater_than_or_equal, require_less_than, and require_less_than_or_equal), now reject nan rather than silently treating it as satisfying the bound. #56

0.10.0 (2026-07-28)

Features

• Added require_like to validate that an array matches another array's shape and/or dtype. #46
• Added require_ndim to validate that an array has a required number of dimensions. #47
• Added require_none and require_not_none to validate that a value is, or is not, None. #50
• Added add_note context manager to attach a note to a RequireItError raised within its block, and a note keyword to raise_as to do the same when converting a ValidationError to another exception type. #51

Changes

• Dropped support for Python 3.11. #52

Fixes

• Fixed require_dtype error messages for NumPy dtype families such as np.floating. #45

Tests

• Cleaned up the parametrized require tests by collecting the failing and passing cases into named CHECKS_THAT_FAIL/CHECKS_THAT_PASS dicts. #49

0.9.0 (2026-04-23)

Features

• Added require_instance to check that a value is an instance of a type. #42

Fixes

• Fixed CI test jobs so macOS runners use the Python version selected by actions/setup-python. #43

0.8.0 (2026-04-14)

Features

• Added raise_as context manager to re-raise ValidationError as a user-specified exception type. #40

0.7.0 (2026-04-12)

Features

• Added require_sorted to check that values are sorted in ascending order. #35
• Added require_dtype to check that values have a given dtype or, optionally, can be safely cast to that dtype. #36

Changes

• Dropped support for Python 3.10. #37

0.6.0 (2026-04-01)

Features

• Allow the dtype keyword of require_array to accept numpy dtype families such as np.integer and np.floating in addition to exact dtypes. #32

0.5.0 (2026-03-28)

Features

• Extended require_array to allow flexible shape validation with support for wildcard dimensions (None or named axes). #29

0.4.0 (2026-03-27)

Features

• Added require_greater_than, require_greater_than_or_equal, and require_less_than_or_equal validators. #26

0.3.0 (2026-03-23)

Features

• Added require_not_one_of validator to ensure a value is not in a forbidden set #15
• Added length validators to check that an object’s length is exactly, at most, or at least a given value #16
• Added require_length_between validator to check that an object’s length is within a specified range #19
• Added require_contains validator to ensure a collection contains required values #21
• Added import_package validator to check for and import a package #22
• Added argparse_type to allow requireit validators to be used as argparse type= callables #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

Tests

• Added unit tests to verify that validators return the input value (not a copy) on success #18

0.2.0 (2026-01-16)

• Standardized validation error messages #8
• Renamed validate_array to require_array #9
• Added optional name keyword to require functions to make error messages easier to read #10
• Added new validator, require_path_string, that checks if a value could be used as a file path #11
• Added new validator, require_less_than, that checks if one value is less than another #12

0.1.0 (2026-01-12)

• Added documentation to the README #1
• Added project metadata files #2
• Added the requireit module #3
• Added pyproject.toml file #4
• Added noxfile.py file and linters #5
• Added unit tests for requireit #6
• Added GitHub Actions for CI #7