b.urlutils : module documentation

Part of bzrlib

A collection of function for handling URL operations.
Function basename Return the last component of a URL.
Function dirname Return the parent directory of the given path.
Function escape Escape relpath to be a valid url.
Function file_relpath Compute just the relative sub-portion of a url
Function is_url Tests whether a URL is in actual fact a URL.
Function join Create a URL by joining sections.
Function joinpath Join URL path segments to a URL path segment.
Function normalize_url Make sure that a path string is in fully normalized URL form.
Function relative_url Return a path to other from base.
Function split Split a URL into its parent directory and a child directory.
Function split_segment_parameters_raw Split the subsegment of the last segment of a URL.
Function split_segment_parameters Split the segment parameters of the last segment of a URL.
Function join_segment_parameters_raw Create a new URL by adding subsegments to an existing one.
Function join_segment_parameters Create a new URL by adding segment parameters to an existing one.
Function strip_trailing_slash Strip trailing slash, except for root paths.
Function unescape Unescape relpath from url format.
Function unescape_for_display Decode what you can for a URL, so that we get a nice looking path.
Function derive_to_location Derive a TO_LOCATION given a FROM_LOCATION.
Function rebase_url Convert a relative path from an old base URL to a new base URL.
Function determine_relative_path Determine a relative path from from_path to to_path.
Class URL Parsed URL.
Function parse_url Extract the server address, the credentials and the path from the url.
Function _find_scheme_and_separator Find the scheme separator (://) and the first path separator
Function _posix_local_path_from_url Convert a url like file:///path/to/foo into /path/to/foo
Function _posix_local_path_to_url Convert a local path like ./foo into a URL like file:///path/to/foo
Function _win32_local_path_from_url Convert a url like file:///C:/path/to/foo into C:/path/to/foo
Function _win32_local_path_to_url Convert a local path like ./foo into a URL like file:///C:/path/to/foo
Function _unescape_safe_chars re.sub callback to convert hex-escapes to plain characters (if safe).
Function _win32_extract_drive_letter On win32 the drive letter needs to be added to the url base.
Function _win32_strip_local_trailing_slash Strip slashes after the drive letter
Function _is_absolute Undocumented
def basename(url, exclude_trailing_slash=True):
Return the last component of a URL.
ParametersurlThe URL in question
exclude_trailing_slashIf the url looks like "path/to/foo/" ignore the final slash and return 'foo' rather than ''
ReturnsJust the final component of the URL. This can return '' if you don't exclude_trailing_slash, or if you are at the root of the URL.
def dirname(url, exclude_trailing_slash=True):
Return the parent directory of the given path.
ParametersurlRelative or absolute URL
exclude_trailing_slashRemove a final slash (treat http://host/foo/ as http://host/foo, but http://host/ stays http://host/)
ReturnsEverything in the URL except the last path chunk
def escape(relpath):
Escape relpath to be a valid url.
def file_relpath(base, path):
Compute just the relative sub-portion of a url

This assumes that both paths are already fully specified file:// URLs.

def _find_scheme_and_separator(url):
Find the scheme separator (://) and the first path separator

This is just a helper functions for other path utilities. It could probably be replaced by urlparse

def is_url(url):
Tests whether a URL is in actual fact a URL.
def join(base, *args):
Create a URL by joining sections.

This will normalize '..', assuming that paths are absolute
(it assumes no symlinks in either path)

If any of *args is an absolute URL, it will be treated correctly.
Example:
    join('http://foo', 'http://bar') => 'http://bar'
    join('http://foo', 'bar') => 'http://foo/bar'
    join('http://foo', 'bar', '../baz') => 'http://foo/baz'
def joinpath(base, *args):
Join URL path segments to a URL path segment.

This is somewhat like osutils.joinpath, but intended for URLs.

XXX: this duplicates some normalisation logic, and also duplicates a lot of path handling logic that already exists in some Transport implementations. We really should try to have exactly one place in the code base responsible for combining paths of URLs.

def _posix_local_path_from_url(url):
Convert a url like file:///path/to/foo into /path/to/foo
def _posix_local_path_to_url(path):
Convert a local path like ./foo into a URL like file:///path/to/foo

This also handles transforming escaping unicode characters, etc.

def _win32_local_path_from_url(url):
Convert a url like file:///C:/path/to/foo into C:/path/to/foo
def _win32_local_path_to_url(path):
Convert a local path like ./foo into a URL like file:///C:/path/to/foo

This also handles transforming escaping unicode characters, etc.

def _unescape_safe_chars(matchobj):
re.sub callback to convert hex-escapes to plain characters (if safe).

e.g. '%7E' will be converted to '~'.

def normalize_url(url):
Make sure that a path string is in fully normalized URL form.

This handles URLs which have unicode characters, spaces, special characters, etc.

It has two basic modes of operation, depending on whether the supplied string starts with a url specifier (scheme://) or not. If it does not have a specifier it is considered a local path, and will be converted into a file:/// url. Non-ascii characters will be encoded using utf-8. If it does have a url specifier, it will be treated as a "hybrid" URL. Basically, a URL that should have URL special characters already escaped (like +?&# etc), but may have unicode characters, etc which would not be valid in a real URL.

ParametersurlEither a hybrid URL or a local path
ReturnsA normalized URL which only includes 7-bit ASCII characters.
def relative_url(base, other):
Return a path to other from base.

If other is unrelated to base, return other. Else return a relative path. This assumes no symlinks as part of the url.

def _win32_extract_drive_letter(url_base, path):
On win32 the drive letter needs to be added to the url base.
def split(url, exclude_trailing_slash=True):
Split a URL into its parent directory and a child directory.
ParametersurlA relative or absolute URL
exclude_trailing_slashStrip off a final '/' if it is part of the path (but not if it is part of the protocol specification)
Returns(parent_url, child_dir). child_dir may be the empty string if we're at the root.
def split_segment_parameters_raw(url):
Split the subsegment of the last segment of a URL.
ParametersurlA relative or absolute URL
Returns(url, subsegments)
def split_segment_parameters(url):
Split the segment parameters of the last segment of a URL.
ParametersurlA relative or absolute URL
Returns(url, segment_parameters)
def join_segment_parameters_raw(base, *subsegments):
Create a new URL by adding subsegments to an existing one.

This adds the specified subsegments to the last path in the specified base URL. The subsegments should be bytestrings.

NoteYou probably want to use join_segment_parameters instead.
def join_segment_parameters(url, parameters):
Create a new URL by adding segment parameters to an existing one.

The parameters of the last segment in the URL will be updated; if a parameter with the same key already exists it will be overwritten.

ParametersurlA URL, as string
parametersDictionary of parameters, keys and values as bytestrings
def _win32_strip_local_trailing_slash(url):
Strip slashes after the drive letter
def strip_trailing_slash(url):
Strip trailing slash, except for root paths.

The definition of 'root path' is platform-dependent.
This assumes that all URLs are valid netloc urls, such that they
form:
scheme://host/path
It searches for ://, and then refuses to remove the next '/'.
It can also handle relative paths
Examples:
    path/to/foo       => path/to/foo
    path/to/foo/      => path/to/foo
    http://host/path/ => http://host/path
    http://host/path  => http://host/path
    http://host/      => http://host/
    file:///          => file:///
    file:///foo/      => file:///foo
    # This is unique on win32 platforms, and is the only URL
    # format which does it differently.
    file:///c|/       => file:///c:/
def unescape(url):
Unescape relpath from url format.

This returns a Unicode path from a URL

def unescape_for_display(url, encoding):
Decode what you can for a URL, so that we get a nice looking path.

This will turn file:// urls into local paths, and try to decode any portions of a http:// style url that it can.

Any sections of the URL which can't be represented in the encoding or need to stay as escapes are left alone.

ParametersurlA 7-bit ASCII URL
encodingThe final output encoding
ReturnsA unicode string which can be safely encoded into the specified encoding.
def derive_to_location(from_location):
Derive a TO_LOCATION given a FROM_LOCATION.

The normal case is a FROM_LOCATION of http://foo/bar => bar. The Right Thing for some logical destinations may differ though because no / may be present at all. In that case, the result is the full name without the scheme indicator, e.g. lp:foo-bar => foo-bar. This latter case also applies when a Windows drive is used without a path, e.g. c:foo-bar => foo-bar. If no /, path separator or : is found, the from_location is returned.

def _is_absolute(url):
Undocumented
def rebase_url(url, old_base, new_base):
Convert a relative path from an old base URL to a new base URL.

The result will be a relative path. Absolute paths and full URLs are returned unaltered.

def determine_relative_path(from_path, to_path):
Determine a relative path from from_path to to_path.
def parse_url(url):
Extract the server address, the credentials and the path from the url.

user, password, host and path should be quoted if they contain reserved chars.

Parametersurlan quoted url
Returns(scheme, user, password, host, port, path) tuple, all fields are unquoted.
API Documentation for Bazaar, generated by pydoctor at 2022-06-16 00:25:16.