my_project/                      # 项目根目录
├── src/                         # 源代码目录
│   ├── __init__.py              # 包初始化
│   ├── module1.py               # 功能模块1
│   ├── module2.py               # 功能模块2
│   └── sub_package/             # 子包
│       ├── __init__.py
│       └── module3.py
├── tests/                       # 测试目录
│   ├── __init__.py
│   ├── test_module1.py
│   └── test_module2.py
├── docs/                        # 文档目录
├── scripts/                      # 脚本目录
├── data/                        # 数据目录
├── notebooks/                   # Jupyter notebooks
├── requirements.txt             # 依赖列表
├── setup.py                     # 安装配置
├── pyproject.toml               # 现代项目配置
├── .gitignore                   # Git 忽略文件
├── .editorconfig                # 编辑器配置
├── README.md                    # 项目说明
└── LICENSE                      # 许可证

# 方式1：src 目录（推荐）
src/
    my_package/
        __init__.py

# 方式2：直接使用包
my_package/
    __init__.py

[build-system]
requires = ["setuptools>=45", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "my_project"
version = "1.0.0"
description = "项目描述"
readme = "README.md"
requires-python = ">=3.10"
license = {text = "MIT"}
authors = [
    {name = "Your Name", email = "you@example.com"}
]
keywords = ["python", "example"]
classifiers = [
    "Development Status :: 4 - Beta",
    "Intended Audience :: Developers",
    "License :: OSI Approved :: MIT License",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
]

dependencies = [
    "requests>=2.28.0",
    "numpy>=1.24.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "black>=22.0.0",
    "ruff>=0.1.0",
    "mypy>=0.950",
]
test = [
    "pytest>=7.0.0",
    "pytest-cov>=4.0.0",
]
docs = [
    "sphinx>=6.0.0",
]

[project.scripts]
my_project = "my_project.cli:main"

[tool.setuptools.packages.find]
where = ["src"]

[tool.black]
line-length = 88
target-version = ["py310"]
include = '\.pyi?$'

[tool.ruff]
line-length = 88
select = ["E", "F", "W", "I"]
ignore = ["E501"]

[tool.mypy]
python_version = "3.10"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = false

[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = "test_*.py"
python_functions = "test_*"

# 使用 venv
python -m venv venv

# 激活（Windows）
venv\Scripts\activate
# 或 PowerShell
venv\Scripts\Activate.ps1

# 激活（macOS/Linux）
source venv/bin/activate

# 退出
deactivate

# 从 requirements.txt 安装
pip install -r requirements.txt

# 从 pyproject.toml 安装
pip install -e .

# 开发模式安装
pip install -e ".[dev]"

# 安装所有可选依赖
pip install -e ".[dev,test,docs]"

# 核心依赖
requests>=2.28.0
numpy>=1.24.0
pandas>=2.0.0

# 开发依赖
pytest>=7.0.0
black>=22.0.0
ruff>=0.1.0
mypy>=0.950

todo_app/
├── src/
│   └── todo/
│       ├── __init__.py
│       ├── models.py
│       ├── storage.py
│       └── cli.py
├── tests/
│   ├── __init__.py
│   └── test_todo.py
├── pyproject.toml
└── README.md

# src/todo/models.py
"""数据模型"""
from dataclasses import dataclass, field
from datetime import datetime
from typing import Literal


@dataclass
class TodoItem:
    """待办事项"""
    id: int
    title: str
    completed: bool = False
    priority: Literal["low", "medium", "high"] = "medium"
    created_at: datetime = field(default_factory=datetime.now)
    completed_at: datetime | None = None

    def complete(self) -> None:
        """标记为完成"""
        self.completed = True
        self.completed_at = datetime.now()

    def uncomplete(self) -> None:
        """标记为未完成"""
        self.completed = False
        self.completed_at = None

    def __str__(self) -> str:
        status = "✓" if self.completed else "✗"
        priority_symbol = {"low": "↓", "medium": "→", "high": "↑"}
        return f"[{status}] {priority_symbol[self.priority}] {self.title}"

# src/todo/storage.py
"""存储层"""
import json
from pathlib import Path
from typing import Literal

from .models import TodoItem


class Storage:
    """JSON 文件存储"""

    def __init__(self, filepath: str = "todos.json") -> None:
        self.filepath = Path(filepath)
        self._todos: dict[int, TodoItem] = {}
        self._load()

    def _load(self) -> None:
        """加载数据"""
        if self.filepath.exists():
            with open(self.filepath, "r", encoding="utf-8") as f:
                data = json.load(f)
                self._todos = {
                    int(k): TodoItem(**v) for k, v in data.items()
                }

    def _save(self) -> None:
        """保存数据"""
        data = {str(k): v.__dict__ for k, v in self._todos.items()}
        with open(self.filepath, "w", encoding="utf-8") as f:
            json.dump(data, f, ensure_ascii=False, indent=2)

    def add(self, title: str, priority: str = "medium") -> TodoItem:
        """添加待办"""
        todo_id = max(self._todos.keys(), default=0) + 1
        todo = TodoItem(id=todo_id, title=title, priority=priority)
        self._todos[todo_id] = todo
        self._save()
        return todo

    def get(self, todo_id: int) -> TodoItem | None:
        """获取待办"""
        return self._todos.get(todo_id)

    def list(self, completed: bool | None = None) -> list[TodoItem]:
        """列出待办"""
        todos = list(self._todos.values())
        if completed is not None:
            todos = [t for t in todos if t.completed == completed]
        return sorted(todos, key=lambda t: (t.completed, t.created_at))

    def complete(self, todo_id: int) -> bool:
        """完成待办"""
        todo = self._todos.get(todo_id)
        if todo:
            todo.complete()
            self._save()
            return True
        return False

    def uncomplete(self, todo_id: int) -> bool:
        """取消完成"""
        todo = self._todos.get(todo_id)
        if todo:
            todo.uncomplete()
            self._save()
            return True
        return False

    def delete(self, todo_id: int) -> bool:
        """删除待办"""
        if todo_id in self._todos:
            del self._todos[todo_id]
            self._save()
            return True
        return False

# src/todo/cli.py
"""命令行接口"""
import sys
from typing import Literal

from .models import TodoItem
from .storage import Storage


def print_header() -> None:
    print("=" * 50)
    print("       待办事项管理器")
    print("=" * 50)


def print_todos(todos: list[TodoItem]) -> None:
    if not todos:
        print("暂无待办事项")
        return

    for todo in todos:
        print(f"  {todo.id:2d}. {todo}")

    print(f"\n共 {len(todos)} 项")


def add_todo(storage: Storage, title: str, priority: str) -> None:
    """添加待办"""
    todo = storage.add(title, priority)
    print(f"✓ 已添加: {todo.title}")


def list_todos(storage: Storage, filter_completed: bool | None) -> None:
    """列出待办"""
    todos = storage.list(filter_completed)
    print_todos(todos)


def complete_todo(storage: Storage, todo_id: int) -> None:
    """完成待办"""
    if storage.complete(todo_id):
        print(f"✓ 已完成待办 #{todo_id}")
    else:
        print(f"✗ 未找到待办 #{todo_id}")


def delete_todo(storage: Storage, todo_id: int) -> None:
    """删除待办"""
    if storage.delete(todo_id):
        print(f"✓ 已删除待办 #{todo_id}")
    else:
        print(f"✗ 未找到待办 #{todo_id}")


def main() -> None:
    """主函数"""
    storage = Storage()

    if len(sys.argv) < 2:
        print_header()
        print("用法: todo <命令> [参数]")
        print("命令:")
        print("  add <标题> [--priority low|medium|high]")
        print("  ls [--completed] [--pending]")
        print("  done <ID>")
        print("  rm <ID>")
        return

    command = sys.argv[1]

    match command:
        case "add":
            if len(sys.argv) < 3:
                print("请输入待办标题")
                return

            title = sys.argv[2]
            priority = "medium"
            if "--priority" in sys.argv:
                idx = sys.argv.index("--priority")
                if idx + 1 < len(sys.argv):
                    priority = sys.argv[idx + 1]

            add_todo(storage, title, priority)

        case "ls" | "list":
            completed: bool | None = None
            if "--completed" in sys.argv:
                completed = True
            elif "--pending" in sys.argv:
                completed = False

            list_todos(storage, completed)

        case "done" | "complete":
            if len(sys.argv) < 3:
                print("请输入待办 ID")
                return

            try:
                todo_id = int(sys.argv[2])
                complete_todo(storage, todo_id)
            except ValueError:
                print("无效的 ID")

        case "rm" | "delete":
            if len(sys.argv) < 3:
                print("请输入待办 ID")
                return

            try:
                todo_id = int(sys.argv[2])
                delete_todo(storage, todo_id)
            except ValueError:
                print("无效的 ID")

        case _:
            print(f"未知命令: {command}")


if __name__ == "__main__":
    main()

# src/todo/__init__.py
"""Todo 应用包"""
from .models import TodoItem
from .storage import Storage

__version__ = "1.0.0"
__all__ = ["TodoItem", "Storage"]

# tests/test_todo.py
"""测试用例"""
import pytest
from datetime import datetime

from todo.models import TodoItem
from todo.storage import Storage


@pytest.fixture
def storage(tmp_path):
    """创建临时存储"""
    filepath = tmp_path / "todos.json"
    return Storage(filepath=str(filepath))


def test_add_todo(storage):
    """测试添加待办"""
    todo = storage.add("学习 Python", "high")
    assert todo.id == 1
    assert todo.title == "学习 Python"
    assert todo.priority == "high"
    assert todo.completed is False


def test_list_todos(storage):
    """测试列出待办"""
    storage.add("任务1")
    storage.add("任务2")

    todos = storage.list()
    assert len(todos) == 2


def test_complete_todo(storage):
    """测试完成待办"""
    todo = storage.add("任务")
    assert todo.completed is False

    storage.complete(todo.id)

    updated = storage.get(todo.id)
    assert updated.completed is True
    assert updated.completed_at is not None


def test_delete_todo(storage):
    """测试删除待办"""
    todo = storage.add("任务")
    result = storage.delete(todo.id)

    assert result is True
    assert storage.get(todo.id) is None


def test_empty_list(storage):
    """测试空列表"""
    todos = storage.list()
    assert len(todos) == 0

[build-system]
requires = ["setuptools>=45", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "todo-app"
version = "1.0.0"
description = "命令行待办事项管理器"
requires-python = ">=3.10"
dependencies = []

[project.scripts]
todo = "todo.cli:main"

[tool.pytest.ini_options]
testpaths = ["tests"]

# 安装
pip install ruff

# 检查代码
ruff check .

# 自动修复
ruff check . --fix

# 格式化代码
ruff format .

# 创建配置
ruff init

# 安装
pip install black

# 格式化
black .

# 检查（不修改）
black --check .

# 自定义行长度
black --line-length 100 .

# 安装
pip install mypy

# 类型检查
mypy src/

# 严格模式
mypy src/ --strict

# 安装
pip install pytest pytest-cov

# 运行测试
pytest

# 带覆盖率
pytest --cov=src --cov-report=html

# 运行特定测试
pytest tests/test_todo.py::test_add_todo

# 初始化仓库
git init

# 克隆仓库
git clone https://github.com/user/repo.git

# 添加文件
git add .
git add file.py

# 提交
git commit -m "feat: 添加新功能"

# 推送
git push origin main

# 拉取
git pull origin main

# 查看状态
git status

# 查看差异
git diff

# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
*.egg-info/
.installed.cfg
*.egg

# 虚拟环境
venv/
ENV/
env/
.venv

# IDE
.vscode/
.idea/
*.swp
*.swo

# 测试
.pytest_cache/
.coverage
htmlcov/
.tox/

# 环境变量
.env
.env.local

# 日志
*.log

# 数据文件
*.json
!example.json
todos.json