Python项目打包与发布的三大工具(setuptools、Poetry、Flit)使用完全指南

# pyproject.toml（现代 setuptools 写法）
[build-system]
requires = ["setuptools>=68", "wheel"]
build-backend = "setuptools.backends.legacy:build"

[project]
name = "myawesome-lib"
version = "1.0.0"
description = "一个很棒的 Python 库"
readme = "README.md"
license = {text = "MIT"}
authors = [
    {name = "Your Name", email = "you@example.com"}
]
requires-python = ">=3.8"
dependencies = [
    "requests>=2.28.0",
    "click>=8.0",
]

[project.optional-dependencies]
dev = ["pytest>=7.0", "black", "mypy"]
docs = ["sphinx", "sphinx-rtd-theme"]

[project.scripts]
mylib-cli = "mylib.cli:main"

[project.urls]
Homepage = "https://github.com/yourname/mylib"
Documentation = "https://mylib.readthedocs.io"

# 创建新项目
poetry new myawesome-lib

# 目录结构自动生成
myawesome-lib/
├── pyproject.toml
├── README.md
├── myawesome_lib/
│   └── __init__.py
└── tests/
    └── __init__.py

[tool.poetry]
name = "myawesome-lib"
version = "0.1.0"
description = "一个很棒的 Python 库"
authors = ["Your Name <you@example.com>"]
readme = "README.md"
license = "MIT"
homepage = "https://github.com/yourname/myawesome-lib"
repository = "https://github.com/yourname/myawesome-lib"
keywords = ["python", "library"]
classifiers = [
    "Development Status :: 3 - Alpha",
    "Intended Audience :: Developers",
]

[tool.poetry.dependencies]
python = "^3.8"
requests = "^2.28.0"
click = "^8.0"

[tool.poetry.group.dev.dependencies]
pytest = "^7.0"
black = "^23.0"
mypy = "^1.0"

[tool.poetry.scripts]
mylib-cli = "myawesome_lib.cli:main"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

# 添加依赖（自动更新 pyproject.toml 和 poetry.lock）
poetry add requests

# 添加开发依赖
poetry add --group dev pytest black

# 安装所有依赖（包含 lock 文件确保版本一致）
poetry install

# 运行项目内命令
poetry run python main.py
poetry run pytest

# 构建发行包
poetry build
# 输出：dist/myawesome_lib-0.1.0.tar.gz
#       dist/myawesome_lib-0.1.0-py3-none-any.whl

# 发布到 PyPI（一键完成）
poetry publish

[tool.poetry.dependencies]
requests = "^2.28.0"   # 兼容 2.x，不升级到 3.x
click = "~8.0.0"       # 只允许补丁版本升级
numpy = ">=1.20,<2.0"  # 区间限定
flask = "*"             # 任意版本（不推荐）

# pyproject.toml
[build-system]
requires = ["flit_core>=3.4"]
build-backend = "flit_core.buildapi"

[project]
name = "mylib"
dynamic = ["version", "description"]  # 从代码中读取
readme = "README.md"
license = {file = "LICENSE"}
authors = [{name = "Your Name", email = "you@example.com"}]
requires-python = ">=3.8"
dependencies = ["requests"]

# mylib/__init__.py
"""一个极简的 Python 库。"""  # 这是包的 description

__version__ = "1.0.0"         # 这是版本号

# 构建
flit build

# 发布
flit publish

# 初始化项目
poetry new filestats
cd filestats

# filestats/core.py
from pathlib import Path
from collections import defaultdict
from dataclasses import dataclass

@dataclass
class FileStats:
    count: int = 0
    total_size: int = 0
    
    @property
    def size_mb(self) -> float:
        return self.total_size / (1024 * 1024)

def analyze_directory(
    path: str | Path,
    recursive: bool = True
) -> dict[str, FileStats]:
    """分析目录中各类型文件的统计信息"""
    root = Path(path)
    if not root.exists():
        raise FileNotFoundError(f"路径不存在：{path}")
    
    stats: dict[str, FileStats] = defaultdict(FileStats)
    
    pattern = "**/*" if recursive else "*"
    for file_path in root.glob(pattern):
        if not file_path.is_file():
            continue
        
        suffix = file_path.suffix.lower() or "(无扩展名)"
        stats[suffix].count += 1
        stats[suffix].total_size += file_path.stat().st_size
    
    return dict(sorted(stats.items(), key=lambda x: x[1].count, reverse=True))

# filestats/cli.py
import click
from pathlib import Path
from .core import analyze_directory

@click.command()
@click.argument("path", default=".", type=click.Path(exists=True))
@click.option("--no-recursive", is_flag=True, help="不递归子目录")
@click.option("--top", default=10, help="显示前 N 种文件类型")
def main(path: str, no_recursive: bool, top: int) -> None:
    """统计目录中各类型文件的数量和大小"""
    try:
        stats = analyze_directory(path, recursive=not no_recursive)
    except FileNotFoundError as e:
        click.echo(f"错误：{e}", err=True)
        raise click.Abort()
    
    click.echo(f"\n📁 分析路径：{Path(path).resolve()}")
    click.echo(f"{'扩展名':<15} {'数量':>8} {'大小(MB)':>12}")
    click.echo("-" * 38)
    
    for ext, stat in list(stats.items())[:top]:
        click.echo(f"{ext:<15} {stat.count:>8} {stat.size_mb:>11.2f}")
    
    total_files = sum(s.count for s in stats.values())
    click.echo(f"\n共计 {total_files} 个文件，{len(stats)} 种类型")

