Python Best Practices Launchpad

Python ベストプラクティス・ランチパッド

このリポジトリは、uv、ruff、mypy、pytest、および pre-commit を利用した Git フックによる効率的な開発を想定した、実用的な FastAPI REST API を備える最新の Python プロジェクトテンプレートを提供します。堅牢なテスト、コンテナ化、CI/CD 統合を備えた、本番環境対応の Python アプリケーションを構築するためのベストプラクティスを紹介します。

特徴

• FastAPI による REST API： Pydantic モデルを使用したデータ検証機能を備えた、すぐに使える API です。
• Docker と Docker Compose： マルチステージビルドによる本番環境対応のコンテナ化を実現します。
• 依存関係管理に uv を使用： 高速かつ効率的な依存関係の解決と仮想環境の管理を行います。
• Lint とフォーマットに ruff を使用： 一貫したコードスタイルを適用し、エラーを早期に検出して、自動修正機能を提供します。
• 型チェックに mypy を使用： Python コードに静的型付けを追加し、型に関するエラーを防ぎます。
• テストに pytest を使用： ユニットテスト、API テスト、統合テストを含む包括的なテストスイートです。
• Git フックに pre-commit を使用： コミットのたびにコード品質チェックを自動化します。
• GitHub Actions ワークフロー： テストと品質保証のための、すぐに使える CI パイプラインです。
• Dev Container のサポート： VS Code または GitHub Codespaces ですぐに開発を始められる設定が含まれています。

プロジェクト構成

2024-Python-Best-Practices-Launchpad/
├── .github/workflows/       # GitHub workflows for CI/CD
│   └── main.yml             # Main CI workflow
├── .devcontainer/           # Dev Container configuration
│   ├── devcontainer.json    # Dev container settings
│   └── Dockerfile           # Dev container image definition
├── src/                     # Source code directory
│   └── my_package/          # Main package directory
│       ├── __init__.py      # Package initialization
│       ├── api.py           # FastAPI implementation
│       ├── models.py        # Pydantic data models
│       ├── module.py        # Core functionality
│       ├── example.py       # Example calculator class
│       └── run.py           # Script to run the FastAPI server
├── tests/                   # Test directory
│   ├── test_api.py          # Tests for FastAPI endpoints using models
│   ├── test_endpoints.py    # Tests for API endpoints using test client
│   ├── test_module.py       # Tests for core functionality
│   ├── test_example.py      # Tests for example calculator
│   └── integration_test.py  # Integration tests
├── .pre-commit-config.yaml  # Pre-commit hooks configuration
├── docker-compose.yml       # Docker Compose configuration
├── Dockerfile               # Multi-stage production Docker image
├── LICENSE                  # MIT License
├── pyproject.toml           # Project configuration and dependencies
├── pytest.ini               # Pytest configuration
└── README.md                # This file

API の機能

付属の FastAPI アプリケーションは、次の機能を提供します。

• 入力検証機能を備えたデータ処理 API
• 適切なエラー処理とステータスコード
• クロスオリジンリクエスト用の CORS ミドルウェア
• OpenAPI ドキュメントの自動生成（/docs で利用可能）
• リクエスト／レスポンスのスキーマ検証に使用する Pydantic モデル

はじめに

このプロジェクトをセットアップするには、次のいずれかの方法を選択できます。

オプション 1：Dev Container を使用（推奨）

Dev Containers 拡張機能をインストールした VS Code または GitHub Codespaces をお使いの場合、ローカルでセットアップすることなく、すぐに始められます。

1. VS Code + Dev Containers：

   • このリポジトリをクローンします
   • VS Code でリポジトリのフォルダーを開きます
   • 「Reopen in Container」と表示されたら、「Reopen in Container」をクリックします
   • （または、F1 を押して「Reopen in Container」と入力し、表示された項目を選択します）

2. GitHub Codespaces：

   • GitHub リポジトリの「Code」ボタンをクリックします
   • 「Codespaces」タブを選択します
   • 「Create codespace on main」をクリックします

コンテナには必要なツールと依存関係がすべて含まれており、適切に設定された状態ですぐに使用できます。

オプション 2：Docker Compose を使用

Docker Compose を使用して API を実行するには、次のようにします。

# Build and start the container
docker-compose up --build

# API will be available at http://localhost:8000

オプション 3：Linuxbrew/Homebrew を使用したローカルセットアップ

リポジトリをクローンする前に、Linuxbrew（macOS では Homebrew）がインストールされていることを確認してください。

Windows/WSL のセットアップ

