feat: [SYNC-3835] pydocstyle implementation (#585)

Implement pydocstyle and add valid docstrings to describe functionality.

.circleci/config.yml

@@ -74,7 +74,7 @@ jobs:
             pip install --upgrade pip
             pip install poetry
       - run:
-          name: isort, black, flake8 and mypy
+          name: isort, black, flake8, pydocstyle and mypy
           command: make lint
 
   test:
@@ -84,7 +84,7 @@ jobs:
           username: $DOCKER_USER
           password: $DOCKER_PASS
         environment:
-            RUST_BACKTRACE: 1
+          RUST_BACKTRACE: 1
       - image: amazon/dynamodb-local:latest
         auth:
           username: $DOCKER_USER

.dockerignore

@@ -1,5 +1,6 @@
 .DS_Store
 .git
+.install.stamp
 .svn
 *.pyc
 *.egg-info

.gitignore

@@ -44,4 +44,7 @@ docs/old
 .vscode/*
 
 # circleCI
-workspace
+workspace
+
+# For poetry install
+.install.stamp

Makefile

@@ -8,15 +8,24 @@ LOAD_TEST_DIR := $(TESTS_DIR)/load
 POETRY := poetry --directory $(TESTS_DIR)
 DOCKER_COMPOSE := docker compose
 PYPROJECT_TOML := $(TESTS_DIR)/pyproject.toml
+POETRY_LOCK := $(TESTS_DIR)/poetry.lock
 FLAKE8_CONFIG := $(TESTS_DIR)/.flake8
 LOCUST_HOST := "wss://autoconnect.stage.mozaws.net"
+INSTALL_STAMP := .install.stamp
 
 .PHONY: ddb
 
 ddb:
 	mkdir $@
 	curl -sSL http://dynamodb-local.s3-website-us-west-2.amazonaws.com/dynamodb_local_latest.tar.gz | tar xzvC $@
 
+.PHONY: install
+install: $(INSTALL_STAMP)  ##  Install dependencies with poetry
+$(INSTALL_STAMP): $(PYPROJECT_TOML) $(POETRY_LOCK)
+	@if [ -z $(POETRY) ]; then echo "Poetry could not be found. See https://python-poetry.org/docs/"; exit 2; fi
+	$(POETRY) install
+	touch $(INSTALL_STAMP)
+
 upgrade:
 	$(CARGO) install cargo-edit ||
 		echo "\n$(CARGO) install cargo-edit failed, continuing.."
@@ -37,12 +46,17 @@ integration-test:
 		--junit-xml=$(TEST_RESULTS_DIR)/integration_test_results.xml \
 		-v $(PYTEST_ARGS)
 
+.PHONY: pydocstyle
+pydocstyle: $(INSTALL_STAMP)  ##  Run pydocstyle
+	$(POETRY) run pydocstyle -es $(TESTS_DIR) --count --config=$(PYPROJECT_TOML)
+
 lint:
 	$(POETRY) -V
 	$(POETRY) install --no-root
 	$(POETRY) run isort --sp $(PYPROJECT_TOML) -c $(TESTS_DIR)
 	$(POETRY) run black --quiet --diff --config $(PYPROJECT_TOML) --check $(TESTS_DIR)
 	$(POETRY) run flake8 --config $(FLAKE8_CONFIG) $(TESTS_DIR)
+	$(POETRY) run pydocstyle --config=$(PYPROJECT_TOML)
 	$(POETRY) run mypy $(TESTS_DIR) --config-file=$(PYPROJECT_TOML)
 
 load:

scripts/fernet_key.py

@@ -1,6 +1,4 @@
-"""
-A command-line utility that generates endpoint encryption keys.
-"""
+"""A command-line utility that generates endpoint encryption keys."""
 
 from __future__ import print_function
 from cryptography.fernet import Fernet

scripts/gendpoint.py

@@ -1,5 +1,7 @@
+"""Module to process configuration from cli arguments and environment
+variables.
+"""
 #! env python3
-
 import argparse
 import os
 
@@ -35,6 +37,7 @@ def config(env_args: os._Environ) -> argparse.Namespace:
 
 
 def main():
+    """Process environment arguments/variables and set key."""
     args = config(os.environ)
     if isinstance(args.key, list):
         key = args.key[0]

tests/integration/__init__.py

@@ -0,0 +1 @@
+"""__init__.py for integration tests."""

tests/integration/db.py

@@ -59,6 +59,8 @@ class ItemNotFound(Exception):
 
 
 class DynamoDBResource(threading.local):
+    """DynamoDBResource class subclassing threading.local"""
+
     def __init__(self, **kwargs):
         conf = kwargs
         if not conf.get("endpoint_url"):
@@ -87,7 +89,7 @@ def __getattr__(self, name):
     def get_latest_message_tablenames(
         self, prefix: str = "message", previous: int = 1
     ) -> list[str]:
-        """Fetches the name of the last message table"""
+        """Fetch the name of the last message table."""
         client = self._resource.meta.client
         paginator = client.get_paginator("list_tables")
         tables = []
@@ -102,11 +104,13 @@ def get_latest_message_tablenames(
         return tables[0 - previous :]
 
     def get_latest_message_tablename(self, prefix: str = "message") -> str:
-        """Fetches the name of the last message table"""
+        """Fetch the name of the last message table."""
         return self.get_latest_message_tablenames(prefix=prefix, previous=1)[0]
 
 
 class DynamoDBTable(threading.local):
+    """DynamoDBTable class."""
+
     def __init__(self, ddb_resource: DynamoDBResource, *args, **kwargs) -> None:
         self._table = ddb_resource.Table(*args, **kwargs)
 
@@ -118,13 +122,24 @@ def __getattr__(self, name):
 def generate_hash(key: bytes, payload: bytes) -> str:
     """Generate a HMAC for the uaid using the secret
 
-    :returns: HMAC hash and the nonce used as a tuple (nonce, hash).
+    :param key: key
+    :type: bytes
+    :param payload: payload
+    :type: bytes
+    :returns: A hexadecimal string of the HMAC hash and the nonce, used as a tuple (nonce, hash)
+    :rtype: str
     """
     h = hmac.new(key=key, msg=payload, digestmod=hashlib.sha256)
     return h.hexdigest()
 
 
 def normalize_id(ident: uuid.UUID | str) -> str:
+    """Normalize and return ID as string
+
+    :param ident: uuid.UUID or str identifier
+    :returns: string representation of UUID
+    :raises ValueError: raises an exception if UUID is invalid
+    """
     if isinstance(ident, uuid.UUID):
         return str(ident)
     try:
@@ -134,9 +149,10 @@ def normalize_id(ident: uuid.UUID | str) -> str:
 
 
 def base64url_encode(value: bytes | str) -> str:
+    """Encode an unpadded Base64 URL-encoded string per RFC 7515."""
     if isinstance(value, str):
         value = bytes(value, "utf-8")
-    """Encodes an unpadded Base64 URL-encoded string per RFC 7515."""
+
     return base64.urlsafe_b64encode(value).strip(b"=").decode("utf-8")
 
 
@@ -155,9 +171,7 @@ def base64url_encode(value: bytes | str) -> str:
 
 
 def get_month(delta: int = 0) -> datetime.date:
-    """Basic helper function to get a datetime.date object iterations months
-    ahead/behind of now.
-    """
+    """Get a datetime.date object iterations months ahead/behind of now."""
     new = last = datetime.date.today()
     # Move until we hit a new month, this avoids having to manually
     # check year changes as we push forward or backward since the Python
@@ -308,7 +322,8 @@ def get_router_table(
 
 def track_provisioned(func: Callable[..., T]) -> Callable[..., T]:
     """Tracks provisioned exceptions and increments a metric for them named
-    after the function decorated"""
+    after the function decorated.
+    """
 
     @wraps(func)
     def wrapper(self, *args, **kwargs):