Metadata-Version: 2.5
Name: nova-fastapi-tool
Version: 0.2.0
Summary: A FastAPI utility toolkit: logging, Nacos registry & config center, JWT auth, DB helpers, caching, and everyday utils.
Project-URL: Homepage, https://github.com/your-org/nova-fastapi-tool
Project-URL: Repository, https://github.com/your-org/nova-fastapi-tool
Project-URL: Issues, https://github.com/your-org/nova-fastapi-tool/issues
Project-URL: Documentation, https://nova-fastapi-tool.readthedocs.io
Author-email: William <william.ren@petalmail.com>
Maintainer-email: nova-fastapi-tool maintainers <william.ren@petalmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: config-center,fastapi,jwt,logging,nacos,pydantic,rbac,service-registry,utils
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Logging
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.110
Requires-Dist: pydantic-settings>=2.3
Requires-Dist: pydantic>=2.7
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: starlette>=0.36
Provides-Extra: all
Requires-Dist: aiosqlite>=0.20; extra == 'all'
Requires-Dist: argon2-cffi>=23.1; extra == 'all'
Requires-Dist: asyncpg>=0.29; extra == 'all'
Requires-Dist: httpx>=0.27; extra == 'all'
Requires-Dist: loguru>=0.7; extra == 'all'
Requires-Dist: nacos-sdk-python<3,>=1.0.0; extra == 'all'
Requires-Dist: passlib[bcrypt]>=1.7; extra == 'all'
Requires-Dist: pyjwt>=2.9; extra == 'all'
Requires-Dist: pymysql>=1.1; extra == 'all'
Requires-Dist: python-jose[cryptography]>=3.3; extra == 'all'
Requires-Dist: redis>=5.0; extra == 'all'
Requires-Dist: sqlalchemy>=2.0.30; extra == 'all'
Provides-Extra: auth
Requires-Dist: argon2-cffi>=23.1; extra == 'auth'
Requires-Dist: passlib[bcrypt]>=1.7; extra == 'auth'
Requires-Dist: pyjwt>=2.9; extra == 'auth'
Requires-Dist: python-jose[cryptography]>=3.3; extra == 'auth'
Provides-Extra: cache
Requires-Dist: redis>=5.0; extra == 'cache'
Provides-Extra: db
Requires-Dist: aiosqlite>=0.20; extra == 'db'
Requires-Dist: asyncpg>=0.29; extra == 'db'
Requires-Dist: pymysql>=1.1; extra == 'db'
Requires-Dist: sqlalchemy>=2.0.30; extra == 'db'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: hatch>=1.12; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: http
Requires-Dist: httpx>=0.27; extra == 'http'
Provides-Extra: logging
Requires-Dist: loguru>=0.7; extra == 'logging'
Provides-Extra: nacos
Requires-Dist: httpx>=0.27; extra == 'nacos'
Requires-Dist: nacos-sdk-python<3,>=1.0.0; extra == 'nacos'
Description-Content-Type: text/markdown

# nova-fastapi-tool

