karrio-laposte 2025.5rc1__py3-none-any.whl

karrio/mappers/laposte/__init__.py

@@ -0,0 +1,3 @@
+from karrio.mappers.laposte.mapper import Mapper
+from karrio.mappers.laposte.proxy import Proxy
+from karrio.mappers.laposte.settings import Settings

karrio/mappers/laposte/mapper.py

@@ -0,0 +1,22 @@
+"""Karrio La Poste client mapper."""
+
+import typing
+import karrio.lib as lib
+import karrio.api.mapper as mapper
+import karrio.core.models as models
+import karrio.providers.laposte as provider
+import karrio.mappers.laposte.settings as provider_settings
+
+
+class Mapper(mapper.Mapper):
+    settings: provider_settings.Settings
+
+    def create_tracking_request(
+        self, payload: models.TrackingRequest
+    ) -> lib.Serializable:
+        return provider.tracking_request(payload, self.settings)
+
+    def parse_tracking_response(
+        self, response: lib.Deserializable
+    ) -> typing.Tuple[typing.List[models.TrackingDetails], typing.List[models.Message]]:
+        return provider.parse_tracking_response(response, self.settings)

karrio/mappers/laposte/proxy.py

@@ -0,0 +1,23 @@
+"""Karrio La Poste client proxy."""
+
+import karrio.lib as lib
+import karrio.api.proxy as proxy
+import karrio.mappers.laposte.settings as provider_settings
+
+
+class Proxy(proxy.Proxy):
+    settings: provider_settings.Settings
+
+    def get_tracking(self, request: lib.Serializable) -> lib.Deserializable:
+        idships = ",".join(request.serialize())
+        response = lib.request(
+            url=f"{self.settings.server_url}/idships/{idships}?lang={self.settings.lang}",
+            trace=self.trace_as("json"),
+            headers={
+                "accept": "application/json",
+                "X-Okapi-Key": self.settings.api_key,
+            },
+            method="GET",
+        )
+
+        return lib.Deserializable(response, lib.to_dict)

karrio/mappers/laposte/settings.py

@@ -0,0 +1,21 @@
+"""Karrio La Poste client settings."""
+
+import attr
+import karrio.providers.laposte.utils as utils
+
+
+@attr.s(auto_attribs=True)
+class Settings(utils.Settings):
+    """La Poste connection settings."""
+
+    # required carrier specific properties
+    api_key: str
+    lang: utils.LangEnum = "fr_FR"  # type: ignore
+
+    # generic properties
+    id: str = ""
+    test_mode: bool = False
+    carrier_id: str = "laposte"
+    account_country_code: str = "FR"
+    metadata: dict = {}
+    config: dict = {}

karrio/plugins/laposte/__init__.py

@@ -0,0 +1,20 @@
+import karrio.core.metadata as metadata
+import karrio.mappers.laposte as mappers
+import karrio.providers.laposte.units as units
+
+
+METADATA = metadata.PluginMetadata(
+    status="production-ready",
+    id="laposte",
+    label="La Poste",
+    # Integrations
+    Mapper=mappers.Mapper,
+    Proxy=mappers.Proxy,
+    Settings=mappers.Settings,
+    # Data Units
+    is_hub=False,
+    # New fields
+    website="https://www.laposte.fr/",
+    documentation="https://www.lapostegroupe.com/en/services-mail-parcels-business-unit",
+    description="La Poste is a postal service company in France, operating in Metropolitan France and French overseas territories. The company provides mail delivery, parcel shipping, banking services, and digital solutions.",
+)

karrio/providers/laposte/__init__.py

@@ -0,0 +1,6 @@
+
+from karrio.providers.laposte.utils import Settings
+from karrio.providers.laposte.tracking import (
+    parse_tracking_response,
+    tracking_request,
+)

karrio/providers/laposte/error.py

