mirror of https://github.com/astral-sh/uv
Misc. improvements to the documentation (#11255)
This commit is contained in:
Zanie Blue
GitHub
parent
7ec68e1dda
commit
c64965273f
83
README.md
83
README.md
|
|
@ -26,17 +26,17 @@ An extremely fast Python package and project manager, written in Rust.
|
|||
- 🚀 A single tool to replace `pip`, `pip-tools`, `pipx`, `poetry`, `pyenv`, `twine`, `virtualenv`,
|
||||
and more.
|
||||
- ⚡️ [10-100x faster](https://github.com/astral-sh/uv/blob/main/BENCHMARKS.md) than `pip`.
|
||||
- 🐍 [Installs and manages](#python-management) Python versions.
|
||||
- 🛠️ [Runs and installs](#tool-management) Python applications.
|
||||
- ❇️ [Runs single-file scripts](#script-support), with support for
|
||||
[inline dependency metadata](https://docs.astral.sh/uv/guides/scripts#declaring-script-dependencies).
|
||||
- 🗂️ Provides [comprehensive project management](#project-management), with a
|
||||
[universal lockfile](https://docs.astral.sh/uv/concepts/projects#project-lockfile).
|
||||
- 🔩 Includes a [pip-compatible interface](#a-pip-compatible-interface) for a performance boost with
|
||||
a familiar CLI.
|
||||
- 🏢 Supports Cargo-style [workspaces](https://docs.astral.sh/uv/concepts/workspaces) for scalable
|
||||
projects.
|
||||
- 💾 Disk-space efficient, with a [global cache](https://docs.astral.sh/uv/concepts/cache) for
|
||||
- 🗂️ Provides [comprehensive project management](#project), with a
|
||||
[universal lockfile](https://docs.astral.sh/uv/concepts/projects/layout.md#the-lockfile).
|
||||
- ❇️ [Runs scripts](#script-support), with support for
|
||||
[inline dependency metadata](https://docs.astral.sh/uv/guides/scripts.md#declaring-script-dependencies).
|
||||
- 🐍 [Installs and manages](#python-versions) Python versions.
|
||||
- 🛠️ [Runs and installs](#tool) tools published as Python packages.
|
||||
- 🔩 Includes a [pip-compatible interface](#the-pip-interface) for a performance boost with a
|
||||
familiar CLI.
|
||||
- 🏢 Supports Cargo-style [workspaces](https://docs.astral.sh/uv/concepts/projects/workspaces.md)
|
||||
for scalable projects.
|
||||
- 💾 Disk-space efficient, with a [global cache](https://docs.astral.sh/uv/concepts/cache.md) for
|
||||
dependency deduplication.
|
||||
- ⏬ Installable without Rust or Python via `curl` or `pip`.
|
||||
- 🖥️ Supports macOS, Linux, and Windows.
|
||||
|
|
@ -87,7 +87,7 @@ Additionally, the command line reference documentation can be viewed with `uv he
|
|||
|
||||
## Features
|
||||
|
||||
### Project management
|
||||
### Projects
|
||||
|
||||
uv manages project dependencies and environments, with support for lockfiles, workspaces, and more,
|
||||
similar to `rye` or `poetry`:
|
||||
|
|
@ -109,6 +109,13 @@ Installed 2 packages in 1ms
|
|||
|
||||
$ uv run ruff check
|
||||
All checks passed!
|
||||
|
||||
$ uv lock
|
||||
Resolved 2 packages in 0.33ms
|
||||
|
||||
$ uv sync
|
||||
Resolved 2 packages in 0.70ms
|
||||
Audited 1 package in 0.02ms
|
||||
```
|
||||
|
||||
See the [project documentation](https://docs.astral.sh/uv/guides/projects/) to get started.
|
||||
|
|
@ -116,7 +123,31 @@ See the [project documentation](https://docs.astral.sh/uv/guides/projects/) to g
|
|||
uv also supports building and publishing projects, even if they're not managed with uv. See the
|
||||
[publish guide](https://docs.astral.sh/uv/guides/publish/) to learn more.
|
||||
|
||||
### Tool management
|
||||
### Scripts
|
||||
|
||||
uv manages dependencies and environments for single-file scripts.
|
||||
|
||||
Create a new script and add inline metadata declaring its dependencies:
|
||||
|
||||
```console
|
||||
$ echo 'import requests; print(requests.get("https://astral.sh"))' > example.py
|
||||
|
||||
$ uv add --script example.py requests
|
||||
Updated `example.py`
|
||||
```
|
||||
|
||||
Then, run the script in an isolated virtual environment:
|
||||
|
||||
```console
|
||||
$ uv run example.py
|
||||
Reading inline script metadata from: example.py
|
||||
Installed 5 packages in 12ms
|
||||
<Response [200]>
|
||||
```
|
||||
|
||||
See the [scripts documentation](https://docs.astral.sh/uv/guides/scripts/) to get started.
|
||||
|
||||
### Tools
|
||||
|
||||
uv executes and installs command-line tools provided by Python packages, similar to `pipx`.
|
||||
|
||||
|
|
@ -154,7 +185,7 @@ ruff 0.5.0
|
|||
|
||||
See the [tools documentation](https://docs.astral.sh/uv/guides/tools/) to get started.
|
||||
|
||||
### Python management
|
||||
### Python versions
|
||||
|
||||
uv installs Python and allows quickly switching between versions.
|
||||
|
||||
|
|
@ -196,30 +227,6 @@ Pinned `.python-version` to `3.11`
|
|||
See the [Python installation documentation](https://docs.astral.sh/uv/guides/install-python/) to get
|
||||
started.
|
||||
|
||||
### Script support
|
||||
|
||||
uv manages dependencies and environments for single-file scripts.
|
||||
|
||||
Create a new script and add inline metadata declaring its dependencies:
|
||||
|
||||
```console
|
||||
$ echo 'import requests; print(requests.get("https://astral.sh"))' > example.py
|
||||
|
||||
$ uv add --script example.py requests
|
||||
Updated `example.py`
|
||||
```
|
||||
|
||||
Then, run the script in an isolated virtual environment:
|
||||
|
||||
```console
|
||||
$ uv run example.py
|
||||
Reading inline script metadata from: example.py
|
||||
Installed 5 packages in 12ms
|
||||
<Response [200]>
|
||||
```
|
||||
|
||||
See the [scripts documentation](https://docs.astral.sh/uv/guides/scripts/) to get started.
|
||||
|
||||
### A pip-compatible interface
|
||||
|
||||
uv provides a drop-in replacement for common `pip`, `pip-tools`, and `virtualenv` commands.
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
uv provides essential features for Python development — from installing Python and hacking on simple
|
||||
scripts to working on large projects that support multiple Python versions and platforms.
|
||||
|
||||
uv's interface can be broken down into sections, which can be used independently or together.
|
||||
uv's interface can be broken down into sections, which are usable independently or together.
|
||||
|
||||
## Python versions
|
||||
|
||||
|
|
|
|||
|
|
@ -6,6 +6,7 @@ Check out one of the core guides to get started:
|
|||
- [Running scripts and declaring dependencies](./scripts.md)
|
||||
- [Running and installing applications as tools](./tools.md)
|
||||
- [Creating and working on projects](./projects.md)
|
||||
- [Building and publishing packages](./package.md)
|
||||
- [Integrate uv with other software, e.g., Docker, GitHub, PyTorch, and more](./integration/index.md)
|
||||
|
||||
Or, explore the [concept documentation](../concepts/index.md) for comprehensive breakdown of each
|
||||
|
|
|
|||
|
|
@ -162,7 +162,7 @@ export UV_EXTRA_INDEX_URL="https://aws:${AWS_CODEARTIFACT_TOKEN}@${AWS_DOMAIN}-$
|
|||
### Publishing packages
|
||||
|
||||
If you also want to publish your own packages to AWS CodeArtifact, you can use `uv publish` as
|
||||
described in the [publishing guide](../publish.md). You will need to set `UV_PUBLISH_URL` separately
|
||||
described in the [publishing guide](../package.md). You will need to set `UV_PUBLISH_URL` separately
|
||||
from the credentials:
|
||||
|
||||
```bash
|
||||
|
|
|
|||
|
|
@ -1,9 +1,9 @@
|
|||
---
|
||||
title: Publishing a package
|
||||
title: Building and publishing a package
|
||||
description: A guide to using uv to build and publish Python packages to a package index, like PyPI.
|
||||
---
|
||||
|
||||
# Publishing a package
|
||||
# Building and publishing a package
|
||||
|
||||
uv supports building Python packages into source and binary distributions via `uv build` and
|
||||
uploading them to a registry with `uv publish`.
|
||||
|
|
@ -232,4 +232,4 @@ To learn more about working on projects with uv, see the
|
|||
[projects concept](../concepts/projects/index.md) page and the
|
||||
[command reference](../reference/cli.md#uv).
|
||||
|
||||
Or, read on to learn how to [publish your project as a package](./publish.md).
|
||||
Or, read on to learn how to [build and publish your project to a package index](./package.md).
|
||||
|
|
|
|||
|
|
@ -19,12 +19,12 @@ An extremely fast Python package and project manager, written in Rust.
|
|||
- 🚀 A single tool to replace `pip`, `pip-tools`, `pipx`, `poetry`, `pyenv`, `twine`, `virtualenv`,
|
||||
and more.
|
||||
- ⚡️ [10-100x faster](https://github.com/astral-sh/uv/blob/main/BENCHMARKS.md) than `pip`.
|
||||
- 🐍 [Installs and manages](#python-management) Python versions.
|
||||
- 🛠️ [Runs and installs](#tool-management) Python applications.
|
||||
- 🗂️ Provides [comprehensive project management](#project), with a
|
||||
[universal lockfile](./concepts/projects/layout.md#the-lockfile).
|
||||
- ❇️ [Runs scripts](#script-support), with support for
|
||||
[inline dependency metadata](./guides/scripts.md#declaring-script-dependencies).
|
||||
- 🗂️ Provides [comprehensive project management](#project-management), with a
|
||||
[universal lockfile](./concepts/projects/layout.md#the-lockfile).
|
||||
- 🐍 [Installs and manages](#python-versions) Python versions.
|
||||
- 🛠️ [Runs and installs](#tool) tools published as Python packages.
|
||||
- 🔩 Includes a [pip-compatible interface](#the-pip-interface) for a performance boost with a
|
||||
familiar CLI.
|
||||
- 🏢 Supports Cargo-style [workspaces](./concepts/projects/workspaces.md) for scalable projects.
|
||||
|
|
@ -35,7 +35,7 @@ An extremely fast Python package and project manager, written in Rust.
|
|||
uv is backed by [Astral](https://astral.sh), the creators of
|
||||
[Ruff](https://github.com/astral-sh/ruff).
|
||||
|
||||
## Getting started
|
||||
## Installation
|
||||
|
||||
Install uv with our official standalone installer:
|
||||
|
||||
|
|
@ -58,7 +58,7 @@ Then, check out the [first steps](./getting-started/first-steps.md) or read on f
|
|||
uv may also be installed with pip, Homebrew, and more. See all of the methods on the
|
||||
[installation page](./getting-started/installation.md).
|
||||
|
||||
## Project management
|
||||
## Projects
|
||||
|
||||
uv manages project dependencies and environments, with support for lockfiles, workspaces, and more,
|
||||
similar to `rye` or `poetry`:
|
||||
|
|
@ -80,14 +80,45 @@ Installed 2 packages in 1ms
|
|||
|
||||
$ uv run ruff check
|
||||
All checks passed!
|
||||
|
||||
$ uv lock
|
||||
Resolved 2 packages in 0.33ms
|
||||
|
||||
$ uv sync
|
||||
Resolved 2 packages in 0.70ms
|
||||
Audited 1 package in 0.02ms
|
||||
```
|
||||
|
||||
See the [project guide](./guides/projects.md) to get started.
|
||||
|
||||
uv also supports building and publishing projects, even if they're not managed with uv. See the
|
||||
[publish guide](./guides/publish.md) to learn more.
|
||||
[packaging guide](./guides/package.md) to learn more.
|
||||
|
||||
## Tool management
|
||||
## Scripts
|
||||
|
||||
uv manages dependencies and environments for single-file scripts.
|
||||
|
||||
Create a new script and add inline metadata declaring its dependencies:
|
||||
|
||||
```console
|
||||
$ echo 'import requests; print(requests.get("https://astral.sh"))' > example.py
|
||||
|
||||
$ uv add --script example.py requests
|
||||
Updated `example.py`
|
||||
```
|
||||
|
||||
Then, run the script in an isolated virtual environment:
|
||||
|
||||
```console
|
||||
$ uv run example.py
|
||||
Reading inline script metadata from: example.py
|
||||
Installed 5 packages in 12ms
|
||||
<Response [200]>
|
||||
```
|
||||
|
||||
See the [scripts guide](./guides/scripts.md) to get started.
|
||||
|
||||
## Tools
|
||||
|
||||
uv executes and installs command-line tools provided by Python packages, similar to `pipx`.
|
||||
|
||||
|
|
@ -125,7 +156,7 @@ ruff 0.5.4
|
|||
|
||||
See the [tools guide](./guides/tools.md) to get started.
|
||||
|
||||
## Python management
|
||||
## Python versions
|
||||
|
||||
uv installs Python and allows quickly switching between versions.
|
||||
|
||||
|
|
@ -166,30 +197,6 @@ Pinned `.python-version` to `3.11`
|
|||
|
||||
See the [installing Python guide](./guides/install-python.md) to get started.
|
||||
|
||||
## Script support
|
||||
|
||||
uv manages dependencies and environments for single-file scripts.
|
||||
|
||||
Create a new script and add inline metadata declaring its dependencies:
|
||||
|
||||
```console
|
||||
$ echo 'import requests; print(requests.get("https://astral.sh"))' > example.py
|
||||
|
||||
$ uv add --script example.py requests
|
||||
Updated `example.py`
|
||||
```
|
||||
|
||||
Then, run the script in an isolated virtual environment:
|
||||
|
||||
```console
|
||||
$ uv run example.py
|
||||
Reading inline script metadata from: example.py
|
||||
Installed 5 packages in 12ms
|
||||
<Response [200]>
|
||||
```
|
||||
|
||||
See the [scripts guide](./guides/scripts.md) to get started.
|
||||
|
||||
## The pip interface
|
||||
|
||||
uv provides a drop-in replacement for common `pip`, `pip-tools`, and `virtualenv` commands.
|
||||
|
|
|
|||
|
|
@ -68,6 +68,7 @@ plugins:
|
|||
# Note that redirecting an anchor, e.g., `concepts/projects/#managing-dependencies` must be done
|
||||
# client-side and is implemented in `extra.js` instead.
|
||||
redirect_maps:
|
||||
"guides/publish.md": "guides/package.md"
|
||||
"concepts/workspaces.md": "concepts/projects/workspaces.md"
|
||||
"concepts/dependencies.md": "concepts/projects/dependencies.md"
|
||||
"reference/versioning.md": "reference/policies/versioning.md"
|
||||
|
|
@ -103,7 +104,7 @@ nav:
|
|||
- Running scripts: guides/scripts.md
|
||||
- Using tools: guides/tools.md
|
||||
- Working on projects: guides/projects.md
|
||||
- Publishing packages: guides/publish.md
|
||||
- Publishing packages: guides/package.md
|
||||
- Integrations:
|
||||
- guides/integration/index.md
|
||||
- Docker: guides/integration/docker.md
|
||||
|
|
@ -166,4 +167,3 @@ validation:
|
|||
omitted_files: warn
|
||||
absolute_links: warn
|
||||
unrecognized_links: warn
|
||||
anchors: warn
|
||||
|
|
|
|||
Loading…
Reference in New Issue