amazon-subscriptions 1.0.1__py3-none-any.whl

amazon_subscriptions/dates.py

@@ -0,0 +1,63 @@
+"""Resolve the year of dates that Amazon renders without one (e.g. "1. Okt.").
+
+The year is never guessed from the text. It follows from a reference date that is known to be close, with a rule
+per kind of date:
+
+* a next delivery lies in the future, so it is the first occurrence on or after the reference date (minus a grace
+  period for deliveries that are late or on their way),
+* a change deadline lies before its delivery, so it is the last occurrence on or before the delivery date,
+* a date next to a precise timestamp is the occurrence nearest to that timestamp.
+"""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import date, timedelta
+
+#: A next delivery date may lie up to this many days before the reference date, e.g. while it is on its way.
+NEXT_DELIVERY_GRACE_DAYS = 30
+
+
+@dataclass(frozen=True)
+class DateParts:
+    """A date as rendered, which may lack the year."""
+
+    day: int
+    month: int
+    year: int | None = None
+
+
+def resolve(parts: DateParts | None, resolve_year: Callable[[int, int], date | None]) -> date | None:
+    """The date of the parts, using ``resolve_year(day, month)`` if they have no year."""
+    if parts is None:
+        return None
+    if parts.year is not None:
+        return date(parts.year, parts.month, parts.day)
+    return resolve_year(parts.day, parts.month)
+
+
+def _occurrence(year: int, month: int, day: int) -> date | None:
+    try:
+        return date(year, month, day)
+    except ValueError:  # e.g. 29 February
+        return None
+
+
+def _candidates(day: int, month: int, reference: date) -> list[date]:
+    candidates = (_occurrence(year, month, day) for year in (reference.year - 1, reference.year, reference.year + 1))
+    return [candidate for candidate in candidates if candidate is not None]
+
+
+def first_on_or_after(day: int, month: int, not_before: date) -> date | None:
+    return min((c for c in _candidates(day, month, not_before) if c >= not_before), default=None)
+
+
+def last_on_or_before(day: int, month: int, not_after: date) -> date | None:
+    return max((c for c in _candidates(day, month, not_after) if c <= not_after), default=None)
+
+
+def nearest(day: int, month: int, reference: date) -> date | None:
+    return min(_candidates(day, month, reference), key=lambda c: abs(c - reference), default=None)
+
+
+def next_delivery(day: int, month: int, today: date) -> date | None:
+    return first_on_or_after(day, month, today - timedelta(days=NEXT_DELIVERY_GRACE_DAYS))

amazon_subscriptions/exceptions.py

@@ -0,0 +1,21 @@
+class SubscriptionsError(Exception):
+    """Base class of all errors of amazon-subscriptions."""
+
+
+class SessionExpiredError(SubscriptionsError):
+    """The session is not signed in (anymore)."""
+
+
+class CaptchaError(SubscriptionsError):
+    """Amazon answered with a captcha or robot check instead of the requested page."""
+
+
+class PageStructureError(SubscriptionsError):
+    """A page does not have the expected structure, most likely because Amazon changed it."""
+
+    def __init__(self, message: str, page: str | None = None, selector: str | None = None) -> None:
+        super().__init__(f"{message} (page: {page})" if page else message)
+        self.message = message
+        self.page = page
+        #: CSS selector of the element that was not found, if any.
+        self.selector = selector

amazon_subscriptions/locales/__init__.py

