Metadata-Version: 2.4
Name: kstlib
Version: 2.1.1
Summary: Config-driven helpers for Python projects (dynamic config, secure secrets, preset logging, and more…)
Author-email: Michel TRUONG <michel.truong@gmail.com>
Maintainer-email: Michel TRUONG <michel.truong@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/KaminoU/kstlib
Project-URL: Repository, https://github.com/KaminoU/kstlib
Project-URL: Bug Tracker, https://github.com/KaminoU/kstlib/issues
Project-URL: Changelog, https://github.com/KaminoU/kstlib/blob/main/CHANGELOG.md
Keywords: kstlib,config,configuration,yaml,secrets,sops,logging,oauth2,oidc,rest-api,http-client,resilience,circuit-breaker,rate-limiter,websocket,alerts,toolkit
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: pyyaml<7,>=6.0
Requires-Dist: tomli<3,>=2.3
Requires-Dist: tomli-w<2,>=1.0
Requires-Dist: python-box<8,>=7.3
Requires-Dist: typer<1,>=0.19
Requires-Dist: click<9,>=8.3
Requires-Dist: rich<15,>=14.2
Requires-Dist: structlog<26,>=25.0
Requires-Dist: aiosqlite<1,>=0.21
Requires-Dist: aiosmtplib<5,>=4.0
Requires-Dist: websockets<16,>=15.0
Requires-Dist: jinja2<4,>=3.1.5
Requires-Dist: humanize<5,>=4.11
Requires-Dist: httpx<1,>=0.28
Requires-Dist: authlib<2,>=1.6.9
Requires-Dist: pendulum<4,>=3.0
Provides-Extra: dev
Requires-Dist: pytest<9,>=8.4; extra == "dev"
Requires-Dist: pytest-cov<8,>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio<2,>=1.2; extra == "dev"
Requires-Dist: ruff<1,>=0.14; extra == "dev"
Requires-Dist: mypy<2,>=1.18; extra == "dev"
Requires-Dist: types-PyYAML<7,>=6.0; extra == "dev"
Requires-Dist: pre-commit<5,>=4.0; extra == "dev"
Requires-Dist: boto3<2,>=1.35; extra == "dev"
Requires-Dist: moto[ses]<6,>=5.0; extra == "dev"
Provides-Extra: db-crypto
Requires-Dist: sqlcipher3<1,>=0.5; extra == "db-crypto"
Provides-Extra: docs
Requires-Dist: sphinx<9,>=8.1; extra == "docs"
Requires-Dist: furo<2026,>=2025.9; extra == "docs"
Requires-Dist: myst-parser<5,>=4.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints<4,>=3.0; extra == "docs"
Requires-Dist: sphinx-togglebutton<1,>=0.3; extra == "docs"
Requires-Dist: sphinx-design<0.7,>=0.6; extra == "docs"
Provides-Extra: build
Requires-Dist: build<2,>=1.3; extra == "build"
Requires-Dist: twine<7,>=6.2; extra == "build"
Provides-Extra: tox
Requires-Dist: tox<5,>=4.31; extra == "tox"
Provides-Extra: ses
Requires-Dist: boto3<2,>=1.35; extra == "ses"
Provides-Extra: infra-tools
Requires-Dist: awscli-local<1,>=0.22; extra == "infra-tools"
Provides-Extra: textual
Requires-Dist: textual<7,>=6.3; extra == "textual"
Provides-Extra: all
Requires-Dist: pytest<9,>=8.4; extra == "all"
Requires-Dist: pytest-cov<8,>=7.0; extra == "all"
Requires-Dist: pytest-asyncio<2,>=1.2; extra == "all"
Requires-Dist: ruff<1,>=0.14; extra == "all"
Requires-Dist: mypy<2,>=1.18; extra == "all"
Requires-Dist: types-PyYAML<7,>=6.0; extra == "all"
Requires-Dist: sphinx<9,>=8.1; extra == "all"
Requires-Dist: furo<2026,>=2025.9; extra == "all"
Requires-Dist: myst-parser<5,>=4.0; extra == "all"
Requires-Dist: sphinx-autodoc-typehints<4,>=3.0; extra == "all"
Requires-Dist: sphinx-togglebutton<1,>=0.3; extra == "all"
Requires-Dist: sphinx-design<0.7,>=0.6; extra == "all"
Requires-Dist: build<2,>=1.3; extra == "all"
Requires-Dist: twine<7,>=6.2; extra == "all"
Requires-Dist: tox<5,>=4.31; extra == "all"
Requires-Dist: pre-commit<5,>=4.0; extra == "all"
Requires-Dist: boto3<2,>=1.35; extra == "all"
Requires-Dist: moto[ses]<6,>=5.0; extra == "all"
Requires-Dist: awscli-local<1,>=0.22; extra == "all"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/KaminoU/kstlib/main/assets/kstlib.svg" alt="Kstlib Logo" width="420">
</p>

