Python项目构建文件清理指南：告别setup.py的现代化实践

背景：从setup.py到pyproject.toml

在python项目的早期开发实践中，setup.py文件是项目配置和构建的核心。通过执行python setup.py clean --all命令，开发者可以方便地清除项目构建过程中产生的所有临时文件和目录。然而，随着python生态系统的发展，pep 517和pep 518的引入推动了标准化构建后端（如build模块）和pyproject.toml文件的普及。现在，项目通常使用pyproject.toml来声明其构建系统依赖和元数据，并通过python -m build等命令进行构建。

这种转变带来了一个问题：对于不再包含setup.py文件的项目，传统的clean命令已不再适用。因此，理解并掌握手动或脚本化清理这些构建产物的方法，对于维护项目整洁和解决潜在的构建问题至关重要。

核心清理目标：常见的构建产物

在没有setup.py的情况下，构建工具（如build、setuptools等）或Python解释器本身在运行过程中会生成一系列临时文件和目录。这些是清理工作的核心目标：

1. __pycache__ 目录

   • 作用： Python解释器为了提高模块加载速度而缓存编译后的字节码（.pyc文件）。
   • 清理原因： 包含旧的或不必要的字节码，可能导致模块行为异常或占用空间。

2. *`.pyc` 文件**

   立即学习“Python免费学习笔记（深入）”；

   • 作用： 编译后的Python字节码文件，通常存在于__pycache__目录中，但在某些情况下也可能直接存在于源代码目录。
   • 清理原因： 同__pycache__，移除过时或冗余的字节码。

3. .swp 文件

   • 作用： 某些文本编辑器（如Vim）在编辑文件时创建的交换文件，用于崩溃恢复。
   • 清理原因： 属于临时文件，通常在编辑器正常退出后自动删除，但异常情况下可能残留。

4. build 目录

   • 作用： 由构建工具（如setuptools、build）生成，包含编译后的C扩展、中间文件、以及打包前的临时构建内容。
   • 清理原因： 存储了项目的中间构建状态，重新构建时应从干净状态开始。

5. dist 目录

   • 作用： 包含最终分发的包文件，如.whl（wheel）和.tar.gz（source distribution）。
   • 清理原因： 移除旧版本或不成功的构建包，确保发布的是最新且正确的版本。

6. *.egg-info 或 *.dist-info 目录

   • 作用： 包含项目的元数据，由setuptools等工具生成。
   • 清理原因： 有时在重新构建或更改项目元数据后，清理这些目录可以避免冲突。

7. 测试缓存目录 (例如 .pytest_cache)

   • 作用： 测试框架（如pytest）为了加速测试运行而缓存的信息。
   • 清理原因： 移除旧的测试结果或缓存，确保测试环境的干净。

8. 类型检查缓存目录 (例如 .mypy_cache)

   • 作用： 类型检查工具（如mypy）缓存的类型信息。
   • 清理原因： 在代码或配置更改后，清理缓存以强制重新检查。

实战清理方法

由于没有统一的clean命令，我们需要通过手动或脚本化的方式来删除这些文件和目录。

1. 手动删除

对于小型项目或不频繁的清理操作，可以直接通过文件管理器导航到项目目录，然后手动删除上述提到的文件和目录。

2. 命令行清理

这是最常用且高效的方法，适用于各种操作系统。

STORYD

帮你写出让领导满意的精美文稿

下载

a. Linux / macOS (使用 find 和 rm)

在终端中，进入项目根目录，然后执行以下命令：

# 清理 __pycache__ 目录
find . -type d -name "__pycache__" -exec rm -rf {} +

# 清理 *.pyc 文件
find . -type f -name "*.pyc" -delete

# 清理 .swp 文件
find . -type f -name "*.swp" -delete

# 清理 build 目录
rm -rf build

# 清理 dist 目录
rm -rf dist

# 清理 *.egg-info 或 *.dist-info 目录
find . -type d -name "*.egg-info" -exec rm -rf {} +
find . -type d -name "*.dist-info" -exec rm -rf {} +

# 清理测试和类型检查缓存
rm -rf .pytest_cache
rm -rf .mypy_cache

# 综合清理命令 (推荐在项目根目录执行)
echo "Cleaning Python build artifacts..."
find . -type d -name "__pycache__" -exec rm -rf {} +
find . -type f -name "*.pyc" -delete
find . -type f -name "*.swp" -delete
rm -rf build dist .pytest_cache .mypy_cache
find . -type d -name "*.egg-info" -exec rm -rf {} +
find . -type d -name "*.dist-info" -exec rm -rf {} +
echo "Cleaning complete."

b. Windows (使用 for /D 和 del)

在PowerShell或命令提示符中，进入项目根目录，然后执行以下命令：

# 清理 __pycache__ 目录
Get-ChildItem -Path . -Recurse -Directory -ErrorAction SilentlyContinue | Where-Object { $_.Name -eq "__pycache__" } | Remove-Item -Recurse -Force

# 清理 *.pyc 文件
Get-ChildItem -Path . -Recurse -Include *.pyc -ErrorAction SilentlyContinue | Remove-Item -Force

# 清理 .swp 文件
Get-ChildItem -Path . -Recurse -Include *.swp -ErrorAction SilentlyContinue | Remove-Item -Force

