MNT: Clean up docstring formatting and add more

This gets us a clean pass with flake8-docstrings.

Author: dopplershift

setup.py

@@ -1,6 +1,7 @@
 # Copyright (c) 2013-2015 University Corporation for Atmospheric Research/Unidata.
 # Distributed under the terms of the MIT License.
 # SPDX-License-Identifier: MIT
+"""Setup script for installing Siphon."""
 
 from __future__ import print_function
 

siphon/__init__.py

@@ -1,6 +1,7 @@
 # Copyright (c) 2013-2015 University Corporation for Atmospheric Research/Unidata.
 # Distributed under the terms of the MIT License.
 # SPDX-License-Identifier: MIT
+"""Tools for accessing atmospheric and oceanic science data on remote servers."""
 
 # Version import needs to come first so everyone else can pull on import
 from ._version import get_versions

siphon/catalog.py

@@ -2,9 +2,9 @@
 # Distributed under the terms of the MIT License.
 # SPDX-License-Identifier: MIT
 """
-This module contains code to support reading and parsing
-catalog files from a THREDDS Data Server (TDS). They help identifying
-the latest dataset and finding proper URLs to access the data.
+Code to support reading and parsing catalog files from a THREDDS Data Server (TDS).
+
+They help identifying the latest dataset and finding proper URLs to access the data.
 """
 
 from collections import OrderedDict
@@ -26,7 +26,7 @@
 
 class TDSCatalog(object):
     r"""
-    An object for holding information from a THREDDS Client Catalog.
+    Parse information from a THREDDS Client Catalog.
 
     Attributes
     ----------
@@ -44,6 +44,7 @@ class TDSCatalog(object):
         catalog ref title.
 
     """
+
     def __init__(self, catalog_url):
         r"""
         Initialize the TDSCatalog object.
@@ -52,6 +53,7 @@ def __init__(self, catalog_url):
         ----------
         catalog_url : str
             The URL of a THREDDS client catalog
+
         """
         # top level server url
         self.catalog_url = catalog_url
@@ -159,8 +161,7 @@ def _process_datasets(self):
 
 class CatalogRef(object):
     r"""
-    An object for holding Catalog References obtained from a THREDDS Client
-    Catalog.
+    An object for holding catalog references obtained from a THREDDS Client Catalog.
 
     Attributes
     ----------
@@ -170,7 +171,9 @@ class CatalogRef(object):
         url to the :class:`CatalogRef`'s THREDDS Client Catalog
     title : str
         Title of the :class:`CatalogRef` element
+
     """
+
     def __init__(self, base_url, element_node):
         r"""
         Initialize the catalogRef object.
@@ -191,12 +194,13 @@ def __init__(self, base_url, element_node):
         self.href = urljoin(base_url, href)
 
     def follow(self):
-        r""" Follow the catalog reference, returning a new :class:`TDSCatalog`
+        r"""Follow the catalog reference and return a new :class:`TDSCatalog`.
 
         Returns
         -------
         TDSCatalog
             The referenced catalog
+
         """
         return TDSCatalog(self.href)
 
@@ -215,10 +219,11 @@ class Dataset(object):
         A dictionary of access urls whose keywords are the access service
         types defined in the catalog (for example, "OPENDAP", "NetcdfSubset",
         "WMS", etc.
+
     """
+
     def __init__(self, element_node, catalog_url=''):
-        r"""
-        Initialize the Dataset object.
+        r"""Initialize the Dataset object.
 
         Parameters
         ----------
@@ -229,7 +234,7 @@ def __init__(self, element_node, catalog_url=''):
 
         """
         self.name = element_node.attrib['name']
-        if ('urlPath' in element_node.attrib):
+        if 'urlPath' in element_node.attrib:
             self.url_path = element_node.attrib['urlPath']
         else:
             self.url_path = None
@@ -248,8 +253,7 @@ def __init__(self, element_node, catalog_url=''):
                             'the latest.xml dataset!')
 
     def resolve_url(self, catalog_url):
