Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update project documentation for the application / library concepts #6718

Merged
merged 1 commit into from
Aug 27, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 71 additions & 2 deletions docs/concepts/projects.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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]
Expand All @@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But this isn't required right?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well.. I wrote it that way at first but that gets confusing. I think we have

  • Applications: no build backend
  • Libraries: yes build backend
  • Other: you set package manually

- 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
Expand Down
57 changes: 32 additions & 25 deletions docs/guides/projects.md
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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`

Expand All @@ -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
Expand Down
10 changes: 10 additions & 0 deletions docs/guides/publish.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
Loading