Merge pull request #55 from hpe-container-platform-community/fix_client_docstrings

snowch · web-flow · commit 38a9fde9a4ec · 2020-06-14T17:43:11.000+01:00
add docstrings to catalog
diff --git a/.travis.yml b/.travis.yml
@@ -36,7 +36,7 @@ jobs:
       install:
         - pip3 install flake8 flake8-docstrings flake8-per-file-ignores
       script:
-        - flake8 --exclude hpecp/catalog.py,hpecp/config.py,hpecp/gateway.py,hpecp/logger.py,hpecp/lock.py,hpecp/k8s_cluster.py,hpecp/k8s_worker.py,hpecp/license.py,hpecp/exceptions.py,hpecp/user.py,hpecp/tenant.py,hpecp/role.py --docstring-convention numpy bin/ hpecp/
+        - flake8 --exclude hpecp/gateway.py,hpecp/logger.py,hpecp/k8s_cluster.py,hpecp/user.py,hpecp/tenant.py,hpecp/role.py --docstring-convention numpy bin/ hpecp/
     - stage: coverage_library
       name: "Code coverage LIBRARY (./hpecp)"
       python: 3.8
diff --git a/hpecp/catalog.py b/hpecp/catalog.py
@@ -25,7 +25,7 @@
 
 
 class CatalogController:
-    """This is the main class that users will interact with to talk to catalogs.
+    """Class that users will interact with to work with catalogs.
 
     An instance of this class is available in the
     `client.ContainerPlatformClient` with the attribute name
@@ -43,13 +43,16 @@ def __init__(self, client):
         self.client = client
 
     def list(self):
-        """Retrieve a list of Catalogs
+        """Retrieve a list of Catalogs.
 
-        Returns:
-            CatalogList: list of Catalogs
+        Returns
+        -------
+        CatalogList
+            list of Catalogs
 
