standalone-python-scripts

スタンドアロン Python スクリプト

PEP 723 のインラインメタデータと uv を使って依存関係を管理する、単一ファイルの Python スクリプトを作成するためのガイドラインです。

使用する場面

• スタンドアロンの Python スクリプト（単一ファイルで、pyproject.toml はなし）を作成する場合
• CLI ツールやユーティリティスクリプトを作成する場合
• 外部依存関係を含む、簡単な自動化スクリプトや単発のスクリプトを作成する場合

対象外： 複数のモジュールやパッケージ、または pyproject.toml/setup.py 構成を持つ大規模な Python プロジェクト。

手順

1. Python バージョンのサポート状況を確認する — requires-python を設定する前に、対象のバージョンがサポート終了（EOL）を迎えておらず、EOL まで少なくとも 1 年あることを確認します。現在の状況は https://devguide.python.org/versions/ で確認してください。ユーザーから明示的に求められた場合に限り、古いバージョンを対象にします。

2. 依存関係を最小限にする — 明確に時間を節約できるか、不可欠な機能を提供する外部パッケージのみを追加します。可能な場合は標準ライブラリを優先します。

3. PEP 723 のインラインメタデータを追加する — スクリプトの先頭で、次の # /// script ブロック形式を使って依存関係を宣言します。

   # /// script
   # requires-python = ">=3.12"
   # dependencies = [
   #     "click>=8.1",
   #     "arrow>=1.3",
   # ]
   # ///
   

4. uv のシバンを使う — スクリプトに標準ライブラリ以外の依存関係がある場合は、次を使用します。

   #!/usr/bin/env -S uv run --script
   

   これにより、./script.py で直接実行できます。

5. 引数の解析には Click を優先する — スクリプトで CLI 引数が必要な場合は、argparse やその他のライブラリより Click を使用します。

6. 日付と時刻の処理には Arrow を優先する — スクリプトで日付や時刻を扱う場合は、datetime やその他のライブラリより Arrow を使用します。

7. 実行可能にする — スクリプトを作成したら、chmod +x script.py を実行して、直接実行できるようにします。

例

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "click>=8.1",
#     "arrow>=1.3",
# ]
# ///

import click
import arrow

@click.command()
@click.option("--name", default="World", help="Name to greet")
@click.option("--date", is_flag=True, help="Show today's date")
def main(name, date):
    """Greet someone and optionally show the date."""
    click.echo(f"Hello, {name}!")
    if date:
        click.echo(f"Today is {arrow.now().format('YYYY-MM-DD')}")

if __name__ == "__main__":
    main()

注意点

• 過剰な設計： 簡単な作業に依存関係を追加しないでください。datetime で十分なら Arrow を追加せず、argparse で足りるなら Click を追加しないでください。
• シバンの不足： #!/usr/bin/env -S uv run --script がないと、./script.py で直接実行できません。
• 無効なメタデータブロック： # /// script ブロックは先頭に置き、PEP 723 の形式に正確に従う必要があります。
• chmod の実行忘れ： 直接実行するには、スクリプトに実行権限（chmod +x）が必要です。
• バージョンの変動： uv がパッケージを解決する際の予期しない変更を避けるため、依存関係には最低バージョンを指定します。

検証

スクリプトを作成したら、次の手順を実行します。

1. メタデータブロックが有効であることを確認します：uv run --script script.py --help
2. スクリプトを直接実行します：./script.py
3. 依存関係がインストールされ、スクリプトが期待どおりに動作することを確認します

簡単なチェックリスト：

Is the Python version still supported (not EOL, >1 year to EOL)?
Does the script have a shebang line?
Is the PEP 723 metadata block present and valid?
Are dependencies minimal and justified?
Is the script executable (chmod +x)?