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, normalize_path, 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.url())?;
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: normalize_path(root.join(install_path))
729                    .into_owned()
730                    .into_boxed_path(),
731                ext,
732                url,
733            },
734            Self::Directory {
735                install_path,
736                editable,
737                r#virtual,
738                url,
739                ..
740            } => Self::Directory {
741                install_path: normalize_path(root.join(install_path))
742                    .into_owned()
743                    .into_boxed_path(),
744                editable,
745                r#virtual,
746                url,
747            },
748        }
749    }
750}
751
752impl Display for RequirementSource {
753    /// Display the [`RequirementSource`], with the intention of being shown directly to a user,
754    /// rather than for inclusion in a `requirements.txt` file.
755    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
756        match self {
757            Self::Registry {
758                specifier, index, ..
759            } => {
760                write!(f, "{specifier}")?;
761                if let Some(index) = index {
762                    write!(f, " (index: {})", index.url)?;
763                }
764            }
765            Self::Url { url, .. } => {
766                write!(f, " {url}")?;
767            }
768            Self::Git {
769                url: _,
770                git,
771                subdirectory,
772            } => {
773                write!(f, " git+{}", git.url())?;
774                if let Some(reference) = git.reference().as_str() {
775                    write!(f, "@{reference}")?;
776                }
777                if let Some(subdirectory) = subdirectory {
778                    writeln!(f, "#subdirectory={}", subdirectory.display())?;
779                }
780                if git.lfs().enabled() {
781                    writeln!(
782                        f,
783                        "{}lfs=true",
784                        if subdirectory.is_some() { "&" } else { "#" }
785                    )?;
786                }
787            }
788            Self::Path { url, .. } => {
789                write!(f, "{url}")?;
790            }
791            Self::Directory { url, .. } => {
792                write!(f, "{url}")?;
793            }
794        }
795        Ok(())
796    }
797}
798
799#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
800#[serde(untagged)]
801enum RequirementSourceWire {
802    /// Ex) `source = { git = "<https://github.com/astral-test/uv-public-pypackage?rev=0.0.1#0dacfd662c64cb4ceb16e6cf65a157a8b715b979>" }`
803    Git { git: String },
804    /// Ex) `source = { url = "<https://example.org/foo-1.0.zip>" }`
805    Direct {
806        url: DisplaySafeUrl,
807        subdirectory: Option<PortablePathBuf>,
808    },
809    /// Ex) `source = { path = "/home/ferris/iniconfig-2.0.0-py3-none-any.whl" }`
810    Path { path: PortablePathBuf },
811    /// Ex) `source = { directory = "/home/ferris/iniconfig" }`
812    Directory { directory: PortablePathBuf },
813    /// Ex) `source = { editable = "/home/ferris/iniconfig" }`
814    Editable { editable: PortablePathBuf },
815    /// Ex) `source = { editable = "/home/ferris/iniconfig" }`
816    Virtual { r#virtual: PortablePathBuf },
817    /// Ex) `source = { specifier = "foo >1,<2" }`
818    Registry {
819        #[serde(skip_serializing_if = "VersionSpecifiers::is_empty", default)]
820        specifier: VersionSpecifiers,
821        index: Option<DisplaySafeUrl>,
822        conflict: Option<ConflictItem>,
823    },
824}
825
826impl From<RequirementSource> for RequirementSourceWire {
827    fn from(value: RequirementSource) -> Self {
828        match value {
829            RequirementSource::Registry {
830                specifier,
831                index,
832                conflict,
833            } => {
834                let index = index.map(|index| index.url.into_url()).map(|mut index| {
835                    index.remove_credentials();
836                    index
837                });
838                Self::Registry {
839                    specifier,
840                    index,
841                    conflict,
842                }
843            }
844            RequirementSource::Url {
845                subdirectory,
846                location,
847                ext: _,
848                url: _,
849            } => Self::Direct {
850                url: location,
851                subdirectory: subdirectory.map(PortablePathBuf::from),
852            },
853            RequirementSource::Git {
854                git,
855                subdirectory,
856                url: _,
857            } => {
858                let mut url = git.url().clone();
859
860                // Remove the credentials.
861                url.remove_credentials();
862
863                // Clear out any existing state.
864                url.set_fragment(None);
865                url.set_query(None);
866
867                // Put the subdirectory in the query.
868                if let Some(subdirectory) = subdirectory
869                    .as_deref()
870                    .map(PortablePath::from)
871                    .as_ref()
872                    .map(PortablePath::to_string)
873                {
874                    url.query_pairs_mut()
875                        .append_pair("subdirectory", &subdirectory);
876                }
877
878                // Persist lfs=true in the distribution metadata only when explicitly enabled.
879                if git.lfs().enabled() {
880                    url.query_pairs_mut().append_pair("lfs", "true");
881                }
882
883                // Put the requested reference in the query.
884                match git.reference() {
885                    GitReference::Branch(branch) => {
886                        url.query_pairs_mut().append_pair("branch", branch.as_str());
887                    }
888                    GitReference::Tag(tag) => {
889                        url.query_pairs_mut().append_pair("tag", tag.as_str());
890                    }
891                    GitReference::BranchOrTag(rev)
892                    | GitReference::BranchOrTagOrCommit(rev)
893                    | GitReference::NamedRef(rev) => {
894                        url.query_pairs_mut().append_pair("rev", rev.as_str());
895                    }
896                    GitReference::DefaultBranch => {}
897                }
898
899                // Put the precise commit in the fragment.
900                if let Some(precise) = git.precise() {
901                    url.set_fragment(Some(&precise.to_string()));
902                }
903
904                Self::Git {
905                    git: url.to_string(),
906                }
907            }
908            RequirementSource::Path {
909                install_path,
910                ext: _,
911                url: _,
912            } => Self::Path {
913                path: PortablePathBuf::from(install_path),
914            },
915            RequirementSource::Directory {
916                install_path,
917                editable,
918                r#virtual,
919                url: _,
920            } => {
921                if editable.unwrap_or(false) {
922                    Self::Editable {
923                        editable: PortablePathBuf::from(install_path),
924                    }
925                } else if r#virtual.unwrap_or(false) {
926                    Self::Virtual {
927                        r#virtual: PortablePathBuf::from(install_path),
928                    }
929                } else {
930                    Self::Directory {
931                        directory: PortablePathBuf::from(install_path),
932                    }
933                }
934            }
935        }
936    }
937}
938
939impl TryFrom<RequirementSourceWire> for RequirementSource {
940    type Error = RequirementError;
941
942    fn try_from(wire: RequirementSourceWire) -> Result<Self, RequirementError> {
943        match wire {
944            RequirementSourceWire::Registry {
945                specifier,
946                index,
947                conflict,
948            } => Ok(Self::Registry {
949                specifier,
950                index: index
951                    .map(|index| IndexMetadata::from(IndexUrl::from(VerbatimUrl::from_url(index)))),
952                conflict,
953            }),
954            RequirementSourceWire::Git { git } => {
955                let mut repository = DisplaySafeUrl::parse(&git)?;
956
957                let mut reference = GitReference::DefaultBranch;
958                let mut subdirectory: Option<PortablePathBuf> = None;
959                let mut lfs = GitLfs::Disabled;
960                for (key, val) in repository.query_pairs() {
961                    match &*key {
962                        "tag" => reference = GitReference::Tag(val.into_owned()),
963                        "branch" => reference = GitReference::Branch(val.into_owned()),
964                        "rev" => reference = GitReference::from_rev(val.into_owned()),
965                        "subdirectory" => {
966                            subdirectory = Some(PortablePathBuf::from(val.as_ref()));
967                        }
968                        "lfs" => lfs = GitLfs::from(val.eq_ignore_ascii_case("true")),
969                        _ => {}
970                    }
971                }
972
973                let precise = repository.fragment().map(GitOid::from_str).transpose()?;
974
975                // Clear out any existing state.
976                repository.set_fragment(None);
977                repository.set_query(None);
978
979                // Remove the credentials.
980                repository.remove_credentials();
981
982                // Create a PEP 508-compatible URL.
983                let mut url = DisplaySafeUrl::parse(&format!("git+{repository}"))?;
984                if let Some(rev) = reference.as_str() {
985                    let path = format!("{}@{}", url.path(), rev);
986                    url.set_path(&path);
987                }
988                let mut frags: Vec<String> = Vec::new();
989                if let Some(subdirectory) = subdirectory.as_ref() {
990                    frags.push(format!("subdirectory={subdirectory}"));
991                }
992                // Preserve that we're using Git LFS in the Verbatim Url representations
993                if lfs.enabled() {
994                    frags.push("lfs=true".to_string());
995                }
996                if !frags.is_empty() {
997                    url.set_fragment(Some(&frags.join("&")));
998                }
999
1000                let url = VerbatimUrl::from_url(url);
1001
1002                Ok(Self::Git {
1003                    git: GitUrl::from_fields(repository, reference, precise, lfs)?,
1004                    subdirectory: subdirectory.map(Box::<Path>::from),
1005                    url,
1006                })
1007            }
1008            RequirementSourceWire::Direct { url, subdirectory } => {
1009                let location = url.clone();
1010
1011                // Create a PEP 508-compatible URL.
1012                let mut url = url.clone();
1013                if let Some(subdirectory) = &subdirectory {
1014                    url.set_fragment(Some(&format!("subdirectory={subdirectory}")));
1015                }
1016
1017                Ok(Self::Url {
1018                    location,
1019                    subdirectory: subdirectory.map(Box::<Path>::from),
1020                    ext: DistExtension::from_path(url.path())
1021                        .map_err(|err| ParsedUrlError::MissingExtensionUrl(url.to_string(), err))?,
1022                    url: VerbatimUrl::from_url(url.clone()),
1023                })
1024            }
1025            // TODO(charlie): The use of `CWD` here is incorrect. These should be resolved relative
1026            // to the workspace root, but we don't have access to it here. When comparing these
1027            // sources in the lockfile, we replace the URL anyway. Ideally, we'd either remove the
1028            // URL field or make it optional.
1029            RequirementSourceWire::Path { path } => {
1030                let path = Box::<Path>::from(path);
1031                let url = VerbatimUrl::from_normalized_path(normalize_path(CWD.join(&path)))?;
1032                Ok(Self::Path {
1033                    ext: DistExtension::from_path(&path).map_err(|err| {
1034                        ParsedUrlError::MissingExtensionPath(path.to_path_buf(), err)
1035                    })?,
1036                    install_path: path,
1037                    url,
1038                })
1039            }
1040            RequirementSourceWire::Directory { directory } => {
1041                let directory = Box::<Path>::from(directory);
1042                let url = VerbatimUrl::from_normalized_path(normalize_path(CWD.join(&directory)))?;
1043                Ok(Self::Directory {
1044                    install_path: directory,
1045                    editable: Some(false),
1046                    r#virtual: Some(false),
1047                    url,
1048                })
1049            }
1050            RequirementSourceWire::Editable { editable } => {
1051                let editable = Box::<Path>::from(editable);
1052                let url = VerbatimUrl::from_normalized_path(normalize_path(CWD.join(&editable)))?;
1053                Ok(Self::Directory {
1054                    install_path: editable,
1055                    editable: Some(true),
1056                    r#virtual: Some(false),
1057                    url,
1058                })
1059            }
1060            RequirementSourceWire::Virtual { r#virtual } => {
1061                let r#virtual = Box::<Path>::from(r#virtual);
1062                let url = VerbatimUrl::from_normalized_path(normalize_path(CWD.join(&r#virtual)))?;
1063                Ok(Self::Directory {
1064                    install_path: r#virtual,
1065                    editable: Some(false),
1066                    r#virtual: Some(true),
1067                    url,
1068                })
1069            }
1070        }
1071    }
1072}
1073
1074#[cfg(test)]
1075mod tests {
1076    use std::path::PathBuf;
1077
1078    use uv_pep508::{MarkerTree, VerbatimUrl};
1079
1080    use crate::{Requirement, RequirementSource};
1081
1082    #[test]
1083    fn roundtrip() {
1084        let requirement = Requirement {
1085            name: "foo".parse().unwrap(),
1086            extras: Box::new([]),
1087            groups: Box::new([]),
1088            marker: MarkerTree::TRUE,
1089            source: RequirementSource::Registry {
1090                specifier: ">1,<2".parse().unwrap(),
1091                index: None,
1092                conflict: None,
1093            },
1094            origin: None,
1095        };
1096
1097        let raw = toml::to_string(&requirement).unwrap();
1098        let deserialized: Requirement = toml::from_str(&raw).unwrap();
1099        assert_eq!(requirement, deserialized);
1100
1101        let path = if cfg!(windows) {
1102            "C:\\home\\ferris\\foo"
1103        } else {
1104            "/home/ferris/foo"
1105        };
1106        let requirement = Requirement {
1107            name: "foo".parse().unwrap(),
1108            extras: Box::new([]),
1109            groups: Box::new([]),
1110            marker: MarkerTree::TRUE,
1111            source: RequirementSource::Directory {
1112                install_path: PathBuf::from(path).into_boxed_path(),
1113                editable: Some(false),
1114                r#virtual: Some(false),
1115                url: VerbatimUrl::from_absolute_path(path).unwrap(),
1116            },
1117            origin: None,
1118        };
1119
1120        let raw = toml::to_string(&requirement).unwrap();
1121        let deserialized: Requirement = toml::from_str(&raw).unwrap();
1122        assert_eq!(requirement, deserialized);
1123    }
1124}
uv_distribution_types/requirement.rs

uv_distribution_types/
requirement.rs
