From ed0cc7cfc3bbd70fa4004e4f592b11ac69bf017f Mon Sep 17 00:00:00 2001 From: Zanie Blue Date: Tue, 27 Aug 2024 13:47:14 -0500 Subject: [PATCH] Update project documentation for the application / library concepts --- docs/concepts/projects.md | 73 +++++++++++++++++++++++++++++++++++++-- docs/guides/projects.md | 57 ++++++++++++++++-------------- docs/guides/publish.md | 10 ++++++ 3 files changed, 113 insertions(+), 27 deletions(-) diff --git a/docs/concepts/projects.md b/docs/concepts/projects.md index ca1cfdeb8188..5bf25bd01e16 100644 --- a/docs/concepts/projects.md +++ b/docs/concepts/projects.md @@ -10,7 +10,10 @@ Python projects help manage Python applications spanning multiple files. Python project metadata is defined in a `pyproject.toml` file. -`uv init` can be used to create a new project, with a basic `pyproject.toml` and package definition. +!!! + + `uv init` can be used to create a new project. See [Creating projects](#creating-projects) for + details. A minimal project definition includes a name, version, and description: @@ -21,7 +24,7 @@ version = "0.1.0" description = "Add your description here" ``` -Additionally, it's recommended to include a Python version requirement: +It's recommended, but not required, to include a Python version requirement: ```toml title="pyproject.toml" [project] @@ -39,6 +42,72 @@ dependency list from the command line with `uv add` and `uv remove`. uv also sup 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`. +## Creating projects + +uv supports initializing a project with `uv init`. By default, uv will create a project in the +working directory. Projects can be created in a target directory by providing a name, e.g., +`uv init foo`. If there's already a project in the target directory, i.e., there's a +`pyproject.toml`, uv will exit with an error. + +By default, uv will create a project for an [application](#applications). However, the `--lib` flag +can be used to create a project for a [library](#libraries). + +## Project types + +uv groups projects into two types: **applications** and **libraries**. + +### Applications + +Application projects are suitable for web servers, scripts, and command-line interfaces. + +Application projects have the following traits: + +- A build backend is not defined. +- Source code is often in the top-level directory, e.g., `hello.py`. +- The project package is not installed in the project environment. + +!!! note + + The `--package` flag can be passed to `uv init` to create a distributable application, + e.g., if you want to publish a command-line interface via PyPI. uv will define a build + backend for the project, include a `[project.scripts]` entrypoint, and install the project + package into the project environment. + + Similarly, a build backend can be manually defined to treat any application as a distributable + package. This may require changes to the project directory structure, depending on the build + backend. + +### Libraries + +A library is a project that is intended to be built and distributed as a Python package, for +example, by uploading it to PyPI. A library provides functions and objects for other projects to +consume. + +Library projects have the following traits: + +- A build backend is required. +- Source code is typically in a `src/{package}` directory. +- The project package is installed in the project environment. + +Libraries can be created with `uv init` by providing the `--lib` flag. uv will assume that any +project that defines a `[build-system]` is a library. + +### Other types + +By default, uv uses the presence of a `[build-system]` in the `pyproject.toml` to determine if a +project is an application or a library. However, uv also allows manually declaring if a project +should be treated as a package. + +To enable or disable build and installation of the project package regardless of the presence of a +`[build-system]` definition, use the [`tool.uv.package`](../reference/settings.md#package) setting. + +Setting `tool.uv.package = true` will force a project package to be built and installed into the +project environment. If no build system is defined, uv will use the setuptools legacy backend. + +Setting `tool.uv.package = false` will force a project package _not_ to be built and installed into +the project environment. uv will ignore the declared build system, if any, when interacting with the +project. + ## Project environments uv creates a virtual environment in a `.venv` directory next to the `pyproject.toml`. This virtual diff --git a/docs/guides/projects.md b/docs/guides/projects.md index 076b397a1c8c..46613e318293 100644 --- a/docs/guides/projects.md +++ b/docs/guides/projects.md @@ -1,7 +1,6 @@ # Working on projects -uv is capable of managing Python projects using a `pyproject.toml` with a `[project]` metadata -table. +uv supports managing Python projects, which define their dependencies in a `pyproject.toml` file. ## Creating a new project @@ -20,34 +19,42 @@ $ cd hello-world $ uv init ``` -This will create the following directory structure: +uv will create the following files: ```text . -├── pyproject.toml ├── README.md -└── src - └── hello_world - └── __init__.py +├── hello.py +└── pyproject.toml ``` -### Working on an existing project - -If your project already contains a standard `pyproject.toml`, you can start using uv immediately. -Commands like `uv add` and `uv run` will create a [lockfile](#uvlock) and [environment](#venv) the -first time they are used. +The `hello.py` file contains a simple "Hello world" program. Try it out with `uv run`: -If you are migrating from an alternative Python package manager, you may need to edit your -`pyproject.toml` manually before using uv. Most Python package managers extend the `pyproject.toml` -standard to support common features, such as development dependencies. These extensions are specific -to each package manager and will need to be converted to uv's format. See the documentation on -[project dependencies](../concepts/dependencies.md) for more details. +```console +$ uv run hello.py +Hello from hello-world! +``` ## Project structure A project consists of a few important parts that work together and allow uv to manage your project. -Along with the files created by `uv init`, uv will create a virtual environment and `uv.lock` file -in the root of your project the first time you run a project command. +In addition to the files created by `uv init`, uv will create a virtual environment and `uv.lock` +file in the root of your project the first time you run a project command, i.e., `uv run`, +`uv sync`, or `uv lock`. + +A complete listing would look like: + +```text +. +├── .venv +│   ├── bin +│   ├── lib +│   └── pyvenv.cfg +├── README.md +├── hello.py +├── pyproject.toml +└── uv.lock +``` ### `pyproject.toml` @@ -60,20 +67,20 @@ version = "0.1.0" description = "Add your description here" readme = "README.md" dependencies = [] - -[tool.uv] -dev-dependencies = [] ``` -This is where you specify dependencies, as well as details about the project such as its description -or license. You can edit this file manually, or use commands like `uv add` and `uv remove` to manage -your project through the CLI. +You'll use this file to specify dependencies, as well as details about the project such as its +description or license. You can edit this file manually, or use commands like `uv add` and +`uv remove` to manage your project from the terminal. !!! tip See the official [`pyproject.toml` guide](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/) for more details on getting started with the `pyproject.toml` format. +You'll also use this file to specify uv [configuration options](../configuration/files.md) in a +[`[tool.uv]`](../reference/settings.md) section. + ### `.venv` The `.venv` folder contains your project's virtual environment, a Python environment that is diff --git a/docs/guides/publish.md b/docs/guides/publish.md index 28cb73bbdedc..ede7257ab76f 100644 --- a/docs/guides/publish.md +++ b/docs/guides/publish.md @@ -4,6 +4,16 @@ uv does not yet have dedicated commands for building and publishing a package. I the PyPA tools [`build`](https://github.com/pypa/build) and [`twine`](https://github.com/pypa/twine), both of which can be invoked via `uvx`. +## Preparing your project for packaging + +Before attempting to publish your project, you'll want to make sure it's ready to be packaged for +distribution. + +If your project does not include a `[build-system]` definition in the `pyproject.toml`, uv will not +build it by default. This means that your project may not be ready for distribution. Read more about +the effect of declaring a build system in the +[project concept](../concepts/projects.md#project-types) documentation. + ## Building your package Build your package with the official `build` frontend: