Metadata-Version: 2.3
Name: tools-for-dev
Version: 0.1.1
Summary: Add your description here
Requires-Dist: devtools>=0.12.2
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# tools-for-dev

基于 DEBUG 环境变量控制的 Python 开发调试工具库

## 功能特性

- **`debug_only`** - 装饰器，仅在 DEBUG 模式下执行函数
- **`debug_print`** - 仅在 DEBUG 模式下输出的调试打印
- **`debug_pprint`** - 仅在 DEBUG 模式下输出的美化打印
- **`is_debug`** - DEBUG 环境变量检测

## 安装

使用 uv 安装：

```bash
uv add tools-for-dev
```

使用 pip 安装：

```bash
pip install tools-for-dev
```

## 快速开始

### 设置 DEBUG 环境变量

```bash
# Linux / macOS
export DEBUG=1

# Windows (PowerShell)
$env:DEBUG=1
```

### 使用示例

```python
from tools_for_dev import debug_only, debug_print, debug_pprint

# 使用 debug_print
debug_print("这是一条调试信息")
debug_print("变量值:", {"name": "test", "value": 42})

# 使用 debug_pprint（美化打印）
debug_pprint({"user": {"name": "Buffalo", "age": 25}})

# 使用 debug_only 装饰器
@debug_only()
def my_debug_function():
    print("仅在 DEBUG 模式下执行")
    return "debug result"

result = my_debug_function()
# DEBUG=1 时返回 "debug result"，否则返回 None

# 强制启用装饰器（不受环境变量影响）
@debug_only(enable=True)
def always_enabled():
    print("始终执行")
```

## API 文档

### `debug_only(enable: bool = False)`

装饰器工厂函数，控制被装饰函数仅在 DEBUG 模式下执行。

- `enable`: 如果设为 `True`，强制启用装饰器，不受环境变量影响

### `debug_print(*args, **kwargs)`

基于 `devtools.debug` 的调试打印，仅在 DEBUG 模式下输出。

### `debug_pprint(*args, **kwargs)`

基于 `devtools.pprint` 的美化打印，仅在 DEBUG 模式下输出。

### `is_debug() -> bool`

检测当前是否处于 DEBUG 模式，通过读取 `DEBUG` 环境变量判断。

**注意**：当前实现使用 `os.getenv("DEBUG", False)`，当环境变量设置为任意值（包括 `DEBUG=0`）时均会返回 `True`。如需更精确的控制，建议修改为：

```python
def is_debug() -> bool:
    return os.getenv("DEBUG", "").lower() in ("1", "true", "yes")
```

## 开发

### 安装开发依赖

```bash
uv sync
```

### 运行测试

```bash
uv run pytest
```

### 运行测试（带覆盖率）

```bash
uv run pytest --cov
```

### 构建

```bash
uv build
```

## 依赖

- Python >= 3.11
- devtools >= 0.12.2

## 开发依赖

- allure-pytest >= 2.16.0
- pytest-cov >= 7.1.0
- pytest-mock >= 3.15.1

## 许可证

MIT License

## 作者

Buffalo