otdf-python 0.3.5__py3-none-any.whl → 0.4.1__py3-none-any.whl

otdf_python/manifest.py

@@ -1,3 +1,5 @@
+"""TDF manifest representation and serialization."""
+
 import json
 from dataclasses import asdict, dataclass, field
 from typing import Any
@@ -5,6 +7,8 @@ from typing import Any
 
 @dataclass
 class ManifestSegment:
+    """Encrypted segment information in TDF manifest."""
+
     hash: str
     segmentSize: int
     encryptedSegmentSize: int
@@ -12,12 +16,16 @@ class ManifestSegment:
 
 @dataclass
 class ManifestRootSignature:
+    """Root signature for manifest integrity."""
+
     alg: str
     sig: str
 
 
 @dataclass
 class ManifestIntegrityInformation:
+    """Manifest integrity information with signatures and hashes."""
+
     rootSignature: ManifestRootSignature
     segmentHashAlg: str
     segmentSizeDefault: int
@@ -27,12 +35,16 @@ class ManifestIntegrityInformation:
 
 @dataclass
 class ManifestPolicyBinding:
+    """Policy binding with algorithm and hash."""
+
     alg: str
     hash: str
 
 
 @dataclass
 class ManifestKeyAccess:
+    """Key access information in manifest."""
+
     type: str
     url: str
     protocol: str
@@ -47,6 +59,8 @@ class ManifestKeyAccess:
 
 @dataclass
 class ManifestMethod:
+    """Encryption method information in manifest."""
+
     algorithm: str
     iv: str
     isStreamable: bool | None = None
@@ -54,6 +68,8 @@ class ManifestMethod:
 
 @dataclass
 class ManifestEncryptionInformation:
+    """Encryption information in TDF manifest."""
+
     type: str
     policy: str
     keyAccess: list[ManifestKeyAccess]
@@ -63,6 +79,8 @@ class ManifestEncryptionInformation:
 
 @dataclass
 class ManifestPayload:
+    """Payload information in TDF manifest."""
+
     type: str
     url: str
     protocol: str
@@ -72,12 +90,16 @@ class ManifestPayload:
 
 @dataclass
 class ManifestBinding:
+    """Assertion binding information."""
+
     method: str
     signature: str
 
 
 @dataclass
 class ManifestAssertion:
+    """TDF assertion in manifest."""
+
     id: str
     type: str
     scope: str
@@ -88,6 +110,8 @@ class ManifestAssertion:
 
 @dataclass
 class Manifest:
+    """TDF manifest with encryption and payload information."""
+
     schemaVersion: str | None = None
     encryptionInformation: ManifestEncryptionInformation | None = None
     payload: ManifestPayload | None = None

otdf_python/nanotdf.py

@@ -1,3 +1,5 @@
+"""NanoTDF reader and writer implementation."""
+
 import contextlib
 import hashlib
 import json
@@ -24,22 +26,32 @@ from .asym_crypto import AsymDecryption
 
 
 class NanoTDFException(SDKException):
+    """Base exception for NanoTDF operations."""
+
     pass
 
 
 class NanoTDFMaxSizeLimit(NanoTDFException):
+    """Exception for NanoTDF size limit exceeded."""
+
     pass
 
 
 class UnsupportedNanoTDFFeature(NanoTDFException):
+    """Exception for unsupported NanoTDF features."""
+
     pass
 
 
 class InvalidNanoTDFConfig(NanoTDFException):
+    """Exception for invalid NanoTDF configuration."""
+
     pass
 
 
 class NanoTDF:
+    """NanoTDF reader and writer for compact TDF format."""
+
     MAGIC_NUMBER_AND_VERSION = MAGIC_NUMBER_AND_VERSION
     K_MAX_TDF_SIZE = (16 * 1024 * 1024) - 3 - 32
     K_NANOTDF_GMAC_LENGTH = 8
@@ -48,6 +60,7 @@ class NanoTDF:
     K_EMPTY_IV = bytes([0x0] * 12)
 
     def __init__(self, services=None, collection_store: CollectionStore | None = None):
