Ensure

Warnings

• gotcha When using `ensure_annotations` with multiprocessing, you might encounter `PicklingError` due to issues with pickling decorated functions. This is a known limitation when dealing with annotation enforcement across process boundaries.
  Fix: Avoid using `@ensure_annotations` on functions that are passed directly to `multiprocessing` pools or other serialization mechanisms. Consider performing validation at the entry point of the worker process instead, or use alternative validation methods for multiprocessing-sensitive code.
• gotcha Unlike Python's built-in `assert` statement, `ensure` is designed to be production-safe and will not have its checks disabled when Python is run with the `-O` (optimization) flag. If you intend for checks to be removable in optimized builds, `ensure` is not the right tool for those specific checks.
  Fix: Be aware of this distinction when choosing between `assert` and `ensure`. If certain runtime checks are performance-critical and should only run in debug environments, use Python's native `assert`.
• breaking Older versions (pre-0.8.1) of `ensure` had compatibility issues with the `collections.abc` module due to changes in Python's standard library, particularly impacting type checking for abstract base classes. This could lead to `ImportError` or unexpected behavior.
  Fix: Upgrade to `ensure` version 0.8.1 or later. This issue was resolved in versions 0.8.1 and 0.8.2. Ensure your Python environment is compatible with the library's `requires_python >=3.6`.
• gotcha Python 3.12 deprecated `unittest.TestCase.assertRaisesRegexp` in favor of `unittest.TestCase.assertRaisesRegex`. Although `ensure` updated its internal usage in v1.0.4, older versions of `ensure` might experience compatibility issues or warnings when run with Python 3.12, particularly in tests that internally rely on the `unittest` module's regex assertion methods.
  Fix: Update to `ensure` version 1.0.4 or newer to ensure full compatibility and avoid deprecation warnings with Python 3.12.

Install

• pip install ensure Install stable version

Imports

• ensure

  from ensure import ensure

  The primary entry point for assertion chaining.
• check

  from ensure import check

  Used for validations that raise a custom exception or a specific type, rather than an EnsureError.
• ensure_annotations

  from ensure import ensure_annotations

  Decorator for enforcing function signature type annotations (Python 3 only).

Quickstart

This quickstart demonstrates core `ensure` functionalities: basic type and value assertions, chained property checks, function call validation (including expected return values and raised exceptions), and the use of `check` for custom exception types. It also shows how to apply `ensure_annotations` for runtime type checking in functions.

from ensure import ensure, check

# Basic assertions
ensure(1).is_an(int)
ensure("hello").is_a(str).has_length(5)
ensure([1, 2, 3]).contains(1).and_also.does_not_contain(4)

# Chained assertions
ensure({"a": 1, "b": 2}).has_key("a").whose_value.is_an(int)

# Function call assertions
ensure(int).called_with("1100101", base=2).returns(101)
ensure(dict).called_with(1, 2).raises(TypeError)

# Using 'check' for custom exception handling
try:
    check(1).is_a(float).or_raise(ValueError, "Value must be a float, got {value}")
except ValueError as e:
    print(f"Caught expected error: {e}")

# Type annotation enforcement (Python 3)
from ensure import ensure_annotations, EnsureError

@ensure_annotations
def add_numbers(a: int, b: int) -> int:
    return a + b

print(f"2 + 3 = {add_numbers(2, 3)}")

# This would typically raise an EnsureError
try:
    add_numbers("2", 3)
except EnsureError as e:
    print(f"Caught expected annotation error: {e}")