Python脚本封装成库：从模块化到PyPI发布的完整指南

1. 为什么要把 Python 脚本封装成库当你写了一个能解决实际问题的 Python 脚本比如处理 Excel 表格、调用某个接口、或者做数据清洗最直接的使用方式就是打开终端输入python your_script.py。但如果你想让同事、其他项目或者未来的自己更方便地复用这段代码直接传脚本文件会显得很业余。封装成库的核心价值有三个可复用性别人不需要看懂你的脚本内部逻辑只需要import你的库调用几个函数就能完成操作。可维护性当脚本需要修改时你只需要更新库的版本所有依赖这个库的项目都能受益。可分发性你可以把库上传到 PyPI其他人用pip install就能安装无需手动复制文件。很多人在这一步容易踩坑把一堆全局变量和直接执行的代码混在一起导致别人根本无法导入。封装的第一步其实是先理清哪些代码是给别人用的接口哪些是内部实现细节。2. 从脚本到模块的最小改造假设你有一个处理 CSV 文件的脚本csv_processor.py原本长这样import csv input_file data.csv output_file cleaned_data.csv def clean_data(): with open(input_file, r) as f: reader csv.reader(f) rows [row for row in reader] # 一些数据处理逻辑 cleaned_rows [] for row in rows: if row and row[0] ! : cleaned_rows.append(row) with open(output_file, w) as f: writer csv.writer(f) writer.writerows(cleaned_rows) if __name__ __main__: clean_data()这个脚本能直接运行但如果别人想在自己的代码中调用clean_data函数会遇到两个问题input_file和output_file是硬编码的而且直接运行会立即执行清洗逻辑。最小改造方案import csv def clean_data(input_file, output_file): 清洗 CSV 文件数据 Args: input_file: 输入文件路径 output_file: 输出文件路径 with open(input_file, r) as f: reader csv.reader(f) rows [row for row in reader] cleaned_rows [] for row in rows: if row and row[0] ! : cleaned_rows.append(row) with open(output_file, w) as f: writer csv.writer(f) writer.writerows(cleaned_rows) if __name__ __main__: # 只有直接运行脚本时才执行 clean_data(data.csv, cleaned_data.csv)这样改造后别人可以这样使用你的代码from csv_processor import clean_data clean_data(my_data.csv, my_cleaned_data.csv)这就是最简单的模块化。但真正的库还需要考虑更多实际场景。3. 设计合理的包结构当功能变多时单个文件会变得臃肿。这时候需要创建包package结构。一个典型的库结构如下my_data_utils/ ├── __init__.py ├── csv_processor.py ├── excel_utils.py ├── data_validator.py └── constants.py关键文件说明__init__.py让 Python 把这个目录当作包来处理可以在这里定义导入快捷方式按功能分模块每个文件负责一类功能比如 CSV 处理、Excel 处理、数据验证等__init__.py的常见写法from .csv_processor import clean_data, merge_files from .excel_utils import read_excel, write_excel from .data_validator import validate_schema __version__ 0.1.0 __all__ [clean_data, merge_files, read_excel, write_excel, validate_schema]这样用户导入时更简洁import my_data_utils my_data_utils.clean_data(data.csv, output.csv) # 或者 from my_data_utils import clean_data4. 配置 setup.py 或 pyproject.toml要让他人能用pip install安装你的库需要创建打包配置文件。现在推荐使用pyproject.toml[build-system] requires [setuptools61.0, wheel] build-backend setuptools.build_meta [project] name my-data-utils version 0.1.0 authors [ {name Your Name, email your.emailexample.com}, ] description A utility library for data processing readme README.md license {text MIT} keywords [csv, excel, data-processing] classifiers [ Development Status :: 3 - Alpha, Intended Audience :: Developers, License :: OSI Approved :: MIT License, Programming Language :: Python :: 3, Programming Language :: Python :: 3.8, Programming Language :: Python :: 3.9, Programming Language :: Python :: 3.10, ] dependencies [ openpyxl3.0.0, # 如果有依赖库 ] [project.urls] Homepage https://github.com/yourusername/my-data-utils Bug Reports https://github.com/yourusername/my-data-utils/issues传统的setup.py写法仍然有效from setuptools import setup, find_packages with open(README.md, r, encodingutf-8) as fh: long_description fh.read() setup( namemy-data-utils, version0.1.0, authorYour Name, author_emailyour.emailexample.com, descriptionA utility library for data processing, long_descriptionlong_description, long_description_content_typetext/markdown, packagesfind_packages(), classifiers[ Development Status :: 3 - Alpha, Intended Audience :: Developers, License :: OSI Approved :: MIT License, Programming Language :: Python :: 3, Programming Language :: Python :: 3.8, ], python_requires3.8, install_requires[ openpyxl3.0.0, ], )5. 添加必要的元数据和文档README.md 是门面应该包含# My Data Utils 一个用于数据处理实用工具库。 ## 安装 bash pip install my-data-utils快速开始from my_data_utils import clean_data # 清洗 CSV 文件 clean_data(input.csv, output.csv)功能特性CSV 文件清洗和处理Excel 文件读写数据格式验证API 文档clean_data(input_file, output_file)清洗 CSV 文件数据...许可证MIT**代码文档字符串**也很重要 python def clean_data(input_file, output_file, skip_emptyTrue): 清洗 CSV 文件数据移除空行和无效数据 Args: input_file (str): 输入 CSV 文件路径 output_file (str): 输出 CSV 文件路径 skip_empty (bool): 是否跳过空行默认为 True Returns: bool: 处理成功返回 True失败返回 False Raises: FileNotFoundError: 当输入文件不存在时 PermissionError: 当没有文件读写权限时 Example: clean_data(data.csv, cleaned.csv) True # 实现代码...6. 本地测试和打包发布本地安装测试# 在项目目录下 pip install -e . # 测试导入 python -c import my_data_utils; print(my_data_utils.__version__)打包命令# 安装构建工具 pip install build twine # 构建分发包 python -m build # 检查打包文件 twine check dist/* # 上传到 PyPI测试版 twine upload --repository-url https://test.pypi.org/legacy/ dist/* # 上传到正式 PyPI twine upload dist/*7. 版本管理和兼容性处理版本号规范语义化版本MAJOR.MINOR.PATCH如1.2.3MAJOR不兼容的 API 修改MINOR向下兼容的功能新增PATCH向下兼容的问题修复兼容性处理技巧# 在 __init__.py 中处理导入兼容 try: from .new_feature import advanced_clean except ImportError: # 如果依赖不满足提供降级方案 def advanced_clean(*args, **kwargs): raise ImportError(advanced_clean requires additional dependencies) # 弃用警告 import warnings def old_function(): warnings.warn( old_function is deprecated, use new_function instead, DeprecationWarning, stacklevel2 ) return new_function()8. 高级封装技巧使用类封装复杂状态class DataProcessor: 数据处理器的类封装 def __init__(self, config_fileNone): self.config self._load_config(config_file) self.stats {processed: 0, failed: 0} def process_directory(self, directory_path): 处理整个目录的文件 for file_path in self._find_data_files(directory_path): try: self.process_file(file_path) self.stats[processed] 1 except Exception as e: self.stats[failed] 1 print(fFailed to process {file_path}: {e}) def process_file(self, file_path): 处理单个文件 # 具体实现 pass def _load_config(self, config_file): 加载配置的私有方法 pass def _find_data_files(self, directory): 查找数据文件的私有方法 pass使用装饰器提供额外功能import time from functools import wraps def timer(func): 计时装饰器 wraps(func) def wrapper(*args, **kwargs): start_time time.time() result func(*args, **kwargs) end_time time.time() print(f{func.__name__} executed in {end_time - start_time:.2f} seconds) return result return wrapper def validate_input(required_type): 输入验证装饰器 def decorator(func): wraps(func) def wrapper(input_data, *args, **kwargs): if not isinstance(input_data, required_type): raise TypeError(fInput must be {required_type}, got {type(input_data)}) return func(input_data, *args, **kwargs) return wrapper return decorator # 使用装饰器 timer validate_input(str) def process_text(text, methodclean): # 处理文本 pass9. 错误处理和日志配置合理的错误处理import logging # 设置日志 logger logging.getLogger(__name__) def robust_data_processing(input_file, output_file): 带错误处理的数据处理函数 try: # 检查输入文件 if not os.path.exists(input_file): raise FileNotFoundError(fInput file {input_file} not found) # 检查文件权限 if not os.access(input_file, os.R_OK): raise PermissionError(fNo read permission for {input_file}) # 处理逻辑 with open(input_file, r, encodingutf-8) as f: data f.read() processed_data process_content(data) # 确保输出目录存在 os.makedirs(os.path.dirname(output_file), exist_okTrue) with open(output_file, w, encodingutf-8) as f: f.write(processed_data) logger.info(fSuccessfully processed {input_file} to {output_file}) return True except Exception as e: logger.error(fFailed to process {input_file}: {e}) return False10. 测试和持续集成编写测试用例# tests/test_csv_processor.py import unittest import tempfile import os from my_data_utils.csv_processor import clean_data class TestCSVProcessor(unittest.TestCase): def setUp(self): 测试前准备 self.temp_dir tempfile.mkdtemp() def test_clean_data_basic(self): 测试基本数据清洗功能 # 创建测试文件 input_file os.path.join(self.temp_dir, test.csv) output_file os.path.join(self.temp_dir, output.csv) with open(input_file, w) as f: f.write(name,age\nJohn,25\n,30\nAlice,\n) # 执行清洗 result clean_data(input_file, output_file) self.assertTrue(result) self.assertTrue(os.path.exists(output_file)) def tearDown(self): 测试后清理 import shutil shutil.rmtree(self.temp_dir) if __name__ __main__: unittest.main()GitHub Actions 自动化测试# .github/workflows/test.yml name: Tests on: [push, pull_request] jobs: test: runs-on: ubuntu-latest strategy: matrix: python-version: [3.8, 3.9, 3.10] steps: - uses: actions/checkoutv3 - name: Set up Python ${{ matrix.python-version }} uses: actions/setup-pythonv4 with: python-version: ${{ matrix.python-version }} - name: Install dependencies run: | python -m pip install --upgrade pip pip install -e .[dev] - name: Run tests run: | python -m pytest tests/ -v封装成库不是一蹴而就的过程我建议先从最小可用的模块开始然后根据实际使用需求逐步完善。重点是要保持接口的稳定性一旦发布版本就要尽量保持向后兼容。每次修改都问自己这个改动会不会让现有的用户代码报错如果会就要考虑版本号升级和适当的迁移指导。