houdimi 0.1.1

Type-safe primitives, functional patterns, and Django integration helpers for Python 3.14+

houdimi

A Python 3.14+ utility library providing type-safe primitives, functional patterns, and Django integration helpers. Built for projects that require explicit error handling, strict runtime type guarantees, and expressive domain modeling.

---

Installation

pip install houdimi

Django integration requires Django to be installed separately:

pip install houdimi django

---

Modules

Core (houdimi.core)

Foundational type aliases and runtime introspection utilities shared across all other modules.

Provides numeric constraint types (Positive, Negative, NonZero, Infinite) backed by beartype validators, generic container aliases (Array, Map, Pair, Nullable), JSON structural aliases, and a complete set of callable type shapes (Function, Predicate, Consumer, Supplier, Unary, Yields). Runtime type checking against TypeAliasType objects via isalias and narrow.

---

Result (houdimi.results)

Rust-inspired Result[T, E] monad for explicit, composable error handling.

Replaces bare try/except blocks with a value-level API: Result.OK(value) and Result.ERROR(exception) are the two possible states. Supports monadic chaining via map, map_error, and_then, and or_else. The try_catch decorator wraps any function to return Result[T, E] automatically, catching specified exception types and preserving the original function signature for type checkers.

---

OOP (houdimi.oop)

Object: a rich introspectable base class for domain objects.

Provides full Python protocol support (equality, hashing, repr, copy, deepcopy, pickle) and a .info cached property exposing categorized member metadata: public/private/dunder methods and attributes, property descriptors with docs and accessor references, and instance field values. Useful for serialization, debugging tooling, and reflective frameworks.

---

Strings (houdimi.strings)

Annotated string types and identifier case conversion.

String[min, max] and RegexString[pattern] produce Annotated[str, ...] types with bounds or pattern constraints enforced at runtime via beartype.

CaseRegex covers 12 naming conventions (PascalCase, camelCase, snake_case, kebab-case, CONSTANT_CASE, Ada_Case, Train-Case, COBOL-CASE, dot.case, flatcase, UPPERFLATCASE). CaseStrategy detects the convention of any string via a heuristic priority ranking and converts between any two conventions: directly when a registered path exists, transitively via snake_case otherwise. RegexPatterns provides callable StrEnum members for common patterns: EMAIL, IPV4, HEX_COLOR, UUID.

---

Decorators (houdimi.decorators)

Composable function and class behavior modifiers.

Function decorators: deprecated (deprecation warning), cached(calls=n) (result caching for N invocations), once (permanent cache), repeat(times=n) (multi-execution), before(hook) and after(hook) (pre/post side effects).

Class decorators: @singleton (immediate instantiation, re-instantiation blocked), @with_hooks(on_init, on_del) (lifecycle callbacks), @with_lock (thread-safe singleton via RLock), @with_counter (instantiation count tracking).

classproperty: descriptor for @property-style class-level computed attributes without module-level globals.

---

Math (houdimi.math)

3D geometry primitives and byte-level binary utilities.

Point3D and Vector3D support full arithmetic operator overloading: addition, subtraction, scalar multiplication, dot product (*), cross product (@), and division. Includes length (cached), unit vector, and angle computation in radians or degrees. Standard reference constants available as class properties.

Range[low, high] produces a Literal[low, ..., high] type at subscription time for integer range constraints. Word wraps an 8-bit integer with named bit-level operations (read, set, toggle, on, off).

---

Transitions (houdimi.transitions)

Enum-driven finite state machine with guard conditions and lifecycle hooks.

Machine[T] is initialized with an enum type and a starting state. Transition objects define named moves with source state guards, checks (predicate list), and before/after callback lists. Rule[T] wraps predicates with boolean composition operators (&, |, ~) for building compound guards without nesting lambdas. Transitions can be triggered by name or via direct attribute access on the machine instance.

---

HTTP & Django (houdimi.http)

HTTP exceptions, typed query parameter extraction, Django response utilities, and Result-typed ORM scaffolding.

Exceptions: ApplicationError base with ClientError (400–499) and ServerError (500–599) hierarchies. Each instance carries a formatted error string, human-readable message, validated status code, and detail strings. A .response property returns a ready Django JsonResponse.

CRUD: @make_repository(model=M) and @make_service(repo=R) decorators inject Result-typed get_all, get_by_id, create, update, and delete methods. User-defined methods take precedence over injected ones. RepositoryBase[M] and ServiceBase[M, R] base classes give Pyright visibility of the injected signatures.

Query parameters: QueryParams extends Django QueryDict with typed accessors for strings, numbers, booleans, lists, enums, dates, datetimes, and Unix epoch timestamps. Accessed parameters are automatically recorded in .filters.

Endpoint builder: Endpoint is a fluent, immutable URL builder supporting path concatenation, API version prefixing, query string appending, pagination, and field selection.

Response key conversion: BackendResponse serializes JSON with camelCase keys; FrontendResponse uses snake_case. Both are pre-configured JsonResponse subclasses via the with_keys decorator.

---

Repository structure

This package is composed of independently versioned Git submodules aggregated under the houdimi root.

Submodule path	Repository
houdimi/core/	houdimi-core
houdimi/results/	houdimi-results
houdimi/oop/	houdimi-oop
houdimi/strings/	houdimi-strings
houdimi/decorators/	houdimi-decorators
houdimi/math/	houdimi-math
houdimi/transitions/	houdimi-transitions
houdimi/http/	houdimi-http

Clone with all submodules:

git clone --recurse-submodules https://github.com/DanielDH179/houdimi

See .claude/skills/git-submodules.md for submodule management operations.

---

License

MIT: see LICENSE for details.