Zanie Blue
ca9aaf1c48
- Adds a collapsible section for the project concept - Splits the project concept document into several child documents. - Moves the workspace and dependencies documents to under the project section - Adds a mkdocs plugin for redirects, so links to the moved documents still work I attempted to make the minimum required changes to the contents of the documents here. There is a lot of room for improvement on the content of each new child document. For review purposes, I want to do that work separately. I'd prefer if the review focused on this structure and idea rather than the content of the files. I expect to do this to other documentation pages that would otherwise be very nested. The project concept landing page and nav (collapsed by default) looks like this now: <img width="1507" alt="Screenshot 2024-11-14 at 11 28 45 AM" src="https://github.com/user-attachments/assets/88288b09-8463-49d4-84ba-ee27144b62a5">
4.1 KiB
Project structure and files
The pyproject.toml
Python project metadata is defined in a pyproject.toml file. uv requires this file to identify the
root directory of a project.
!!! tip
`uv init` can be used to create a new project. See [Creating projects](./init.md) for
details.
A minimal project definition includes a name, version, and description:
[project]
name = "example"
version = "0.1.0"
description = "Add your description here"
It's recommended, but not required, to include a Python version requirement in the [project]
section:
requires-python = ">=3.12"
Including a Python version requirement defines the Python syntax that is allowed in the project and affects selection of dependency versions (they must support the same Python version range).
The pyproject.toml also lists dependencies of the project in the project.dependencies and
project.optional-dependencies fields. uv supports modifying the project's dependencies from the
command line with uv add and uv remove. uv also supports extending the standard dependency
definitions with package sources in tool.uv.sources.
!!! tip
See the official [`pyproject.toml` guide](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/) for more details on getting started with a `pyproject.toml`.
The project environment
When working on a project with uv, uv will create a virtual environment as needed. While some uv
commands will create a temporary environment (e.g., uv run --isolated), uv also manages a
persistent environment with the project and its dependencies in a .venv directory next to the
pyproject.toml. It is stored inside the project to make it easy for editors to find — they need
the environment to give code completions and type hints. It is not recommended to include the
.venv directory in version control; it is automatically excluded from git with an internal
.gitignore file.
To run a command in the project environment, use uv run. Alternatively the project environment can
be activated as normal for a virtual environment.
When uv run is invoked, it will create the project environment if it does not exist yet or ensure
it is up-to-date if it exists. The project environment can also be explicitly created with
uv sync.
It is not recommended to modify the project environment manually, e.g., with uv pip install. For
project dependencies, use uv add to add a package to the environment. For one-off requirements,
use uvx or
uv run --with.
!!! tip
If you don't want uv to manage the project environment, set [`managed = false`](../../reference/settings.md#managed)
to disable automatic locking and syncing of the project. For example:
```toml title="pyproject.toml"
[tool.uv]
managed = false
```
The lockfile
uv creates a uv.lock file next to the pyproject.toml.
uv.lock is a universal or cross-platform lockfile that captures the packages that would be
installed across all possible Python markers such as operating system, architecture, and Python
version.
Unlike the pyproject.toml, which is used to specify the broad requirements of your project, the
lockfile contains the exact resolved versions that are installed in the project environment. This
file should be checked into version control, allowing for consistent and reproducible installations
across machines.
A lockfile ensures that developers working on the project are using a consistent set of package versions. Additionally, it ensures when deploying the project as an application that the exact set of used package versions is known.
The lockfile is created and updated during uv invocations that use the project environment, i.e.,
uv sync and uv run. The lockfile may also be explicitly updated using uv lock.
uv.lock is a human-readable TOML file but is managed by uv and should not be edited manually.
There is no Python standard for lockfiles at this time, so the format of this file is specific to uv
and not usable by other tools.