Python パッケージ化用語集#

Core packaging#

__init__.py#

ディレクトリを Python パッケージとしてマークする特別な Python ファイル。 Python はこのファイルを参照すると、そのフォルダーにインポート可能なコードが含まれていることを認識します。空にすることも、パッケージのインポート時に実行されるコードを含めることもできます。

APIトークン#

パッケージを公開するときに PyPI または TestPyPI で認証するために使用される秘密キー。アカウント設定で生成し、パスワードの代わりに使用します。 これをパスワードのように扱い、決して共有したり、バージョン管理にコミットしたりしないでください。

バックエンドの構築#

パッケージを配布ファイルに構築する実際の作業を行うツール。このガイドでは、ビルドバックエンドは Hatchling です。これは、[build-system] の下の pyproject.toml ファイルで指定します。

hatch build を実行することでビルドを実行します。あるいは、「python -m build」を実行することもできます。参照: 公式 Python パッケージ化ドキュメント

Distribution files#

他の人がパッケージをインストールできるようにするために PyPI にアップロードするファイル。一般的なタイプには、ホイール (.whl) とソースディストリビューション (.tar.gz) の 2 つがあります。「ホイール (.whl)」および「ソース配布 (sdist)」も参照してください。

モジュール#

インポートできる関数、クラス、変数などのコードを含む単一の Python ファイル (.py)。パッケージは 1 つ以上のモジュールで構成されます。

pyproject.toml#

Python パッケージのルートにある構成ファイル。 TOML 形式で記述され、名前、バージョン、作成者、ライセンスなどのメタデータが保存されます。 Hatch、uv、pytest などのツールを構成することもできます。 Python パッケージ PyPI を準備するも参照してください。

Python package#

インストール、インポート、他のユーザーとの共有ができるように構造化された Python コードのディレクトリ。パッケージには少なくとも __init__.py ファイルと pyproject.toml ファイルが含まれます。これは 通常パッケージ と呼ばれることもあります。

情報: 名前空間パッケージという用語を聞くことがありますが、これは実際にはパッケージではなく、サブパッケージのコンテナです。これはこのガイドの範囲外です。興味がある場合は、Python ドキュメントを参照してください。

PyPI / テストPyPI#

PyPI (Python Package Index) は、Python パッケージが公開およびインストールされる公式リポジトリです。 TestPyPI は、パブリッシュワークフローの学習とテストに使用される別の練習環境です。 pypi.org および test.pypi.org を参照してください。 Python パッケージを PyPI に公開するも参照してください。

ソース配布 (sdist)#

Python パッケージの 2 つの配布ファイルタイプのうちの 1 つ。 sdist (.tar.gz) には、ソースコードとプロジェクトファイルが含まれています。誰かが sdist からインストールすると、ツールは最初にパッケージをローカルに構築します。 Python パッケージを PyPI に公開するも参照してください。

TOML#

Tom's Obvious Minimal Language、構成ファイルの単純な形式。 TOML はデータを [project] や [tool.hatch] などのテーブルと配列に編成します。 pyproject.toml は TOML を使用します。

信頼できる出版#

API トークンの代わりに GitHub Actions を使用して PyPI に公開する安全な方法。シークレットトークンを保存するのではなく、リポジトリを直接信頼するように PyPI を構成します。 GitHub Actions 経由で安全かつ自動公開するための信頼された公開のセットアップも参照してください。

ホイール (.whl)#

Python パッケージのバイナリ配布タイプ。ホイールは、ビルドステップなしで直接インストールされる、事前にビルドされたバイナリ形式 (.whl、ZIP ファイル) です。多くの純粋な Python パッケージでは、1 つのホイールがプラットフォーム間で動作します。 Python パッケージを PyPI に公開するも参照してください。

Tools#

