shipthisapi-python 2.1.0__tar.gz → 3.0.0__tar.gz

{shipthisapi_python-2.1.0 → shipthisapi_python-3.0.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: shipthisapi-python
-Version: 2.1.0
-Summary: ShipthisAPI utility package
+Version: 3.0.0
+Summary: ShipthisAPI async utility package
 Home-page: https://github.com/shipthisco/shipthisapi-python
 Author: Mayur Rawte
 Author-email: mayur@shipthis.co
@@ -9,12 +9,14 @@ Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24.0
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
 Dynamic: description
 Dynamic: description-content-type
 Dynamic: home-page
+Dynamic: requires-dist
 Dynamic: summary
 
 # ShipthisAPI Python 

{shipthisapi_python-2.1.0 → shipthisapi_python-3.0.0}/ShipthisAPI/__init__.py

@@ -1,5 +1,5 @@
 # __variables__ with double-quoted values will be available in setup.py
-__version__ = "2.1.0"
+__version__ = "3.0.0"
 
 from .shipthisapi import (
     ShipthisAPI,

{shipthisapi_python-2.1.0 → shipthisapi_python-3.0.0}/ShipthisAPI/shipthisapi.py

@@ -1,30 +1,35 @@
 """Shipthis API Client.
 
-A Python client for the Shipthis public API.
+An async Python client for the Shipthis public API.
 
 Usage:
+    import asyncio
     from ShipthisAPI import ShipthisAPI
 
-    client = ShipthisAPI(
-        organisation="your_org_id",
-        x_api_key="your_api_key",
-        region_id="your_region",
-        location_id="your_location"
-    )
+    async def main():
+        # Initialize the client
+        client = ShipthisAPI(
+            organisation="your_org_id",
+            x_api_key="your_api_key",
+            region_id="your_region",
+            location_id="your_location"
+        )
+
+        # Connect and validate
+        await client.connect()
 
-    # Connect and validate
-    client.connect()
+        # Get items from a collection
+        items = await client.get_list("shipment")
 
-    # Get items from a collection
-    items = client.get_list("shipment")
+        # Patch document fields
+        await client.patch_item("fcl_load", doc_id, {"status": "completed"})
 
-    # Get a single item
-    item = client.get_one_item("shipment", doc_id="abc123")
+    asyncio.run(main())
 """
 
-from typing import Any, Dict, List, Optional, Union
+from typing import Any, Dict, List, Optional
 import json
-import requests
+import httpx
 
 
 class ShipthisAPIError(Exception):
@@ -50,7 +55,7 @@ class ShipthisRequestError(ShipthisAPIError):
 
 
 class ShipthisAPI:
-    """Shipthis API client for public API access.
+    """Async Shipthis API client for public API access.
 
     Attributes:
         base_api_endpoint: The base URL for the API.
@@ -60,6 +65,7 @@ class ShipthisAPI:
         region_id: Region ID for requests.
         location_id: Location ID for requests.
         timeout: Request timeout in seconds.
+        custom_headers: Custom headers to override defaults.
     """
 
     DEFAULT_TIMEOUT = 30
@@ -68,28 +74,28 @@ class ShipthisAPI:
     def __init__(
         self,
         organisation: str,
-        x_api_key: str,
+        x_api_key: str = None,
         user_type: str = "employee",
         region_id: str = None,
         location_id: str = None,
         timeout: int = None,
         base_url: str = None,
+        custom_headers: Dict[str, str] = None,
     ) -> None:
         """Initialize the Shipthis API client.
 
         Args:
             organisation: Your organisation ID.
-            x_api_key: Your API key.
+            x_api_key: Your API key (optional if using custom_headers with auth).
             user_type: User type for requests (default: "employee").
             region_id: Region ID for requests.
             location_id: Location ID for requests.
             timeout: Request timeout in seconds (default: 30).
             base_url: Custom base URL (optional, for testing).
+            custom_headers: Custom headers that override defaults.
         """
         if not organisation:
             raise ValueError("organisation is required")
-        if not x_api_key:
-            raise ValueError("x_api_key is required")
 
         self.x_api_key = x_api_key
         self.organisation_id = organisation
@@ -98,6 +104,7 @@ class ShipthisAPI:
         self.location_id = location_id
         self.timeout = timeout or self.DEFAULT_TIMEOUT
         self.base_api_endpoint = base_url or self.BASE_API_ENDPOINT
+        self.custom_headers = custom_headers or {}
         self.organisation_info = None
         self.is_connected = False
 
@@ -111,39 +118,50 @@ class ShipthisAPI:
         self.region_id = region_id
         self.location_id = location_id
 
-    def _get_headers(self) -> Dict[str, str]:
+    def _get_headers(self, override_headers: Dict[str, str] = None) -> Dict[str, str]:
         """Build request headers.
 
+        Args:
+            override_headers: Headers to override for this specific request.
+
         Returns:
             Dictionary of headers.
         """
         headers = {
-            "x-api-key": self.x_api_key,
             "organisation": self.organisation_id,
             "usertype": self.user_type,
             "Content-Type": "application/json",
             "Accept": "application/json",
         }
+        if self.x_api_key:
+            headers["x-api-key"] = self.x_api_key
         if self.region_id:
             headers["region"] = self.region_id
         if self.location_id:
             headers["location"] = self.location_id
+        # Apply custom headers from init
+        headers.update(self.custom_headers)
+        # Apply per-request override headers
+        if override_headers:
+            headers.update(override_headers)
         return headers
 
-    def _make_request(
+    async def _make_request(
         self,
         method: str,
         path: str,
         query_params: Dict[str, Any] = None,
         request_data: Dict[str, Any] = None,
+        headers: Dict[str, str] = None,
     ) -> Dict[str, Any]:
-        """Make an HTTP request to the API.
+        """Make an async HTTP request to the API.
 
         Args:
             method: HTTP method (GET, POST, PUT, PATCH, DELETE).
             path: API endpoint path.
             query_params: Query parameters.
             request_data: Request body data.
+            headers: Headers to override for this request.
 
         Returns:
             API response data.
@@ -153,41 +171,32 @@ class ShipthisAPI:
             ShipthisRequestError: If the request fails.
         """
         url = self.base_api_endpoint + path
-        headers = self._get_headers()
+        request_headers = self._get_headers(headers)
 
-        try:
-            if request_data:
-                response = requests.request(
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            try:
+                response = await client.request(
                     method,
                     url,
-                    json=request_data,
-                    headers=headers,
+                    headers=request_headers,
                     params=query_params,
-                    timeout=self.timeout,
+                    json=request_data,
                 )
-            else:
-                response = requests.request(
-                    method,
-                    url,
-                    headers=headers,
-                    params=query_params,
-                    timeout=self.timeout,
+            except httpx.TimeoutException:
+                raise ShipthisRequestError(
+                    message="Request timed out",
+                    status_code=408,
+                )
+            except httpx.ConnectError as e:
+                raise ShipthisRequestError(
+                    message=f"Connection error: {str(e)}",
+                    status_code=0,
+                )
+            except httpx.RequestError as e:
+                raise ShipthisRequestError(
+                    message=f"Request failed: {str(e)}",
+                    status_code=0,
                 )
-        except requests.exceptions.Timeout:
-            raise ShipthisRequestError(
-                message="Request timed out",
-                status_code=408,
-            )
-        except requests.exceptions.ConnectionError as e:
-            raise ShipthisRequestError(
-                message=f"Connection error: {str(e)}",
-                status_code=0,
-            )
-        except requests.exceptions.RequestException as e:
-            raise ShipthisRequestError(
-                message=f"Request failed: {str(e)}",
-                status_code=0,
-            )
 
         # Handle authentication errors
         if response.status_code == 401:
@@ -235,7 +244,7 @@ class ShipthisAPI:
 
     # ==================== Connection ====================
 
-    def connect(self) -> Dict[str, Any]:
+    async def connect(self) -> Dict[str, Any]:
         """Connect and validate the API connection.
 
         Fetches organisation info and validates region/location.
@@ -247,7 +256,7 @@ class ShipthisAPI:
         Raises:
             ShipthisAPIError: If connection fails.
         """
-        info = self.info()
+        info = await self.info()
         self.organisation_info = info.get("organisation")
 
         if not self.region_id or not self.location_id:
@@ -273,7 +282,7 @@ class ShipthisAPI:
 
     # ==================== Info ====================
 
-    def info(self) -> Dict[str, Any]:
+    async def info(self) -> Dict[str, Any]:
         """Get organisation and user info.
 
         Returns:
@@ -282,11 +291,11 @@ class ShipthisAPI:
         Raises:
             ShipthisAPIError: If the request fails.
         """
-        return self._make_request("GET", "user-auth/info")
+        return await self._make_request("GET", "user-auth/info")
 
     # ==================== Collection CRUD ====================
 
-    def get_one_item(
+    async def get_one_item(
         self,
         collection_name: str,
         doc_id: str = None,
@@ -312,19 +321,19 @@ class ShipthisAPI:
             params = {}
             if only_fields:
                 params["only"] = only_fields
-            return self._make_request("GET", path, query_params=params if params else None)
+            return await self._make_request("GET", path, query_params=params if params else None)
         else:
             params = {}
             if filters:
                 params["query_filter_v2"] = json.dumps(filters)
             if only_fields:
                 params["only"] = only_fields
-            resp = self._make_request("GET", f"incollection/{collection_name}", params)
+            resp = await self._make_request("GET", f"incollection/{collection_name}", params)
             if isinstance(resp, dict) and resp.get("items"):
                 return resp.get("items")[0]
             return None
 
-    def get_list(
+    async def get_list(
         self,
         collection_name: str,
         filters: Dict[str, Any] = None,
@@ -369,13 +378,13 @@ class ShipthisAPI:
         if not meta:
             params["meta"] = "false"
 
-        response = self._make_request("GET", f"incollection/{collection_name}", params)
+        response = await self._make_request("GET", f"incollection/{collection_name}", params)
 
         if isinstance(response, dict):
             return response.get("items", [])
         return []
 
-    def search(
+    async def search(
         self,
         collection_name: str,
         query: str,
@@ -398,7 +407,7 @@ class ShipthisAPI:
         Raises:
             ShipthisAPIError: If the request fails.
         """
-        return self.get_list(
+        return await self.get_list(
             collection_name,
             search_query=query,
             page=page,
@@ -406,7 +415,7 @@ class ShipthisAPI:
             only_fields=only_fields,
         )
 
-    def create_item(
+    async def create_item(
         self, collection_name: str, data: Dict[str, Any]
     ) -> Dict[str, Any]:
         """Create a new item in a collection.
@@ -421,7 +430,7 @@ class ShipthisAPI:
         Raises:
             ShipthisAPIError: If the request fails.
         """
-        resp = self._make_request(
+        resp = await self._make_request(
             "POST",
             f"incollection/{collection_name}",
             request_data={"reqbody": data},
@@ -430,7 +439,7 @@ class ShipthisAPI:
             return resp.get("data")
         return resp
 
-    def update_item(
+    async def update_item(
         self,
         collection_name: str,
         object_id: str,
@@ -449,7 +458,7 @@ class ShipthisAPI:
         Raises:
             ShipthisAPIError: If the request fails.
         """
-        resp = self._make_request(
+        resp = await self._make_request(
             "PUT",
             f"incollection/{collection_name}/{object_id}",
             request_data={"reqbody": updated_data},
@@ -458,7 +467,7 @@ class ShipthisAPI:
             return resp.get("data")
         return resp
 
-    def patch_item(
+    async def patch_item(
         self,
         collection_name: str,
         object_id: str,
@@ -466,24 +475,34 @@ class ShipthisAPI:
     ) -> Dict[str, Any]:
         """Patch specific fields of an item.
 
+        This is the recommended way to update document fields. It goes through
+        full field validation, workflow triggers, audit logging, and business logic.
+
         Args:
-            collection_name: Name of the collection.
+            collection_name: Name of the collection (e.g., "sea_shipment", "fcl_load").
             object_id: Document ID.
-            update_fields: Fields to update.
+            update_fields: Dictionary of field_id to value mappings.
 
         Returns:
             Updated document data.
 
         Raises:
             ShipthisAPIError: If the request fails.
+
+        Example:
+            await client.patch_item(
+                "fcl_load",
+                "68a4f906743189ad061429a7",
+                update_fields={"container_no": "CONT123", "seal_no": "SEAL456"}
+            )
         """
-        return self._make_request(
+        return await self._make_request(
             "PATCH",
             f"incollection/{collection_name}/{object_id}",
             request_data={"update_fields": update_fields},
         )
 
-    def delete_item(self, collection_name: str, object_id: str) -> Dict[str, Any]:
+    async def delete_item(self, collection_name: str, object_id: str) -> Dict[str, Any]:
         """Delete an item.
 
         Args:
@@ -496,14 +515,14 @@ class ShipthisAPI:
         Raises:
             ShipthisAPIError: If the request fails.
         """
-        return self._make_request(
+        return await self._make_request(
             "DELETE",
             f"incollection/{collection_name}/{object_id}",
         )
 
     # ==================== Workflow Operations ====================
 
-    def get_job_status(
+    async def get_job_status(
         self, collection_name: str, object_id: str
     ) -> Dict[str, Any]:
         """Get the job status for a document.
@@ -518,12 +537,12 @@ class ShipthisAPI:
         Raises:
             ShipthisAPIError: If the request fails.
         """
-        return self._make_request(
+        return await self._make_request(
             "GET",
             f"workflow/{collection_name}/job_status/{object_id}",
         )
 
-    def set_job_status(
+    async def set_job_status(
         self,
         collection_name: str,
         object_id: str,
@@ -542,13 +561,13 @@ class ShipthisAPI:
         Raises:
             ShipthisAPIError: If the request fails.
         """
-        return self._make_request(
+        return await self._make_request(
             "POST",
             f"workflow/{collection_name}/job_status/{object_id}",
             request_data={"action_index": action_index},
         )
 
-    def get_workflow(self, object_id: str) -> Dict[str, Any]:
+    async def get_workflow(self, object_id: str) -> Dict[str, Any]:
         """Get a workflow configuration.
 
         Args:
@@ -560,11 +579,11 @@ class ShipthisAPI:
         Raises:
             ShipthisAPIError: If the request fails.
         """
-        return self._make_request("GET", f"incollection/workflow/{object_id}")
+        return await self._make_request("GET", f"incollection/workflow/{object_id}")
 
     # ==================== Reports ====================
 
-    def get_report_view(
+    async def get_report_view(
         self,
         report_name: str,
         start_date: str,
@@ -598,7 +617,7 @@ class ShipthisAPI:
         if self.location_id:
             params["location"] = self.location_id
 
-        return self._make_request(
+        return await self._make_request(
             "POST",
             f"report-view/{report_name}",
             query_params=params,
@@ -607,7 +626,7 @@ class ShipthisAPI:
 
     # ==================== Third-party Services ====================
 
-    def get_exchange_rate(
+    async def get_exchange_rate(
         self,
         source_currency: str,
         target_currency: str = "USD",
@@ -630,12 +649,12 @@ class ShipthisAPI:
         if date is None:
             date = int(time.time() * 1000)
 
-        return self._make_request(
+        return await self._make_request(
             "GET",
             f"thirdparty/currency?source={source_currency}&target={target_currency}&date={date}",
         )
 
-    def autocomplete(
+    async def autocomplete(
         self,
         reference_name: str,
         data: Dict[str, Any],
@@ -656,14 +675,14 @@ class ShipthisAPI:
         if self.location_id:
             params["location"] = self.location_id
 
-        return self._make_request(
+        return await self._make_request(
             "POST",
             f"autocomplete-reference/{reference_name}",
             query_params=params if params else None,
             request_data=data,
         )
 
-    def search_location(self, query: str) -> List[Dict[str, Any]]:
+    async def search_location(self, query: str) -> List[Dict[str, Any]]:
         """Search for locations using Google Places.
 
         Args:
@@ -675,12 +694,12 @@ class ShipthisAPI:
         Raises:
             ShipthisAPIError: If the request fails.
         """
-        return self._make_request(
+        return await self._make_request(
             "GET",
             f"thirdparty/search-place-autocomplete?query={query}",
         )
 
-    def get_place_details(
+    async def get_place_details(
         self,
         place_id: str,
         description: str = "",
@@ -697,14 +716,14 @@ class ShipthisAPI:
         Raises:
             ShipthisAPIError: If the request fails.
         """
-        return self._make_request(
+        return await self._make_request(
             "GET",
             f"thirdparty/select-google-place?query={place_id}&description={description}",
         )
 
     # ==================== Conversations ====================
 
-    def create_conversation(
+    async def create_conversation(
         self,
         view_name: str,
         document_id: str,
@@ -729,9 +748,9 @@ class ShipthisAPI:
             "view_name": view_name,
             "message_type": conversation_data.get("type", ""),
         }
-        return self._make_request("POST", "conversation", request_data=payload)
+        return await self._make_request("POST", "conversation", request_data=payload)
 
-    def get_conversations(
+    async def get_conversations(
         self,
         view_name: str,
         document_id: str,
@@ -762,11 +781,11 @@ class ShipthisAPI:
             "message_type": message_type,
             "version": "2",
         }
-        return self._make_request("GET", "conversation", query_params=params)
+        return await self._make_request("GET", "conversation", query_params=params)
 
     # ==================== Bulk Operations ====================
 
-    def bulk_edit(
+    async def bulk_edit(
         self,
         collection_name: str,
         ids: List[str],
@@ -788,7 +807,7 @@ class ShipthisAPI:
             ShipthisAPIError: If the request fails.
 
         Example:
-            client.bulk_edit(
+            await client.bulk_edit(
                 "customer",
                 ids=["5fdc00487f7636c97b9fa064", "608fe19fc33215427867f34e"],
                 update_data={"company.fax_no": "12323231", "address.state": "California"}
@@ -803,7 +822,7 @@ class ShipthisAPI:
         if external_update_data:
             payload["data"]["external_update_data"] = external_update_data
 
-        return self._make_request(
+        return await self._make_request(
             "POST",
             f"incollection_group_edit/{collection_name}",
             request_data=payload,
@@ -811,7 +830,7 @@ class ShipthisAPI:
 
     # ==================== Workflow Actions ====================
 
-    def primary_workflow_action(
+    async def primary_workflow_action(
         self,
         collection: str,
         workflow_id: str,
@@ -837,7 +856,7 @@ class ShipthisAPI:
             ShipthisAPIError: If the request fails.
 
         Example:
-            client.primary_workflow_action(
+            await client.primary_workflow_action(
                 collection="pickup_delivery",
                 workflow_id="job_status",
                 object_id="68a4f906743189ad061429a7",
@@ -853,13 +872,13 @@ class ShipthisAPI:
         if start_state_id:
             payload["start_state_id"] = start_state_id
 
-        return self._make_request(
+        return await self._make_request(
             "POST",
             f"workflow/{collection}/{workflow_id}/{object_id}",
             request_data=payload,
         )
 
-    def secondary_workflow_action(
+    async def secondary_workflow_action(
         self,
         collection: str,
         workflow_id: str,
@@ -883,7 +902,7 @@ class ShipthisAPI:
             ShipthisAPIError: If the request fails.
 
         Example:
-            client.secondary_workflow_action(
+            await client.secondary_workflow_action(
                 collection="pickup_delivery",
                 workflow_id="driver_status",
                 object_id="67ed10859b7cf551a19f813e",
@@ -892,7 +911,7 @@ class ShipthisAPI:
         """
         payload = additional_data or {}
 
-        return self._make_request(
+        return await self._make_request(
             "POST",
             f"workflow/{collection}/{workflow_id}/{object_id}/{target_state}",
             request_data=payload,
@@ -900,7 +919,7 @@ class ShipthisAPI:
 
     # ==================== File Upload ====================
 
-    def upload_file(
+    async def upload_file(
         self,
         file_path: str,
         file_name: str = None,
@@ -933,18 +952,18 @@ class ShipthisAPI:
         try:
             with open(file_path, "rb") as f:
                 files = {"file": (file_name, f)}
-                response = requests.post(
-                    upload_url,
-                    headers=headers,
-                    files=files,
-                    timeout=self.timeout * 2,  # Double timeout for uploads
-                )
+                async with httpx.AsyncClient(timeout=self.timeout * 2) as client:
+                    response = await client.post(
+                        upload_url,
+                        headers=headers,
+                        files=files,
+                    )
         except FileNotFoundError:
             raise ShipthisRequestError(
                 message=f"File not found: {file_path}",
                 status_code=0,
             )
-        except requests.exceptions.RequestException as e:
+        except httpx.RequestError as e:
             raise ShipthisRequestError(
                 message=f"Upload failed: {str(e)}",
                 status_code=0,
@@ -959,4 +978,38 @@ class ShipthisAPI:
         raise ShipthisRequestError(
             message=f"Upload failed with status {response.status_code}",
             status_code=response.status_code,
-        )
+        )
+
+    # ==================== Reference Linked Fields ====================
+
+    async def create_reference_linked_field(
+        self,
+        collection_name: str,
+        doc_id: str,
+        payload: Dict[str, Any],
+    ) -> Dict[str, Any]:
+        """Create a reference-linked field on a document.
+
+        Args:
+            collection_name: Collection name.
+            doc_id: Document ID.
+            payload: Field data to create.
+
+        Returns:
+            API response.
+
+        Raises:
+            ShipthisAPIError: If the request fails.
+
+        Example:
+            await client.create_reference_linked_field(
+                "sea_shipment",
+                "68a4f906743189ad061429a7",
+                payload={"field_name": "containers", "data": {...}}
+            )
+        """
+        return await self._make_request(
+            "POST",
+            f"incollection/create-reference-linked-field/{collection_name}/{doc_id}",
+            request_data=payload,
+        )

{shipthisapi_python-2.1.0 → shipthisapi_python-3.0.0}/setup.py

@@ -5,15 +5,18 @@ with open("README.md", "r") as fh:
 
 
 setuptools.setup(
-     name='shipthisapi-python',  
-     version='2.1.0',
+     name='shipthisapi-python',
+     version='3.0.0',
      author="Mayur Rawte",
      author_email="mayur@shipthis.co",
-     description="ShipthisAPI utility package",
+     description="ShipthisAPI async utility package",
      long_description=long_description,
      long_description_content_type="text/markdown",
      url="https://github.com/shipthisco/shipthisapi-python",
      packages=setuptools.find_packages(),
+     install_requires=[
+         "httpx>=0.24.0",
+     ],
      classifiers=[
          "Programming Language :: Python :: 3",
          "License :: OSI Approved :: MIT License",

{shipthisapi_python-2.1.0 → shipthisapi_python-3.0.0}/shipthisapi_python.egg-info/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: shipthisapi-python
-Version: 2.1.0
-Summary: ShipthisAPI utility package
+Version: 3.0.0
+Summary: ShipthisAPI async utility package
 Home-page: https://github.com/shipthisco/shipthisapi-python
 Author: Mayur Rawte
 Author-email: mayur@shipthis.co
@@ -9,12 +9,14 @@ Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24.0
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
 Dynamic: description
 Dynamic: description-content-type
 Dynamic: home-page
+Dynamic: requires-dist
 Dynamic: summary
 
 # ShipthisAPI Python 

{shipthisapi_python-2.1.0 → shipthisapi_python-3.0.0}/shipthisapi_python.egg-info/SOURCES.txt

@@ -5,4 +5,5 @@ ShipthisAPI/shipthisapi.py
 shipthisapi_python.egg-info/PKG-INFO
 shipthisapi_python.egg-info/SOURCES.txt
 shipthisapi_python.egg-info/dependency_links.txt
+shipthisapi_python.egg-info/requires.txt
 shipthisapi_python.egg-info/top_level.txt

shipthisapi_python-3.0.0/shipthisapi_python.egg-info/requires.txt

@@ -0,0 +1 @@
+httpx>=0.24.0