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

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

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

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

@ -438,12 +438,17 @@ def get_rpaths(pkg):
def get_std_cmake_args(pkg): def get_std_cmake_args(pkg):
"""Returns the list of standard arguments that would be used if this """List of standard arguments used if a package is a CMakePackage.
package was a CMakePackage instance.
: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) return spack.CMakePackage._std_args(pkg)
@ -465,10 +470,13 @@ def parent_class_modules(cls):
def load_external_modules(pkg): def load_external_modules(pkg):
"""Traverse the spec list associated with a package """Traverse a package's spec DAG and load any external modules.
and find any specs that have 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()): for dep in list(pkg.spec.traverse()):
if dep.external_module: if dep.external_module:
@ -531,25 +539,29 @@ def setup_package(pkg, dirty=False):
def fork(pkg, function, dirty=False): def fork(pkg, function, dirty=False):
"""Fork a child process to do part of a spack build. """Fork a child process to do part of a spack build.
:param pkg: pkg whose environemnt we should set up the forked process for. Args:
:param function: arg-less function to run in the child process.
:param dirty: If True, do NOT clean the environment before building. 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:: Usage::
def child_fun(): def child_fun():
# do stuff # do stuff
build_env.fork(pkg, child_fun) build_env.fork(pkg, child_fun)
Forked processes are run with the build environment set up by Forked processes are run with the build environment set up by
spack.build_environment. This allows package authors to have spack.build_environment. This allows package authors to have full
full control over the environment, etc. without affecting control over the environment, etc. without affecting other builds
other builds that might be executed in the same spack call. that might be executed in the same spack call.
If something goes wrong, the child process is expected to print If something goes wrong, the child process is expected to print the
the error and the parent process will exit with error as error and the parent process will exit with error as well. If things
well. If things go well, the child exits and the parent go well, the child exits and the parent carries on.
carries on.
""" """
def child_execution(child_connection, input_stream): 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): def _setup_command_available(self, command):
"""Determines whether or not a setup.py command exists. """Determines whether or not a setup.py command exists.
:param str command: The command to look for Args:
:return: True if the command is found, else False command (str): The command to look for
:rtype: bool
Returns:
bool: True if the command is found, else False
""" """
kwargs = { kwargs = {
'output': os.devnull, '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 The ``first_stage_function`` kwarg allows ``spack create`` to determine
things like the build system of the archive. things like the build system of the archive.
:param dict url_dict: A dictionary of the form: version -> URL Args:
:param str name: The name of the package url_dict (dict): A dictionary of the form: version -> URL
:param callable first_stage_function: Function to run on first staging area name (str): The name of the package
:param bool keep_stage: Don't clean up staging area when command completes 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 Returns:
:rtype: str str: A multi-line string containing versions and corresponding hashes
""" """
first_stage_function = kwargs.get('first_stage_function', None) first_stage_function = kwargs.get('first_stage_function', None)
keep_stage = kwargs.get('keep_stage', False) keep_stage = kwargs.get('keep_stage', False)

45
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 If a name was provided, always use that. Otherwise, if a URL was
provided, extract the name from that. Otherwise, use a default. 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 Returns:
:rtype: str str: The name of the package
""" """
# Default package name # Default package name
@ -487,10 +489,11 @@ def get_url(args):
Use a default URL if none is provided. 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 Returns:
:rtype: str str: The URL of the package
""" """
# Default URL # Default URL
@ -510,11 +513,13 @@ def get_versions(args, name):
Returns default values if no URL is provided. Returns default values if no URL is provided.
:param argparse.Namespace args: The arguments given to ``spack create`` Args:
:param str name: The name of the package args (argparse.Namespace): The arguments given to ``spack create``
name (str): The name of the package
:returns: Versions and hashes, and a BuildSystemGuesser object Returns:
:rtype: str and BuildSystemGuesser str and BuildSystemGuesser: Versions and hashes, and a
BuildSystemGuesser object
""" """
# Default version, hash, and guesser # 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 is provided, download the tarball and peek inside to guess what
build system it uses. Otherwise, use a generic template by default. build system it uses. Otherwise, use a generic template by default.
:param argparse.Namespace args: The arguments given to ``spack create`` Args:
:param BuildSystemGuesser guesser: The first_stage_function given to \ args (argparse.Namespace): The arguments given to ``spack create``
``spack checksum`` which records the build system it detects 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 Returns:
:rtype: str str: The name of the build system template to use
""" """
# Default template # Default template
@ -584,11 +590,12 @@ def get_repository(args, name):
"""Returns a Repo object that will allow us to determine the path where """Returns a Repo object that will allow us to determine the path where
the new package file should be created. the new package file should be created.
:param argparse.Namespace args: The arguments given to ``spack create`` Args:
:param str name: The name of the package to create 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 Returns:
:rtype: Repo Repo: A Repo object capable of determining the path to the package file
""" """
spec = Spec(name) spec = Spec(name)
# Figure out namespace for spec # 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): def edit_package(name, repo_path, namespace):
"""Opens the requested package file in your favorite $EDITOR. """Opens the requested package file in your favorite $EDITOR.
:param str name: The name of the package Args:
:param str repo_path: The path to the repository containing this package name (str): The name of the package
:param str namespace: A valid namespace registered with Spack 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 # Find the location of the package
if repo_path: 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 """Prints a URL. Underlines the detected name with dashes and
the detected version with tildes. 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) name, ns, nl, ntup, ver, vs, vl, vtup = substitution_offsets(url)
underlines = [' '] * max(ns + nl, vs + vl) underlines = [' '] * max(ns + nl, vs + vl)
@ -260,13 +261,15 @@ def print_name_and_version(url):
def url_list_parsing(args, urls, url, pkg): def url_list_parsing(args, urls, url, pkg):
"""Helper function for :func:`url_list`. """Helper function for :func:`url_list`.
:param argparse.Namespace args: The arguments given to ``spack url list`` Args:
:param set urls: List of URLs that have already been added args (argparse.Namespace): The arguments given to ``spack url list``
:param url: A URL to potentially add to ``urls`` depending on ``args`` urls (set): List of URLs that have already been added
:type url: str or None url (str or None): A URL to potentially add to ``urls`` depending on
:param spack.package.PackageBase pkg: The Spack package ``args``
:returns: The updated ``urls`` list pkg (spack.package.PackageBase): The Spack package
:rtype: set
Returns:
set: The updated set of ``urls``
""" """
if url: if url:
if args.correct_name or args.incorrect_name: 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): def name_parsed_correctly(pkg, name):
"""Determine if the name of a package was correctly parsed. """Determine if the name of a package was correctly parsed.
:param spack.package.PackageBase pkg: The Spack package Args:
:param str name: The name that was extracted from the URL pkg (spack.package.PackageBase): The Spack package
:returns: True if the name was correctly parsed, else False name (str): The name that was extracted from the URL
:rtype: bool
Returns:
bool: True if the name was correctly parsed, else False
""" """
pkg_name = pkg.name pkg_name = pkg.name
@ -336,10 +341,12 @@ def name_parsed_correctly(pkg, name):
def version_parsed_correctly(pkg, version): def version_parsed_correctly(pkg, version):
"""Determine if the version of a package was correctly parsed. """Determine if the version of a package was correctly parsed.
:param spack.package.PackageBase pkg: The Spack package Args:
:param str version: The version that was extracted from the URL pkg (spack.package.PackageBase): The Spack package
:returns: True if the name was correctly parsed, else False version (str): The version that was extracted from the URL
:rtype: bool
Returns:
bool: True if the name was correctly parsed, else False
""" """
version = remove_separators(version) 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. 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. Unfortunately, this also means that 1.23 and 12.3 are equal.
:param version: A version Args:
:type version: str or Version version (str or Version): A version
:returns: The version with all separator characters removed
:rtype: str Returns:
str: The version with all separator characters removed
""" """
version = str(version) version = str(version)

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

@ -265,20 +265,22 @@ def _depends_on(pkg, spec, when=None, type=None):
@directive('conflicts') @directive('conflicts')
def conflicts(conflict_spec, when=None): def conflicts(conflict_spec, when=None):
"""Allows a package to define a conflict, i.e. a concretized configuration """Allows a package to define a conflict.
that is known to be non-valid.
For example a package that is known not to be buildable with intel Currently, a "conflict" is a concretized configuration that is known
compilers can declare: to be non-valid. For example, a package that is known not to be
buildable with intel compilers can declare::
conflicts('%intel') 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') conflicts('%intel', when='+foo')
:param conflict_spec: constraint defining the known conflict Args:
:param when: optional constraint that triggers the conflict conflict_spec (Spec): constraint defining the known conflict
when (Spec): optional constraint that triggers the conflict
""" """
def _execute(pkg): def _execute(pkg):
# If when is not specified the conflict always holds # 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 @staticmethod
def from_sourcing_files(*args, **kwargs): def from_sourcing_files(*args, **kwargs):
"""Creates an instance of EnvironmentModifications that, if executed, """Returns modifications that would be made by sourcing files.
has the same effect on the environment as sourcing the files passed as
parameters
:param \*args: list of files to be sourced Args:
:rtype: instance of EnvironmentModifications *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() env = EnvironmentModifications()

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

@ -911,11 +911,18 @@ def from_url(url):
def from_kwargs(**kwargs): def from_kwargs(**kwargs):
""" """Construct an appropriate FetchStrategy from the given keyword arguments.
Construct the appropriate FetchStrategy from the given keyword arguments.
:param kwargs: dictionary of keyword arguments Args:
:return: fetcher or raise a FetchError exception **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: for fetcher in all_strategies:
if fetcher.matches(kwargs): 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): 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. Raises:
RuntimeError: if the name is not an allowed archive type.
:param fetcher:
:return:
""" """
basename = os.path.basename(resource.fetcher.url) basename = os.path.basename(resource.fetcher.url)
if not allowed_archive(basename): if not allowed_archive(basename):

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

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

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

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

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

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

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

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

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

@ -116,9 +116,11 @@ def strip_version_suffixes(path):
* ``libevent-2.0.21`` * ``libevent-2.0.21``
* ``cuda_8.0.44`` * ``cuda_8.0.44``
:param str path: The filename or URL for the package Args:
:return: The ``path`` with any extraneous suffixes removed path (str): The filename or URL for the package
:rtype: str
Returns:
str: The ``path`` with any extraneous suffixes removed
""" """
# NOTE: This could be done with complicated regexes in parse_version_offset # 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 # 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`` * ``converge``
* ``jpeg`` * ``jpeg``
:param str path: The filename or URL for the package Args:
:param str version: The version detected for this URL path (str): The filename or URL for the package
:return: The ``path`` with any extraneous suffixes removed version (str): The version detected for this URL
:rtype: str
Returns:
str: The ``path`` with any extraneous suffixes removed
""" """
# NOTE: This could be done with complicated regexes in parse_name_offset # 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 # 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): def parse_version_offset(path):
"""Try to extract a version string from a filename or URL. """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:
version of the package, tuple of (Version, int, int, int, str): A tuple containing:
first index of version, version of the package,
length of version string, first index of version,
the index of the matching regex length of version string,
the matching regex 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 original_path = path
@ -524,12 +529,14 @@ def parse_version_offset(path):
def parse_version(path): def parse_version(path):
"""Try to extract a version string from a filename or URL. """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 Returns:
:rtype: spack.version.Version 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) version, start, length, i, regex = parse_version_offset(path)
return Version(version) return Version(version)
@ -538,19 +545,20 @@ def parse_version(path):
def parse_name_offset(path, v=None): def parse_name_offset(path, v=None):
"""Try to determine the name of a package from its filename or URL. """Try to determine the name of a package from its filename or URL.
:param str path: The filename or URL for the package Args:
:param str v: The version of the package path (str): The filename or URL for the package
v (str): The version of the package
:return: A tuple containing: Returns:
name of the package, tuple of (str, int, int, int, str): A tuple containing:
first index of name, name of the package,
length of name, first index of name,
the index of the matching regex length of name,
the matching regex 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 original_path = path
@ -651,13 +659,15 @@ def parse_name_offset(path, v=None):
def parse_name(path, ver=None): def parse_name(path, ver=None):
"""Try to determine the name of a package from its filename or URL. """Try to determine the name of a package from its filename or URL.
:param str path: The filename or URL for the package Args:
:param str ver: The version of the package path (str): The filename or URL for the package
ver (str): The version of the package
:return: The name of the package Returns:
:rtype: str 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) name, start, length, i, regex = parse_name_offset(path, ver)
return name return name
@ -667,16 +677,17 @@ def parse_name_and_version(path):
"""Try to determine the name of a package and extract its version """Try to determine the name of a package and extract its version
from its filename or URL. 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:
The name of the package tuple of (str, Version)A tuple containing:
The version of the package The name of the package
The version of the package
:rtype: tuple Raises:
UndetectableVersionError: 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
:raises UndetectableNameError: If the URL does not match any regexes
""" """
ver = parse_version(path) ver = parse_version(path)
name = parse_name(path, ver) name = parse_name(path, ver)
@ -804,9 +815,10 @@ def color_url(path, **kwargs):
| Green: Instances of version string from :func:`substitute_version`. | Green: Instances of version string from :func:`substitute_version`.
| Magenta: Instances of the name (protected from substitution). | Magenta: Instances of the name (protected from substitution).
:param str path: The filename or URL for the package Args:
:keyword bool errors: Append parse errors at end of string. path (str): The filename or URL for the package
:keyword bool subs: Color substitutions as well as parsed name/version. errors (bool): Append parse errors at end of string.
subs (bool): Color substitutions as well as parsed name/version.
""" """
errors = kwargs.get('errors', False) errors = kwargs.get('errors', False)
subs = kwargs.get('subs', 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): 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 underscores, and pluses. In general, we want our package names to
only contain lowercase letters, digits, and dashes. only contain lowercase letters, digits, and dashes.
:param str name: The original name of the package Args:
:return: The new name of the package name (str): The original name of the package
:rtype: str
Returns:
str: The new name of the package
""" """
# Convert CamelCase to Dashed-Names # Convert CamelCase to Dashed-Names
# e.g. ImageMagick -> Image-Magick # e.g. ImageMagick -> Image-Magick

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

@ -28,20 +28,23 @@
def composite(interface=None, method_list=None, container=list): 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.
it needs to be a composite for a given interface.
:param interface: class exposing the interface to which the composite \ Args:
object must conform. Only non-private and non-special methods will \ interface (type): class exposing the interface to which the
be taken into account 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
:param method_list: names of methods that should be part of the composite Returns:
a class decorator that patches a class adding all the methods
it needs to be a composite for a given interface.
: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 # Check if container fulfills the MutableSequence contract and raise an
# exception if it doesn't. The patched class returned by the decorator will # exception if it doesn't. The patched class returned by the decorator will