@@ -0,0 +1,68 @@
+from urllib.parse import urlparse
+
+from amazonorders.constants import Constants
+from amazonorders.region_data import REGION_SITES
+
+from amazon_subscriptions.exceptions import SubscriptionsError
+from amazon_subscriptions.locales.base import SubscriptionLocale
+from amazon_subscriptions.locales.en import EnglishSubscriptionLocale
+
+#: ISO 4217 code of the currency of each Amazon site, keyed by the TLD suffix that follows ``amazon.``.
+#:
+#: amazon-orders only knows the symbol a site shows its prices with, and ``$`` alone does not tell US, Canadian and
+#: Australian dollars apart. The pages never show the code.
+SITE_CURRENCIES: dict[str, str] = {
+    "ae": "AED",
+    "ca": "CAD",
+    "co.jp": "JPY",
+    "co.uk": "GBP",
+    "co.za": "ZAR",
+    "com": "USD",
+    "com.au": "AUD",
+    "com.be": "EUR",
+    "com.br": "BRL",
+    "com.mx": "MXN",
+    "com.tr": "TRY",
+    "de": "EUR",
+    "eg": "EGP",
+    "es": "EUR",
+    "fr": "EUR",
+    "ie": "EUR",
+    "in": "INR",
+    "it": "EUR",
+    "nl": "EUR",
+    "pl": "PLN",
+    "sa": "SAR",
+    "se": "SEK",
+    "sg": "SGD",
+}
+
+
+def tld_of(domain_or_url: str) -> str:
+    """The TLD suffix of a storefront, e.g. ``de`` for ``amazon.de`` or ``https://www.amazon.de``."""
+    host = urlparse(domain_or_url).hostname if "://" in domain_or_url else domain_or_url
+    host = (host or "").lower()
+    if "amazon." not in host:
+        raise SubscriptionsError(f"{domain_or_url!r} is not an Amazon storefront.")
+    return host.split("amazon.", 1)[1]
+
+
+def get_locale(domain_or_url: str) -> SubscriptionLocale:
+    """The locale of a storefront, given by domain (``amazon.de``) or base URL (``https://www.amazon.de``).
+
+    Every storefront that offers its pages in English is supported, as amazon-orders requests them in English.
+
+    :raises SubscriptionsError: If the storefront is not known or offers no English pages.
+    """
+    tld = tld_of(domain_or_url)
+    site = REGION_SITES.get(tld)
+    if site is None or tld not in SITE_CURRENCIES:
+        raise SubscriptionsError(f"amazon.{tld} is not a known Amazon storefront.")
+    if not site.english_locale:
+        raise SubscriptionsError(
+            f"amazon.{tld} does not offer its pages in English, which is the only language supported."
+        )
+    return EnglishSubscriptionLocale(SITE_CURRENCIES[tld], Constants.region_currency_symbol(tld))
+
+
+__all__ = ["SITE_CURRENCIES", "EnglishSubscriptionLocale", "SubscriptionLocale", "get_locale", "tld_of"]

amazon_subscriptions/locales/base.py

