Metadata-Version: 2.4
Name: houdimi
Version: 0.1.1
Summary: Type-safe primitives, functional patterns, and Django integration helpers for Python 3.14+
Author-email: Daniel Dmitrienco Herrera <danieldh231001@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Daniel Dmitrienco Herrera
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/DanielDH179/houdimi
Project-URL: Repository, https://github.com/DanielDH179/houdimi
Project-URL: Issues, https://github.com/DanielDH179/houdimi/issues
Keywords: typing,result,functional,django,utilities
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: beartype>=0.22.9
Requires-Dist: django>=6.0.2
Requires-Dist: rich>=14.3.3
Provides-Extra: dev
Requires-Dist: autopep8>=2.3.1; extra == "dev"
Requires-Dist: coverage>=7.13.4; extra == "dev"
Requires-Dist: psycopg2-binary>=2.9.11; extra == "dev"
Requires-Dist: pudb>=2025.1.5; extra == "dev"
Requires-Dist: pydantic>=2.12.5; extra == "dev"
Requires-Dist: pytest>=9.0.2; extra == "dev"
Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
Dynamic: license-file

# houdimi

[![PyPI version](https://img.shields.io/pypi/v/houdimi.svg)](https://pypi.org/project/houdimi/)
[![Python](https://img.shields.io/pypi/pyversions/houdimi.svg)](https://pypi.org/project/houdimi/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

```bash
pip install houdimi
```

Django integration requires Django to be installed separately:

```bash
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:

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

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

---

## License

MIT: see [LICENSE](LICENSE) for details.
