How to configure workspace environmentsワークスペース環境の設定方法

---

Workspace environments allow you to manage multiple related packages within a single environment. This is useful for monorepos or projects with multiple interdependent packages.ワークスペース環境を使用すると、単一の環境内で複数の関連パッケージを管理できます。これは、モノレポや複数の相互依存パッケージを持つプロジェクトに便利です。

Basic workspace configuration基本的なワークスペースの構成

Define workspace members in your environment configuration using the workspace.members option:環境構成で workspace.members オプションを使用してワークスペースメンバーを定義します:

pyproject.toml hatch.toml

[tool.hatch.envs.default]
workspace.members = [
  "packages/core",
  "packages/utils",
  "packages/cli"
]

[envs.default]
workspace.members = [
  "packages/core",
  "packages/utils",
  "packages/cli"
]

Workspace members are automatically installed as editable packages in the environment.ワークスペースメンバーは、環境内で自動的に編集可能なパッケージとしてインストールされます。

Pattern matchingパターンマッチング

Use glob patterns to automatically discover workspace members:グロブパターンを使用してワークスペースメンバーを自動的に発見します:

pyproject.toml hatch.toml

[tool.hatch.envs.default]
workspace.members = ["packages/*"]

[envs.default]
workspace.members = ["packages/*"]

Excluding membersメンバーの除外

Exclude specific packages from workspace discovery:特定のパッケージをワークスペースの発見から除外します:

pyproject.toml hatch.toml

[tool.hatch.envs.default]
workspace.members = ["packages/*"]
workspace.exclude = ["packages/experimental*"]

[envs.default]
workspace.members = ["packages/*"]
workspace.exclude = ["packages/experimental*"]

Member-specific featuresメンバー特有の機能

Install specific optional dependencies for workspace members:ワークスペースメンバーのために特定のオプション依存関係をインストールします:

pyproject.toml hatch.toml

[tool.hatch.envs.default]
workspace.members = [
  {path = "packages/core", features = ["dev"]},
  {path = "packages/utils", features = ["test", "docs"]},
  "packages/cli"
]

[envs.default]
workspace.members = [
  {path = "packages/core", features = ["dev"]},
  {path = "packages/utils", features = ["test", "docs"]},
  "packages/cli"
]

Environment-specific workspaces環境特有のワークスペース

Different environments can include different workspace members:異なる環境には異なるワークスペースメンバーが含まれる場合があります：

pyproject.toml hatch.toml

[tool.hatch.envs.unit-tests]
workspace.members = ["packages/core", "packages/utils"]
scripts.test = "pytest tests/unit"

[tool.hatch.envs.integration-tests]
workspace.members = ["packages/*"]
scripts.test = "pytest tests/integration"

[tool.hatch.envs.docs]
workspace.members = [
  {path = "packages/core", features = ["docs"]},
  {path = "packages/utils", features = ["docs"]}
]

[envs.unit-tests]
workspace.members = ["packages/core", "packages/utils"]
scripts.test = "pytest tests/unit"

[envs.integration-tests]
workspace.members = ["packages/*"]
scripts.test = "pytest tests/integration"

[envs.docs]
workspace.members = [
  {path = "packages/core", features = ["docs"]},
  {path = "packages/utils", features = ["docs"]}
]

Test matrices with workspacesワークスペースを使用したテストマトリックス

Combine workspace configuration with test matrices:ワークスペースの設定とテストマトリックスを組み合わせる：

pyproject.toml hatch.toml

[[tool.hatch.envs.test.matrix]]
python = ["3.9", "3.10", "3.11", "3.12"]

[tool.hatch.envs.test]
workspace.members = ["packages/*"]
dependencies = ["pytest", "coverage"]
scripts.test = "pytest {args}"

[[tool.hatch.envs.test-core.matrix]]
python = ["3.9", "3.10", "3.11", "3.12"]

[tool.hatch.envs.test-core]
workspace.members = ["packages/core"]
dependencies = ["pytest", "coverage"]
scripts.test = "pytest packages/core/tests {args}"

[[envs.test.matrix]]
python = ["3.9", "3.10", "3.11", "3.12"]

[envs.test]
workspace.members = ["packages/*"]
dependencies = ["pytest", "coverage"]
scripts.test = "pytest {args}"

[[envs.test-core.matrix]]
python = ["3.9", "3.10", "3.11", "3.12"]

