初心者向けに Python コードベースを整理して維持する手順

私がこの投稿を書いている理由は、多くの貢献者がいる場合でも、プロジェクトをクリーンに保つための洞察を共有するためです。データの性質が絶えず変化し、Python ライブラリとアプリケーションでの処理要求を考慮すると、これはデータ エンジニアにとって特に重要です。

タイトルは少しクリックしそうに聞こえるかもしれませんが、次の手順に従うと、Python コードの管理がはるかに簡単になります。あなたが上級開発者であれば、おそらくここで何も新しいことは見つからないでしょう。心配しないでください。面白いミームを用意しました。

ステップ 1: バージョン管理

これは些細なことのように思えるかもしれませんが、実際に、コードをローカル コンピューターにのみ保存し、残念ながらコードをどこにもバックアップしなかったために紛失してしまった人を知っています。 GitHub、GitLab、Bitbucket などのプラットフォームで動作する Git など、利用可能なバージョン管理システムがいくつかあります。 Git は多くの人にとって頼りになる選択肢ですが、SVN (Subversion) や Mercurial などの他のバージョン管理システムも依然としてコード管理において重要な役割を果たしています。

このガイドでは、基本的なデータ処理を説明するための 1 つの関数を備えた小さなデモ Python ライブラリの作成を開始します。これは完全なツールキットを意図したものではありませんが、コードの品質、環境管理、CI/CD ワークフローなどのベスト プラクティスを示す簡単な例として機能します。

まず、デモ Python ライブラリのリポジトリを作成し、blog_de_toolkit という名前にしました。これはパブリックなので、自由にフォークして、既存のコードを独自のプロジェクトの開始点として使用してください。適切なドキュメントが不可欠であるため、推奨される空の README ファイルを含めました。また、リポジトリを整理しておくために、デフォルトの Python .gitignore テンプレートを追加して、不要なファイルがアップロードされないようにしました。

リポジトリが作成できたので、それを複製できます。

ここでは Git コマンドについて詳しく説明するつもりはありません。オンラインでチュートリアルがたくさん見つかります。プレーンなターミナル CLI の使用が好きでない場合は、より視覚的で直感的なインターフェイスを提供する GitHub Desktop や SourceTree などのツールを使用してリポジトリを管理することもできます。

個人的には、GitHub Desktop の使用をとても楽しんでいます。それでは、リポジトリのクローンをローカル コンピューターに作成し、好みの IDE で開きましょう。

これまでに得られたことを見てみましょう:

最初としては悪くありません!

ステップ 2: プロジェクトの構造

ステップ 2 では、de_toolkit プロジェクトを整理します。優れた構造により、物が見つけやすくなり、すべてが整理整頓されます。コード、テスト、ドキュメント用のフォルダーを作成し、構築するためのシンプルでクリーンなフレームワークをセットアップします。

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

追加するすべての便利なコード用のメイン フォルダー、将来の単体テスト用の tests フォルダー、および不要なファイルをリポジトリから遠ざけるための .gitignore があります。 setup.py ファイルもあります。これは、プロジェクトをインストール可能にするための基本セットアップです。これについては、後でステップ 8: 配布パッケージを作成するで説明するため、ここでは詳しく説明しません。

プロジェクトの構造を設定するとき、一貫性を保つことは大きな違いを生みます。プロジェクトが成長するにつれて、data_tools.py を csv_tools.py と json_tools.py に分割するなど、小さなモジュールに分割することをお勧めします。こうすることで、長いファイルを調べなくても、必要なものを管理したり見つけたりすることが簡単になります。

docs/ フォルダーを追加することも、たとえいくつかのメモから始まるとしても、賢い選択です。これは、あなた (および他の人) がプロジェクトの進行に伴って物事がどのように機能するかを追跡するのに役立ちます。 YAML や JSON などの構成を使用している場合は、configs/ フォルダーを使用すると、作業を整理するのに役立ちます。また、自動化またはテスト用のスクリプトを作成する予定がある場合は、scripts/ フォルダーにスクリプトを整理しておくと便利です。

この時点で、プロジェクトの構築を続けるために、いくつかの追加ライブラリをインストールする必要があります。

ステップ 3: 開発環境

確かに、コマンドラインから pip install を実行して、必要な依存関係をインストールすることもできます。しかし、それぞれが異なるバージョンの Python とライブラリを必要とする複数のプロジェクトをやりくりしている場合はどうなるでしょうか?そこで仮想環境が登場します。仮想環境は、特定の Python バージョンを含む各プロジェクトの依存関係を分離するため、すべてが自己完結型で独立した状態を保ちます。

