Metadata-Version: 2.4
Name: hyperi-pylib
Version: 2.24.3
Summary: Enterprise infrastructure for containerized Python applications - configuration, logging, timeouts, database, metrics, and application framework
Home-page: https://github.com/hyperi-io/hyperi-pylib
Author: HyperI Team
Author-email: HyperI Team <dev@hyperi.io>
Maintainer-email: HyperI Team <dev@hyperi.io>
License-Expression: LicenseRef-FSL-1.1-ALv2
Project-URL: Homepage, https://github.com/hyperi-io/hyperi-pylib
Project-URL: Documentation, https://hyperi-io.github.io/hyperi-pylib/
Project-URL: Repository, https://github.com/hyperi-io/hyperi-pylib
Project-URL: Bug Reports, https://github.com/hyperi-io/hyperi-pylib/issues
Project-URL: Changelog, https://github.com/hyperi-io/hyperi-pylib/blob/main/CHANGELOG.md
Keywords: hypersec,enterprise,containerization,kubernetes,docker,logging,configuration,prometheus,metrics,database,application-framework,fastapi
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Logging
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: dynaconf>=3.2.12
Requires-Dist: loguru>=0.7.3
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: mergedeep>=1.3.4
Requires-Dist: tomli-w>=1.0.0
Requires-Dist: typer>=0.20.0
Requires-Dist: dulwich>=0.22.0
Provides-Extra: cli
Provides-Extra: http
Requires-Dist: httpx>=0.27.0; extra == "http"
Requires-Dist: stamina>=25.1.0; extra == "http"
Provides-Extra: cache
Requires-Dist: cashews>=7.0.0; extra == "cache"
Requires-Dist: msgpack>=1.0.0; extra == "cache"
Requires-Dist: psycopg[binary,pool]>=3.2.0; extra == "cache"
Provides-Extra: metrics
Requires-Dist: prometheus-client>=0.19.0; extra == "metrics"
Requires-Dist: psutil>=7.1.0; extra == "metrics"
Provides-Extra: opentelemetry
Requires-Dist: opentelemetry-api>=1.20.0; extra == "opentelemetry"
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "opentelemetry"
Requires-Dist: opentelemetry-exporter-otlp>=1.20.0; extra == "opentelemetry"
Requires-Dist: opentelemetry-exporter-prometheus>=0.41b0; extra == "opentelemetry"
Provides-Extra: expression
Requires-Dist: common-expression-language>=0.5.6; extra == "expression"
Provides-Extra: database
Provides-Extra: kafka
Requires-Dist: confluent-kafka>=2.3.0; extra == "kafka"
Requires-Dist: genson>=1.3.0; extra == "kafka"
Provides-Extra: presidio
Requires-Dist: presidio-analyzer>=2.2.0; extra == "presidio"
Requires-Dist: presidio-anonymizer>=2.2.0; extra == "presidio"
Provides-Extra: secrets-vault
Provides-Extra: secrets-aws
Requires-Dist: boto3>=1.35.0; extra == "secrets-aws"
Requires-Dist: aiobotocore>=2.15.0; extra == "secrets-aws"
Provides-Extra: secrets-gcp
Requires-Dist: google-cloud-secret-manager>=2.26.0; extra == "secrets-gcp"
Provides-Extra: secrets-azure
Requires-Dist: azure-keyvault-secrets>=4.9.0; extra == "secrets-azure"
Requires-Dist: azure-identity>=1.25.1; extra == "secrets-azure"
Provides-Extra: secrets
Requires-Dist: boto3>=1.35.0; extra == "secrets"
Requires-Dist: aiobotocore>=2.15.0; extra == "secrets"
Requires-Dist: google-cloud-secret-manager>=2.26.0; extra == "secrets"
Requires-Dist: azure-keyvault-secrets>=4.9.0; extra == "secrets"
Requires-Dist: azure-identity>=1.25.1; extra == "secrets"
Provides-Extra: license
Requires-Dist: cryptography>=46.0.5; extra == "license"
Requires-Dist: httpx>=0.27.0; extra == "license"
Provides-Extra: version-check
Provides-Extra: enhanced
Provides-Extra: dev
Requires-Dist: setuptools>=70.0.0; extra == "dev"
Requires-Dist: wheel>=0.42.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: cryptography>=46.0.5; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-httpx>=0.30.0; extra == "dev"
Requires-Dist: httpx>=0.27.0; extra == "dev"
Requires-Dist: stamina>=25.1.0; extra == "dev"
Requires-Dist: boto3>=1.35.0; extra == "dev"
Requires-Dist: aiobotocore>=2.15.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: black>=24.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: ty>=0.0.21; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: bandit[toml]>=1.7.0; extra == "dev"
Requires-Dist: pip-audit>=2.6.0; extra == "dev"
Requires-Dist: interrogate>=1.5.0; extra == "dev"
Requires-Dist: vulture>=2.7.0; extra == "dev"
Requires-Dist: vermin>=1.6.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Requires-Dist: python-semantic-release>=9.0.0; extra == "dev"
Requires-Dist: mergedeep>=1.3.4; extra == "dev"
Requires-Dist: pycryptodomex>=3.20.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: tiktoken>=0.5.0; extra == "dev"
Requires-Dist: faker>=33.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx<8.0.0,>=7.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=3.0.0; extra == "docs"
Requires-Dist: myst-parser>=3.0.0; extra == "docs"
Requires-Dist: sphinx-autobuild>=2024.0.0; extra == "docs"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# hyperi-pylib