-        r"""
-        Resolve the url of the dataset when reading latest.xml
+        r"""Resolve the url of the dataset when reading latest.xml.
 
         Parameters
         ----------
@@ -283,9 +287,7 @@ def resolve_url(self, catalog_url):
                 log.warning('no dataset url path found in latest.xml!')
 
     def make_access_urls(self, catalog_url, all_services, metadata=None):
-        r"""
-        Make fully qualified urls for the access methods enabled on the
-        dataset.
+        r"""Make fully qualified urls for the access methods enabled on the dataset.
 
         Parameters
         ----------
@@ -295,8 +297,8 @@ def make_access_urls(self, catalog_url, all_services, metadata=None):
             list of :class:`SimpleService` objects associated with the dataset
         metadata : TDSCatalogMetadata
             Metadata from the :class:`TDSCatalog`
-        """
 
+        """
         all_service_dict = {service.name: service for service in all_services}
         service_name = None
         if metadata:
@@ -335,15 +337,14 @@ def make_access_urls(self, catalog_url, all_services, metadata=None):
         self.access_urls = access_urls
 
     def add_access_element_info(self, access_element):
+        """Create an access method from a catalog element."""
         service_name = access_element.attrib['serviceName']
         url_path = access_element.attrib['urlPath']
         self.access_element_info[service_name] = url_path
 
 
 class SimpleService(object):
-    r"""
-    An object for holding information about an access service enabled on a
-    dataset.
+    r"""Hold information about an access service enabled on a dataset.
 
     Attributes
     ----------
@@ -355,7 +356,9 @@ class SimpleService(object):
         A dictionary of access urls whose keywords are the access service
         types defined in the catalog (for example, "OPENDAP", "NetcdfSubset",
         "WMS", etc.)
+
     """
+
     def __init__(self, service_node):
         r"""
         Initialize the Dataset object.
@@ -373,8 +376,7 @@ def __init__(self, service_node):
 
 
 class CompoundService(object):
-    r"""
-    An object for holding information about compound services.
+    r"""Hold information about compound services.
 
     Attributes
     ----------
@@ -385,10 +387,11 @@ class CompoundService(object):
         "COMPOUND")
     services : list[SimpleService]
         A list of :class:`SimpleService` objects
+
     """
+
     def __init__(self, service_node):
-        r"""
-        Initialize a :class:`CompoundService` object.
+        r"""Initialize a :class:`CompoundService` object.
 
         Parameters
         ----------
@@ -410,8 +413,7 @@ def __init__(self, service_node):
 
 
 def _find_base_tds_url(catalog_url):
-    """
-    Identify the base URL of the THREDDS server from the catalog URL.
+    """Identify the base URL of the THREDDS server from the catalog URL.
 
     Will retain URL scheme, host, port and username/password when present.
     """
@@ -423,9 +425,7 @@ def _find_base_tds_url(catalog_url):
 
 
 def _get_latest_cat(catalog_url):
-    r"""
-    Get the latest dataset catalog from the supplied top level dataset catalog
-    url.
+    r"""Get the latest dataset catalog from the supplied top level dataset catalog url.
 
     Parameters
     ----------
@@ -448,10 +448,10 @@ def _get_latest_cat(catalog_url):
 
 
 def get_latest_access_url(catalog_url, access_method):
-    r"""
-    Get the data access url, using a specified access method, to the latest
-    data available from a top level dataset catalog (url). Currently only
-    supports the existence of one "latest" dataset.
+    r"""Get the data access url to the latest data using a specified access method.
+
+    These are available for a data available from a top level dataset catalog (url).
+    Currently only supports the existence of one "latest" dataset.
 
     Parameters
     ----------
@@ -466,8 +466,8 @@ def get_latest_access_url(catalog_url, access_method):
         Data access URL to be used to access the latest data available from a
         given catalog using the specified `access_method`. Typically a single string,
         but not always.
-    """
 
+    """
     latest_cat = _get_latest_cat(catalog_url)
     if latest_cat != '':
         if len(list(latest_cat.datasets.keys())) > 0:

siphon/cdmr/__init__.py