幸いなことに、仮想環境を作成するためのツールは数多くあるため、自分にとって最適なものを選択できます。

• virtualenv

• ヴェンヴ

• コンダ

• ピェンヴ

• pipenv

• 詩

個人的に、私は pyenv の大ファンなので、ここではそれを使用します。仕事にも個人的なプロジェクトにも欠かせないものなので、すでにラップトップにインストールしています。

Python をインストールすることから始めましょう:

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

pyenv がこの Python バージョンを認識しない場合は、まず更新してみてください。たとえば、Mac を使用していて、Homebrew で pyenv をインストールした場合は、次を実行します:

pyenv install 3.12.2

「ModuleNotFoundError: No module names '_lzma'」というエラーが発生した場合は、次のことを試してください。

brew update && brew upgrade pyenv

次に、プロジェクト フォルダーに新しい仮想環境を作成しましょう:

brew install readline xz

次に、作成したばかりの仮想環境にローカル Python バージョンを設定します。

pyenv virtualenv 3.12.2 de_toolkit

MacOS でコマンドを実行しても環境が切り替わらない場合は、解決策が記載されたオンラインのスレッドが役立ちます。すべてが正しく設定されると、次のようにコマンド ラインの先頭に de_toolkit が表示されるはずです。

さて、依存関係をインストールしましょう:

pyenv local de_toolkit

次に、インストールされているすべてのパッケージとそのバージョンを、requirements.txt ファイルに保存します。これにより、プロジェクトの依存関係を共有したり、同じ環境を別の場所で再作成したりすることが簡単になります:

pip install setuptools wheel twine pandas 

これが私たちが入手したインストール済みパッケージのリストです:

もちろん、必要に応じて、requirements.txt ファイルを編集して、メイン ライブラリとそのバージョンのみを保持することもできます。

ステップ 4: 認証情報とシークレットの管理

このステップは非常に重要であり、おそらく最も重要なステップの 1 つです。 GitHub リポジトリで資格情報が公開されたり、機密トークンが誤って公開で共有されたりするという恐ろしい話を聞いたことがあるでしょう。これを回避するには、最初からコードに機密情報を含めないようにすることが重要です。そうしないと、データベースのパスワードをハードコーディングし、変更をプッシュし、大騒ぎしたことを忘れがちです。資格情報は公開されています。

パスワード、API キー、データベース認証情報のハードコーディングは、重大なセキュリティ リスクです。これらがパブリック リポジトリに侵入すると、システム全体が危険にさらされる可能性があります。シークレットを処理する最も安全な方法は、シークレットを環境変数または .env ファイルに保存することです。これらの変数を Python プロジェクトにロードしやすくするために、python-dotenv ライブラリを使用します。 .env ファイルからキーと値のペアを読み取り、コード内で環境変数として使用できるようにします。

まず、次のコマンドを使用してライブラリをインストールします。

pip freeze > requirements.txt

次の内容を含む .env ファイルをプロジェクト フォルダーに作成します。

pip install python-dotenv

ここで、python-dotenv:

を使用してこれらのシークレットをロードするように data_tools.py を変更しましょう。

load_dotenv() を呼び出すと、現在のディレクトリで .env ファイルが検索され、その内容が環境にロードされます。 os.getenv() を使用すると、コード内でこれらの変数に安全にアクセスでき、資格情報をソース コードから隔離して、偶発的な公開のリスクを軽減できます。

重要なヒントは、.env ファイルをバージョン管理にコミットしないことです。誤ってプッシュされないように、それを .gitignore に追加します。

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

VSCode を使用している場合は、.env * ファイルを自動的に認識する便利な dotenv 拡張機能があります。ターミナルから作業したい場合は、次のように *.env ファイルをエクスポートできます:

pyenv install 3.12.2

ステップ 5: コードを書く

プロジェクトに取り組むときは、理解しやすく管理しやすい、小さくて再利用可能な関数を作成するようにしてください。良い経験則は次のとおりです: 「2 回以上使用する場合は、関数に変換します。」

data_tools.py で、CSV からデータをロードしてクリーニングするなど、一般的なデータ エンジニアリング ロジックを示す関数を作成しましょう。

プロのヒント: Python の関数名と変数名は snake_case

に限定してください。これにより、コードの一貫性が保たれ、読みやすくなります。 x や df2 のようなわかりにくい名前は避けてください。明確でわかりやすい名前を付けると、コードの操作が容易になります。

