Merge branch 'fix-docstrings' into 'main'

Fix docstring issues

See merge request computing/gwdatafind/client!68

gwdatafind/__main__.py

@@ -36,11 +36,19 @@ __credits__ = 'Scott Koranda, The LIGO Scientific Collaboration'
 # -- command line parsing -----------------------------------------------------
 
 class DataFindArgumentParser(argparse.ArgumentParser):
+    """Custom `~argparse.ArgumentParser` for GWDataFind.
+
+    Mainly to handle the legacy mutually-exclusive optional arguments...
+    """
     def __init__(self, *args, **kwargs):
+        """Create a new `DataFindArgumentParser`.
+        """
         super(DataFindArgumentParser, self).__init__(*args, **kwargs)
         self._optionals.title = "Optional arguments"
 
     def parse_args(self, *args, **kwargs):
+        """Parse arguments with an extra sanity check.
+        """
         args = super(DataFindArgumentParser, self).parse_args(*args, **kwargs)
         args.show_urls = not any((args.ping, args.show_observatories,
                                   args.show_types, args.show_times,
@@ -49,7 +57,7 @@ class DataFindArgumentParser(argparse.ArgumentParser):
         return args
 
     def sanity_check(self, namespace):
-        """Sanity check parsed command line options
+        """Sanity check parsed command line options.
 
         If any problems are found `argparse.ArgumentParser.error` is called,
         which in turn calls :func:`sys.exit`.
@@ -79,7 +87,7 @@ class DataFindArgumentParser(argparse.ArgumentParser):
 
 
 def command_line():
-    """Build an `~argparse.ArgumentParser` for the `gwdatafind` CLI
+    """Build an `~argparse.ArgumentParser` for the `gwdatafind` CLI.
     """
     try:
         defhost = get_default_host()
@@ -192,7 +200,7 @@ def ping(args, out):
 
 
 def show_observatories(args, out):
-    """Worker for the --show-observatories option
+    """Worker for the --show-observatories option.
 
     Parameters
     ----------
@@ -212,7 +220,7 @@ def show_observatories(args, out):
 
 
 def show_types(args, out):
-    """Worker for the --show-types option
+    """Worker for the --show-types option.
 
     Parameters
     ----------
@@ -233,7 +241,7 @@ def show_types(args, out):
 
 
 def show_times(args, out):
-    """Worker for the --show-times option
+    """Worker for the --show-times option.
 
     Parameters
     ----------
@@ -261,7 +269,7 @@ def show_times(args, out):
 
 
 def latest(args, out):
-    """Worker for the --latest option
+    """Worker for the --latest option.
 
     Parameters
     ----------
@@ -282,7 +290,7 @@ def latest(args, out):
 
 
 def filename(args, out):
-    """Worker for the --filename option
+    """Worker for the --filename option.
 
     Parameters
     ----------
@@ -303,7 +311,7 @@ def filename(args, out):
 
 
 def show_urls(args, out):
-    """Worker for the default (show-urls) option
+    """Worker for the default (show-urls) option.
 
     Parameters
     ----------
@@ -326,7 +334,7 @@ def show_urls(args, out):
 
 
 def postprocess_cache(urls, args, out):
-    """Post-process a cache produced from a DataFind query
+    """Post-process a cache produced from a DataFind query.
 
     This function checks for gaps in the file coverage, prints the cache
     in the requested format, then prints gaps to stderr if requested.
@@ -360,7 +368,7 @@ def postprocess_cache(urls, args, out):
 # -- CLI ----------------------------------------------------------------------
 
 def main(args=None):
-    """Run the thing
+    """Run the thing.
     """
     # parse command line
     parser = command_line()

gwdatafind/api.py

@@ -15,7 +15,7 @@
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 
-"""API URL implementation for GWDataFind
+"""API URL implementation for GWDataFind.
 
 The functions in this module return URL paths to request on a given host
 to execute various GWDataFind queries.
@@ -30,7 +30,7 @@ DEFAULT_SERVICE_PREFIX = "LDR/services/data/v1"
 
 
 def _prefix(func):
-    """Wrap ``func`` to prepend the path prefix automatically
+    """Wrap ``func`` to prepend the path prefix automatically.
 
     This just simplifies the functional constructions below.
     """
@@ -45,16 +45,22 @@ def _prefix(func):
 
 @_prefix
 def ping_path():
+    """Return the API path to ping the server.
+    """
     return "gwf/H/R/1,2"
 
 
 @_prefix
 def find_observatories_path():
+    """Return the API path to query for all observatories.
+    """
     return "gwf.json"
 
 
 @_prefix
 def find_types_path(site=None):
+    """Return the API path to query for datasets for one or all sites.
+    """
     if site:
         return "gwf/{site[0]}.json".format(site=site)
     return "gwf/all.json"
@@ -62,6 +68,8 @@ def find_types_path(site=None):
 
 @_prefix
 def find_times_path(site, frametype, start, end):
+    """Return the API path to query for data availability segments.
+    """
     if start is None and end is None:
         return "gwf/{site}/{type}/segments.json".format(
             site=site,
@@ -77,6 +85,8 @@ def find_times_path(site, frametype, start, end):
 
 @_prefix
 def find_url_path(framefile):
+    """Return the API path to query for the URL of a specific filename.
+    """
     filename = basename(framefile)
     site, frametype, _ = filename.split("-", 2)
     return "gwf/{site}/{type}/{filename}.json".format(
@@ -88,6 +98,8 @@ def find_url_path(framefile):
 
 @_prefix
 def find_latest_path(site, frametype, urltype):
+    """Return the API path to query for the latest file in a dataset.
+    """
     stub = "gwf/{site}/{type}/latest".format(
         site=site,
         type=frametype,
@@ -99,6 +111,8 @@ def find_latest_path(site, frametype, urltype):
 
 @_prefix
 def find_urls_path(site, frametype, start, end, urltype=None, match=None):
+    """Return the API path to query for all URLs for a dataset in an interval.
+    """
     stub = "gwf/{site}/{type}/{start},{end}".format(
         site=site,
         type=frametype,

gwdatafind/conftest.py

@@ -16,7 +16,7 @@
 # You should have received a copy of the GNU General Public License
 # along with GWDataFind.  If not, see <http://www.gnu.org/licenses/>.
 
-"""Pytest hooks for gwdatafind
+"""Pytest hooks for gwdatafind.
 """
 
 import warnings

gwdatafind/io.py

@@ -16,7 +16,7 @@
 # You should have received a copy of the GNU General Public License
 # along with GWDataFind.  If not, see <http://www.gnu.org/licenses/>.
 
-"""I/O (mainly O) routines for GWDataFind
+"""I/O (mainly O) routines for GWDataFind.
 """
 
 import os.path
@@ -32,7 +32,7 @@ __author__ = 'Duncan Macleod <duncan.macleod@ligo.org>'
 class LalCacheEntry(
     namedtuple('CacheEntry', ('obs', 'tag', 'segment', 'url')),
 ):
-    """Simplified version of `lal.utils.CacheEntry`
+    """Simplified version of `lal.utils.CacheEntry`.
 
     This is provided so that we don't have to depend on lalsuite.
     """
@@ -48,12 +48,14 @@ class LalCacheEntry(
 
     @classmethod
     def from_url(cls, url, **kwargs):
+        """Create a new `LalCacheEntry` from a URL that follows LIGO-T050017.
+        """
         obs, tag, seg = filename_metadata(url)
         return cls(obs, tag, seg, url)
 
 
 def lal_cache(urls):
-    """Convert a list of URLs into a LAL cache
+    """Convert a list of URLs into a LAL cache.
 
     Returns
     -------
@@ -85,7 +87,7 @@ class OmegaCacheEntry(namedtuple(
 
 
 def omega_cache(cache):
-    """Convert a list of `LalCacheEntry` into a list of `OmegaCacheEntry`
+    """Convert a list of `LalCacheEntry` into a list of `OmegaCacheEntry`.
 
     Returns
     -------

gwdatafind/tests/__init__.py

@@ -16,7 +16,7 @@
 # You should have received a copy of the GNU General Public License
 # along with GWDataFind.  If not, see <http://www.gnu.org/licenses/>.
 
-"""Tests for :mod:`gwdatafind`
+"""Tests for :mod:`gwdatafind`.
 """
 
 __author__ = 'Duncan Macleod <duncan.macleod@ligo.org>'

gwdatafind/tests/conftest.py

@@ -15,7 +15,7 @@
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 
-"""Test utilities
+"""Test utilities.
 """
 
 import os
@@ -27,7 +27,7 @@ from . import yield_fixture
 
 @yield_fixture
 def response():
-    """Patch an HTTPConnection to do nothing in particular
+    """Patch an HTTPConnection to do nothing in particular.
 
     Yields the patch for `http.client.HTTPConnection.getresponse`
     """
@@ -38,7 +38,7 @@ def response():
 
 @yield_fixture
 def tmpname():
-    """Return a temporary file name, cleaning up after the method returns
+    """Return a temporary file name, cleaning up after the method returns.
     """
     name = tempfile.mktemp()
     open(name, 'w').close()

gwdatafind/tests/test_api.py

@@ -16,7 +16,7 @@
 # You should have received a copy of the GNU General Public License
 # along with GWDataFind.  If not, see <http://www.gnu.org/licenses/>.
 
-"""Test suite for `gwdatafind.api`
+"""Test suite for `gwdatafind.api`.
 
 This just asserts that the API implementation here matches the expectation
 from the v1 API for gwdatfind_server.

gwdatafind/tests/test_http.py

@@ -15,7 +15,7 @@
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 
-"""Tests for :mod:`gwdatafind.http`
+"""Tests for :mod:`gwdatafind.http`.
 """
 
 import json

gwdatafind/tests/test_main.py

@@ -16,7 +16,7 @@
 # You should have received a copy of the GNU General Public License
 # along with GWDataFind.  If not, see <http://www.gnu.org/licenses/>.
 
-"""Tests for :mod:`gwdatafind.__main__` (the CLI)
+"""Tests for :mod:`gwdatafind.__main__` (the CLI).
 """
 
 import argparse

gwdatafind/tests/test_utils.py

@@ -17,7 +17,7 @@
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 
-"""Tests for :mod:`gwdatafind.utils`
+"""Tests for :mod:`gwdatafind.utils`.
 """
 
 from unittest import mock

gwdatafind/ui.py

@@ -16,6 +16,13 @@
 # You should have received a copy of the GNU General Public License
 # along with GWDataFind.  If not, see <http://www.gnu.org/licenses/>.
 
+"""User interface functions for GWDataFind.
+
+These are all imported to the top-level namespace, so should be
+referred to in usage as ``gwdatafind.<function>`` and not
+``gwdatafind.ui.<function>``
+"""
+
 from functools import wraps
 from re import compile as compile_regex
 from urllib.parse import urlparse
@@ -50,7 +57,7 @@ __all__ = [
 # -- deprecated methods -------------------------
 
 def connect(host=None, port=None):  # pragma: no cover
-    """Open a new connection to a Datafind server
+    """Open a new connection to a Datafind server.
 
     This method will auto-select between HTTP and HTTPS based on port,
     and (for HTTPS) will automatically load the necessary X509 credentials
@@ -112,7 +119,7 @@ def get(url, *args, **kwargs):
 
 
 def get_json(*args, **kwargs):
-    """Perform a GET request and return JSON
+    """Perform a GET request and return JSON.
 
     Parameters
     ----------
@@ -136,7 +143,7 @@ def get_json(*args, **kwargs):
 
 
 def _url(host, api_func, *args, **kwargs):
-    """Construct the full URL for a query to ``host`` using an API function
+    """Construct the full URL for a query to ``host`` using an API function.
 
     Parameters
     ----------
@@ -499,7 +506,7 @@ def find_urls(
     host=None,
     session=None,
 ):
-    """Query a GWDataFind host for all URLs for a dataset in an interval
+    """Query a GWDataFind host for all URLs for a dataset in an interval.
 
     Parameters
     ----------

gwdatafind/utils.py

@@ -17,7 +17,7 @@
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 
-"""Utilities for the GW datafind service
+"""Utilities for the GW datafind service.
 """
 
 import os
@@ -29,7 +29,7 @@ from igwn_auth_utils import x509 as igwn_x509
 
 
 def get_default_host():
-    """Returns the default host as stored in the ``${GWDATAFIND_SERVER}``
+    """Return the default host as stored in the ``${GWDATAFIND_SERVER}``.
 
     Returns
     -------
@@ -131,7 +131,7 @@ def find_credential():
 # -- LIGO-T050017 filename parsing --------------------------------------------
 
 def filename_metadata(filename):
-    """Return metadata parsed from a filename following LIGO-T050017
+    """Return metadata parsed from a filename following LIGO-T050017.
 
     Parameters
     ----------

setup.cfg

@@ -83,6 +83,8 @@ ignore =
 	D200,
 	# blank link after class docstring
 	D203, D204
+	# missing docstring in magic method
+	D105
 	# missing whitespace around arithmetic operator
 	E226,
 	# use of assert

setup.py

@@ -16,7 +16,7 @@
 # You should have received a copy of the GNU General Public License
 # along with GWDataFind.  If not, see <http://www.gnu.org/licenses/>.
 
-"""Setup GWDataFind
+"""Setup GWDataFind.
 """
 
 from setuptools import setup