> **A Hutool-style FastAPI utility toolkit.**
>
> Fast + Tool = nova-fastapi-tool. A curated, modular, batteries-included Python library that brings the
> elegance of [Hutool](https://hutool.cn/) (Java's beloved util library) to the FastAPI world.

<p align="center">
  <em>Keep FastAPI sweet — one helper at a time.</em>
</p>

---

## ✨ Features

| Module | What it gives you | Hutool analog |
|---|---|---|
| **core**     | `StrUtil`, `DateUtil`, `IdUtil`, `HashUtil`, `MapUtil`, `ValidUtil`, `CryptoUtil` | hutool-core |
| **logging**  | Unified `LogUtil` facade (std logging + optional loguru), JSON formatter, request-ID middleware | hutool-log |
| **config**   | Multi-profile YAML / `.env` loader, Pydantic-settings base, environment-variable expansion | hutool-setting |
| **nacos**    | Nacos **service registry & discovery** + **config center** with FastAPI `lifespan` auto-wiring | (unique) |
| **auth**     | JWT `JwtUtil`, password hashing (argon2/bcrypt), RBAC deps, rate-limiter | hutool-jwt |
| **web**      | `create_app` factory, global exception handler, unified `R.ok()` / `R.fail()` response, CORS helper | (unique) |
| **db**       | SQLAlchemy 2 async/sync helpers — `DbUtil` / `AsyncDbUtil`, typed `Page` pagination, transactions, engine registry | hutool-db |
| **cache**    | `CacheUtil` / `AsyncCacheUtil` facade — memory (LRU+TTL) or Redis backend, pluggable serializer | hutool-cache |
| **http**     | httpx-based client wrapper — `HttpUtil` / `AsyncHttpUtil` one-shots, reusable `HttpClient` / `AsyncHttpClient`, retry with backoff | hutool-http |

---

## 🚀 Install

The package follows the **"core + optional extras"** pattern — exactly like Hutool's modular
dependencies. Pick just what you need:

```bash
# Only core utilities (StrUtil / DateUtil / unified response / common middleware)
pip install nova-fastapi-tool

# + Nacos service registry & config center
pip install nova-fastapi-tool[nacos]

# + JWT auth / RBAC / password hashing / rate limiting
pip install nova-fastapi-tool[auth]

# + rich loguru-backed logging
pip install nova-fastapi-tool[logging]

# + httpx-based HTTP client wrapper (HttpUtil / HttpClient)
pip install nova-fastapi-tool[http]

# = Everything (≈ hutool-all)
pip install nova-fastapi-tool[all]

# = Dev / test / build tooling
pip install nova-fastapi-tool[dev]
```

> **Python ≥ 3.11** is required.

---

## 🧩 5-second tour

```python
from fastapi import FastAPI
from nova_fastapi_tool import create_app, LogUtil, R, StrUtil, DateUtil

# 1) Assemble a production-ready FastAPI app in 1 line
app: FastAPI = create_app(title="demo-service", debug=False, cors_origins=["*"])

# 2) Simple logging facade that behaves everywhere
LogUtil.info("Starting demo at {}", DateUtil.now_iso())

# 3) String helpers — Hutool-ish ergonomics
if StrUtil.is_blank("  "):
    LogUtil.warning("Empty input detected; masked={}", StrUtil.mask_email("user@example.com"))

# 4) Unified response envelope — your front-end will love you
@app.get("/hello")
def hello(name: str | None = None) -> R:
    return R.ok({"greeting": f"Hello, {StrUtil.or_default(name, 'World')}!"})
```

### With Nacos + JWT

See [`examples/`](./examples) for:

- `minimal_app.py` — Logging + unified response skeleton
- `nacos_demo.py` — Service register/discovery + config-center watcher
- `auth_demo.py` — JWT login + role-protected endpoints

---

## 📁 Project layout

```
pypi-fastapi/
├── pyproject.toml           # PEP 621 packaging + extras (nacos/auth/logging/…)
├── src/
│   └── nova_fastapi_tool/            # Importable package (same name as PyPI artifact)
│       ├── __init__.py      # Re-exports everything (≈ hutool-all)
│       ├── version.py       # Single source of truth for version
│       ├── core/            # StrUtil, DateUtil, IdUtil, HashUtil, …
│       ├── logging/         # LogUtil facade + JSON formatter + request-ID MW
│       ├── config/          # Multi-profile YAML/.env + Settings base class
│       ├── nacos/           # NacosClient, Registry, ConfigCenter, Discovery, lifespan
│       ├── auth/            # JwtUtil, passwords, RBAC, rate-limit, Depends
│       ├── web/             # create_app, exceptions, R response, CORS, access-log MW
│       ├── db/              # DbUtil / AsyncDbUtil, Page, transactions, engine registry
│       ├── cache/           # CacheUtil / AsyncCacheUtil, memory/Redis backends
│       └── http/            # HttpUtil / HttpClient, retry config, HttpError
├── tests/                   # Pytest suite, module-scoped
└── examples/                # Runnable demos
```

---

## 🛡️ License

Apache License 2.0 — see [`LICENSE`](./LICENSE).

## 📦 Publish to PyPI

> **PyPI credentials are kept out of this repo.** Export a project-scoped API token as environment
> variables before uploading:
>
> ```bash
> export TWINE_USERNAME=__token__
> export TWINE_PASSWORD=pypi-xxxxxxxxxxxxxxxxxxxx
> hatch build            # → dist/nova_fastapi_tool-X.Y.Z{.tar.gz,.whl}
> twine upload dist/*
> ```
