zhangyiss/spack
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Documentation: Database.query methods share docstrings (#13515)

Browse Source 
Currently, query arguments in the Spack core are documented on the
Database._query method, where the functionality is defined.

For users of the spack python command, this makes the python builtin
method help less than ideally useful, as help(spack.store.db.query)
and help(spack.store.db.query_local) do not show relevant information.

This PR updates the doc attributes for the Database.query and
Database.query_local arguments to mirror everything after the first
line of the Database._query docstring.
This commit is contained in:
Greg Becker 2019-10-30 18:47:48 -05:00 committed by Peter Scheibel
parent 230c6aa326
commit a97faeb3c7
1 changed files with 53 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

94
lib/spack/spack/database.py
View File

@ -206,6 +206,50 @@ def __getattribute__(self, name):
"Cannot access attribute '{0}' of lock".format(name))
_query_docstring = """
Args:
query_spec: queries iterate through specs in the database and
return those that satisfy the supplied ``query_spec``. If
query_spec is `any`, This will match all specs in the
database. If it is a spec, we'll evaluate
``spec.satisfies(query_spec)``
known (bool or any, optional): Specs that are "known" are those
for which Spack can locate a ``package.py`` file -- i.e.,
Spack "knows" how to install them. Specs that are unknown may
represent packages that existed in a previous version of
Spack, but have since either changed their name or
been removed
installed (bool or any, or InstallStatus or iterable of
InstallStatus, optional): if ``True``, includes only installed
specs in the search; if ``False`` only missing specs, and if
``any``, all specs in database. If an InstallStatus or iterable
of InstallStatus, returns specs whose install status
(installed, deprecated, or missing) matches (one of) the
InstallStatus. (default: True)
explicit (bool or any, optional): A spec that was installed
following a specific user request is marked as explicit. If
instead it was pulled-in as a dependency of a user requested
spec it's considered implicit.
start_date (datetime, optional): filters the query discarding
specs that have been installed before ``start_date``.
end_date (datetime, optional): filters the query discarding
specs that have been installed after ``end_date``.
hashes (container): list or set of hashes that we can use to
restrict the search
Returns:
list of specs that match the query
"""
class Database(object):
"""Per-process lock objects for each install prefix."""
@ -1158,48 +1202,8 @@ def _query(
end_date=None,
hashes=None
):
"""Run a query on the database
"""Run a query on the database."""
Args:
query_spec: queries iterate through specs in the database and
return those that satisfy the supplied ``query_spec``. If
query_spec is `any`, This will match all specs in the
database. If it is a spec, we'll evaluate
``spec.satisfies(query_spec)``
known (bool or any, optional): Specs that are "known" are those
for which Spack can locate a ``package.py`` file -- i.e.,
Spack "knows" how to install them. Specs that are unknown may
represent packages that existed in a previous version of
Spack, but have since either changed their name or
been removed
installed (bool or any, or InstallStatus or iterable of
InstallStatus, optional): if ``True``, includes only installed
specs in the search; if ``False`` only missing specs, and if
``any``, all specs in database. If an InstallStatus or iterable
of InstallStatus, returns specs whose install status
(installed, deprecated, or missing) matches (one of) the
InstallStatus. (default: True)
explicit (bool or any, optional): A spec that was installed
following a specific user request is marked as explicit. If
instead it was pulled-in as a dependency of a user requested
spec it's considered implicit.
start_date (datetime, optional): filters the query discarding
specs that have been installed before ``start_date``.
end_date (datetime, optional): filters the query discarding
specs that have been installed after ``end_date``.
hashes (container): list or set of hashes that we can use to
restrict the search
Returns:
list of specs that match the query
"""
# TODO: Specs are a lot like queries. Should there be a
# TODO: wildcard spec object, and should specs have attributes
# TODO: like installed and known that can be queried? Or are
@ -1246,11 +1250,17 @@ def _query(
return results
_query.__doc__ += _query_docstring
def query_local(self, *args, **kwargs):
"""Query only the local Spack database."""
with self.read_transaction():
return sorted(self._query(*args, **kwargs))
query_local.__doc__ += _query_docstring
def query(self, *args, **kwargs):
"""Query the Spack database including all upstream databases."""
upstream_results = []
for upstream_db in self.upstream_dbs:
# queries for upstream DBs need to *not* lock - we may not
@ -1265,6 +1275,8 @@ def query(self, *args, **kwargs):
return sorted(results)
query.__doc__ += _query_docstring
def query_one(self, query_spec, known=any, installed=True):
"""Query for exactly one spec that matches the query spec.