py-canada-post 1.0.0__py3-none-any.whl

py_canada_post/__init__.py

@@ -0,0 +1,6 @@
+"""py-canada-post wrapper."""
+from py_canada_post import client
+
+__all__ = ["client"]
+
+__version__ = "1.0.0"

py_canada_post/__main__.py

@@ -0,0 +1,4 @@
+from py_canada_post.cli.app import app
+
+if __name__ == "__main__":
+    app()

py_canada_post/cli/app.py

@@ -0,0 +1,32 @@
+from importlib.metadata import version
+
+from cyclopts import App
+
+from .rating import rating_app
+
+
+def version_callback() -> str:
+    """
+    Function to get a version of the wrapper.
+
+    Returns
+    -------
+    str
+        Version of the wrapper.
+    """
+
+    return version('py_canada_post')
+
+
+app = App(
+    name="py-canada-post",
+    help="Python wrapper to interact with Canada Post API.",
+    version_format="rich",
+    version_flags=["--version", "-v"],
+    version=version_callback,
+    help_format="rich",
+)
+app.command(rating_app)
+
+if __name__ == "__main__":
+    app()

py_canada_post/cli/rating/__init__.py

@@ -0,0 +1 @@
+from .rating_app import rating_app

py_canada_post/cli/rating/commands/discover_services.py

@@ -0,0 +1,54 @@
+from typing import Annotated
+
+from cyclopts import Parameter, App
+
+from py_canada_post.client import PyCanadaPost
+from py_canada_post.services.rating.types import Service
+
+client = PyCanadaPost.from_env()
+
+discover_services = App(
+    name="discover-services",
+    help="Command to get available services."
+)
+
+
+@discover_services.command
+def discover_services(
+    country_code: Annotated[
+        str,
+        Parameter(name=["country-code", "-c"], required=True)
+    ],
+    origin_postal_code: Annotated[
+        str,
+        Parameter(name=["origin-postal-code", "-o"], required=False)
+    ] = None,
+    destination_postal_code: Annotated[
+        str,
+        Parameter(name=["destination-postal-code", "-d"], required=False)
+    ] = None
+) -> list[Service] | None:
+    """
+    Command to get available services.
+
+    Parameters
+    ----------
+    country_code : str
+        Country code in a 2-letter format (e.g. JP, CA, US).
+    origin_postal_code : str, optional
+        Origin postal code where the package will be sent from.
+    destination_postal_code : str, optional
+        Destination postal code where the package will be delivered to.
+
+    Returns
+    -------
+    list[Service] | None
+        List of services or None.
+    """
+
+    services = client.rating.services.discover_services(
+        country_code,
+        origin_postal_code,
+        destination_postal_code
+    )
+    return services

py_canada_post/cli/rating/commands/get_rates.py

@@ -0,0 +1,154 @@
+from datetime import datetime
+from typing import Annotated, Literal
+
+from cyclopts import Parameter, App
+
+from py_canada_post.client import PyCanadaPost
+from py_canada_post.services.rating.types import Destination, Option, ParcelCharacteristics, Rate
+
+client = PyCanadaPost.from_env()
+
+get_rates = App(
+    name="get-rates",
+    help="Command to get rates."
+)
+
+
+@get_rates.command
+def get_rates(
+    origin_postal_code: Annotated[
+        str,
+        Parameter(name=["origin-postal-code", "-o"], required=True)
+    ],
+    destination: Annotated[
+        Destination,
+        Parameter(name=["destination", "-d"], required=True)
+    ],
+    promo_code: Annotated[
+        str,
+        Parameter(name=["promo-code", "-p"], required=False)
+    ] = None,
+    quote_type: Annotated[
+        Literal["commercial", "counter"],
+        Parameter(name=["quote-type", "-q"], required=False)
+    ] = "commercial",
+    expected_mailing_date: Annotated[
+        datetime,
+        Parameter(name=["expected-mailing-date", "-m"], required=False)
+    ] = None,
+    options: Annotated[
+        list[Option],
+        Parameter(name=["options", "-O"], required=False, consume_multiple=True)
+    ] = None,
+    parcel_characteristics: Annotated[
+        ParcelCharacteristics,
+        Parameter(name=["parcel-characteristics", "-c"], required=False)
+    ] = None,
+    unpackaged: Annotated[
+        bool,
+        Parameter(name=["unpackaged", "-u"], required=False)
+    ] = False,
+    mailing_tube: Annotated[
+        bool,
+        Parameter(name=["mailing-tube", "-t"], required=False)
+    ] = False,
+    oversized: Annotated[
+        bool,
+        Parameter(name=["oversized", "-z"], required=False)
+    ] = False,
+    services: Annotated[
+        list[Literal[
+            "DOM.RP",
+            "DOM.EP",
+            "DOM.XP",
+            "DOM.XP.CERT",
+            "DOM.PC",
+            "DOM.LIB",
+            "USA.EP",
+            "USA.SP.AIR",
+            "USA.TP",
+            "USA.TP.LVM",
+            "USA.XP",
+            "INT.XP",
+            "INT.IP.AIR",
+            "INT.IP.SURF",
+            "INT.SP.AIR",
+            "INT.SP.SURF",
+            "INT.TP"
+        ]],
+        Parameter(name=["services", "-s"], required=False, consume_multiple=True)
+    ] = None
+) -> list[Rate] | None:
+    """
+    Command to get rates.
+
+    Parameters
+    ----------
+    origin_postal_code : str
+        Postal Code from which the parcel will be sent.
+        Format ANANAN (only accepted with uppercase)
+    destination : Destination
+        Defines the destination of the parcel.
+    promo_code : str, optional
+        If you have a promotional discount code, enter it here. The discount amount will be returned in the response under the adjustment structure.
+    quote_type : Literal["commercial", "counter"], default "commercial"
+        Either commercial or counter.
+
+        - "commercial" will return the discounted price for the commercial customer or Solutions for Small Business member.
+        - "counter" will return the regular price paid by consumers.
+        Defaults to "commercial" if not specified.
+    expected_mailing_date : datetime, optional
+        The expected mailing date for the parcel.
+
+        This date is used in calculations of the expected delivery date, however all rate quotes are based on the current system date.
+    options : list[Option], optional
+        Structure containing the list of options desired for the shipment.
+    parcel_characteristics : ParcelCharacteristics, optional
+        Details of the parcel such as weight and dimensions.
+    unpackaged : bool, default False
+        Indicates that the parcel will be unpackaged (e.g. tires)
+    mailing_tube : bool, default False
+        Indicates that the object will be shipped in a mailing tube
+    oversized : bool, default False
+        Indicates that the object has oversized dimensions. Automatically set correctly if dimensions are provided.
+    services : list[Literal[
+        "DOM.RP",
+        "DOM.EP",
+        "DOM.XP",
+        "DOM.XP.CERT",
+        "DOM.PC",
+        "DOM.LIB",
+        "USA.EP",
+        "USA.SP.AIR",
+        "USA.TP",
+        "USA.TP.LVM",
+        "USA.XP",
+        "INT.XP",
+        "INT.IP.AIR",
+        "INT.IP.SURF",
+        "INT.SP.AIR",
+        "INT.SP.SURF",
+        "INT.TP"
+    ]], optional
+        List of services to be used for the shipment.
+
+    Returns
+    -------
+    list[Rate] or None
+        List of rates or None.
+    """
+
+    rates = client.rating.rates.get_rates(
+        origin_postal_code,
+        destination,
+        promo_code,
+        quote_type,
+        expected_mailing_date,
+        options,
+        parcel_characteristics,
+        unpackaged,
+        mailing_tube,
+        oversized,
+        services
+    )
+    return rates

py_canada_post/cli/rating/rating_app.py

@@ -0,0 +1,12 @@
+from cyclopts import App
+
+from .commands.discover_services import discover_services
+from .commands.get_rates import get_rates
+
+rating_app = App(
+    name="rating",
+    help="Command to contain all rating-related commands (e.g. get_rates, discover_services etc.)."
+)
+
+rating_app.command(get_rates)
+rating_app.command(discover_services)

py_canada_post/client.py

@@ -0,0 +1,113 @@
+import os
+from base64 import b64encode
+from typing import Literal
+from typing import Self
+
+from dotenv import load_dotenv
+from requests.auth import to_native_string
+
+from py_canada_post.services.rating.rating import Rating
+
+load_dotenv()
+
+
+class PyCanadaPost:
+    def __init__(
+            self,
+            customer_number: int,
+            api_key: str,
+            environment: Literal["SANDBOX", "PRODUCTION"] = "SANDBOX",
+            contract_id: int = None,
+            language: Literal["en-CA", "fr-CA"] = "en-CA"
+    ) -> None:
+        """
+        Initialize class variables.
+
+        Parameters
+        ----------
+        customer_number : int
+            Customer number that was obtained from Canada Post Developer Portal.
+        api_key : str
+            Api key that was obtained from Canada Post Developer Porta
+        environment : Literal["SANDBOX", "PRODUCTION"], default "SANDBOX"
+            Environment of the app.
+        contract_id : int, optional
+            Contract id that was obtained from Canada Post Developer Portal.
+        language : Literal["en-CA", "fr-CA"], default "en-CA"
+            Language to use.
+        """
+
+        self.customer_number = customer_number
+        self.contract_id = contract_id
+        self.environment = environment
+        self.language = language
+        self._api_key = api_key
+
+        self.endpoint = self._get_endpoint()
+        self.headers = self._get_headers()
+
+        self.rating = Rating(self.headers, self.endpoint, self.customer_number, self.contract_id)
+
+    def _get_endpoint(self) -> str:
+        """
+        Function to get an endpoint based on the environment.
+
+        Returns
+        -------
+        str
+            Endpoint.
+        """
+
+        endpoints = {
+            "SANDBOX": "https://ct.soa-gw.canadapost.ca",
+            "PRODUCTION": "https://soa-gw.canadapost.ca"
+        }
+
+        return endpoints[self.environment]
+
+    def _get_headers(self) -> dict:
+        """
+        Function to get essential headers.
+
+        Returns
+        -------
+        dict
+            Headers.
+        """
+
+        username, password = self._api_key.split(":")
+
+        username = username.encode("latin1")
+        password = password.encode("latin1")
+
+        return {
+            "Accept-Language": self.language,
+            "Authorization": "Basic " + to_native_string(b64encode(b":".join((username, password))).strip())
+        }
+
+    @classmethod
+    def from_env(cls) -> Self:
+        """
+        Function to initialize PyCanadaPost client object based on the .env variables.
+        Function raises an error if .env variables don't exist.
+
+        Returns
+        -------
+        Self@PyCanadaPost
+            PyCanadaPost client object.
+        """
+        customer_number = os.getenv("CUSTOMER_NUMBER", None)
+        api_key = os.getenv("API_KEY", None)
+        contract_id = os.getenv("CONTRACT_ID", None)
+
+        if not customer_number or not api_key or not contract_id:
+            raise AssertionError(
+                "Missing .env variables. "
+                "Please make sure you have CUSTOMER_NUMBER, API_KEY and CONTRACT_ID set up in your .env"
+            )
+
+        return cls(
+            customer_number=int(customer_number),
+            api_key=api_key,
+            contract_id=int(contract_id),
+        )

py_canada_post/exceptions/__init__.py

@@ -0,0 +1,37 @@
+from py_canada_post.exceptions.exceptions import (
+    CanadaPostError,
+    ServerError,
+    UserIdDeactivated,
+    EndpointMissmatch,
+    APIMissmatch,
+    InvalidCustomer,
+    UnspecifiedPlatform,
+    PlatformNotAuthorized,
+    InactivePlatform,
+    UnauthorizedPlatform,
+    InvalidPlatformKeyType,
+    IncorrectPlatformRequest,
+    PostOfficesNotFound,
+    InvalidContractNumber,
+    InvalidPostalCode,
+    MissingOriginPostalCode
+)
+
+__all__ = [
+    "CanadaPostError",
+    "ServerError",
+    "UserIdDeactivated",
+    "EndpointMissmatch",
+    "APIMissmatch",
+    "InvalidCustomer",
+    "UnspecifiedPlatform",
+    "PlatformNotAuthorized",
+    "InactivePlatform",
+    "UnauthorizedPlatform",
+    "InvalidPlatformKeyType",
+    "IncorrectPlatformRequest",
+    "PostOfficesNotFound",
+    "InvalidContractNumber",
+    "InvalidPostalCode",
+    "MissingOriginPostalCode"
+]

py_canada_post/exceptions/exception_map.py

