Metadata-Version: 2.3
Name: smartutils-py
Version: 0.0.5
Summary: 一个面向中大型项目的Python基础工具库，涵盖配置管理、日志、上下文、ID生成、数据处理、设计模式、定时、异常处理等基础功能。
License: MIT
Keywords: utils,python,基础工具,日志,配置,ID,设计模式,定时
Author: wuruimiao
Author-email: dev.wuruimiao@qq.com
Requires-Python: >=3.10,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
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: Topic :: Software Development :: Libraries :: Python Modules
Provides-Extra: all
Provides-Extra: auth
Provides-Extra: django
Provides-Extra: fastapi
Provides-Extra: flask
Provides-Extra: kafka
Provides-Extra: mongo
Provides-Extra: mysql
Provides-Extra: opentelemetry
Provides-Extra: pgsql
Provides-Extra: redis
Requires-Dist: PyJWT (>=2.10.1,<2.11.0) ; extra == "auth" or extra == "all"
Requires-Dist: PyYAML (>=6.0.2,<6.1.0)
Requires-Dist: aiokafka (>=0.12.0,<0.13.0) ; extra == "kafka" or extra == "all"
Requires-Dist: asyncmy (>=0.2.10,<0.3.0) ; extra == "mysql" or extra == "all"
Requires-Dist: asyncpg (>=0.30.0,<0.31.0) ; extra == "pgsql" or extra == "all"
Requires-Dist: bcrypt (>=4.3.0,<4.4.0) ; extra == "auth" or extra == "all"
Requires-Dist: beanie (>=1.30.0,<2.0.0) ; extra == "mongo" or extra == "all"
Requires-Dist: contextvars (>=2.4,<2.5)
Requires-Dist: django (>=5.2.3,<5.3.0) ; extra == "django" or extra == "all"
Requires-Dist: fastapi (>=0.115.11,<0.116.0) ; extra == "fastapi" or extra == "all"
Requires-Dist: filetype (>=1.2.0,<2.0.0) ; extra == "all"
Requires-Dist: flask (>=3.1.1,<3.2.0) ; extra == "flask" or extra == "all"
Requires-Dist: loguru (>=0.7.3,<0.8.0)
Requires-Dist: motor (>=3.7.1,<4.0.0) ; extra == "mongo" or extra == "all"
Requires-Dist: opentelemetry-exporter-otlp (>=1.33.1,<1.34.0) ; extra == "opentelemetry" or extra == "all"
Requires-Dist: opentelemetry-instrumentation-fastapi (>=0.54b1,<0.55) ; extra == "opentelemetry" or extra == "all"
Requires-Dist: opentelemetry-instrumentation-requests (>=0.54b1,<0.55) ; extra == "opentelemetry" or extra == "all"
Requires-Dist: opentelemetry-sdk (>=1.33.1,<1.34.0) ; extra == "opentelemetry" or extra == "all"
Requires-Dist: orjson (>=3.10.18,<3.11.0)
Requires-Dist: pillow (>=11.2.1,<11.3.0) ; extra == "auth" or extra == "all"
Requires-Dist: pydantic (>=2.10.6,<2.11.0) ; extra == "fastapi" or extra == "all"
Requires-Dist: pyotp (>=2.9.0,<2.10.0) ; extra == "auth" or extra == "all"
Requires-Dist: python-dotenv (>=1.1.0,<1.2.0)
Requires-Dist: python-snappy (>=0.7.3,<0.8.0) ; extra == "kafka" or extra == "all"
Requires-Dist: qrcode (>=8.1,<8.2) ; extra == "auth" or extra == "all"
Requires-Dist: redis (>=5.2.1,<5.3.0) ; extra == "redis" or extra == "all"
Requires-Dist: sqlalchemy[asyncio] (>=2.0.38,<2.1.0) ; extra == "mysql" or extra == "pgsql" or extra == "all"
Requires-Dist: starlette (>=0.46.2,<0.47.0) ; extra == "fastapi" or extra == "all"
Requires-Dist: uhashring (>=2.4,<3.0) ; extra == "all"
Requires-Dist: ulid-py (>=1.1.0,<1.2.0)
Requires-Dist: uvicorn[standard] (>=0.34.0,<0.35.0) ; extra == "fastapi" or extra == "all"
Requires-Dist: zstandard (>=0.23.0,<0.24.0) ; extra == "kafka" or extra == "all"
Project-URL: Homepage, https://github.com/wuruimiao/smartutils
Project-URL: Repository, https://github.com/wuruimiao/smartutils
Description-Content-Type: text/markdown

# smartutils

`smartutils` 是一个面向 Python 的通用工具库，集成了配置管理、上下文、ID生成、数据处理、设计模式、文件操作、日志、定时器、异常处理等常用功能，适用于中大型项目的基础设施搭建和快速开发。

## 主要功能模块

- **配置管理**：支持 YAML 配置加载、工厂模式、配置键管理。
- **上下文管理**：基于 contextvars，支持多种上下文变量注册与管理。
- **ID 生成**：支持多种分布式唯一 ID 生成方案。
- **数据处理**：包括类型校验、哈希环、URL、CSV、中文数字等工具。
- **设计模式**：内置单例、工厂、弃用等常用设计模式实现。
- **文件操作**：文件读写、压缩、路径、锁、类型判断等。
- **日志系统**：基于 loguru，支持多级别日志与自定义扩展。
- **定时与计时**：Timer 类和 timeit 装饰器，支持同步/异步计时。
- **异常处理**：业务异常、系统异常、异常映射与工厂。
- **系统工具**：进程管理、平台信息、cgroup 资源管理等。
- **应用层支持**：插件、适配器、请求上下文、FastAPI 响应模型等。

## 安装依赖

项目使用 [Poetry](https://python-poetry.org/) 管理依赖，核心依赖如下：

- Python >= 3.8
- PyYAML
- loguru
- contextvars
- python-dotenv
- orjson

可选依赖（数据库、缓存、Web 框架等）详见 `pyproject.toml`。

安装命令：

```bash
poetry install
```

## 快速开始

```python
from smartutils.init import init

# 初始化 smartutils，加载配置
await init("config/config.yaml")

# 使用时间工具
from smartutils import time
now = time.get_now_str()

# 使用定时器
from smartutils import timer

@timer.timeit("任务耗时：")
def my_task():
    # ... 业务逻辑 ...
    pass

my_task()
```

## 测试

项目内置丰富的单元测试，运行如下：

```bash
pytest -s --cov=smartutils --cov-report=html tests tests_real
```

## 贡献

欢迎提交 issue 和 PR，完善文档和功能！

