shipaw 0.3.0__tar.gz

shipaw-0.3.0/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: shipaw
+Version: 0.3.0
+Summary: Shipping client
+Author: pawrequest
+Author-email: pawrequest <shipaw+pawrequest@users.noreply.github.com>
+License-Expression: MIT
+Requires-Dist: pawdantic
+Requires-Dist: combadge[zeep]
+Requires-Dist: thefuzz
+Requires-Dist: loguru
+Requires-Dist: phonenumbers
+Requires-Dist: pydantic-settings
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pygments>=2.19.2
+Requires-Dist: parcelforce-expresslink
+Requires-Dist: apc-hypaship
+Requires-Dist: pydantic[email]>=2.11.9
+Requires-Dist: pytest>=8.4.2
+Requires-Dist: fastapi[standard]>=0.117.1
+Requires-Dist: pawdf
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: hatchling>=1.27.0
+Requires-Dist: pytest ; extra == 'dev'
+Requires-Dist: autodoc-pydantic ; extra == 'dev'
+Requires-Dist: sphinx ; extra == 'dev'
+Requires-Dist: sphinx-autodoc-typehints ; extra == 'dev'
+Requires-Dist: sphinx-rtd-theme ; extra == 'dev'
+Requires-Dist: myst-parser ; extra == 'dev'
+Requires-Dist: sphinx-readme ; extra == 'dev'
+Requires-Dist: sphinx-rtd-dark-mode ; extra == 'dev'
+Requires-Python: >=3.13
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+

shipaw-0.3.0/pyproject.toml