[envs.test-core]
workspace.members = ["packages/core"]
dependencies = ["pytest", "coverage"]
scripts.test = "pytest packages/core/tests {args}"

Performance optimizationパフォーマンス最適化

Enable parallel dependency resolution for faster environment setup:環境設定を迅速化するために並列依存関係解決を有効にする：

pyproject.toml hatch.toml

[tool.hatch.envs.default]
workspace.members = ["packages/*"]
workspace.parallel = true

[envs.default]
workspace.members = ["packages/*"]
workspace.parallel = true

Monorepo exampleモノレポの例

Complete configuration for a typical monorepo structure:典型的なモノレポ構造の完全な設定：

pyproject.toml hatch.toml

# Root pyproject.toml
[project]
name = "my-monorepo"
version = "1.0.0"

[tool.hatch.envs.default]
workspace.members = ["packages/*"]
workspace.exclude = ["packages/experimental*"]
workspace.parallel = true
dependencies = ["pytest", "black", "ruff"]

[tool.hatch.envs.test]
workspace.members = [
  {path = "packages/core", features = ["test"]},
  {path = "packages/utils", features = ["test"]},
  "packages/cli"
]
dependencies = ["pytest", "coverage", "pytest-cov"]
scripts.test = "pytest --cov {args}"

[tool.hatch.envs.lint]
detached = true
workspace.members = ["packages/*"]
dependencies = ["ruff", "black", "mypy"]
scripts.check = ["ruff check .", "black --check .", "mypy ."]
scripts.fmt = ["ruff check --fix .", "black ."]

[[tool.hatch.envs.ci.matrix]]
python = ["3.9", "3.10", "3.11", "3.12"]

[tool.hatch.envs.ci]
template = "test"
workspace.parallel = false  # Disable for CI stability

# Root pyproject.toml
[project]
name = "my-monorepo"
version = "1.0.0"

[envs.default]
workspace.members = ["packages/*"]
workspace.exclude = ["packages/experimental*"]
workspace.parallel = true
dependencies = ["pytest", "black", "ruff"]

[envs.test]
workspace.members = [
  {path = "packages/core", features = ["test"]},
  {path = "packages/utils", features = ["test"]},
  "packages/cli"
]
dependencies = ["pytest", "coverage", "pytest-cov"]
scripts.test = "pytest --cov {args}"

[envs.lint]
detached = true
workspace.members = ["packages/*"]
dependencies = ["ruff", "black", "mypy"]
scripts.check = ["ruff check .", "black --check .", "mypy ."]
scripts.fmt = ["ruff check --fix .", "black ."]

[[envs.ci.matrix]]
python = ["3.9", "3.10", "3.11", "3.12"]

[envs.ci]
template = "test"
workspace.parallel = false  # Disable for CI stability

Library with plugins exampleプラグインを持つライブラリの例

Configuration for a library with optional plugins:オプションのプラグインを持つライブラリの設定：

pyproject.toml hatch.toml

[tool.hatch.envs.default]
workspace.members = ["core"]
dependencies = ["pytest"]

[tool.hatch.envs.full]
workspace.members = [
  "core",
  "plugins/database",
  "plugins/cache",
  "plugins/auth"
]
dependencies = ["pytest", "pytest-asyncio"]

[tool.hatch.envs.database-only]
workspace.members = [
  "core",
  {path = "plugins/database", features = ["postgresql", "mysql"]}
]

[[tool.hatch.envs.plugin-test.matrix]]
plugin = ["database", "cache", "auth"]

[tool.hatch.envs.plugin-test]
workspace.members = [
  "core",
  "plugins/{matrix:plugin}"
]
scripts.test = "pytest plugins/{matrix:plugin}/tests {args}"

[envs.default]
workspace.members = ["core"]
dependencies = ["pytest"]

[envs.full]
workspace.members = [
  "core",
  "plugins/database",
  "plugins/cache",
  "plugins/auth"
]
dependencies = ["pytest", "pytest-asyncio"]

[envs.database-only]
workspace.members = [
  "core",
  {path = "plugins/database", features = ["postgresql", "mysql"]}
]

[[envs.plugin-test.matrix]]
plugin = ["database", "cache", "auth"]

[envs.plugin-test]
workspace.members = [
  "core",
  "plugins/{matrix:plugin}"
]
scripts.test = "pytest plugins/{matrix:plugin}/tests {args}"