-        Raises:
-            APIException
+        Raises
+        ------
+        APIException
         """
         response = self.client._request(
             url="/api/v1/catalog/",
@@ -61,17 +64,21 @@ def list(self):
         )
 
     def get(self, catalog_id):
-        """Retrieve a catalog identified by {catalog_id}
+        """Retrieve a catalog identified by {catalog_id}.
 
-        Args:
-            catalog_id: str
-                The Catalog ID - format: '/api/v1/catalog/[0-9]+'
+        Parameters
+        ----------
+        catalog_id: str
+            The Catalog ID - format: '/api/v1/catalog/[0-9]+'
 
-        Raises:
-            APIException
+        Returns
+        -------
+        Catalog
+            object representing the requested Catalog
 
-        Returns:
-            Catalog -- object representing the requested Catalog
+        Raises
+        ------
+        APIException
         """
         assert isinstance(
             catalog_id, str
@@ -88,19 +95,7 @@ def get(self, catalog_id):
 
 
 class Catalog:
-    """Create an instance of Catalog from json data returned from the HPE
-
-    Container Platform API. Users of this library are not expected to create an
-    instance of this class.
-
-    Parameters:
-        json : str
-            The json returned by the API representing a Catalog.
-
-    Returns:
-        Catalog:
-            An instance of Catalog
-    """
+    """Catalog Image item."""
 
     # All of the fields of Catalog objects as returned by the HPE Container
     # Platform API.
@@ -133,6 +128,23 @@ class Catalog:
     default_display_fields = all_fields
 
     def __init__(self, json):
+        """Create a Catalog Image.
+
+        Parameters
+        ----------
+        json : str
+            The json returned by the API representing a Catalog.
+
+        Returns
+        -------
+        Catalog:
+            An instance of Catalog
+
+        Note
+        ----
+        Users of the library aren't expected to create instances of this class
+        directly.
+        """
         self.json = json
         self.display_columns = Catalog.default_display_fields
 
@@ -155,13 +167,15 @@ def __len__(self):
 
     def set_display_columns(self, columns):
         """Set the columns this instance should have when the instance is used
-
         with :py:meth:`.CatalogList.tabulate`.
 
-        Parameters:
-            columns : list[str]
-                Set the list of colums to return
+        Parameters
+        ----------
+        columns : list[str]
+            Set the list of colums to return
 
+        See Also
+        --------
         See :py:attr:`all_fields` for the complete list of field names.
         """
         self.display_columns = columns
@@ -185,14 +199,17 @@ def state(self):
 
 
 class CatalogList:
-    """List of :py:obj:`.Catalog` objects
+    """List of :py:obj:`.Catalog` objects.
 
-    This class is not expected to be instantiated by users.
+    Parameters
+    ----------
+    json : str
+        json data returned from the HPE Container Platform API get request
+        to /api/v1/catalog
 
-    Parameters:
-        json : str
-            json data returned from the HPE Container Platform API get request
-            to /api/v1/catalog
+    Note
+    ----
+    This class is not expected to be instantiated by users.
     """
 
     def __init__(self, json):
@@ -234,25 +251,30 @@ def tabulate(
         style="pretty",
         display_headers=True,
     ):
-        """Provide a tabular represenation of the list of Catalogs
+        """Provide a tabular represenation of the list of Catalog images.
+
+        Parameters
+        ----------
+        columns : list[str]
+            list of columns to return in the table - default
+            :py:attr:`.Catalog.default_display_fields`
+        style: str
+            See: https://github.com/astanin/python-tabulate#table-format
 
-        Parameters:
-            columns : list[str]
-                list of columns to return in the table - default
-                :py:attr:`.Catalog.default_display_fields`
-            style: str
-                See: https://github.com/astanin/python-tabulate#table-format
+        Returns
+        -------
+        str
+            table output
 
-        Returns:
-            str : table output
+        Example
+        -------
+        Print the catalog list with all of the avaialble fields:
 
-        Example::
+        >>> print(hpeclient.catalog.list().tabulate())
 
-            # Print the catalog list with all of the avaialble fields
-            print(hpeclient.catalog.list().tabulate())
+        Print the cluster list with a subset of the fields:
 
-            # Print the cluster list with a subset of the fields
-            print(hpeclient.catalog.list().tabulate(columns=['id', 'state']))
+        >>> print(hpeclient.catalog.list().tabulate(columns=['id', 'state']))
         """
         if columns != Catalog.default_display_fields:
             assert isinstance(
diff --git a/hpecp/k8s_worker.py b/hpecp/k8s_worker.py
@@ -144,18 +144,22 @@ def create_with_ssh_password(self, username, password):
         raise NotImplementedError()
 
     def create_with_ssh_key(self, ip, ssh_key_data, tags=[]):
-        """Create a gateway instance using SSH key credentials to access the host
-
-        Args:
-            ip: str
-                The IP address of the proxy host.  Used for internal
-                communication.
-            ssh_key_data: str
-                The ssh key data as a string.
-            tags: list
-                Tags to use, e.g. "{ 'tag1': 'foo', 'tag2', 'bar' }".
-
-        Returns: Worker ID
+        """Create a gateway instance using SSH key credentials to access the host.
+
+        Parameters
+        ----------
+        ip: str
+            The IP address of the proxy host.  Used for internal
+            communication.
+        ssh_key_data: str
+            The ssh key data as a string.
+        tags: list
+            Tags to use, e.g. "{ 'tag1': 'foo', 'tag2', 'bar' }".
+
+        Returns
+        -------
+        string
+            Worker ID
         """
 
         assert isinstance(
@@ -221,22 +225,26 @@ def delete(self, worker_id):
     def wait_for_status(self, worker_id, status=[], timeout_secs=1200):
         """Wait for K8S worker status.
 
-        Args:
-            worker_id: str
-                The worker ID - format: '/api/v1/workers/[0-9]+'
-            status: list[:py:class:`WorkerK8sStatus`]
-                Status(es) to wait for.  Use an empty array if you want to
-                wait for a cluster's existence to cease.
-            timeout_secs: int
-                How long to wait for the status(es) before raising an
-                exception.
-
-        Returns:
-            bool: True if status was found before timeout, otherwise False
-
-        Raises:
-            APIItemNotFoundException: if the item is not found and status is
-            not empty
+        Parameters
+        ----------
+        worker_id: str
+            The worker ID - format: '/api/v1/workers/[0-9]+'
+        status: list[:py:class:`WorkerK8sStatus`]
+            Status(es) to wait for.  Use an empty array if you want to
+            wait for a cluster's existence to cease.
+        timeout_secs: int
+            How long to wait for the status(es) before raising an
+            exception.
+
+        Returns
+        -------
+        bool
+            True if status was found before timeout, otherwise False
+
+        Raises
+        ------
+        APIItemNotFoundException
+            If the item is not found and status is not empty
             APIException: if a generic API exception occurred
         """
         assert isinstance(
diff --git a/hpecp/license.py b/hpecp/license.py
@@ -80,18 +80,18 @@ def upload_with_ssh_pass(
         )
 
     def register(self, server_filename):
-        """Register a license that has been uploaded to
-        '/srv/bluedata/license/' on the controller.
-
-        Arguments:
-
-            server_filename: str
-                Filepath to the license on the server, e.g.
-                '/srv/bluedata/license/LICENSE-1.txt'
-
-        Raises:
-
-            APIException
+        """Register a license. The license must have previously been uploaded
+        to '/srv/bluedata/license/' on the controller.
+
+        Parameters
+        ----------
+        server_filename: str
+            Filepath to the license on the server, e.g.
+            '/srv/bluedata/license/LICENSE-1.txt'
+
+        Raises
+        ------
+        APIException
         """
         data = {"hpelicense_file": server_filename}
         return self.client._request(
@@ -102,16 +102,16 @@ def register(self, server_filename):
         )
 
     def delete(self, license_key):
-        """Delete a license by LicenseKey
-
-        Arguments:
-
-            license_key: str
-                The license key, e.g. '1234 1234 ... 1234 "SOMETEXT"'
+        """Delete a license by LicenseKey.
 
-        Raises:
+        Parameters
+        ----------
+        license_key: str
+            The license key, e.g. '1234 1234 ... 1234 "SOMETEXT"'
 
-            APIException
+        Raises
+        ------
+        APIException
         """
 
         try:
diff --git a/hpecp/lock.py b/hpecp/lock.py