@@ -0,0 +1,32 @@
+import karrio.schemas.laposte.error as laposte
+import typing
+import karrio.lib as lib
+import karrio.core.models as models
+import karrio.providers.laposte.utils as provider_utils
+
+
+def parse_error_response(
+    response: typing.Union[dict, typing.List[dict]],
+    settings: provider_utils.Settings,
+    **kwargs,
+) -> typing.List[models.Message]:
+    responses = response if isinstance(response, list) else [response]
+    errors = [
+        lib.to_object(laposte.Error, res)
+        for res in responses
+        if (
+            not str(res.get("returnCode")).startswith("20")
+            or res.get("code") is not None
+        )
+    ]
+
+    return [
+        models.Message(
+            carrier_id=settings.carrier_id,
+            carrier_name=settings.carrier_name,
+            code=error.returnCode or error.code,
+            message=error.returnMessage or error.message,
+            details={**kwargs},
+        )
+        for error in errors
+    ]

karrio/providers/laposte/tracking.py

@@ -0,0 +1,79 @@
+import karrio.schemas.laposte.tracking_response as laposte
+import typing
+import karrio.lib as lib
+import karrio.core.units as units
+import karrio.core.models as models
+import karrio.providers.laposte.error as error
+import karrio.providers.laposte.utils as provider_utils
+import karrio.providers.laposte.units as provider_units
+
+
+def parse_tracking_response(
+    _response: lib.Deserializable[typing.Union[dict, typing.List[dict]]],
+    settings: provider_utils.Settings,
+) -> typing.Tuple[typing.List[models.TrackingDetails], typing.List[models.Message]]:
+    response = _response.deserialize()
+    responses = response if isinstance(response, list) else [response]
+    messages = error.parse_error_response(responses, settings)
+    tracking_details = [
+        _extract_details(res["shipment"], settings)
+        for res in responses
+        if str(res.get("returnCode")).startswith("20")
+    ]
+
+    return tracking_details, messages
+
+
+def _extract_details(
+    data: dict,
+    settings: provider_utils.Settings,
+) -> models.TrackingDetails:
+    shipment = lib.to_object(laposte.Shipment, data)
+    status = next(
+        (
+            status.name
+            for status in list(provider_units.TrackingStatus)
+            if shipment.event[0].code in status.value
+        ),
+        provider_units.TrackingStatus.in_transit.name,
+    )
+
+    return models.TrackingDetails(
+        carrier_id=settings.carrier_id,
+        carrier_name=settings.carrier_name,
+        tracking_number=shipment.idShip,
+        status=status,
+        events=[
+            models.TrackingEvent(
+                date=lib.fdate(event.date, "%Y-%m-%dT%H:%M:%S%z"),
+                description=event.label,
+                code=event.code,
+                time=lib.flocaltime(event.date, "%Y-%m-%dT%H:%M:%S%z"),
+                location=None,
+            )
+            for event in shipment.event
+        ],
+        estimated_delivery=lib.fdate(shipment.deliveryDate, "%Y-%m-%dT%H:%M:%S%z"),
+        delivered=shipment.isFinal,
+        info=models.TrackingInfo(
+            carrier_tracking_link=shipment.url,
+            expected_delivery=lib.fdate(shipment.estimDate, "%Y-%m-%dT%H:%M:%S%z"),
+            shipment_service=shipment.product,
+            shipping_date=lib.fdate(shipment.entryDate, "%Y-%m-%dT%H:%M:%S%z"),
+            shipment_origin_country=getattr(
+                shipment.contextData, "originCountry", None
+            ),
+            shipment_destination_country=getattr(
+                shipment.contextData, "arrivalCountry", None
+            ),
+        ),
+    )
+
+
+def tracking_request(
+    payload: models.TrackingRequest,
+    settings: provider_utils.Settings,
+) -> lib.Serializable:
+    request = payload.tracking_numbers
+
+    return lib.Serializable(request)

karrio/providers/laposte/units.py

