karrio 2023.5.1__py3-none-any.whl → 2025.5rc1__py3-none-any.whl

karrio/__init__.py

@@ -1,101 +1 @@
-"""Karrio package root module
-
-Karrio makes shipping carrier webservices integration easy by providing
-a modern and dev friendly library and by providing a unified extensible API
-to communicate with all supported carriers.
-
--- Speak Karrio, Speak carriers...
-
-Example:
-    Examples can be given using either the ``Example`` or ``Examples``
-    sections. Sections support any reStructuredText formatting, including
-    literal blocks::
-
-        >>> import karrio
-        >>> from karrio.core.utils import DP
-        >>> from karrio.core.models import Address, Parcel, RateRequest
-        >>> canadapost = karrio.gateway["canadapost"].create(
-        ...     {
-        ...         "username": "username",
-        ...         "password": "password",
-        ...         "customer_number": "123456789",
-        ...         "test": True
-        ...     }
-        ... )
-        >>> shipper = Address(
-        ...     postal_code= "V6M2V9",
-        ...     city= "Vancouver",
-        ...     country_code= "CA",
-        ...     state_code= "BC",
-        ...     address_line1= "5840 Oak St"
-        ... )
-        >>> recipient = Address(
-        ...     postal_code= "E1C4Z8",
-        ...     city= "Moncton",
-        ...     country_code= "CA",
-        ...     state_code= "NB",
-        ...     residential= False,
-        ...     address_line1= "125 Church St"
-        ... )
-        >>> parcel = Parcel(
-        ...     height= 3.0,
-        ...     length= 6.0,
-        ...     width= 3.0,
-        ...     weight= 0.5
-        ... )
-        >>> request = karrio.Rating.fetch(
-        ...     RateRequest(
-        ...         shipper=shipper,
-        ...         recipient=recipient,
-        ...         parcels=[parcel],
-        ...         services=["canadapost_priority"]
-        ...     )
-        ... )
-        >>> rates = request.from_(canadapost).parse()
-        >>> print(DP.to_dict(rates))
-        [
-            [],
-            [
-                {
-                    "base_charge": 12.26,
-                    "carrier_name": "canadapost",
-                    "carrier_id": "canadapost",
-                    "currency": "CAD",
-                    "transit_days": 2,
-                    "extra_charges": [
-                        {"amount": -0.37, "currency": "CAD", "name": "Automation discount"},
-                        {"amount": 1.75, "currency": "CAD", "name": "Fuel surcharge"}
-                    ],
-                    "service": "canadapost_xpresspost",
-                    "total_charge": 13.64
-                }
-            ]
-        ]
-
-Attributes:
-    gateway (GatewayInitializer): Gateway initializer singleton instance
-
-"""
 __path__ = __import__("pkgutil").extend_path(__path__, __name__)  # type: ignore
-
-from karrio.api.gateway import GatewayInitializer
-import karrio.api.interface as interface
-
-gateway = GatewayInitializer.get_instance()
-Pickup = interface.Pickup
-Rating = interface.Rating
-Shipment = interface.Shipment
-Tracking = interface.Tracking
-Address = interface.Address
-Document = interface.Document
-
-
-__all__ = [
-    "gateway",
-    "Pickup",
-    "Rating",
-    "Shipment",
-    "Tracking",
-    "Address",
-    "Document",
-]

karrio/addons/renderer.py

@@ -12,7 +12,7 @@ LINE_SEPARATOR = """
 """
 
 
-def generate_pdf_from_svg_label(content: str, **kwargs) -> Image:
+def generate_pdf_from_svg_label(content: str, **kwargs):
     template = fromstring(content)
     label = Image.new("L", (1200, 1800), "white")
     draw = ImageDraw.Draw(label)

karrio/api/gateway.py

@@ -1,19 +1,16 @@
 """Karrio API Gateway definition modules."""
+
 import attr
+import typing
 import logging
