From a7300ab7af167734a566a9beb2422b2af5aa3ffd Mon Sep 17 00:00:00 2001 From: konstin Date: Thu, 10 Apr 2025 12:10:50 +0200 Subject: [PATCH 01/17] Make uv the preview default --- .../src/project_build_backend.rs | 3 +- crates/uv/src/commands/project/init.rs | 20 ++++- crates/uv/tests/it/init.rs | 85 +++++++++++++++++++ 3 files changed, 104 insertions(+), 4 deletions(-) diff --git a/crates/uv-configuration/src/project_build_backend.rs b/crates/uv-configuration/src/project_build_backend.rs index df1d97978c6ec..d5550acadbb16 100644 --- a/crates/uv-configuration/src/project_build_backend.rs +++ b/crates/uv-configuration/src/project_build_backend.rs @@ -1,5 +1,5 @@ /// Available project build backends for use in `pyproject.toml`. -#[derive(Clone, Copy, Debug, PartialEq, Default, serde::Deserialize)] +#[derive(Clone, Copy, Debug, PartialEq, serde::Deserialize)] #[serde(deny_unknown_fields, rename_all = "kebab-case")] #[cfg_attr(feature = "clap", derive(clap::ValueEnum))] #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] @@ -11,7 +11,6 @@ pub enum ProjectBuildBackend { #[cfg_attr(feature = "schemars", schemars(skip))] /// Use uv as the project build backend. Uv, - #[default] #[serde(alias = "hatchling")] #[cfg_attr(feature = "clap", value(alias = "hatchling"))] /// Use [hatchling](https://pypi.org/project/hatchling) as the project build backend. diff --git a/crates/uv/src/commands/project/init.rs b/crates/uv/src/commands/project/init.rs index a51f5489e423d..529c06959422a 100644 --- a/crates/uv/src/commands/project/init.rs +++ b/crates/uv/src/commands/project/init.rs @@ -149,6 +149,7 @@ pub(crate) async fn init( no_config, cache, printer, + preview, ) .await?; @@ -289,6 +290,7 @@ async fn init_project( no_config: bool, cache: &Cache, printer: Printer, + preview: PreviewMode, ) -> Result<()> { // Discover the current workspace, if it exists. let workspace_cache = WorkspaceCache::default(); @@ -575,6 +577,7 @@ async fn init_project( author_from, no_readme, package, + preview, )?; if let Some(workspace) = workspace { @@ -702,6 +705,7 @@ impl InitProjectKind { author_from: Option, no_readme: bool, package: bool, + preview: PreviewMode, ) -> Result<()> { match self { InitProjectKind::Application => InitProjectKind::init_application( @@ -716,6 +720,7 @@ impl InitProjectKind { author_from, no_readme, package, + preview, ), InitProjectKind::Library => InitProjectKind::init_library( name, @@ -729,6 +734,7 @@ impl InitProjectKind { author_from, no_readme, package, + preview, ), } } @@ -747,6 +753,7 @@ impl InitProjectKind { author_from: Option, no_readme: bool, package: bool, + preview: PreviewMode, ) -> Result<()> { fs_err::create_dir_all(path)?; @@ -779,7 +786,11 @@ impl InitProjectKind { } // Add a build system - let build_backend = build_backend.unwrap_or_default(); + let build_backend = match build_backend { + Some(build_backend) => build_backend, + None if preview.is_enabled() => ProjectBuildBackend::Uv, + None => ProjectBuildBackend::Hatch, + }; pyproject.push('\n'); pyproject.push_str(&pyproject_build_system(name, build_backend)); pyproject_build_backend_prerequisites(name, path, build_backend)?; @@ -829,6 +840,7 @@ impl InitProjectKind { author_from: Option, no_readme: bool, package: bool, + preview: PreviewMode, ) -> Result<()> { if !package { return Err(anyhow!("Library projects must be packaged")); @@ -849,7 +861,11 @@ impl InitProjectKind { ); // Always include a build system if the project is packaged. - let build_backend = build_backend.unwrap_or_default(); + let build_backend = match build_backend { + Some(build_backend) => build_backend, + None if preview.is_enabled() => ProjectBuildBackend::Uv, + None => ProjectBuildBackend::Hatch, + }; pyproject.push('\n'); pyproject.push_str(&pyproject_build_system(name, build_backend)); pyproject_build_backend_prerequisites(name, path, build_backend)?; diff --git a/crates/uv/tests/it/init.rs b/crates/uv/tests/it/init.rs index ccb397490f3d7..60c70884ff376 100644 --- a/crates/uv/tests/it/init.rs +++ b/crates/uv/tests/it/init.rs @@ -446,6 +446,91 @@ fn init_library() -> Result<()> { Ok(()) } +/// Test the uv build backend with using `uv init --lib --preview`. To be merged with the regular +/// init lib test once the uv build backend becomes the stable default. +#[test] +fn init_library_preview() -> Result<()> { + let context = TestContext::new("3.12"); + + let child = context.temp_dir.child("foo"); + child.create_dir_all()?; + + let pyproject_toml = child.join("pyproject.toml"); + let init_py = child.join("src").join("foo").join("__init__.py"); + let py_typed = child.join("src").join("foo").join("py.typed"); + + uv_snapshot!(context.filters(), context.init().current_dir(&child).arg("--lib").arg("--preview"), @r###" + success: true + exit_code: 0 + ----- stdout ----- + + ----- stderr ----- + Initialized project `foo` + "###); + + let pyproject = fs_err::read_to_string(&pyproject_toml)?; + let mut filters = context.filters(); + filters.push((r#"\["uv_build>=.*,<.*"\]"#, r#"["uv_build[SPECIFIERS]"]"#)); + insta::with_settings!({ + filters => filters, + }, { + assert_snapshot!( + pyproject, @r#" + [project] + name = "foo" + version = "0.1.0" + description = "Add your description here" + readme = "README.md" + requires-python = ">=3.12" + dependencies = [] + + [build-system] + requires = ["uv_build[SPECIFIERS]"] + build-backend = "uv_build" + "# + ); + }); + + let init = fs_err::read_to_string(init_py)?; + insta::with_settings!({ + filters => context.filters(), + }, { + assert_snapshot!( + init, @r###" + def hello() -> str: + return "Hello from foo!" + "### + ); + }); + + let py_typed = fs_err::read_to_string(py_typed)?; + insta::with_settings!({ + filters => context.filters(), + }, { + assert_snapshot!( + py_typed, @"" + ); + }); + + uv_snapshot!(context.filters(), context.run().arg("--preview").current_dir(&child).arg("python").arg("-c").arg("import foo; print(foo.hello())"), @r###" + success: true + exit_code: 0 + ----- stdout ----- + Hello from foo! + + ----- stderr ----- + warning: `VIRTUAL_ENV=[VENV]/` does not match the project environment path `.venv` and will be ignored; use `--active` to target the active environment instead + Using CPython 3.12.[X] interpreter at: [PYTHON-3.12] + Creating virtual environment at: .venv + Resolved 1 package in [TIME] + Prepared 1 package in [TIME] + Installed 1 package in [TIME] + + foo==0.1.0 (from file://[TEMP_DIR]/foo) + "###); + + Ok(()) +} + #[test] fn init_bare_lib() { let context = TestContext::new("3.12"); From d5e42d3fb0e06c5ed7dc938540bff94a4c5b9b8e Mon Sep 17 00:00:00 2001 From: konstin Date: Wed, 9 Apr 2025 23:12:17 +0200 Subject: [PATCH 02/17] uv build backend docs --- docs/concepts/projects/init.md | 4 +- docs/configuration/build_backend.md | 82 +++++++++++++++++++++++++++++ docs/configuration/index.md | 1 + mkdocs.template.yml | 1 + 4 files changed, 86 insertions(+), 2 deletions(-) create mode 100644 docs/configuration/build_backend.md diff --git a/docs/concepts/projects/init.md b/docs/concepts/projects/init.md index 75fe1adbbbfe1..3a8dd244e57f0 100644 --- a/docs/concepts/projects/init.md +++ b/docs/concepts/projects/init.md @@ -202,8 +202,8 @@ build-backend = "hatchling.build" !!! tip You can select a different build backend template by using `--build-backend` with `hatchling`, - `flit-core`, `pdm-backend`, `setuptools`, `maturin`, or `scikit-build-core`. An alternative - backend is required if you want to create a [library with extension modules](#projects-with-extension-modules). + `uv_build`, `flit-core`, `pdm-backend`, `setuptools`, `maturin`, or `scikit-build-core`. An + alternative backend is required if you want to create a [library with extension modules](#projects-with-extension-modules). The created module defines a simple API function: diff --git a/docs/configuration/build_backend.md b/docs/configuration/build_backend.md new file mode 100644 index 0000000000000..50ede0d3fe942 --- /dev/null +++ b/docs/configuration/build_backend.md @@ -0,0 +1,82 @@ +# The uv build backend + +!!! note + + The uv build backend is currently in preview and may change in any future release. + + By default, uv currently uses the hatchling build backend. + +A build backend transforms a source directory into a source distribution or a wheel. While uv +supports all build backends (PEP 517), it ships with the `uv_build` backend that integrates tightly +with uv. + +The uv build backend currently only supports Python code and only builds universal wheels. An +alternative backend is required if you want to create a +[library with extension modules](../concepts/projects/init.md#projects-with-extension-modules). + +To use the uv build backend, configure it in `pyproject.toml`: + +```toml +[build-system] +requires = ["uv_build>=0.6.13,<0.7"] +build-backend = "uv_build" +``` + +You can also use `uv init` to generate a new project that uses the uv build backend: + +```shell +uv init --build-backend uv +``` + +`uv_build` is a separate package from uv, optimized for a small size and high portability. `uv` +includes a copy of the build backend, so when running `uv build`, the same version will be used for +the build backend as for the uv process. Other build frontends, such as `python -m build`, will +choose the latest compatible `uv_build` version. + +## Include and exclude configuration + +To select which files to include in the source distribution, we first add the included files and +directories, then remove the excluded files and directories. + +When building the source distribution, the following files and directories are included: + +- `pyproject.toml` +- The module under `tool.uv.build-backend.module-root`, by default + `src//**`. +- `project.license-files` and `project.readme`. +- All directories under `tool.uv.build-backend.data`. +- All patterns from `tool.uv.build-backend.source-include`. + +From these, we remove the `tool.uv.build-backend.source-exclude` and the default excludes. + +When building the wheel, the following files and directories are included: + +- The module under `tool.uv.build-backend.module-root`, by default + `src//**`. +- `project.license-files` and `project.readme`, as part of the project metadata. +- Each directory under `tool.uv.build-backend.data`, as data directories. + +From these, we remove the `tool.uv.build-backend.source-exclude`, +`tool.uv.build-backend.wheel-exclude` and default excludes. The source dist excludes are applied to +avoid source tree to wheel source builds including more files than source tree to source +distribution to wheel build. + +There are no specific wheel includes. There must only be one top level module, and all data files +must either be under the module root or in the appropriate +[data directory](../reference/settings.md#build-backend_data). Most packages store small data in the +module root alongside the source code. + +## Include and exclude syntax + +Includes are anchored, which means that `pyproject.toml` includes only +`/pyproject.toml`. For example, `assets/**/sample.csv` includes all `sample.csv` files +in `/assets` or any child directory. To recursively include all files under a +directory, use a `/**` suffix, e.g. `src/**`. For performance and reproducibility, avoid patterns +without an anchor such as `**/sample.csv`. + +Excludes are not anchored, which means that `__pycache__` excludes all directories named +`__pycache__` and its children anywhere. To anchor a directory, use a `/` prefix, e.g., `/dist` will +exclude only `/dist`. + +All fields accepting patterns use the reduced portable glob syntax from +[PEP 639](https://peps.python.org/pep-0639/#add-license-FILES-key). diff --git a/docs/configuration/index.md b/docs/configuration/index.md index 38c68875fc1ec..d348f6a9c47a6 100644 --- a/docs/configuration/index.md +++ b/docs/configuration/index.md @@ -6,6 +6,7 @@ Read about the various ways to configure uv: - [Using environment variables](./environment.md) - [Configuring authentication](./authentication.md) - [Configuring package indexes](./indexes.md) +- [The uv build backend](./build_backend.md) Or, jump to the [settings reference](../reference/settings.md) which enumerates the available configuration options. diff --git a/mkdocs.template.yml b/mkdocs.template.yml index ac4f326630573..f957c053bb068 100644 --- a/mkdocs.template.yml +++ b/mkdocs.template.yml @@ -140,6 +140,7 @@ nav: - Authentication: configuration/authentication.md - Package indexes: configuration/indexes.md - Installer: configuration/installer.md + - uv build backend: configuration/build_backend.md - The pip interface: - pip/index.md - Using environments: pip/environments.md From 7192d3057c5e2d01e3ae687f11dcd170f8c3bf02 Mon Sep 17 00:00:00 2001 From: konsti Date: Thu, 17 Apr 2025 15:12:04 +0200 Subject: [PATCH 03/17] Update docs/configuration/build_backend.md Co-authored-by: Zanie Blue --- docs/configuration/build_backend.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/configuration/build_backend.md b/docs/configuration/build_backend.md index 50ede0d3fe942..6a8fcfdaa1178 100644 --- a/docs/configuration/build_backend.md +++ b/docs/configuration/build_backend.md @@ -2,9 +2,9 @@ !!! note - The uv build backend is currently in preview and may change in any future release. + The uv build backend is currently in preview and may change without warning. - By default, uv currently uses the hatchling build backend. + When preview mode is not enabled, uv uses [hatchling](https://pypi.org/project/hatchling/) as the default build backend. A build backend transforms a source directory into a source distribution or a wheel. While uv supports all build backends (PEP 517), it ships with the `uv_build` backend that integrates tightly From c07664d401d1ff9489575cfed1aff0404f11978b Mon Sep 17 00:00:00 2001 From: konsti Date: Thu, 17 Apr 2025 15:12:13 +0200 Subject: [PATCH 04/17] Update docs/configuration/build_backend.md Co-authored-by: Zanie Blue --- docs/configuration/build_backend.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration/build_backend.md b/docs/configuration/build_backend.md index 6a8fcfdaa1178..5b5f0dd86c4f0 100644 --- a/docs/configuration/build_backend.md +++ b/docs/configuration/build_backend.md @@ -6,7 +6,7 @@ When preview mode is not enabled, uv uses [hatchling](https://pypi.org/project/hatchling/) as the default build backend. -A build backend transforms a source directory into a source distribution or a wheel. While uv +A build backend transforms a source tree (i.e., a directory) into a source distribution or a wheel. While uv supports all build backends (PEP 517), it ships with the `uv_build` backend that integrates tightly with uv. From 2a0ab67d64b27a22361925b5dec1c2756b6a63c5 Mon Sep 17 00:00:00 2001 From: konsti Date: Thu, 17 Apr 2025 15:12:20 +0200 Subject: [PATCH 05/17] Update docs/configuration/build_backend.md Co-authored-by: Zanie Blue --- docs/configuration/build_backend.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration/build_backend.md b/docs/configuration/build_backend.md index 5b5f0dd86c4f0..b5c0776bec2e3 100644 --- a/docs/configuration/build_backend.md +++ b/docs/configuration/build_backend.md @@ -7,7 +7,7 @@ When preview mode is not enabled, uv uses [hatchling](https://pypi.org/project/hatchling/) as the default build backend. A build backend transforms a source tree (i.e., a directory) into a source distribution or a wheel. While uv -supports all build backends (PEP 517), it ships with the `uv_build` backend that integrates tightly +supports all build backends (as specified by PEP 517), it includes a `uv_build` backend that integrates tightly with uv. The uv build backend currently only supports Python code and only builds universal wheels. An From f5cacf5e64f021da0eafb230f43a87d93524b74b Mon Sep 17 00:00:00 2001 From: konsti Date: Thu, 17 Apr 2025 15:12:27 +0200 Subject: [PATCH 06/17] Update docs/configuration/build_backend.md Co-authored-by: Zanie Blue --- docs/configuration/build_backend.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration/build_backend.md b/docs/configuration/build_backend.md index b5c0776bec2e3..5dcdd51aa6229 100644 --- a/docs/configuration/build_backend.md +++ b/docs/configuration/build_backend.md @@ -8,7 +8,7 @@ A build backend transforms a source tree (i.e., a directory) into a source distribution or a wheel. While uv supports all build backends (as specified by PEP 517), it includes a `uv_build` backend that integrates tightly -with uv. +with uv to improve performance and user experience. The uv build backend currently only supports Python code and only builds universal wheels. An alternative backend is required if you want to create a From 51b538a92aeef8c497bb25f1bb0bea3a473d419a Mon Sep 17 00:00:00 2001 From: konsti Date: Thu, 17 Apr 2025 15:12:37 +0200 Subject: [PATCH 07/17] Update docs/configuration/build_backend.md Co-authored-by: Zanie Blue --- docs/configuration/build_backend.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration/build_backend.md b/docs/configuration/build_backend.md index 5dcdd51aa6229..6f941ff6b5b38 100644 --- a/docs/configuration/build_backend.md +++ b/docs/configuration/build_backend.md @@ -14,7 +14,7 @@ The uv build backend currently only supports Python code and only builds univers alternative backend is required if you want to create a [library with extension modules](../concepts/projects/init.md#projects-with-extension-modules). -To use the uv build backend, configure it in `pyproject.toml`: +To use the uv build backend in an existing project, add it to the `[build-system]` section in your `pyproject.toml`: ```toml [build-system] From fc9f2f3d3c589bab27416402de69e3b6cb0e9ca5 Mon Sep 17 00:00:00 2001 From: konsti Date: Thu, 17 Apr 2025 15:12:48 +0200 Subject: [PATCH 08/17] Update docs/configuration/build_backend.md Co-authored-by: Zanie Blue --- docs/configuration/build_backend.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration/build_backend.md b/docs/configuration/build_backend.md index 6f941ff6b5b38..1f3f5f2ce9344 100644 --- a/docs/configuration/build_backend.md +++ b/docs/configuration/build_backend.md @@ -22,7 +22,7 @@ requires = ["uv_build>=0.6.13,<0.7"] build-backend = "uv_build" ``` -You can also use `uv init` to generate a new project that uses the uv build backend: +You can also create a new project that uses the uv build backend with `uv init`: ```shell uv init --build-backend uv From 96d013f515f1a486e1be38393a140a75c7508b13 Mon Sep 17 00:00:00 2001 From: konsti Date: Thu, 17 Apr 2025 15:13:38 +0200 Subject: [PATCH 09/17] Update docs/configuration/build_backend.md Co-authored-by: Zanie Blue --- docs/configuration/build_backend.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration/build_backend.md b/docs/configuration/build_backend.md index 1f3f5f2ce9344..6edae9a29f825 100644 --- a/docs/configuration/build_backend.md +++ b/docs/configuration/build_backend.md @@ -35,7 +35,7 @@ choose the latest compatible `uv_build` version. ## Include and exclude configuration -To select which files to include in the source distribution, we first add the included files and +To select which files to include in the source distribution, uv first adds the included files and directories, then remove the excluded files and directories. When building the source distribution, the following files and directories are included: From 103f623b1d7f5990cf48f6c38cf79f21c2d6cfde Mon Sep 17 00:00:00 2001 From: konsti Date: Thu, 17 Apr 2025 15:13:49 +0200 Subject: [PATCH 10/17] Update docs/configuration/build_backend.md Co-authored-by: Zanie Blue --- docs/configuration/build_backend.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration/build_backend.md b/docs/configuration/build_backend.md index 6edae9a29f825..85365d6ed74b5 100644 --- a/docs/configuration/build_backend.md +++ b/docs/configuration/build_backend.md @@ -36,7 +36,7 @@ choose the latest compatible `uv_build` version. ## Include and exclude configuration To select which files to include in the source distribution, uv first adds the included files and -directories, then remove the excluded files and directories. +directories, then removes the excluded files and directories. This means that exclusions always take precedence over inclusions. When building the source distribution, the following files and directories are included: From 11e8fee70c315c20ba2175ec431fa375c02fcf0e Mon Sep 17 00:00:00 2001 From: konstin Date: Wed, 23 Apr 2025 15:40:27 +0200 Subject: [PATCH 11/17] Editing --- .../{build_backend.md => build-backend.md} | 36 ++++++++++--------- docs/configuration/index.md | 2 +- mkdocs.template.yml | 2 +- pyproject.toml | 1 + 4 files changed, 23 insertions(+), 18 deletions(-) rename docs/configuration/{build_backend.md => build-backend.md} (69%) diff --git a/docs/configuration/build_backend.md b/docs/configuration/build-backend.md similarity index 69% rename from docs/configuration/build_backend.md rename to docs/configuration/build-backend.md index 85365d6ed74b5..e83625d094d72 100644 --- a/docs/configuration/build_backend.md +++ b/docs/configuration/build-backend.md @@ -6,15 +6,16 @@ When preview mode is not enabled, uv uses [hatchling](https://pypi.org/project/hatchling/) as the default build backend. -A build backend transforms a source tree (i.e., a directory) into a source distribution or a wheel. While uv -supports all build backends (as specified by PEP 517), it includes a `uv_build` backend that integrates tightly -with uv to improve performance and user experience. +A build backend transforms a source tree (i.e., a directory) into a source distribution or a wheel. +While uv supports all build backends (as specified by PEP 517), it includes a `uv_build` backend +that integrates tightly with uv to improve performance and user experience. The uv build backend currently only supports Python code and only builds universal wheels. An alternative backend is required if you want to create a [library with extension modules](../concepts/projects/init.md#projects-with-extension-modules). -To use the uv build backend in an existing project, add it to the `[build-system]` section in your `pyproject.toml`: +To use the uv build backend in an existing project, add it to the `[build-system]` section in your +`pyproject.toml`: ```toml [build-system] @@ -28,15 +29,16 @@ You can also create a new project that uses the uv build backend with `uv init`: uv init --build-backend uv ``` -`uv_build` is a separate package from uv, optimized for a small size and high portability. `uv` -includes a copy of the build backend, so when running `uv build`, the same version will be used for -the build backend as for the uv process. Other build frontends, such as `python -m build`, will -choose the latest compatible `uv_build` version. +`uv_build` is a separate package from uv, optimized for portability and small binary size. The `uv` +command includes a copy of the build backend, so when running `uv build`, the same version will be +used for the build backend as for the uv process. Other build frontends, such as `python -m build`, +will choose the latest compatible `uv_build` version. ## Include and exclude configuration To select which files to include in the source distribution, uv first adds the included files and -directories, then removes the excluded files and directories. This means that exclusions always take precedence over inclusions. +directories, then removes the excluded files and directories. This means that exclusions always take +precedence over inclusions. When building the source distribution, the following files and directories are included: @@ -47,7 +49,7 @@ When building the source distribution, the following files and directories are i - All directories under `tool.uv.build-backend.data`. - All patterns from `tool.uv.build-backend.source-include`. -From these, we remove the `tool.uv.build-backend.source-exclude` and the default excludes. +From these, `tool.uv.build-backend.source-exclude` and the default excludes are removed. When building the wheel, the following files and directories are included: @@ -56,10 +58,9 @@ When building the wheel, the following files and directories are included: - `project.license-files` and `project.readme`, as part of the project metadata. - Each directory under `tool.uv.build-backend.data`, as data directories. -From these, we remove the `tool.uv.build-backend.source-exclude`, -`tool.uv.build-backend.wheel-exclude` and default excludes. The source dist excludes are applied to -avoid source tree to wheel source builds including more files than source tree to source -distribution to wheel build. +From these, `tool.uv.build-backend.source-exclude`, `tool.uv.build-backend.wheel-exclude` and the +default excludes are removed. The source dist excludes are applied to avoid source tree to wheel +source builds including more files than source tree to source distribution to wheel build. There are no specific wheel includes. There must only be one top level module, and all data files must either be under the module root or in the appropriate @@ -71,8 +72,11 @@ module root alongside the source code. Includes are anchored, which means that `pyproject.toml` includes only `/pyproject.toml`. For example, `assets/**/sample.csv` includes all `sample.csv` files in `/assets` or any child directory. To recursively include all files under a -directory, use a `/**` suffix, e.g. `src/**`. For performance and reproducibility, avoid patterns -without an anchor such as `**/sample.csv`. +directory, use a `/**` suffix, e.g. `src/**`. + +!!! note + + For performance and reproducibility, avoid patterns without an anchor such as `**/sample.csv`. Excludes are not anchored, which means that `__pycache__` excludes all directories named `__pycache__` and its children anywhere. To anchor a directory, use a `/` prefix, e.g., `/dist` will diff --git a/docs/configuration/index.md b/docs/configuration/index.md index d348f6a9c47a6..813519629ea0e 100644 --- a/docs/configuration/index.md +++ b/docs/configuration/index.md @@ -6,7 +6,7 @@ Read about the various ways to configure uv: - [Using environment variables](./environment.md) - [Configuring authentication](./authentication.md) - [Configuring package indexes](./indexes.md) -- [The uv build backend](./build_backend.md) +- [The uv build backend](build-backend.md) Or, jump to the [settings reference](../reference/settings.md) which enumerates the available configuration options. diff --git a/mkdocs.template.yml b/mkdocs.template.yml index f957c053bb068..8f00d782bd137 100644 --- a/mkdocs.template.yml +++ b/mkdocs.template.yml @@ -140,7 +140,7 @@ nav: - Authentication: configuration/authentication.md - Package indexes: configuration/indexes.md - Installer: configuration/installer.md - - uv build backend: configuration/build_backend.md + - Build backend: configuration/build-backend.md - The pip interface: - pip/index.md - Using environments: pip/environments.md diff --git a/pyproject.toml b/pyproject.toml index 9a3f41d946491..285445f86844a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -86,6 +86,7 @@ version_files = [ "docs/guides/integration/pre-commit.md", "docs/guides/integration/github.md", "docs/guides/integration/aws-lambda.md", + "docs/configuration/build_backend.md", ] [tool.mypy] From 82461198a782866364fb2a3bf02d8611f6dd7e4f Mon Sep 17 00:00:00 2001 From: konstin Date: Wed, 23 Apr 2025 15:50:12 +0200 Subject: [PATCH 12/17] Add admonition about upper bounds --- docs/configuration/build-backend.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/configuration/build-backend.md b/docs/configuration/build-backend.md index e83625d094d72..a894df9b831b2 100644 --- a/docs/configuration/build-backend.md +++ b/docs/configuration/build-backend.md @@ -23,6 +23,12 @@ requires = ["uv_build>=0.6.13,<0.7"] build-backend = "uv_build" ``` +!!! important + + The uv build backend follows the same + [versioning policy](https://docs.astral.sh/uv/reference/versioning/), setting an upper bound on + the `uv_build` version ensures that the package continues to build in the future. + You can also create a new project that uses the uv build backend with `uv init`: ```shell From 025cb5936fbcf9171c9a0de5595d81ee5adfbb60 Mon Sep 17 00:00:00 2001 From: konstin Date: Wed, 23 Apr 2025 16:01:45 +0200 Subject: [PATCH 13/17] Editing --- docs/configuration/build-backend.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/configuration/build-backend.md b/docs/configuration/build-backend.md index a894df9b831b2..9d752b35d5cd9 100644 --- a/docs/configuration/build-backend.md +++ b/docs/configuration/build-backend.md @@ -10,8 +10,8 @@ A build backend transforms a source tree (i.e., a directory) into a source distr While uv supports all build backends (as specified by PEP 517), it includes a `uv_build` backend that integrates tightly with uv to improve performance and user experience. -The uv build backend currently only supports Python code and only builds universal wheels. An -alternative backend is required if you want to create a +The uv build backend currently only supports Python code. An alternative backend is required if you +want to create a [library with extension modules](../concepts/projects/init.md#projects-with-extension-modules). To use the uv build backend in an existing project, add it to the `[build-system]` section in your From 9517cb9e00944eb08108393124830c81da33d3c5 Mon Sep 17 00:00:00 2001 From: konstin Date: Fri, 25 Apr 2025 10:12:01 +0200 Subject: [PATCH 14/17] Test `--package` --- crates/uv/tests/it/init.rs | 47 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/crates/uv/tests/it/init.rs b/crates/uv/tests/it/init.rs index 60c70884ff376..d86eba07a406a 100644 --- a/crates/uv/tests/it/init.rs +++ b/crates/uv/tests/it/init.rs @@ -531,6 +531,53 @@ fn init_library_preview() -> Result<()> { Ok(()) } +/// Test the uv build backend with using `uv init --package --preview`. To be merged with the regular +/// init lib test once the uv build backend becomes the stable default. +#[test] +fn init_package_preview() -> Result<()> { + let context = TestContext::new("3.12"); + + let child = context.temp_dir.child("foo"); + child.create_dir_all()?; + + uv_snapshot!(context.filters(), context.init().current_dir(&child).arg("--package").arg("--preview"), @r###" + success: true + exit_code: 0 + ----- stdout ----- + + ----- stderr ----- + Initialized project `foo` + "###); + + let pyproject = fs_err::read_to_string(child.join("pyproject.toml"))?; + let mut filters = context.filters(); + filters.push((r#"\["uv_build>=.*,<.*"\]"#, r#"["uv_build[SPECIFIERS]"]"#)); + insta::with_settings!({ + filters => filters, + }, { + assert_snapshot!( + pyproject, @r#" + [project] + name = "foo" + version = "0.1.0" + description = "Add your description here" + readme = "README.md" + requires-python = ">=3.12" + dependencies = [] + + [project.scripts] + foo = "foo:main" + + [build-system] + requires = ["uv_build[SPECIFIERS]"] + build-backend = "uv_build" + "# + ); + }); + + Ok(()) +} + #[test] fn init_bare_lib() { let context = TestContext::new("3.12"); From bdc8288472dd75818f5a4f68affe41d05a6d9d5f Mon Sep 17 00:00:00 2001 From: konstin Date: Fri, 25 Apr 2025 10:12:04 +0200 Subject: [PATCH 15/17] Link build system docs --- docs/configuration/build-backend.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/configuration/build-backend.md b/docs/configuration/build-backend.md index 9d752b35d5cd9..a4cac3f04a19c 100644 --- a/docs/configuration/build-backend.md +++ b/docs/configuration/build-backend.md @@ -14,8 +14,9 @@ The uv build backend currently only supports Python code. An alternative backend want to create a [library with extension modules](../concepts/projects/init.md#projects-with-extension-modules). -To use the uv build backend in an existing project, add it to the `[build-system]` section in your -`pyproject.toml`: +To use the uv build backend as +[build system](https://docs.astral.sh/uv/concepts/projects/config/#build-systems) in an existing +project, add it to the `[build-system]` section in your `pyproject.toml`: ```toml [build-system] From 2a75f4dbdf797104f96e316df6e7813ef168981c Mon Sep 17 00:00:00 2001 From: konsti Date: Mon, 5 May 2025 15:39:49 +0200 Subject: [PATCH 16/17] Update pyproject.toml Co-authored-by: Zanie Blue --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 285445f86844a..4dab66c87919a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -86,7 +86,7 @@ version_files = [ "docs/guides/integration/pre-commit.md", "docs/guides/integration/github.md", "docs/guides/integration/aws-lambda.md", - "docs/configuration/build_backend.md", + "docs/configuration/build-backend.md", ] [tool.mypy] From e4c0f6d4310dcd59bd61850c710de01a0a359355 Mon Sep 17 00:00:00 2001 From: konstin Date: Mon, 5 May 2025 15:42:40 +0200 Subject: [PATCH 17/17] Use relative links --- docs/configuration/build-backend.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/configuration/build-backend.md b/docs/configuration/build-backend.md index a4cac3f04a19c..6825919f020a5 100644 --- a/docs/configuration/build-backend.md +++ b/docs/configuration/build-backend.md @@ -14,9 +14,8 @@ The uv build backend currently only supports Python code. An alternative backend want to create a [library with extension modules](../concepts/projects/init.md#projects-with-extension-modules). -To use the uv build backend as -[build system](https://docs.astral.sh/uv/concepts/projects/config/#build-systems) in an existing -project, add it to the `[build-system]` section in your `pyproject.toml`: +To use the uv build backend as [build system](../concepts/projects/config.md#build-systems) in an +existing project, add it to the `[build-system]` section in your `pyproject.toml`: ```toml [build-system] @@ -26,9 +25,9 @@ build-backend = "uv_build" !!! important - The uv build backend follows the same - [versioning policy](https://docs.astral.sh/uv/reference/versioning/), setting an upper bound on - the `uv_build` version ensures that the package continues to build in the future. + The uv build backend follows the same [versioning policy](../reference/policies/versioning.md), + setting an upper bound on the `uv_build` version ensures that the package continues to build in + the future. You can also create a new project that uses the uv build backend with `uv init`: