diff --git a/docs/concepts/projects/config.md b/docs/concepts/projects/config.md index 7cea90bfc..898a68f4d 100644 --- a/docs/concepts/projects/config.md +++ b/docs/concepts/projects/config.md @@ -1,8 +1,24 @@ # Configuring projects +## Python version requirement + +Projects may declare the Python versions supported by the project in the `project.requires-python` +field of the `pyproject.toml`. + +It is recommended to set a `requires-python` value: + +```toml title="pyproject.toml" +[project] +requires-python = ">=3.12" +``` + +The Python version requirement determines the Python syntax that is allowed in the project and +affects selection of dependency versions (they must support the same Python version range). + ## Entry points -uv uses the standard `[project.scripts]` table to define entry points for the project. +Projects may define entry points for the project in the `[project.scripts]` table of the +`pyproject.toml`. For example, to declare a command called `hello` that invokes the `hello` function in the `example_package_app` module: @@ -18,15 +34,26 @@ hello = "example_package_app:hello" ## Build systems -Projects _may_ define a `[build-system]` in the `pyproject.toml`. The build system defines how the -project should be packaged and installed. +A build system determines how the project should be packaged and installed. Projects may declare and +configure a build system in the `[build-system]` table of the `pyproject.toml`. uv uses the presence of a build system to determine if a project contains a package that should be installed in the project virtual environment. If a build system is not defined, uv will not attempt to build or install the project itself, just its dependencies. If a build system is defined, uv will -build and install the project into the project environment. By default, projects are installed in -[editable mode](https://setuptools.pypa.io/en/latest/userguide/development_mode.html) so changes to -the source code are reflected immediately, without re-installation. +build and install the project into the project environment. + +The `--build-backend` option can be provided to `uv init` to create a packaged project with an +appropriate layout. The `--package` option can be provided to `uv init` to create a packaged project +with the default build system. + +!!! note + + While uv will not build and install the current project without a build system definition, + the presence of a `[build-system]` table is not required in other packages. For legacy reasons, + if a build system is not defined, then `setuptools.build_meta:__legacy__` is used to build the + package. Packages you depend on may not explicitly declare their build system but are still + installable. Similarly, if you add a dependency on a local package, uv will always attempt to + build and install it. ## Project packaging diff --git a/docs/concepts/projects/dependencies.md b/docs/concepts/projects/dependencies.md index 750b72695..c718de57b 100644 --- a/docs/concepts/projects/dependencies.md +++ b/docs/concepts/projects/dependencies.md @@ -1,6 +1,19 @@ # Managing dependencies -uv is capable of adding, updating, and removing dependencies using the CLI. +Dependencies of the project are defined in several tables: + +- [`project.dependencies`](./dependencies.md#project-dependencies): Published dependencies. +- [`project.optional-dependencies`](./dependencies.md#optional-dependencies): Published optional + dependencies, or "extras". +- [`dependency-groups`](./dependencies.md#dependency-groups): Local dependencies for development. + +!!! note + + The `project.dependencies` and `project.optional-dependencies` tables can be used even if + project isn't going to be published. `dependency-groups` are a recently standardized feature + and may not be supported by all tools yet. + +uv supports modifying the project's dependencies with `uv add` and `uv remove`. ## Adding dependencies diff --git a/docs/concepts/projects/layout.md b/docs/concepts/projects/layout.md index c2134d462..1bf39b1e3 100644 --- a/docs/concepts/projects/layout.md +++ b/docs/concepts/projects/layout.md @@ -2,41 +2,29 @@ ## 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. +Python project metadata is defined in a +[`pyproject.toml`](https://packaging.python.org/en/latest/guides/writing-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: +A minimal project definition includes a name and version: ```toml title="pyproject.toml" [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: +Additional project metadata and configuration includes: -```toml title="pyproject.toml" -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](./dependencies.md) 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`. +- [Python version requirement](./config.md#python-version-requirement) +- [Dependencies](./dependencies.md) +- [Build system](./config.md#build-systems) +- [Entry points (commands)](./config.md#entry-points) ## The project environment