# tmyPyTools

**Repository Path**: taominyao/tmyPyTools

## Basic Information

- **Project Name**: tmyPyTools
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-18
- **Last Updated**: 2025-12-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

🐍 现代 Python 项目结构模板：tmyPyTools

1. [ ] 说明：这是一个现代、清晰、可维护性强的 Python 项目结构，适用于 CLI 工具、Web 后端、数据分析管道、Python 库（发布到 PyPI）等场景。


📂 项目结构树
```
tmyPyTools/
│
├── docs/                       # 文档（Sphinx / MkDocs / Markdown）
│   └── index.md
│
├── examples/                   # 使用示例（对库项目尤其重要） 展示如何调用你的包（比文档更直观）。
│   └── quickstart.py           # 快速入门示例，展示基本用法。
│
├── scripts/                    # 运维/部署/数据处理等脚本 非 Python 核心逻辑，但对项目运行至关重要
│   ├── deploy.sh               # 部署到服务器或云平台
│   └── seed_db.py              # 初始化数据库（如创建表、插入初始数据）
│
├── src/                        # ← 源代码目录 源码放这里（避免开发时因当前目录在 PYTHONPATH 中而意外导入本地未安装的包（即“开发污染”））
│   └── tmy_package/            # ← 实际的 Python 包（名字可自定义）,必须包含 __init__.py（即使为空），使其成为合法的 Python 包。
│       ├── core/               # 核心业务逻辑，存放与领域模型、服务层相关的代码。保持与框架/基础设施解耦（便于测试和复用）。
│       │   ├── __init__.py
│       │   ├── models.py       # 数据模型（Pydantic、SQLAlchemy 等）。
│       │   └── services.py     # 业务逻辑（如用户注册、订单处理）。
│       ├── utils/              # 通用工具函数（与业务无关的辅助函数）。避免过度设计“utils”——只放真正通用的代码
│       │   ├── __init__.py
│       │   └── helpers.py
│       ├── __init__.py         # 标识说明该目录为 Python 包, 可用于控制 from my_package import * 的导出内容（通过 __all__）。可在此初始化日志、配置等。
│       ├── config.py           # 配置管理 集中管理配置（环境变量、默认值等）。 推荐使用 pydantic-settings（原 pydantic.BaseSettings），支持 .env 文件加载（通过 dotenv）
│       └── main.py             # 入口点（如 CLI 或 FastAPI app）如果是 CLI 工具：包含 if __name__ == "__main__": cli(); 如果是 Web 应用（如 FastAPI/Flask）：定义 app = FastAPI() 实例
│
├── tests/                      # 测试（与 src 同级，便于 pytest 发现）结构清晰，区分单元测试和集成测试。
│   ├──integration/             # 集成测试：测试多个模块协作，或与数据库/API 交互。
│   │   └── test_api.py
│   ├── unit/                   # 单元测试：测试单个函数/类，快速、无外部依赖。
│   │   └── test_core.py
│   ├── __init__.py
│   └── conftest.py             # pytest 配置/fixture 定义 fixture（如数据库连接、mock 对象）。设置测试钩子（setup/teardown）。
│
│
├── .editorconfig               # 统一编辑器风格 统一团队编辑器设置（缩进用空格还是 Tab？每行多少字符？）。
├── .gitignore                  # 忽略虚拟环境（venv/）、缓存（__pycache__）、日志等。
├── .pre-commit-config.yaml     # Git 提交前自动格式化/检查
├── docker-compose.yml          # 【可选文件】容器编排（Web/微服务项目）编排多个服务（如 app + db + redis）
├── Dockerfile                  # 【可选文件】定义镜像。
├── LICENSE                     # 开源许可证（MIT、Apache 2.0、GPL 等）。
├── Makefile                    # 常用命令快捷方式（如 make test, make lint） 封装常用命令，提升开发效率
├── pyproject.toml              # ← 现代标准：构建、依赖、工具配置一体化 统一配置：构建系统（如 setuptools、poetry、hatch）、依赖、格式化工具（black、ruff）、测试（pytest）等。
├── README.md                   # 项目简介、安装指南、快速开始、贡献说明。
└── requirements.txt            # （仅当不用 pyproject.toml 管理依赖时） ❌ 不建议与 pyproject.toml 共存（会造成依赖冲突）。
```

💡 关键优势：

1. 使用 src/ 布局避免“开发污染”
2. 通过 pyproject.toml 统一管理依赖与工具配置
3. 测试分层（unit / integration）便于 CI 和本地开发
4. 支持 pre-commit、editorconfig 等工程化实践

✅ 适用场景
* 🧰 CLI 工具（命令行程序）
* 🌐 Web 后端服务（FastAPI / Flask）
* 📊 数据分析管道
* 📦 可发布的 Python 库（上传至 PyPI）

📌 提示：此结构遵循 Hynek Schlawack 等 Python 社区专家推荐的最佳实践。