docstring cleanup

nateprewitt · nateprewitt · commit 62730e4a6466 · 2025-02-27T11:18:49.000-07:00
diff --git a/packages/aws-sdk-signers/requirements.txt b/packages/aws-sdk-signers/requirements.txt
diff --git a/packages/aws-sdk-signers/src/aws_sdk_signers/__init__.py b/packages/aws-sdk-signers/src/aws_sdk_signers/__init__.py
@@ -1,10 +1,7 @@
-"""
-Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
-SPDX-License-Identifier: Apache-2.0
-
-AWS SDK Signers provides stand-alone signing functionality for use with
-HTTP tools such as AioHTTP, Curl, Postman, Requests, urllib3, etc.
-"""
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""AWS SDK Signers provides stand-alone signing functionality for use with HTTP tools
+such as AioHTTP, Curl, Postman, Requests, urllib3, etc."""
 
 from __future__ import annotations
 
diff --git a/packages/aws-sdk-signers/src/aws_sdk_signers/_http.py b/packages/aws-sdk-signers/src/aws_sdk_signers/_http.py
@@ -1,8 +1,6 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
 """
-Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
-SPDX-License-Identifier: Apache-2.0
-
-
 NOTE TO THE READER:
 
 This file is _strictly_ temporary and subject to abrupt breaking changes
@@ -61,8 +59,8 @@ def remove(self, value: str) -> None:
             return
 
     def as_string(self, delimiter: str = ",") -> str:
-        """Get delimited string of all values. A comma followed by a space is used
-        by default.
+        """Get delimited string of all values. A comma followed by a space is used by
+        default.
 
         If the ``Field`` has zero values, the empty string is returned. If the ``Field``
         has exactly one value, the value is returned unmodified.
@@ -316,8 +314,9 @@ def __eq__(self, other: object) -> bool:
 
 
 class URIParameters(TypedDict):
-    """TypedDict representing the parameters for the URI class. These need to be
-    kept in sync for the `to_dict` method.
+    """TypedDict representing the parameters for the URI class.
+
+    These need to be kept in sync for the `to_dict` method.
     """
 
     # TODO: Unpack doesn't seem to do what we want, so we need a way to represent
diff --git a/packages/aws-sdk-signers/src/aws_sdk_signers/_identity.py b/packages/aws-sdk-signers/src/aws_sdk_signers/_identity.py
@@ -1,7 +1,5 @@
-"""
-Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
-SPDX-License-Identifier: Apache-2.0
-"""
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
 
 from dataclasses import dataclass
 from datetime import UTC, datetime
diff --git a/packages/aws-sdk-signers/src/aws_sdk_signers/_io.py b/packages/aws-sdk-signers/src/aws_sdk_signers/_io.py
@@ -1,7 +1,5 @@
-"""
-Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
-SPDX-License-Identifier: Apache-2.0
-"""
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
 
 from asyncio import iscoroutinefunction
 from collections.abc import AsyncIterable, AsyncIterator, Awaitable, Callable
@@ -44,8 +42,8 @@ def __init__(self, data: StreamingBlob):
     async def read(self, size: int = -1) -> bytes:
         """Read a number of bytes from the stream.
 
-        :param size: The maximum number of bytes to read. If less than 0, all bytes
-        will be read.
+        :param size: The maximum number of bytes to read. If less than 0, all bytes will
+            be read.
         """
         if self._closed or not self._data:
             raise ValueError("I/O operation on closed file.")
@@ -93,7 +91,7 @@ def iter_chunks(
         """Iterate over the reader in chunks of a given size.
 
         :param chunk_size: The maximum size of each chunk. If less than 0, the entire
-        reader will be read into one chunk.
+            reader will be read into one chunk.
         """
         return _AsyncByteStreamIterator(self.read, chunk_size)
 
@@ -149,8 +147,8 @@ def __init__(self, data: StreamingBlob):
     async def read(self, size: int = -1) -> bytes:
         """Read a number of bytes from the stream.
 
-        :param size: The maximum number of bytes to read. If less than 0, all bytes
-        will be read.
+        :param size: The maximum number of bytes to read. If less than 0, all bytes will
+            be read.
         """
         if self._data_source is None or size == 0:
             return self._buffer.read(size)
@@ -227,7 +225,7 @@ def iter_chunks(
         """Iterate over the reader in chunks of a given size.
 
         :param chunk_size: The maximum size of each chunk. If less than 0, the entire
-        reader will be read into one chunk.
+            reader will be read into one chunk.
         """
         return _AsyncByteStreamIterator(self.read, chunk_size)
 
@@ -263,8 +261,7 @@ def __init__(self, read: Callable[[int], Awaitable[bytes]], chunk_size: int):
         """Initializes self.
 
         :param read: An async callable that reads a given number of bytes from some
-        source.
-
+            source.
         :param chunk_size: The number of bytes to read in each iteration.
         """
         self._read = read
diff --git a/packages/aws-sdk-signers/src/aws_sdk_signers/_version.py b/packages/aws-sdk-signers/src/aws_sdk_signers/_version.py
@@ -1,7 +1,5 @@
-"""
-Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
-SPDX-License-Identifier: Apache-2.0
-"""
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
 
 # This file is protected via CODEOWNERS
 from __future__ import annotations
diff --git a/packages/aws-sdk-signers/src/aws_sdk_signers/exceptions.py b/packages/aws-sdk-signers/src/aws_sdk_signers/exceptions.py
@@ -1,7 +1,5 @@
-"""
-Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
-SPDX-License-Identifier: Apache-2.0
-"""
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
 
 
 class AWSSDKWarning(UserWarning): ...
diff --git a/packages/aws-sdk-signers/src/aws_sdk_signers/interfaces/__init__.py b/packages/aws-sdk-signers/src/aws_sdk_signers/interfaces/__init__.py
@@ -0,0 +1,2 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
diff --git a/packages/aws-sdk-signers/src/aws_sdk_signers/interfaces/http.py b/packages/aws-sdk-signers/src/aws_sdk_signers/interfaces/http.py
@@ -1,7 +1,5 @@
-"""
-Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
-SPDX-License-Identifier: Apache-2.0
-"""
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
 
 from __future__ import annotations
 
@@ -35,8 +33,8 @@ class FieldPosition(Enum):
 class Field(Protocol):
     """A name-value pair representing a single field in a request or response.
 
-    The kind will dictate metadata placement within a message, for example as
-    a header or trailer field in an HTTP request as defined in RFC 9110 Section 5.
+    The kind will dictate metadata placement within a message, for example as a header
+    or trailer field in an HTTP request as defined in RFC 9110 Section 5.
 
     All field names are case insensitive and case-variance must be treated as
     equivalent. Names may be normalized but should be preserved for accuracy during
diff --git a/packages/aws-sdk-signers/src/aws_sdk_signers/interfaces/identity.py b/packages/aws-sdk-signers/src/aws_sdk_signers/interfaces/identity.py
@@ -1,7 +1,5 @@
-"""
-Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
-SPDX-License-Identifier: Apache-2.0
-"""
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
 
 from __future__ import annotations
 
diff --git a/packages/aws-sdk-signers/src/aws_sdk_signers/interfaces/io.py b/packages/aws-sdk-signers/src/aws_sdk_signers/interfaces/io.py
@@ -1,7 +1,5 @@
-"""
-Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
-SPDX-License-Identifier: Apache-2.0
-"""
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
 
 from typing import Protocol, runtime_checkable
 
diff --git a/packages/aws-sdk-signers/src/aws_sdk_signers/signers.py b/packages/aws-sdk-signers/src/aws_sdk_signers/signers.py
@@ -1,7 +1,5 @@
-"""
-Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
-SPDX-License-Identifier: Apache-2.0
-"""
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
 
 import datetime
 import hmac
@@ -43,9 +41,7 @@ class SigV4SigningProperties(TypedDict, total=False):
 
 
 class SigV4Signer:
