requireit 0.4.0

Tiny runtime validators for explicit precondition checks

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

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

API overview

All validators:

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

Membership validation

require_one_of(value, *, allowed)

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

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

Range validation

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

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:

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

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

Validate NumPy array properties without copying or modifying the array.

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:

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

Release Notes

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