uv_python/
python_version.rs

1#[cfg(feature = "schemars")]
2use std::borrow::Cow;
3use std::collections::BTreeMap;
4use std::env;
5use std::ffi::OsString;
6use std::fmt::{Display, Formatter};
7use std::ops::Deref;
8use std::str::FromStr;
9
10use thiserror::Error;
11use uv_pep440::Version;
12use uv_pep508::{MarkerEnvironment, StringVersion};
13use uv_static::EnvVars;
14
15use crate::implementation::ImplementationName;
16
17#[derive(Error, Debug)]
18pub enum BuildVersionError {
19    #[error("`{0}` is not valid unicode: {1:?}")]
20    NotUnicode(&'static str, OsString),
21}
22
23#[derive(Debug, Clone, PartialEq, Eq, Hash)]
24pub struct PythonVersion(StringVersion);
25
26impl From<StringVersion> for PythonVersion {
27    fn from(version: StringVersion) -> Self {
28        Self(version)
29    }
30}
31
32impl Deref for PythonVersion {
33    type Target = StringVersion;
34
35    fn deref(&self) -> &Self::Target {
36        &self.0
37    }
38}
39
40impl FromStr for PythonVersion {
41    type Err = String;
42
43    fn from_str(s: &str) -> Result<Self, Self::Err> {
44        let version = StringVersion::from_str(s)
45            .map_err(|err| format!("Python version `{s}` could not be parsed: {err}"))?;
46        if version.is_dev() {
47            return Err(format!("Python version `{s}` is a development release"));
48        }
49        if version.is_local() {
50            return Err(format!("Python version `{s}` is a local version"));
51        }
52        if version.epoch() != 0 {
53            return Err(format!("Python version `{s}` has a non-zero epoch"));
54        }
55        if let Some(major) = version.release().first() {
56            if u8::try_from(*major).is_err() {
57                return Err(format!(
58                    "Python version `{s}` has an invalid major version ({major})"
59                ));
60            }
61        }
62        if let Some(minor) = version.release().get(1) {
63            if u8::try_from(*minor).is_err() {
64                return Err(format!(
65                    "Python version `{s}` has an invalid minor version ({minor})"
66                ));
67            }
68        }
69        if let Some(patch) = version.release().get(2) {
70            if u8::try_from(*patch).is_err() {
71                return Err(format!(
72                    "Python version `{s}` has an invalid patch version ({patch})"
73                ));
74            }
75        }
76
77        Ok(Self(version))
78    }
79}
80
81#[cfg(feature = "schemars")]
82impl schemars::JsonSchema for PythonVersion {
83    fn schema_name() -> Cow<'static, str> {
84        Cow::Borrowed("PythonVersion")
85    }
86
87    fn json_schema(_generator: &mut schemars::generate::SchemaGenerator) -> schemars::Schema {
88        schemars::json_schema!({
89            "type": "string",
90            "pattern": r"^3\.\d+(\.\d+)?$",
91            "description": "A Python version specifier, e.g. `3.11` or `3.12.4`."
92        })
93    }
94}
95
96impl<'de> serde::Deserialize<'de> for PythonVersion {
97    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
98        struct Visitor;
99
100        impl serde::de::Visitor<'_> for Visitor {
101            type Value = PythonVersion;
102
103            fn expecting(&self, f: &mut Formatter) -> std::fmt::Result {
104                f.write_str("a string")
105            }
106
107            fn visit_str<E: serde::de::Error>(self, v: &str) -> Result<Self::Value, E> {
108                PythonVersion::from_str(v).map_err(serde::de::Error::custom)
109            }
110        }
111
112        deserializer.deserialize_str(Visitor)
113    }
114}
115
116impl Display for PythonVersion {
117    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
118        Display::fmt(&self.0, f)
119    }
120}
121
122impl PythonVersion {
123    /// Return a [`MarkerEnvironment`] compatible with the given [`PythonVersion`], based on
124    /// a base [`MarkerEnvironment`].
125    ///
126    /// The returned [`MarkerEnvironment`] will preserve the base environment's platform markers,
127    /// but override its Python version markers.
128    pub fn markers(&self, base: &MarkerEnvironment) -> MarkerEnvironment {
129        let mut markers = base.clone();
130
131        // Ex) `implementation_version == "3.12.0"`
132        if markers.implementation_name() == "cpython" {
133            let python_full_version = self.python_full_version();
134            markers = markers.with_implementation_version(StringVersion {
135                // Retain the verbatim representation, provided by the user.
136                string: self.0.to_string(),
137                version: python_full_version,
138            });
139        }
140
141        // Ex) `python_full_version == "3.12.0"`
142        let python_full_version = self.python_full_version();
143        markers = markers.with_python_full_version(StringVersion {
144            // Retain the verbatim representation, provided by the user.
145            string: self.0.to_string(),
146            version: python_full_version,
147        });
148
149        // Ex) `python_version == "3.12"`
150        let python_version = self.python_version();
151        markers = markers.with_python_version(StringVersion {
152            string: python_version.to_string(),
153            version: python_version,
154        });
155
156        markers
157    }
158
159    /// Return the `python_version` marker corresponding to this Python version.
160    ///
161    /// This should include exactly a major and minor version, but no patch version.
162    ///
163    /// Ex) `python_version == "3.12"`
164    pub fn python_version(&self) -> Version {
165        let major = self.release().first().copied().unwrap_or(0);
166        let minor = self.release().get(1).copied().unwrap_or(0);
167        Version::new([major, minor])
168    }
169
170    /// Return the `python_full_version` marker corresponding to this Python version.
171    ///
172    /// This should include exactly a major, minor, and patch version (even if it's zero), along
173    /// with any pre-release or post-release information.
174    ///
175    /// Ex) `python_full_version == "3.12.0b1"`
176    pub fn python_full_version(&self) -> Version {
177        let major = self.release().first().copied().unwrap_or(0);
178        let minor = self.release().get(1).copied().unwrap_or(0);
179        let patch = self.release().get(2).copied().unwrap_or(0);
180        Version::new([major, minor, patch])
181            .with_pre(self.0.pre())
182            .with_post(self.0.post())
183    }
184
185    /// Return the full parsed Python version.
186    pub fn version(&self) -> &Version {
187        &self.0.version
188    }
189
190    /// Return the full parsed Python version.
191    pub fn into_version(self) -> Version {
192        self.0.version
193    }
194
195    /// Return the major version of this Python version.
196    pub fn major(&self) -> u8 {
197        u8::try_from(self.0.release().first().copied().unwrap_or(0)).expect("invalid major version")
198    }
199
200    /// Return the minor version of this Python version.
201    pub fn minor(&self) -> u8 {
202        u8::try_from(self.0.release().get(1).copied().unwrap_or(0)).expect("invalid minor version")
203    }
204
205    /// Return the patch version of this Python version, if set.
206    pub fn patch(&self) -> Option<u8> {
207        self.0
208            .release()
209            .get(2)
210            .copied()
211            .map(|patch| u8::try_from(patch).expect("invalid patch version"))
212    }
213
214    /// Returns a copy of the Python version without the patch version
215    #[must_use]
216    pub fn without_patch(&self) -> Self {
217        Self::from_str(format!("{}.{}", self.major(), self.minor()).as_str())
218            .expect("dropping a patch should always be valid")
219    }
220}
221
222/// Get the environment variable name for the build constraint for a given implementation.
223pub(crate) fn python_build_version_variable(implementation: ImplementationName) -> &'static str {
224    match implementation {
225        ImplementationName::CPython => EnvVars::UV_PYTHON_CPYTHON_BUILD,
226        ImplementationName::PyPy => EnvVars::UV_PYTHON_PYPY_BUILD,
227        ImplementationName::GraalPy => EnvVars::UV_PYTHON_GRAALPY_BUILD,
228        ImplementationName::Pyodide => EnvVars::UV_PYTHON_PYODIDE_BUILD,
229    }
230}
231
232/// Get the build version number from the environment variable for a given implementation.
233pub(crate) fn python_build_version_from_env(
234    implementation: ImplementationName,
235) -> Result<Option<String>, BuildVersionError> {
236    let variable = python_build_version_variable(implementation);
237
238    let Some(build_os) = env::var_os(variable) else {
239        return Ok(None);
240    };
241
242    let build = build_os
243        .into_string()
244        .map_err(|raw| BuildVersionError::NotUnicode(variable, raw))?;
245
246    let trimmed = build.trim();
247    if trimmed.is_empty() {
248        return Ok(None);
249    }
250
251    Ok(Some(trimmed.to_string()))
252}
253
254/// Get the build version numbers for all Python implementations.
255pub(crate) fn python_build_versions_from_env()
256-> Result<BTreeMap<ImplementationName, String>, BuildVersionError> {
257    let mut versions = BTreeMap::new();
258    for implementation in ImplementationName::iter_all() {
259        let Some(build) = python_build_version_from_env(implementation)? else {
260            continue;
261        };
262        versions.insert(implementation, build);
263    }
264    Ok(versions)
265}
266
267#[cfg(test)]
268mod tests {
269    use std::str::FromStr;
270
271    use uv_pep440::{Prerelease, PrereleaseKind, Version};
272
273    use crate::PythonVersion;
274
275    #[test]
276    fn python_markers() {
277        let version = PythonVersion::from_str("3.11.0").expect("valid python version");
278        assert_eq!(version.python_version(), Version::new([3, 11]));
279        assert_eq!(version.python_version().to_string(), "3.11");
280        assert_eq!(version.python_full_version(), Version::new([3, 11, 0]));
281        assert_eq!(version.python_full_version().to_string(), "3.11.0");
282
283        let version = PythonVersion::from_str("3.11").expect("valid python version");
284        assert_eq!(version.python_version(), Version::new([3, 11]));
285        assert_eq!(version.python_version().to_string(), "3.11");
286        assert_eq!(version.python_full_version(), Version::new([3, 11, 0]));
287        assert_eq!(version.python_full_version().to_string(), "3.11.0");
288
289        let version = PythonVersion::from_str("3.11.8a1").expect("valid python version");
290        assert_eq!(version.python_version(), Version::new([3, 11]));
291        assert_eq!(version.python_version().to_string(), "3.11");
292        assert_eq!(
293            version.python_full_version(),
294            Version::new([3, 11, 8]).with_pre(Some(Prerelease {
295                kind: PrereleaseKind::Alpha,
296                number: 1
297            }))
298        );
299        assert_eq!(version.python_full_version().to_string(), "3.11.8a1");
300    }
301}
uv_python/python_version.rs

uv_python/
python_version.rs
