llnl package

Subpackages

llnl.util package

Submodules

llnl.path module

Path primitives that just require Python standard library.

class llnl.path.Path[source]

Bases: object

Enum to identify the path-style.

platform_path: int = 0

unix: int = 0

windows: int = 1

llnl.path.convert_to_platform_path(path: str) → str[source]: Converts the input path to the current platform’s native style.

llnl.path.convert_to_posix_path(path: str) → str[source]: Converts the input path to POSIX style.

llnl.path.convert_to_windows_path(path: str) → str[source]: Converts the input path to Windows style.

llnl.path.format_os_path(path: str, mode: int = 0) → str[source]

Formats the input path to use consistent, platform specific separators.

Absolute paths are converted between drive letters and a prepended ‘/’ as per platform requirement.

Parameters:

path – the path to be normalized, must be a string or expose the replace method.
mode – the path file separator style to normalize the passed path to. Default is unix style, i.e. ‘/’

llnl.path.path_to_os_path(*parameters: str) → List[str][source]: Takes an arbitrary number of positional parameters, converts each argument of type string to use a normalized filepath separator, and returns a list of all values.

llnl.path.system_path_filter(_func=None, arg_slice: slice | None = None)[source]

Filters function arguments to account for platform path separators. Optional slicing range can be specified to select specific arguments

This decorator takes all (or a slice) of a method’s positional arguments and normalizes usage of filepath separators on a per platform basis.

Note: **kwargs, urls, and any type that is not a string are ignored so in such cases where path normalization is required, that should be handled by calling path_to_os_path directly as needed.

Parameters:: arg_slice – a slice object specifying the slice of arguments in the decorated method over which filepath separators are normalized

llnl.string module

String manipulation functions that do not have other dependencies than Python standard library

llnl.string.comma_and(sequence: List[str]) → str[source]: Return a string with all the elements of the input joined by comma, but the last one (which is joined by ‘and’).

llnl.string.comma_list(sequence: List[str], article: str = '') → str[source]

llnl.string.comma_or(sequence: List[str]) → str[source]: Return a string with all the elements of the input joined by comma, but the last one (which is joined by ‘or’).

llnl.string.plural(n: int, singular: str, plural: str | None = None, show_n: bool = True) → str[source]

Pluralize <singular> word by adding an s if n != 1.

Parameters:

n – number of things there are
singular – singular form of word
plural – optional plural form, for when it’s not just singular + ‘s’
show_n – whether to include n in the result string (default True)

Returns:

“1 thing” if n == 1 or “n things” if n != 1

llnl.string.quote(sequence: List[str], q: str = "'") → List[str][source]: Quotes each item in the input list with the quote character passed as second argument.

llnl.url module

URL primitives that just require Python standard library.

llnl.url.allowed_archive(path_or_url: str) → bool[source]: Returns true if the input is a valid archive, False otherwise.

llnl.url.check_and_remove_ext(path: str, *, extension: str) → str[source]: Returns the input path with the extension removed, if the extension is present in path. Otherwise, returns the input unchanged.

llnl.url.compression_ext_from_compressed_archive(extension: str) → str | None[source]: Returns compression extension for a compressed archive

llnl.url.determine_url_file_extension(path: str) → str[source]

This returns the type of archive a URL refers to. This is sometimes confusing because of URLs like:

https://github.com/petdance/ack/tarball/1.93_02

Where the URL doesn’t actually contain the filename. We need to know what type it is so that we can appropriately name files in mirrors.

llnl.url.expand_contracted_extension(extension: str) → str[source]

Returns the expanded version of a known contracted extension.

This function maps extensions like “.tgz” to “.tar.gz”. On unknown extensions, return the input unmodified.

llnl.url.expand_contracted_extension_in_path(path_or_url: str, *, extension: str | None = None) → str[source]

Returns the input path or URL with any contraction extension expanded.

Parameters:

path_or_url – path or URL to be expanded
extension – if specified, only attempt to expand that extension

llnl.url.extension_from_path(path_or_url: str | None) → str | None[source]

Tries to match an allowed archive extension to the input. Returns the first match, or None if no match was found.

Raises:: ValueError – if the input is None

llnl.url.find_list_urls(url: str) → Set[str][source]

Find good list URLs for the supplied URL.

By default, returns the dirname of the archive path.

Provides special treatment for the following websites, which have a unique list URL different from the dirname of the download URL:

GitHub	https://github.com/<repo>/<name>/releases
GitLab	https://gitlab.*/<repo>/<name>/tags
BitBucket	https://bitbucket.org/<repo>/<name>/downloads/?tab=tags
CRAN	https://*.r-project.org/src/contrib/Archive/<name>
PyPI	https://pypi.org/simple/<name>/
LuaRocks	https://luarocks.org/modules/<repo>/<name>

Note: this function is called by spack versions, spack checksum, and spack create, but not by spack fetch or spack install.

Parameters:: url (str) – The download URL for the package
Returns:: One or more list URLs for the package
Return type:: set

llnl.url.has_extension(path_or_url: str, ext: str) → bool[source]: Returns true if the extension in input is present in path, false otherwise.

llnl.url.remove_extension(path_or_url: str, *, extension: str) → str[source]: Returns the input with the extension removed

llnl.url.split_url_extension(url: str) → Tuple[str, ...][source]

Some URLs have a query string, e.g.:

In (1), the query string needs to be stripped to get at the extension, but in (2) & (3), the filename is IN a single final query argument.

This strips the URL into three pieces: prefix, ext, and suffix. The suffix contains anything that was stripped off the URL to get at the file extension. In (1), it will be '?raw=true', but in (2), it will be empty. In (3) the suffix is a parameter that follows after the file extension, e.g.:

('https://github.com/losalamos/CLAMR/blob/packages/PowerParser_v2.0.7', '.tgz', '?raw=true')
('http://www.apache.org/dyn/closer.cgi?path=/cassandra/1.2.0/apache-cassandra-1.2.0-rc2-bin', '.tar.gz', None)
('https://gitlab.kitware.com/vtk/vtk/repository/archive', '.tar.bz2', '?ref=v7.0.0')

llnl.url.split_url_on_sourceforge_suffix(url: str) → Tuple[str, ...][source]: If the input is a sourceforge URL, returns base URL and “/download” suffix. Otherwise, returns the input URL and an empty string.

llnl.url.strip_compression_extension(path_or_url: str, ext: str | None = None) → str[source]

Strips the compression extension from the input, and returns it. For instance, “foo.tgz” becomes “foo.tar”.

If no extension is given, try a default list of extensions.

Parameters:

path_or_url – input to be stripped
ext – if given, extension to be stripped

llnl.url.strip_extension(path_or_url: str, *, extension: str | None = None) → str[source]

If a path contains the extension in input, returns the path stripped of the extension. Otherwise, returns the input path.

If extension is None, attempts to strip any allowed extension from path.

llnl.url.strip_query_and_fragment(url: str) → Tuple[str, str][source]

Strips query and fragment from a url, then returns the base url and the suffix.

Parameters:: url – URL to be stripped
Raises:: ValueError – when there is any error parsing the URL

llnl.url.strip_version_suffixes(path_or_url: str) → str[source]

Some tarballs contain extraneous information after the version:

bowtie2-2.2.5-source
libevent-2.0.21-stable
cuda_8.0.44_linux.run

These strings are not part of the version number and should be ignored. This function strips those suffixes off and returns the remaining string. The goal is that the version is always the last thing in path:

bowtie2-2.2.5
libevent-2.0.21
cuda_8.0.44

Parameters:: path_or_url – The filename or URL for the package
Returns:: The path with any extraneous suffixes removed