meet flake8-docstring recommendations (#32)

* meet flake8-docstring lint suggestions
* remove unused import

Author: cmeissner

phpypam/__init__.py

@@ -1,3 +1,4 @@
+"""Package that provides phpIPAM API interface."""
 from pkg_resources import get_distribution, DistributionNotFound
 
 from phpypam.core.api import Api as api

phpypam/core/__init__.py

@@ -0,0 +1 @@
+"""Core package provide api and exception classes."""

phpypam/core/api.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 # (c) Christian Meißner 2020
-
+"""Default class to handle all api interactions with phpIPAM server."""
 import re
 import requests
 
@@ -15,14 +15,18 @@
 
 
 class Api(object):
+    """The main class.
 
-    """ The main class. It generates tha API object where you can run
+    It generates tha API object where you can run
     different actions again to `create`, `update` and `delete` entities.
     It also provides functions with informational character only.
     """
+
     def __init__(self, url, app_id, username=None, password=None, token=None, encryption=False, timeout=None, ssl_verify=True, user_agent=None):
+        """Generate the api object.
+
+        The costructor collects all data to connect to phpIPAM API. If all data is there it makes the connection to the given server.
 
-        """ contructor method
         :param url: The URL to a phpIPAM instance. It includes the protocol (`http` or `https`).
         :type url: str
         :param app_id: The app_id which is used for the API operations.
@@ -64,8 +68,8 @@ def __init__(self, url, app_id, username=None, password=None, token=None, encryp
             self._login()
 
     def _query(self, path='user', headers=None, method=GET, data=None, params=None, auth=None, token=None):
+        """Send queries to phpIPAM API in a generalistic manner.
 
-        """ Sends queries to phpIPAM API in a generalistic manner
         :param path: Path to the controler and possibly to function to use., defaults to 'user'
         :type path: str, optional
         :param headers: Optional request headers, defaults to None
@@ -121,23 +125,26 @@ def _query(self, path='user', headers=None, method=GET, data=None, params=None,
                 return result['data']
 
     def _login(self):
-        """ Login method """
+        """Login to phpIPAM API and return token."""
         _auth = HTTPBasicAuth(self._api_username, self._api_password)
         resp = self._query(method=POST, auth=_auth)
 
         self._api_token = resp['token']
 
     def get_token(self):
+        """Return last login token.
 
-        """ Method to grap last login token
         :return: Returns the api token from the last successful login.
         :rtype: str
         """
         return self._api_token
 
     def get_entity(self, controller, controller_path=None, params=None):
+        """Get existing entity from phpIPAM server.
+
+        This method query for existing entity. It there a result it will be returned otherwise
+        an PhpIPAMEntityNotFound exception is raised from underlying method.
 
-        """ Method to get an existing entity
         :param controller: Name of the controller to request entity from.
         :type controller: str
         :param controller_path: The path which is used to query for entities, defaults to None
@@ -158,8 +165,8 @@ def get_entity(self, controller, controller_path=None, params=None):
         return self._query(token=self._api_token, method=GET, path=_path, params=_params)
 
     def create_entity(self, controller, controller_path=None, data=None, params=None):
+        """Create an entity.
 
-        """ Create an entity
         :param controller: Name of the controller to use.
         :type controller: str
         :param controller_path: The path which is used to query for entities, defaults to None
@@ -182,8 +189,8 @@ def create_entity(self, controller, controller_path=None, data=None, params=None
         return self._query(token=self._api_token, method=POST, path=_path, data=data, params=_params)
 
     def delete_entity(self, controller, controller_path, params=None):
+        """Delete an entity.
 
-        """ This method is used to delete an entity.
         :param controller: Name of the controller to use.
         :type controller: str
         :param controller_path: The path wich is used to access the entity to delete.
@@ -200,8 +207,8 @@ def delete_entity(self, controller, controller_path, params=None):
         return self._query(token=self._api_token, method=DELETE, path=_path, params=_params)
 
     def update_entity(self, controller, controller_path=None, data=None, params=None):
+        """Update an entity.
 
-        """ This method is used to update an entity.
         :param controller: Name of the controller to use.
         :type controller: str
         :param controller_path: The path which is used to access the entity to update., defaults to None
@@ -224,9 +231,11 @@ def update_entity(self, controller, controller_path=None, data=None, params=None
         return self._query(token=self._api_token, method=PATCH, path=_path, data=data, params=_params)
 
     def controllers(self):
+        """Report all controllers from phpIPAM API.
 
-        """ This method is used to report all known controllers of phpIPAM API.
+        This method is used to report all known controllers of phpIPAM API.
         Unfortunately the API doesn't report all nor the correct paths for all 'controllers'.
+
         :return: Returns a tuple of controller paths.
         :rtype: tuple
         """

phpypam/core/exceptions.py

@@ -1,14 +1,16 @@
-# provides the main query methods.
-
-import json
+"""Class to provided different Exceptions."""
 
 
 class PHPyPAMException(Exception):
-    """ PHPyPAMExeption, children of :class:`Exception`.
+    """PHPyPAMExeption, children of :class:`Exception`.
+
     This exception is raised if anythings in :class:`phpypam.api` doesn't work out.
     """
+
     def __init__(self, *args, code=None, message=None):
-        """ Constructor method.
+        """Generate PHPyPAMException.
+
+        This Exception takes 'code' and 'message' and decided on it which special Exception can be raised.
 
         :param code: Status code which comes from caller., defaults to None
         :type code: int, optional
@@ -44,32 +46,35 @@ def __init__(self, *args, code=None, message=None):
 
 
 class PHPyPAMInvalidCredentials(Exception):
+    """Exception PHPyPAMInvalidCredentials, children of :class:`Exception`.
 
-    """ Exception PHPyPAMInvalidCredentials, children of :class:`Exception`.
     This Exception is raised if there are any issues with the authentication against phpIPAM api.
     """
+
     def __init__(self, *args, **kwargs):
-        """ constructor method """
+        """Generate PHPyPAMInvalidCredentials exception."""
         super(PHPyPAMInvalidCredentials, self).__init__(*args, **kwargs)
 
 
 class PHPyPAMEntityNotFoundException(Exception):
+    """Exception PHPyPAMEntityNotFoundException, children of :class:`Exception`.
 
-    """ Exception PHPyPAMEntityNotFoundException, children of :class:`Exception`.
     This Exception is raised if an entity was not found.
     """
+
     def __init__(self, *args, **kwargs):
-        """ constructor method """
+        """Generate PHPyPAMEntityNotFoundException."""
         super(PHPyPAMEntityNotFoundException, self).__init__(*args, **kwargs)
 
 
 class PHPyPAMInvalidSyntax(Exception):
+    """Exception PHPyPAMInvalidSyntax, children of :class:`Exception`.
 
-    """ Exception PHPyPAMInvalidSyntax, children of :class:`Exception`.
     This Exception is raised if there are any issues with syntax of request against phpIPAM api.
     """
+
     def __init__(self, *args, **kwargs):
-        """ constructor method """
+        """Generate PHPyPAMInvalidSyntax exception."""
         self._message = kwargs.pop('message', '')
 
         super(PHPyPAMInvalidSyntax, self).__init__(self._message, *args, **kwargs)