Workspace Support (#2073)

Co-authored-by: Ofek Lev <[email protected]>

Author: cjames23

.github/workflows/build-hatch.yml

@@ -51,7 +51,7 @@ jobs:
       run: |-
         uv pip install --system build
         uv pip install --system .
-        uv pip install --system ./backend
+        hatch env create
 
     # Windows installers don't accept non-integer versions so we ubiquitously
     # perform the following transformation: X.Y.Z.devN -> X.Y.Z.N
@@ -166,7 +166,7 @@ jobs:
     - name: Install Hatch
       run: |-
         uv pip install --system -e .
-        uv pip install --system -e ./backend
+        hatch env create
 
     - name: Install Rust toolchain
       uses: dtolnay/rust-toolchain@stable

.github/workflows/cli.yml

@@ -43,7 +43,6 @@ jobs:
     - name: Install ourself
       run: |
         uv pip install --system .
-        uv pip install --system ./backend
 
     - name: Benchmark
       run: |

.github/workflows/docs-dev.yml

@@ -38,7 +38,7 @@ jobs:
     - name: Install ourself
       run: |
         uv pip install --system -e .
-        uv pip install --system -e ./backend
+        hatch env create
 
     - name: Configure Git for GitHub Actions bot
       run: |

.github/workflows/docs-release.yml

@@ -36,7 +36,7 @@ jobs:
     - name: Install ourself
       run: |
         uv pip install --system -e .
-        uv pip install --system -e ./backend
+        hatch env create     
 
     - name: Display full version
       run: hatch version

.github/workflows/test.yml

@@ -24,7 +24,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
 
     steps:
     - uses: actions/checkout@v4
@@ -40,7 +40,7 @@ jobs:
     - name: Install ourself
       run: |
         uv pip install --system -e .
-        uv pip install --system -e ./backend
+        hatch env create
 
     - name: Run static analysis
       run: hatch fmt --check
@@ -115,7 +115,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
 
     steps:
     - uses: actions/checkout@v4

docs/history/hatchling.md

@@ -12,6 +12,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 - Drop support for Python 3.8
 
+***Changed:***
+
+- Drop support for Python 3.8
+
 ## [1.27.0](https://github.com/pypa/hatch/releases/tag/hatchling-v1.27.0) - 2024-11-26 ## {: #hatchling-v1.27.0 }
 
 ***Added:***

docs/how-to/environment/workspace.md

@@ -0,0 +1,302 @@
+# 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:
+
+```toml config-example
+[tool.hatch.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:
+
+```toml config-example
+[tool.hatch.envs.default]
+workspace.members = ["packages/*"]
+```
+
+## Excluding members
+
+Exclude specific packages from workspace discovery:
+
+```toml config-example
+[tool.hatch.envs.default]
+workspace.members = ["packages/*"]
+workspace.exclude = ["packages/experimental*"]
+```
+
+## Member-specific features
+
+Install specific optional dependencies for workspace members:
+
+```toml config-example
+[tool.hatch.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:
+
+```toml config-example
+[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"]}
+]
+```
+
+## Test matrices with workspaces
+
+Combine workspace configuration with test matrices:
+
+```toml config-example
+[[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}"
+```
+
+## Performance optimization
+
+Enable parallel dependency resolution for faster environment setup:
+
+```toml config-example
+[tool.hatch.envs.default]
+workspace.members = ["packages/*"]
+workspace.parallel = true
+```
+
+## Cross-member dependencies
+
+Workspace members can depend on each other. When installed, pip or uv will resolve the dependency relationships:
+
+```toml tab="packages/app/pyproject.toml"
+[project]
+name = "app"
+dependencies = ["core", "utils"]
+```
+
+```toml tab="pyproject.toml"
+[tool.hatch.envs.default]
+workspace.members = [
+  "packages/core",
+  "packages/utils",
+  "packages/app"
+]
+```
+
+All workspace members are installed as editable packages. Pip or uv handles resolving the dependencies between app, core, and utils during installation.
+
+## Monorepo example
+
+Complete configuration for a typical monorepo structure:
+
+```toml config-example
+# 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
+```
+
+## Library with plugins example
+
+Configuration for a library with optional plugins:
+
+```toml config-example
+[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}"
+```
+
+## Multi-service application example
+
+Configuration for microservices development:
+
+```toml config-example
+[tool.hatch.envs.default]
+workspace.members = ["shared"]
+dependencies = ["pytest", "requests"]
+
+[tool.hatch.envs.api]
+workspace.members = [
+  "shared",
+  {path = "services/api", features = ["dev"]}
+]
+dependencies = ["fastapi", "uvicorn"]
+scripts.dev = "uvicorn services.api.main:app --reload"
+
+[tool.hatch.envs.worker]
+workspace.members = [
+  "shared",
+  {path = "services/worker", features = ["dev"]}
+]
+dependencies = ["celery", "redis"]
+scripts.dev = "celery -A services.worker.tasks worker --loglevel=info"
+
+[tool.hatch.envs.integration]
+workspace.members = [
+  "shared",
+  "services/api",
+  "services/worker",
+  "services/frontend"
+]
+dependencies = ["pytest", "httpx", "docker"]
+scripts.test = "pytest tests/integration {args}"
+```
+
+## Documentation generation example
+
+Configuration for generating documentation across packages:
+
+```toml config-example
+[tool.hatch.envs.docs]
+workspace.members = [
+  {path = "packages/core", features = ["docs"]},
+  {path = "packages/cli", features = ["docs"]},
+  {path = "packages/plugins", features = ["docs"]}
+]
+dependencies = [
+  "mkdocs",
+  "mkdocs-material",
+  "mkdocstrings[python]"
+]
+scripts.serve = "mkdocs serve"
+scripts.build = "mkdocs build"
+
+[tool.hatch.envs.docs-api-only]
+workspace.members = [
+  {path = "packages/core", features = ["docs"]}
+]
+template = "docs"
+scripts.serve = "mkdocs serve --config-file mkdocs-api.yml"
+```
+
+## Development workflow example
+
+Configuration supporting different development workflows:
+
+```toml config-example
+[tool.hatch.envs.dev]
+workspace.members = ["packages/*"]
+workspace.parallel = true
+dependencies = [
+  "pytest",
+  "black",
+  "ruff",
+  "mypy",
+  "pre-commit"
+]
+scripts.setup = "pre-commit install"
+scripts.test = "pytest {args}"
+scripts.lint = ["ruff check .", "black --check .", "mypy ."]
+scripts.fmt = ["ruff check --fix .", "black ."]
+
+[tool.hatch.envs.feature]
+template = "dev"
+workspace.members = [
+  "packages/core",
+  "packages/{env:FEATURE_PACKAGE}"
+]
+scripts.test = "pytest packages/{env:FEATURE_PACKAGE}/tests {args}"
+
+[[tool.hatch.envs.release.matrix]]
+package = ["core", "utils", "cli"]
+
+[tool.hatch.envs.release]
+detached = true
+workspace.members = ["packages/{matrix:package}"]
+dependencies = ["build", "twine"]
+scripts.build = "python -m build packages/{matrix:package}"
+scripts.publish = "twine upload packages/{matrix:package}/dist/*"
+```

docs/meta/authors.md

@@ -17,3 +17,4 @@
 - Olga Matoula [:material-github:](https://github.com/olgarithms) [:material-twitter:](https://twitter.com/olgarithms_)
 - Philip Blair [:material-email:](mailto:[email protected])
 - Robert Rosca [:material-github:](https://github.com/robertrosca)
+- Cary Hawkins [:material-github](https://github.com/cjames23)

docs/plugins/environment/reference.md

@@ -51,6 +51,7 @@ All environment types should [offer support](#hatch.env.plugin.interface.Environ
       - dependencies_in_sync
       - sync_dependencies
       - dependency_hash
+      - project_dependencies
       - project_root
       - sep
       - pathsep