uv_distribution_types/
requirement.rs

1use std::fmt::{Display, Formatter};
2use std::io;
3use std::path::Path;
4use std::str::FromStr;
5
6use thiserror::Error;
7use uv_cache_key::{CacheKey, CacheKeyHasher};
8use uv_distribution_filename::DistExtension;
9use uv_fs::{CWD, PortablePath, PortablePathBuf, try_relative_to_if};
10use uv_git_types::{GitLfs, GitOid, GitReference, GitUrl, GitUrlParseError, OidParseError};
11use uv_normalize::{ExtraName, GroupName, PackageName};
12use uv_pep440::VersionSpecifiers;
13use uv_pep508::{
14    MarkerEnvironment, MarkerTree, RequirementOrigin, VerbatimUrl, VersionOrUrl, marker,
15};
16use uv_redacted::{DisplaySafeUrl, DisplaySafeUrlError};
17
18use crate::{IndexMetadata, IndexUrl};
19
20use uv_pypi_types::{
21    ConflictItem, Hashes, ParsedArchiveUrl, ParsedDirectoryUrl, ParsedGitUrl, ParsedPathUrl,
22    ParsedUrl, ParsedUrlError, VerbatimParsedUrl,
23};
24
25#[derive(Debug, Error)]
26pub enum RequirementError {
27    #[error(transparent)]
28    VerbatimUrlError(#[from] uv_pep508::VerbatimUrlError),
29    #[error(transparent)]
30    ParsedUrlError(#[from] ParsedUrlError),
31    #[error(transparent)]
32    UrlParseError(#[from] DisplaySafeUrlError),
33    #[error(transparent)]
34    OidParseError(#[from] OidParseError),
35    #[error(transparent)]
36    GitUrlParse(#[from] GitUrlParseError),
37}
38
39/// A representation of dependency on a package, an extension over a PEP 508's requirement.
40///
41/// The main change is using [`RequirementSource`] to represent all supported package sources over
42/// [`VersionOrUrl`], which collapses all URL sources into a single stringly type.
43///
44/// Additionally, this requirement type makes room for dependency groups, which lack a standardized
45/// representation in PEP 508. In the context of this type, extras and groups are assumed to be
46/// mutually exclusive, in that if `extras` is non-empty, `groups` must be empty and vice versa.
47#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
48pub struct Requirement {
49    pub name: PackageName,
50    #[serde(skip_serializing_if = "<[ExtraName]>::is_empty", default)]
51    pub extras: Box<[ExtraName]>,
52    #[serde(skip_serializing_if = "<[GroupName]>::is_empty", default)]
53    pub groups: Box<[GroupName]>,
54    #[serde(
55        skip_serializing_if = "marker::ser::is_empty",
56        serialize_with = "marker::ser::serialize",
57        default
58    )]
59    pub marker: MarkerTree,
60    #[serde(flatten)]
61    pub source: RequirementSource,
62    #[serde(skip)]
63    pub origin: Option<RequirementOrigin>,
64}
65
66impl Requirement {
67    /// Returns whether the markers apply for the given environment.
68    ///
69    /// When `env` is `None`, this specifically evaluates all marker
70    /// expressions based on the environment to `true`. That is, this provides
71    /// environment independent marker evaluation.
72    pub fn evaluate_markers(&self, env: Option<&MarkerEnvironment>, extras: &[ExtraName]) -> bool {
73        self.marker.evaluate_optional_environment(env, extras)
74    }
75
76    /// Returns `true` if the requirement is editable.
77    pub fn is_editable(&self) -> bool {
78        self.source.is_editable()
79    }
80
81    /// Convert to a [`Requirement`] with a relative path based on the given root.
82    pub fn relative_to(self, path: &Path) -> Result<Self, io::Error> {
83        Ok(Self {
84            source: self.source.relative_to(path)?,
85            ..self
86        })
87    }
88
89    /// Convert to a [`Requirement`] with an absolute path based on the given root.
90    #[must_use]
91    pub fn to_absolute(self, path: &Path) -> Self {
92        Self {
93            source: self.source.to_absolute(path),
94            ..self
95        }
96    }
97
98    /// Return the hashes of the requirement, as specified in the URL fragment.
99    pub fn hashes(&self) -> Option<Hashes> {
100        let RequirementSource::Url { ref url, .. } = self.source else {
101            return None;
102        };
103        let fragment = url.fragment()?;
104        Hashes::parse_fragment(fragment).ok()
105    }
106
107    /// Set the source file containing the requirement.
108    #[must_use]
109    pub fn with_origin(self, origin: RequirementOrigin) -> Self {
110        Self {
111            origin: Some(origin),
112            ..self
113        }
114    }
115}
116
117impl std::hash::Hash for Requirement {
118    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
119        let Self {
120            name,
121            extras,
122            groups,
123            marker,
124            source,
125            origin: _,
126        } = self;
127        name.hash(state);
128        extras.hash(state);
129        groups.hash(state);
130        marker.hash(state);
131        source.hash(state);
132    }
133}
134
135impl PartialEq for Requirement {
136    fn eq(&self, other: &Self) -> bool {
137        let Self {
138            name,
139            extras,
140            groups,
141            marker,
142            source,
143            origin: _,
144        } = self;
145        let Self {
146            name: other_name,
147            extras: other_extras,
148            groups: other_groups,
149            marker: other_marker,
150            source: other_source,
151            origin: _,
152        } = other;
153        name == other_name
154            && extras == other_extras
155            && groups == other_groups
156            && marker == other_marker
157            && source == other_source
158    }
159}
160
161impl Eq for Requirement {}
162
163impl Ord for Requirement {
164    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
165        let Self {
166            name,
167            extras,
168            groups,
169            marker,
170            source,
171            origin: _,
172        } = self;
173        let Self {
174            name: other_name,
175            extras: other_extras,
176            groups: other_groups,
177            marker: other_marker,
178            source: other_source,
179            origin: _,
180        } = other;
181        name.cmp(other_name)
182            .then_with(|| extras.cmp(other_extras))
183            .then_with(|| groups.cmp(other_groups))
184            .then_with(|| marker.cmp(other_marker))
185            .then_with(|| source.cmp(other_source))
186    }
187}
188
189impl PartialOrd for Requirement {
190    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
191        Some(self.cmp(other))
192    }
193}
194
195impl From<Requirement> for uv_pep508::Requirement<VerbatimUrl> {
196    /// Convert a [`Requirement`] to a [`uv_pep508::Requirement`].
197    fn from(requirement: Requirement) -> Self {
198        Self {
199            name: requirement.name,
200            extras: requirement.extras,
201            marker: requirement.marker,
202            origin: requirement.origin,
203            version_or_url: match requirement.source {
204                RequirementSource::Registry { specifier, .. } => {
205                    Some(VersionOrUrl::VersionSpecifier(specifier))
206                }
207                RequirementSource::Url { url, .. }
208                | RequirementSource::Git { url, .. }
209                | RequirementSource::Path { url, .. }
210                | RequirementSource::Directory { url, .. } => Some(VersionOrUrl::Url(url)),
211            },
212        }
213    }
214}
215
216impl From<Requirement> for uv_pep508::Requirement<VerbatimParsedUrl> {
217    /// Convert a [`Requirement`] to a [`uv_pep508::Requirement`].
218    fn from(requirement: Requirement) -> Self {
219        Self {
220            name: requirement.name,
221            extras: requirement.extras,
222            marker: requirement.marker,
223            origin: requirement.origin,
224            version_or_url: match requirement.source {
225                RequirementSource::Registry { specifier, .. } => {
226                    Some(VersionOrUrl::VersionSpecifier(specifier))
227                }
228                RequirementSource::Url {
229                    location,
230                    subdirectory,
231                    ext,
232                    url,
233                } => Some(VersionOrUrl::Url(VerbatimParsedUrl {
234                    parsed_url: ParsedUrl::Archive(ParsedArchiveUrl {
235                        url: location,
236                        subdirectory,
237                        ext,
238                    }),
239                    verbatim: url,
240                })),
241                RequirementSource::Git {
242                    git,
243                    subdirectory,
244                    url,
245                } => Some(VersionOrUrl::Url(VerbatimParsedUrl {
246                    parsed_url: ParsedUrl::Git(ParsedGitUrl {
247                        url: git,
248                        subdirectory,
249                    }),
250                    verbatim: url,
251                })),
252                RequirementSource::Path {
253                    install_path,
254                    ext,
255                    url,
256                } => Some(VersionOrUrl::Url(VerbatimParsedUrl {
257                    parsed_url: ParsedUrl::Path(ParsedPathUrl {
258                        url: url.to_url(),
259                        install_path,
260                        ext,
261                    }),
262                    verbatim: url,
263                })),
264                RequirementSource::Directory {
265                    install_path,
266                    editable,
267                    r#virtual,
268                    url,
269                } => Some(VersionOrUrl::Url(VerbatimParsedUrl {
270                    parsed_url: ParsedUrl::Directory(ParsedDirectoryUrl {
271                        url: url.to_url(),
272                        install_path,
273                        editable,
274                        r#virtual,
275                    }),
276                    verbatim: url,
277                })),
278            },
279        }
280    }
281}
282
283impl From<uv_pep508::Requirement<VerbatimParsedUrl>> for Requirement {
284    /// Convert a [`uv_pep508::Requirement`] to a [`Requirement`].
285    fn from(requirement: uv_pep508::Requirement<VerbatimParsedUrl>) -> Self {
286        let source = match requirement.version_or_url {
287            None => RequirementSource::Registry {
288                specifier: VersionSpecifiers::empty(),
289                index: None,
290                conflict: None,
291            },
292            // The most popular case: just a name, a version range and maybe extras.
293            Some(VersionOrUrl::VersionSpecifier(specifier)) => RequirementSource::Registry {
294                specifier,
295                index: None,
296                conflict: None,
297            },
298            Some(VersionOrUrl::Url(url)) => {
299                RequirementSource::from_parsed_url(url.parsed_url, url.verbatim)
300            }
301        };
302        Self {
303            name: requirement.name,
304            groups: Box::new([]),
305            extras: requirement.extras,
306            marker: requirement.marker,
307            source,
308            origin: requirement.origin,
309        }
310    }
311}
312
313impl Display for Requirement {
314    /// Display the [`Requirement`], with the intention of being shown directly to a user, rather
315    /// than for inclusion in a `requirements.txt` file.
316    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
317        write!(f, "{}", self.name)?;
318        if !self.extras.is_empty() {
319            write!(
320                f,
321                "[{}]",
322                self.extras
323                    .iter()
324                    .map(ToString::to_string)
325                    .collect::<Vec<_>>()
326                    .join(",")
327            )?;
328        }
329        match &self.source {
330            RequirementSource::Registry {
331                specifier, index, ..
332            } => {
333                write!(f, "{specifier}")?;
334                if let Some(index) = index {
335                    write!(f, " (index: {})", index.url)?;
336                }
337            }
338            RequirementSource::Url { url, .. } => {
339                write!(f, " @ {url}")?;
340            }
341            RequirementSource::Git {
342                url: _,
343                git,
344                subdirectory,
345            } => {
346                write!(f, " @ git+{}", git.repository())?;
347                if let Some(reference) = git.reference().as_str() {
348                    write!(f, "@{reference}")?;
349                }
350                if let Some(subdirectory) = subdirectory {
351                    writeln!(f, "#subdirectory={}", subdirectory.display())?;
352                }
353                if git.lfs().enabled() {
354                    writeln!(
355                        f,
356                        "{}lfs=true",
357                        if subdirectory.is_some() { "&" } else { "#" }
358                    )?;
359                }
360            }
361            RequirementSource::Path { url, .. } => {
362                write!(f, " @ {url}")?;
363            }
364            RequirementSource::Directory { url, .. } => {
365                write!(f, " @ {url}")?;
366            }
367        }
368        if let Some(marker) = self.marker.contents() {
369            write!(f, " ; {marker}")?;
370        }
371        Ok(())
372    }
373}
374
375impl CacheKey for Requirement {
376    fn cache_key(&self, state: &mut CacheKeyHasher) {
377        self.name.as_str().cache_key(state);
378
379        self.groups.len().cache_key(state);
380        for group in &self.groups {
381            group.as_str().cache_key(state);
382        }
383
384        self.extras.len().cache_key(state);
385        for extra in &self.extras {
386            extra.as_str().cache_key(state);
387        }
388
389        if let Some(marker) = self.marker.contents() {
390            1u8.cache_key(state);
391            marker.to_string().cache_key(state);
392        } else {
393            0u8.cache_key(state);
394        }
395
396        match &self.source {
397            RequirementSource::Registry {
398                specifier,
399                index,
400                conflict: _,
401            } => {
402                0u8.cache_key(state);
403                specifier.len().cache_key(state);
404                for spec in specifier.iter() {
405                    spec.operator().as_str().cache_key(state);
406                    spec.version().cache_key(state);
407                }
408                if let Some(index) = index {
409                    1u8.cache_key(state);
410                    index.url.cache_key(state);
411                } else {
412                    0u8.cache_key(state);
413                }
414                // `conflict` is intentionally omitted
415            }
416            RequirementSource::Url {
417                location,
418                subdirectory,
419                ext,
420                url,
421            } => {
422                1u8.cache_key(state);
423                location.cache_key(state);
424                if let Some(subdirectory) = subdirectory {
425                    1u8.cache_key(state);
426                    subdirectory.display().to_string().cache_key(state);
427                } else {
428                    0u8.cache_key(state);
429                }
430                ext.name().cache_key(state);
431                url.cache_key(state);
432            }
433            RequirementSource::Git {
434                git,
435                subdirectory,
436                url,
437            } => {
438                2u8.cache_key(state);
439                git.to_string().cache_key(state);
440                if let Some(subdirectory) = subdirectory {
441                    1u8.cache_key(state);
442                    subdirectory.display().to_string().cache_key(state);
443                } else {
444                    0u8.cache_key(state);
445                }
446                if git.lfs().enabled() {
447                    1u8.cache_key(state);
448                }
449                url.cache_key(state);
450            }
451            RequirementSource::Path {
452                install_path,
453                ext,
454                url,
455            } => {
456                3u8.cache_key(state);
457                install_path.cache_key(state);
458                ext.name().cache_key(state);
459                url.cache_key(state);
460            }
461            RequirementSource::Directory {
462                install_path,
463                editable,
464                r#virtual,
465                url,
466            } => {
467                4u8.cache_key(state);
468                install_path.cache_key(state);
469                editable.cache_key(state);
470                r#virtual.cache_key(state);
471                url.cache_key(state);
472            }
473        }
474
475        // `origin` is intentionally omitted
476    }
477}
478
479/// The different locations with can install a distribution from: Version specifier (from an index),
480/// HTTP(S) URL, git repository, and path.
481///
482/// We store both the parsed fields (such as the plain url and the subdirectory) and the joined
483/// PEP 508 style url (e.g. `file:///<path>#subdirectory=<subdirectory>`) since we need both in
484/// different locations.
485#[derive(
486    Hash, Debug, Clone, Eq, PartialEq, Ord, PartialOrd, serde::Serialize, serde::Deserialize,
487)]
488#[serde(try_from = "RequirementSourceWire", into = "RequirementSourceWire")]
489pub enum RequirementSource {
490    /// The requirement has a version specifier, such as `foo >1,<2`.
491    Registry {
492        specifier: VersionSpecifiers,
493        /// Choose a version from the index at the given URL.
494        index: Option<IndexMetadata>,
495        /// The conflict item associated with the source, if any.
496        conflict: Option<ConflictItem>,
497    },
498    // TODO(konsti): Track and verify version specifier from `project.dependencies` matches the
499    // version in remote location.
500    /// A remote `http://` or `https://` URL, either a built distribution,
501    /// e.g. `foo @ https://example.org/foo-1.0-py3-none-any.whl`, or a source distribution,
502    /// e.g.`foo @ https://example.org/foo-1.0.zip`.
503    Url {
504        /// The remote location of the archive file, without subdirectory fragment.
505        location: DisplaySafeUrl,
506        /// For source distributions, the path to the distribution if it is not in the archive
507        /// root.
508        subdirectory: Option<Box<Path>>,
509        /// The file extension, e.g. `tar.gz`, `zip`, etc.
510        ext: DistExtension,
511        /// The PEP 508 style URL in the format
512        /// `<scheme>://<domain>/<path>#subdirectory=<subdirectory>`.
513        url: VerbatimUrl,
514    },
515    /// A remote Git repository, over either HTTPS or SSH.
516    Git {
517        /// The repository URL and reference to the commit to use.
518        git: GitUrl,
519        /// The path to the source distribution if it is not in the repository root.
520        subdirectory: Option<Box<Path>>,
521        /// The PEP 508 style url in the format
522        /// `git+<scheme>://<domain>/<path>@<rev>#subdirectory=<subdirectory>`.
523        url: VerbatimUrl,
524    },
525    /// A local built or source distribution, either from a path or a `file://` URL. It can either
526    /// be a binary distribution (a `.whl` file) or a source distribution archive (a `.zip` or
527    /// `.tar.gz` file).
528    Path {
529        /// The absolute path to the distribution which we use for installing.
530        install_path: Box<Path>,
531        /// The file extension, e.g. `tar.gz`, `zip`, etc.
532        ext: DistExtension,
533        /// The PEP 508 style URL in the format
534        /// `file:///<path>#subdirectory=<subdirectory>`.
535        url: VerbatimUrl,
536    },
537    /// A local source tree (a directory with a pyproject.toml in, or a legacy
538    /// source distribution with only a setup.py but non pyproject.toml in it).
539    Directory {
540        /// The absolute path to the distribution which we use for installing.
541        install_path: Box<Path>,
542        /// For a source tree (a directory), whether to install as an editable.
543        editable: Option<bool>,
544        /// For a source tree (a directory), whether the project should be built and installed.
545        r#virtual: Option<bool>,
546        /// The PEP 508 style URL in the format
547        /// `file:///<path>#subdirectory=<subdirectory>`.
548        url: VerbatimUrl,
549    },
550}
551
552impl RequirementSource {
553    /// Construct a [`RequirementSource`] for a URL source, given a URL parsed into components and
554    /// the PEP 508 string (after the `@`) as [`VerbatimUrl`].
555    pub fn from_parsed_url(parsed_url: ParsedUrl, url: VerbatimUrl) -> Self {
556        match parsed_url {
557            ParsedUrl::Path(local_file) => Self::Path {
558                install_path: local_file.install_path.clone(),
559                ext: local_file.ext,
560                url,
561            },
562            ParsedUrl::Directory(directory) => Self::Directory {
563                install_path: directory.install_path.clone(),
564                editable: directory.editable,
565                r#virtual: directory.r#virtual,
566                url,
567            },
568            ParsedUrl::Git(git) => Self::Git {
569                git: git.url.clone(),
570                url,
571                subdirectory: git.subdirectory,
572            },
573            ParsedUrl::Archive(archive) => Self::Url {
574                url,
575                location: archive.url,
576                subdirectory: archive.subdirectory,
577                ext: archive.ext,
578            },
579        }
580    }
581
582    /// Convert the source to a [`VerbatimParsedUrl`], if it's a URL source.
583    pub fn to_verbatim_parsed_url(&self) -> Option<VerbatimParsedUrl> {
584        match self {
585            Self::Registry { .. } => None,
586            Self::Url {
587                location,
588                subdirectory,
589                ext,
590                url,
591            } => Some(VerbatimParsedUrl {
592                parsed_url: ParsedUrl::Archive(ParsedArchiveUrl::from_source(
593                    location.clone(),
594                    subdirectory.clone(),
595                    *ext,
596                )),
597                verbatim: url.clone(),
598            }),
599            Self::Path {
600                install_path,
601                ext,
602                url,
603            } => Some(VerbatimParsedUrl {
604                parsed_url: ParsedUrl::Path(ParsedPathUrl::from_source(
605                    install_path.clone(),
606                    *ext,
607                    url.to_url(),
608                )),
609                verbatim: url.clone(),
610            }),
611            Self::Directory {
612                install_path,
613                editable,
614                r#virtual,
615                url,
616            } => Some(VerbatimParsedUrl {
617                parsed_url: ParsedUrl::Directory(ParsedDirectoryUrl::from_source(
618                    install_path.clone(),
619                    *editable,
620                    *r#virtual,
621                    url.to_url(),
622                )),
623                verbatim: url.clone(),
624            }),
625            Self::Git {
626                git,
627                subdirectory,
628                url,
629            } => Some(VerbatimParsedUrl {
630                parsed_url: ParsedUrl::Git(ParsedGitUrl::from_source(
631                    git.clone(),
632                    subdirectory.clone(),
633                )),
634                verbatim: url.clone(),
635            }),
636        }
637    }
638
639    /// Convert the source to a version specifier or URL.
640    ///
641    /// If the source is a registry and the specifier is empty, it returns `None`.
642    pub fn version_or_url(&self) -> Option<VersionOrUrl<VerbatimParsedUrl>> {
643        match self {
644            Self::Registry { specifier, .. } => {
645                if specifier.is_empty() {
646                    None
647                } else {
648                    Some(VersionOrUrl::VersionSpecifier(specifier.clone()))
649                }
650            }
651            Self::Url { .. } | Self::Git { .. } | Self::Path { .. } | Self::Directory { .. } => {
652                Some(VersionOrUrl::Url(self.to_verbatim_parsed_url()?))
653            }
654        }
655    }
656
657    /// Returns `true` if the source is editable.
658    pub fn is_editable(&self) -> bool {
659        matches!(
660            self,
661            Self::Directory {
662                editable: Some(true),
663                ..
664            }
665        )
666    }
667
668    /// Returns `true` if the source is empty.
669    pub fn is_empty(&self) -> bool {
670        match self {
671            Self::Registry { specifier, .. } => specifier.is_empty(),
672            Self::Url { .. } | Self::Git { .. } | Self::Path { .. } | Self::Directory { .. } => {
673                false
674            }
675        }
676    }
677
678    /// If the source is the registry, return the version specifiers
679    pub fn version_specifiers(&self) -> Option<&VersionSpecifiers> {
680        match self {
681            Self::Registry { specifier, .. } => Some(specifier),
682            Self::Url { .. } | Self::Git { .. } | Self::Path { .. } | Self::Directory { .. } => {
683                None
684            }
685        }
686    }
687
688    /// Convert the source to a [`RequirementSource`] relative to the given path.
689    pub fn relative_to(self, path: &Path) -> Result<Self, io::Error> {
690        match self {
691            Self::Registry { .. } | Self::Url { .. } | Self::Git { .. } => Ok(self),
692            Self::Path {
693                install_path,
694                ext,
695                url,
696            } => Ok(Self::Path {
697                install_path: try_relative_to_if(&install_path, path, !url.was_given_absolute())?
698                    .into_boxed_path(),
699                ext,
700                url,
701            }),
702            Self::Directory {
703                install_path,
704                editable,
705                r#virtual,
706                url,
707                ..
708            } => Ok(Self::Directory {
709                install_path: try_relative_to_if(&install_path, path, !url.was_given_absolute())?
710                    .into_boxed_path(),
711                editable,
712                r#virtual,
713                url,
714            }),
715        }
716    }
717
718    /// Convert the source to a [`RequirementSource`] with an absolute path based on the given root.
719    #[must_use]
720    pub fn to_absolute(self, root: &Path) -> Self {
721        match self {
722            Self::Registry { .. } | Self::Url { .. } | Self::Git { .. } => self,
723            Self::Path {
724                install_path,
725                ext,
726                url,
727            } => Self::Path {
728                install_path: uv_fs::normalize_path_buf(root.join(install_path)).into_boxed_path(),
729                ext,
730                url,
731            },
732            Self::Directory {
733                install_path,
734                editable,
735                r#virtual,
736                url,
737                ..
738            } => Self::Directory {
739                install_path: uv_fs::normalize_path_buf(root.join(install_path)).into_boxed_path(),
740                editable,
741                r#virtual,
742                url,
743            },
744        }
745    }
746}
747
748impl Display for RequirementSource {
749    /// Display the [`RequirementSource`], with the intention of being shown directly to a user,
750    /// rather than for inclusion in a `requirements.txt` file.
751    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
752        match self {
753            Self::Registry {
754                specifier, index, ..
755            } => {
756                write!(f, "{specifier}")?;
757                if let Some(index) = index {
758                    write!(f, " (index: {})", index.url)?;
759                }
760            }
761            Self::Url { url, .. } => {
762                write!(f, " {url}")?;
763            }
764            Self::Git {
765                url: _,
766                git,
767                subdirectory,
768            } => {
769                write!(f, " git+{}", git.repository())?;
770                if let Some(reference) = git.reference().as_str() {
771                    write!(f, "@{reference}")?;
772                }
773                if let Some(subdirectory) = subdirectory {
774                    writeln!(f, "#subdirectory={}", subdirectory.display())?;
775                }
776                if git.lfs().enabled() {
777                    writeln!(
778                        f,
779                        "{}lfs=true",
780                        if subdirectory.is_some() { "&" } else { "#" }
781                    )?;
782                }
783            }
784            Self::Path { url, .. } => {
785                write!(f, "{url}")?;
786            }
787            Self::Directory { url, .. } => {
788                write!(f, "{url}")?;
789            }
790        }
791        Ok(())
792    }
793}
794
795#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
796#[serde(untagged)]
797enum RequirementSourceWire {
798    /// Ex) `source = { git = "<https://github.com/astral-test/uv-public-pypackage?rev=0.0.1#0dacfd662c64cb4ceb16e6cf65a157a8b715b979>" }`
799    Git { git: String },
800    /// Ex) `source = { url = "<https://example.org/foo-1.0.zip>" }`
801    Direct {
802        url: DisplaySafeUrl,
803        subdirectory: Option<PortablePathBuf>,
804    },
805    /// Ex) `source = { path = "/home/ferris/iniconfig-2.0.0-py3-none-any.whl" }`
806    Path { path: PortablePathBuf },
807    /// Ex) `source = { directory = "/home/ferris/iniconfig" }`
808    Directory { directory: PortablePathBuf },
809    /// Ex) `source = { editable = "/home/ferris/iniconfig" }`
810    Editable { editable: PortablePathBuf },
811    /// Ex) `source = { editable = "/home/ferris/iniconfig" }`
812    Virtual { r#virtual: PortablePathBuf },
813    /// Ex) `source = { specifier = "foo >1,<2" }`
814    Registry {
815        #[serde(skip_serializing_if = "VersionSpecifiers::is_empty", default)]
816        specifier: VersionSpecifiers,
817        index: Option<DisplaySafeUrl>,
818        conflict: Option<ConflictItem>,
819    },
820}
821
822impl From<RequirementSource> for RequirementSourceWire {
823    fn from(value: RequirementSource) -> Self {
824        match value {
825            RequirementSource::Registry {
826                specifier,
827                index,
828                conflict,
829            } => {
830                let index = index.map(|index| index.url.into_url()).map(|mut index| {
831                    index.remove_credentials();
832                    index
833                });
834                Self::Registry {
835                    specifier,
836                    index,
837                    conflict,
838                }
839            }
840            RequirementSource::Url {
841                subdirectory,
842                location,
843                ext: _,
844                url: _,
845            } => Self::Direct {
846                url: location,
847                subdirectory: subdirectory.map(PortablePathBuf::from),
848            },
849            RequirementSource::Git {
850                git,
851                subdirectory,
852                url: _,
853            } => {
854                let mut url = git.repository().clone();
855
856                // Remove the credentials.
857                url.remove_credentials();
858
859                // Clear out any existing state.
860                url.set_fragment(None);
861                url.set_query(None);
862
863                // Put the subdirectory in the query.
864                if let Some(subdirectory) = subdirectory
865                    .as_deref()
866                    .map(PortablePath::from)
867                    .as_ref()
868                    .map(PortablePath::to_string)
869                {
870                    url.query_pairs_mut()
871                        .append_pair("subdirectory", &subdirectory);
872                }
873
874                // Persist lfs=true in the distribution metadata only when explicitly enabled.
875                if git.lfs().enabled() {
876                    url.query_pairs_mut().append_pair("lfs", "true");
877                }
878
879                // Put the requested reference in the query.
880                match git.reference() {
881                    GitReference::Branch(branch) => {
882                        url.query_pairs_mut().append_pair("branch", branch.as_str());
883                    }
884                    GitReference::Tag(tag) => {
885                        url.query_pairs_mut().append_pair("tag", tag.as_str());
886                    }
887                    GitReference::BranchOrTag(rev)
888                    | GitReference::BranchOrTagOrCommit(rev)
889                    | GitReference::NamedRef(rev) => {
890                        url.query_pairs_mut().append_pair("rev", rev.as_str());
891                    }
892                    GitReference::DefaultBranch => {}
893                }
894
895                // Put the precise commit in the fragment.
896                if let Some(precise) = git.precise() {
897                    url.set_fragment(Some(&precise.to_string()));
898                }
899
900                Self::Git {
901                    git: url.to_string(),
902                }
903            }
904            RequirementSource::Path {
905                install_path,
906                ext: _,
907                url: _,
908            } => Self::Path {
909                path: PortablePathBuf::from(install_path),
910            },
911            RequirementSource::Directory {
912                install_path,
913                editable,
914                r#virtual,
915                url: _,
916            } => {
917                if editable.unwrap_or(false) {
918                    Self::Editable {
919                        editable: PortablePathBuf::from(install_path),
920                    }
921                } else if r#virtual.unwrap_or(false) {
922                    Self::Virtual {
923                        r#virtual: PortablePathBuf::from(install_path),
924                    }
925                } else {
926                    Self::Directory {
927                        directory: PortablePathBuf::from(install_path),
928                    }
929                }
930            }
931        }
932    }
933}
934
935impl TryFrom<RequirementSourceWire> for RequirementSource {
936    type Error = RequirementError;
937
938    fn try_from(wire: RequirementSourceWire) -> Result<Self, RequirementError> {
939        match wire {
940            RequirementSourceWire::Registry {
941                specifier,
942                index,
943                conflict,
944            } => Ok(Self::Registry {
945                specifier,
946                index: index
947                    .map(|index| IndexMetadata::from(IndexUrl::from(VerbatimUrl::from_url(index)))),
948                conflict,
949            }),
950            RequirementSourceWire::Git { git } => {
951                let mut repository = DisplaySafeUrl::parse(&git)?;
952
953                let mut reference = GitReference::DefaultBranch;
954                let mut subdirectory: Option<PortablePathBuf> = None;
955                let mut lfs = GitLfs::Disabled;
956                for (key, val) in repository.query_pairs() {
957                    match &*key {
958                        "tag" => reference = GitReference::Tag(val.into_owned()),
959                        "branch" => reference = GitReference::Branch(val.into_owned()),
960                        "rev" => reference = GitReference::from_rev(val.into_owned()),
961                        "subdirectory" => {
962                            subdirectory = Some(PortablePathBuf::from(val.as_ref()));
963                        }
964                        "lfs" => lfs = GitLfs::from(val.eq_ignore_ascii_case("true")),
965                        _ => {}
966                    }
967                }
968
969                let precise = repository.fragment().map(GitOid::from_str).transpose()?;
970
971                // Clear out any existing state.
972                repository.set_fragment(None);
973                repository.set_query(None);
974
975                // Remove the credentials.
976                repository.remove_credentials();
977
978                // Create a PEP 508-compatible URL.
979                let mut url = DisplaySafeUrl::parse(&format!("git+{repository}"))?;
980                if let Some(rev) = reference.as_str() {
981                    let path = format!("{}@{}", url.path(), rev);
982                    url.set_path(&path);
983                }
984                let mut frags: Vec<String> = Vec::new();
985                if let Some(subdirectory) = subdirectory.as_ref() {
986                    frags.push(format!("subdirectory={subdirectory}"));
987                }
988                // Preserve that we're using Git LFS in the Verbatim Url representations
989                if lfs.enabled() {
990                    frags.push("lfs=true".to_string());
991                }
992                if !frags.is_empty() {
993                    url.set_fragment(Some(&frags.join("&")));
994                }
995
996                let url = VerbatimUrl::from_url(url);
997
998                Ok(Self::Git {
999                    git: GitUrl::from_fields(repository, reference, precise, lfs)?,
1000                    subdirectory: subdirectory.map(Box::<Path>::from),
1001                    url,
1002                })
1003            }
1004            RequirementSourceWire::Direct { url, subdirectory } => {
1005                let location = url.clone();
1006
1007                // Create a PEP 508-compatible URL.
1008                let mut url = url.clone();
1009                if let Some(subdirectory) = &subdirectory {
1010                    url.set_fragment(Some(&format!("subdirectory={subdirectory}")));
1011                }
1012
1013                Ok(Self::Url {
1014                    location,
1015                    subdirectory: subdirectory.map(Box::<Path>::from),
1016                    ext: DistExtension::from_path(url.path())
1017                        .map_err(|err| ParsedUrlError::MissingExtensionUrl(url.to_string(), err))?,
1018                    url: VerbatimUrl::from_url(url.clone()),
1019                })
1020            }
1021            // TODO(charlie): The use of `CWD` here is incorrect. These should be resolved relative
1022            // to the workspace root, but we don't have access to it here. When comparing these
1023            // sources in the lockfile, we replace the URL anyway. Ideally, we'd either remove the
1024            // URL field or make it optional.
1025            RequirementSourceWire::Path { path } => {
1026                let path = Box::<Path>::from(path);
1027                let url =
1028                    VerbatimUrl::from_normalized_path(uv_fs::normalize_path_buf(CWD.join(&path)))?;
1029                Ok(Self::Path {
1030                    ext: DistExtension::from_path(&path).map_err(|err| {
1031                        ParsedUrlError::MissingExtensionPath(path.to_path_buf(), err)
1032                    })?,
1033                    install_path: path,
1034                    url,
1035                })
1036            }
1037            RequirementSourceWire::Directory { directory } => {
1038                let directory = Box::<Path>::from(directory);
1039                let url = VerbatimUrl::from_normalized_path(uv_fs::normalize_path_buf(
1040                    CWD.join(&directory),
1041                ))?;
1042                Ok(Self::Directory {
1043                    install_path: directory,
1044                    editable: Some(false),
1045                    r#virtual: Some(false),
1046                    url,
1047                })
1048            }
1049            RequirementSourceWire::Editable { editable } => {
1050                let editable = Box::<Path>::from(editable);
1051                let url = VerbatimUrl::from_normalized_path(uv_fs::normalize_path_buf(
1052                    CWD.join(&editable),
1053                ))?;
1054                Ok(Self::Directory {
1055                    install_path: editable,
1056                    editable: Some(true),
1057                    r#virtual: Some(false),
1058                    url,
1059                })
1060            }
1061            RequirementSourceWire::Virtual { r#virtual } => {
1062                let r#virtual = Box::<Path>::from(r#virtual);
1063                let url = VerbatimUrl::from_normalized_path(uv_fs::normalize_path_buf(
1064                    CWD.join(&r#virtual),
1065                ))?;
1066                Ok(Self::Directory {
1067                    install_path: r#virtual,
1068                    editable: Some(false),
1069                    r#virtual: Some(true),
1070                    url,
1071                })
1072            }
1073        }
1074    }
1075}
1076
1077#[cfg(test)]
1078mod tests {
1079    use std::path::PathBuf;
1080
1081    use uv_pep508::{MarkerTree, VerbatimUrl};
1082
1083    use crate::{Requirement, RequirementSource};
1084
1085    #[test]
1086    fn roundtrip() {
1087        let requirement = Requirement {
1088            name: "foo".parse().unwrap(),
1089            extras: Box::new([]),
1090            groups: Box::new([]),
1091            marker: MarkerTree::TRUE,
1092            source: RequirementSource::Registry {
1093                specifier: ">1,<2".parse().unwrap(),
1094                index: None,
1095                conflict: None,
1096            },
1097            origin: None,
1098        };
1099
1100        let raw = toml::to_string(&requirement).unwrap();
1101        let deserialized: Requirement = toml::from_str(&raw).unwrap();
1102        assert_eq!(requirement, deserialized);
1103
1104        let path = if cfg!(windows) {
1105            "C:\\home\\ferris\\foo"
1106        } else {
1107            "/home/ferris/foo"
1108        };
1109        let requirement = Requirement {
1110            name: "foo".parse().unwrap(),
1111            extras: Box::new([]),
1112            groups: Box::new([]),
1113            marker: MarkerTree::TRUE,
1114            source: RequirementSource::Directory {
1115                install_path: PathBuf::from(path).into_boxed_path(),
1116                editable: Some(false),
1117                r#virtual: Some(false),
1118                url: VerbatimUrl::from_absolute_path(path).unwrap(),
1119            },
1120            origin: None,
1121        };
1122
1123        let raw = toml::to_string(&requirement).unwrap();
1124        let deserialized: Requirement = toml::from_str(&raw).unwrap();
1125        assert_eq!(requirement, deserialized);
1126    }
1127}
uv_distribution_types/requirement.rs

uv_distribution_types/
requirement.rs