@@ -0,0 +1,138 @@
+from .exceptions import (
+    ServerError,
+    UserIdDeactivated,
+    EndpointMissmatch,
+    APIMissmatch,
+    InvalidCustomer,
+    UnspecifiedPlatform,
+    PlatformNotAuthorized,
+    InactivePlatform,
+    UnauthorizedPlatform,
+    InvalidPlatformKeyType,
+    IncorrectPlatformRequest,
+    PostOfficesNotFound,
+    InvalidContractNumber,
+    InvalidPostalCode,
+    InvalidDestinationCountry,
+    MissingOriginPostalCode
+)
+
+
+class ExceptionDefinition:
+    def __init__(self, exception: type[Exception], description: str, mitigation: str = None) -> None:
+        """
+        Initialize class variables.
+
+        Parameters
+        ----------
+        exception : type[Exception]
+            Exception-type (e.g. ServerError, UserIdDeactivated).
+        description : str
+            Description of the error to display.
+        mitigation : str, optional
+            Steps to fix the issue arisen.
+        """
+
+        self.exception = exception
+        self.description = description
+        self.mitigation = mitigation
+
+
+ERROR_MAP: dict[str, ExceptionDefinition] = {
+    "Server": ExceptionDefinition(
+        ServerError,
+        "Rejected by SLM Monitor",
+        "You have exceeded the throttle limit for your API key. "
+        "You will be blocked from making additional calls for up to a minute."
+    ),
+    "AA001": ExceptionDefinition(
+        UserIdDeactivated,
+        "The user id for the request has been deactivated. "
+        "If you withdrew from the Developer Program, rejoin the program.",
+        "From the Developer Program website, select Join Now."
+    ),
+    "AA002": ExceptionDefinition(
+        EndpointMissmatch,
+        "The username and password of the request do not match the endpoint. "
+        "E.g. development key against production endpoint or vice versa.",
+        "Merchant requests cannot be sent to the development environment."
+    ),
+    "AA003": ExceptionDefinition(
+        APIMissmatch,
+        "The API key in the 'Authorization' header does not match "
+        "the mailed-by customer number in the request.",
+        "Verify your data."
+    ),
+    "AA004": ExceptionDefinition(
+        InvalidCustomer,
+        "You cannot mail on behalf of the requested customer."
+    ),
+    "AA005": ExceptionDefinition(
+        UnspecifiedPlatform,
+        "Platform id not specified",
+        "The platform-id header variable is empty or not present in the URL. "
+        "This should only be encountered during platform development coding."
+    ),
+    "AA006": ExceptionDefinition(
+        PlatformNotAuthorized,
+        "Platform not authorized",
+        "The platform-id specified is incorrect or the merchant subsequently came to "
+        "Canada Post and intentionally revoked permission for your platform to submit transactions on its behalf. "
+        "The merchant could be asked to revalidate with Canada Post if they "
+        "want to re-establish their relationship with the platform. "
+        "This error would also occur if the online owner of the platform key voluntarily "
+        "withdrew from the Developer Program. In rare cases, Canada Post may have deactivated "
+        "the entire platform status due to fraud or misuse concerns."
+    ),
+    "AA007": ExceptionDefinition(
+        InactivePlatform,
+        "Platform not active",
+        "You will receive this error if you have tried to use "
+        "Get Merchant Registration Token while your application to become an approved e-commerce "
+        "platform with Canada Post is still pending. "
+        "You cannot use this service until Canada Post has approved your application. "
+        "In rare cases, Canada Post may have deactivated the entire platform status due to fraud or misuse concerns."
+    ),
+    "AA008": ExceptionDefinition(
+        UnauthorizedPlatform,
+        "Unauthorized Platform",
+        "You will receive this error if you are attempting to use Get Merchant"
+        " Registration Token service but have not applied to become an e-commerce platform with Canada Post. "
+        "To apply, sign in to the Developer Program home page and select Become a Platform."
+    ),
+    "AA009": ExceptionDefinition(
+        InvalidPlatformKeyType,
+        "Key type not valid for platform-id",
+        "If a key other than a merchant key is being used to authenticate a transaction, "
+        "the platform-id field must not be specified. Remove the platform-id field from the "
+        "request even if you are a registered platform. Only requests done on behalf of a "
+        "merchant can specify the platform-id."
+    ),
+    "AA010": ExceptionDefinition(
+        IncorrectPlatformRequest,
+        "Incorrectly configured platform request.",
+        "The platform-id in the header and the platform-id in the URL disagree. "
+        "These values must match."
+    ),
+    "E00010": ExceptionDefinition(
+        PostOfficesNotFound,
+        "No Post Offices found"
+    ),
+    "2550": ExceptionDefinition(
+        InvalidContractNumber,
+        "The contract number is not valid.",
+        "Please enter the correct contract number"
+    ),
+    "7266": ExceptionDefinition(
+        InvalidPostalCode,
+        "Postal Code must be in format A9A or A9A9A9."
+    ),
+    "8534": ExceptionDefinition(
+        InvalidDestinationCountry,
+        "A valid destination country must be supplied."
+    ),
+    "9194": ExceptionDefinition(
+        MissingOriginPostalCode,
+        "origin-postal-code must also be provided when destination-postal-code is provided."
+    )
+}