From 30c9609c4e04e5768ad3ec22d738c73954864e27 Mon Sep 17 00:00:00 2001 From: Greg Becker Date: Wed, 30 Oct 2019 18:47:48 -0500 Subject: Documentation: Database.query methods share docstrings (#13515) 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. --- lib/spack/spack/database.py | 94 +++++++++++++++++++++++++-------------------- 1 file changed, 53 insertions(+), 41 deletions(-) (limited to 'lib') diff --git a/lib/spack/spack/database.py b/lib/spack/spack/database.py index a1748fc585..e6e82f9803 100644 --- a/lib/spack/spack/database.py +++ b/lib/spack/spack/database.py @@ -206,6 +206,50 @@ class ForbiddenLock(object): "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 @@ class Database(object): 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 @@ class Database(object): 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 @@ class Database(object): 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. -- cgit v1.2.3-70-g09d2