-from typing import Callable, Optional, Union, List
-
-from karrio.api.proxy import Proxy
-from karrio.api.mapper import Mapper
-from karrio.core import Settings
-from karrio.core.utils import DP, Tracer
-from karrio.core.models import Message
-from karrio.core.errors import ShippingSDKError
-from karrio.references import (
-    import_extensions,
-    detect_capabilities,
-    detect_proxy_methods,
-)
+
+import karrio.core as core
+import karrio.api.proxy as proxy
+import karrio.core.utils as utils
+import karrio.api.mapper as mapper
+import karrio.core.models as models
+import karrio.core.errors as errors
+import karrio.references as references
 
 logger = logging.getLogger(__name__)
 
@@ -23,25 +20,25 @@ class Gateway:
     """The carrier connection instance"""
 
     is_hub: bool
-    proxy: Proxy
-    mapper: Mapper
-    tracer: Tracer
-    settings: Settings
+    proxy: proxy.Proxy
+    mapper: mapper.Mapper
+    tracer: utils.Tracer
+    settings: core.Settings
 
     @property
-    def capabilities(self) -> List[str]:
-        return detect_capabilities(self.proxy_methods)
+    def capabilities(self) -> typing.List[str]:
+        return references.detect_capabilities(self.proxy_methods)
 
     @property
