Install & Compatibility
Where this runs
tested against v1.0.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.158s · 18MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.132s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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).
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}")
Debug
Known issues
gotchaWhen 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.fixAvoid 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.
affects: >=1.0.0
gotchaUnlike 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.fixBe 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`.
affects: All versions
breakingOlder 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.fixUpgrade 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`.
affects: <0.8.1
gotchaPython 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.fixUpdate to `ensure` version 1.0.4 or newer to ensure full compatibility and avoid deprecation warnings with Python 3.12.
affects: <1.0.4 (when used with Python 3.12)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'ensure'
The `ensure` library has not been installed in the current Python environment, or the environment is not correctly activated.
fixInstall the library using pip: `pip install ensure`
AttributeError: module 'ensure' has no attribute 'this'
Developers incorrectly try to access assertion helpers like 'this' or 'that' as direct attributes of the 'ensure' module, rather than using the `ensure` callable instance with the subject as an argument.
fixThe correct usage involves calling the `ensure` instance directly with the value to be checked, e.g., `from ensure import ensure; ensure(some_value).is_an(int)`.
TypeError: 'module' object is not callable
This error occurs when a developer attempts to call the `ensure` module itself as a function (e.g., `import ensure; ensure()`), instead of calling the `ensure` instance imported from the module with the value to be validated.
fixImport the `ensure` instance explicitly and use it as a callable, passing the value to be checked: `from ensure import ensure; ensure(1).is_an(int)`.
AttributeError: 'TestCase' object has no attribute 'assertRaisesRegexp'
This specific error arises when using older versions of the `ensure` library (prior to 1.0.4) with Python 3.12, because Python 3.12 removed the deprecated `assertRaisesRegexp` method, which older `ensure` versions relied upon for internal testing or assertions.
fixUpgrade the `ensure` library to version 1.0.4 or newer to ensure compatibility with Python 3.12: `pip install --upgrade ensure`.
Upgrade
Version history
1.0.4latest on PyPI · released Dec 10, 2023
Audit
Dependencies
No dependency data recorded yet.