copier#: テンプレートから新しいプロジェクトを作成するためのコマンドラインツール。このガイドでは、コピー機と pyOpenSci パッケージテンプレートを使用して、構造、構成、ツールを迅速にセットアップできます。 copier.readthedocs.io を参照してください。
coverage.py#: テストによって実行されるコードの量を、多くの場合パーセンテージで測定するツール。どのラインとブランチがカバーされているかを示します。 coverage.readthedocs.io を参照してください。
ハッチ#: 最新の Python パッケージ化およびプロジェクト管理ツール。このガイドでは、Hatch を使用してパッケージを構築し、環境を管理し、スクリプトを実行し、公開します。設定は pyproject.toml にあります。 hatch.pypa.io を参照してください。 Hatch について知るも参照してください。
孵化したばかりの子#: The build backend used by Hatch. When you run python -m build or hatch build, Hatchling reads pyproject.toml and creates sdist and wheel files. See hatch.pypa.io/latest/config/build.
ピップ#: Python のデフォルトのパッケージインストーラー。これを使用すると、「pip install package-name」などのコマンドで PyPI から環境にパッケージをインストールできます。 pip.pypa.io を参照してください。
pytest#: テストを検出して実行するために広く使用されている Python テストフレームワーク。このガイドでは、pytest は多くの場合 Hatch スクリプトを通じて実行されます。 docs.pytest.org を参照してください。
ラフ#: 高速な Python リンターおよびフォーマッタ。スタイルをチェックし、多くのスタイルの問題を自動的に修正できます。 docs.astral.sh/ruff を参照してください。
スフィンクス#: Python プロジェクト用のドキュメントジェネレーター。 Sphinx は docstring とドキュメントファイルを読み取り、ドキュメントサイトを構築します。 sphinx-doc.orgを参照してください。
麻ひも#: 配布ファイルを PyPI または TestPyPI に安全にアップロードするためのツール。 twine.readthedocs.io を参照してください。
紫外線#: 高速な Python パッケージおよび環境マネージャー。このガイドでは、uv を使用して依存関係を管理し、プロジェクト環境でコマンドを実行できます。 docs.astral.sh/uv を参照してください。

ハッチング固有の概念#

ハッチ環境#: Hatch によって管理される分離された Python 環境。 pyproject.toml で、テスト、ドキュメント、ビルド、スタイルチェック用に複数の環境を定義でき、それぞれに独自の依存関係とスクリプトが含まれます。
スクリプト（ハッチング）#: pyproject.toml の Hatch 環境内で定義された名前付きコマンド。スクリプトには、「hatch run build:check」や「hatch run test:run」などのショートカットが用意されています。
タスクランナー#: 反復的な開発ワークフローを自動化するツール。 Hatch は、特定の環境で実行されるスクリプトを定義できるようにすることで、タスクランナーとして機能できます。

Development concepts#

コードカバレッジ#: テスト中に実行されるソースコードの量の尺度 (通常はパーセンテージ)。カバレッジが高いからといってバグがないことは保証されませんが、カバレッジが低い場合はテストされていない領域があることを示している可能性があります。
Dependencies#: パッケージが動作するために必要な他の Python パッケージ。共通クラスには、必須の依存関係、オプションの依存関係、および開発の依存関係が含まれます。
Docstring#: 動作、入力、出力を説明する関数、クラス、またはモジュールの先頭にある文字列。 docstring は、Sphinx などのツールで API ドキュメントを生成するために使用できます。
エンドツーエンドのテスト#: 最初から最後まで完全なユーザーワークフローをシミュレートするテスト。科学的パッケージでは、ドキュメントのビルド中に実行されるチュートリアルがエンドツーエンドのテストとして機能します。
結合テスト#: 複数の機能またはコンポーネントがどのように連携して動作するかをチェックするテスト。単体テストとは異なり、より広範なワークフロー全体の動作を検証します。
糸くず#: スタイルの問題、書式設定の問題、コード内の潜在的なエラーを自動的にチェックします。
単体テスト#: 1 つの関数またはメソッドを単独でチェックするテスト。単体テストは高速であり、障害が発生した場所を特定するのに役立ちます。
バージョン指定子/下限#: 依存関係のバージョンを受け入れる制約。たとえば、numpy>=1.24 は下限を設定するため、1.24 より古いバージョンは使用されません。

Git / GitHub#

git#: バージョン管理のためのツールです。
GitHub#: リポジトリの共有を容易にするアカウントと組織を提供するサービス。
GitHub コードスペース#: ブラウザ上で動作するクラウドベースの開発環境。 github.com/features/codespaces を参照してください。
スコープ付きコミット#: 1 つの修正や 1 つの機能更新など、1 つの集中的な変更を行う git コミット。スコープ付きコミットにより、レビュー可能性と履歴の明確さが向上します。

Documentation#

Code of conduct#: プロジェクト内で貢献者とコミュニティのメンバーが互いにどのように接するかについての期待を設定する文書。
Contributing guide#: セットアップ手順、ワークフロー、コードスタイルなど、他の人がどのように貢献できるかを説明するドキュメント (多くの場合「CONTRIBUTING.md」)。
MyST Markdown#: Markedly Structured Text、Sphinx ディレクティブとロールをサポートする Markdown フレーバー。 Sphinx の機能を維持しながら、Markdown ベースのドキュメントが可能になります。 myst-parser.readthedocs.ioを参照してください。
README#: GitHub および多くの場合 PyPI 上のパッケージのフロントページ。優れた README では、目的、インストール、使用方法、サポートオプションについて説明しています。

AI#

生成AI / LLM#: 生成 AI システムは、テキスト、コード、画像などのコンテンツを生成します。 LLM は Large Language Model の略で、ChatGPT、GitHub Copilot、Claude などのツールの背後にあるテクノロジーです。