Merge pull request #286 from EasyPost/carrier_metadata_ga

feat: carrier metadata GA

Author: Justintime50

CHANGELOG.md

@@ -15,6 +15,7 @@
   - References to `Scanform` are now `ScanForm` and `scan_form`
   - `primary_or_secondary` paramater name for billing functions is now called `priority` to match the API and docs
 - The `update_email` function of the `referral_customer` service had the parameter order switched so `id` (previously called `user_id`) is first which matches the rest of the library
+- Retrieving carrier metadata is now in GA
 - Dropped Python 3.6 support
 - Bumps all dependencies
 

easypost/easypost_client.py

@@ -13,6 +13,7 @@
     BetaReferralCustomerService,
     BillingService,
     CarrierAccountService,
+    CarrierMetadataService,
     CustomsInfoService,
     CustomsItemService,
     EndShipperService,
@@ -55,6 +56,7 @@ def __init__(
         self.beta_referral_customer = BetaReferralCustomerService(self)
         self.billing = BillingService(self)
         self.carrier_account = CarrierAccountService(self)
+        self.carrier_metadata = CarrierMetadataService(self)
         self.customs_info = CustomsInfoService(self)
         self.customs_item = CustomsItemService(self)
         self.end_shipper = EndShipperService(self)

easypost/services/__init__.py

@@ -6,6 +6,7 @@
 from easypost.services.beta_referral_customer_service import BetaReferralCustomerService
 from easypost.services.billing_service import BillingService
 from easypost.services.carrier_account_service import CarrierAccountService
+from easypost.services.carrier_metadata_service import CarrierMetadataService
 from easypost.services.customs_info_service import CustomsInfoService
 from easypost.services.customs_item_service import CustomsItemService
 from easypost.services.end_shipper_service import EndShipperService

easypost/services/beta_carrier_metadata_service.py

@@ -4,6 +4,7 @@
     List,
     Optional,
 )
+from warnings import warn
 
 from easypost.easypost_object import convert_to_easypost_object
 from easypost.requestor import (
@@ -23,6 +24,12 @@ def retrieve_carrier_metadata(
         types: Optional[List[str]] = None,
     ) -> List[Dict[str, Any]]:
         """Get metadata for all carriers on the EasyPost platform."""
+        warn(
+            'This method is deprecated, use the "retrieve" function of "carrier_metadata" on the client instead.',
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
         params = {
             "carriers": ",".join(carriers) if carriers else None,
             "types": ",".join(types) if types else None,

easypost/services/carrier_metadata_service.py

@@ -0,0 +1,37 @@
+from typing import (
+    Any,
+    Dict,
+    List,
+    Optional,
+)
+
+from easypost.easypost_object import convert_to_easypost_object
+from easypost.requestor import (
+    RequestMethod,
+    Requestor,
+)
+from easypost.services.base_service import BaseService
+
+
+class CarrierMetadataService(BaseService):
+    def __init__(self, client):
+        self._client = client
+
+    def retrieve(
+        self,
+        carriers: Optional[List[str]] = None,
+        types: Optional[List[str]] = None,
+    ) -> List[Dict[str, Any]]:
+        """Get metadata for all carriers on the EasyPost platform or specify optional filters."""
+        params = {
+            "carriers": ",".join(carriers) if carriers else None,
+            "types": ",".join(types) if types else None,
+        }
+
+        response = Requestor(self._client).request(
+            method=RequestMethod.GET,
+            url="/metadata/carriers",
+            params=params,
+        )
+
+        return convert_to_easypost_object(response=response.get("carriers", []))

tests/cassettes/test_retrieve_carrier_metadata.yaml

@@ -0,0 +1,27 @@
+import pytest
+
+
+@pytest.mark.vcr()
+def test_retrieve_carrier_metadata(test_client):
+    """Tests that we can retrieve all carriers and all metadata from the API when no params are provided."""
+    carrier_metadata = test_client.carrier_metadata.retrieve()
+
+    # Assert we get multiple carriers
+    assert any(carrier.name == "usps" for carrier in carrier_metadata)
+    assert any(carrier.name == "fedex" for carrier in carrier_metadata)
+
+
+@pytest.mark.vcr()
+def test_retrieve_carrier_metadata_with_filters(test_client):
+    """Tests that we can retrieve metadata based on the filters provided."""
+    carrier_metadata = test_client.carrier_metadata.retrieve(
+        carriers=["usps"],
+        types=["service_levels", "predefined_packages"],
+    )
+
+    # Assert we get the single carrier we asked for and only the types we asked for
+    assert all(carrier.name == "usps" for carrier in carrier_metadata)
+    assert len(carrier_metadata) == 1
+    assert carrier_metadata[0]["service_levels"]
+    assert carrier_metadata[0]["predefined_packages"]
+    assert not carrier_metadata[0].get("supported_features")