Python 套件發布協作實務：從文件撰寫到依賴管理的完整指南

# docs/conf.py 設定範例
# Sphinx 組態檔案，定義文件生成的各項參數

import os
import sys
sys.path.insert(0, os.path.abspath('..'))

# 專案基本資訊設定
project = 'Python 套件管理工具'
copyright = '2025, 玄貓（BlackCat）'
author = '玄貓（BlackCat）'
version = '1.0'
release = '1.0.0'

# Sphinx 擴充功能設定
extensions = [
    'sphinx.ext.autodoc',      # 自動從程式碼產生文件
    'sphinx.ext.napoleon',     # 支援 Google 與 NumPy 風格的 docstring
    'sphinx.ext.viewcode',     # 在文件中加入原始碼連結
    'sphinx.ext.intersphinx',  # 跨專案文件參照
]

# 文件主題設定
html_theme = 'sphinx_rtd_theme'  # 使用 Read the Docs 主題
html_static_path = ['_static']

# 支援繁體中文搜尋
language = 'zh_TW'

# mypackage/core.py 程式碼範例
# 示範如何撰寫符合 Sphinx 規範的 docstring

class DataProcessor:
    """資料處理核心類別
    
    此類別提供資料清理、轉換與驗證功能，適用於各類結構化資料處理場景。
    
    Parameters
    ----------
    config : dict
        處理器組態設定，包含驗證規則與轉換參數
    logger : logging.Logger, optional
        日誌記錄器實例，預設為 None
        
    Attributes
    ----------
    rules : list
        資料驗證規則清單
    transformers : dict
        資料轉換器映射表
        
    Examples
    --------
    建立資料處理器並執行基本操作：
    
    >>> processor = DataProcessor({'validate': True})
    >>> result = processor.process(raw_data)
    >>> print(result.status)
    'success'
    """
    
    def __init__(self, config, logger=None):
        self.config = config
        self.logger = logger
        self.rules = []
        self.transformers = {}
    
    def process(self, data):
        """處理輸入資料
        
        對輸入資料執行驗證與轉換操作，回傳處理結果物件。
        
        Parameters
        ----------
        data : pd.DataFrame
            待處理的原始資料
            
        Returns
        -------
        ProcessResult
            包含處理狀態與結果資料的物件
            
        Raises
        ------
        ValidationError
            當資料驗證失敗時拋出
        TransformError
            當資料轉換失敗時拋出
        """
        # 實際處理邏輯
        pass

# setup.py 完整設定範例
from setuptools import setup, find_packages
import os

# 讀取 README 作為長描述
with open('README.md', 'r', encoding='utf-8') as f:
    long_description = f.read()

# 讀取依賴清單
with open('requirements.txt', 'r', encoding='utf-8') as f:
    requirements = [line.strip() for line in f if line.strip() and not line.startswith('#')]

setup(
    name='python-toolkit',
    version='1.0.0',
    author='玄貓（BlackCat）',
    author_email='blackcat@example.com',
    description='Python 開發工具集，提供資料處理與系統整合功能',
    long_description=long_description,
    long_description_content_type='text/markdown',
    url='https://github.com/blackcat/python-toolkit',
    project_urls={
        'Documentation': 'https://python-toolkit.readthedocs.io',
        'Bug Reports': 'https://github.com/blackcat/python-toolkit/issues',
        'Source Code': 'https://github.com/blackcat/python-toolkit',
    },
    
    # 套件發現與包含
    packages=find_packages(exclude=['tests', 'docs', 'examples']),
    include_package_data=True,
    
    # 依賴管理
    install_requires=requirements,
    extras_require={
        'dev': [
            'pytest>=7.0.0',
            'pytest-cov>=4.0.0',
            'flake8>=5.0.0',
            'black>=22.0.0',
        ],
        'docs': [
            'sphinx>=5.0.0',
            'sphinx-rtd-theme>=1.0.0',
        ],
    },
    
    # Python 版本需求
    python_requires='>=3.8',
    
    # 分類資訊
    classifiers=[
        'Development Status :: 5 - Production/Stable',
        'Intended Audience :: Developers',
        'Topic :: Software Development :: Libraries :: Python Modules',
        'License :: OSI Approved :: MIT License',
        'Programming Language :: Python :: 3',
        'Programming Language :: Python :: 3.8',
        'Programming Language :: Python :: 3.9',
        'Programming Language :: Python :: 3.10',
        'Programming Language :: Python :: 3.11',
        'Operating System :: OS Independent',
    ],
    
    # 命令列工具入口點
    entry_points={
        'console_scripts': [
            'pytoolkit=python_toolkit.cli:main',
        ],
    },
    
    # 套件資料
    package_data={
        'python_toolkit': ['config/*.yaml', 'templates/*.jinja2'],
    },
)