<!-- BADGES:START -->
[![Build Status](https://github.com/hyperi-io/hyperi-pylib/actions/workflows/ci.yml/badge.svg)](https://github.com/hyperi-io/hyperi-pylib/actions)
[![Python Version](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-FSL--1.1--ALv2-blue)](LICENSE)
<!-- BADGES:END -->

Enterprise infrastructure for all HyperI Python projects — configuration, logging, metrics, database utilities, Kafka, caching, and CLI framework.

## Features

Core modules — always installed (`uv add hyperi-pylib`):

| Module | Description | Third-party deps |
|---|---|---|
| `logging` | Structured JSON logging with automatic sensitive data masking | loguru |
| `config` | 8-layer cascade (CLI → ENV → .env → PostgreSQL → YAML → defaults), container-aware | dynaconf, pyyaml, python-dotenv, mergedeep, tomli-w, dulwich |
| `runtime` | Container/K8s/local environment detection with standard path resolution | stdlib only |
| `database` | Connection URL builders for PostgreSQL, Redis, and others | stdlib only |
| `cli` | `DfeApp` framework — subclass to get `run`/`version`/`config-check` for free | typer |
| `harness` | Timeout monitors and utility helpers | stdlib only |
| `version-check` | Startup check for new hyperi-pylib releases (skipped if httpx absent) | httpx (lazy) |

Optional modules — enabled by installing the matching extra:

| Module | Extra | Third-party deps |
|---|---|---|
| `http` | `http` | httpx, stamina |
| `metrics` | `metrics` | prometheus-client, psutil |
| `expression` | `expression` | common-expression-language (CEL via Rust/PyO3) |
| `cache` | `cache` | cashews, msgpack, psycopg[binary,pool] |
| `kafka` | `kafka` | confluent-kafka, genson |
| `opentelemetry` | `opentelemetry` | opentelemetry SDK + OTLP + Prometheus exporters |

## Installation

> **Package naming:** `hyperi-pylib` on PyPI, `hyperi_pylib` for Python imports.

```bash
# Core only (logging, config, runtime, database, cli, harness, version-check)
uv add hyperi-pylib

# With common extras
uv add "hyperi-pylib[http,metrics,kafka]"

# Full stack
uv add "hyperi-pylib[http,metrics,expression,cache,kafka,opentelemetry]"
```

### Optional Extras

| Extra | Packages | Size |
|---|---|---|
| `http` | httpx + stamina | ~1 MB |
| `metrics` | prometheus-client + psutil | ~1 MB |
| `expression` | common-expression-language (CEL) | ~6 MB |
| `cache` | cashews + msgpack + psycopg[binary,pool] | ~14 MB (psycopg C libs) |
| `kafka` | confluent-kafka + genson | ~11 MB (C libs) |
| `opentelemetry` | OpenTelemetry SDK + exporters | ~4 MB |
| `presidio` | Presidio analyser + anonymiser | ~500 MB (spaCy + ML models) |
| `secrets` | All secrets backends (Vault + AWS + GCP + Azure) | — |
| `secrets-vault` | OpenBao / HashiCorp Vault (uses `http` extra) | convenience marker |
| `secrets-aws` | AWS Secrets Manager via boto3 | ~100 MB |
| `secrets-gcp` | GCP Secret Manager | ~80–100 MB |
| `secrets-azure` | Azure Key Vault | ~50 MB |

## Quick Start

### Logging

```python
from hyperi_pylib.logger import logger

logger.info("Service starting", version="1.0.0")
logger.error("DB connection failed", host="postgres", retry=3)
```

Auto-detects console vs container — structured JSON in containers, human-readable locally.

### Configuration

```python
from hyperi_pylib.config import settings

# Automatic cascade: CLI > ENV > .env > PostgreSQL > settings.yaml > defaults
host = settings.database.host
port = settings.api.port
```

ENV key mapping: `settings.database.host` → `MYAPP_DATABASE_HOST`

### Database URLs

```python
from hyperi_pylib import build_database_url

postgres = build_database_url("postgresql")  # reads POSTGRES_HOST, POSTGRES_PORT, etc.
redis = build_database_url("redis")          # reads REDIS_HOST, REDIS_PORT, etc.
```

### Runtime Paths

```python
from hyperi_pylib import get_runtime_paths

runtime = get_runtime_paths()
config = runtime.config_dir / "app.yaml"   # /config in K8s, ~/.config locally
data   = runtime.data_dir  / "state.db"   # /data in K8s, ~/.local/share locally
```

### Metrics

```python
from hyperi_pylib import create_metrics

metrics = create_metrics(namespace="myapp")
metrics.http_requests.inc()
metrics.active_users.set(42)
metrics.request_duration.observe(0.123)
```

### Cache

```python
from hyperi_pylib.cache import PostgresCache, generate_cache_key

cache = PostgresCache(dsn="postgresql://user:pass@host/db")
await cache.init()

key = generate_cache_key("analytics", "events", org_id="acme")
await cache.set(key, {"data": [...]}, ttl_seconds=300, namespace="analytics")
value = await cache.get(key)

await cache.close()
```

### Kafka

```python
from hyperi_pylib.kafka import KafkaClient, KafkaConsumer, KafkaProducer
```

### DfeApp CLI Framework

Subclass `DfeApp` to get standard CLI lifecycle (`run`, `version`, `config-check`) with no boilerplate:

```python
from hyperi_pylib.cli import DfeApp, VersionInfo

class MyService(DfeApp):
    name = "my-service"
    env_prefix = "MY_SVC"

    def version_info(self) -> VersionInfo:
        return VersionInfo(self.name, "1.0.0")

    async def run_service_async(self, config) -> None:
        ...

if __name__ == "__main__":
    MyService().cli()
```

Config always uses the Dynaconf cascade — no bespoke loading needed.

## Development

```bash
make quality   # lint, type-check, security audit
make test      # run test suite
make build     # build wheel
```

## License

FSL-1.1-ALv2 — See LICENSE
