From c9637f00f089b647e1bd4f371e7a54dfcb56335f Mon Sep 17 00:00:00 2001 From: Mathieu Kniewallner Date: Wed, 17 Jul 2024 02:41:45 +0200 Subject: [PATCH] docs: bunch of fixes and improvements (#5136) ## Summary A bunch of fixes and improvements on different parts of the documentation. For Docker documentation changes, links to the relevant documentations have been included in the commit messages. --- docs/cache.md | 4 ++-- docs/configuration/environment.md | 6 +++--- docs/guides/docker.md | 6 ++---- docs/guides/pre-commit.md | 6 +++--- docs/guides/using-azure-artifacts.md | 14 +++++++------- docs/preview/workspaces.md | 2 +- 6 files changed, 18 insertions(+), 20 deletions(-) diff --git a/docs/cache.md b/docs/cache.md index 0b62f49fa..2f2b689a8 100644 --- a/docs/cache.md +++ b/docs/cache.md @@ -17,12 +17,12 @@ The specifics of uv's caching semantics vary based on the nature of the dependen the local `.whl` or `.tar.gz` file). For directories, uv caches based on the last-modified time of the `pyproject.toml`, `setup.py`, or `setup.cfg` file. -It's safe to run multiple `uv` commands concurrently, even against the same virtual environment. +It's safe to run multiple uv commands concurrently, even against the same virtual environment. uv's cache is designed to be thread-safe and append-only, and thus robust to multiple concurrent readers and writers. uv applies a file-based lock to the target virtual environment when installing, to avoid concurrent modifications across processes. -Note that it's _not_ safe to modify the uv cache directly (e.g., `uv cache clean`) while other `uv` +Note that it's _not_ safe to modify the uv cache directly (e.g., `uv cache clean`) while other uv commands are running, and _never_ safe to modify the cache directly (e.g., by removing a file or directory). diff --git a/docs/configuration/environment.md b/docs/configuration/environment.md index 93f81bd9c..520d17bc5 100644 --- a/docs/configuration/environment.md +++ b/docs/configuration/environment.md @@ -40,16 +40,16 @@ uv accepts the following command-line arguments as environment variables: as a link mode. - `UV_NO_BUILD_ISOLATION`: Equivalent to the `--no-build-isolation` command-line argument. If set, uv will skip isolation when building source distributions. -- `UV_CUSTOM_COMPILE_COMMAND`: Used to override `uv` in the output header of the `requirements.txt` +- `UV_CUSTOM_COMPILE_COMMAND`: Used to override uv in the output header of the `requirements.txt` files generated by `uv pip compile`. Intended for use-cases in which `uv pip compile` is called from within a wrapper script, to include the name of the wrapper script in the output file. - `UV_KEYRING_PROVIDER`: Equivalent to the `--keyring-provider` command-line argument. If set, uv will use this value as the keyring provider. - `UV_CONFIG_FILE`: Equivalent to the `--config-file` command-line argument. Expects a path to a local `uv.toml` file to use as the configuration file. -- `UV_CONCURRENT_DOWNLOADS`: Sets the maximum number of in-flight concurrent downloads that `uv` +- `UV_CONCURRENT_DOWNLOADS`: Sets the maximum number of in-flight concurrent downloads that uv will perform at any given time. -- `UV_CONCURRENT_BUILDS`: Sets the maximum number of source distributions that `uv` will build +- `UV_CONCURRENT_BUILDS`: Sets the maximum number of source distributions that uv will build concurrently at any given time. - `UV_CONCURRENT_INSTALLS`: Used to control the number of threads used when installing and unzipping packages. diff --git a/docs/guides/docker.md b/docs/guides/docker.md index 4df5d4f9a..18b6b6d7a 100644 --- a/docs/guides/docker.md +++ b/docs/guides/docker.md @@ -13,9 +13,8 @@ docker run ghcr.io/astral-sh/uv --help uv can be installed by copying from the official Docker image: ```dockerfile -FROM ghcr.io/astral-sh/uv:latest as uv FROM python:3.12-slim-bullseye -COPY --from=uv /uv /bin/uv +COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv ``` Or with the standalone installer: @@ -24,8 +23,7 @@ Or with the standalone installer: FROM python:3.12-slim-bullseye RUN apt-get update && apt-get install -y curl --no-install-recommends RUN curl -LsSf https://astral.sh/uv/install.sh | sh -ENV PATH="/root/.cargo/bin/: -$PATH" +ENV PATH="/root/.cargo/bin/:$PATH" ``` Note this requires `curl` to be available. diff --git a/docs/guides/pre-commit.md b/docs/guides/pre-commit.md index 74a1b9d94..590bcb0dd 100644 --- a/docs/guides/pre-commit.md +++ b/docs/guides/pre-commit.md @@ -7,7 +7,7 @@ To compile requirements via pre-commit, add the following to the `.pre-commit-co ```yaml - repo: https://github.com/astral-sh/uv-pre-commit # uv version. - rev: 0.2.13 + rev: 0.2.25 hooks: # Compile requirements - id: pip-compile @@ -19,7 +19,7 @@ To compile alternative files, modify `args` and `files`: ```yaml - repo: https://github.com/astral-sh/uv-pre-commit # uv version. - rev: 0.2.13 + rev: 0.2.25 hooks: # Compile requirements - id: pip-compile @@ -32,7 +32,7 @@ To run the hook over multiple files at the same time: ```yaml - repo: https://github.com/astral-sh/uv-pre-commit # uv version. - rev: 0.2.13 + rev: 0.2.25 hooks: # Compile requirements - id: pip-compile diff --git a/docs/guides/using-azure-artifacts.md b/docs/guides/using-azure-artifacts.md index cbc159544..216f3df39 100644 --- a/docs/guides/using-azure-artifacts.md +++ b/docs/guides/using-azure-artifacts.md @@ -1,25 +1,25 @@ # Using Azure Artifacts -`uv` can install packages from [Azure DevOps Artifacts](https://learn.microsoft.com/en-us/azure/devops/artifacts/start-using-azure-artifacts?view=azure-devops&tabs=nuget%2Cnugetserver). You can authenticate to a feed using a [Personal Access Token](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=Windows) or interactively using Keyring. - +uv can install packages from [Azure DevOps Artifacts](https://learn.microsoft.com/en-us/azure/devops/artifacts/start-using-azure-artifacts?view=azure-devops&tabs=nuget%2Cnugetserver). You can authenticate to a feed using a [Personal Access Token](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=Windows) or interactively using Keyring. ## Authenticate using a PAT -If you have a Personal Access Token available (eg [`$(System.AccessToken)` in an Azure pipeline](https://learn.microsoft.com/en-us/azure/devops/pipelines/build/variables?view=azure-devops&tabs=yaml#systemaccesstoken)), you can authenticate to Artifacts using Basic Auth. Simply include the PAT in the password field of the URL. The username can be any dummy string. + +If you have a Personal Access Token available (e.g. [`$(System.AccessToken)` in an Azure pipeline](https://learn.microsoft.com/en-us/azure/devops/pipelines/build/variables?view=azure-devops&tabs=yaml#systemaccesstoken)), you can authenticate to Artifacts using Basic Auth. Simply include the PAT in the password field of the URL. The username can be any dummy string. ```bash # if your token is in the ADO_PAT environment variable -export UV_EXTRA_INDEX_URL=https://dummy:$ADO_PAT@pkgs.dev.azure.com/{organisation}/{project}/_packaging/{feedName}/pypi/simple/ +export UV_EXTRA_INDEX_URL=https://dummy:$ADO_PAT@pkgs.dev.azure.com/{organization}/{project}/_packaging/{feedName}/pypi/simple/ uv pip install my-private-package ``` - ## Authenticate using Keyring + If you don’t have a PAT handy, you can authenticate to Artifacts using [`keyring`](https://github.com/jaraco/keyring) with [the `artifacts-keyring` plugin](https://github.com/Microsoft/artifacts-keyring). Because you’ll be using these two packages to authenticate to Azure Artifacts, you should arrange to have them installed into your environment from a source other than Artifacts. The `artifacts-keyring` plugin wraps [the Azure Artifacts Credential Provider tool](https://github.com/microsoft/artifacts-credprovider). The credential provider supports a few different authentication modes including interactive login — see [the tool's docs](https://github.com/microsoft/artifacts-credprovider) for information on how to configure it. -[`uv` only supports using Keyring in subprocess mode](https://github.com/astral-sh/uv/blob/main/PIP_COMPATIBILITY.md#registry-authentication). The `keyring` executable must be on the `PATH`, meaning it should be installed globally or into your currently-active virtual environment. Keyring’s CLI requires a username in the URL, so you should modify your index URL to include the default username `VssSessionToken`. +[uv only supports using Keyring in subprocess mode](https://github.com/astral-sh/uv/blob/main/PIP_COMPATIBILITY.md#registry-authentication). The `keyring` executable must be on the `PATH`, meaning it should be installed globally or into your currently-active virtual environment. Keyring’s CLI requires a username in the URL, so you should modify your index URL to include the default username `VssSessionToken`. ```bash # preinstall keyring and the Artifacts plugin from the public PyPI @@ -29,7 +29,7 @@ uv pip install keyring artifacts-keyring export UV_KEYRING_PROVIDER=subprocess # include default username in URL -export UV_EXTRA_INDEX_URL=https://VssSessionToken@pkgs.dev.azure.com/{organisation}/{project}/_packaging/{feedName}/pypi/simple/ +export UV_EXTRA_INDEX_URL=https://VssSessionToken@pkgs.dev.azure.com/{organization}/{project}/_packaging/{feedName}/pypi/simple/ uv pip install my-private-package ``` diff --git a/docs/preview/workspaces.md b/docs/preview/workspaces.md index 49737dba3..bd5cae0f7 100644 --- a/docs/preview/workspaces.md +++ b/docs/preview/workspaces.md @@ -6,7 +6,7 @@ Workspaces help organize large codebases by splitting them into multiple package independent dependencies. When using the `uv pip` interface, workspace dependencies behave like automatic editable path -dependencies. Using the `uv` project interface, all of the workspace packages are locked together. +dependencies. Using the uv project interface, all of the workspace packages are locked together. `uv run` installs only the current package (unless overridden with `--package`) and its workspace and non-workspace dependencies.