[tool.poetry.scripts]
filestats = "filestats.cli:main"

poetry install
poetry run filestats /path/to/any/directory --top 5

# tests/test_core.py
import pytest
from pathlib import Path
import tempfile
from filestats.core import analyze_directory, FileStats

@pytest.fixture
def temp_dir(tmp_path: Path) -> Path:
    """创建测试用临时目录"""
    (tmp_path / "a.py").write_text("print('hello')")
    (tmp_path / "b.py").write_text("x = 1")
    (tmp_path / "readme.md").write_text("# Test")
    subdir = tmp_path / "sub"
    subdir.mkdir()
    (subdir / "c.py").write_text("pass")
    return tmp_path

def test_analyze_directory_counts(temp_dir: Path) -> None:
    stats = analyze_directory(temp_dir)
    assert stats[".py"].count == 3
    assert stats[".md"].count == 1

def test_analyze_directory_non_recursive(temp_dir: Path) -> None:
    stats = analyze_directory(temp_dir, recursive=False)
    assert stats[".py"].count == 2  # 不含子目录

def test_invalid_path() -> None:
    with pytest.raises(FileNotFoundError):
        analyze_directory("/nonexistent/path")

poetry run pytest --cov=filestats

poetry config pypi-token.pypi pypi-AgEIcHlwaS5vcmcXXXXXXXXX
poetry config pypi-token.testpypi pypi-AgEIcHlwaS5vcmcYYYYYYYYY

# Poetry 提供便捷的版本管理命令
poetry version patch   # 1.0.0 → 1.0.1
poetry version minor   # 1.0.0 → 1.1.0
poetry version major   # 1.0.0 → 2.0.0

# 步骤一：构建发行包
poetry build

# 验证构建结果
ls dist/
# filestats-0.1.0.tar.gz
# filestats-0.1.0-py3-none-any.whl

# 步骤二：先发布到 TestPyPI 验证
poetry publish --repository testpypi

# 步骤三：在新环境中测试安装
pip install --index-url https://test.pypi.org/simple/ filestats
filestats --help  # 验证功能正常

# 步骤四：确认无误后发布正式版
poetry publish

# .github/workflows/publish.yml
name: Publish to PyPI

on:
  push:
    tags:
      - "v*"  # 推送 tag 时触发

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.11"
      
      - name: Install Poetry
        run: pip install poetry
      
      - name: Install dependencies
        run: poetry install
      
      - name: Run tests
        run: poetry run pytest
      
      - name: Build and publish
        env:
          POETRY_PYPI_TOKEN_PYPI: ${{ secrets.PYPI_TOKEN }}
        run: |
          poetry build
          poetry publish

poetry version patch
git add pyproject.toml
git commit -m "chore: bump version to $(poetry version -s)"
git tag v$(poetry version -s)
git push && git push --tags
# GitHub Actions 自动完成后续发布

# filestats

[![外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传](https://img-home.csdnimg.cn/images/20230724024159.png?origin_url=https%3A%2F%2Fbadge.fury.io%2Fpy%2Ffilestats.svg&pos_id=img-jHHE1z5y-1772663561917)](https://pypi.org/project/filestats/)
[![外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传](https://img-home.csdnimg.cn/images/20230724024159.png?origin_url=https%3A%2F%2Fimg.shields.io%2Fbadge%2Fpython-3.8%2B-blue.svg&pos_id=img-8fTVZX00-1772663561919)](https://www.python.org/)

> 快速统计目录中各类型文件的工具

## 安装

\```bash
pip install filestats
\```

## 快速开始

\```bash
# 统计当前目录
filestats .

# 不递归，只显示前 5 种类型
filestats /path/to/dir --no-recursive --top 5
\```

## 作为库使用

\```python
from filestats import analyze_directory
stats = analyze_directory("/path/to/dir")
\```

# pyproject.toml 中明确包含
[tool.setuptools.package-data]
mylib = ["*.json", "*.yaml", "data/*"]

[tool.poetry]
include = ["filestats/data/*.json"]
exclude = ["filestats/tests/*"]

# ❌ 过于宽松——可能引入不兼容版本
requests = "*"

# ❌ 过于严格——妨碍用户使用其他兼容版本
requests = "2.28.1"

# ✓ 推荐：允许兼容的次版本更新
requests = "^2.28.0"

# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 极速安装依赖
uv pip install requests  # 比 pip 快 10 倍以上

# 未来：uv 可能统一包管理与项目管理
uv init myproject
uv add requests
uv run python main.py

# 在 PyPI 项目设置中配置 GitHub Actions 可信发布后
- name: Publish to PyPI
  uses: pypa/gh-action-pypi-publish@release/v1
  # 不需要任何密钥！OIDC 自动认证