Enum IndexUrl 

pub enum IndexUrl {
    Pypi(Arc<VerbatimUrl>),
    Url(Arc<VerbatimUrl>),
    Path(Arc<VerbatimUrl>),
}

The URL of an index to use for fetching packages (e.g., PyPI).

Variants

Pypi(Arc<VerbatimUrl>)

Url(Arc<VerbatimUrl>)

Path(Arc<VerbatimUrl>)

Implementations

impl IndexUrl

pub fn parse(path: &str, root_dir: Option<&Path>) -> Result<Self, IndexUrlError>

Parse an IndexUrl from a string, relative to an optional root directory.

If no root directory is provided, relative paths are resolved against the current working directory.

pub fn root(&self) -> Option<DisplaySafeUrl>

Return the root Url of the index, if applicable.

For indexes with a /simple endpoint, this is simply the URL with the final segment removed. This is useful, e.g., for credential propagation to other endpoints on the index.

impl IndexUrl

pub fn url(&self) -> &DisplaySafeUrl

Return the raw URL for the index.

pub fn into_url(self) -> DisplaySafeUrl

Convert the index URL into a DisplaySafeUrl.

pub fn without_credentials(&self) -> Cow<'_, DisplaySafeUrl>

Return the redacted URL for the index, omitting any sensitive credentials.

pub fn warn_on_disambiguated_relative_path(&self)

Warn user if the given URL was provided as an ambiguous relative path.

This is a temporary warning. Ambiguous values will not be accepted in the future.

Methods from Deref<Target = Url>

pub fn join(&self, input: &str) -> Result<Url, ParseError>

Parse a string as an URL, with this URL as the base URL.

The inverse of this is make_relative.

Notes

• A trailing slash is significant. Without it, the last path component is considered to be a “file” name to be removed to get at the “directory” that is used as the base.
• A scheme relative special URL as input replaces everything in the base URL after the scheme.
• An absolute URL (with a scheme) as input replaces the whole base URL (even the scheme).

Examples

use url::Url;

// Base without a trailing slash
let base = Url::parse("https://example.net/a/b.html")?;
let url = base.join("c.png")?;
assert_eq!(url.as_str(), "https://example.net/a/c.png");  // Not /a/b.html/c.png

// Base with a trailing slash
let base = Url::parse("https://example.net/a/b/")?;
let url = base.join("c.png")?;
assert_eq!(url.as_str(), "https://example.net/a/b/c.png");

// Input as scheme relative special URL
let base = Url::parse("https://alice.com/a")?;
let url = base.join("//eve.com/b")?;
assert_eq!(url.as_str(), "https://eve.com/b");

// Input as base url relative special URL
let base = Url::parse("https://alice.com/a")?;
let url = base.join("/v1/meta")?;
assert_eq!(url.as_str(), "https://alice.com/v1/meta");

// Input as absolute URL
let base = Url::parse("https://alice.com/a")?;
let url = base.join("http://eve.com/b")?;
assert_eq!(url.as_str(), "http://eve.com/b");  // http instead of https

Errors

If the function can not parse an URL from the given string with this URL as the base URL, a ParseError variant will be returned.

pub fn make_relative(&self, url: &Url) -> Option<String>

Creates a relative URL if possible, with this URL as the base URL.

This is the inverse of join.

Examples

use url::Url;

let base = Url::parse("https://example.net/a/b.html")?;
let url = Url::parse("https://example.net/a/c.png")?;
let relative = base.make_relative(&url);
assert_eq!(relative.as_ref().map(|s| s.as_str()), Some("c.png"));

let base = Url::parse("https://example.net/a/b/")?;
let url = Url::parse("https://example.net/a/b/c.png")?;
let relative = base.make_relative(&url);
assert_eq!(relative.as_ref().map(|s| s.as_str()), Some("c.png"));

let base = Url::parse("https://example.net/a/b/")?;
let url = Url::parse("https://example.net/a/d/c.png")?;
let relative = base.make_relative(&url);
assert_eq!(relative.as_ref().map(|s| s.as_str()), Some("../d/c.png"));

let base = Url::parse("https://example.net/a/b.html?c=d")?;
let url = Url::parse("https://example.net/a/b.html?e=f")?;
let relative = base.make_relative(&url);
assert_eq!(relative.as_ref().map(|s| s.as_str()), Some("?e=f"));

Errors

If this URL can’t be a base for the given URL, None is returned. This is for example the case if the scheme, host or port are not the same.

pub fn as_str(&self) -> &str

Return the serialization of this URL.

This is fast since that serialization is already stored in the Url struct.

Examples

use url::Url;

let url_str = "https://example.net/";
let url = Url::parse(url_str)?;
assert_eq!(url.as_str(), url_str);

pub fn origin(&self) -> Origin

Return the origin of this URL (https://url.spec.whatwg.org/#origin)

Note: this returns an opaque origin for file: URLs, which causes url.origin() != url.origin().

Examples

URL with ftp scheme:

use url::{Host, Origin, Url};

let url = Url::parse("ftp://example.com/foo")?;
assert_eq!(url.origin(),
           Origin::Tuple("ftp".into(),
                         Host::Domain("example.com".into()),
                         21));

URL with blob scheme:

use url::{Host, Origin, Url};

let url = Url::parse("blob:https://example.com/foo")?;
assert_eq!(url.origin(),
           Origin::Tuple("https".into(),
                         Host::Domain("example.com".into()),
                         443));

URL with file scheme:

use url::{Host, Origin, Url};

let url = Url::parse("file:///tmp/foo")?;
assert!(!url.origin().is_tuple());

let other_url = Url::parse("file:///tmp/foo")?;
assert!(url.origin() != other_url.origin());

URL with other scheme:

use url::{Host, Origin, Url};

let url = Url::parse("foo:bar")?;
assert!(!url.origin().is_tuple());

pub fn scheme(&self) -> &str

Return the scheme of this URL, lower-cased, as an ASCII string without the ‘:’ delimiter.

Examples

use url::Url;

let url = Url::parse("file:///tmp/foo")?;
assert_eq!(url.scheme(), "file");

pub fn is_special(&self) -> bool

Return whether the URL is special (has a special scheme)

Examples

use url::Url;

assert!(Url::parse("http:///tmp/foo")?.is_special());
assert!(Url::parse("file:///tmp/foo")?.is_special());
assert!(!Url::parse("moz:///tmp/foo")?.is_special());

pub fn has_authority(&self) -> bool

Return whether the URL has an ‘authority’, which can contain a username, password, host, and port number.

URLs that do not are either path-only like unix:/run/foo.socket or cannot-be-a-base like data:text/plain,Stuff.

See also the authority method.

Examples

use url::Url;

let url = Url::parse("ftp://rms@example.com")?;
assert!(url.has_authority());

let url = Url::parse("unix:/run/foo.socket")?;
assert!(!url.has_authority());

let url = Url::parse("data:text/plain,Stuff")?;
assert!(!url.has_authority());

pub fn authority(&self) -> &str

Return the authority of this URL as an ASCII string.

Non-ASCII domains are punycode-encoded per IDNA if this is the host of a special URL, or percent encoded for non-special URLs. IPv6 addresses are given between [ and ] brackets. Ports are omitted if they match the well known port of a special URL.

Username and password are percent-encoded.

See also the has_authority method.

Examples

use url::Url;

let url = Url::parse("unix:/run/foo.socket")?;
assert_eq!(url.authority(), "");
let url = Url::parse("file:///tmp/foo")?;
assert_eq!(url.authority(), "");
let url = Url::parse("https://user:password@example.com/tmp/foo")?;
assert_eq!(url.authority(), "user:password@example.com");
let url = Url::parse("irc://àlex.рф.example.com:6667/foo")?;
assert_eq!(url.authority(), "%C3%A0lex.%D1%80%D1%84.example.com:6667");
let url = Url::parse("http://àlex.рф.example.com:80/foo")?;
assert_eq!(url.authority(), "xn--lex-8ka.xn--p1ai.example.com");

pub fn cannot_be_a_base(&self) -> bool

Return whether this URL is a cannot-be-a-base URL, meaning that parsing a relative URL string with this URL as the base will return an error.

This is the case if the scheme and : delimiter are not followed by a / slash, as is typically the case of data: and mailto: URLs.

Examples

use url::Url;

let url = Url::parse("ftp://rms@example.com")?;
assert!(!url.cannot_be_a_base());

let url = Url::parse("unix:/run/foo.socket")?;
assert!(!url.cannot_be_a_base());

let url = Url::parse("data:text/plain,Stuff")?;
assert!(url.cannot_be_a_base());

pub fn username(&self) -> &str

Return the username for this URL (typically the empty string) as a percent-encoded ASCII string.

Examples

use url::Url;

let url = Url::parse("ftp://rms@example.com")?;
assert_eq!(url.username(), "rms");

let url = Url::parse("ftp://:secret123@example.com")?;
assert_eq!(url.username(), "");

let url = Url::parse("https://example.com")?;
assert_eq!(url.username(), "");

pub fn password(&self) -> Option<&str>

Return the password for this URL, if any, as a percent-encoded ASCII string.

Examples

use url::Url;

let url = Url::parse("ftp://rms:secret123@example.com")?;
assert_eq!(url.password(), Some("secret123"));

let url = Url::parse("ftp://:secret123@example.com")?;
assert_eq!(url.password(), Some("secret123"));

let url = Url::parse("ftp://rms@example.com")?;
assert_eq!(url.password(), None);

let url = Url::parse("https://example.com")?;
assert_eq!(url.password(), None);

pub fn has_host(&self) -> bool

Equivalent to url.host().is_some().

Examples

use url::Url;

let url = Url::parse("ftp://rms@example.com")?;
assert!(url.has_host());

let url = Url::parse("unix:/run/foo.socket")?;
assert!(!url.has_host());

let url = Url::parse("data:text/plain,Stuff")?;
assert!(!url.has_host());

pub fn host_str(&self) -> Option<&str>

Return the string representation of the host (domain or IP address) for this URL, if any.

Non-ASCII domains are punycode-encoded per IDNA if this is the host of a special URL, or percent encoded for non-special URLs. IPv6 addresses are given between [ and ] brackets.

Cannot-be-a-base URLs (typical of data: and mailto:) and some file: URLs don’t have a host.

See also the host method.

Examples

use url::Url;

let url = Url::parse("https://127.0.0.1/index.html")?;
assert_eq!(url.host_str(), Some("127.0.0.1"));

let url = Url::parse("https://subdomain.example.com")?;
assert_eq!(url.host_str(), Some("subdomain.example.com"));

let url = Url::parse("ftp://rms@example.com")?;
assert_eq!(url.host_str(), Some("example.com"));

let url = Url::parse("unix:/run/foo.socket")?;
assert_eq!(url.host_str(), None);

let url = Url::parse("data:text/plain,Stuff")?;
assert_eq!(url.host_str(), None);

pub fn host(&self) -> Option<Host<&str>>

Return the parsed representation of the host for this URL. Non-ASCII domain labels are punycode-encoded per IDNA if this is the host of a special URL, or percent encoded for non-special URLs.

Cannot-be-a-base URLs (typical of data: and mailto:) and some file: URLs don’t have a host.

See also the host_str method.

Examples

use url::Url;

let url = Url::parse("https://127.0.0.1/index.html")?;
assert!(url.host().is_some());

let url = Url::parse("ftp://rms@example.com")?;
assert!(url.host().is_some());

let url = Url::parse("unix:/run/foo.socket")?;
assert!(url.host().is_none());

let url = Url::parse("data:text/plain,Stuff")?;
assert!(url.host().is_none());

pub fn domain(&self) -> Option<&str>

If this URL has a host and it is a domain name (not an IP address), return it. Non-ASCII domains are punycode-encoded per IDNA if this is the host of a special URL, or percent encoded for non-special URLs.

Examples

use url::Url;

let url = Url::parse("https://127.0.0.1/")?;
assert_eq!(url.domain(), None);

let url = Url::parse("mailto:rms@example.net")?;
assert_eq!(url.domain(), None);

let url = Url::parse("https://example.com/")?;
assert_eq!(url.domain(), Some("example.com"));

let url = Url::parse("https://subdomain.example.com/")?;
assert_eq!(url.domain(), Some("subdomain.example.com"));

pub fn port(&self) -> Option<u16>

Return the port number for this URL, if any.

Note that default port numbers are never reflected by the serialization, use the port_or_known_default() method if you want a default port number returned.

Examples

use url::Url;

let url = Url::parse("https://example.com")?;
assert_eq!(url.port(), None);

let url = Url::parse("https://example.com:443/")?;
assert_eq!(url.port(), None);

let url = Url::parse("ssh://example.com:22")?;
assert_eq!(url.port(), Some(22));

pub fn port_or_known_default(&self) -> Option<u16>

Return the port number for this URL, or the default port number if it is known.

This method only knows the default port number of the http, https, ws, wss and ftp schemes.

For URLs in these schemes, this method always returns Some(_). For other schemes, it is the same as Url::port().

Examples

use url::Url;

let url = Url::parse("foo://example.com")?;
assert_eq!(url.port_or_known_default(), None);

let url = Url::parse("foo://example.com:1456")?;
assert_eq!(url.port_or_known_default(), Some(1456));

let url = Url::parse("https://example.com")?;
assert_eq!(url.port_or_known_default(), Some(443));

pub fn socket_addrs( &self, default_port_number: impl Fn() -> Option<u16>, ) -> Result<Vec<SocketAddr>, Error>

Resolve a URL’s host and port number to SocketAddr.

If the URL has the default port number of a scheme that is unknown to this library, default_port_number provides an opportunity to provide the actual port number. In non-example code this should be implemented either simply as || None, or by matching on the URL’s .scheme().

If the host is a domain, it is resolved using the standard library’s DNS support.

Examples

let url = url::Url::parse("https://example.net/").unwrap();
let addrs = url.socket_addrs(|| None).unwrap();
std::net::TcpStream::connect(&*addrs)

/// With application-specific known default port numbers
fn socket_addrs(url: url::Url) -> std::io::Result<Vec<std::net::SocketAddr>> {
    url.socket_addrs(|| match url.scheme() {
        "socks5" | "socks5h" => Some(1080),
        _ => None,
    })
}

pub fn path(&self) -> &str

Return the path for this URL, as a percent-encoded ASCII string. For cannot-be-a-base URLs, this is an arbitrary string that doesn’t start with ‘/’. For other URLs, this starts with a ‘/’ slash and continues with slash-separated path segments.

Examples

use url::{Url, ParseError};

let url = Url::parse("https://example.com/api/versions?page=2")?;
assert_eq!(url.path(), "/api/versions");

let url = Url::parse("https://example.com")?;
assert_eq!(url.path(), "/");

let url = Url::parse("https://example.com/countries/việt nam")?;
assert_eq!(url.path(), "/countries/vi%E1%BB%87t%20nam");

pub fn path_segments(&self) -> Option<Split<'_, char>>

Unless this URL is cannot-be-a-base, return an iterator of ‘/’ slash-separated path segments, each as a percent-encoded ASCII string.

Return None for cannot-be-a-base URLs.

When Some is returned, the iterator always contains at least one string (which may be empty).

Examples

use url::Url;


let url = Url::parse("https://example.com/foo/bar")?;
let mut path_segments = url.path_segments().ok_or_else(|| "cannot be base")?;
assert_eq!(path_segments.next(), Some("foo"));
assert_eq!(path_segments.next(), Some("bar"));
assert_eq!(path_segments.next(), None);

let url = Url::parse("https://example.com")?;
let mut path_segments = url.path_segments().ok_or_else(|| "cannot be base")?;
assert_eq!(path_segments.next(), Some(""));
assert_eq!(path_segments.next(), None);

let url = Url::parse("data:text/plain,HelloWorld")?;
assert!(url.path_segments().is_none());

let url = Url::parse("https://example.com/countries/việt nam")?;
let mut path_segments = url.path_segments().ok_or_else(|| "cannot be base")?;
assert_eq!(path_segments.next(), Some("countries"));
assert_eq!(path_segments.next(), Some("vi%E1%BB%87t%20nam"));

pub fn query(&self) -> Option<&str>

Return this URL’s query string, if any, as a percent-encoded ASCII string.

Examples

use url::Url;

fn run() -> Result<(), ParseError> {
let url = Url::parse("https://example.com/products?page=2")?;
let query = url.query();
assert_eq!(query, Some("page=2"));

let url = Url::parse("https://example.com/products")?;
let query = url.query();
assert!(query.is_none());

let url = Url::parse("https://example.com/?country=español")?;
let query = url.query();
assert_eq!(query, Some("country=espa%C3%B1ol"));

pub fn query_pairs(&self) -> Parse<'_>

Parse the URL’s query string, if any, as application/x-www-form-urlencoded and return an iterator of (key, value) pairs.

Examples

use std::borrow::Cow;

use url::Url;

let url = Url::parse("https://example.com/products?page=2&sort=desc")?;
let mut pairs = url.query_pairs();

assert_eq!(pairs.count(), 2);

assert_eq!(pairs.next(), Some((Cow::Borrowed("page"), Cow::Borrowed("2"))));
assert_eq!(pairs.next(), Some((Cow::Borrowed("sort"), Cow::Borrowed("desc"))));

pub fn fragment(&self) -> Option<&str>

Return this URL’s fragment identifier, if any.

A fragment is the part of the URL after the # symbol. The fragment is optional and, if present, contains a fragment identifier that identifies a secondary resource, such as a section heading of a document.

In HTML, the fragment identifier is usually the id attribute of a an element that is scrolled to on load. Browsers typically will not send the fragment portion of a URL to the server.

Note: the parser did not percent-encode this component, but the input may have been percent-encoded already.

Examples

use url::Url;

let url = Url::parse("https://example.com/data.csv#row=4")?;

assert_eq!(url.fragment(), Some("row=4"));

let url = Url::parse("https://example.com/data.csv#cell=4,1-6,2")?;

assert_eq!(url.fragment(), Some("cell=4,1-6,2"));

pub fn serialize_internal<S>( &self, serializer: S, ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>

where S: Serializer,

Serialize with Serde using the internal representation of the Url struct.

The corresponding deserialize_internal method sacrifices some invariant-checking for speed, compared to the Deserialize trait impl.

This method is only available if the serde Cargo feature is enabled.

pub fn to_file_path(&self) -> Result<PathBuf, ()>

Assuming the URL is in the file scheme or similar, convert its path to an absolute std::path::Path.

Note: This does not actually check the URL’s scheme, and may give nonsensical results for other schemes. It is the user’s responsibility to check the URL’s scheme before calling this.

let path = url.to_file_path();

Returns Err if the host is neither empty nor "localhost" (except on Windows, where file: URLs may have a non-local host), or if Path::new_opt() returns None. (That is, if the percent-decoded path contains a NUL byte or, for a Windows path, is not UTF-8.)

This method is only available if the std Cargo feature is enabled.

Trait Implementations

impl Clone for IndexUrl

fn clone(&self) -> IndexUrl

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for IndexUrl

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for IndexUrl

type Target = Url

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'de> Deserialize<'de> for IndexUrl

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for IndexUrl

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> From<&'a IndexUrl> for IndexMetadataRef<'a>

fn from(value: &'a IndexUrl) -> Self

Converts to this type from the input type.

impl From<IndexUrl> for DisplaySafeUrl

fn from(index: IndexUrl) -> Self

Converts to this type from the input type.

impl From<IndexUrl> for Index

fn from(value: IndexUrl) -> Self

Converts to this type from the input type.

impl From<IndexUrl> for IndexMetadata

fn from(value: IndexUrl) -> Self

Converts to this type from the input type.

impl From<VerbatimUrl> for IndexUrl

fn from(url: VerbatimUrl) -> Self

Converts to this type from the input type.

impl FromStr for IndexUrl

type Err = IndexUrlError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Hash for IndexUrl

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for IndexUrl

fn cmp(&self, other: &IndexUrl) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for IndexUrl

fn eq(&self, other: &IndexUrl) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for IndexUrl

fn partial_cmp(&self, other: &IndexUrl) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for IndexUrl

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl Verbatim for IndexUrl

fn verbatim(&self) -> Cow<'_, str>

Return the verbatim representation of the distribution.

impl Eq for IndexUrl

impl StructuralPartialEq for IndexUrl