requireit 0.8.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 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_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_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

• 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.

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.8.0 (2026-04-14)

Features

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

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