konsti
db371560bc
To enforce the 100 character line limit in markdown files introduced in https://github.com/astral-sh/uv/pull/5635, and to automate the formatting of markdown files, i've added prettier and formatted our markdown files with it. I've excluded the changelog and the generated references documentation from this for having too many changes, but we can also include them. I'm not particular on which style we use. My main motivations are (major) not having to reflow markdown files myself anymore and (minor) consistence between all markdown files. I've chosen prettier for similar reason as we chose black, it's a single good style that's automated and shared in the community. I do prefer prettier's style of not breaking inside of a link name though. This PR is in two parts, the first adds prettier to CI and documents using it, while the second actually formats the docs. When merge conflicts arise, we can drop the last commit and regenerate it with `npx prettier --prose-wrap always --write BENCHMARKS.md CONTRIBUTING.md README.md STYLE.md docs/*.md docs/concepts/**/*.md docs/guides/**/*.md docs/pip/**/*.md`. --------- Co-authored-by: Zanie Blue <contact@zanie.dev>
86 lines
2.8 KiB
Markdown
86 lines
2.8 KiB
Markdown
# Workspaces
|
|
|
|
Workspaces help organize large codebases by splitting them into multiple packages with independent
|
|
dependencies.
|
|
|
|
When using the `uv pip` interface, workspace dependencies behave like automatic editable path
|
|
dependencies. Using the uv project interface, all of the workspace packages are locked together.
|
|
`uv run` installs only the current package (unless overridden with `--package`) and its workspace
|
|
and non-workspace dependencies.
|
|
|
|
## Configuration
|
|
|
|
A workspace can be created by adding a `tool.uv.workspace` to a `pyproject.toml` that is the
|
|
workspace root. This table contains `members` (mandatory) and `exclude` (optional), with lists of
|
|
globs of directories:
|
|
|
|
```toml title="pyproject.toml"
|
|
[tool.uv.workspace]
|
|
members = ["packages/*", "examples/*"]
|
|
exclude = ["example/excluded_example"]
|
|
```
|
|
|
|
If `tool.uv.sources` is defined in the workspace root, it applies to all packages, unless overridden
|
|
in the `tool.uv.sources` of a specific project.
|
|
|
|
## Common structures
|
|
|
|
There a two main workspace structures: A **root package with helpers** and a **flat workspace**.
|
|
|
|
The root workspace layout defines one main package in the root of the repository, with helper
|
|
packages in `packages`. In this example `albatross/pyproject.toml` has both a `project` section and
|
|
a `tool.uv.workspace` section.
|
|
|
|
```text
|
|
albatross
|
|
├── packages
|
|
│ ├── provider_a
|
|
│ │ ├── pyproject.toml
|
|
│ │ └── src
|
|
│ │ └── provider_a
|
|
│ │ ├── __init__.py
|
|
│ │ └── foo.py
|
|
│ └── provider_b
|
|
│ ├── pyproject.toml
|
|
│ └── src
|
|
│ └── provider_b
|
|
│ ├── __init__.py
|
|
│ └── bar.py
|
|
├── pyproject.toml
|
|
├── README.md
|
|
├── uv.lock
|
|
└── src
|
|
└── albatross
|
|
└── main.py
|
|
```
|
|
|
|
In the flat layout, all packages are in the `packages` directory, and the root `pyproject.toml`
|
|
defines a so-called virtual workspace. In this example `albatross/pyproject.toml` has only a
|
|
`tool.uv.workspace` section, but no `project`.
|
|
|
|
```text
|
|
albatross
|
|
├── packages
|
|
│ ├── albatross
|
|
│ │ ├── pyproject.toml
|
|
│ │ └── src
|
|
│ │ └── albatross
|
|
│ │ ├── __init__.py
|
|
│ │ └── foo.py
|
|
│ ├── provider_a
|
|
│ │ ├── pyproject.toml
|
|
│ │ └── src
|
|
│ │ └── provider_a
|
|
│ │ ├── __init__.py
|
|
│ │ └── foo.py
|
|
│ └── provider_b
|
|
│ ├── pyproject.toml
|
|
│ └── src
|
|
│ └── provider_b
|
|
│ ├── __init__.py
|
|
│ └── bar.py
|
|
├── pyproject.toml
|
|
├── README.md
|
|
└── uv.lock
|
|
```
|