Skip to content

Commit

Permalink
write project guide
Browse files Browse the repository at this point in the history
  • Loading branch information
ibraheemdev committed Jul 18, 2024
1 parent 7beae77 commit 8029892
Show file tree
Hide file tree
Showing 2 changed files with 113 additions and 8 deletions.
2 changes: 1 addition & 1 deletion docs/first-steps.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ These commands are intended for managing development of a Python project. In the
- `uv sync`
- `uv lock`

See the documentation on [projects](./projects.md) for more details on getting started.
See the [project guide](./guides/projects.md) for more details on getting started.

### Toolchain management

Expand Down
119 changes: 112 additions & 7 deletions docs/guides/projects.md
Original file line number Diff line number Diff line change
@@ -1,32 +1,137 @@
# Working on projects

uv can be used to create and manage the development of a Python project from the
ground up.

## Creating a new project

You can create a new Python project using the `uv init` command:

```console
$ uv init hello-world
$ cd hello-world
```

Alternatively, you can initialize a project in the working directory:

```console
$ cd hello-world
$ uv init
```

This will create the following directory structure:

```
uv init
.
├── .venv
├── pyproject.toml
├── README.md
├── uv.lock
└── src
└── hello-world
└── __init__.py
```

### Working on an existing project

<!-- What makes a project compatible with uv commands? What are my alternatives? -->
If your project already contains a standard `pyproject.toml`, you can start
using uv without any extra work. Commands like `uv add` and `uv run` will
create the lockfile and virtual environment the first time they are run.

If you are migrating from an alternative Python package manager, you may need to
edit your `pyproject.toml` manually to use uv. uv uses the `[tool.uv]` section
of the `pyproject.toml` to support non-standard features, such as development
dependencies. Alternative Python package managers may use different sections,
or a custom format altogether.

## Project structure

A project consists of a few important parts that work together and allow uv to
manage your project.

### `pyproject.toml`

The `pyproject.toml` contains metadata about your project:

```toml
[project]
name = "hello-world"
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 it's 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.

### `.venv`

The `.venv` folder contains your project's virtual environment, a Python
environment that is isolated from the rest of your system. This is where uv will
install your project's dependencies.

### `uv.lock`

`uv.lock` is a lockfile that contains exact information about your project's
dependencies. Unlike the `pyproject.toml` which is used to specify the broad
requirements of your project, the lockfile contains the exact versions that are
installed in the virtual environment. This allows for consistent and
reproducible installations across machines.

`uv.lock` is a human-readable TOML file but is managed by uv and should not be
edited manually.

## Running commands

`uv run` can be used to run arbitrary scripts or commands in your project
environment. This ensures that the lockfile and virtual environment are
up-to-date before executing a given command:

```console
$ uv run python my_script.py
$ uv run flask run -p 3000
```
uv run

Alternatively, you can use `uv sync` to manually synchronize the lockfile and
virtual environment before executing a command:

```console
$ uv sync
$ python my_script.py
```

## Managing dependencies

You can add dependencies to your `pyproject.toml` with the `uv add` command.
This will also update the lockfile and virtual environment:

```console
$ uv add requests
```
uv add
```

You can also specify version constraints or alternative sources:

```console
# Specify a version constraint
$ uv add 'requests==2.31.0'

# Add a git dependency
$ uv add requests --git https://github.com/psf/requests
```
uv remove

To remove a package, you can use `uv remove`:

```console
$ uv remove requests
```

## Next steps

See the [projects concept](../projects.md) documentation for more details on projects.
See the [projects concept](../projects.md) documentation for more details about
projects.

0 comments on commit 8029892

Please sign in to comment.