Skip to content
@aws/nx-plugin
Blog

Python プロジェクト

Python プロジェクトジェネレーターは、ベストプラクティスで構成された最新の Python ライブラリまたはアプリケーションを作成するために使用できます。UV で管理され、UV ワークスペース内で単一のロックファイルと仮想環境を使用し、テスト実行には pytest、静的解析には Ruff、型チェックには ty を使用します。

使用方法

Section titled “使用方法”

Python プロジェクトの生成

Section titled “Python プロジェクトの生成”

新しい Python プロジェクトは2つの方法で生成できます：

このジェネレーターを実行@aws/nx-plugin:py#project

pnpm nx g @aws/nx-plugin:py#project
コマンドを組み立てる6

必須

必須

変更されるファイルを確認するためにドライランを実行することもできます

オプション

Section titled “オプション”
ジェネレーターオプション6 オプション
name必須string

Pythonプロジェクトの名前

type必須enumデフォルト: application

プロジェクトが application か library かを指定します

applicationlibrary
directorystringデフォルト: packages

プロジェクトが配置される親ディレクトリ

subDirectorystring

プロジェクトが配置されるサブディレクトリ。デフォルトではプロジェクト名になります。

moduleNamestring

Pythonモジュール名

preferInstallDependenciesbooleanデフォルト: true

ジェネレーター実行後に依存関係のインストールを優先するかどうか。複数のジェネレーターをバッチ処理する際にインストールを延期する場合はfalseに設定します（後続のジェネレーターがNxプロジェクトグラフを計算できるよう、必要に応じてインストールは実行されます）。最後に一度だけインストールします。

ジェネレーターの出力

Section titled “ジェネレーターの出力”

ジェネレーターは <directory>/<name> ディレクトリに以下のプロジェクト構造を作成します：

  • Directory<module-name>
    • __init__.py Module initialisation
  • Directorytests
    • __init__.py Module initialisation
    • conftest.py Test configuration
    • test_noop.py Placeholder test
  • project.json Project configuration and build targets
  • pyproject.toml Packaging configuration file used by UV
  • .python-version Contains the project’s Python version

また、ワークスペースのルートに以下のファイルが作成/更新されることに気づくでしょう：

  • pyproject.toml Workspace level packaging configuration for UV
  • .python-version Contains the workspace Python version
  • uv.lock Lockfile for Python dependencies

Python ソースコードの記述

Section titled “Python ソースコードの記述”

<module-name> ディレクトリに Python ソースコードを追加します。

他のプロジェクトでライブラリコードをインポートする

Section titled “他のプロジェクトでライブラリコードをインポートする”

Python プロジェクトに依存関係を追加するには、add ターゲットを使用します。

2つの Python プロジェクト my_app と my_lib を作成したとします。これらは完全修飾プロジェクト名として my_scope.my_app と my_scope.my_lib を持ち、デフォルトではそれぞれ my_scope_my_app と my_scope_my_lib というモジュール名を持ちます。

my_app が my_lib に依存するようにするには、以下のコマンドを実行します：

Terminal window
pnpm nx run my_scope.my_app:add my_scope.my_lib

その後、ライブラリコードをインポートできます：

packages/my_app/my_scope_my_app/main.py
from my_scope_my_lib.my_module import my_function

上記で、my_scope_my_lib はライブラリのモジュール名、my_module は Python ソースファイル my_module.py に対応し、my_function はそのファイルで定義されたメソッドです。

依存関係

Section titled “依存関係”

プロジェクトに依存関係を追加するには、Python プロジェクトで add ターゲットを実行します。例えば：

Terminal window
pnpm nx run my_scope.my_library:add some-pip-package

これにより、プロジェクトの pyproject.toml ファイルに依存関係が追加され、ルートの uv.lock が更新されます。

ランタイムコード

Section titled “ランタイムコード”

Python プロジェクトをランタイムコードとして使用する場合（例えば AWS Lambda 関数のハンドラーとして）、ソースコードとすべての依存関係のバンドルを作成する必要があります。py#lambda-function、py#api、py#mcp-server ジェネレーターはこれを自動的に追加します。手動で追加するには、これらのジェネレーターが提供する形式に合わせて、project.json ファイルに以下のようなターゲットを追加します：

project.json
{
  "targets": {
    "bundle": {
      "dependsOn": ["bundle-x86"]
    },
    "bundle-x86": {
      "cache": true,
      "inputs": ["production", "^production"],
      "executor": "nx:run-commands",
      "outputs": ["{workspaceRoot}/dist/{projectRoot}/bundle-x86"],
      "options": {
        "commands": [
          "uv export --frozen --no-dev --no-editable --project {projectRoot} --package my_scope.my_library -o dist/{projectRoot}/bundle-x86/requirements.txt",
          "uv pip install -n --no-deps --no-installer-metadata --no-compile-bytecode --python-platform x86_64-manylinux_2_28 --python-version 3.14 --target dist/{projectRoot}/bundle-x86 -r dist/{projectRoot}/bundle-x86/requirements.txt"
        ],
        "parallel": false
      },
      "dependsOn": ["compile"]
    }
  }
}