ここでは関数の動作、パラメータ、戻り値の型を説明するために docstring を使用します。これにより、他の開発者 (および将来のあなた) が関数の使用方法を理解しやすくなります。よく使われる docstring 規則はいくつかありますが、最も一般的なものには、PEP 257、Google スタイル、および NumPy スタイルが含まれます。

小規模な関数の場合は、多くの場合 PEP 257 で十分ですが、より複雑なプロジェクトの場合は、Google または NumPy スタイルの方がより明確で構造的です。

Python の型ヒント (この例の file_path: str など) は、関数の入力と出力に予期されるデータ型を示します。読みやすさを向上させ、バグを見つけやすくし、明確な期待値を設定することでコラボレーションを容易にします。

型ヒントが関数シグネチャを改善する方法の例を次に示します。

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

この例では、タイプ ヒント file_path: str は引数が文字列であることを示していますが、-> pd.DataFrame は、関数が Pandas DataFrame を返すことを示します。これにより、関数の動作が一目で分かりやすくなります。型ヒントは、PyCharm、VSCode、mypy などの IDE やリンターでも機能し、互換性のない型が渡された場合にオートコンプリートと早期警告を提供します。

関数が複数の型または None を返すことができる場合は、型指定モジュールの Optional を使用できます。

pyenv install 3.12.2

これは、関数が文字列または None を返す可能性があることを示します。より複雑なデータ構造の場合は、型指定モジュールの List、Dict、または Tuple を使用して、予期される型を指定できます。

ステップ 6: テストを作成する

単体テストを書くことは、予期せぬ事態が生じることなく、コードが期待どおりに動作することを確認する簡単な方法です。これらはバグを早期に発見し、すべてが期待どおりに機能することを確認して自信を持って変更を加えるのに役立ちます。 Python には、単体テストに利用できるライブラリがいくつかあり、それぞれに長所とエコシステムがあります。

• 単体テスト

• pytest

• 鼻2

• 仮説

このガイドでは、シンプルで柔軟で使いやすい pytest を使用します。次のコマンドでインストールできます:

brew update && brew upgrade pyenv

次に、tests/ フォルダー内に test_data_tools.py という名前のファイルを作成します。先ほど実装したコードのテストをいくつか書いてみましょう。これは、load_and_clean_data() 関数と環境変数取得ロジックのサンプル テストです:

test_load_and_clean_data() では、StringIO を使用して CSV ファイルを入力としてシミュレートします。これにより、実際のファイルを必要とせずにテストできるようになります。このテストでは、関数が重複値と NaN 値を正しく削除していることを検証し、DataFrame に欠落データがないことを確認し、「name」列の一意のエントリが正しいことを確認します。

test_get_database_url() と test_get_api_key() では、pytest が提供するユーティリティである monkeypatch を使用して、テスト中に環境変数を一時的に設定します。これにより、関数は実際の環境変数を必要とせずに期待値を返すようになります。

すべてのテストを実行するには、次のコマンドを実行するだけです:

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