1. WSL をインストールする： Microsoft の公式手順に従って WSL をインストールし、Linux ディストリビューション（例：Ubuntu）を選択します。

2. 直接 WSL ターミナルを開く：

   • Windows ターミナル（PowerShell やコマンドプロンプトなど）から wsl を使用しないでください。
   • VS Code の場合： ターミナルタブの「+」ボタンをクリックして新しい統合ターミナルを開き、ドロップダウンメニューから WSL ディストリビューション（例：「Ubuntu」、「Debian」）を選択します。
   • スタートメニューからの場合： または、Windows のスタートメニューから WSL ディストリビューションのターミナル（例：「Ubuntu」、「Debian」）を直接起動します。

   このセクションの以降の手順はすべて、この直接 WSL ターミナル内で実行してください。

3. 基本的な依存関係をインストールする（WSL 内）：

   sudo apt update && sudo apt install -y build-essential curl file git
   

4. Linuxbrew をインストールする：

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   

5. Linuxbrew を PATH に追加する： 使用しているシェルに応じて、次の行を ~/.bashrc または ~/.zshrc に追加します。

   export PATH="/home/linuxbrew/.linuxbrew/bin:$PATH"
   export MANPATH="/home/linuxbrew/.linuxbrew/share/man:$MANPATH"
   export INFOPATH="/home/linuxbrew/.linuxbrew/share/info:$INFOPATH"
   

   次に、source ~/.bashrc または source ~/.zshrc を実行します。

6. Linuxbrew で Python をインストールする： brew install python

macOS

1. Homebrew をインストールする： まだインストールしていない場合は、ターミナルで次のコマンドを実行して Homebrew をインストールします。

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   

2. Homebrew で Python をインストールする： brew install python

Linux

1. Linuxbrew をインストールする： Linuxbrew のホームページにある手順に従います：https://brew.sh/
2. Linuxbrew で Python をインストールする： brew install python

2. プロジェクトのセットアップ

Linuxbrew（または macOS の Homebrew）と Python をインストールしたら、次の手順に進みます。

1. リポジトリをクローンする：

   git clone <repository_url>
   cd <project_name>
   

2. 仮想環境を作成して有効化する：

   uv venv
   

   このコマンドは、仮想環境がまだ存在しない場合に作成します。

3. 依存関係をインストールする：

    uv sync
   

   このコマンドは、開発用依存関係を含め、ロックファイル（uv.lock）に記載されたすべての依存関係をインストールします。

4. Git フックをインストールする：

   pre-commit install
   

   このコマンドは、各コミットの前にフォーマットとリントを自動的に実行する pre-commit フックをインストールします。

5. ロックファイルを作成する：

   uv lock
   

   このコマンドは、プロジェクト内のすべての依存関係を既知のバージョンに固定するロックファイルを作成します。

開発

• API サーバーを実行する： 開発用に FastAPI サーバーをローカルで起動します。

  python -m src.my_package.run
  

  または

  uvicorn my_package.api:app --reload
  

• API ドキュメントにアクセスする： ブラウザーを開き、次の URL にアクセスします。

  • Swagger UI：http://localhost:8000/docs
  • ReDoc：http://localhost:8000/redoc

• テストを実行する： ルートフォルダーで pytest を使用してテストを実行します。

  pytest
  

API エンドポイント

• GET / - API 情報を返すルートエンドポイント
• POST /process - データ項目のリストを処理します
  • 項目の配列と省略可能な名前を含む JSON を受け付けます
  • 処理した項目の平均値、最大値、件数を返します

Docker のサポート

このプロジェクトには、本番環境に対応した Docker 設定が含まれています。

• イメージを小さくするマルチステージビルド
• セキュリティ向上のための非 root ユーザー
• 適切な環境変数
• ヘルスチェック
• リソース制限

Docker でビルドして実行するには：

# Build the image
docker build -t python-best-practices .

# Run the container
docker run -p 8000:8000 python-best-practices

自動リントとフォーマット

• ruff は、変更を保存するとフォーマットとリントのエラーを自動的に修正します。

型チェック

• mypy は pre-commit フックの一部として実行され、型に関する問題を検出します。

設定

コア設定

プロジェクトのコア設定は、pyproject.toml ファイルにあります。

• プロジェクトのメタデータ：
  • 名前、バージョン、説明、作成者などの基本的なプロジェクト情報
  • requires-python で指定する Python のバージョン
