Merge pull request #10 from nrccua/ARCH-503-apply-pydoc-to-aioradio

apply pydoc to project

.pre-commit-config.yaml

@@ -2,14 +2,23 @@ default_language_version:
     python: python3.8
 repos:
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v3.1.0
+    rev: v3.4.0
     hooks:
     -   id: check-added-large-files
     -   id: check-ast
+    -   id: check-docstring-first
     -   id: check-json
     -   id: check-yaml
     -   id: debug-statements
     -   id: end-of-file-fixer
     -   id: name-tests-test
     -   id: requirements-txt-fixer
     -   id: trailing-whitespace
+-   repo: https://github.com/PyCQA/isort
+    rev: 5.6.4
+    hooks:
+    -   id: isort
+-   repo: https://github.com/myint/docformatter
+    rev: v1.3.1
+    hooks:
+    -   id: docformatter

HISTORY.rst

@@ -3,6 +3,13 @@ History
 =======
 
 
+v0.9.6 (2020-12-22)
+-----------------------
+
+* Apply pydoc to repository.
+* Add isort and docformatter to pre-commit.
+
+
 v0.9.5 (2020-12-14)
 -----------------------
 

aioradio/aws/dynamodb.py

@@ -1,10 +1,8 @@
-'''Generic async AWS functions for DynamoDB.'''
+"""Generic async AWS functions for DynamoDB."""
 
 # pylint: disable=too-many-arguments
 
-from typing import Any
-from typing import Dict
-from typing import List
+from typing import Any, Dict, List
 
 from aioradio.aws.utils import AwsServiceManager
 
@@ -19,7 +17,18 @@ async def create_dynamo_table(
         attribute_definitions: List[Dict[str, str]],
         key_schema: List[Dict[str, str]],
         provisioned_throughput: Dict[str, int]) -> str:
-    '''Create dynamo table. '''
+    """Create dynamo table.
+
+    Args:
+        table_name (str): dynamo table name
+        region (str): AWS region
+        attribute_definitions (List[Dict[str, str]]): an attribute for describing the key schema for the table
+        key_schema (List[Dict[str, str]]): attributes that make up the primary key of a table, or the key attributes of an index
+        provisioned_throughput (Dict[str, int]): Throughput (ReadCapacityUnits & WriteCapacityUnits) for the dynamo table
+
+    Returns:
+        str: error message if any
+    """
 
     error = ''
 
