Metadata-Version: 2.4
Name: xigua
Version: 0.1.12
Summary: 小工具集 — 各类实用小功能
Author-email: xigua <2587125111@qq.com>
License: Copyright © 2024 xigua Authors. All Rights Reserve.
Project-URL: Homepage, https://pypi.org/project/xigua
Keywords: utilities,tools,metadata,exif,ffprobe,media,hls
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: Pillow>=9.0.0
Requires-Dist: PyYAML<7.0,>=6.0
Provides-Extra: heif
Requires-Dist: pillow-heif>=0.10.0; extra == "heif"
Provides-Extra: hls
Requires-Dist: rich>=13.0.0; extra == "hls"

# xigua — 小工具集

各类实用小功能，按模块组织，持续扩展。

## 已包含模块

### media — 本地图片/视频元数据

读取本地图片或视频的全部元数据（中文键名输出）。

```python
from xigua.media import MediaMetadataService

# 读取为字典
data = MediaMetadataService.read("/path/to/photo.jpg")

# 直接格式化输出
print(MediaMetadataService.format_file("/path/to/clip.mp4", fmt="text"))
print(MediaMetadataService.format_file("/path/to/clip.mp4", fmt="yaml", include_md5=False))
```

命令行：

```bash
xigua-media /path/to/photo.jpg
xigua-media /path/to/clip.mp4 --fmt text --no-md5
```

**依赖说明：**
- 图片：Pillow（HEIC/HEIF 需 `pip install xigua[heif]`）
- 视频：系统需安装 `ffprobe`

### media.hls — 本地 HLS 多码率转码

```python
from xigua.media.hls import transcode_local_hls, select_hls_rungs

master, tmp = transcode_local_hls("/path/to/video.mov")
if master:
    print(master)
    tmp.cleanup()
```

转码进度条需 `pip install xigua[hls]`（rich）。

### log — 通用日志器

标准库 `logging` 的轻量封装，提供上下文绑定、稳定哈希采样、敏感字段脱敏、JSON/文本输出等能力，方法签名与 `logging.Logger` 保持一致（支持 `%s` 占位符延迟格式化、`exc_info`）。

```python
from xigua.log import get_logger, LoggerConfig

logger = get_logger(
    "my_app",
    config=LoggerConfig(
        level="INFO",
        console=True,
        file_path="logs/app.log",   # 不设置则不写文件，不产生磁盘副作用
        log_format="json",          # "text" 或 "json"
        sample_rate=0.5,            # DEBUG/INFO 采样率，WARNING 及以上始终记录
        sensitive_fields=["password", "token"],
    ),
)

logger.info("处理请求 user_id=%s", 123, extra={"request_id": "abc"})

with logger.context(request_id="abc-123"):
    logger.info("子任务开始")

with logger.timeit("批处理耗时"):
    do_work()

try:
    risky()
except Exception:
    logger.exception("处理失败")
```

同一个 `name` 重复调用 `get_logger()` 会复用同一实例（类似 `logging.getLogger`）。也可以省略 `config`，改用 `LoggerConfig.from_env()` 支持的 `XIGUA_LOG_*` 环境变量（如 `XIGUA_LOG_LEVEL`、`XIGUA_LOG_FORMAT`、`XIGUA_LOG_SAMPLE_RATE` 等）按环境切换配置。

## 安装

```bash
pip install xigua
pip install xigua[heif]   # 支持 HEIC/HEIF
pip install xigua[hls]    # HLS 转码进度条
```

## 发布

```bash
cd /Users/xigua/pypi-publish
./publish xigua --bump patch
```