<p align="center">
  <strong>Config-driven Python toolkit for resilient applications</strong>
</p>

<p align="center">
  <a href="https://github.com/KaminoU/kstlib/actions/workflows/ci.yml"><img src="https://github.com/KaminoU/kstlib/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
  <a href="https://kstlib.readthedocs.io/"><img src="https://img.shields.io/badge/docs-RTD-blue" alt="Documentation"></a>
  <a href="https://pypi.org/project/kstlib/"><img src="https://img.shields.io/pypi/v/kstlib?color=blue" alt="PyPI"></a>
  <img src="https://img.shields.io/badge/python-≥3.10-blue" alt="Python">
  <a href="https://github.com/KaminoU/kstlib/blob/main/LICENSE.md"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
</p>

---

**kstlib** is a personal Python toolkit built over 7 years of learning and experimentation.

It started as a way to explore Python best practices, evolved into utilities for personal automation,
and now serves as the foundation for study projects in algorithmic trading and market analysis.

The focus has always been on building **resilient, secure, and performant** systems.

> **Note**: Everything works via Python, but since kstlib is heavily config-driven,
> the [Examples Gallery](https://kstlib.readthedocs.io/en/latest/examples.html) showcases
> a YAML-first approach.

## Core Modules

| Module | Purpose |
|--------|---------|
| **config** | Cascading config files, includes, SOPS encryption, Box access |
| **secrets** | Multi-provider resolver (env, keyring, SOPS, KMS) with guardrails |
| **logging** | Rich console, rotating files, TRACE level, structlog integration |
| **auth** | OIDC/OAuth2 with PKCE, token storage, auto-refresh |
| **mail** | Jinja templates, transports (SMTP, Gmail API, Resend, AWS SES) |
| **alerts** | Multi-channel (Slack, Email), throttling, severity levels |
| **websocket** | Resilient connections, auto-reconnect, heartbeat, watchdog |
| **rapi** | Config-driven REST client with HMAC signing |
| **pipeline** | Declarative sequential workflows (shell/python/callable steps), error policies, conditional execution |
| **monitoring** | Collectors + Jinja rendering + delivery (file, mail) |
| **resilience** | Circuit breaker, rate limiter, graceful shutdown |
| **ops** | Session manager (tmux), containers (Docker/Podman) |
| **helpers** | TimeTrigger, formatting, secure delete, validators |

## Quick Start

### Installation

```bash
pip install kstlib
```

### Basic Usage

```python
from kstlib.config import load_from_file
from kstlib import cache

config = load_from_file("config.yml")

@cache(ttl=300)
def expensive_computation(x: int) -> int:
    return x ** 2

result = expensive_computation(5)
```

### Minimal Configuration

```yaml
app:
  name: "My Application"
  debug: true

database:
  host: "localhost"
  port: 5432
```

## Documentation

Full documentation available at **[kstlib.readthedocs.io](https://kstlib.readthedocs.io/)**

- [Features Guide](https://kstlib.readthedocs.io/en/latest/features/index.html)
- [Examples Gallery](https://kstlib.readthedocs.io/en/latest/examples.html)
- [API Reference](https://kstlib.readthedocs.io/en/latest/api/index.html)
- [Development Guide](https://kstlib.readthedocs.io/en/latest/development/index.html)

## Installation Options

```bash
# Standard install
pip install kstlib

# With uv (faster)
uv pip install kstlib

# Development install
pip install "kstlib[dev]"

# All extras
pip install "kstlib[all]"

# From GitHub (latest)
pip install "git+https://github.com/KaminoU/kstlib.git"
```

## License

MIT License - Copyright 2025 Michel TRUONG

See [LICENSE](LICENSE.md) for full text.