@@ -39,7 +48,14 @@ async def create_dynamo_table(
 
 @AWS_SERVICE.active
 async def get_list_of_dynamo_tables(region: str) -> List[str]:
-    '''Get list of Dynamo tables in a particular region.'''
+    """Get list of Dynamo tables in a particular region.
+
+    Args:
+        region (str): AWS region
+
+    Returns:
+        List[str]: list of dynamo tables
+    """
 
     tables = []
     result = await DYNAMO[region]['client']['obj'].list_tables()
@@ -50,7 +66,16 @@ async def get_list_of_dynamo_tables(region: str) -> List[str]:
 
 @AWS_SERVICE.active
 async def scan_dynamo(table_name: str, region: str, key: Any=None) -> List[Any]:
-    '''Scan dynamo table using a filter_expression if supplied.'''
+    """Scan dynamo table using a filter_expression if supplied.
+
+    Args:
+        table_name (str): dynamo table name
+        region (str): AWS region
+        key (Any, optional): filter expression to reduce items scaned. Defaults to None.
+
+    Returns:
+        List[Any]: list of scanned items
+    """
 
     result = []
     scan_kwargs = {'FilterExpression': key} if key is not None else {}
@@ -68,7 +93,16 @@ async def scan_dynamo(table_name: str, region: str, key: Any=None) -> List[Any]:
 
 @AWS_SERVICE.active
 async def put_item_in_dynamo(table_name: str, region: str, item: Dict[str, Any]) -> Dict[str, Any]:
-    '''Put item in dynamo table.'''
+    """Put item in dynamo table.
+
+    Args:
+        table_name (str): dynamo table name
+        region (str): AWS region
+        item (Dict[str, Any]): items to add/modifiy in dynamo table
+
+    Returns:
+        Dict[str, Any]: response of operation
+    """
 
     result = {}
     table = await DYNAMO[region]['resource']['obj'].Table(table_name)
@@ -77,8 +111,17 @@ async def put_item_in_dynamo(table_name: str, region: str, item: Dict[str, Any])
 
 
 @AWS_SERVICE.active
-async def query_dynamo(table_name: str, region: str, key: Any):
-    '''Query dynamo for with specific key_condition_expression.'''
+async def query_dynamo(table_name: str, region: str, key: Any) -> List[Any]:
+    """Query dynamo for with specific key_condition_expression.
+
+    Args:
+        table_name (str): dynamo table name
+        region (str): AWS region
+        key (Any): KeyConditionExpression parameter to provide a specific value for the partition key
+
+    Returns:
+        List[Any]: [description]
+    """
 
     result = []
     query_kwargs = {'KeyConditionExpression': key}
@@ -104,7 +147,21 @@ async def update_item_in_dynamo(
         expression_attribute_values: str='',
         condition_expression: str='',
         return_values: str='UPDATED_NEW') -> Dict[str, Any]:
-    '''Update an item in Dynamo without overwriting the entire item.'''
+    """Update an item in Dynamo without overwriting the entire item.
+
+    Args:
+        table_name (str): dynamo table name
+        region (str): AWS region
+        key (Dict[str, Any]): partition key and sort key if applicable
+        update_expression (str): attributes to be updated, the action to be performed on them, and new value(s) for them
+        expression_attribute_names (str): one or more substitution tokens for attribute names in an expression
+        expression_attribute_values (str, optional): one or more values that can be substituted in an expression. Defaults to ''.
+        condition_expression (str, optional): condition that must be satisfied in order for a conditional update to succeed. Defaults to ''.
+        return_values (str, optional): items to return in response. Defaults to 'UPDATED_NEW'.
+
+    Returns:
+        Dict[str, Any]: [description]
+    """
 
     result = {}
     update_kwargs = {
@@ -127,7 +184,16 @@ async def update_item_in_dynamo(
 
 @AWS_SERVICE.active
 async def batch_write_to_dynamo(table_name: str, region: str, items: List[Dict[str, Any]]) -> bool:
-    '''Write batch of items to dynamo table.'''
+    """Write batch of items to dynamo table.
+
+    Args:
+        table_name (str): dynamo table name
+        region (str): AWS region
+        items (List[Dict[str, Any]]): items to write to dynamo table
+
+    Returns:
+        bool: success status of writing items
+    """
 
     batch_writer_successful = False
 
@@ -146,7 +212,16 @@ async def batch_get_items_from_dynamo(
         table_name: str,
         region: str,
         items: List[Dict[str, Any]]) -> Dict[str, Any]:
-    '''Get batch of items from dynamo.'''
+    """Get batch of items from dynamo.
+
+    Args:
+        table_name (str): dynamo table name
+        region (str): AWS region
+        items (List[Dict[str, Any]]): list of items to fetch from dynamo table
+
+    Returns:
+        Dict[str, Any]: response of operation
+    """
 
     response = await DYNAMO[region]['resource']['obj'].batch_get_item(RequestItems={table_name: {'Keys': items}})
 

aioradio/aws/moto_server.py

@@ -1,34 +1,40 @@
-'''moto server for pytesting aws services.'''
+"""moto server for pytesting aws services."""
 
 # pylint: disable=too-many-instance-attributes
 # pylint: disable=unused-variable
 
 import asyncio
 import functools
 import logging
+import os
 import socket
 import threading
 import time
-import os
 
 # Third Party
 import aiohttp
 import moto.server
 import werkzeug.serving
 
-
 HOST = '127.0.0.1'
 
 _PYCHARM_HOSTED = os.environ.get('PYCHARM_HOSTED') == '1'
 _CONNECT_TIMEOUT = 90 if _PYCHARM_HOSTED else 10
 
 
-def get_free_tcp_port(release_socket: bool = False):
-    '''Get an available TCP port.'''
+def get_free_tcp_port(release_socket: bool = False) -> tuple:
+    """Get an available TCP port.
+
+    Args:
+        release_socket (bool, optional): release socket. Defaults to False.
+
+    Returns:
+        tuple: socket and port
+    """
 
     sckt = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
     sckt.bind((HOST, 0))
-    addr, port = sckt.getsockname()
+    _, port = sckt.getsockname()
     if release_socket:
         sckt.close()
         return port
@@ -37,8 +43,11 @@ def get_free_tcp_port(release_socket: bool = False):
 
 
 class MotoService:
-    """ Will Create MotoService. Service is ref-counted so there will only be one per process.
-    Real Service will be returned by `__aenter__`."""
+    """Will Create MotoService.
+
+    Service is ref-counted so there will only be one per process. Real
+    Service will be returned by `__aenter__`.
+    """
 
     _services = dict()  # {name: instance}
     _main_app: moto.server.DomainDispatcherApplication = None
@@ -59,8 +68,12 @@ def __init__(self, service_name: str, port: int = None):
         self._server = None
 
     @property
-    def endpoint_url(self):
-        '''Get the server endpoint url.'''
+    def endpoint_url(self) -> str:
+        """Get the server endpoint url.
+
+        Returns:
+            str: url
+        """
 
         return f'http://{self._ip_address}:{self._port}'