+        """Initialize NanoTDF reader/writer."""
         self.services = services
         self.collection_store = collection_store or NoOpCollectionStore()
 
@@ -59,7 +72,7 @@ class NanoTDF:
         return PolicyObject(uuid=policy_uuid, body=body)
 
     def _serialize_policy_object(self, obj):
-        """Custom NanoTDF serializer to convert to compatible JSON format."""
+        """Serialize policy object to compatible JSON format."""
         from otdf_python.policy_object import AttributeObject, PolicyBody
 
         if isinstance(obj, PolicyBody):
@@ -82,8 +95,7 @@ class NanoTDF:
             return obj.__dict__
 
     def _prepare_payload(self, payload: bytes | BytesIO) -> bytes:
-        """
-        Convert BytesIO to bytes and validate payload size.
+        """Convert BytesIO to bytes and validate payload size.
 
         Args:
             payload: The payload data as bytes or BytesIO
@@ -93,6 +105,7 @@ class NanoTDF:
 
         Raises:
             NanoTDFMaxSizeLimit: If the payload exceeds the maximum size
+
         """
         if isinstance(payload, BytesIO):
             payload = payload.getvalue()
@@ -101,14 +114,14 @@ class NanoTDF:
         return payload
 
     def _prepare_policy_data(self, config: NanoTDFConfig) -> tuple[bytes, str]:
-        """
-        Prepare policy data from configuration.
+        """Prepare policy data from configuration.
 
         Args:
             config: NanoTDFConfig configuration
 
         Returns:
             tuple: (policy_body, policy_type)
+
         """
         attributes = config.attributes if config.attributes else []
         policy_object = self._create_policy_object(attributes)
@@ -150,8 +163,7 @@ class NanoTDF:
         config: NanoTDFConfig,
         ephemeral_public_key: bytes | None = None,
     ) -> bytes:
-        """
-        Create the NanoTDF header.
+        """Create the NanoTDF header.
 
         Args:
             policy_body: The policy body bytes
@@ -161,6 +173,7 @@ class NanoTDF:
 
         Returns:
             bytes: The header bytes
+
         """
         from otdf_python.header import Header  # Local import to avoid circular import
 
@@ -228,8 +241,7 @@ class NanoTDF:
         return self.MAGIC_NUMBER_AND_VERSION + header_bytes
 
     def _is_ec_key(self, key_pem: str) -> bool:
-        """
-        Detect if a PEM key is an EC key (vs RSA).
+        """Detect if a PEM key is an EC key (vs RSA).
 
         Args:
             key_pem: PEM-formatted key string
@@ -239,6 +251,7 @@ class NanoTDF:
 
         Raises:
             SDKException: If key cannot be parsed
+
         """
         try:
             # Try to load as public key first
@@ -260,13 +273,12 @@ class NanoTDF:
             else:
                 raise SDKException("Invalid PEM format - no BEGIN header found")
         except Exception as e:
-            raise SDKException(f"Failed to detect key type: {e}")
+            raise SDKException(f"Failed to detect key type: {e}") from e
 
     def _derive_key_with_ecdh(  # noqa: C901
         self, config: NanoTDFConfig
     ) -> tuple[bytes, bytes | None, bytes | None]:
-        """
-        Derive encryption key using ECDH if KAS public key is provided or can be fetched.
+        """Derive encryption key using ECDH if KAS public key is provided or can be fetched.
 
         This implements the NanoTDF spec's ECDH + HKDF key derivation:
         1. Generate ephemeral keypair
@@ -283,6 +295,7 @@ class NanoTDF:
                 - derived_key: 32-byte AES-256 key for encrypting the payload
                 - ephemeral_public_key_compressed: Compressed ephemeral public key to store in header (None for RSA)
                 - kas_public_key: KAS public key PEM string (or None if not available)