• 依存関係：
  • プロジェクトの依存関係は、[project.dependencies 配列に記載されています。
  • 開発用の依存関係は、[project.optional-dependencies.dev] 配列に記載するか、追加のグループを作成できます。

[tool.uv]

• default-groups = ["dev"]：開発用の依存関係をデフォルトでインストールするよう設定します。

[tool.ruff]

• line-length = 100：最大行長を設定します。
• select：ruff や各種リンターから有効にするルールの一覧です。
• ignore：無視するルールの一覧です。
• fix = true：リンティングエラーを自動修正します。
• per-file-ignores：特定のファイルやパターンに対して、特定のルールを無視するよう設定します。
• quote-style = "single"：シングルクォートを使うスタイルに設定します。

[tool.mypy]

• mypy_path = "src"：mypy の型チェックでパッケージを検索する場所です。
• python_version = "3.10"：使用する Python のバージョンです。
• strict = true：厳密な型チェックのオプションを有効にします。
• plugins = ["pytest_mypy_plugins"]：mypy で pytest プラグインを利用できるようにします。

Git フックの設定（.pre-commit-config.yaml）

このファイルでは、各コミットの前にチェックを実行するツール pre-commit を設定します。次の項目が含まれます。

• 汎用フック（pre-commit-hooks）： 末尾の空白の削除、ファイル末尾の改行の強制、YAML の検証など。
• ruff フック（astral-sh/ruff-pre-commit）： Ruff のエラーを自動修正します（ruff --fix）。
• black フック（psf/black）： black フォーマッターでコードを自動的に再フォーマットします。
• mypy フック（pre-commit/mirrors-mypy）： mypy でコードの型エラーをチェックします。

VS Code の設定（.vscode/settings.json）

このファイルでは、VS Code エディターを設定します。

• 型チェック： python.analysis.typeCheckingMode：Python の型チェッカーを有効にします。
• リンティング： python.linting.ruffEnabled：リンターとして ruff を有効にします。
• フォーマット： python.formatting.provider：pre-commit を使用するため、デフォルトのフォーマッターを無効にします。
• Ruff の設定： Ruff 言語サーバーの設定です（例：importStrategy、organizeImports、fixAll、showSyntaxErrors）。
• ruff.configurationPreference：ファイルベースの設定を優先します。

よく使われる便利な設定（基本設定には含まれません）

以下は、よく使われている、または該当する場合に役立つ追加の設定です。

1. Ruff のカスタムルールと無視設定

• [tool.ruff.lint.per-file-ignores]： このセクションを使うと、特定のファイルのルールを無視できます。例：

  [tool.ruff.lint.per-file-ignores]
  "tests/*" = ["S101", "ANN"]  # Allow asserts and skip annotations in tests.
  "src/my_package/legacy.py" = ["B001", "B002"] # Ignore specific bugbear rules for legacy code
  

• extend-select と extend-ignore： プロジェクトにルールを追加したり、ルールを無視したりできます。

  [tool.ruff.lint
  extend-select = ["PT"] # adds rules from flake8-pytest
  extend-ignore = ["ANN101", "ANN401"] # extends the ignore rules
  

• ルール固有のオプション： たとえば isort のオプションなど、特定のルールはさらに設定できます。

  [tool.ruff.lint.isort]
  force-wrap-aliases = true
  

2. Mypy のカスタムオプション

• ignore_missing_imports: 依存関係や型チェックで問題が発生している場合は、true に設定します。

  [tool.mypy]
  ignore_missing_imports = true
  

• disallow_untyped_defs: 関数定義に型注釈を必須にする場合は、disallow_untyped_defs = true を使用します。

  [tool.mypy]
  disallow_untyped_defs = true
  

• disallow_any_explicit: コード内で Any 型を明示的に使用することを禁止する場合に設定します。

  [tool.mypy]
   disallow_any_explicit = true
  

• warn_unreachable: 到達不能なコードに対する警告を有効にする場合に設定します。

  [tool.mypy]
  warn_unreachable = true
  

  使用可能な設定の一覧については、Mypy の設定ドキュメントを参照してください。

3. uv の設定

• constraint-dependencies: 推移的依存関係を特定のバージョンに固定する場合は、constraint-dependencies を使用します。

  [tool.uv]
      constraint-dependencies = ["cryptography<42.0.0"]
  

• override-dependencies: 依存関係に特定のバージョンを強制的に使用させます。

  [tool.uv]
      override-dependencies = ["cryptography==42.0.0"]
  

• index: 依存関係の取得元となる追加のパッケージインデックスを指定できます。

  [[tool.uv.index]]
   name = "pytorch"
   url = "https://download.pytorch.org/whl/cu121"
   explicit = true
  
   [tool.uv.sources]
   torch = { index = "pytorch" }
  

4. テストの設定

• pytest.ini: pytest のオプションを設定するには、ルートフォルダーに pytest.ini を作成します。

  [pytest]
  testpaths = tests
  addopts =
      --cov=src/my_package
      --cov-report term-missing
      -vv
  

  これにより、tests フォルダー内のすべてのテストに対して pytest が実行されます。

  src/my_package のカバレッジ情報も追加されます。

  また、詳細モードで実行されます。

5. pre-commit の設定

他のリポジトリからフックを追加できます。

既存のフックは必要に応じて設定できます。たとえば、ruff の対象からファイルを除外する場合は、次のようにします。

-   id: ruff
    args: ["--fix", "--exclude", "path/to/exclude"]

環境とワークスペースの設定に関するヒント

異なる Python バージョンの使用

• このテンプレートには Python 3.10 以降が必要です
• 複数の Python バージョンがインストールされている場合：
  • Windows では、バージョンを指定するために py -3.10 -m venv .venv を使用します
  • Unix では、python3.10 -m venv .venv を使用します
  • uv では、pyproject.toml の requires-python に Python バージョンを指定します

IDE との連携

1. VS Code

   • Python と Ruff の拡張機能をインストールします
   • コマンドパレットを使用して Python インタープリターを選択します
   • pre-commit フックをインストールした後、VS Code を再起動します
   • 行末を統一するため、「Files: Eol」を「\n」に設定します

2. PyCharm

   • Languages & Frameworks > Python > Ruff で「Ruff」を有効にします
   • 「Editor > Code Style > Line separator」を Unix に設定します
   • pytest をデフォルトのテストランナーとして設定します

仮想環境のベストプラクティス

• 依存関係の競合を避けるため、プロジェクトごとに venv を作成します
• .venv ディレクトリはコミットしないでください（.gitignore に含まれています）
• Windows で UV が失敗する場合は、python -m venv に切り替えます
• 依存関係に問題があると思われる場合は、venv を再構築します

トラブルシューティング

よくある問題

1. ツールのインストール後に「Command not found」エラーが発生する

   • PATH に Linuxbrew/Homebrew の bin ディレクトリが含まれていることを確認してください
   • ターミナルを再起動するか、source ~/.bashrc（またはお使いのシェルに相当するコマンド）を実行してみてください

2. UV 固有の問題

   • uv sync が「Default group 'dev' is not defined」というエラーで失敗する場合は、pyproject.toml の設定を確認してください
   • UV を Python モジュールとして使用する場合（スクリプト内など）は、pip install uv でインストールしてください
   • Windows ユーザーは、仮想環境を作成する際に Python のフルパスを使用する必要がある場合があります：python -m venv .venv

3. サードパーティライブラリの型チェックエラー

   • ライブラリの型スタブをインストールしてください：uv pip install types-libraryname
   • 型スタブが利用できない場合は、pyproject.toml でそのライブラリを mypy の無視リストに追加してください
   • pytest-mypy-plugins を使用していてエラーが発生する場合は、任意の設定項目なので、mypy の設定から削除できます

4. pre-commit フックの設定

   • pre-commit run --all-files を実行すると、詳細なエラーメッセージを確認できます
   • エラーメッセージに従って問題を修正するか、フックの設定を更新してください
   • ruff-format はファイルのフォーマットに成功していても「failed」と表示することがあります。これは想定された動作です
   • ruff の設定で問題が発生した場合は、最小限の設定から始めて、ルールを徐々に追加してください

5. パッケージのインストールと開発モード

   • -e を使って開発モードでインストールする場合は、正しいディレクトリにいることを確認してください
   • Windows で仮想環境を有効化するには、バックスラッシュを使用します：.venv\Scripts\activate
   • 「No source for code」に関するカバレッジ警告が表示される場合は、パッケージが開発モードでインストールされていることを確認してください

6. テストに関する問題

   • 統合テストでは、Windows でもパスにスラッシュを使用してください（pytest で推奨されています）
   • 一時ファイルに関するカバレッジ警告は、統合テスト中は無視して問題ありません
   • テストでファイルを変更する場合は、実際のプロジェクトファイルに影響しないように tempfile.TemporaryDirectory() を使用してください

開発のヒント

1. 効率的なテストのワークフロー

   • 特定のテストファイルを実行します：pytest tests/test_module.py -v
   • カバレッジ付きでテストを実行します：pytest --cov=src/my_package
   • -v フラグを使用すると、テストごとの結果を詳しく確認できます

2. 型チェックのベストプラクティス

   • テスト関数に -> None の戻り値型アノテーションを追加してください
   • テスト内で意図的に型に違反する場合は、# type: ignore コメントを慎重に使用してください
   • 開発の反復を速めるため、pre-commit とは別に mypy を実行することを検討してください

3. コードスタイルとフォーマット

   • pre-commit を通じて ruff にコードのフォーマットを自動で処理させてください
   • 文字列にはシングルクォートを使用してください（ruff の設定で指定されています）
   • 行の長さは 100 文字にしてください（ruff の設定で指定されています）

PyPI へのパッケージの公開

プロジェクトを配布できる状態になったら、Python Package Index（PyPI）に公開して、pip または uv からインストールできるようにします。以下に、パッケージを公開する手順を説明します。

公開に向けたパッケージの準備

1. pyproject.toml が適切に設定されていることを確認します：

   • プロジェクトのメタデータ（名前、バージョン、説明、作者など）を確認してください
   • すべての依存関係が正しく記載されていることを確認してください
   • 明確で分かりやすい README.md が用意されていることを確認してください

2. パッケージ分類子を作成または更新します： ユーザーがパッケージを見つけやすくなるよう、適切な分類子を追加してください：

   [project]
   # ...existing metadata...
   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",
       "Topic :: Software Development :: Libraries",
   ]
   

配布パッケージのビルド

1. ビルドツールをインストールします：

   uv pip install build twine
   

2. パッケージをビルドします：

   python -m build
   

   これにより、ソース配布物（.tar.gz）と wheel 配布物（.whl）の両方が dist/ ディレクトリに作成されます。

TestPyPI でのテスト

メインの PyPI リポジトリに公開する前に、TestPyPI でテストすることをおすすめします。

1. TestPyPI アカウントを作成します： https://test.pypi.org/account/register/ で登録します。

2. 認証情報を設定します： ~/.pypirc を作成または編集します。

   [distutils]
   index-servers =
       pypi
       testpypi
   
   [pypi]
   username = __token__
   password = pypi-AgEIcHlwaS5vcmc...  # Your PyPI API token
   
   [testpypi]
   repository = https://test.pypi.org/legacy/
   username = __token__
   password = pypi-AgEIcHlwaS5vcmc...  # Your TestPyPI API token
   

3. TestPyPI にアップロードします：

   python -m twine upload --repository testpypi dist/*
   

4. TestPyPI からのインストールをテストします：

   uv pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ your-package-name
   

PyPI への公開

TestPyPI ですべてが正しく動作することを確認したら、次の手順に進みます。

1. PyPI アカウントを作成します： https://pypi.org/account/register/ で登録します。

2. API トークンを生成します：

   • https://pypi.org/manage/account/token/ にアクセスします。
   • 「Upload to PyPI」スコープのトークンを作成します。
   • トークンは再表示されないため、安全な場所に保存します。

3. PyPI にアップロードします：

   python -m twine upload dist/*
   

   ユーザー名とパスワード（またはトークン）の入力を求められます。

4. PyPI からのインストールを確認します：

   uv pip install your-package-name
   

GitHub Actions による公開の自動化

GitHub Actions を使って公開プロセスを自動化できます。以下はワークフローの例です。

1. .github/workflows/publish.yml に GitHub Actions ワークフローファイルを作成します。

name: Publish to PyPI

on:
  release:
    types: [created]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: '3.10'
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install build twine
    - name: Build and publish
      env:
        TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }}
        TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
      run: |
        python -m build
        twine upload dist/*

2. GitHub リポジトリにシークレットを追加します：
   • リポジトリの設定に移動します。
   • ［Secrets and variables］>［Actions］に移動します。
   • PYPI_USERNAME を追加します（__token__ を使用します）。
   • PYPI_PASSWORD を追加します（PyPI API トークンを指定します）。

このワークフローを使用すると、新しい GitHub リリースを作成するたびに、新しいパッケージバージョンが自動的に公開されます。

バージョン管理

リリースにはセマンティックバージョニング（MAJOR.MINOR.PATCH）を使用します。

• MAJOR：互換性のない API の変更
• MINOR：後方互換性を保った新機能
• PATCH：後方互換性のあるバグ修正

リリースのたびに、pyproject.toml のバージョンを更新します。

[project]
name = "my_package"
version = "0.2.0"  # Update this line

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細については、LICENSE ファイルを参照してください。

貢献

このテンプレートに機能を追加したい場合や改善を提案したい場合は、お気軽にプルリクエストを作成してください。