インストール

Section titled “インストール”

以下のコマンドで Python の依存関係をインストールします：

Terminal window
uv sync

ビルド

Section titled “ビルド”

Python プロジェクトには build ターゲット（project.json で定義）が設定されており、以下のように実行できます：

Terminal window
pnpm nx build <project-name>

ここで <project-name> はプロジェクトの完全修飾名です。

build ターゲットは、プロジェクトのコンパイル、リント、テスト、型チェックを実行します。

ビルド出力は、ワークスペースのルート dist フォルダ内の、パッケージとターゲット用のディレクトリ（例：dist/packages/<my-library>/build）にあります。

ワークスペース内のすべてのプロジェクトをビルドするには、以下を実行します：

Terminal window
pnpm nx run-many --target build

または短縮コマンドを使用します：

Terminal window
pnpm build

アセンブル

Section titled “アセンブル”

プロジェクトには assemble ターゲットもあり、これはリント、テスト、型チェックのゲートを実行せずに、プロジェクトがデプロイメントに提供するもの（例えば、コンパイルまたはバンドルされた出力）を生成します。

Terminal window
pnpm nx assemble <project-name>

デプロイターゲットは assemble に依存しているため、デプロイ時にはデプロイしようとしているもののみをビルドします。

テスト

Section titled “テスト”

プロジェクトのテストには pytest が設定されています。

テストの記述

Section titled “テストの記述”

テストは、プロジェクト内の tests ディレクトリに、test_ で始まる Python ファイルに記述する必要があります。例えば：

  • Directorymy_library
    • my_module.py
  • Directorytests
    • test_my_module.py Tests for my_module.py

テストは test_ で始まるメソッドで、期待値を検証するためのアサーションを行います。例えば：

tests/test_my_module.py
from my_library.my_module import say_hello


def test_say_hello():
  assert say_hello("Darth Vader") == "Hello, Darth Vader!"

テストの記述方法の詳細については、pytest ドキュメントを参照してください。

テストの実行

Section titled “テストの実行”

テストはプロジェクトの build ターゲットの一部として実行されますが、test ターゲットを実行することで個別に実行することもできます：

Terminal window
pnpm nx test <project-name>

-k フラグを使用して、テストファイルまたはメソッドの名前を指定することで、個別のテストまたはテストスイートを実行できます：

Terminal window
pnpm nx test <project-name> -k 'test_say_hello'

テストファイルとキャッシング

Section titled “テストファイルとキャッシング”

プロジェクトの tests ディレクトリは、nx.json の production という名前の入力から除外されます。

テストファイルを含むことができない出力を持つターゲット（compile やバンドルターゲットなど）は、default ではなく production を読み取るため、テストを編集してもそれらや、あなたのプロジェクトに依存するプロジェクト内のタスクは無効化されません。

除外は意図的に tests ディレクトリに限定されています。パッケージディレクトリ内の test_*.py ファイルは、ビルドされた配布物にパッケージ化されるため、本番コードとして扱われ、ビルドを無効化します。

test、lint、format、typecheck ターゲットは default を読み取るため、テストを編集すると再実行されます。typecheck はテストも型チェックするため、テスト内の型エラーも報告されることに注意してください。

型チェック

Section titled “型チェック”

Python プロジェクトは型チェックに ty を使用します。

型チェッカーの実行

Section titled “型チェッカーの実行”

型チェックはプロジェクトの build ターゲットの一部として実行されますが、typecheck ターゲットを介して個別に実行することもできます：

Terminal window
pnpm nx run <project-name>:typecheck

型エラーの抑制

Section titled “型エラーの抑制”

単一行の特定の診断を抑制するには、行末に # ty: ignore[<rule>] コメントを追加します。例えば：

value: int = "not an int"  # ty: ignore[invalid-assignment]

プロジェクト全体で型チェックの動作を設定するには、プロジェクトの pyproject.toml に [tool.ty] セクションを追加します。利用可能なオプションについては、ty 設定リファレンスを参照してください。

リント

Section titled “リント”

Python プロジェクトはリントに Ruff を使用します。

リンターの実行

Section titled “リンターの実行”

プロジェクトをチェックするためにリンターを呼び出すには、lint ターゲットを実行します。

Terminal window
pnpm nx lint <project-name>

リント問題の修正

Section titled “リント問題の修正”

リントやフォーマットの問題の大部分は自動的に修正できます。--configuration=fix 引数を指定して実行することで、Ruff にリント問題を修正させることができます。

Terminal window
pnpm nx lint <project-name> --configuration=fix

同様に、ワークスペース内のすべてのパッケージのすべてのリント問題を修正したい場合は、以下を実行できます：

Terminal window
pnpm nx run-many --target lint --all --configuration=fix

リント問題のスキップ

Section titled “リント問題のスキップ”

開発中にリント問題によって作業が遅くなるのを避けるため（特にプロジェクトに自動修正できない問題がある場合）、skip-lint 設定でビルドを実行できます：

Terminal window
pnpm nx run-many --target build --configuration=skip-lint

これにより、ビルドの一部として Ruff は実行されますが、lint ターゲットは常に成功したと見なされます。