+
         """
         import logging
 
@@ -384,8 +397,7 @@ class NanoTDF:
         return derived_key, ephemeral_public_key_compressed, kas_public_key
 
     def _encrypt_payload(self, payload: bytes, key: bytes) -> tuple[bytes, bytes]:
-        """
-        Encrypt the payload using AES-GCM.
+        """Encrypt the payload using AES-GCM.
 
         Args:
             payload: The payload to encrypt
@@ -393,6 +405,7 @@ class NanoTDF:
 
         Returns:
             tuple: (iv, ciphertext)
+
         """
         iv = secrets.token_bytes(self.K_NANOTDF_IV_SIZE)
         iv_padded = self.K_EMPTY_IV[: self.K_IV_PADDING] + iv
@@ -403,8 +416,7 @@ class NanoTDF:
     def create_nano_tdf(
         self, payload: bytes | BytesIO, output_stream: BinaryIO, config: NanoTDFConfig
     ) -> int:
-        """
-        Stream-based NanoTDF creation - writes encrypted payload to an output stream.
+        """Stream-based NanoTDF creation - writes encrypted payload to an output stream.
 
         For convenience method that returns bytes, use create_nanotdf() instead.
         Supports ECDH key derivation if KAS info with public key is provided in config.
@@ -422,8 +434,8 @@ class NanoTDF:
             UnsupportedNanoTDFFeature: If an unsupported feature is requested
             InvalidNanoTDFConfig: If the configuration is invalid
             SDKException: For other errors
-        """
 
+        """
         # Process payload and validate size
         payload = self._prepare_payload(payload)
 
@@ -557,8 +569,7 @@ class NanoTDF:
         output_stream: BinaryIO,
         config: NanoTDFConfig,
     ) -> None:
-        """
-        Stream-based NanoTDF decryption - writes decrypted payload to an output stream.
+        """Stream-based NanoTDF decryption - writes decrypted payload to an output stream.
 
         For convenience method that returns bytes, use read_nanotdf() instead.
         Supports ECDH key derivation and KAS key unwrapping.
@@ -571,6 +582,7 @@ class NanoTDF:
         Raises:
             InvalidNanoTDFConfig: If the NanoTDF format is invalid or config is missing required info
             SDKException: For other errors
+
         """
         # Convert to bytes if BytesIO
         if isinstance(nano_tdf_data, BytesIO):
@@ -582,7 +594,7 @@ class NanoTDF:
             header_len = Header.peek_length(nano_tdf_data)
             header_obj = Header.from_bytes(nano_tdf_data[:header_len])
         except Exception as e:
-            raise InvalidNanoTDFConfig(f"Failed to parse NanoTDF header: {e}")
+            raise InvalidNanoTDFConfig(f"Failed to parse NanoTDF header: {e}") from e
 
         # Read payload section per NanoTDF spec:
         # [3 bytes: length] [3 bytes: IV] [variable: ciphertext] [tag]
@@ -768,8 +780,7 @@ class NanoTDF:
         return key, config
 
     def create_nanotdf(self, data: bytes, config: dict | NanoTDFConfig) -> bytes:
-        """
-        Convenience method - creates a NanoTDF and returns the encrypted bytes.
+        """Create a NanoTDF and return the encrypted bytes.
 
         For stream-based version, use create_nano_tdf() instead.
         """
@@ -846,8 +857,7 @@ class NanoTDF:
     def read_nanotdf(
         self, nanotdf_bytes: bytes, config: dict | NanoTDFConfig | None = None
     ) -> bytes:
