From d5dd43aa182f3a384c041d91a15ca5d79dde685b Mon Sep 17 00:00:00 2001
From: samypr100 <3933065+samypr100@users.noreply.github.com>
Date: Fri, 10 Oct 2025 09:55:09 -0400
Subject: [PATCH] Missing added_in on new env vars (#16217)
## Summary
Adds the version for environment variables added in
https://github.com/astral-sh/uv/pull/16040 and
https://github.com/astral-sh/uv/pull/16125. as these were in-flight
before documentation versioning was added.
Adds ability to emit a compiler error when added in is missing for
improved reporting to the developer.
e.g. example for the ones fixed in this PR
```shell
error: missing #[attr_added_in("x.y.z")] on `UV_UPLOAD_HTTP_TIMEOUT`
note: env vars for an upcoming release should be annotated with `#[attr_added_in("next release")]`
--> crates\uv-static\src\env_vars.rs:593:15
|
593 | pub const UV_UPLOAD_HTTP_TIMEOUT: &'static str = "UV_UPLOAD_HTTP_TIMEOUT";
| ^^^^^^^^^^^^^^^^^^^^^^
error: missing #[attr_added_in("x.y.z")] on `UV_WORKING_DIRECTORY`
note: env vars for an upcoming release should be annotated with `#[attr_added_in("next release")]`
--> crates\uv-static\src\env_vars.rs:1087:15
|
1087 | pub const UV_WORKING_DIRECTORY: &'static str = "UV_WORKING_DIRECTORY";
| ^^^^^^^^^^^^^^^^^^^^
error: could not compile `uv-static` (lib) due to 2 previous errors
```
---
crates/uv-macros/src/lib.rs | 26 ++++++++++++++++++++++----
crates/uv-static/src/env_vars.rs | 3 ++-
docs/reference/environment.md | 2 ++
3 files changed, 26 insertions(+), 5 deletions(-)
diff --git a/crates/uv-macros/src/lib.rs b/crates/uv-macros/src/lib.rs
index 81a4c624b..d32e908fe 100644
--- a/crates/uv-macros/src/lib.rs
+++ b/crates/uv-macros/src/lib.rs
@@ -1,7 +1,8 @@
mod options_metadata;
use proc_macro::TokenStream;
-use quote::quote;
+use quote::{quote, quote_spanned};
+use syn::spanned::Spanned;
use syn::{Attribute, DeriveInput, ImplItem, ItemImpl, LitStr, parse_macro_input};
#[proc_macro_derive(OptionsMetadata, attributes(option, doc, option_group))]
@@ -109,14 +110,14 @@ pub fn attribute_env_vars_metadata(_attr: TokenStream, input: TokenStream) -> To
return None;
};
let name = lit.value();
- Some((name, doc, added_in))
+ Some((name, doc, added_in, item.ident.span()))
}
ImplItem::Fn(item) if !is_hidden(&item.attrs) => {
// Extract the environment variable patterns.
if let Some(pattern) = get_env_var_pattern_from_attr(&item.attrs) {
let doc = get_doc_comment(&item.attrs);
let added_in = get_added_in(&item.attrs);
- Some((pattern, doc, added_in))
+ Some((pattern, doc, added_in, item.sig.span()))
} else {
None // Skip if pattern extraction fails.
}
@@ -125,8 +126,25 @@ pub fn attribute_env_vars_metadata(_attr: TokenStream, input: TokenStream) -> To
})
.collect();
+ // Look for missing attr_added_in and issue a compiler error if any are found.
+ let added_in_errors: Vec<_> = constants
+ .iter()
+ .filter_map(|(name, _, added_in, span)| {
+ added_in.is_none().then_some({
+ let msg = format!(
+ "missing #[attr_added_in(\"x.y.z\")] on `{name}`\nnote: env vars for an upcoming release should be annotated with `#[attr_added_in(\"next release\")]`"
+ );
+ quote_spanned! {*span => compile_error!(#msg); }
+ })
+ })
+ .collect();
+
+ if !added_in_errors.is_empty() {
+ return quote! { #ast #(#added_in_errors)* }.into();
+ }
+
let struct_name = &ast.self_ty;
- let pairs = constants.iter().map(|(name, doc, added_in)| {
+ let pairs = constants.iter().map(|(name, doc, added_in, _span)| {
if let Some(added_in) = added_in {
quote! { (#name, #doc, Some(#added_in)) }
} else {
diff --git a/crates/uv-static/src/env_vars.rs b/crates/uv-static/src/env_vars.rs
index b6cf12a4d..fc073cf92 100644
--- a/crates/uv-static/src/env_vars.rs
+++ b/crates/uv-static/src/env_vars.rs
@@ -1,6 +1,5 @@
//! Environment variables used or supported by uv.
//! Used to generate `docs/reference/environment.md`.
-//! NOTICE: Upcoming release functionality should be documented with `#[attr_added_in("0.9.1")]`.
use uv_macros::{attr_added_in, attr_env_var_pattern, attr_hidden, attribute_env_vars_metadata};
/// Declares all environment variable used throughout `uv` and its crates.
@@ -591,6 +590,7 @@ impl EnvVars {
pub const NO_PROXY: &'static str = "NO_PROXY";
/// Timeout (in seconds) for only upload HTTP requests. (default: 900 s)
+ #[attr_added_in("0.9.1")]
pub const UV_UPLOAD_HTTP_TIMEOUT: &'static str = "UV_UPLOAD_HTTP_TIMEOUT";
/// Timeout (in seconds) for HTTP requests. (default: 30 s)
@@ -1085,6 +1085,7 @@ impl EnvVars {
pub const UV_PROJECT: &'static str = "UV_PROJECT";
/// Equivalent to the `--directory` command-line argument.
+ #[attr_added_in("0.9.1")]
pub const UV_WORKING_DIRECTORY: &'static str = "UV_WORKING_DIRECTORY";
/// Disable GitHub-specific requests that allow uv to skip `git fetch` in some circumstances.
diff --git a/docs/reference/environment.md b/docs/reference/environment.md
index 4f3ee4b48..f362853d0 100644
--- a/docs/reference/environment.md
+++ b/docs/reference/environment.md
@@ -652,6 +652,7 @@ Used ephemeral environments like CI to install uv to a specific path while preve
the installer from modifying shell profiles or environment variables.
### `UV_UPLOAD_HTTP_TIMEOUT`
+added in `0.9.1`
Timeout (in seconds) for only upload HTTP requests. (default: 900 s)
@@ -670,6 +671,7 @@ created by `uv venv`.
Note that `setuptools` and `wheel` are not included in Python 3.12+ environments.
### `UV_WORKING_DIRECTORY`
+added in `0.9.1`
Equivalent to the `--directory` command-line argument.