@@ -0,0 +1,57 @@
+import karrio.lib as lib
+import karrio.core.units as units
+
+
+class PackagingType(lib.StrEnum):
+    """Carrier specific packaging type"""
+
+    PACKAGE = "PACKAGE"
+
+    """ Unified Packaging type mapping """
+    envelope = PACKAGE
+    pak = PACKAGE
+    tube = PACKAGE
+    pallet = PACKAGE
+    small_box = PACKAGE
+    medium_box = PACKAGE
+    your_packaging = PACKAGE
+
+
+class ShippingService(lib.StrEnum):
+    """Carrier specific services"""
+
+    laposte_standard_service = "La Poste Standard Service"
+
+
+class ShippingOption(lib.Enum):
+    """Carrier specific options"""
+
+    # laposte_option = lib.OptionEnum("code")
+
+    """ Unified Option type mapping """
+    # insurance = laposte_coverage  #  maps unified karrio option to carrier specific
+
+    pass
+
+
+def shipping_options_initializer(
+    options: dict,
+    package_options: units.ShippingOptions = None,
+) -> units.ShippingOptions:
+    """
+    Apply default values to the given options.
+    """
+
+    if package_options is not None:
+        options.update(package_options.content)
+
+    def items_filter(key: str) -> bool:
+        return key in ShippingOption  # type: ignore
+
+    return units.ShippingOptions(options, ShippingOption, items_filter=items_filter)
+
+
+class TrackingStatus(lib.Enum):
+    delivered = ["DI1"]
+    in_transit = [""]
+    out_for_delivery = ["MD2", "ET1"]

karrio/providers/laposte/utils.py

@@ -0,0 +1,24 @@
+import karrio.lib as lib
+import karrio.core as core
+
+
+LangEnum = lib.units.create_enum("LangEnum", ["fr_FR", "en_US"])
+
+
+class Settings(core.Settings):
+    """La Poste connection settings."""
+
+    api_key: str
+    lang: LangEnum = "fr_FR"  # type: ignore
+
+    @property
+    def carrier_name(self):
+        return "laposte"
+
+    @property
+    def server_url(self):
+        return "https://api.laposte.fr/suivi/v2"
+
+    @property
+    def tracking_url(self):
+        return "https://www.laposte.fr/outils/suivre-vos-envois?code={}"

karrio/schemas/laposte/error.py

@@ -0,0 +1,14 @@
+import attr
+import jstruct
+import typing
+
+
+@attr.s(auto_attribs=True)
+class Error:
+    returnCode: typing.Optional[int] = None
+    returnMessage: typing.Optional[str] = None
+    lang: typing.Optional[str] = None
+    scope: typing.Optional[str] = None
+    idShip: typing.Optional[str] = None
+    code: typing.Optional[str] = None
+    message: typing.Optional[str] = None

karrio/schemas/laposte/tracking_response.py

@@ -0,0 +1,61 @@
+import attr
+import jstruct
+import typing
+
+
+@attr.s(auto_attribs=True)
+class DeliveryChoice:
+    deliveryChoice: typing.Optional[int] = None
+
+
+@attr.s(auto_attribs=True)
+class ContextData:
+    deliveryChoice: typing.Optional[DeliveryChoice] = jstruct.JStruct[DeliveryChoice]
+    originCountry: typing.Optional[str] = None
+    arrivalCountry: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class Event:
+    code: typing.Optional[str] = None
+    label: typing.Optional[str] = None
+    date: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class Timeline:
+    shortLabel: typing.Optional[str] = None
+    longLabel: typing.Optional[str] = None
+    id: typing.Optional[int] = None
+    country: typing.Optional[str] = None
+    status: typing.Optional[bool] = None
+    type: typing.Optional[int] = None
+    date: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class Shipment:
+    idShip: typing.Optional[str] = None
+    holder: typing.Optional[int] = None
+    product: typing.Optional[str] = None
+    isFinal: typing.Optional[bool] = None
+    deliveryDate: typing.Optional[str] = None
+    entryDate: typing.Optional[str] = None
+    timeline: typing.Optional[typing.List[Timeline]] = jstruct.JList[Timeline]
+    event: typing.Optional[typing.List[Event]] = jstruct.JList[Event]
+    contextData: typing.Optional[ContextData] = jstruct.JStruct[ContextData]
+    estimDate: typing.Optional[str] = None
+    url: typing.Optional[str] = None
+
+
+@attr.s(auto_attribs=True)
+class Response:
+    lang: typing.Optional[str] = None
+    scope: typing.Optional[str] = None
+    returnCode: typing.Optional[int] = None
+    shipment: typing.Optional[Shipment] = jstruct.JStruct[Shipment]
+
+
+@attr.s(auto_attribs=True)
+class TrackingResponse:
+    responses: typing.Optional[typing.List[Response]] = jstruct.JList[Response]