# 清理 build 目录
Remove-Item -Path "build" -Recurse -Force -ErrorAction SilentlyContinue

# 清理 dist 目录
Remove-Item -Path "dist" -Recurse -Force -ErrorAction SilentlyContinue

# 清理 *.egg-info 或 *.dist-info 目录
Get-ChildItem -Path . -Recurse -Directory -ErrorAction SilentlyContinue | Where-Object { $_.Name -like "*.egg-info" -or $_.Name -like "*.dist-info" } | Remove-Item -Recurse -Force

# 清理测试和类型检查缓存
Remove-Item -Path ".pytest_cache" -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item -Path ".mypy_cache" -Recurse -Force -ErrorAction SilentlyContinue

# 综合清理命令 (推荐在项目根目录执行)
Write-Host "Cleaning Python build artifacts..."
Get-ChildItem -Path . -Recurse -Directory -ErrorAction SilentlyContinue | Where-Object { $_.Name -eq "__pycache__" } | Remove-Item -Recurse -Force
Get-ChildItem -Path . -Recurse -Include *.pyc, *.swp -ErrorAction SilentlyContinue | Remove-Item -Force
Remove-Item -Path "build", "dist", ".pytest_cache", ".mypy_cache" -Recurse -Force -ErrorAction SilentlyContinue
Get-ChildItem -Path . -Recurse -Directory -ErrorAction SilentlyContinue | Where-Object { $_.Name -like "*.egg-info" -or $_.Name -like "*.dist-info" } | Remove-Item -Recurse -Force
Write-Host "Cleaning complete."

3. 利用 .gitignore 文件

虽然.gitignore不能直接清理已存在的文件，但它能阻止这些临时文件被误提交到版本控制系统，从而保持仓库的整洁。在项目的.gitignore文件中添加以下条目：

# Byte-code files
__pycache__/
*.pyc

# Build artifacts
build/
dist/
*.egg-info/
*.dist-info/

# Editor swap files
*.swp

# Testing and type checking caches
.pytest_cache/
.mypy_cache/

# Other common temporary files
.coverage
.venv/ # If you manage virtual environment inside the project folder
venv/

4. 自动化清理脚本或任务运行器

对于大型项目或团队协作，将清理命令封装成一个脚本或使用任务运行器（如Makefile、invoke、npm scripts）是一个更好的选择。

a. Python 清理脚本 (clean.py)

可以在项目根目录创建一个clean.py脚本：

import shutil
import glob
import os

def clean_build_artifacts():
    """Removes common Python build artifacts and temporary files."""
    print("Cleaning Python build artifacts...")

    # Directories to remove
    dirs_to_remove = [
        "build",
        "dist",
        "__pycache__",
        ".pytest_cache",
        ".mypy_cache",
    ]

    for d in dirs_to_remove:
        if os.path.exists(d):
            print(f"  Removing directory: {d}")
            shutil.rmtree(d)

    # Files to remove
    file_patterns_to_remove = [
        "**/*.pyc",
        "**/*.swp",
        "**/*.egg-info",
        "**/*.dist-info",
    ]

    for pattern in file_patterns_to_remove:
        # Use glob.glob with recursive=True for Python 3.5+
        for f in glob.glob(pattern, recursive=True):
            if os.path.isfile(f) or os.path.isdir(f): # Check if it's a file or dir
                print(f"  Removing: {f}")
                if os.path.isfile(f):
                    os.remove(f)
                else: # It's a directory
                    shutil.rmtree(f)

    print("Cleaning complete.")

if __name__ == "__main__":
    clean_build_artifacts()

然后通过 python clean.py 执行清理。

b. Makefile (Linux/macOS)

在项目根目录创建Makefile文件：

.PHONY: clean

clean:
    @echo "Cleaning Python build artifacts..."
    find . -type d -name "__pycache__" -exec rm -rf {} +
    find . -type f -name "*.pyc" -delete
    find . -type f -name "*.swp" -delete
    rm -rf build dist .pytest_cache .mypy_cache
    find . -type d -name "*.egg-info" -exec rm -rf {} +
    find . -type d -name "*.dist-info" -exec rm -rf {} +
    @echo "Cleaning complete."

然后通过 make clean 执行清理。

注意事项

• 谨慎操作： 在执行任何删除命令之前，请务必确认您正在操作正确的目录，并了解这些文件和目录的作用。错误地删除关键文件可能导致项目无法运行。
• 备份： 对于重要项目，在进行大规模清理之前进行备份是一个好习惯。
• 理解通配符： 使用rm -rf *或del *等命令时要格外小心，确保只删除目标文件，避免误删。
• 环境隔离： 始终在项目的虚拟环境（venv或conda env）中进行开发和构建，这有助于将项目依赖和构建产物隔离，避免污染系统环境。
• 区分生产与开发： 在生产环境中，通常只需要部署最终的包文件，不需要保留构建过程中的临时文件。

总结

随着Python项目构建工具和实践的演进，setup.py的传统清理方式已逐渐被淘汰。适应这一变化，掌握手动识别和清理构建产物的方法，并通过命令行工具、.gitignore或自动化脚本来管理项目整洁，是现代Python开发者必备的技能。定期清理不仅能释放磁盘空间，还能避免因旧的构建缓存导致的潜在问题，确保项目始终在一个干净、可控的环境中运行和构建。