hlrs-software-stack/spack
7
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Convert rest docstrings to Google docstrings. (#3994)

Browse source 
- Sometimes you need something mindless to do.
- Sometimes it can be helpful, as well.
This commit is contained in:
Todd Gamblin 2017-04-27 07:45:34 -07:00 committed by GitHub
parent a6986312ba
commit 455cae01c2
18 changed files with 352 additions and 276 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

69
lib/spack/llnl/util/filesystem.py
View file

@ -584,32 +584,32 @@ def __str__(self):
return self.joined()
def find_system_libraries(args, shared=True):
"""Searches the usual system library locations for the libraries
specified in args.
def find_system_libraries(library_names, shared=True):
"""Searches the usual system library locations for ``library_names``.
Search order is as follows:
1. /lib64
2. /lib
3. /usr/lib64
4. /usr/lib
5. /usr/local/lib64
6. /usr/local/lib
1. ``/lib64``
2. ``/lib``
3. ``/usr/lib64``
4. ``/usr/lib``
5. ``/usr/local/lib64``
6. ``/usr/local/lib``
:param args: Library name(s) to search for
:type args: str or collections.Sequence
:param bool shared: if True searches for shared libraries,
Args:
library_names (str or list of str): Library name(s) to search for
shared (bool): searches for shared libraries if True
:returns: The libraries that have been found
:rtype: LibraryList
Returns:
LibraryList: The libraries that have been found
"""
if isinstance(args, str):
args = [args]
elif not isinstance(args, collections.Sequence):
if isinstance(library_names, str):
library_names = [library_names]
elif not isinstance(library_names, collections.Sequence):
message = '{0} expects a string or sequence of strings as the '
message += 'first argument [got {1} instead]'
message = message.format(find_system_libraries.__name__, type(args))
message = message.format(
find_system_libraries.__name__, type(library_names))
raise TypeError(message)
libraries_found = []
@ -622,7 +622,7 @@ def find_system_libraries(args, shared=True):
'/usr/local/lib',
]
for library in args:
for library in library_names:
for root in search_locations:
result = find_libraries(library, root, shared, recurse=True)
if result:
@ -632,27 +632,26 @@ def find_system_libraries(args, shared=True):
return libraries_found
def find_libraries(args, root, shared=True, recurse=False):
"""Returns an iterable object containing a list of full paths to
libraries if found.
def find_libraries(library_names, root, shared=True, recurse=False):
"""Returns an iterable of full paths to libraries found in a root dir.
:param args: Library name(s) to search for
:type args: str or collections.Sequence
:param str root: The root directory to start searching from
:param bool shared: if True searches for shared libraries,
otherwise for static
:param bool recurse: if False search only root folder,
Args:
library_names (str or list of str): Library names to search for
root (str): The root directory to start searching from
shared (bool): if True searches for shared libraries, otherwise static.
recurse (bool): if False search only root folder,
if True descends top-down from the root
:returns: The libraries that have been found
:rtype: LibraryList
Returns:
LibraryList: The libraries that have been found
"""
if isinstance(args, str):
args = [args]
elif not isinstance(args, collections.Sequence):
if isinstance(library_names, str):
library_names = [library_names]
elif not isinstance(library_names, collections.Sequence):
message = '{0} expects a string or sequence of strings as the '
message += 'first argument [got {1} instead]'
raise TypeError(message.format(find_libraries.__name__, type(args)))
raise TypeError(message.format(
find_libraries.__name__, type(library_names)))
# Construct the right suffix for the library
if shared is True:
@ -660,7 +659,7 @@ def find_libraries(args, root, shared=True, recurse=False):
else:
suffix = 'a'
# List of libraries we are searching with suffixes
libraries = ['{0}.{1}'.format(lib, suffix) for lib in args]
libraries = ['{0}.{1}'.format(lib, suffix) for lib in library_names]
# Search method
if recurse is False:
search_method = _find_libraries_non_recursive

46
lib/spack/spack/build_environment.py
View file

@ -438,12 +438,17 @@ def get_rpaths(pkg):
def get_std_cmake_args(pkg):
"""Returns the list of standard arguments that would be used if this
package was a CMakePackage instance.
"""List of standard arguments used if a package is a CMakePackage.
:param pkg: pkg under consideration
Returns:
list of str: standard arguments that would be used if this
package were a CMakePackage instance.
:return: list of arguments for cmake
Args:
pkg (PackageBase): package under consideration
Returns:
list of str: arguments for cmake
"""
return spack.CMakePackage._std_args(pkg)
@ -465,10 +470,13 @@ def parent_class_modules(cls):
def load_external_modules(pkg):
"""Traverse the spec list associated with a package
and find any specs that have external modules.
"""Traverse a package's spec DAG and load any external modules.
:param pkg: package under consideration
Traverse a package's dependencies and load any external modules
associated with them.
Args:
pkg (PackageBase): package to load deps for
"""
for dep in list(pkg.spec.traverse()):
if dep.external_module:
@ -531,9 +539,14 @@ def setup_package(pkg, dirty=False):
def fork(pkg, function, dirty=False):
"""Fork a child process to do part of a spack build.
:param pkg: pkg whose environemnt we should set up the forked process for.
:param function: arg-less function to run in the child process.
:param dirty: If True, do NOT clean the environment before building.
Args:
pkg (PackageBase): package whose environemnt we should set up the
forked process for.
function (callable): argless function to run in the child
process.
dirty (bool): If True, do NOT clean the environment before
building.
Usage::
@ -542,14 +555,13 @@ def child_fun():
build_env.fork(pkg, child_fun)
Forked processes are run with the build environment set up by
spack.build_environment. This allows package authors to have
full control over the environment, etc. without affecting
other builds that might be executed in the same spack call.
spack.build_environment. This allows package authors to have full
control over the environment, etc. without affecting other builds
that might be executed in the same spack call.
If something goes wrong, the child process is expected to print
the error and the parent process will exit with error as
well. If things go well, the child exits and the parent
carries on.
If something goes wrong, the child process is expected to print the
error and the parent process will exit with error as well. If things
go well, the child exits and the parent carries on.
"""
def child_execution(child_connection, input_stream):

8
lib/spack/spack/build_systems/python.py
View file

@ -137,9 +137,11 @@ def setup_py(self, *args, **kwargs):
def _setup_command_available(self, command):
"""Determines whether or not a setup.py command exists.
:param str command: The command to look for
:return: True if the command is found, else False
:rtype: bool
Args:
command (str): The command to look for
Returns:
bool: True if the command is found, else False
"""
kwargs = {
'output': os.devnull,

13
lib/spack/spack/cmd/checksum.py
View file

@ -57,13 +57,14 @@ def get_checksums(url_dict, name, **kwargs):
The ``first_stage_function`` kwarg allows ``spack create`` to determine
things like the build system of the archive.
:param dict url_dict: A dictionary of the form: version -> URL
:param str name: The name of the package
:param callable first_stage_function: Function to run on first staging area
:param bool keep_stage: Don't clean up staging area when command completes
Args:
url_dict (dict): A dictionary of the form: version -> URL
name (str): The name of the package
first_stage_function (callable): Function to run on first staging area
keep_stage (bool): Don't clean up staging area when command completes
:returns: A multi-line string containing versions and corresponding hashes
:rtype: str
Returns:
str: A multi-line string containing versions and corresponding hashes
"""
first_stage_function = kwargs.get('first_stage_function', None)
keep_stage = kwargs.get('keep_stage', False)

43
lib/spack/spack/cmd/create.py
View file

@ -451,10 +451,12 @@ def get_name(args):
If a name was provided, always use that. Otherwise, if a URL was
provided, extract the name from that. Otherwise, use a default.
:param argparse.Namespace args: The arguments given to ``spack create``
Args:
args (param argparse.Namespace): The arguments given to
``spack create``
:returns: The name of the package
:rtype: str
Returns:
str: The name of the package
"""
# Default package name
@ -487,10 +489,11 @@ def get_url(args):
Use a default URL if none is provided.
:param argparse.Namespace args: The arguments given to ``spack create``
Args:
args (argparse.Namespace): The arguments given to ``spack create``
:returns: The URL of the package
:rtype: str
Returns:
str: The URL of the package
"""
# Default URL
@ -510,11 +513,13 @@ def get_versions(args, name):
Returns default values if no URL is provided.
:param argparse.Namespace args: The arguments given to ``spack create``
:param str name: The name of the package
Args:
args (argparse.Namespace): The arguments given to ``spack create``
name (str): The name of the package
:returns: Versions and hashes, and a BuildSystemGuesser object
:rtype: str and BuildSystemGuesser
Returns:
str and BuildSystemGuesser: Versions and hashes, and a
BuildSystemGuesser object
"""
# Default version, hash, and guesser
@ -552,12 +557,13 @@ def get_build_system(args, guesser):
is provided, download the tarball and peek inside to guess what
build system it uses. Otherwise, use a generic template by default.
:param argparse.Namespace args: The arguments given to ``spack create``
:param BuildSystemGuesser guesser: The first_stage_function given to \
Args:
args (argparse.Namespace): The arguments given to ``spack create``
guesser (BuildSystemGuesser): The first_stage_function given to
``spack checksum`` which records the build system it detects
:returns: The name of the build system template to use
:rtype: str
Returns:
str: The name of the build system template to use
"""
# Default template
@ -584,11 +590,12 @@ def get_repository(args, name):
"""Returns a Repo object that will allow us to determine the path where
the new package file should be created.
:param argparse.Namespace args: The arguments given to ``spack create``
:param str name: The name of the package to create
Args:
args (argparse.Namespace): The arguments given to ``spack create``
name (str): The name of the package to create
:returns: A Repo object capable of determining the path to the package file
:rtype: Repo
Returns:
Repo: A Repo object capable of determining the path to the package file
"""
spec = Spec(name)
# Figure out namespace for spec

7
lib/spack/spack/cmd/edit.py
View file

@ -38,9 +38,10 @@
def edit_package(name, repo_path, namespace):
"""Opens the requested package file in your favorite $EDITOR.
:param str name: The name of the package
:param str repo_path: The path to the repository containing this package
:param str namespace: A valid namespace registered with Spack
Args:
name (str): The name of the package
repo_path (str): The path to the repository containing this package
namespace (str): A valid namespace registered with Spack
"""
# Find the location of the package
if repo_path:

48
lib/spack/spack/cmd/url.py
View file

@ -244,7 +244,8 @@ def print_name_and_version(url):
"""Prints a URL. Underlines the detected name with dashes and
the detected version with tildes.
:param str url: The url to parse
Args:
url (str): The url to parse
"""
name, ns, nl, ntup, ver, vs, vl, vtup = substitution_offsets(url)
underlines = [' '] * max(ns + nl, vs + vl)
@ -260,13 +261,15 @@ def print_name_and_version(url):
def url_list_parsing(args, urls, url, pkg):
"""Helper function for :func:`url_list`.
:param argparse.Namespace args: The arguments given to ``spack url list``
:param set urls: List of URLs that have already been added
:param url: A URL to potentially add to ``urls`` depending on ``args``
:type url: str or None
:param spack.package.PackageBase pkg: The Spack package
:returns: The updated ``urls`` list
:rtype: set
Args:
args (argparse.Namespace): The arguments given to ``spack url list``
urls (set): List of URLs that have already been added
url (str or None): A URL to potentially add to ``urls`` depending on
``args``
pkg (spack.package.PackageBase): The Spack package
Returns:
set: The updated set of ``urls``
"""
if url:
if args.correct_name or args.incorrect_name:
@ -310,10 +313,12 @@ def url_list_parsing(args, urls, url, pkg):
def name_parsed_correctly(pkg, name):
"""Determine if the name of a package was correctly parsed.
:param spack.package.PackageBase pkg: The Spack package
:param str name: The name that was extracted from the URL
:returns: True if the name was correctly parsed, else False
:rtype: bool
Args:
pkg (spack.package.PackageBase): The Spack package
name (str): The name that was extracted from the URL
Returns:
bool: True if the name was correctly parsed, else False
"""
pkg_name = pkg.name
@ -336,10 +341,12 @@ def name_parsed_correctly(pkg, name):
def version_parsed_correctly(pkg, version):
"""Determine if the version of a package was correctly parsed.
:param spack.package.PackageBase pkg: The Spack package
:param str version: The version that was extracted from the URL
:returns: True if the name was correctly parsed, else False
:rtype: bool
Args:
pkg (spack.package.PackageBase): The Spack package
version (str): The version that was extracted from the URL
Returns:
bool: True if the name was correctly parsed, else False
"""
version = remove_separators(version)
@ -359,10 +366,11 @@ def remove_separators(version):
Make sure 1.2.3, 1-2-3, 1_2_3, and 123 are considered equal.
Unfortunately, this also means that 1.23 and 12.3 are equal.
:param version: A version
:type version: str or Version
:returns: The version with all separator characters removed
:rtype: str
Args:
version (str or Version): A version
Returns:
str: The version with all separator characters removed
"""
version = str(version)

16
lib/spack/spack/directives.py
View file

@ -265,20 +265,22 @@ def _depends_on(pkg, spec, when=None, type=None):
@directive('conflicts')
def conflicts(conflict_spec, when=None):
"""Allows a package to define a conflict, i.e. a concretized configuration
that is known to be non-valid.
"""Allows a package to define a conflict.
For example a package that is known not to be buildable with intel
compilers can declare:
Currently, a "conflict" is a concretized configuration that is known
to be non-valid. For example, a package that is known not to be
buildable with intel compilers can declare::
conflicts('%intel')
To express the same constraint only when the 'foo' variant is activated:
To express the same constraint only when the 'foo' variant is
activated::
conflicts('%intel', when='+foo')
:param conflict_spec: constraint defining the known conflict
:param when: optional constraint that triggers the conflict
Args:
conflict_spec (Spec): constraint defining the known conflict
when (Spec): optional constraint that triggers the conflict
"""
def _execute(pkg):
# If when is not specified the conflict always holds

13
lib/spack/spack/environment.py
View file

@ -262,12 +262,15 @@ def apply_modifications(self):
@staticmethod
def from_sourcing_files(*args, **kwargs):
"""Creates an instance of EnvironmentModifications that, if executed,
has the same effect on the environment as sourcing the files passed as
parameters
"""Returns modifications that would be made by sourcing files.
:param \*args: list of files to be sourced
:rtype: instance of EnvironmentModifications
Args:
*args (list of str): list of files to be sourced
Returns:
EnvironmentModifications: an object that, if executed, has
the same effect on the environment as sourcing the files
passed as parameters
"""
env = EnvironmentModifications()

15
lib/spack/spack/fetch_strategy.py
View file

@ -911,11 +911,18 @@ def from_url(url):
def from_kwargs(**kwargs):
"""
Construct the appropriate FetchStrategy from the given keyword arguments.
"""Construct an appropriate FetchStrategy from the given keyword arguments.
:param kwargs: dictionary of keyword arguments
:return: fetcher or raise a FetchError exception
Args:
**kwargs: dictionary of keyword arguments, e.g. from a
``version()`` directive in a package.
Returns:
fetch_strategy: The fetch strategy that matches the args, based
on attribute names (e.g., ``git``, ``hg``, etc.)
Raises:
FetchError: If no ``fetch_strategy`` matches the args.
"""
for fetcher in all_strategies:
if fetcher.matches(kwargs):

9
lib/spack/spack/mirror.py
View file

@ -117,13 +117,10 @@ def get_matching_versions(specs, **kwargs):
def suggest_archive_basename(resource):
"""
Return a tentative basename for an archive.
"""Return a tentative basename for an archive.
Raises an exception if the name is not an allowed archive type.
:param fetcher:
:return:
Raises:
RuntimeError: if the name is not an allowed archive type.
"""
basename = os.path.basename(resource.fetcher.url)
if not allowed_archive(basename):

63
lib/spack/spack/package.py
View file

@ -73,7 +73,7 @@
class InstallPhase(object):
"""Manages a single phase of the installation
"""Manages a single phase of the installation.
This descriptor stores at creation time the name of the method it should
search for execution. The method is retrieved at __get__ time, so that
@ -214,10 +214,13 @@ def run_after(*phases):
def on_package_attributes(**attr_dict):
"""Executes the decorated method only if at the moment of calling
the instance has attributes that are equal to certain values.
"""Decorator: executes instance function only if object has attr valuses.
:param dict attr_dict: dictionary mapping attribute names to their
Executes the decorated method only if at the moment of calling the
instance has attributes that are equal to certain values.
Args:
attr_dict (dict): dictionary mapping attribute names to their
required values
"""
def _execute_under_condition(func):
@ -1082,12 +1085,14 @@ def _stage_and_write_lock(self):
yield
def _process_external_package(self, explicit):
"""Helper function to process external packages. It runs post install
hooks and registers the package in the DB.
"""Helper function to process external packages.
:param bool explicit: True if the package was requested explicitly by
the user, False if it was pulled in as a dependency of an explicit
package.
Runs post install hooks and registers the package in the DB.
Args:
explicit (bool): if the package was requested explicitly by
the user, False if it was pulled in as a dependency of an
explicit package.
"""
if self.spec.external_module:
message = '{s.name}@{s.version} : has external module in {module}'
@ -1143,24 +1148,25 @@ def do_install(self,
Package implementations should override install() to describe
their build process.
:param bool keep_prefix: Keep install prefix on failure. By default,
Args:
keep_prefix (bool): Keep install prefix on failure. By default,
destroys it.
:param bool keep_stage: By default, stage is destroyed only if there
keep_stage (bool): By default, stage is destroyed only if there
are no exceptions during build. Set to True to keep the stage
even with exceptions.
:param bool install_deps: Install dependencies before installing this
install_deps (bool): Install dependencies before installing this
package
:param bool skip_patch: Skip patch stage of build if True.
:param bool verbose: Display verbose build output (by default,
skip_patch (bool): Skip patch stage of build if True.
verbose (bool): Display verbose build output (by default,
suppresses it)
:param int make_jobs: Number of make jobs to use for install. Default
make_jobs (int): Number of make jobs to use for install. Default
is ncpus
:param bool run_tests: Run tests within the package's install()
:param bool fake: Don't really build; install fake stub files instead.
:param bool explicit: True if package was explicitly installed, False
run_tests (bool): Run tests within the package's install()
fake (bool): Don't really build; install fake stub files instead.
explicit (bool): True if package was explicitly installed, False
if package was implicitly installed (as a dependency).
:param bool dirty: Don't clean the build environment before installing.
:param bool force: Install again, even if already installed.
dirty (bool): Don't clean the build environment before installing.
force (bool): Install again, even if already installed.
"""
if not self.spec.concrete:
raise ValueError("Can only install concrete packages: %s."
@ -1423,10 +1429,11 @@ def setup_environment(self, spack_env, run_env):
1. Qt extensions need ``QTDIR`` set.
:param EnvironmentModifications spack_env: List of environment
Args:
spack_env (EnvironmentModifications): List of environment
modifications to be applied when this package is built
within Spack.
:param EnvironmentModifications run_env: List of environment
run_env (EnvironmentModifications): List of environment
modifications to be applied when this package is run outside
of Spack. These are added to the resulting module file.
"""
@ -1450,14 +1457,15 @@ def setup_dependent_environment(self, spack_env, run_env, dependent_spec):
to the ``lib/pythonX.Y/site-packages`` directory in the module's
install prefix. This method could be used to set that variable.
:param EnvironmentModifications spack_env: List of environment
Args:
spack_env (EnvironmentModifications): List of environment
modifications to be applied when the dependent package is
built within Spack.
:param EnvironmentModifications run_env: List of environment
run_env (EnvironmentModifications): List of environment
modifications to be applied when the dependent package is
run outside of Spack. These are added to the resulting
module file.
:param Spec dependent_spec: The spec of the dependent package
dependent_spec (Spec): The spec of the dependent package
about to be built. This allows the extendee (self) to query
the dependent's state. Note that *this* package's spec is
available as ``self.spec``.
@ -1489,11 +1497,12 @@ def setup_dependent_package(self, module, dependent_spec):
indicating the path to their libraries, since these
paths differ by BLAS/LAPACK implementation.
:param spack.package.PackageBase.module module: The Python ``module``
Args:
module (spack.package.PackageBase.module): The Python ``module``
object of the dependent package. Packages can use this to set
module-scope variables for the dependent to use.
:param Spec dependent_spec: The spec of the dependent package
dependent_spec (Spec): The spec of the dependent package
about to be built. This allows the extendee (self) to
query the dependent's state. Note that *this*
package's spec is available as ``self.spec``.

40
lib/spack/spack/spec.py
View file

@ -758,32 +758,35 @@ def __str__(self):
def _libs_default_handler(descriptor, spec, cls):
"""Default handler when looking for 'libs' attribute. The default
tries to search for 'lib{spec.name}' recursively starting from
"""Default handler when for ``libs`` attribute in Spec interface.
Tries to search for ``lib{spec.name}`` recursively starting from
`spec.prefix`.
:param ForwardQueryToPackage descriptor: descriptor that triggered
Args:
descriptor (ForwardQueryToPackage): descriptor that triggered
the call
:param Spec spec: spec that is being queried
:param type(spec) cls: type of spec, to match the signature of the
spec (Spec): spec that is being queried
cls (type(spec)): type of spec, to match the signature of the
descriptor `__get__` method
"""
name = 'lib' + spec.name
shared = '+shared' in spec
return find_libraries(
name, root=spec.prefix, shared=shared, recurse=True
)
return find_libraries(name, root=spec.prefix, shared=shared, recurse=True)
def _cppflags_default_handler(descriptor, spec, cls):
"""Default handler when looking for cppflags attribute. The default
just returns '-I{spec.prefix.include}'.
"""Default handler for the ``cppflags`` attribute in the Spec interface.
:param ForwardQueryToPackage descriptor: descriptor that triggered
The default just returns ``-I{spec.prefix.include}``.
Args:
descriptor (ForwardQueryToPackage): descriptor that triggered
the call
:param Spec spec: spec that is being queried
:param type(spec) cls: type of spec, to match the signature of the
descriptor `__get__` method
spec (Spec): spec that is being queried
cls (type(spec)): type of spec, to match the signature of the
descriptor ``__get__`` method
"""
return '-I' + spec.prefix.include
@ -792,12 +795,13 @@ class ForwardQueryToPackage(object):
"""Descriptor used to forward queries from Spec to Package"""
def __init__(self, attribute_name, default_handler=None):
"""Initializes the instance of the descriptor
"""Create a new descriptor.
:param str attribute_name: name of the attribute to be
Args:
attribute_name (str): name of the attribute to be
searched for in the Package instance
:param callable default_handler: [optional] default function
to be called if the attribute was not found in the Package
default_handler (callable, optional): default function to be
called if the attribute was not found in the Package
instance
"""
self.attribute_name = attribute_name

10
lib/spack/spack/test/modules.py
View file

@ -63,10 +63,12 @@ def _mock(filename, mode):
def get_modulefile_content(factory, spec):
"""Writes the module file and returns the content as a string.
:param factory: module file factory
:param spec: spec of the module file to be written
:return: content of the module file
:rtype: str
Args:
factory: module file factory
spec: spec of the module file to be written
Returns:
str: content of the module file
"""
spec.concretize()
generator = factory(spec)

9
lib/spack/spack/test/python_version.py
View file

@ -67,9 +67,12 @@
def pyfiles(search_paths, exclude=()):
"""Generator that yields all the python files in the search paths.
:param search_paths: list of paths to search for python files
:param exclude: file paths to exclude from search
:return: python files
Args:
search_paths (list of str): list of paths to search for python files
exclude (list of str): file paths to exclude from search
Yields:
python files in the search path.
"""
# first file is the spack script.
yield spack.spack_file

84
lib/spack/spack/url.py
View file

@ -116,9 +116,11 @@ def strip_version_suffixes(path):
* ``libevent-2.0.21``
* ``cuda_8.0.44``
:param str path: The filename or URL for the package
:return: The ``path`` with any extraneous suffixes removed
:rtype: str
Args:
path (str): The filename or URL for the package
Returns:
str: The ``path`` with any extraneous suffixes removed
"""
# NOTE: This could be done with complicated regexes in parse_version_offset
# NOTE: The problem is that we would have to add these regexes to the end
@ -227,10 +229,12 @@ def strip_name_suffixes(path, version):
* ``converge``
* ``jpeg``
:param str path: The filename or URL for the package
:param str version: The version detected for this URL
:return: The ``path`` with any extraneous suffixes removed
:rtype: str
Args:
path (str): The filename or URL for the package
version (str): The version detected for this URL
Returns:
str: The ``path`` with any extraneous suffixes removed
"""
# NOTE: This could be done with complicated regexes in parse_name_offset
# NOTE: The problem is that we would have to add these regexes to every
@ -339,18 +343,19 @@ def determine_url_file_extension(path):
def parse_version_offset(path):
"""Try to extract a version string from a filename or URL.
:param str path: The filename or URL for the package
Args:
path (str): The filename or URL for the package
:return: A tuple containing:
Returns:
tuple of (Version, int, int, int, str): A tuple containing:
version of the package,
first index of version,
length of version string,
the index of the matching regex
the matching regex
:rtype: tuple
:raises UndetectableVersionError: If the URL does not match any regexes
Raises:
UndetectableVersionError: If the URL does not match any regexes
"""
original_path = path
@ -524,12 +529,14 @@ def parse_version_offset(path):
def parse_version(path):
"""Try to extract a version string from a filename or URL.
:param str path: The filename or URL for the package
Args:
path (str): The filename or URL for the package
:return: The version of the package
:rtype: spack.version.Version
Returns:
spack.version.Version: The version of the package
:raises UndetectableVersionError: If the URL does not match any regexes
Raises:
UndetectableVersionError: If the URL does not match any regexes
"""
version, start, length, i, regex = parse_version_offset(path)
return Version(version)
@ -538,19 +545,20 @@ def parse_version(path):
def parse_name_offset(path, v=None):
"""Try to determine the name of a package from its filename or URL.
:param str path: The filename or URL for the package
:param str v: The version of the package
Args:
path (str): The filename or URL for the package
v (str): The version of the package
:return: A tuple containing:
Returns:
tuple of (str, int, int, int, str): A tuple containing:
name of the package,
first index of name,
length of name,
the index of the matching regex
the matching regex
:rtype: tuple
:raises UndetectableNameError: If the URL does not match any regexes
Raises:
UndetectableNameError: If the URL does not match any regexes
"""
original_path = path
@ -651,13 +659,15 @@ def parse_name_offset(path, v=None):
def parse_name(path, ver=None):
"""Try to determine the name of a package from its filename or URL.
:param str path: The filename or URL for the package
:param str ver: The version of the package
Args:
path (str): The filename or URL for the package
ver (str): The version of the package
:return: The name of the package
:rtype: str
Returns:
str: The name of the package
:raises UndetectableNameError: If the URL does not match any regexes
Raises:
UndetectableNameError: If the URL does not match any regexes
"""
name, start, length, i, regex = parse_name_offset(path, ver)
return name
@ -667,16 +677,17 @@ def parse_name_and_version(path):
"""Try to determine the name of a package and extract its version
from its filename or URL.
:param str path: The filename or URL for the package
Args:
path (str): The filename or URL for the package
:return: A tuple containing:
Returns:
tuple of (str, Version)A tuple containing:
The name of the package
The version of the package
:rtype: tuple
:raises UndetectableVersionError: If the URL does not match any regexes
:raises UndetectableNameError: If the URL does not match any regexes
Raises:
UndetectableVersionError: If the URL does not match any regexes
UndetectableNameError: If the URL does not match any regexes
"""
ver = parse_version(path)
name = parse_name(path, ver)
@ -804,9 +815,10 @@ def color_url(path, **kwargs):
| Green: Instances of version string from :func:`substitute_version`.
| Magenta: Instances of the name (protected from substitution).
:param str path: The filename or URL for the package
:keyword bool errors: Append parse errors at end of string.
:keyword bool subs: Color substitutions as well as parsed name/version.
Args:
path (str): The filename or URL for the package
errors (bool): Append parse errors at end of string.
subs (bool): Color substitutions as well as parsed name/version.
"""
errors = kwargs.get('errors', False)
subs = kwargs.get('subs', False)

12
lib/spack/spack/util/naming.py
View file

@ -110,13 +110,17 @@ def possible_spack_module_names(python_mod_name):
def simplify_name(name):
"""Simplifies a name which may include uppercase letters, periods,
"""Simplify package name to only lowercase, digits, and dashes.
Simplifies a name which may include uppercase letters, periods,
underscores, and pluses. In general, we want our package names to
only contain lowercase letters, digits, and dashes.
:param str name: The original name of the package
:return: The new name of the package
:rtype: str
Args:
name (str): The original name of the package
Returns:
str: The new name of the package
"""
# Convert CamelCase to Dashed-Names
# e.g. ImageMagick -> Image-Magick

27
lib/spack/spack/util/pattern.py
View file

@ -28,20 +28,23 @@
def composite(interface=None, method_list=None, container=list):
"""Returns a class decorator that patches a class adding all the methods
"""Decorator implementing the GoF composite pattern.
Args:
interface (type): class exposing the interface to which the
composite object must conform. Only non-private and
non-special methods will be taken into account
method_list (list of str): names of methods that should be part
of the composite
container (MutableSequence): container for the composite object
(default = list). Must fulfill the MutableSequence
contract. The composite class will expose the container API
to manage object composition
Returns:
a class decorator that patches a class adding all the methods
it needs to be a composite for a given interface.
:param interface: class exposing the interface to which the composite \
object must conform. Only non-private and non-special methods will \
be taken into account
:param method_list: names of methods that should be part of the composite
:param container: container for the composite object (default = list). \
Must fulfill the MutableSequence contract. The composite class will \
expose the container API to manage object composition
:return: class decorator
"""
# Check if container fulfills the MutableSequence contract and raise an
# exception if it doesn't. The patched class returned by the decorator will