karrio_laposte-2025.5rc1.dist-info/METADATA

@@ -0,0 +1,45 @@
+Metadata-Version: 2.4
+Name: karrio_laposte
+Version: 2025.5rc1
+Summary: Karrio - La Poste Shipping Extension
+Author-email: karrio <hello@karrio.io>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/karrioapi/karrio
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: karrio
+
+
+# karrio.laposte
+
+This package is a La Poste extension of the [karrio](https://pypi.org/project/karrio) multi carrier shipping SDK.
+
+## Requirements
+
+`Python 3.11+`
+
+## Installation
+
+```bash
+pip install karrio.laposte
+```
+
+## Usage
+
+```python
+import karrio.sdk as karrio
+from karrio.mappers.laposte.settings import Settings
+
+
+# Initialize a carrier gateway
+laposte = karrio.gateway["laposte"].create(
+    Settings(
+        ...
+    )
+)
+```
+
+Check the [Karrio Mutli-carrier SDK docs](https://docs.karrio.io) for Shipping API requests

karrio_laposte-2025.5rc1.dist-info/RECORD

@@ -0,0 +1,18 @@
+karrio/mappers/laposte/__init__.py,sha256=Vc5jW0ohCxnxsv_msdf4ftlVcg5tF9_ETsne2u-UxYk,148
+karrio/mappers/laposte/mapper.py,sha256=TFfFyez_qeX94yxlFMydzNp2B7NvynTHY_8o0irGiMk,735
+karrio/mappers/laposte/proxy.py,sha256=NQyWL0rc-ky80o1NF2eNOpLTq9q6k6RQHosSjDrwgsQ,745
+karrio/mappers/laposte/settings.py,sha256=k7J2BUyX4U8g2T3xFTrNbwvSq0TkSjdBwl3BzPgv98w,498
+karrio/plugins/laposte/__init__.py,sha256=s5MbbVNYqW4OLp_lHKlAR8q-Ws0pLv9JPFa1Kp2fdc0,749
+karrio/providers/laposte/__init__.py,sha256=UmsiUvmZL8zOhAcoZMippZ6okpCPa8BcnWCfNEkSYWw,154
+karrio/providers/laposte/error.py,sha256=oohq1_PrH_AwIbMzDHAwN9Q6pSCdifUw8z6Dz-bt6VA,948
+karrio/providers/laposte/tracking.py,sha256=LgrZYJl8TF7XM6UQ3ZKh0d9cr14Z8ZG1iPYqHAeHdo0,2757
+karrio/providers/laposte/units.py,sha256=dOC62QEibI0bmI4Ukobvj81cH1udqnzHTbIGNBAsQEk,1332
+karrio/providers/laposte/utils.py,sha256=BYbMIdsf-vIQltFPMTy53JlyTF6g9Wva1shPmheIczI,529
+karrio/schemas/laposte/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+karrio/schemas/laposte/error.py,sha256=JUKNxIEHhNVZ6aTGyA9QeF6WJRcnv4z_T-lEe4DPNHk,370
+karrio/schemas/laposte/tracking_response.py,sha256=x_VPNtzg4LSrNKPFffzZ0H-tzZNrkLcnQIVXsKJRo7A,1822
+karrio_laposte-2025.5rc1.dist-info/METADATA,sha256=ME6McQbh1vvJHh9T17Dr085pefSCn6aAUy_TOr2sTqs,996
+karrio_laposte-2025.5rc1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+karrio_laposte-2025.5rc1.dist-info/entry_points.txt,sha256=jFXL-V5ZRLAXwmk3DrdkzFpby2AHihbknUW_61y9Ft8,59
+karrio_laposte-2025.5rc1.dist-info/top_level.txt,sha256=FZCY8Nwft8oEGHdl--xku8P3TrnOxu5dETEU_fWpRSM,20
+karrio_laposte-2025.5rc1.dist-info/RECORD,,

karrio_laposte-2025.5rc1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

karrio_laposte-2025.5rc1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[karrio.plugins]
+laposte = karrio.plugins.laposte:METADATA

karrio_laposte-2025.5rc1.dist-info/top_level.txt

@@ -0,0 +1,3 @@
+dist
+karrio
+schemas