-    """
-    Request signer for applying the AWS Signature Version 4 algorithm.
-    """
+    """Request signer for applying the AWS Signature Version 4 algorithm."""
 
     def sign(
         self,
@@ -56,13 +52,11 @@ def sign(
     ) -> AWSRequest:
         """Generate and apply a SigV4 Signature to a copy of the supplied request.
 
-        :param signing_properties:
-            SigV4SigningProperties to define signing primitives such as
-            the target service, region, and date.
-        :param request:
-            An AWSRequest to sign prior to sending to the service.
-        :param identity:
-            A set of credentials representing an AWS Identity or role capacity.
+        :param signing_properties: SigV4SigningProperties to define signing primitives
+            such as the target service, region, and date.
+        :param request: An AWSRequest to sign prior to sending to the service.
+        :param identity: A set of credentials representing an AWS Identity or role
+            capacity.
         """
         # Copy and prepopulate any missing values in the
         # supplied request and signing properties.
@@ -107,7 +101,7 @@ def sign(
     def generate_authorization_field(
         self, *, credential: str, signed_headers: list[str], signature: str
     ) -> Field:
-        """Generate the `Authorization` field
+        """Generate the `Authorization` field.
 
         :param credential:
             Credential scope string for generating the Authorization header.
@@ -138,13 +132,15 @@ def _signature(
         In SigV4, a signing key is created that is scoped to a specific region and
         service. The date, region, service and resulting signing key are individually
         hashed, then the composite hash is used to sign the string to sign.
-
-        DateKey              = HMAC-SHA256("AWS4"+"<SecretAccessKey>", "<YYYYMMDD>")
-        DateRegionKey        = HMAC-SHA256(<DateKey>, "<aws-region>")
-        DateRegionServiceKey = HMAC-SHA256(<DateRegionKey>, "<aws-service>")
-        SigningKey           = HMAC-SHA256(<DateRegionServiceKey>, "aws4_request")
         """
         assert signing_properties["date"] is not None
+
+        # Components of Signing Key Calculation
+        #
+        # DateKey              = HMAC-SHA256("AWS4"+"<SecretAccessKey>", "<YYYYMMDD>")
+        # DateRegionKey        = HMAC-SHA256(<DateKey>, "<aws-region>")
+        # DateRegionServiceKey = HMAC-SHA256(<DateRegionKey>, "<aws-service>")
+        # SigningKey = HMAC-SHA256(<DateRegionServiceKey>, "aws4_request")
         k_date = self._hash(
             key=f"AWS4{secret_key}".encode(), value=signing_properties["date"][0:8]
         )
@@ -213,9 +209,9 @@ def _apply_required_fields(
     def canonical_request(
         self, *, signing_properties: SigV4SigningProperties, request: AWSRequest
     ) -> str:
-        """The canonical request is a standardized string laying out the
-        components used in the SigV4 signing algorithm. This is useful to quickly
-        compare inputs to find signature mismatches and unintended variances.
+        """The canonical request is a standardized string laying out the components used
+        in the SigV4 signing algorithm. This is useful to quickly compare inputs to find
+        signature mismatches and unintended variances.
 
         The SigV4 specification defines the canonical request to be:
             <HTTPMethod>\n
@@ -257,9 +253,9 @@ def string_to_sign(
     ) -> str:
         """The string to sign is the second step of our signing algorithm which
         concatenates the formal identifier of our signing algorithm, the signing
-        DateTime, the scope of our credentials, and a hash of our previously
-        generated canonical request. This is another checkpoint that can be used
-        to ensure we're constructing our signature as intended.
+        DateTime, the scope of our credentials, and a hash of our previously generated
+        canonical request. This is another checkpoint that can be used to ensure we're
+        constructing our signature as intended.
 
         The SigV4 specification defines the string to sign as:
             Algorithm \n
@@ -410,9 +406,7 @@ def _compute_payload_hash(
 
 
 class AsyncSigV4Signer:
-    """
-    Request signer for applying the AWS Signature Version 4 algorithm.
-    """
+    """Request signer for applying the AWS Signature Version 4 algorithm."""
 
     async def sign(
         self,
@@ -423,13 +417,11 @@ async def sign(
     ) -> AWSRequest:
         """Generate and apply a SigV4 Signature to a copy of the supplied request.
 
-        :param signing_properties:
-            SigV4SigningProperties to define signing primitives such as
-            the target service, region, and date.
-        :param request:
-            An AWSRequest to sign prior to sending to the service.
-        :param identity:
-            A set of credentials representing an AWS Identity or role capacity.
+        :param signing_properties: SigV4SigningProperties to define signing primitives
+            such as the target service, region, and date.
+        :param request: An AWSRequest to sign prior to sending to the service.
+        :param identity: A set of credentials representing an AWS Identity or role
+            capacity.
         """
         # Copy and prepopulate any missing values in the
         # supplied request and signing properties.
@@ -474,7 +466,7 @@ async def sign(
     async def generate_authorization_field(
         self, *, credential: str, signed_headers: list[str], signature: str
     ) -> Field:
-        """Generate the `Authorization` field
+        """Generate the `Authorization` field.
 
         :param credential:
             Credential scope string for generating the Authorization header.
@@ -505,13 +497,15 @@ async def _signature(
         In SigV4, a signing key is created that is scoped to a specific region and
         service. The date, region, service and resulting signing key are individually
         hashed, then the composite hash is used to sign the string to sign.
-
-        DateKey              = HMAC-SHA256("AWS4"+"<SecretAccessKey>", "<YYYYMMDD>")
-        DateRegionKey        = HMAC-SHA256(<DateKey>, "<aws-region>")
-        DateRegionServiceKey = HMAC-SHA256(<DateRegionKey>, "<aws-service>")
-        SigningKey           = HMAC-SHA256(<DateRegionServiceKey>, "aws4_request")
         """
         assert signing_properties.get("date") is not None
+
+        # Components of Signing Key Calculation
+        #
+        # DateKey              = HMAC-SHA256("AWS4"+"<SecretAccessKey>", "<YYYYMMDD>")
+        # DateRegionKey        = HMAC-SHA256(<DateKey>, "<aws-region>")
+        # DateRegionServiceKey = HMAC-SHA256(<DateRegionKey>, "<aws-service>")
+        # SigningKey = HMAC-SHA256(<DateRegionServiceKey>, "aws4_request")
         k_date = await self._hash(
             key=f"AWS4{secret_key}".encode(), value=signing_properties["date"][0:8]
         )
@@ -581,9 +575,9 @@ async def _apply_required_fields(
     async def canonical_request(
         self, *, signing_properties: SigV4SigningProperties, request: AWSRequest
     ) -> str:
-        """The canonical request is a standardized string laying out the
-        components used in the SigV4 signing algorithm. This is useful to quickly
-        compare inputs to find signature mismatches and unintended variances.
+        """The canonical request is a standardized string laying out the components used
+        in the SigV4 signing algorithm. This is useful to quickly compare inputs to find
+        signature mismatches and unintended variances.
 
         The SigV4 specification defines the canonical request to be:
             <HTTPMethod>\n
@@ -629,9 +623,9 @@ async def string_to_sign(
     ) -> str:
         """The string to sign is the second step of our signing algorithm which
         concatenates the formal identifier of our signing algorithm, the signing
-        DateTime, the scope of our credentials, and a hash of our previously
-        generated canonical request. This is another checkpoint that can be used
-        to ensure we're constructing our signature as intended.
+        DateTime, the scope of our credentials, and a hash of our previously generated
+        canonical request. This is another checkpoint that can be used to ensure we're
+        constructing our signature as intended.
 
         The SigV4 specification defines the string to sign as:
             Algorithm \n
@@ -784,6 +778,7 @@ async def _compute_payload_hash(
 
 def _remove_dot_segments(path: str, remove_consecutive_slashes: bool = True) -> str:
     """Removes dot segments from a path per :rfc:`3986#section-5.2.4`.
+
     Optionally removes consecutive slashes, true by default.
     :param path: The path to modify.
     :param remove_consecutive_slashes: Whether to remove consecutive slashes.
diff --git a/packages/aws-sdk-signers/tests/unit/test_signers.py b/packages/aws-sdk-signers/tests/unit/test_signers.py
@@ -1,7 +1,5 @@
-"""
-Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
-SPDX-License-Identifier: Apache-2.0
-"""
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
 
 import re
 import typing

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.`
	`2`	`+# SPDX-License-Identifier: Apache-2.0`