@@ -0,0 +1,189 @@
+import html
+import logging
+import re
+from datetime import date
+from decimal import Decimal, InvalidOperation
+from typing import ClassVar
+
+from amazon_subscriptions.dates import DateParts
+from amazon_subscriptions.models import Interval, IntervalUnit, ListPriceType, SubscriptionStatus
+
+logger = logging.getLogger(__name__)
+
+
+def normalize_space(text: str) -> str:
+    """Collapse all whitespace, including non-breaking spaces, into single spaces."""
+    return re.sub(r"\s+", " ", text).strip()
+
+
+class SubscriptionLocale:
+    """Texts and formats of the Subscribe & Save pages in one language.
+
+    A language is supported by a subclass that sets the class attributes. The currency is the storefront's, so one
+    subclass serves every storefront that shows its pages in that language, see
+    :func:`amazon_subscriptions.locales.get_locale`.
+
+    :param currency: ISO 4217 code of the storefront's currency.
+    :param currency_symbol: The symbol the storefront shows its prices with. It is removed from amounts, as is the
+        code.
+    """
+
+    #: Month names and abbreviations, lower case.
+    MONTHS: ClassVar[dict[str, int]]
+    #: Patterns of a date, with ``{months}`` for the alternatives of :attr:`MONTHS`. Groups: ``day``, ``month``,
+    #: ``year`` (may be empty).
+    DATE_PATTERNS: ClassVar[list[str]]
+
+    #: Text before the next delivery date of a subscription tile.
+    NEXT_DELIVERY_PREFIX: ClassVar[str]
+    #: Texts of a subscription tile that are neither title, date, quantity nor a status (e.g. links).
+    TILE_ACTION_TEXTS: ClassVar[list[str]]
+    #: Status texts of a subscription tile, matched as prefix. Texts not listed give ``unknown`` and a warning.
+    STATUS_TEXTS: ClassVar[dict[str, SubscriptionStatus]]
+    #: Text shown instead of the subscriptions when there are none. ``None`` if not known yet.
+    NO_SUBSCRIPTIONS_TEXT: ClassVar[str | None] = None
+
+    #: Text before the arrival date of a delivery card.
+    ARRIVAL_PREFIX: ClassVar[str]
+    #: Text before the change deadline of a delivery card.
+    DEADLINE_PREFIX: ClassVar[str]
+
+    #: Quantity and interval, e.g. "3 units every 2 months". Groups: quantity, every (optional), unit.
+    QUANTITY_INTERVAL_RE: ClassVar[re.Pattern[str]]
+    #: Unit words of intervals, lower case.
+    INTERVAL_UNITS: ClassVar[dict[str, IntervalUnit]]
+    #: Discount of an item, e.g. "Save 15%". Group: percent.
+    DISCOUNT_PERCENT_RE: ClassVar[re.Pattern[str]]
+    #: Number of items of a delivery, e.g. "11 items". Group: count.
+    ITEM_COUNT_RE: ClassVar[re.Pattern[str]]
+    #: Total savings of a delivery. Group: amount. ``None`` if not known yet.
+    SAVINGS_RE: ClassVar[re.Pattern[str] | None] = None
+    #: Text stating that the maximum discount of a delivery is unlocked.
+    MAX_DISCOUNT_UNLOCKED_TEXT: ClassVar[str]
+    #: Item alerts stating that a backup product is sent instead of the subscribed one.
+    SUBSTITUTE_ALERT_TEXTS: ClassVar[list[str]]
+
+    #: Unit price of a product page, e.g. "€24.99 per l". Groups: amount, unit.
+    UNIT_PRICE_RE: ClassVar[re.Pattern[str]]
+    #: Labels of the list price of a product page by the type they state, matched as prefix.
+    LIST_PRICE_TYPES: ClassVar[dict[str, ListPriceType]]
+    #: Captions of the buybox rows with other offers of the product, e.g. of other sellers.
+    ALTERNATIVE_OFFERS_CAPTIONS: ClassVar[list[str]]
+    #: Label of the entry of the product itself in a comparison widget, matched as prefix.
+    THIS_ITEM_LABEL: ClassVar[str]
+
+    #: Amount pattern without currency, e.g. "1,234.56". Groups: integer part, decimals (optional).
+    AMOUNT_RE: ClassVar[re.Pattern[str]]
+    #: Thousands separator of :attr:`AMOUNT_RE`.
+    THOUSANDS_SEPARATOR: ClassVar[str]
+
+    def __init__(self, currency: str, currency_symbol: str | None = None) -> None:
+        #: ISO 4217 code of the storefront's currency.
+        self.currency = currency
+        noise = sorted({currency, *([currency_symbol] if currency_symbol else [])}, key=len, reverse=True)
+        #: Texts around an amount that are not part of it: the currency's symbol and code.
+        self.amount_noise_re = re.compile("|".join(map(re.escape, noise)))
+        months = "|".join(sorted(map(re.escape, self.MONTHS), key=len, reverse=True))
+        self._date_res = [
+            re.compile(pattern.replace("{months}", months), re.IGNORECASE) for pattern in self.DATE_PATTERNS
+        ]
+
+    def parse_amount(self, text: str | None) -> Decimal | None:
+        """Parse an amount such as ``€1,234.56``. The text must contain nothing else."""
+        if not text:
+            return None
+        value = normalize_space(self.amount_noise_re.sub("", normalize_space(text))).replace(" ", "")
+        match = self.AMOUNT_RE.fullmatch(value)
+        if not match:
+            logger.warning(f"Amount {text!r} was not recognized, so it was not parsed.")
+            return None
+        integer, decimals = match.group(1), match.group(2) or "0"
+        try:
+            return Decimal(f"{integer.replace(self.THOUSANDS_SEPARATOR, '')}.{decimals}")
+        except InvalidOperation:  # pragma: no cover, the pattern only matches digits
+            return None
+
+    def parse_date_parts(self, text: str | None) -> DateParts | None:
+        """Parse the single date in a text such as ``Arriving: Thu, 1 Oct``, with or without year."""
+        if not text:
+            return None
+        text = normalize_space(text)
+        matches = sorted((m for date_re in self._date_res for m in date_re.finditer(text)), key=lambda m: m.start())
+        found: set[tuple[int, int, int | None]] = set()
+        end = 0
+        for match in matches:
+            # Patterns of both orders may match the same month, e.g. "Oct 12" in "5 Oct 12 units", the first wins
+            if match.start() < end:
+                continue
+            end = match.end()
+            year = int(match["year"]) if match["year"] else None
+            found.add((int(match["day"]), self.MONTHS[match["month"].lower()], year))
+        if len(found) != 1:
+            logger.warning(f"Date {text!r} has {'no' if not found else 'more than one'} date, so it was not parsed.")
+            return None
+        day, month, year = found.pop()
+        try:
+            # 2000 is a leap year, so 29 Feb without year is valid
+            date(year or 2000, month, day)
+        except ValueError:
+            logger.warning(f"Date {text!r} is not a valid date, so it was not parsed.")
+            return None
+        return DateParts(day, month, year)
+
+    def parse_quantity_interval(self, text: str | None, warn: bool = True) -> tuple[int, Interval] | None:
+        """Parse quantity and interval such as ``3 units every 2 months``."""
+        match = self.QUANTITY_INTERVAL_RE.fullmatch(normalize_space(text or ""))
+        if not match:
+            if text and warn:
+                logger.warning(f"Quantity and interval {text!r} were not recognized, so they were not parsed.")
+            return None
+        quantity, every, unit = match.groups()
+        return int(quantity), Interval(int(every or 1), self.INTERVAL_UNITS[unit.lower()])
+
+    def parse_discount_percent(self, text: str | None) -> int | None:
+        match = self.DISCOUNT_PERCENT_RE.search(normalize_space(text or ""))
+        return int(match.group(1)) if match else None
+
+    def parse_item_count(self, text: str | None) -> int | None:
+        match = self.ITEM_COUNT_RE.search(normalize_space(text or ""))
+        return int(match.group(1)) if match else None
+
+    def parse_savings(self, text: str | None) -> Decimal | None:
+        match = self.SAVINGS_RE.search(normalize_space(text or "")) if self.SAVINGS_RE else None
+        return self.parse_amount(match.group(1)) if match else None
+
+    def parse_unit_price(self, text: str | None) -> tuple[Decimal, str] | None:
+        """Parse a unit price such as ``€24.99 per l`` into amount and unit."""
+        match = self.UNIT_PRICE_RE.fullmatch(normalize_space(html.unescape(text or "")))
+        if not match:
+            if text:
+                logger.warning(f"Unit price {text!r} was not recognized, so it was not parsed.")
+            return None
+        amount = self.parse_amount(match.group(1))
+        return (amount, match.group(2)) if amount is not None else None
+
+    def list_price_type_of(self, label: str | None) -> ListPriceType | None:
+        """The type of a list price by its label, ``None`` if the label is not one of a list price."""
+        label = normalize_space(label or "").lower()
+        for prefix, list_price_type in self.LIST_PRICE_TYPES.items():
+            if label.startswith(prefix.lower()):
+                return list_price_type
+        return None
+
+    def is_alternative_offers_caption(self, text: str | None) -> bool:
+        text = normalize_space(text or "").lower()
+        return any(text.startswith(caption.lower()) for caption in self.ALTERNATIVE_OFFERS_CAPTIONS)
+
+    def is_this_item_label(self, text: str | None) -> bool:
+        return normalize_space(text or "").lower().startswith(self.THIS_ITEM_LABEL.lower())
+
+    def status_of(self, text: str) -> SubscriptionStatus:
+        """The status of a subscription tile's status text."""
+        for prefix, status in self.STATUS_TEXTS.items():
+            if normalize_space(text).lower().startswith(prefix.lower()):
+                return status
+        logger.warning(f"Subscription status {text!r} is not known, so it was not parsed.")
+        return SubscriptionStatus.UNKNOWN
+
+    def is_substitute_alert(self, text: str) -> bool:
+        return any(alert.lower() in normalize_space(text).lower() for alert in self.SUBSTITUTE_ALERT_TEXTS)

