apc-hypaship 0.1.1__tar.gz

apc_hypaship-0.1.1/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.3
+Name: apc-hypaship
+Version: 0.1.1
+Summary: Basic API client for APC-Hypaship platform
+Author: paw
+Author-email: paw <pawrequest@users.noreply.github.com>
+Requires-Dist: dotenv>=0.9.9
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: pydantic-settings>=2.11.0
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+

apc_hypaship-0.1.1/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["uv_build>=0.8.22,<0.9.0"]
+build-backend = "uv_build"
+
+[project]
+name = "apc-hypaship"
+version = "0.1.1"
+description = "Basic API client for APC-Hypaship platform"
+readme = "README.md"
+authors = [
+    { name = "paw", email = "pawrequest@users.noreply.github.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "dotenv>=0.9.9",
+    "httpx>=0.28.1",
+    "loguru>=0.7.3",
+    "pydantic-settings>=2.11.0",
+]
+[dependency-groups]
+dev = [
+    "autodoc-pydantic>=2.2.0",
+    "myst-parser>=4.0.1",
+    "pytest>=8.4.2",
+    "sphinx>=8.2.3",
+    "sphinx-autodoc-typehints>=3.2.0",
+    "sphinx-readme>=1.2.1",
+    "sphinx-rtd-dark-mode>=1.3.0",
+    "sphinx-rtd-theme>=3.0.2",
+]
+#[[tool.uv.index]]
+#name = "testpypi"
+#url = "https://test.pypi.org/simple/"
+#publish-url = "https://test.pypi.org/legacy/"
+#explicit = true
+

apc_hypaship-0.1.1/src/apc_hypaship/apc_client.py

@@ -0,0 +1,77 @@
+from typing import Literal
+
+import httpx
+
+from apc_hypaship.config import APCSettings, apc_settings
+from apc_hypaship.models.response.label_track import Tracks
+from apc_hypaship.models.response.resp import BookingResponse, ServiceAvailabilityResponse
+from apc_hypaship.models.response.shipment import Label
+from apc_hypaship.models.request.shipment import Shipment
+
+ResponseMode = Literal['raw'] | Literal['json'] | type
+
+
+def make_post(
+    url: str,
+    data: dict | None = None,
+    settings: APCSettings = apc_settings(),
+) -> httpx.Response:
+    headers = settings.headers
+    res = httpx.post(url, headers=headers, json=data, timeout=30)
+    res.raise_for_status()
+    return res
+
+
+def make_get(
+    url: str,
+    params: dict | None = None,
+    settings: APCSettings = apc_settings(),
+) -> httpx.Response:
+    headers = settings.headers
+    res = httpx.get(url, headers=headers, params=params, timeout=30)
+    res.raise_for_status()
+    return res
+
+
+def service_available(
+    shipment: Shipment,
+    settings: APCSettings = apc_settings(),
+) -> ServiceAvailabilityResponse:
+    shipment_dict = shipment.model_dump(by_alias=True, mode='json')
+    res = make_post(settings.services_endpoint, shipment_dict)
+    return ServiceAvailabilityResponse(**res.json())
+
+
+def book_shipment(
+    shipment: Shipment,
+    settings=apc_settings(),
+) -> BookingResponse:
+    shipment_dict = shipment.model_dump(by_alias=True, mode='json')
+    res = make_post(url=settings.orders_endpoint, data=shipment_dict, settings=settings)
+    return BookingResponse(**res.json())
+
+
+def get_label(
+    shipment_num: str,
+    settings: APCSettings = apc_settings(),
+) -> Label:
+    params = {'labelformat': 'PDF'}
+    label = make_get(
+        url=settings.one_order_endpoint(shipment_num),
+        params=params,
+        settings=settings,
+    )
+    label = BookingResponse(**label.json())
+    return label.orders.order.label
+
+
+def get_tracks(
+    shipment_num: str,
+    settings: APCSettings = apc_settings(),
+) -> Tracks:
+    res = make_get(url=settings.track_endpoint(shipment_num), settings=settings)
+    res = res.json()
+    t = res.get('Tracks')
+    return Tracks(**t)
+
+

apc_hypaship-0.1.1/src/apc_hypaship/config.py

@@ -0,0 +1,88 @@
+import os
+from datetime import date, time
+from functools import lru_cache
+from pathlib import Path
+import base64
+from typing import Annotated
+
+from loguru import logger
+from pydantic import BaseModel, ConfigDict, SecretStr, AliasGenerator, StringConstraints
+from pydantic.alias_generators import to_pascal
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+def encode_b64_str(s: str) -> str:
+    return base64.b64encode(s.encode('utf8')).decode('utf8')
+
+
+def get_remote_user(login, password) -> str:
+    usr_str = f'{login}:{password}'
+    return f'Basic {encode_b64_str(usr_str)}'
+
+
+def apc_date(d: date) -> str:
+    return d.strftime('%d/%m/%Y')
+
+
+def load_env() -> Path:
+    apc_env = Path(os.getenv('APC_ENV'))
+    if not apc_env.exists():
+        raise ValueError('APC_ENV not set correctly')
+    logger.debug(f'Loading APC environment from {apc_env}')
+    return apc_env
+
+
+class APCSettings(BaseSettings):
+    apc_email: SecretStr
+    apc_password: SecretStr
+    base_url: str
+    model_config = SettingsConfigDict(env_file=load_env())
+
+    @property
+    def headers(self) -> dict:
+        usr = self.apc_email.get_secret_value()
+        pwd = self.apc_password.get_secret_value()
+        return {
+            'Content-Type': 'application/json',
+            'remote-user': get_remote_user(usr, pwd),
+        }
+
+    @property
+    def services_endpoint(self) -> str:
+        return self.base_url + 'ServiceAvailability.json'
+
+    @property
+    def orders_endpoint(self) -> str:
+        return self.base_url + 'Orders.json'
+
+    def one_order_endpoint(self, order_num: str) -> str:
+        return self.base_url + f'Orders/{order_num}.json'
+
+    def track_endpoint(self, order_num: str) -> str:
+        return self.base_url + f'Tracks/{order_num}.json'
+
+
+@lru_cache
+def apc_settings() -> APCSettings:
+    return APCSettings()
+
+
+class APCBaseModel(BaseModel):
+    model_config = ConfigDict(
+        json_encoders={
+            time: lambda v: v.strftime('%H:%M'),
+            date: lambda v: v.strftime('%d/%m/%Y'),
+        },
+        alias_generator=AliasGenerator(
+            alias=to_pascal,
+        ),
+        populate_by_name=True,
+        use_enum_values=True,
+    )
+
+
+def str_length_const(length: int):
+    return Annotated[
+        str,
+        StringConstraints(strip_whitespace=True, max_length=length),
+    ]

apc_hypaship-0.1.1/src/apc_hypaship/models/request/address.py

@@ -0,0 +1,29 @@
+# from pawdantic.paw_types import str_length_const
+
+from apc_hypaship.config import APCBaseModel, str_length_const
+
+
+class Contact(APCBaseModel):
+    person_name: str
+    phone_number: str | None = None
+    mobile_number: str
+    email: str | None
+
+
+class Address(APCBaseModel):
+    contact: Contact
+    company_name: str = str_length_const(34)
+    address_line_1: str_length_const(64)
+    address_line_2: str_length_const(64) | None = None
+    city: str
+    county: str | None = None
+    postal_code: str
+    country_code: str = 'GB'
+    country_name: str | None = None
+    instructions: str | None = None
+    safeplace: str | None = None
+
+
+class AddressDelivery(Address):
+    instructions: str = ''
+

apc_hypaship-0.1.1/src/apc_hypaship/models/request/services.py

@@ -0,0 +1,42 @@
+from types import MappingProxyType
+
+from pydantic import ConfigDict
+
+from apc_hypaship.config import APCBaseModel
+
+APC_SERVICES_DICT = dict(
+    NEXT_DAY="ND16",
+    NEXT_DAY_12="ND12",
+    NEXT_DAY_9="ND09",
+)
+
+
+class ServiceSpec(APCBaseModel):
+    model_config = ConfigDict(extra="ignore")
+    Carrier: str
+    CollectionDate: str
+    Currency: str
+    DeliveryGroup: str
+    EstimatedDeliveryDate: str
+    ExtraCharges: str
+    FuelCharge: str
+    InsuranceCharge: str
+    ItemType: str
+    LatestBookingDateTime: str
+    MaxCompensation: str
+    MaxItemHeight: str
+    MaxItemLength: str
+    MaxItemWidth: str
+    MaxTransitDays: str
+    MinTransitDays: str
+    ProductCode: str
+    Rate: str
+    ServiceName: str
+    Signed: str
+    TotalCost: str
+    Tracked: str
+    Vat: str
+    VolumetricWeight: str
+    WeightUnit: str
+
+

apc_hypaship-0.1.1/src/apc_hypaship/models/request/shipment.py

@@ -0,0 +1,69 @@
+from datetime import date, time
+from typing import Literal, Sequence
+
+from pydantic import Field, model_validator
+from loguru import logger
+
+from apc_hypaship.models.request.address import Address
+from apc_hypaship.config import APCBaseModel
+
+
+class Item(APCBaseModel):
+    type: Literal["ALL"] = "ALL"
+    weight: float | None = 12
+    length: float | None = None
+    width: float | None = None
+    height: float | None = None
+    reference: str | None = None
+
+
+class Items(APCBaseModel):
+    item: Sequence[Item] = Field(default_factory=list)
+
+
+class ShipmentDetails(APCBaseModel):
+    number_of_pieces: int
+    items: Items | None = None
+
+    @model_validator(mode="after")
+    def check_items(self):
+        if not self.items:
+            self.items = Items(item=[Item() for _ in range(self.number_of_pieces)])
+            logger.debug("Auto-filled items with weight = 12kg per box")
+        return self
+
+
+class GoodsInfo(APCBaseModel):
+    goods_value: str = "1000"
+    goods_description: str = "Radios"
+    fragile: bool = False
+    security: bool = False
+    increased_liability: bool = False
+    premium_insurance: bool = False
+    premium: bool = False
+
+
+
+
+class Order(APCBaseModel):
+    collection_date: date
+    ready_at: time = time(hour=9)
+    closed_at: time = time(hour=17)
+    product_code: str
+    reference: str
+    collection: Address | None = None
+    delivery: Address
+    goods_info: GoodsInfo
+    shipment_details: ShipmentDetails
+
+
+class Orders(APCBaseModel):
+    order: Order
+
+
+class Shipment(APCBaseModel):
+    orders: Orders
+
+    @classmethod
+    def from_order(cls, order: Order) -> "Shipment":
+        return cls(orders=Orders(order=order))

apc_hypaship-0.1.1/src/apc_hypaship/models/response/address.py

@@ -0,0 +1,16 @@
+from apc_hypaship.models.request.address import Address as _Address, Contact as _Contact
+
+
+class Contact(_Contact):
+    person_name: str | None = None
+    mobile_number: str | None = None
+    email: str | None = None
+
+
+class Address(_Address):
+    company_name: str | None = None
+    address_line_1: str | None = None
+    postal_code: str | None = None
+    city: str | None = None
+    country_code: str | None = None
+    contact: Contact | None = None

apc_hypaship-0.1.1/src/apc_hypaship/models/response/common.py

@@ -0,0 +1,6 @@
+from apc_hypaship.config import APCBaseModel
+
+
+class Messages(APCBaseModel):
+    code: str | None = None
+    description: str | None = None

apc_hypaship-0.1.1/src/apc_hypaship/models/response/label_track.py

@@ -0,0 +1,31 @@
+from apc_hypaship.config import APCBaseModel
+from apc_hypaship.models.response.address import Address
+from apc_hypaship.models.response.common import Messages
+from apc_hypaship.models.response.service import GoodsInfo
+from apc_hypaship.models.response.shipment import Depots, ShipmentDetails
+
+
+class Track(APCBaseModel):
+    adult_signature: str | None = None
+    closed_at: str | None = None
+    collection: Address | None = None
+    collection_date: str | None = None
+    custom_reference1: str | None = None
+    custom_reference2: str | None = None
+    custom_reference3: str | None = None
+    delivery: Address | None = None
+    depots: Depots | None = None
+    goods_info: GoodsInfo | None = None
+    item_option: str | None = None
+    order_number: str | None = None
+    product_code: str | None = None
+    ready_at: str | None = None
+    reference: str | None = None
+    shipment_details: ShipmentDetails | None = None
+    way_bill: str | None = None
+
+
+class Tracks(APCBaseModel):
+    account_number: str | None = None
+    messages: Messages | None = None
+    track: Track | None = None

apc_hypaship-0.1.1/src/apc_hypaship/models/response/parcelspecs.py

@@ -0,0 +1,66 @@
+from enum import Enum
+
+from apc_hypaship.config import APCBaseModel
+
+
+class ParcelSpec(APCBaseModel):
+    name: str
+    service_code: str
+    max_len: float
+    max_width: float
+    max_height: float | None
+    max_weight: float
+    max_items: int
+    notes: str | None = None
+
+
+class ParcelSpecs(Enum):
+    MAILPACK = ParcelSpec(
+        name='MailPack',
+        service_code='MP',
+        max_len=37.5,
+        max_width=29.5,
+        max_height=None,
+        max_weight=1,
+        max_items=1,
+        notes='must fit in provided or pre-approved packaging',
+    )
+    COURIERPACK = ParcelSpec(
+        name='CourierPack',
+        service_code='CP',
+        max_len=54.5,
+        max_width=45.5,
+        max_height=None,
+        max_weight=5,
+        max_items=1,
+        notes='must fit in provided or pre-approved packaging',
+    )
+    LIGHTWEIGHTPARCEL = ParcelSpec(
+        name='Lightweight Parcel',
+        service_code='LW',
+        max_len=45.0,
+        max_width=35.0,
+        max_height=20.0,
+        max_weight=5,
+        max_items=1,
+    )
+    STANDARDNEXTDAYPARCEL = ParcelSpec(
+        name='Standard Next Day Parcel',
+        service_code='ND',
+        max_len=120.0,
+        max_width=55.0,
+        max_height=50.0,
+        max_weight=30,
+        max_items=20,
+        notes='max 60x60x60 also ok',
+    )
+    NONCONVEYABLEPARCEL = ParcelSpec(
+        name='Non-Conveyable Parcel',
+        service_code='NC',
+        max_len=160.0,
+        max_width=60.0,
+        max_height=60.0,
+        max_weight=30,
+        max_items=2,
+        notes='width+height < 120 also ok',
+    )

apc_hypaship-0.1.1/src/apc_hypaship/models/response/resp.py

@@ -0,0 +1,31 @@
+from apc_hypaship.config import APCBaseModel
+from apc_hypaship.models.response.common import Messages
+from apc_hypaship.models.response.service import Services
+from apc_hypaship.models.response.shipment import Orders, Order
+
+
+class Response(APCBaseModel): ...
+
+
+class BookingResponse(Response):
+    orders: Orders | None = None
+
+    @property
+    def order_num(self):
+        return self.orders.order.order_number if self.orders and self.orders.order else None
+
+
+class OrdersResponse(APCBaseModel):
+    orders: Orders
+
+
+class ServiceAvailability(APCBaseModel):
+    account_number: str | None = None
+    messages: Messages | None = None
+    order: Order | None = None
+    services: Services | None = None
+
+
+class ServiceAvailabilityResponse(APCBaseModel):
+    service_availability: ServiceAvailability
+

apc_hypaship-0.1.1/src/apc_hypaship/models/response/service.py

@@ -0,0 +1,53 @@
+from pydantic import Field
+
+from apc_hypaship.config import APCBaseModel
+from apc_hypaship.models.request.shipment import GoodsInfo as _GoodsInfo
+
+
+class GoodsInfo(_GoodsInfo):
+    goods_description: str | None = None
+    non_conv: str | None = None
+    charge_on_delivery: str | None = None
+    goods_value: str | None = None
+
+
+class Rates(APCBaseModel):
+    rate: str | None = None
+    extra_charges: str | None = None
+    fuel_charge: str | None = None
+    insurance_charge: str | None = None
+    vat: str | None = None
+    total_cost: str | None = None
+    currency: str | None = None
+
+
+class Service(APCBaseModel):
+    carrier: str | None = None
+    service_name: str | None = None
+    product_code: str | None = None
+    min_transit_days: str | None = None
+    max_transit_days: str | None = None
+    tracked: str | None = None
+    signed: str | None = None
+    max_compensation: str | None = None
+    max_item_length: str | None = None
+    max_item_width: str | None = None
+    max_item_height: str | None = None
+    item_type: str | None = None
+    delivery_group: str | None = None
+    collection_date: str | None = None
+    estimated_delivery_date: str | None = None
+    latest_booking_date_time: str | None = None
+    rate: str | None = None
+    extra_charges: str | None = None
+    fuel_charge: str | None = None
+    insurance_charge: str | None = None
+    vat: str | None = None
+    total_cost: str | None = None
+    currency: str | None = None
+    volumetric_weight: str | None = None
+    weight_unit: str | None = None
+
+
+class Services(APCBaseModel):
+    service: list[Service] = Field(default_factory=list)

apc_hypaship-0.1.1/src/apc_hypaship/models/response/shipment.py

@@ -0,0 +1,82 @@
+from typing import Union, List
+
+from apc_hypaship.config import APCBaseModel
+from apc_hypaship.models.response.address import Address
+from apc_hypaship.models.response.common import Messages
+from apc_hypaship.models.response.service import GoodsInfo, Rates
+
+
+class Label(APCBaseModel):
+    content: bytes | None = None
+    format: str | None = None
+
+
+class Item(APCBaseModel):
+    item_number: str | None = None
+    tracking_number: str | None = None
+    type: str | None = None
+    weight: str | None = None
+    length: str | None = None
+    width: str | None = None
+    height: str | None = None
+    value: str | None = None
+    reference: str | None = None
+    label: Label | None = None
+
+
+class Items(APCBaseModel):
+    item: Item | None = None
+
+
+class ShipmentDetails(APCBaseModel):
+    items: Union[Item, List[Item]] | None = None
+    number_of_pieces: str | None = None
+    total_weight: str | None = None
+    volumetric_weight: str | None = None
+
+
+class Depots(APCBaseModel):
+    collecting_depot: str | None = None
+    delivery_depot: str | None = None
+    delivery_route: str | None = None
+    is_scottish: str | None = None
+    presort: str | None = None
+    request_depot: str | None = None
+    route: str | None = None
+    seg_code: str | None = None
+    zone: str | None = None
+
+
+class Order(APCBaseModel):
+    messages: Messages | None = None
+    account_number: list[str] | None = None
+    entry_type: str | None = None
+    collection_date: str | None = None
+    ready_at: str | None = None
+    closed_at: str | None = None
+    product_code: str | None = None
+    rule_name: str | None = None
+    item_option: str | None = None
+    order_number: str | None = None
+    way_bill: str | None = None
+    reference: str | None = None
+    custom_reference1: str | None = None
+    custom_reference2: str | None = None
+    custom_reference3: str | None = None
+    adult_signature: str | None = None
+    depots: Depots | None = None
+    collection: Address | None = None
+    delivery: Address | None = None
+    goods_info: GoodsInfo | None = None
+    shipment_details: ShipmentDetails | None = None
+    rates: Rates | None = None
+    barcode: str | None = None
+    delivery_date: str | None = None
+    label: Label | None = None
+    network_name: str | None = None
+
+
+class Orders(APCBaseModel):
+    account_number: str | None = None
+    messages: Messages | None = None
+    order: Order | None = None