# MANIFEST.in 檔案範例
# 指定需要包含在發布套件中的額外檔案

include LICENSE
include README.md
include CHANGELOG.md
include requirements.txt
include requirements-dev.txt

recursive-include python_toolkit/config *.yaml *.yml
recursive-include python_toolkit/templates *.jinja2
recursive-include docs *.rst *.md
recursive-include examples *.py *.ipynb
recursive-include tests *.py

global-exclude __pycache__
global-exclude *.py[cod]
global-exclude .DS_Store

# 建立發布套件的完整流程
# 清理舊的建置檔案
rm -rf build/ dist/ *.egg-info

# 更新建置工具
python -m pip install --upgrade setuptools wheel twine

# 建立發布套件
python setup.py sdist bdist_wheel

# 檢查套件完整性
twine check dist/*

# 本地測試安裝
pip install dist/python-toolkit-1.0.0-py3-none-any.whl

# 上傳至 PyPI
twine upload dist/*

# 版本號管理策略範例
# 建議將版本號定義在獨立模組中統一管理

# python_toolkit/__version__.py
__version__ = '1.0.0'
__version_info__ = tuple(int(i) for i in __version__.split('.'))

# setup.py 中引用版本號
from python_toolkit.__version__ import __version__

setup(
    name='python-toolkit',
    version=__version__,
    # 其他設定...
)

# Pipfile 完整設定範例
# 定義專案的依賴套件與環境設定

[[source]]
name = "pypi"
url = "https://pypi.org/simple"
verify_ssl = true

# 生產環境依賴
[packages]
requests = "==2.31.0"
numpy = ">=1.24.0,<2.0.0"
pandas = "~=2.0.0"
sqlalchemy = "*"
python-dotenv = "==1.0.0"

# 開發環境依賴
[dev-packages]
pytest = "==7.4.0"
pytest-cov = "==4.1.0"
black = "==23.7.0"
flake8 = "==6.1.0"
mypy = "==1.5.0"
ipython = "*"
jupyter = "*"

# Python 版本需求
[requires]
python_version = "3.11"

# Pipenv 行為設定
[pipenv]
allow_prereleases = false

# Pipenv 常用操作指令集
# 建立虛擬環境並安裝依賴
pipenv install

# 安裝開發環境依賴
pipenv install --dev

# 新增套件到生產環境
pipenv install requests

# 新增套件到開發環境
pipenv install --dev pytest

# 更新所有套件到最新相容版本
pipenv update

# 檢查套件安全性漏洞
pipenv check

# 顯示依賴關係樹狀圖
pipenv graph

# 啟動虛擬環境 shell
pipenv shell

# 在虛擬環境中執行指令
pipenv run python script.py

# 移除虛擬環境
pipenv --rm

# 產生 requirements.txt 相容格式
pipenv requirements > requirements.txt

# 環境設定自動化腳本範例
# scripts/setup_env.py

import subprocess
import sys
import os

def check_python_version():
    """檢查 Python 版本是否符合需求"""
    required_version = (3, 8)
    current_version = sys.version_info[:2]
    
    if current_version < required_version:
        print(f"錯誤：需要 Python {required_version[0]}.{required_version[1]} 或更高版本")
        print(f"目前版本：Python {current_version[0]}.{current_version[1]}")
        sys.exit(1)
    
    print(f"Python 版本檢查通過：{sys.version}")

def install_pipenv():
    """安裝 Pipenv 工具"""
    try:
        subprocess.run(['pipenv', '--version'], check=True, capture_output=True)
        print("Pipenv 已安裝")
    except (subprocess.CalledProcessError, FileNotFoundError):
        print("正在安裝 Pipenv...")
        subprocess.run([sys.executable, '-m', 'pip', 'install', 'pipenv'], check=True)
        print("Pipenv 安裝完成")

def setup_environment():
    """建立虛擬環境並安裝依賴"""
    print("正在建立虛擬環境...")
    subprocess.run(['pipenv', 'install', '--dev'], check=True)
    print("環境設定完成")
    
    print("\n執行以下指令啟動虛擬環境：")
    print("  pipenv shell")

if __name__ == '__main__':
    print("開始設定專案環境...\n")
    check_python_version()
    install_pipenv()
    setup_environment()
    print("\n環境設定完成！")

# environment.yml 完整設定範例
# 定義跨語言專案的 Conda 環境

name: data-science-project
channels:
  - conda-forge
  - defaults

dependencies:
  # Python 直譯器
  - python=3.11
  
  # 核心科學計算套件
  - numpy=1.24.*
  - scipy=1.11.*
  - pandas=2.0.*
  
  # 資料視覺化
  - matplotlib=3.7.*
  - seaborn=0.12.*
  - plotly=5.15.*
  
  # 機器學習框架
  - scikit-learn=1.3.*
  - tensorflow=2.13.*
  - pytorch=2.0.*
  
  # 資料處理工具
  - jupyter=1.0.*
  - jupyterlab=4.0.*
  - notebook=7.0.*
  
  # C/C++ 編譯工具鏈
  - gcc_linux-64=11.4.*
  - gxx_linux-64=11.4.*
  - cmake=3.27.*
  
  # 系統層級依賴
  - hdf5=1.14.*
  - netcdf4=1.6.*
  
  # 透過 pip 安裝的 Python 套件
  - pip
  - pip:
    - opencv-python==4.8.0.76
    - pillow==10.0.0
    - python-dotenv==1.0.0

# 環境變數設定
variables:
  CUDA_HOME: /usr/local/cuda
  LD_LIBRARY_PATH: /usr/local/cuda/lib64:$LD_LIBRARY_PATH

# Conda 環境管理完整指令
# 從 environment.yml 建立環境
conda env create -f environment.yml

# 啟動指定環境
conda activate data-science-project

# 顯示所有環境清單
conda env list

# 更新環境中的套件
conda env update -f environment.yml --prune

# 匯出目前環境設定
conda env export > environment.yml
conda env export --no-builds > environment.yml

# 複製環境
conda create --name new-env --clone data-science-project

# 移除環境
conda env remove --name data-science-project

# 清理快取釋放空間
conda clean --all

# 檢視環境中已安裝套件
conda list

# 搜尋可用套件
conda search numpy

# 安裝新套件到目前環境
conda install matplotlib

# 更新單一套件
conda update numpy

# 企業級 Conda 設定範例
# .condarc 檔案位於使用者家目錄

channels:
  - https://conda.company.internal/packages  # 企業私有通道
  - conda-forge                               # 社群通道
  - defaults                                  # 官方通道

channel_priority: strict  # 嚴格遵守通道優先順序

# 預設安裝位置
envs_dirs:
  - /data/conda/envs
  - ~/.conda/envs

# 套件快取位置
pkgs_dirs:
  - /data/conda/pkgs
  - ~/.conda/pkgs

# 代理伺服器設定
proxy_servers:
  http: http://proxy.company.internal:8080
  https: https://proxy.company.internal:8080

# SSL 驗證設定
ssl_verify: true
ssl_verify_certificates: /etc/ssl/certs/ca-bundle.crt

# 自動啟動環境
auto_activate_base: false

# 顯示通道 URL
show_channel_urls: true

# setup.py 整合 Sphinx 文件建置範例
from setuptools import setup, Command
from setuptools.command.build_py import build_py
import subprocess
import os
import shutil

class BuildSphinxCommand(Command):
    """自訂命令：建置 Sphinx 文件"""
    
    description = '建置 Sphinx HTML 文件'
    user_options = []
    
    def initialize_options(self):
        pass
    
    def finalize_options(self):
        pass
    
    def run(self):
        """執行 Sphinx 文件建置流程"""
        docs_dir = os.path.join(os.path.dirname(__file__), 'docs')
        build_dir = os.path.join(docs_dir, '_build')
        
        # 清理舊的建置檔案
        if os.path.exists(build_dir):
            shutil.rmtree(build_dir)
        
        # 執行 Sphinx 建置
        subprocess.run(
            ['sphinx-build', '-b', 'html', docs_dir, os.path.join(build_dir, 'html')],
            check=True
        )
        
        print(f"文件已建置完成：{os.path.join(build_dir, 'html')}")

class CustomBuildPy(build_py):
    """擴充標準建置命令，加入文件建置步驟"""
    
    def run(self):
        # 先執行標準建置流程
        build_py.run(self)
        
        # 執行文件建置
        self.run_command('build_sphinx')

setup(
    name='python-toolkit',
    version='1.0.0',
    
    # 註冊自訂命令
    cmdclass={
        'build_sphinx': BuildSphinxCommand,
        'build_py': CustomBuildPy,
    },
    
    # 將建置的文件包含在套件中
    package_data={
        'python_toolkit': ['docs/_build/html/*'],
    },
)

# .readthedocs.yml 設定範例
# Read the Docs 平台的建置設定檔

version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.11"
  
  jobs:
    pre_build:
      - pip install poetry
      - poetry export -f requirements.txt --output requirements.txt --without-hashes

sphinx:
  configuration: docs/conf.py
  fail_on_warning: false

formats:
  - pdf
  - epub

python:
  install:
    - requirements: requirements.txt
    - requirements: docs/requirements.txt
    - method: pip
      path: .

# 自動化版本號管理腳本範例
# scripts/bump_version.py

import re
import sys
from pathlib import Path

def read_version(file_path):
    """從檔案中讀取目前版本號"""
    content = file_path.read_text(encoding='utf-8')
    match = re.search(r"__version__\s*=\s*['\"]([^'\"]+)['\"]", content)
    if not match:
        raise ValueError(f"無法在 {file_path} 中找到版本號")
    return match.group(1)

def parse_version(version_str):
    """解析版本號為數字元組"""
    parts = version_str.split('.')
    if len(parts) != 3:
        raise ValueError(f"版本號格式錯誤：{version_str}")
    return tuple(int(p) for p in parts)

def bump_version(version, bump_type):
    """遞增版本號
    
    bump_type 可為 'major'、'minor' 或 'patch'
    """
    major, minor, patch = parse_version(version)
    
    if bump_type == 'major':
        return f"{major + 1}.0.0"
    elif bump_type == 'minor':
        return f"{major}.{minor + 1}.0"
    elif bump_type == 'patch':
        return f"{major}.{minor}.{patch + 1}"
    else:
        raise ValueError(f"不支援的遞增類型：{bump_type}")

def update_version_file(file_path, new_version):
    """更新版本號檔案"""
    content = file_path.read_text(encoding='utf-8')
    new_content = re.sub(
        r"(__version__\s*=\s*['\"])[^'\"]+(['\"])",
        f"\\g<1>{new_version}\\g<2>",
        content
    )
    file_path.write_text(new_content, encoding='utf-8')
    print(f"已更新 {file_path} 版本號為 {new_version}")

def main():
    if len(sys.argv) != 2:
        print("使用方式：python bump_version.py [major|minor|patch]")
        sys.exit(1)
    
    bump_type = sys.argv[1]
    version_file = Path('python_toolkit/__version__.py')
    
    current_version = read_version(version_file)
    new_version = bump_version(current_version, bump_type)
    update_version_file(version_file, new_version)
    
    print(f"版本號已從 {current_version} 更新為 {new_version}")

if __name__ == '__main__':
    main()

# .github/workflows/ci.yml 持續整合設定範例
# GitHub Actions 自動化測試與檢查流程

name: 持續整合

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  test:
    name: 執行測試與程式碼檢查
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ['3.8', '3.9', '3.10', '3.11']
    
    steps:
      - name: 取出程式碼
        uses: actions/checkout@v3
      
      - name: 設定 Python ${{ matrix.python-version }}
        uses: actions/setup-python@v4
        with:
          python-version: ${{ matrix.python-version }}
      
      - name: 快取依賴套件
        uses: actions/cache@v3
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
          restore-keys: |
            ${{ runner.os }}-pip-
      
      - name: 安裝依賴
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt
          pip install -r requirements-dev.txt
      
      - name: 程式碼風格檢查
        run: |
          flake8 python_toolkit tests
          black --check python_toolkit tests
      
      - name: 型別檢查
        run: |
          mypy python_toolkit
      
      - name: 執行測試
        run: |
          pytest tests/ --cov=python_toolkit --cov-report=xml
      
      - name: 上傳覆蓋率報告
        uses: codecov/codecov-action@v3
        with:
          file: ./coverage.xml
          fail_ci_if_error: true
  
  docs:
    name: 建置文件
    runs-on: ubuntu-latest
    
    steps:
      - name: 取出程式碼
        uses: actions/checkout@v3
      
      - name: 設定 Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      
      - name: 安裝依賴
        run: |
          pip install -r docs/requirements.txt
      
      - name: 建置 Sphinx 文件
        run: |
          cd docs
          make html
      
      - name: 部署到 GitHub Pages
        if: github.ref == 'refs/heads/main'
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/_build/html

# 安全性檢查工具使用範例
# 使用 pip-audit 掃描 Python 套件漏洞
pip install pip-audit
pip-audit

# 使用 safety 檢查已知安全問題
pip install safety
safety check

# Pipenv 內建安全檢查
pipenv check

# 更新有安全問題的套件
pip install --upgrade package-name
pipenv update package-name

# .github/dependabot.yml 自動化依賴更新設定
# Dependabot 會定期檢查並建立更新 PR

version: 2
updates:
  # Python 依賴更新
  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "weekly"
      day: "monday"
      time: "09:00"
    open-pull-requests-limit: 10
    reviewers:
      - "blackcat"
    labels:
      - "dependencies"
      - "python"
    commit-message:
      prefix: "chore"
      include: "scope"
    
    # 依賴群組設定
    groups:
      production-dependencies:
        patterns:
          - "requests"
          - "numpy"
          - "pandas"
      development-dependencies:
        patterns:
          - "pytest*"
          - "black"
          - "flake8"
    
    # 忽略特定更新
    ignore:
      - dependency-name: "django"
        update-types: ["version-update:semver-major"]

# CONTRIBUTING.md 貢獻指南範例

# 貢獻指南

感謝您考慮為本專案做出貢獻！我們歡迎各種形式的貢獻，包括錯誤回報、功能建議、文件改善與程式碼貢獻。

## 開發環境設定

1. Fork 本專案並 clone 到本地：
   ```bash
   git clone https://github.com/your-username/python-toolkit.git
   cd python-toolkit