私が pytest を愛する理由の 1 つは、その柔軟性です。フィクスチャ、パラメータ化されたテスト、プラグインなどの強力な機能を提供することで、基本的な単体テストを超えています。フィクスチャを使用すると、複数のテストで再利用できるテスト データや構成をセットアップできるため、コードを DRY (Don'trepeat Yourself) に保つことができます。パラメーター化されたテストを使用すると、異なる入力を使用して同じテストを実行できるため、時間を節約し、重複を減らすことができます。また、pytest の機能を拡張する必要がある場合は、Django アプリのテスト、コード カバレッジの測定、HTTP リクエストのモックなどのためのプラグインの幅広いエコシステムがあります。

ステップ 7: コードの品質と事前コミットフック

高いコード品質を維持すると、コードが読みやすく、保守しやすく、一般的なバグがないことが保証されます。いくつかのツールは、一貫したコーディング標準を適用し、コードを自動的にフォーマットし、潜在的な問題を早期に検出するのに役立ちます。人気のあるオプションには、pylint、flake8、black、および detect-secrets などがあります。

• pylint はコーディング標準を強制し、一般的なエラーを検出します。

• flake8 は、スタイル違反と論理エラーを検出するツールを組み合わせています。

• black は、コードが PEP8 標準に準拠していることを確認する独自のフォーマッタです。

• detect-secrets はコードをスキャンして、ハードコードされたシークレットの公開を防ぎます。

これらのツールは次の方法でインストールできます:

pyenv install 3.12.2

たとえば、特定のファイルまたはディレクトリに対して pylint を実行します。

brew update && brew upgrade pyenv

コードを改善するための警告と提案を含むレポートが表示されます。特定の警告を無視するには、次を使用できます:

brew install readline xz

flake8 を使用して、スタイルの問題や論理エラーを見つけることもできます。

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

コードを自動的にフォーマットするには、black:

を実行します。

pyenv install 3.12.2

変更を加えるたびにこれらのツールを手動で実行する代わりに、コミット前フックを使用してプロセスを自動化できます。コミット前フックは各コミットの前に自動的に実行され、ツールが失敗するとコミットをブロックします。

まず、pre-commit パッケージをインストールします。

brew update && brew upgrade pyenv

次に、次の内容を含む .pre-commit-config.yaml ファイルをプロジェクト ディレクトリに作成します (ここでは、お気に入りの基本的な事前コミットをすべて使用しました)。

ローカル リポジトリでコミット前フックをアクティブ化します:

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

これで、コミットしようとするたびに、これらのツールが自動的に実行されます。いずれかのツールが失敗した場合、問題が解決されるまでコミットはブロックされます。コードベース全体ですべてのフックを手動で実行することもできます:

pyenv install 3.12.2

ステップ 8: 配布パッケージを作成する

プロジェクトを構築し、コードを書き、テストを追加し、コミット前フックを設定したので、次のステップは、他の人 (または将来の私たち) がそれを簡単に使用できる方法を考えることです。プロジェクトをパッケージ化することでそれが可能になります。これにより、すべてをきちんとバンドルできるため、ファイルを手動でコピーすることなくインストールして使用できるようになります。

プロジェクトを共有するには、パッケージを適切に構造化し、意味のある README を作成し、開始スクリプトを作成して、配布パッケージを生成する必要があります。通常、優れた README には、プロジェクト名とその内容の簡単な説明、インストール手順、使用例、環境をセットアップするための開発手順、および貢献に関するガイドラインが含まれています。 blog_de_toolkit プロジェクトの簡単な README.md サンプルはリポジトリにあります。

Python パッケージの中核となるのは、setup.py ファイルです。このファイルは、プロジェクトをパッケージ化してインストールするために必要なメタデータと構成を定義する場所です。これには、プロジェクトを識別できるようにする、プロジェクトの名前、バージョン、および説明が含まれます。 long_description は README ファイルから読み取られ、PyPI でプロジェクトを見たときにユーザーにプロジェクトに関する詳細なコンテキストを提供します。 install_requires リストで 依存関係 を指定すると、パッケージとともに自動的にインストールされます。 entry_points セクションはコマンドライン インターフェイス (CLI) エントリを定義するため、ユーザーは端末からツールを実行できます。 find_packages() を使用してすべてのサブモジュールをパッケージに含めます。classifiers セクションは、プロジェクトで使用されている Python のバージョンとライセンスなどのメタデータを提供します。最後に、python_requires フィールドにより、パッケージが互換性のある Python バージョンにのみインストールされるようにします。blog_de_toolkit プロジェクトの setup.py 構成は次のとおりです。

setup.py が構成されたら、配布パッケージをビルドできます。まず、次のコマンドを使用して必要なツールをインストールします。

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

次にパッケージをビルドします:

pyenv install 3.12.2

このコマンドは 2 つの配布ファイルを作成します:

• sdist: ソースアーカイブ (例: .tar.gz)

• bdist_wheel: ビルドされたパッケージ (例: .whl)

これらのファイルは dist/ ディレクトリにあります。パッケージをテストするには、次のコマンドを使用してローカルにインストールします。

brew update && brew upgrade pyenv

次のコマンドを実行して CLI コマンドをテストすることもできます。

brew install readline xz

データベース URL、API キー、およびクリーンアップされたデータを sample_data.csv から出力する必要があります。

パッケージをパブリックに共有したい場合は、PyPI にアップロードできます。まず、Twine をインストールします:

pyenv virtualenv 3.12.2 de_toolkit

次にパッケージをアップロードします:

pyenv local de_toolkit

PyPI 認証情報の入力を求められます。アップロードすると、他の人は次のコマンドを使用して PyPI から直接パッケージをインストールできます。

pip install setuptools wheel twine pandas 

ステップ 10: メインブランチの保護

プロジェクトが成長するにつれて、より多くの人々が同じコードベースで、多くの場合同時に作業するようになります。適切な保護策がなければ、間違い、テストされていないコード、または偶発的なマージが忍び込み、事態を混乱させることが簡単に発生します。物事をスムーズに進め、高い基準を維持するには、メインブランチを保護することが不可欠になります。このステップでは、ブランチ保護ルールの設定方法を検討し、プル リクエストでコード レビューをスムーズに行うためのヒントをいくつか共有します。

ブランチ保護ルールにより、テストに合格したりコードレビューを受けたりすることなく、誰もメインブランチに直接プッシュできないようになります。これにより、未完成の機能、バグ、または不正なコードが忍び込んでプロジェクトを破壊するのを防ぎます。また、プル リクエストを要求することでチームワークを促進し、他の人にフィードバックを提供する機会を与えます。さらに、テストやリンターなどの自動チェックにより、マージ前にコードが確実であることが確認されます。

GitHub でブランチ保護ルールを設定するのは非常に簡単です。リポジトリの 設定 に移動し、「コードと自動化」セクションの ブランチ をクリックします。 ブランチ保護ルール を探し、ブランチ保護ルールの追加 をクリックします。ブランチ名フィールドに「main」と入力します。次に、いくつかの設定を調整します。

プル リクエストのレビューを要求するブランチ保護ルールを設定して、コードがマージされる前に誰かがコードをチェックするようにすることができます。ステータス チェックにより、テストが合格しリンターがスムーズに実行されることが確認され、ブランチを最新の変更内容で最新の状態に保つことで競合を回避できます。必要に応じて、ブランチにプッシュできるユーザーを制限したり、セキュリティを強化するために署名付きコミットを要求したりすることもできます。すべてを設定したら、作成 をクリックします。これで、直接プッシュしたり、テストをスキップしたりする必要はなくなります。

プル リクエストがレビューされるときは、レビュー担当者にとって作業が簡単になるようにすることをお勧めします。まず、変更によって何が行われるのか、なぜその変更が必要なのかを明確に説明します。更新内容を反映する意味のあるコミット メッセージを使用します。変更が小さく、焦点が絞られている場合、レビュープロセスはよりスムーズかつ迅速になります。コメントに丁寧に返信し、要求された変更をフォローアップすることを忘れないでください。これは、フィードバックを大切にしていることを示し、コラボレーションを前向きに保つのに役立ちます。

あなたがプル リクエストをレビューしている場合、あなたの仕事は単に間違いを見つけるだけではなく、コードを改善し、チームメイトをサポートすることです。まず、プル リクエストの説明を読んで、変更が何を達成しようとしているかを理解します。建設的なフィードバックを提供することに重点を置きます。必要に応じて代替案を提案し、その方が効果的である理由を説明します。シンプルな「素敵なリファクタリング?!」で優れた成果を評価する肯定的なレビュー体験を生み出すのにも役立ちます。テストを監視して、テストが存在し、関連性があり、合格していることを確認します。何か不明な点がある場合は、推測するのではなく質問してください。結局のところ、レビューはチームワーク、つまりプロジェクトをより良くするために協力することです。

レビュー テンプレートを使用すると、全員が重要なことに集中し続けることができ、プロセスがよりスムーズになります。以下はプル リクエスト レビュー テンプレートの例です:

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

このようなテンプレートを投稿ガイドラインに追加するか、リポジトリにリンクすると、レビュー担当者が順調に作業を進めやすくなります。また、レビュー間で一貫性が保たれるため、チームがクリーンで整理されたコードベースを維持するのに役立ちます。

ステップ 11: CI/CD の GitHub アクション

メイン ブランチを保護し続けることの重要性を踏まえて、すべてのコード変更がマージまたはデプロイする前に適切にテスト、レビュー、検証されていることを確認することも重要です。ここで、継続的インテグレーション (CI) と 継続的デリバリー/デプロイメント (CD) が登場します。 CI/CD は、テストの実行、コード チェックの実行、変更のデプロイのプロセスを自動化し、開発者に迅速なフィードバックを提供し、本番環境にバグが侵入する可能性を減らします。

GitHub Actions は、GitHub に直接統合された自動化ツールです。これにより、プッシュ リクエストやプル リクエストなど、リポジトリ内のイベントに応答するワークフローを作成できます。 GitHub Actions では、健全なコードベースを維持するためにいくつかの主要なタスクを自動化できます。例:

• コードがプッシュされるかプルリクエストが作成されるたびにテストを実行し、新しい変更によって何も壊れないことを確認します。

• 一貫したコーディング標準を適用するためにコード スタイルと lint をチェックします。

• コミット前フックを適用してコードをフォーマットし、末尾のスペースなどの小さな問題を検出します。

• ドキュメントを生成するか、すべてのチェックに合格したらコードをデプロイします。

メイン ブランチでプッシュまたはプル リクエストが発生するたびに単体テストを実行し、コミット前リンター (黒など) を適用する GitHub Actions ワークフローを設定しましょう。

まず、ワークフロー ファイルを作成します。

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

ci.yml の内容は次のとおりです:

このワークフローは、コードがプッシュされるか、メイン ブランチでプル リクエストが開かれるたびに、テストと lint を自動化します。コードがマージされる前に、すべての品質チェックに合格することが保証されます。 events/checkout アクションはリポジトリをランナーに複製し、actions/setup-python を使用してワークフロー用に Python 3.12 を構成します。依存関係は、pip を使用してrequirements.txtからインストールされます。その後、すべてのテストが pytest で実行され、コミット前のフックによってコードが書式設定とスタイルのガイドラインに従っていることが確認されます。いずれかのテストまたはチェックが失敗すると、壊れたコードがマージされるのを防ぐためにワークフローが停止します。

試してみましょう。まず、main から新しいブランチを作成し、いくつかの変更を加えます。

私の場合は、README ファイルを更新しました。変更をコミットし、メイン ブランチへのプル リクエストを開きます。

これで、レビューが必要であり、GitHub Actions (GA) がすべてのチェックを実行していることがわかります。ブランチ保護ルールによってマージがブロックされている場合でも、権限で保護をバイパスできるため、「要件が満たされるのを待たずにマージ」できます。

GitHub Actions ワークフローの結果は、アクション タブで追跡できます。

これは、実行中に pytest ステップがどのように表示されるかを示す例です:

ステップ 12: セマンティック バージョニング (SemVer)

プロジェクトのバージョンを手動で追跡すると、特にプロジェクトが大きくなると面倒になる可能性があります。ここで セマンティック バージョニング (SemVer) が登場します。MAJOR.MINOR.PATCH パターンに従って、各リリースでの変更点を伝達します。 python-semantic-release を使用してバージョニングを自動化すると、これがさらに簡単になります。コミットメッセージを分析し、変更の種類に基づいてバージョンを上げ、リリースにタグを付け、必要に応じてパッケージを PyPI に公開することもできます。これにより、バージョン管理から推測に頼る必要がなくなり、一貫性が確保されます。

シームレスなバージョニングのために、python-semantic-release を GitHub Actions に直接統合できます。公式ドキュメントには、メイン ブランチにプッシュするたびにバージョンのバンプとリリースを自動化するワークフローが記載されています。この設定を使用すると、リリース プロセスがスムーズで人手がかからなくなるため、手動でのバージョン管理を気にせずにコードの作成に集中できます。

一般的なワークフローの例 — python-semantic-release

これを機能させるには、コミット メッセージが従来のコミット標準に従う必要があります。コミットの種類ごとに、バージョンが PATCH、MINOR、または MAJOR レベルに上がるかどうかが決まります:

• 修正: PATCH バージョンのバンプ (例: 1.0.0 → 1.0.1) をトリガーします。

• feat: マイナー バージョン バンプ (例: 1.0.0 → 1.1.0) をトリガーします。

• 重大な変更: コミットメッセージ内の または ! は、メジャー バージョン バンプ (例: 1.0.0 → 2.0.0) をトリガーします。

これらの簡単な規則に従うことで、新しいバージョンごとに何が起こるかを常に知ることができます。

結論

プロジェクトの整理やシークレットの管理から、テストの作成、ワークフローの自動化、セマンティック バージョニングによるリリースの処理まで、すべてをカバーしてきました。適切なツールとプロセスを使用すると、信頼性が高く保守しやすいプロジェクトの構築がはるかにスムーズになり、さらに楽しくなります。

重要なのは、一貫性を保ち、可能なところは自動化し、継続的に改善し続けることです。それぞれの小さな一歩が、時間の経過とともに大きな変化をもたらします。次はあなたの番です。構築し、実験し、そのプロセスを楽しんでください。これらの手順を次のプロジェクトに適用してみてください。その経験をコメント欄でお気軽に共有してください!

以上が初心者向けに Python コードベースを整理して維持する手順の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。