amazon_subscriptions/locales/en.py

@@ -0,0 +1,65 @@
+import re
+from typing import ClassVar
+
+from amazon_subscriptions.locales.base import SubscriptionLocale
+from amazon_subscriptions.models import IntervalUnit, ListPriceType, SubscriptionStatus
+
+_MONTH_NAMES = [
+    "january", "february", "march", "april", "may", "june",
+    "july", "august", "september", "october", "november", "december",
+]  # fmt: skip
+
+
+class EnglishSubscriptionLocale(SubscriptionLocale):
+    """The Subscribe & Save pages in English, as every storefront that offers English shows them.
+
+    Dates are read in both orders, "1 Oct" and "Oct 1", and amounts as "1,234.56".
+    """
+
+    MONTHS: ClassVar[dict[str, int]] = {
+        **{name: number for number, name in enumerate(_MONTH_NAMES, 1)},
+        **{name[:3]: number for number, name in enumerate(_MONTH_NAMES, 1)},
+        "sept": 9,
+    }
+    DATE_PATTERNS: ClassVar[list[str]] = [
+        # 1 Oct, 1st October 2026, Thu, 1 Oct
+        r"(?<![\d.,])(?P<day>\d{1,2})(?:st|nd|rd|th)?\s+(?P<month>{months})\.?(?![a-z])(?:,?\s+(?P<year>\d{4}))?(?!\d)",
+        # Oct 1, October 1st, 2026, Thu, Oct 1
+        r"(?<![a-z])(?P<month>{months})\.?\s+(?P<day>\d{1,2})(?:st|nd|rd|th)?(?![\d.,]\d)(?:,?\s+(?P<year>\d{4}))?(?!\d)",
+    ]
+
+    NEXT_DELIVERY_PREFIX = "Next delivery:"
+    TILE_ACTION_TEXTS: ClassVar[list[str]] = ["Edit or cancel"]
+    # TODO: capture tiles of paused and unavailable subscriptions to fill this
+    STATUS_TEXTS: ClassVar[dict[str, SubscriptionStatus]] = {}
+    ARRIVAL_PREFIX = "Arriving"
+    DEADLINE_PREFIX = "Last day to edit"
+
+    QUANTITY_INTERVAL_RE = re.compile(
+        r"(\d+) units? every (?:(\d+) )?(day|days|week|weeks|month|months)", re.IGNORECASE
+    )
+    INTERVAL_UNITS: ClassVar[dict[str, IntervalUnit]] = {
+        "day": IntervalUnit.DAY, "days": IntervalUnit.DAY,
+        "week": IntervalUnit.WEEK, "weeks": IntervalUnit.WEEK,
+        "month": IntervalUnit.MONTH, "months": IntervalUnit.MONTH,
+    }  # fmt: skip
+    DISCOUNT_PERCENT_RE = re.compile(r"Saving (\d{1,2}) ?%", re.IGNORECASE)
+    ITEM_COUNT_RE = re.compile(r"(\d+) items?\b")
+    # "Saving €10.58 - Max savings unlocked", not the "Saving 15%" of an item
+    SAVINGS_RE = re.compile(r"\bSaving (?!\d+ ?%)(.+?)(?: - |$)", re.IGNORECASE)
+    MAX_DISCOUNT_UNLOCKED_TEXT = "Max savings unlocked"
+    SUBSTITUTE_ALERT_TEXTS: ClassVar[list[str]] = ["Backup product will be shipped"]
+
+    UNIT_PRICE_RE = re.compile(r"(.+?) per (.+)")
+    # TODO: capture the label of the lowest price of the last 30 days to add it. In October 2026, no product page of
+    # amazon.de showed it, in German either.
+    LIST_PRICE_TYPES: ClassVar[dict[str, ListPriceType]] = {
+        "RRP": ListPriceType.RRP,
+        "Was": ListPriceType.WAS,
+    }
+    # "Get it faster" is a faster delivery of the same offer, not an alternative offer.
+    ALTERNATIVE_OFFERS_CAPTIONS: ClassVar[list[str]] = ["Another way to buy"]
+    THIS_ITEM_LABEL = "This item:"
+
+    AMOUNT_RE = re.compile(r"(-?(?:\d{1,3}(?:,\d{3})+|\d+))(?:\.(\d{1,2}))?")
+    THOUSANDS_SEPARATOR = ","

amazon_subscriptions/models.py

@@ -0,0 +1,163 @@
+import datetime
+from dataclasses import dataclass, field
+from decimal import Decimal
+from enum import Enum
+
+
+class IntervalUnit(str, Enum):
+    DAY = "day"
+    WEEK = "week"
+    MONTH = "month"
+
+
+class SubscriptionStatus(str, Enum):
+    ACTIVE = "active"
+    PAUSED = "paused"
+    #: The subscribed product is not available, e.g. a backup product is sent instead.
+    UNAVAILABLE = "unavailable"
+    SKIPPED = "skipped"
+    UNKNOWN = "unknown"
+
+
+class ListPriceType(str, Enum):
+    """What the list price of a product page is, by its label."""
+
+    #: Recommended retail price, "RRP" on English pages.
+    RRP = "rrp"
+    #: Lowest price of the last 30 days.
+    LOWEST_30D = "lowest_30d"
+    #: A former price, "Was" on English pages.
+    WAS = "was"
+
+
+class ListPriceSource(str, Enum):
+    """The block of a product page the list price was read from."""
+
+    #: The price block of the offer in the buybox.
+    BUYBOX = "buybox"
+    #: The entry of the product itself ("This item:") in a comparison widget. Only recommended retail prices are
+    #: read from there, as the widget may show another offer than the buybox.
+    WIDGET = "widget"
+    #: The price block of an alternative offer of the same product. Only recommended retail prices are read from there.
+    ALTERNATIVE_OFFER = "alternative_offer"
+
+
+@dataclass(frozen=True)
+class ParseError:
+    """A page that could not be loaded or read completely, so the object it belongs to is incomplete."""
+
+    #: URL of the page.
+    url: str | None
+    message: str
+    #: CSS selector of the element that was not found, if known.
+    selector: str | None = None
+    #: Path of the file the page was saved to for diagnosis, ``None`` if no page was received.
+    html_path: str | None = None
+
+
+@dataclass(frozen=True)
+class Interval:
+    every: int
+    unit: IntervalUnit
+
+
+@dataclass(frozen=True)
+class AlternativeOffer:
+    """Another offer of the same product, listed next to the buybox offer ("Another way to buy"), e.g. of another
+    seller."""
+
+    #: Price of a one-time purchase.
+    price: Decimal
+    unit_price: Decimal | None = None
+    unit_price_unit: str | None = None
+    #: Name of the seller as the offer shows it, ``Amazon`` if Amazon sells it, ``None`` if the page does not show it.
+    seller: str | None = None
+    #: Merchant ID of the seller, from the link to its seller profile. ``None`` if Amazon sells it.
+    seller_id: str | None = None
+    #: Alternative offers cannot be subscribed to.
+    subscribable: bool = False
+
+
+@dataclass
+class Subscription:
+    subscription_id: str
+    asin: str | None = None
+    title: str | None = None
+    product_url: str | None = None
+    image_url: str | None = None
+    quantity: int | None = None
+    interval: Interval | None = None
+    next_delivery_date: datetime.date | None = None
+    status: SubscriptionStatus = SubscriptionStatus.UNKNOWN
+    #: Regular (one-time purchase) price of one unit. Only read with ``with_prices``, from the product page.
+    price: Decimal | None = None
+    #: List price of one unit, if the product page shows one for this product. Only read with ``with_prices``.
+    list_price: Decimal | None = None
+    #: What ``list_price`` is, by its label.
+    list_price_type: ListPriceType | None = None
+    #: The block of the product page ``list_price`` was read from.
+    list_price_source: ListPriceSource | None = None
+    #: Subscribe & Save discount of the next delivery in percent.
+    discount_percent: int | None = None
+    #: Price of the next delivery of this subscription, for the whole quantity and with the discount applied.
+    subscription_price: Decimal | None = None
+    #: Price per unit of measure of the regular price, e.g. per ``kg``. Only read with ``with_prices``.
+    unit_price: Decimal | None = None
+    #: The unit of measure of ``unit_price`` as shown by Amazon, e.g. ``kg``, ``100 ml`` or ``count``.
+    unit_price_unit: str | None = None
+    #: The cheapest other offer of the same product on the product page. Only read with ``with_prices``.
+    alternative_offer: AlternativeOffer | None = None
+    #: ISO 4217 code of the amounts.
+    currency: str | None = None
+    #: Status text shown by Amazon, if any.
+    raw_status_text: str | None = None
+    #: Pages of this subscription that could not be read, so some of its fields may be ``None``.
+    parse_errors: list[ParseError] = field(default_factory=list)
+
+
+@dataclass
+class DeliveryItem:
+    title: str
+    quantity: int | None = None
+    interval: Interval | None = None
+    #: Price for the whole quantity, with the discount applied.
+    price: Decimal | None = None
+    discount_percent: int | None = None
+    #: Alert shown for the item, e.g. that a backup product is sent.
+    alert_text: str | None = None
+    #: ``True`` if a backup product is sent instead of the subscribed one.
+    substitute: bool = False
+    #: The subscription of this item. Delivery pages do not link items to subscriptions, so they are matched by
+    #: title (see :func:`amazon_subscriptions.parse.matching.match_deliveries`). ``None`` if no unique match.
+    subscription_id: str | None = None
+    #: ASIN of the subscribed product, also if a backup product is sent instead.
+    asin: str | None = None
+    #: ASIN of the backup product if ``substitute`` is ``True``. ``title``, ``price`` and ``discount_percent`` are then
+    #: the ones of the backup product. ``None`` if it could not be read from the subscription's detail sheet.
+    substitute_asin: str | None = None
+
+
+@dataclass
+class DiscountTier:
+    #: Number of items (products) in the delivery.
+    item_count: int | None = None
+    #: ``True`` if Amazon states that the maximum discount is unlocked for this delivery.
+    max_discount_unlocked: bool | None = None
+    #: Total savings of the delivery as stated by Amazon.
+    savings: Decimal | None = None
+
+
+@dataclass
+class UpcomingDelivery:
+    date: datetime.date
+    change_deadline: datetime.date | None = None
+    items: list[DeliveryItem] = field(default_factory=list)
+    discount_tier: DiscountTier = field(default_factory=DiscountTier)
+    #: Sum of the item prices. ``None`` if any item has no price (yet).
+    total: Decimal | None = None
+    currency: str | None = None
+    delivery_bundle_id: str | None = None
+    #: URL of the delivery page.
+    url: str | None = None
+    #: Pages of this delivery that could not be read, so some of its fields may be ``None`` and items missing.
+    parse_errors: list[ParseError] = field(default_factory=list)

amazon_subscriptions/parse/__init__.py

@@ -0,0 +1,28 @@
+"""Pure functions that turn Subscribe & Save pages into objects. They send no requests."""
+
+from amazon_subscriptions.parse.acp import AcpWidget, parse_acp_widget
+from amazon_subscriptions.parse.deliveries import (
+    parse_deliveries_next_url,
+    parse_delivery_cards,
+    parse_delivery_page,
+)
+from amazon_subscriptions.parse.detail import BackupItem, parse_subscription_detail
+from amazon_subscriptions.parse.matching import match_deliveries, titles_match
+from amazon_subscriptions.parse.product import ProductPrices, parse_product_page
+from amazon_subscriptions.parse.subscriptions import parse_subscriptions, parse_subscriptions_next_url
+
+__all__ = [
+    "AcpWidget",
+    "BackupItem",
+    "ProductPrices",
+    "match_deliveries",
+    "parse_acp_widget",
+    "parse_deliveries_next_url",
+    "parse_delivery_cards",
+    "parse_delivery_page",
+    "parse_product_page",
+    "parse_subscription_detail",
+    "parse_subscriptions",
+    "parse_subscriptions_next_url",
+    "titles_match",
+]

amazon_subscriptions/parse/acp.py

@@ -0,0 +1,41 @@
+"""Parse the widgets of the landing page that load further pages by XHR (Amazon's "ACP" widgets)."""
+
+import json
+from dataclasses import dataclass
+
+from amazon_subscriptions.exceptions import PageStructureError
+from amazon_subscriptions.parse.util import Html, attr_of, soup_of
+
+
+@dataclass(frozen=True)
+class AcpWidget:
+    """What the browser sends to load the next page of a widget, see ``SubscriptionsClient._paginate``."""
+
+    #: Path of the widget, e.g. ``/acp/myd-hub-subscriptions-card-desktop/<id>/``.
+    path: str
+    #: Value of the ``x-amz-acp-params`` header.
+    params: str
+    stamp: str
+    #: Tracking parameters of the widget (``pf_rd_p``, ``pf_rd_r``).
+    tracking: dict[str, str]
+
+
+def parse_acp_widget(html: Html, next_page_selector: str, page: str | None = None) -> AcpWidget | None:
+    """The widget around the next page marker ``next_page_selector``, or ``None`` if there is no next page.
+
+    :raises PageStructureError: If the marker is not inside a widget with the expected attributes.
+    """
+    marker = soup_of(html).select_one(next_page_selector)
+    if marker is None:
+        return None
+    widget = marker.find_parent(attrs={"data-acp-path": True})
+    path = attr_of(widget, "data-acp-path")
+    params = attr_of(widget, "data-acp-params")
+    stamp = attr_of(widget, "data-acp-stamp")
+    try:
+        tracking = json.loads(attr_of(widget, "data-acp-tracking") or "{}")
+    except ValueError:
+        tracking = None
+    if not (path and params and stamp and isinstance(tracking, dict)):
+        raise PageStructureError(f"Next page {next_page_selector!r} is not inside a widget", page)
+    return AcpWidget(path, params, stamp, {k: v for k, v in tracking.items() if k in ("pf_rd_p", "pf_rd_r")})