@@ -0,0 +1,83 @@
+[project]
+license = "MIT"
+name = "shipaw"
+version = "0.3.0"
+description = "Shipping client"
+authors = [
+    { name = "pawrequest", email = "shipaw+pawrequest@users.noreply.github.com" }
+]
+readme = "README.md"
+requires-python = ">= 3.13"
+dependencies = [
+    'pawdantic', # special pydantic types eg truncated strings
+    'combadge[zeep]', # xml client
+    'thefuzz', # fuzzy search to match addresses
+    'loguru', # logging
+    'phonenumbers',
+    'pydantic-settings',
+    "httpx>=0.28.1",
+    "pygments>=2.19.2",
+    #    "royal-mail-click-and-drop",
+    "parcelforce-expresslink",
+    "apc-hypaship",
+    "pydantic[email]>=2.11.9",
+    "pytest>=8.4.2",
+    "fastapi[standard]>=0.117.1",
+    "pawdf",
+    "jinja2>=3.1.6",
+    "hatchling>=1.27.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    'pytest',
+    'autodoc_pydantic',
+    "sphinx",
+    "sphinx-autodoc-typehints",
+    "sphinx-rtd-theme",
+    "myst-parser",
+    "sphinx-readme",
+    "sphinx_rtd_dark_mode",
+]
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.ruff]
+line-length = 120
+extend-select = ["Q", "RUF100", "UP"]
+flake8-quotes = { inline-quotes = "single", multiline-quotes = "double" }
+format.quote-style = "single"
+
+[tool.uv.sources]
+pawdantic = { git = 'https://github.com/pawrequest/pawdantic' }
+pawdf = { git = 'https://github.com/pawrequest/pawdf' }
+royal-mail-click-and-drop = { git = "https://github.com/pawrequest/royal-mail-click-and-drop" }
+parcelforce-expresslink = { git = "https://github.com/pawrequest/parcelforce_expresslink" }
+apc-hypaship = { git = "https://github.com/pawrequest/apc-hypaship" }
+#
+
+[build-system]
+requires = ["uv_build"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+#data = { data = "ui" }
+source-includes = ["src/shipaw/ui/**"]
+
+#[tool.uv.build-backend]
+#source-include = ["src/shipaw/ui/**"]
+#[tool.uv.build-backend.data]
+#["src/shipaw/ui"]
+
+
+#[build-system]
+#requires = ["hatchling"]
+#build-backend = "hatchling.build"
+
+
+#[tool.hatch.build.targets.sdist]
+#include = [
+#    "src/",
+#    "ui/,
+#]

shipaw-0.3.0/src/shipaw/__init__.py

@@ -0,0 +1,3 @@
+# from .providers import *
+#
+# __all__ = ['ParcelforceShippingProvider', 'APCShippingProvider']

shipaw-0.3.0/src/shipaw/config.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+from importlib.resources import files
+
+import functools
+import os
+import re
+from datetime import date, datetime
+from pathlib import Path
+from urllib.parse import quote
+
+import pydantic as _p
+from dotenv import load_dotenv
+from fastapi.encoders import jsonable_encoder
+from loguru import logger
+from pydantic import Field, computed_field, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from starlette.templating import Jinja2Templates
+
+from shipaw.models.address import Address, Contact, FullContact
+from shipaw.models.ship_types import ShipDirection
+
+
+def load_env_index(envs_index: Path) -> None:
+    load_dotenv(envs_index)
+
+
+# def load_envs() -> Path:
+#     shipaw_envs = Path(os.getenv('SHIPAW_ENVS'))
+#     if not shipaw_envs or not shipaw_envs.exists():
+#         raise ValueError('SHIPAW_ENVS not set')
+#
+#     apc = shipaw_envs / 'apc.env'
+#     pf = shipaw_envs / 'parcelforce.env'
+#     shipaw_env = shipaw_envs / 'shipaw.env'
+#
+#     for f in (apc, pf, shipaw_env):
+#         if not f.exists():
+#             raise ValueError(f'Env file {f} does not exist')
+#
+#     os.environ['APC_ENV'] = str(apc)
+#     os.environ['PARCELFORCE_ENV'] = str(pf)
+#     os.environ['SHIPAW_ENV'] = str(shipaw_env)
+#     return shipaw_env
+
+
+#
+def load_env():
+    ei = Path(os.environ.get('ENV_INDEX'))
+    load_env_index(ei)
+    shipaw_env = os.getenv('SHIPAW_ENV')
+    shipaw_env = Path(shipaw_env) if shipaw_env else None
+    if not shipaw_env or not shipaw_env.exists():
+        raise ValueError('SHIPAW_ENV not set')
+    logger.debug(f'Loading SHIPAW environment from {shipaw_env}')
+    return shipaw_env
+
+
+def sanitise_id(value):
+    return re.sub(r'\W|^(?=\d)', '_', value).lower()
+
+
+def date_int_w_ordinal(n: int):
+    """Convert an integer to its ordinal as a string, e.g. 1 -> 1st, 2 -> 2nd, etc."""
+    return str(n) + ('th' if 4 <= n % 100 <= 20 else {1: 'st', 2: 'nd', 3: 'rd'}.get(n % 10, 'th'))
+
+
+def ordinal_dt(dt: datetime | date) -> str:
+    """Convert a datetime or date to a string with an ordinal day, e.g. 'Mon 1st Jan 2020'."""
+    return dt.strftime(f'%a {date_int_w_ordinal(dt.day)} %b %Y')
+
+
+def get_ui():
+    res = files('shipaw').joinpath('ui')
+    return res
+
+
+class ShipawSettings(BaseSettings):
+    # toggles
+    shipper_live: bool = False
+    log_level: str = 'DEBUG'
+
+    # dirs
+    label_dir: Path
+    log_dir: Path
+    ui_dir: Path = Field(default_factory=get_ui)
+
+    # auto dirs
+    static_dir: Path | None = None
+    template_dir: Path | None = None
+    templates: Jinja2Templates | None = None
+
+    # sender details
+    address_line1: str
+    address_line2: str | None = None
+    address_line3: str | None = None
+    town: str
+    postcode: str
+    country: str = 'GB'
+    business_name: str
+    contact_name: str
+    email: str
+    phone: str | None = None
+    mobile_phone: str
+
+    model_config = SettingsConfigDict(env_ignore_empty=True, env_file=load_env())
+
+    ## SET UI/TEMPLATE DIRS ##
+    @model_validator(mode='after')
+    def set_ui(self):
+        self.static_dir = self.static_dir or self.ui_dir / 'static'
+        self.template_dir = self.template_dir or self.ui_dir / 'templates'
+        self.templates = self.templates or Jinja2Templates(directory=self.template_dir)
+        self.templates.env.filters['jsonable'] = jsonable_encoder
+        self.templates.env.filters['urlencode'] = lambda value: quote(str(value))
+        self.templates.env.filters['sanitise_id'] = sanitise_id
+        self.templates.env.filters['ordinal_dt'] = ordinal_dt
+        return self
+
+    ## SET LOGGING & LABELS ##
+    @computed_field
+    @property
+    def log_file(self) -> Path:
+        return self.log_dir / 'shipaw.log'
+
+    @computed_field
+    @property
+    def ndjson_log_file(self) -> Path:
+        return self.log_dir / 'shipaw.ndjson'
+
+    @_p.model_validator(mode='after')
+    def create_log_files(self):
+        self.log_dir.mkdir(parents=True, exist_ok=True)
+        for v in (self.log_file, self.ndjson_log_file):
+            v.touch()
+        return self
+
+    @_p.field_validator('label_dir', mode='after')
+    def create_label_dirs(cls, v, values):
+        directions = [_ for _ in ShipDirection]
+        for subdir in directions:
+            apath = v / subdir
+            if not apath.exists():
+                apath.mkdir(parents=True, exist_ok=True)
+        return v
+
+    ## SET ADDRESS/CONTACT OBJECTS FROM ENV VARS ##
+    @property
+    def contact(self):
+        return Contact(
+            contact_name=self.contact_name,
+            email_address=self.email,
+            mobile_phone=self.mobile_phone,
+        )
+
+    @property
+    def address(self):
+        return Address(
+            address_lines=[_ for _ in [self.address_line1, self.address_line2, self.address_line3] if _],
+            town=self.town,
+            postcode=self.postcode,
+            country=self.country,
+            business_name=self.business_name,
+        )
+
+    @property
+    def full_contact(self) -> FullContact:
+        return FullContact(
+            address=self.address,
+            contact=self.contact,
+        )
+
+
+@functools.lru_cache
+def shipaw_settings() -> ShipawSettings:
+    return ShipawSettings.model_validate({})
+

shipaw-0.3.0/src/shipaw/fapi/alerts.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from enum import StrEnum
+
+from pydantic import Field
+
+from shipaw.models.base import ShipawBaseModel
+
+
+class AlertType(StrEnum):
+    ERROR = 'ERROR'
+    WARNING = 'WARNING'
+    NOTIFICATION = 'NOTIFICATION'
+
+
+class Alert(ShipawBaseModel):
+    code: int | None = None
+    message: str
+    type: AlertType = AlertType.NOTIFICATION
+
+    def __eq__(self, other):
+        if not isinstance(other, Alert):
+            return NotImplemented
+        return (self.code, self.message, self.type) == (other.code, other.message, other.type)
+
+    def __hash__(self):
+        return hash((self.code, self.message, self.type))
+
+    @classmethod
+    def from_exception(cls, e: Exception):
+        return cls(message=str(e), type=AlertType.ERROR)
+
+
+class Alerts(ShipawBaseModel):
+    alert: list[Alert] = Field(default_factory=list[Alert])
+
+    def __bool__(self):
+        return bool(self.alert)
+
+    def __add__(self, other: Alerts | Alert):
+        if not isinstance(other, Alerts) and not isinstance(other, Alert):
+            raise TypeError(f'Expected Alerts or Alert instance, got {type(other)}')
+        if isinstance(other, Alert):
+            other = Alerts(alert=[other])
+        combined = set(self.alert) | set(other.alert)
+        return Alerts(alert=list(combined))
+
+    def __iadd__(self, other: Alerts | Alert):
+        if not isinstance(other, Alerts) and not isinstance(other, Alert):
+            raise TypeError(f'Expected Alerts or Alert instance, got {type(other)}')
+        if isinstance(other, Alert):
+            other = Alerts(alert=[other])
+        self.alert = list(set(self.alert) | set(other.alert))
+        return self
+
+    def __sub__(self, other: Alerts | Alert):
+        if not isinstance(other, Alerts) and not isinstance(other, Alert):
+            raise TypeError(f'Expected Alerts or Alert instance, got {type(other)}')
+        if isinstance(other, Alert):
+            other = Alerts(alert=[other])
+        diff = set(self.alert) - set(other.alert)
+        return Alerts(alert=list(diff))
+
+    def __contains__(self, alert: Alert):
+        return alert in set(self.alert)
+
+    @classmethod
+    def empty(cls):
+        return cls(alert=[])
+
+
+async def maybe_alert_phone_number(phone_num: str):
+    """Alert if phone number is not 11 digits or does not start with 01, 02 or 07. (parcelforce requirement)"""
+    alerts = Alerts.empty()
+    if len(phone_num) != 11 or not phone_num[1] in [
+        '1',
+        '2',
+        '7',
+    ]:
+        alerts += Alert(
+            type=AlertType.WARNING,
+            message='The Mobile phone number must be 11 digits and begin with 01, 02 or 07, no SMS will be sent',
+        )
+    return alerts

shipaw-0.3.0/src/shipaw/fapi/app.py

@@ -0,0 +1,78 @@
+import contextlib
+
+from fastapi import FastAPI, responses
+from fastapi.encoders import jsonable_encoder
+from fastapi.exceptions import RequestValidationError
+from loguru import logger
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+from starlette.staticfiles import StaticFiles
+
+from shipaw.config import shipaw_settings
+from shipaw.fapi.alerts import Alert, AlertType, Alerts
+from shipaw.fapi.routes_api import router as json_router
+from shipaw.fapi.routes_html import router as html_router
+
+
+@contextlib.asynccontextmanager
+async def lifespan(app_: FastAPI):
+    try:
+        # set_pf_env()
+        # pythoncom.CoInitialize()
+        # with sqm.Session(am_db.ENGINE) as session:
+        #     pf_shipper = ELClient()
+        #     populate_db_from_cmc(session, pf_shipper)
+        yield
+
+    finally:
+        # pythoncom.CoUninitialize()
+
+        ...
+
+
+app = FastAPI(lifespan=lifespan)
+app.mount('/static', StaticFiles(directory=str(shipaw_settings().static_dir)), name='static')
+app.include_router(json_router, prefix='/api')
+app.include_router(html_router)
+app.ship_live = shipaw_settings().shipper_live
+app.alerts = Alerts.empty()
+
+
+@app.exception_handler(RequestValidationError)
+async def request_validation_exception_handler(request: Request, exc: RequestValidationError):
+    errors = exc.errors()
+    msg2 = ''
+    for err in errors:
+        if type := err.get('type'):
+            msg2 += type + ' '
+        if loc := err.get('loc'):
+            msg2 += f'in {loc} '
+        if ctx := err.get('ctx'):
+            if reason := ctx.get('reason'):
+                msg2 += f': {reason} '
+        if input_ := err.get('input'):
+            msg2 += f'. Input = {input_} '
+
+    logger.error(msg2)
+    alerts = Alerts(alert=[Alert(code=1, message=msg2, type=AlertType.ERROR)])
+    return JSONResponse(
+        status_code=422, content={'detail': jsonable_encoder(exc.errors()), 'alerts': alerts.model_dump(mode='json'), 'message': msg2}
+    )
+
+
+@app.get('/robots.txt', response_class=responses.PlainTextResponse)
+async def robots_txt() -> str:
+    return 'User-agent: *\nAllow: /'
+
+
+@app.get('/favicon.ico', include_in_schema=False)
+async def favicon_ico():
+    return responses.RedirectResponse(url='/static/favicon.svg')
+
+
+@app.get('/', response_class=JSONResponse)
+async def base():
+    return JSONResponse(content={'status': 'ok'})
+
+
+

shipaw-0.3.0/src/shipaw/fapi/backend.py

@@ -0,0 +1,89 @@
+import json
+
+from httpx import HTTPStatusError
+from loguru import logger
+from parcelforce_expresslink.client import ParcelforceClient
+
+from shipaw.fapi.requests import ShipmentRequest
+from shipaw.fapi.responses import ShipmentBookingResponse
+from shipaw.fapi.alerts import AlertType, Alert
+
+
+def extract_http_error_message(exception: HTTPStatusError) -> str:
+    if hasattr(exception, 'response') and exception.response is not None:
+        return exception.response.text
+    logger.warning('HTTPStatusError has no response attribute')
+    return str(exception)
+
+
+def extract_http_error_message_json(exception: HTTPStatusError) -> dict:
+    error_string = extract_http_error_message(exception)
+    try:
+        error_data = json.loads(error_string)
+        return error_data.get('Messages')
+
+    except json.JSONDecodeError:
+        logger.warning('Error.response.text is not valid JSON')
+        return {'Code': error_string, 'Description': ''}
+
+
+async def http_status_alerts(exception: HTTPStatusError) -> list[Alert]:
+    error_dict = extract_http_error_message_json(exception)
+    return [Alert(message=f'{error_dict.get('Code')}:  {error_dict.get('Description')}', type=AlertType.ERROR)]
+
+
+async def try_book_shipment(shipment_request: ShipmentRequest) -> ShipmentBookingResponse:
+    shipment_response = ShipmentBookingResponse(shipment=shipment_request.shipment)
+    try:
+        shipment_response = shipment_request.provider.book_shipment(shipment_request.shipment)
+
+    except HTTPStatusError as e:
+        for alert in await http_status_alerts(e):
+            shipment_response.alerts += alert
+
+    except Exception as e:
+        logger.exception(f'Error booking shipment: {e}')
+        shipment_response.alerts += Alert.from_exception(e)
+
+    return shipment_response
+
+
+async def try_get_label_data(request: ShipmentRequest, response: ShipmentBookingResponse) -> bytes | None:
+    try:
+        if response.label_data is None and response.shipment_num:
+            response.label_data = request.provider.get_label_content(response.shipment_num)
+        return response.label_data
+
+    except HTTPStatusError as e:
+        for alert in await http_status_alerts(e):
+            response.alerts += alert
+        logger.exception(f'HTTP error getting label data')
+
+    except Exception as e:
+        logger.exception(f'Error getting label data')
+        response.alerts += Alert.from_exception(e)
+
+    return None
+
+
+async def try_write_label(response: ShipmentBookingResponse):
+    try:
+        await response.write_label_file()
+    except Exception as e:
+        logger.exception(f'Error writing label file: {e}')
+        response.alerts += Alert.from_exception(e)
+
+
+async def try_get_write_label(request: ShipmentRequest, response: ShipmentBookingResponse):
+    if not response.label_data:
+        await try_get_label_data(request, response)
+    await try_write_label(response)
+
+
+def get_el_client() -> ParcelforceClient:
+    try:
+        return ParcelforceClient()
+    except Exception as e:
+        logger.error(f'Error getting Parcelforce ExpressLink Client: {e}')
+        raise
+

shipaw-0.3.0/src/shipaw/fapi/callbacks.py

@@ -0,0 +1,7 @@
+from typing import Callable, Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from shipaw.fapi.requests import ShipmentRequest
+    from shipaw.fapi.responses import ShipmentBookingResponse
+
+CALLBACK_REGISTER: dict[str, Callable[['ShipmentRequest', 'ShipmentBookingResponse'], Any]] = {}

shipaw-0.3.0/src/shipaw/fapi/form_data.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import json
+from datetime import date
+
+from fastapi import Depends, Form
+from loguru import logger
+from pawdantic.paw_types import VALID_POSTCODE
+from pydantic import EmailStr
+
+from shipaw.models.address import Address, Contact, FullContact
+from shipaw.config import shipaw_settings
+from shipaw.fapi.requests import ShipmentRequest
+from shipaw.models.ship_types import ShipDirection
+from shipaw.models.shipment import Shipment
+
+
+async def full_contact_form(
+    address_line1: str = Form(...),
+    address_line2: str = Form(''),
+    address_line3: str = Form(''),
+    town: str = Form(...),
+    postcode: VALID_POSTCODE = Form(...),
+    contact_name: str = Form(...),
+    email_address: EmailStr = Form(...),
+    business_name: str = Form(...),
+    mobile_phone: str = Form(...),
+) -> FullContact:
+    return FullContact(
+        address=Address(
+            address_lines=[address_line1, address_line2, address_line3],
+            town=town,
+            postcode=postcode,
+            business_name=business_name,
+        ),
+        contact=Contact(
+            contact_name=contact_name,
+            email_address=email_address,
+            mobile_phone=mobile_phone,
+        ),
+    )
+
+
+async def shipment_f_form(
+    full_contact: FullContact = Depends(full_contact_form),
+    shipping_date: date = Form(...),
+    boxes: int = Form(...),
+    service: str = Form(...),
+    direction: ShipDirection = Form(...),
+    reference: str = Form(...),
+    context_json: str = Form(...),
+) -> Shipment:
+    context = json.loads(context_json)
+    logger.info('Creating Shipment Request from form')
+
+    if direction == ShipDirection.OUTBOUND:
+        recipient = full_contact
+        sender = None
+    elif direction in {ShipDirection.INBOUND, ShipDirection.DROPOFF}:
+        recipient = shipaw_settings().full_contact
+        sender = full_contact
+    else:
+        raise ValueError(f'Unknown direction: {direction}')
+
+    shipment = Shipment(
+        recipient=recipient,
+        sender=sender,
+        boxes=boxes,
+        shipping_date=shipping_date,
+        direction=direction,
+        reference=reference,
+        service=service,
+        context=context,
+    )
+    return shipment
+
+
+async def shipment_request_form(
+    shipment: Shipment = Depends(shipment_f_form), provider_name: str = Form(...)
+) -> ShipmentRequest:
+    return ShipmentRequest(
+        shipment=shipment,
+        provider_name=provider_name,
+    )
+
+
+async def shipment_form_json(shipment_json: str = Form(...)) -> Shipment:
+    shipy = Shipment.model_validate_json(shipment_json)
+    return shipy
+
+
+async def shipment_request_form_json(shipment_request_json: str = Form(...)) -> ShipmentRequest:
+    shipy = ShipmentRequest.model_validate_json(shipment_request_json)
+    return shipy
+
+
+async def context_form_json(context_json: str = Form(...)) -> dict:
+    context = json.loads(context_json)
+    return context