-    def proxy_methods(self) -> List[str]:
-        return detect_proxy_methods(self.proxy.__class__)
+    def proxy_methods(self) -> typing.List[str]:
+        return references.detect_proxy_methods(self.proxy.__class__)
 
     def check(self, request: str, origin_country_code: str = None):
         messages = []
 
         if request not in self.proxy_methods:
             messages.append(
-                Message(
+                models.Message(
                     carrier_id=self.settings.carrier_id,
                     carrier_name=self.settings.carrier_name,
                     code="SHIPPING_SDK_NON_SUPPORTED_ERROR",
@@ -55,7 +52,7 @@ class Gateway:
             and (origin_country_code != self.settings.account_country_code)
         ):
             messages.append(
-                Message(
+                models.Message(
                     carrier_id=self.settings.carrier_id,
                     carrier_name=self.settings.carrier_name,
                     code="SHIPPING_SDK_ORIGIN_NOT_SERVICED_ERROR",
@@ -72,9 +69,21 @@ class Gateway:
 class ICreate:
     """A gateway initializer type class"""
 
-    initializer: Callable[[Union[Settings, dict], Optional[Tracer]], Gateway]
-
-    def create(self, settings: Union[Settings, dict], tracer: Tracer = None) -> Gateway:
+    initializer: typing.Callable[
+        [
+            typing.Union[core.Settings, dict],
+            typing.Optional[utils.Tracer],
+            typing.Optional[utils.Cache],
+        ],
+        Gateway,
+    ]
+
+    def create(
+        self,
+        settings: typing.Union[core.Settings, dict],
+        tracer: utils.Tracer = None,
+        cache: utils.Cache = None,
+    ) -> Gateway:
         """A gateway factory with a fluent API interface.
 
         Args:
@@ -83,7 +92,7 @@ class ICreate:
         Returns:
             Gateway: The carrier connection instance
         """
-        return self.initializer(settings, tracer)
+        return self.initializer(settings, tracer, cache)
 
 
 class GatewayInitializer:
@@ -111,7 +120,9 @@ class GatewayInitializer:
             provider = self.providers[key]
 
             def initializer(
-                settings: Union[Settings, dict], tracer: Tracer = None
+                settings: typing.Union[core.Settings, dict],
+                tracer: utils.Tracer = None,
+                cache: utils.Cache = None,
             ) -> Gateway:
                 """Initialize a provider gateway with the required settings
 
@@ -121,31 +132,43 @@ class GatewayInitializer:
                 Returns:
                     Gateway: a gateway instance
                 """
+
                 try:
-                    _tracer = tracer or Tracer()
-                    settings_value: Settings = (
-                        DP.to_object(provider.Settings, settings)
+                    _tracer = tracer or utils.Tracer()
+                    _cache = cache or utils.Cache()
+                    settings_value: core.Settings = (
+                        utils.DP.to_object(provider.Settings, settings)
                         if isinstance(settings, dict)
                         else settings
                     )
+
+                    # set cache handle to all carrier settings
+                    setattr(settings_value, "cache", _cache)
+
+                    # set tracer handle to all carrier settings
+                    setattr(settings_value, "tracer", _tracer)
+
                     return Gateway(
                         tracer=_tracer,
                         is_hub=provider.is_hub,
                         settings=settings_value,
                         mapper=provider.Mapper(settings_value),
-                        proxy=provider.Proxy(settings_value, tracer=_tracer),
+                        proxy=provider.Proxy(settings_value),
                     )
+
                 except Exception as er:
-                    raise ShippingSDKError(f"Failed to setup provider '{key}'") from er
+                    raise errors.ShippingSDKError(
+                        f"Failed to setup provider '{key}'"
+                    ) from er
 
             return ICreate(initializer)
         except KeyError as e:
             logger.error(e)
-            raise ShippingSDKError(f"Unknown provider '{key}'")
+            raise errors.ShippingSDKError(f"Unknown provider '{key}'")
 
     @property
     def providers(self):
-        return import_extensions()
+        return references.collect_providers_data()
 
     @staticmethod
     def get_instance() -> "GatewayInitializer":

karrio/api/interface.py

@@ -139,7 +139,7 @@ class IRequestFromMany:
 
     def from_(self, *gateways: gateway.Gateway) -> IDeserialize:
         """Execute the request action(s) from the provided gateway(s)"""
-        return self.action(list(gateways))
+        return self.action(list({_.settings.carrier_id: _ for _ in gateways}.values()))
 
 
 class Address:
@@ -309,9 +309,9 @@ class Rating:
 
                 return IDeserialize(deserialize)
 
-            deserializable_collection: typing.List[
-                IDeserialize
-            ] = lib.run_asynchronously(lambda g: fail_safe(g)(process)(g), gateways)
+            deserializable_collection: typing.List[IDeserialize] = (
+                lib.run_asynchronously(lambda g: fail_safe(g)(process)(g), gateways)
+            )
 
             def flatten(*args):
                 responses = [p.parse() for p in deserializable_collection]
@@ -485,3 +485,40 @@ class Document:
             return IDeserialize(deserialize)
 
         return IRequestFrom(action)
+
+
+class Manifest:
+    """The unified Manifest API fluent interface"""
+
+    @staticmethod
+    def create(args: typing.Union[models.ManifestRequest, dict]) -> IRequestFrom:
+        """Submit a manifest creation to a carrier.
+        This operation is often referred to as manifesting a batch of shipments
+
+        Args:
+            args (Union[ManifestRequest, dict]): the manifest creation request payload
+
+        Returns:
+            IRequestWith: a lazy request dataclass instance
+        """
+        logger.debug(f"create a manifest. payload: {lib.to_json(args)}")
+        payload = lib.to_object(models.ManifestRequest, lib.to_dict(args))
+
+        def action(gateway: gateway.Gateway):
+            is_valid, abortion = check_operation(
+                gateway,
+                "create_manifest",
+            )
+            if not is_valid:
+                return abortion
+
+            request: lib.Serializable = gateway.mapper.create_manifest_request(payload)
+            response: lib.Deserializable = gateway.proxy.create_manifest(request)
+
+            @fail_safe(gateway)
+            def deserialize():
+                return gateway.mapper.parse_manifest_response(response)
+
+            return IDeserialize(deserialize)
+
+        return IRequestFrom(action)

karrio/api/mapper.py

@@ -178,6 +178,25 @@ class Mapper(abc.ABC):
             self.settings.carrier_name,
         )
 
+    def create_manifest_request(
+        self, payload: models.ManifestRequest
+    ) -> lib.Serializable:
+        """Create a carrier specific manifest request data from payload
+
+        Args:
+            payload (ManifestRequest): the manifest request payload
+
+        Returns:
+            Serializable: a carrier specific serializable request data type
+
+        Raises:
+            MethodNotSupportedError: Is raised when the carrier integration does not implement this method
+        """
+        raise errors.MethodNotSupportedError(
+            self.__class__.create_manifest_request.__name__,
+            self.settings.carrier_name,
+        )
+
     """Response Parsers"""
 
     def parse_address_validation_response(
@@ -354,3 +373,23 @@ class Mapper(abc.ABC):
             self.__class__.parse_document_upload_response.__name__,
             self.settings.carrier_name,
         )
+
+    def parse_manifest_response(
+        self, response: lib.Deserializable
+    ) -> typing.Tuple[models.ManifestDetails, typing.List[models.Message]]:
+        """Create a unified API manifest result from carrier response
+
+        Args:
+            response (Deserializable): a deserializable manifest response (xml, json, text...)
+
+        Returns:
+            Tuple[ManifestDetails, List[Message]]: the manifest details
+                as well as errors and messages returned
+
+        Raises:
+            MethodNotSupportedError: Is raised when the carrier integration does not implement this method
+        """
+        raise errors.MethodNotSupportedError(
+            self.__class__.parse_manifest_response.__name__,
+            self.settings.carrier_name,
+        )

karrio/api/proxy.py

@@ -13,15 +13,12 @@ class Proxy(abc.ABC):
     """Unified Shipping API Proxy (Interface)"""
 
     settings: settings.Settings
-    tracer: lib.Tracer = attr.field(factory=lib.Tracer)
 
     def trace(self, *args, **kwargs):
-        return self.tracer.with_metadata(dict(connection=self.settings))(
-            *args, **kwargs
-        )
+        return self.settings.trace(*args, **kwargs)
 
     def trace_as(self, format: str):
-        return functools.partial(self.trace, format=format)
+        return self.settings.trace_as(format)
 
     def get_rates(self, request: lib.Serializable) -> lib.Deserializable:
         """Send one or many request(s) to get shipment rates from a carrier webservice
@@ -166,3 +163,19 @@ class Proxy(abc.ABC):
         raise errors.MethodNotSupportedError(
             self.__class__.upload_document.__name__, self.settings.carrier_name
         )
+
+    def create_manifest(self, request: lib.Serializable) -> lib.Deserializable:
+        """Send one or many request(s) to create a manifest from a carrier webservice
+
+        Args:
+            request (Serializable): a carrier specific serializable request data type
+
+        Returns:
+            Deserializable: a Deserializable rate response (xml, json, text...)
+
+        Raises:
+            MethodNotSupportedError: Is raised when the carrier integration does not implement this method
+        """
+        raise errors.MethodNotSupportedError(
+            self.__class__.create_manifest.__name__, self.settings.carrier_name
+        )

karrio/core/__init__.py

@@ -1,2 +1,6 @@
-"""The Karrio core module"""
+"""
+Karrio Core Module.
+
+This module provides core functionality for the Karrio shipping system.
+"""
 from karrio.core.settings import Settings

karrio/core/errors.py

@@ -1,9 +1,10 @@
 """Karrio Custom Errors(Exception) definition modules"""
-from enum import Enum
-from typing import Dict
 
+import enum
+import typing
 
-class FieldErrorCode(Enum):
+
+class FieldErrorCode(enum.Enum):
     required = dict(code="required", message="This field is required")
     invalid = dict(code="invalid", message="This field is invalid")
     exceeds = dict(code="exceeds", message="This field exceeds the max value")
@@ -28,7 +29,7 @@ class FieldError(ShippingSDKDetailedError):
 
     code = "SHIPPING_SDK_FIELD_ERROR"
 
-    def __init__(self, fields: Dict[str, FieldErrorCode]):
+    def __init__(self, fields: typing.Dict[str, FieldErrorCode]):
         super().__init__("Invalid request payload")
         self.details = {name: code.value for name, code in fields.items()}
 
@@ -38,7 +39,7 @@ class ParsedMessagesError(ShippingSDKDetailedError):
 
     code = "SHIPPING_SDK_FIELD_ERROR"
 
-    def __init__(self, messages = []):
+    def __init__(self, messages=[]):
         super().__init__("Invalid request payload")
         self.messages = messages
 

karrio/core/metadata.py

@@ -1,7 +1,13 @@
-"""Karrio Extension Metadata definition module."""
+"""
+Karrio Plugin Metadata Module.
+
+This module provides the PluginMetadata class and related functionality
+for defining and working with Karrio plugin metadata.
+"""
+
 import attr
 from enum import Enum
-from typing import Optional, Type, List, Dict
+from typing import Optional, Type, List, Dict, Any, Literal
 
 from karrio.api.proxy import Proxy
 from karrio.api.mapper import Mapper
@@ -10,29 +16,116 @@ from karrio.core.models import ServiceLevel
 
 
 @attr.s(auto_attribs=True)
-class Metadata:
-    """Karrio extension metadata.
-    Used to describe and define a karrio compatible extension for a carrier webservice integration.
+class PluginMetadata:
     """
+    Metadata for a Karrio plugin.
 
+    This class defines the metadata for a Karrio plugin, including its ID,
+    label, description, capabilities, and other attributes.
+    """
+    id: str
     label: str
+    description: Optional[str] = ""
+    status: Optional[str] = "beta"
+
+    # Components that will be registered if present
+    Proxy: Any = None
+    Mapper: Any = None
+    Validator: Any = None
+    Settings: Any = None
+
+    # Optional metadata
+    options: Any = None
+    services: Any = None
+    countries: Any = None
+    packaging_types: Any = None
+    package_presets: Any = None
+    service_levels: Any = None
+    connection_configs: Any = None
 
-    # Integrations
-    Mapper: Type[Mapper]
-    Proxy: Type[Proxy]
-    Settings: Type[Settings]
-
-    # Data Units
-    options: Optional[Type[Enum]] = None
-    services: Optional[Type[Enum]] = None
-    package_presets: Optional[Type[Enum]] = None
-    packaging_types: Optional[Type[Enum]] = None
-    connection_configs: Optional[Type[Enum]] = None
-    service_levels: Optional[List[ServiceLevel]] = None
-
-    id: Optional[str] = None
-    is_hub: Optional[bool] = False
+    # Extra metadata
+    website: Optional[str] = None
+    documentation: Optional[str] = None
+    readme: Optional[str] = None
+    is_hub: bool = False
     hub_carriers: Optional[Dict[str, str]] = None
+    has_intl_accounts: Optional[bool] = False
+
+    def is_carrier_integration(self) -> bool:
+        """Check if this plugin is a carrier integration based on registered components."""
+        return bool(self.Mapper) and bool(self.Proxy) and bool(self.Settings)
+
+    def is_address_validator(self) -> bool:
+        """Check if this plugin is an address validator based on registered components."""
+        return bool(self.Validator)
+
+    def is_dual_purpose(self) -> bool:
+        """Check if this plugin serves both as a carrier integration and address validator."""
+        return self.is_carrier_integration() and self.is_address_validator()
+
+    @property
+    def plugin_types(self) -> List[str]:
+        """
+        Get a list of all functionality types provided by this plugin.
+
+        Returns:
+            List[str]: List of plugin types, e.g. ["carrier_integration", "address_validator"]
+        """
+        types = []
+        if self.is_carrier_integration():
+            types.append("carrier_integration")
+        if self.is_address_validator():
+            types.append("address_validator")
+        if not types:
+            types.append("unknown")
+        return types
 
+    @property
+    def plugin_type(self) -> str:
+        """
+        Determine the primary type of plugin based on registered components.
+        For dual-purpose plugins, returns "dual_purpose".
+
+        Returns:
+            str: "carrier_integration", "address_validator", "dual_purpose", or "unknown"
+        """
+        if self.is_carrier_integration() and self.is_address_validator():
+            return "dual_purpose"
+        elif self.is_carrier_integration():
+            return "carrier_integration"
+        elif self.is_address_validator():
+            return "address_validator"
+        else:
+            return "unknown"
+
+    @property
+    def supports_carrier_integration(self) -> bool:
+        """Check if this plugin provides carrier integration functionality."""
+        return self.is_carrier_integration()
+
+    @property
+    def supports_address_validation(self) -> bool:
+        """Check if this plugin provides address validation functionality."""
+        return self.is_address_validator()
+
+    # Dictionary-like access methods for backward compatibility
     def __getitem__(self, item):
         return getattr(self, item)
+
+    def get(self, key, default=None):
+        """
+        Dictionary-like get method for backward compatibility.
+
+        Args:
+            key: Attribute name to retrieve
+            default: Default value if attribute doesn't exist
+
+        Returns:
+            The attribute value or default if not found
+        """
+        return getattr(self, key, default)
+
+
+# Legacy compatibility aliases
+Metadata = PluginMetadata
+AddressValidatorMetadata = PluginMetadata