Improve assignment schema, fix sanitization bugs, and enhance clients

CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Assignment fields: `image_available_status_code`, `attorney_docket_number`, `domestic_representative`
+- Address fields: `country_or_state_code`, `ict_state_code`, `ict_country_code`
+- PCT application number format support in `sanitize_application_number()`
+
+### Changed
+
+- **BREAKING**: Assignment `correspondence_address_bag` changed to `correspondence_address` (single object, not list)
+- All `PatentDataClient` methods now automatically sanitize application numbers before API requests
+
 ## [0.2.1]
 
 ### Added

examples/patent_data_example.py

@@ -203,6 +203,36 @@
         else:
             print("No documents listed for this application.")
 
+        # Example: Download publication XML (grant or pgpub)
+        print("\nChecking for publication files (grant/pgpub XML)...")
+        if patent_wrapper_detail.grant_document_meta_data:
+            grant_metadata = patent_wrapper_detail.grant_document_meta_data
+            print(f"Grant document available: {grant_metadata.xml_file_name}")
+            print(f"  Product: {grant_metadata.product_identifier}")
+            print(f"  Created: {grant_metadata.file_create_date_time}")
+
+            # Download grant XML to downloads folder with auto-generated filename
+            print("\nDownloading grant XML...")
+            grant_path = client.download_publication(
+                printed_metadata=grant_metadata,
+                destination_path="./download-example",
+                overwrite=True,
+            )
+            print(f"Downloaded grant XML to: {grant_path}")
+
+        if patent_wrapper_detail.pgpub_document_meta_data:
+            pgpub_metadata = patent_wrapper_detail.pgpub_document_meta_data
+            print(f"\nPre-grant publication available: {pgpub_metadata.xml_file_name}")
+
+            # Download with custom filename
+            pgpub_path = client.download_publication(
+                printed_metadata=pgpub_metadata,
+                file_name="my_pgpub.xml",
+                destination_path="./download-example",
+                overwrite=True,
+            )
+            print(f"Downloaded pgpub XML to: {pgpub_path}")
+
         if patent_wrapper_detail.assignment_bag:
             print("\nAssignments:")
             for assignment in patent_wrapper_detail.assignment_bag:

src/pyUSPTO/clients/base.py

@@ -313,6 +313,44 @@ def _extract_filename_from_content_disposition(
 
         return None
 
+    @staticmethod
+    def _get_extension_from_mime_type(mime_type: Optional[str]) -> Optional[str]:
+        """Map MIME type to file extension.
+
+        Maps common USPTO file formats to their appropriate extensions.
+
+        Args:
+            mime_type: The MIME type from Content-Type header (e.g., "application/pdf").
+
+        Returns:
+            Optional[str]: File extension including dot (e.g., ".pdf"), or None if unmapped.
+
+        Examples:
+            >>> _get_extension_from_mime_type("application/pdf")
+            '.pdf'
+            >>> _get_extension_from_mime_type("image/tiff")
+            '.tif'
+            >>> _get_extension_from_mime_type("unknown/type")
+            None
+        """
+        if not mime_type:
+            return None
+
+        # Normalize MIME type (remove charset and other parameters)
+        mime_type = mime_type.split(";")[0].strip().lower()
+
+        # Map of common USPTO file MIME types to extensions
+        mime_to_ext = {
+            "application/pdf": ".pdf",
+            "image/tiff": ".tif",
+            "image/tif": ".tif",
+            "application/xml": ".xml",
+            "text/xml": ".xml",
+            "application/zip": ".zip",
+        }
+
+        return mime_to_ext.get(mime_type)
+
     def _save_response_to_file(
         self, response: requests.Response, file_path: str, overwrite: bool = False
     ) -> str:
@@ -321,6 +359,9 @@ def _save_response_to_file(
         If file_path is a directory, attempts to extract filename from
         Content-Disposition header and save in that directory.
 
+        If file_path has no extension and Content-Disposition doesn't provide
+        a filename, attempts to determine extension from Content-Type header.
+
         Args:
             response: Streaming response object from requests
             file_path: Local path where file should be saved. Can be a file path
@@ -348,6 +389,16 @@ def _save_response_to_file(
                     "header does not contain a filename. Please provide a full file path."
                 )
             path = path / filename
+        # If path has no extension, try to determine it from Content-Type
+        elif not path.suffix:
+            # Only attempt if Content-Disposition doesn't already provide filename
+            content_disp = response.headers.get("Content-Disposition")
+            if not self._extract_filename_from_content_disposition(content_disp):
+                # Try to get extension from Content-Type header
+                content_type = response.headers.get("Content-Type")
+                extension = self._get_extension_from_mime_type(content_type)
+                if extension:
+                    path = path.with_suffix(extension)
 
         # Check for existing file
         if path.exists() and not overwrite: