モダンな Python パッケージ開発フロー (uv + Hatchling)

本ドキュメントでは、最新のパッケージ管理ツールである uv と、ビルドバックエンド Hatchling を用いた配布用 Python パッケージの開発手順をまとめます。

1. uv をグローバルにインストールする

uv は Python のバージョン管理から仮想環境の構築、パッケージ管理までを一元に行う高速なツールです。仮想環境ごとにインストールするのではなく、システム全体（グローバル）にインストールすることが推奨されています。

# asdfでいれているglobalのpythonにインストール
pip install uv

2. プロジェクトディレクトリの作成

新しくパッケージ開発を始める際は、uv init コマンドを使用することで、モダンなプロジェクトの雛形を生成できます（もちろん手動でフォルダを作っても構いません）。

# プロジェクトを作成して移動
uv init my_awesome_project
cd my_awesome_project

これにより、pyproject.toml などの標準的な設定ファイルが用意されます。

3. pyproject.toml の記述と Hatchling について

pyproject.toml はプロジェクトの設定を一元管理するファイルで、旧来の setup.py に代わるものです。

ここではビルドツールとして Hatchling を利用します。Hatchling は、あなたのソースコードを配布可能な形式（Wheel など）にビルド（組み立て）する役割を担います。

# pyproject.toml の記述例

[build-system]
# Hatchlingを利用する宣言
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "my_awesome_project"
version = "0.1.0"
description = "My awesome Python package."
readme = "README.md"
requires-python = ">=3.13"

# 外部ライブラリへの依存関係がある場合はここに記載
dependencies = [
    # "requests", "numpy" など
]

# Hatchling に対して、どのディレクトリをパッケージとして扱うかを指定する
[tool.hatch.build.targets.wheel]
packages = ["src/my_awesome_package"]

💡 Hatchling のメリット 複雑な設定なしで src ディレクトリレイアウトなどを自動で認識してくれ、非常に軽量で uv との親和性も高いのが特徴です。

4. プロジェクトのディレクトリ構成

Python コミュニティでは、インポート時の名前衝突を防ぐ src レイアウト が強く推奨されています。

my_awesome_project/
├── pyproject.toml
├── README.md
└── src/
    └── my_awesome_package/   <-- 実際のプログラムパッケージはここに配置
        ├── __init__.py
        ├── main.py
        └── utils.py

5. 編集可能インストール (Editable Install) による開発

独自のパッケージを開発する際、自作のファイルを読み込ませるための検索パス（sys.path.insert等）を毎回コード内で手動追加するのはアンチパターンです。代わりに、開発中の状態を保ったまま「プロジェクトがあたかもシステムにインストールされているかのように」扱うアプローチを取ります。

# 仮想環境の作成から依存パッケージのインストール、さらに自作パッケージのセットアップまで一括で行う
uv sync

裏側の仕組み（.pth ショートカット） uv sync 等を実行すると、Hatchling の情報をもとに仮想環境内の site-packages にショートカットファイル (.pth) が作成されます。これにより、Python は起動時に自動であなたの src/ 配下のパッケージを標準モジュールのように認識してくれます。コードを修正しても再ビルドや再インストールは不要で、即座に変更が反映されます。

6. 配布用パッケージのビルド (Build)

開発が完了し、他の人に使ってもらうための実体パッケージを作成する場合は、以下のコマンドを実行します。

uv build

すると、プロジェクト内に dist/ ディレクトリが生成され、以下のファイルが出力されます。

Wheel ファイル (.whl): インストールを高速に行えるコンパイル済みパッケージ実体
sdist ファイル (.tar.gz): ソースコードのアーカイブ

📌 できあがったパッケージの使い方 これらのファイルを別の環境の PC などに持っていき uv pip install <パッケージ名>.whl とするだけで、依存関係ごと即座にインストールされて利用可能になります。

7. パッケージの公開・配布 (Publish) ※参考

ビルドしたパッケージは、PyPI (Python Package Index) にアップロードすることで、世界中の誰もが pip install my_awesome_project や uv pip install my_awesome_project でインストールできるようになります。

# 例: PyPI へのアップロード (PyPI のアカウントと API トークンが必要)
uv publish

Pythonパッケージの開発メモ