-        """
-        Convenience method - decrypts a NanoTDF and returns the plaintext bytes.
+        """Decrypt a NanoTDF and return the plaintext bytes.
 
         For stream-based version, use read_nano_tdf() instead.
         """

otdf_python/nanotdf_ecdsa_struct.py

@@ -1,6 +1,4 @@
-"""
-NanoTDF ECDSA Signature Structure.
-"""
+"""NanoTDF ECDSA Signature Structure."""
 
 from dataclasses import dataclass, field
 
@@ -13,8 +11,7 @@ class IncorrectNanoTDFECDSASignatureSize(Exception):
 
 @dataclass
 class NanoTDFECDSAStruct:
-    """
-    Class to handle ECDSA signature structure for NanoTDF.
+    """Class to handle ECDSA signature structure for NanoTDF.
 
     This structure represents an ECDSA signature as required by the NanoTDF format.
     It consists of r and s values along with their lengths.
@@ -29,8 +26,7 @@ class NanoTDFECDSAStruct:
     def from_bytes(
         cls, ecdsa_signature_value: bytes, key_size: int
     ) -> "NanoTDFECDSAStruct":
-        """
-        Create a NanoTDFECDSAStruct from a byte array.
+        """Create a NanoTDFECDSAStruct from a byte array.
 
         Args:
             ecdsa_signature_value: The signature value as bytes
@@ -41,6 +37,7 @@ class NanoTDFECDSAStruct:
 
         Raises:
             IncorrectNanoTDFECDSASignatureSize: If the signature buffer size is invalid
+
         """
         if len(ecdsa_signature_value) != (2 * key_size) + 2:
             raise IncorrectNanoTDFECDSASignatureSize(
@@ -72,8 +69,7 @@ class NanoTDFECDSAStruct:
         return struct_obj
 
     def as_bytes(self) -> bytes:
-        """
-        Convert the signature structure to bytes.
+        """Convert the signature structure to bytes.
         Raises ValueError if r_value or s_value is None.
         """
         if self.r_value is None or self.s_value is None:

otdf_python/nanotdf_type.py

@@ -1,7 +1,11 @@
+"""NanoTDF type enumeration."""
+
 from enum import Enum
 
 
 class ECCurve(Enum):
+    """Elliptic curve enumeration for NanoTDF."""
+
     SECP256R1 = "secp256r1"
     SECP384R1 = "secp384r1"
     SECP521R1 = "secp384r1"
@@ -12,11 +16,15 @@ class ECCurve(Enum):
 
 
 class Protocol(Enum):
+    """Protocol enumeration for KAS communication."""
+
     HTTP = "HTTP"
     HTTPS = "HTTPS"
 
 
 class IdentifierType(Enum):
+    """Identifier type enumeration for NanoTDF."""
+
     NONE = 0
     TWO_BYTES = 2
     EIGHT_BYTES = 8
@@ -27,6 +35,8 @@ class IdentifierType(Enum):
 
 
 class PolicyType(Enum):
+    """Policy type enumeration for NanoTDF."""
+
     REMOTE_POLICY = 0
     EMBEDDED_POLICY_PLAIN_TEXT = 1
     EMBEDDED_POLICY_ENCRYPTED = 2
@@ -34,6 +44,8 @@ class PolicyType(Enum):
 
 
 class Cipher(Enum):
+    """Cipher enumeration for NanoTDF encryption."""
+
     AES_256_GCM_64_TAG = 0
     AES_256_GCM_96_TAG = 1
     AES_256_GCM_104_TAG = 2

otdf_python/policy_binding_serializer.py

@@ -1,21 +1,23 @@
+"""Policy binding serialization for HMAC calculation."""
+
 from typing import Any
 
 
 class PolicyBinding:
-    """
-    Represents a policy binding in the TDF manifest.
+    """Represents a policy binding in the TDF manifest.
+
     This is a placeholder implementation as the complete details of
     the PolicyBinding class aren't provided in the code snippets.
     """
 
     def __init__(self, **kwargs):
+        """Initialize policy binding from kwargs."""
         for key, value in kwargs.items():
             setattr(self, key, value)
 
 
 class PolicyBindingSerializer:
-    """
-    Handles serialization and deserialization of policy bindings.
+    """Handles serialization and deserialization of policy bindings.
     This class provides static methods to convert between JSON representations
     and PolicyBinding objects.
     """

otdf_python/policy_info.py

@@ -1,9 +1,15 @@
+"""Policy information handling for NanoTDF."""
+
+
 class PolicyInfo:
+    """Policy information."""
+
     def __init__(
         self,
         policy_type: int = 0,
         body: bytes | None = None,
     ):
+        """Initialize policy information."""
         self.policy_type = policy_type
         self.body = body
 

otdf_python/policy_object.py

@@ -1,8 +1,12 @@
+"""Policy object dataclasses for OpenTDF."""
+
 from dataclasses import dataclass
 
 
 @dataclass
 class AttributeObject:
+    """An attribute object."""
+
     attribute: str
     display_name: str | None = None
     is_default: bool = False
@@ -12,11 +16,15 @@ class AttributeObject:
 
 @dataclass
 class PolicyBody:
+    """A policy body."""
+
     data_attributes: list[AttributeObject]
     dissem: list[str]
 
 
 @dataclass
 class PolicyObject:
+    """A policy object."""
+
     uuid: str
     body: PolicyBody

otdf_python/policy_stub.py

@@ -1,2 +1,4 @@
+"""Policy UUID constants for OpenTDF."""
+
 # TODO: Replace this with a proper Policy UUID values
 NULL_POLICY_UUID: str = "00000000-0000-0000-0000-000000000000"

otdf_python/resource_locator.py

@@ -1,15 +1,19 @@
+"""NanoTDF resource locator handling."""
+
+
 class ResourceLocator:
-    """
-    NanoTDF Resource Locator per the spec:
-    https://github.com/opentdf/spec/blob/main/schema/nanotdf/README.md
+    """Represent NanoTDF Resource Locator per specification.
+
+    See https://github.com/opentdf/spec/blob/main/schema/nanotdf/README.md
 
     Format:
-    - Byte 0: Protocol Enum (bits 0-3) + Identifier Length (bits 4-7)
-      - Protocol: 0x0=HTTP, 0x1=HTTPS, 0xF=Shared Resource Directory
-      - Identifier: 0x0=None, 0x1=2 bytes, 0x2=8 bytes, 0x3=32 bytes
-    - Byte 1: Body Length (1-255 bytes)
-    - Bytes 2-N: Body (URL path)
-    - Bytes N+1-M: Identifier (optional, 0/2/8/32 bytes)
+        - Byte 0: Protocol Enum (bits 0-3) + Identifier Length (bits 4-7)
+          - Protocol: 0x0=HTTP, 0x1=HTTPS, 0xF=Shared Resource Directory
+          - Identifier: 0x0=None, 0x1=2 bytes, 0x2=8 bytes, 0x3=32 bytes
+        - Byte 1: Body Length (1-255 bytes)
+        - Bytes 2-N: Body (URL path)
+        - Bytes N+1-M: Identifier (optional, 0/2/8/32 bytes)
+
     """
 
     # Protocol enum values
@@ -24,6 +28,13 @@ class ResourceLocator:
     IDENTIFIER_32_BYTES = 0x3
 
     def __init__(self, resource_url: str | None = None, identifier: str | None = None):
+        """Initialize resource locator.
+
+        Args:
+            resource_url: URL of the resource
+            identifier: Optional identifier for the resource
+
+        """
         self.resource_url = resource_url or ""
         self.identifier = identifier or ""
 
@@ -71,8 +82,7 @@ class ResourceLocator:
             raise ValueError(f"Identifier too long: {id_len} bytes (max 32)")
 
     def to_bytes(self):
-        """
-        Convert to NanoTDF Resource Locator format per spec.
+        """Convert to NanoTDF Resource Locator format per spec.
 
         Format:
         - Byte 0: Protocol Enum (bits 0-3) + Identifier Length (bits 4-7)
@@ -106,8 +116,7 @@ class ResourceLocator:
 
     @staticmethod
     def from_bytes_with_size(buffer: bytes):  # noqa: C901
-        """
-        Parse NanoTDF Resource Locator from bytes per spec.
+        """Parse NanoTDF Resource Locator from bytes per spec.
 
         Format:
         - Byte 0: Protocol Enum (bits 0-3) + Identifier Length (bits 4-7)