refactor: update docstrings

Author: madkarmaa

src/streamable/utils/s3.py

@@ -1,4 +1,4 @@
-"""AWS S3 Signature Version 4 utility for generating authentication headers.
+"""AWS S3 Signature V4 utility for generating authentication headers.
 
 This module provides functions to calculate AWS Signature V4 signatures
 and build headers for S3 upload requests.
@@ -9,7 +9,7 @@
 import hashlib
 import hmac
 from datetime import datetime, timezone
-from typing import Optional
+from typing import Literal, Optional, Union
 from urllib.parse import quote
 from ..api.models import UploadInfo
 
@@ -69,7 +69,7 @@ def _create_canonical_request(
     canonical_query_string: str,
     canonical_headers: str,
     signed_headers: str,
-    payload_hash: str,
+    payload_hash: Union[Literal["UNSIGNED-PAYLOAD"], str],
 ) -> str:
     """Create the canonical request string.
 
@@ -126,16 +126,16 @@ def calculate_aws_s3_v4_signature(
     session_token: str,
     region: str,
     timestamp: str,
-    payload_hash: str = "UNSIGNED-PAYLOAD",
+    payload_hash: Union[Literal["UNSIGNED-PAYLOAD"], str] = "UNSIGNED-PAYLOAD",
     query_params: Optional[dict[str, str]] = None,
     extra_headers: Optional[dict[str, str]] = None,
 ) -> tuple[str, str, str]:
     """Calculate AWS S3 V4 signature.
 
     Args:
         method: HTTP method (e.g., 'PUT', 'GET')
-        host: Host header value (e.g., 'streamables-upload.s3.amazonaws.com')
-        path: Request path (e.g., '/upload/y3vwnh')
+        host: Host header value (e.g., 'some-bucket.s3.amazonaws.com')
+        path: Request path (e.g., '/some/key')
         access_key: AWS access key ID
         secret_key: AWS secret access key
         session_token: AWS session token
@@ -223,16 +223,14 @@ def calculate_aws_s3_v4_signature(
 def build_s3_upload_headers(
     upload_info: UploadInfo,
     content_length: int,
-    content_type: str = "application/octet-stream",
     use_current_timestamp: bool = True,
 ) -> dict[str, str]:
     """Build headers for S3 upload request from UploadInfo model.
 
     Args:
         upload_info: UploadInfo pydantic model instance
         content_length: Size of the file being uploaded in bytes
-        content_type: MIME type of the content (default: 'application/octet-stream')
-        use_current_timestamp: If True, generate a new timestamp (recommended for actual uploads)
+        use_current_timestamp: If True, generate a new timestamp (must use for actual uploads)
 
     Returns:
         Dictionary of headers ready for the PUT request
@@ -281,7 +279,7 @@ def build_s3_upload_headers(
     headers: dict[str, str] = {
         "Host": host,
         "Authorization": auth_header,
-        "Content-Type": content_type,
+        "Content-Type": "application/octet-stream",
         "Content-Length": str(content_length),
         "x-amz-content-sha256": "UNSIGNED-PAYLOAD",
         "x-amz-date": timestamp,