Metadata-Version: 2.4
Name: hyperi-pylib
Version: 2.24.2
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: pyyaml>=6.0.3
Requires-Dist: psutil>=7.1.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: api
Requires-Dist: fastapi>=0.104.0; extra == "api"
Requires-Dist: uvicorn[standard]>=0.24.0; extra == "api"
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"
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: presidio
Requires-Dist: presidio-analyzer>=2.2.0; extra == "presidio"
Requires-Dist: presidio-anonymizer>=2.2.0; extra == "presidio"
Provides-Extra: kafka
Requires-Dist: confluent-kafka>=2.3.0; extra == "kafka"
Requires-Dist: genson>=1.3.0; extra == "kafka"
Provides-Extra: secrets-vault
Requires-Dist: httpx>=0.27.0; 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-all
Requires-Dist: hyperi-pylib[secrets-aws,secrets-vault]; extra == "secrets-all"
Provides-Extra: license
Requires-Dist: cryptography>=46.0.5; extra == "license"
Requires-Dist: httpx>=0.27.0; extra == "license"
Provides-Extra: version-check
Requires-Dist: httpx>=0.27.0; 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/workflows/CI%20Publish/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-Proprietary-red)](LICENSE)
<!-- BADGES:END -->

Enterprise Python infrastructure for HyperI projects.

hyperi-pylib provides metrics, logging, and infrastructure utilities for all HyperI Python projects.

> Note: The previous `Application.*` framework (API/Daemon/CLI/Oneshot/MCP) was removed in 2.13.x. Use the individual modules (`logger`, `metrics`, `config`, `kafka`, `http`, `cache`) directly or restore the legacy package from history if you need it.

## Features

- **Logging**: Structured JSON logging with sensitive data masking
- **PII Anonymization**: ML-based anonymization with Presidio integration
- **Database Utilities**: ClickHouse, PostgreSQL, MySQL, Redis connection helpers
- **Configuration**: Multi-layer cascade with environment variable support
- **Runtime**: Application metadata and environment detection
- **Metrics**: Prometheus and OpenTelemetry backends
- **Kafka**: Complete Kafka client library with admin, consumer, producer, and schema analysis
- **Harness**: Smart timeout monitors and container registry utilities
- **CLI**: Typer-based CLI utilities

## Installation

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

### pyproject.toml Configuration (Recommended)

For projects using uv with both JFrog (hyperi-pylib) and PyPI packages, add this to your `pyproject.toml`:

```toml
[tool.uv]
index-strategy = "unsafe-best-match"

[[tool.uv.index]]
name = "hypersec-jfrog"
url = "https://hypersec.jfrog.io/artifactory/api/pypi/hypersec-pypi/simple"
explicit = true

[[tool.uv.index]]
name = "pypi"
url = "https://pypi.org/simple"
default = true

[tool.uv.sources]
hyperi-pylib = { index = "hypersec-jfrog" }
```

**Key settings:**

- `index-strategy = "unsafe-best-match"` - Allows mixing packages from JFrog and PyPI
- `explicit = true` on JFrog - Only use JFrog for explicitly mapped packages
- `default = true` on PyPI - Use PyPI for everything else
- `[tool.uv.sources]` - Explicitly route `hyperi-pylib` to JFrog

Then set credentials via environment variables and install:

```bash
# uv looks for UV_INDEX_{NAME}_USERNAME and UV_INDEX_{NAME}_PASSWORD
# where {NAME} is the uppercase index name with non-alphanumeric chars replaced by underscores
export UV_INDEX_HYPERSEC_JFROG_USERNAME="your-email@hypersec.io"
export UV_INDEX_HYPERSEC_JFROG_PASSWORD="your-jfrog-api-key"

uv sync
```

### Command-Line Installation

```bash
# Set credentials (same env vars work for CLI)
export UV_INDEX_HYPERSEC_JFROG_USERNAME="your-email@hypersec.io"
export UV_INDEX_HYPERSEC_JFROG_PASSWORD="your-jfrog-api-key"

# Using uv with extra-index-url
uv pip install hyperi-pylib \
  --extra-index-url https://hypersec.jfrog.io/artifactory/api/pypi/hypersec-pypi/simple

# With optional dependencies
uv pip install hyperi-pylib[presidio,opentelemetry] \
  --extra-index-url https://hypersec.jfrog.io/artifactory/api/pypi/hypersec-pypi/simple
```

### Optional Dependencies

- `hyperi-pylib[presidio]` - PII anonymization
- `hyperi-pylib[opentelemetry]` - OpenTelemetry metrics
- `hyperi-pylib[api]` - FastAPI support
- `hyperi-pylib[metrics]` - Prometheus metrics

## Quick Start

### Logging

```python
from hyperi_pylib import logger

logger.setup(app_name="my-app", json_output=True)
logger.info("Application started")
logger.error("Something went wrong", exc_info=True)
```

### Configuration

```python
from hyperi_pylib import config

# Initialize configuration
config.setup(app_name="my-app")

# Access settings
settings = config.get_settings()
db_config = config.get_database_config()
```

### Database Connections

```python
from hyperi_pylib import database

# Get database URLs from environment
postgres_url = database.get_postgresql_url()
redis_url = database.get_redis_url()

# Build custom connection URL
url = database.build_database_url(
    driver="postgresql",
    host="localhost",
    port=5432,
    database="mydb",
    username="user",
    password="pass"
)
```

### Kafka

```python
from hyperi_pylib.kafka import KafkaClient

# Create client with configuration
client = KafkaClient.from_config(config_file="kafka.properties")

# Produce messages
await client.produce("my-topic", {"key": "value"})

# Consume messages
async for message in client.consume("my-topic", group_id="my-group"):
    process(message)
```

### Metrics

```python
from hyperi_pylib.metrics import create_metrics_backend

# Prometheus backend
metrics = create_metrics_backend("prometheus")
counter = metrics.counter("requests_total", "Total requests")
counter.inc()
```

## Documentation

- **Metrics**: `docs/METRICS.md`
- **Logging**: `docs/LOGGING.md`
- **Anonymizer**: `docs/ANONYMIZER.md`

## Development

```bash
# Quality checks
ruff check src/ tests/
ruff format src/ tests/

# Tests
pytest tests/

# Build
uv build
```

## License

FSL-1.1-ALv2 - See LICENSE