@@ -1,6 +1,7 @@
 # Copyright (c) 2013-2015 University Corporation for Atmospheric Research/Unidata.
 # Distributed under the terms of the MIT License.
 # SPDX-License-Identifier: MIT
+"""Support for using CDMRemote on a THREDDS Data Server (TDS)."""
 
 from .dataset import Dataset
 

siphon/cdmr/cdmremote.py

@@ -1,6 +1,7 @@
 # Copyright (c) 2013-2015 University Corporation for Atmospheric Research/Unidata.
 # Distributed under the terms of the MIT License.
 # SPDX-License-Identifier: MIT
+"""Support talking to the CDMRemote endpoint on a THREDDS Data Server (TDS)."""
 
 from io import BytesIO
 
@@ -9,29 +10,37 @@
 
 
 class CDMRemote(HTTPEndPoint):
+    """Provide access to the various methods on the CDMRemote endpoint on a TDS."""
+
     def __init__(self, url):
+        """Initialize access to a particular url."""
         super(CDMRemote, self).__init__(url)
         self.deflate = 0
 
     def _fetch(self, query):
         return read_ncstream_messages(BytesIO(self.get_query(query).content))
 
     def fetch_capabilities(self):
+        """Query the CDMRemote end point for its capabilities."""
         return self.get_query(self.query().add_query_parameter(req='capabilities'))
 
     def fetch_cdl(self):
+        """Retrieve the CDL response from CDMRemote."""
         return self.get_query(self.query().add_query_parameter(req='CDL'))
 
     def fetch_data(self, **var):
+        """Retrieve data from CDMRemote for one or more variables."""
         varstr = ','.join(name + self._convert_indices(ind)
                           for name, ind in var.items())
         query = self.query().add_query_parameter(req='data', var=varstr)
         return self._fetch(query)
 
     def fetch_header(self):
+        """Retrieve the header response from CDMRemote."""
         return self._fetch(self.query().add_query_parameter(req='header'))
 
     def fetch_ncml(self):
+        """Retrieve the NCML response from CDMRemote."""
         return self.get_query(self.query().add_query_parameter(req='NcML'))
 
     def query(self):
@@ -43,6 +52,7 @@ def query(self):
         -------
         HTTPQuery
             The created query.
+
         """
         q = super(CDMRemote, self).query()
 

siphon/cdmr/cdmremotefeature.py

@@ -1,6 +1,7 @@
 # Copyright (c) 2016 University Corporation for Atmospheric Research/Unidata.
 # Distributed under the terms of the MIT License.
 # SPDX-License-Identifier: MIT
+"""Provide access to the CDMRemoteFeature endpoint on TDS."""
 
 from io import BytesIO
 
@@ -9,7 +10,8 @@
 
 
 class CDMRemoteFeature(NCSS):
-    """Simple wrapper for speaking to CDMRemoteFeature HTTP endpoint"""
+    """Communicate to the CDMRemoteFeature HTTP endpoint."""
+
     @staticmethod
     def _parse_messages(resp):
         """Parse server responses as CDMRemoteFeature messages."""

siphon/cdmr/coveragedataset.py

@@ -1,6 +1,7 @@
 # Copyright (c) 2016 University Corporation for Atmospheric Research/Unidata.
 # Distributed under the terms of the MIT License.
 # SPDX-License-Identifier: MIT
+"""Provide access to TDS' Coverage Dataset."""
 
 from collections import OrderedDict
 import logging
@@ -15,12 +16,16 @@
 
 
 def reindent_lines(new_leader, source):
-    'Helper for __str__ to re-indent lines'
+    """Re-indent string lines."""
     return new_leader + ('\n' + new_leader).join(source.split('\n'))
 
 
 class CoverageDataset(AttributeContainer):
-    """Experimental class wrapping dataset access using CDMRemoteFeature and Coverages."""
+    """Wrap dataset access using CDMRemoteFeature and Coverages.
+
+    This is still experimental.
+    """
+
     def __init__(self, url):
         """Initialize CoverageDataset from a url pointing to CDMRemoteFeature endpoint."""
         super(CoverageDataset, self).__init__()