ebicsclient 0.1.1__tar.gz → 0.2.0__tar.gz

{ebicsclient-0.1.1 → ebicsclient-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ebicsclient
-Version: 0.1.1
+Version: 0.2.0
 Summary: Pure-Python client for the EBICS 3.0 (H005) banking protocol
 Project-URL: Homepage, https://github.com/schulluk/ebicsclient
 Project-URL: Repository, https://github.com/schulluk/ebicsclient
@@ -232,11 +232,11 @@ a real bank statement.
 - [x] Golden regression fixture from a real ZKB statement
 - [x] CI (ruff / mypy --strict / pytest) and tag-triggered PyPI releases (Trusted Publishing)
 
-**Milestone 5 — Message formats** (next)
+**Milestone 5 — Message formats** (parsers built against genuine ZKB messages)
 
-- [ ] pain.002 status-report parser (accepted / rejected transactions)
-- [ ] camt.052 intraday statements
-- [ ] camt.054 booking advices (QRR / SCOR / LSV)
+- [x] pain.002 status-report parser (group / payment / transaction statuses, reason codes)
+- [x] camt.052 intraday reports
+- [x] camt.054 booking advices (incl. the QRR / SCOR / LSV variants via `service_option`)
 
 **Milestone 6 — Protocol conveniences & breadth**
 

{ebicsclient-0.1.1 → ebicsclient-0.2.0}/README.md

@@ -114,11 +114,11 @@ a real bank statement.
 - [x] Golden regression fixture from a real ZKB statement
 - [x] CI (ruff / mypy --strict / pytest) and tag-triggered PyPI releases (Trusted Publishing)
 
-**Milestone 5 — Message formats** (next)
+**Milestone 5 — Message formats** (parsers built against genuine ZKB messages)
 
-- [ ] pain.002 status-report parser (accepted / rejected transactions)
-- [ ] camt.052 intraday statements
-- [ ] camt.054 booking advices (QRR / SCOR / LSV)
+- [x] pain.002 status-report parser (group / payment / transaction statuses, reason codes)
+- [x] camt.052 intraday reports
+- [x] camt.054 booking advices (incl. the QRR / SCOR / LSV variants via `service_option`)
 
 **Milestone 6 — Protocol conveniences & breadth**
 

{ebicsclient-0.1.1 → ebicsclient-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ebicsclient"
-version = "0.1.1"
+version = "0.2.0"
 description = "Pure-Python client for the EBICS 3.0 (H005) banking protocol"
 readme = "README.md"
 requires-python = ">=3.11"

{ebicsclient-0.1.1 → ebicsclient-0.2.0}/src/ebicsclient/__init__.py

@@ -33,6 +33,7 @@ from ebicsclient.errors import (
     Retryability,
     ReturnCodeError,
     TransportError,
+    UnknownReturnCodeError,
 )
 from ebicsclient.keys import (
     CertificateUsage,
@@ -46,7 +47,9 @@ from ebicsclient.keys import (
     serialize_keyring,
 )
 from ebicsclient.models import (
+    CAMT_052,
     CAMT_053,
+    CAMT_054,
     PAIN_001,
     PAIN_002,
     Balance,
@@ -59,8 +62,13 @@ from ebicsclient.models import (
     InitializationState,
     Keyring,
     Letter,
+    Notification,
     OutputFormat,
+    PaymentStatus,
+    PaymentStatusReport,
     Statement,
+    StatusReason,
+    TransactionStatus,
     UploadPayload,
     User,
 )
@@ -76,7 +84,9 @@ except PackageNotFoundError:  # running from a source tree without an install
     __version__ = "0.0.0"
 
 __all__ = [
+    "CAMT_052",
     "CAMT_053",
+    "CAMT_054",
     "PAIN_001",
     "PAIN_002",
     "Balance",
@@ -105,14 +115,20 @@ __all__ = [
     "MappingCertificateProvider",
     "MessageFormatError",
     "MissingDependencyError",
+    "Notification",
     "OutputFormat",
+    "PaymentStatus",
+    "PaymentStatusReport",
     "ProtocolError",
     "Retryability",
     "ReturnCodeError",
     "SelfSignedCertificateProvider",
     "Statement",
+    "StatusReason",
+    "TransactionStatus",
     "TransportError",
     "TrustAnchorVerifier",
+    "UnknownReturnCodeError",
     "UploadPayload",
     "User",
     "__version__",

{ebicsclient-0.1.1 → ebicsclient-0.2.0}/src/ebicsclient/client.py

@@ -15,9 +15,12 @@ from ebicsclient.certificates import (
     CertificateProvider,
 )
 from ebicsclient.errors import BankKeyMismatchError, ClientStateError, ReturnCodeError
-from ebicsclient.formats import camt053
+from ebicsclient.formats import camt052, camt053, camt054, pain002
 from ebicsclient.models import (
+    CAMT_052,
     CAMT_053,
+    CAMT_054,
+    PAIN_002,
     Bank,
     BankKeyHashes,
     BankKeys,
@@ -25,7 +28,9 @@ from ebicsclient.models import (
     InitializationState,
     Keyring,
     Letter,
+    Notification,
     OutputFormat,
+    PaymentStatusReport,
     Statement,
     User,
 )
@@ -296,6 +301,74 @@ class Client:
         """
         return camt053.parse(self.download(CAMT_053))
 
+    def download_intraday_statements(self) -> list[Statement]:
+        """Download the intraday camt.052 account reports and parse them.
+
+        A convenience over :meth:`download` for ``STM/camt.052``. Intraday reports share
+        the statement shape; interim balances (if any) are in ``balances`` rather than
+        ``opening_balance``/``closing_balance``. The bank's keys must already be available
+        (call :meth:`hpb` first).
+
+        Returns:
+            The intraday reports the bank delivered, in document order.
+
+        Raises:
+            ClientStateError: the bank's keys have not been fetched yet (run HPB first).
+            TransportError: a request could not be delivered.
+            ProtocolError: a response could not be parsed.
+            ReturnCodeError: the bank reported a non-OK return code (e.g. no data available).
+            CryptoError: the order data could not be decrypted.
+            MessageFormatError: the downloaded camt.052 data could not be parsed.
+        """
+        return camt052.parse(self.download(CAMT_052))
+
+    def download_booking_advices(
+        self, btf: BusinessTransactionFormat = CAMT_054
+    ) -> list[Notification]:
+        """Download camt.054 debit/credit notifications (booking advices) and parse them.
+
+        A convenience over :meth:`download` for ``REP/camt.054``. Pass a variant BTF (the
+        same tuple with a ``service_option`` such as ``"XQRR"``/``"XSCR"``) for the Swiss
+        collective-resolution advices. The bank's keys must already be available (call
+        :meth:`hpb` first).
+
+        Args:
+            btf: The camt.054 Business Transaction Format; defaults to the plain ``CAMT_054``.
+
+        Returns:
+            The notifications the bank delivered, in document order.
+
+        Raises:
+            ClientStateError: the bank's keys have not been fetched yet (run HPB first).
+            TransportError: a request could not be delivered.
+            ProtocolError: a response could not be parsed.
+            ReturnCodeError: the bank reported a non-OK return code (e.g. no data available).
+            CryptoError: the order data could not be decrypted.
+            MessageFormatError: the downloaded camt.054 data could not be parsed.
+        """
+        return camt054.parse(self.download(btf))
+
+    def download_payment_status_reports(self) -> list[PaymentStatusReport]:
+        """Download the pain.002 payment status reports and parse them.
+
+        A convenience over :meth:`download` for the common case: it fetches
+        ``PSR/pain.002`` and returns the parsed reports — the bank's verdicts on
+        previously uploaded pain.001 files, including per-transaction rejections.
+        The bank's keys must already be available (call :meth:`hpb` first).
+
+        Returns:
+            The payment status reports the bank delivered, in document order.
+
+        Raises:
+            ClientStateError: the bank's keys have not been fetched yet (run HPB first).
+            TransportError: a request could not be delivered.
+            ProtocolError: a response could not be parsed.
+            ReturnCodeError: the bank reported a non-OK return code (e.g. no data available).
+            CryptoError: the order data could not be decrypted.
+            MessageFormatError: the downloaded pain.002 data could not be parsed.
+        """
+        return pain002.parse(self.download(PAIN_002))
+
     def upload(self, btf: BusinessTransactionFormat, order_data: bytes) -> str:
         """Upload order data for a Business Transaction Format and return the transaction ID.
 

{ebicsclient-0.1.1 → ebicsclient-0.2.0}/src/ebicsclient/errors.py

@@ -161,3 +161,26 @@ class ReturnCodeError(ProtocolError):
         self.code = code
         self.text = text
         super().__init__(code if text is None else f"{code}: {text}", retryability=retryability)
+
+
+class UnknownReturnCodeError(ReturnCodeError):
+    """The bank returned an EBICS code this client does not recognise.
+
+    Deliberately distinct from a *known* failure: the code is outside the client's
+    knowledge, so its meaning is unverified — it could be a bank-specific extension, a
+    spec code not yet in the client's table, or even a success variant (as ``011000``
+    once was). It is treated as a failure (fail closed, never fail open), but callers and
+    logs can tell it apart and verify the code against the EBICS specification and the
+    bank's documentation instead of trusting a masked classification.
+    """
+
+    def __init__(self, code: str, text: str | None = None) -> None:
+        self.code = code
+        self.text = text
+        detail = f" ({text})" if text is not None else ""
+        # Bypass ReturnCodeError.__init__ so the message carries the unknown-code framing.
+        ProtocolError.__init__(
+            self,
+            f"Unknown EBICS return code {code}{detail} — failing closed; verify the code "
+            f"against the EBICS specification and the bank's documentation",
+        )

ebicsclient-0.2.0/src/ebicsclient/formats/camt.py

@@ -0,0 +1,216 @@
+"""Shared parsing core for the ISO 20022 camt account-reporting family.
+
+camt.053 statements (``BkToCstmrStmt/Stmt``), camt.052 intraday reports
+(``BkToCstmrAcctRpt/Rpt``), and camt.054 debit/credit notifications
+(``BkToCstmrDbtCdtNtfctn/Ntfctn``) all share one core shape: an identification, an
+account, and booking entries — statements and reports additionally carry balances. This
+module holds that shared machinery; the thin per-type modules
+(:mod:`~ebicsclient.formats.camt053`, :mod:`~ebicsclient.formats.camt052`,
+:mod:`~ebicsclient.formats.camt054`) only name their wrapper elements and models.
+
+Element names are read namespace-agnostically: each document's camt namespace is adopted
+from its root, so a different message version still parses without a code change.
+"""
+
+import datetime
+from decimal import Decimal, InvalidOperation
+
+from lxml import etree
+
+from ebicsclient.errors import MessageFormatError
+from ebicsclient.models import Balance, CreditDebit, Entry, Statement
+
+_DOCUMENT = "Document"
+# Closing/opening booked balances are selected by their ISO external balance-type code.
+_CLOSING_BOOKED = "CLBD"
+_OPENING_BOOKED = "OPBD"
+
+
+def document_items(
+    document: bytes, message: str, wrapper: str, item: str
+) -> list[tuple[etree._Element, str]]:
+    """Extract the per-account item elements from one camt XML document.
+
+    Args:
+        document: The raw XML document bytes.
+        message: The message name for error reporting (e.g. ``"camt.053"``).
+        wrapper: The wrapper element under ``Document`` (e.g. ``"BkToCstmrStmt"``).
+        item: The repeated item element (e.g. ``"Stmt"``, ``"Rpt"``, ``"Ntfctn"``).
+
+    Returns:
+        The item elements paired with the document's namespace, in document order.
+
+    Raises:
+        MessageFormatError: the document is malformed or not the expected shape.
+    """
+    root = _parse_xml(document, message)
+    local_name = etree.QName(root).localname
+    if local_name != _DOCUMENT:
+        raise MessageFormatError(f"Expected a {message} <Document>, got <{local_name}>")
+    namespace = etree.QName(root).namespace
+    if namespace is None:
+        raise MessageFormatError(f"{message} <Document> declares no namespace")
+    report = child(root, namespace, wrapper)
+    return [(element, namespace) for element in children(report, namespace, item)]
+
+
+def parse_statement(statement: etree._Element, namespace: str) -> Statement:
+    """Parse one ``Stmt``/``Rpt`` element into a :class:`~ebicsclient.models.Statement`."""
+    balances = tuple(
+        parse_balance(balance, namespace) for balance in children(statement, namespace, "Bal")
+    )
+    return Statement(
+        identification=identification(statement, namespace),
+        iban=iban(statement, namespace),
+        opening_balance=balance_with_code(balances, _OPENING_BOOKED),
+        closing_balance=balance_with_code(balances, _CLOSING_BOOKED),
+        balances=balances,
+        entries=parse_entries(statement, namespace),
+    )
+
+
+def identification(item: etree._Element, namespace: str) -> str:
+    """Read the item's ``Id``."""
+    return text(child(item, namespace, "Id"))
+
+
+def iban(item: etree._Element, namespace: str) -> str | None:
+    """Read the account IBAN (``Acct/Id/IBAN``), or ``None`` if another id is used."""
+    account = optional_child(item, namespace, "Acct")
+    if account is None:
+        return None
+    account_id = optional_child(account, namespace, "Id")
+    if account_id is None:
+        return None
+    element = optional_child(account_id, namespace, "IBAN")
+    return text(element) if element is not None else None
+
+
+def parse_entries(item: etree._Element, namespace: str) -> tuple[Entry, ...]:
+    """Parse every booking entry (``Ntry``) of one item, in document order."""
+    return tuple(_parse_entry(entry, namespace) for entry in children(item, namespace, "Ntry"))
+
+
+def parse_balance(balance: etree._Element, namespace: str) -> Balance:
+    """Parse one ``Bal`` element."""
+    amount, currency = _amount(balance, namespace)
+    return Balance(
+        code=text(
+            child(child(child(balance, namespace, "Tp"), namespace, "CdOrPrtry"), namespace, "Cd")
+        ),
+        amount=amount,
+        currency=currency,
+        credit_debit=_credit_debit(balance, namespace),
+        date=_date(child(balance, namespace, "Dt"), namespace),
+    )
+
+
+def balance_with_code(balances: tuple[Balance, ...], code: str) -> Balance | None:
+    """Return the first balance carrying the given ISO balance-type code, if any."""
+    return next((balance for balance in balances if balance.code == code), None)
+
+
+def _parse_entry(entry: etree._Element, namespace: str) -> Entry:
+    amount, currency = _amount(entry, namespace)
+    reference = optional_child(entry, namespace, "AcctSvcrRef")
+    return Entry(
+        amount=amount,
+        currency=currency,
+        credit_debit=_credit_debit(entry, namespace),
+        status=_status(entry, namespace),
+        booking_date=_optional_date(entry, namespace, "BookgDt"),
+        value_date=_optional_date(entry, namespace, "ValDt"),
+        reference=text(reference) if reference is not None else None,
+    )
+
+
+def _status(entry: etree._Element, namespace: str) -> str:
+    # The 2019 vintages wrap the status in <Sts><Cd>…</Cd></Sts>; older ones put the
+    # code straight in <Sts>. Accept either.
+    status = child(entry, namespace, "Sts")
+    code = optional_child(status, namespace, "Cd")
+    return text(code) if code is not None else text(status)
+
+
+def _amount(parent: etree._Element, namespace: str) -> tuple[Decimal, str]:
+    element = child(parent, namespace, "Amt")
+    currency = element.get("Ccy")
+    if currency is None:
+        raise MessageFormatError("A camt <Amt> is missing its Ccy attribute")
+    value = element.text
+    if value is None:
+        raise MessageFormatError("A camt <Amt> is empty")
+    try:
+        return Decimal(value), currency
+    except InvalidOperation as error:
+        raise MessageFormatError(f"A camt <Amt> is not a decimal: {value!r}") from error
+
+
+def _credit_debit(parent: etree._Element, namespace: str) -> CreditDebit:
+    value = text(child(parent, namespace, "CdtDbtInd"))
+    try:
+        return CreditDebit(value)
+    except ValueError as error:
+        raise MessageFormatError(f"A camt <CdtDbtInd> is not CRDT/DBIT: {value!r}") from error
+
+
+def _optional_date(
+    parent: etree._Element, namespace: str, local_name: str
+) -> datetime.date | None:
+    element = optional_child(parent, namespace, local_name)
+    return _date(element, namespace) if element is not None else None
+
+
+def _date(parent: etree._Element, namespace: str) -> datetime.date:
+    # A camt date choice is <Dt> (a date) or <DtTm> (a date-time); take the date part.
+    date = optional_child(parent, namespace, "Dt")
+    if date is not None:
+        return _parse_iso_date(text(date))
+    date_time = optional_child(parent, namespace, "DtTm")
+    if date_time is not None:
+        return _parse_iso_date(text(date_time)[:10])
+    raise MessageFormatError("A camt date is missing both <Dt> and <DtTm>")
+
+
+def _parse_iso_date(value: str) -> datetime.date:
+    try:
+        return datetime.date.fromisoformat(value)
+    except ValueError as error:
+        raise MessageFormatError(f"A camt date is not an ISO date: {value!r}") from error
+
+
+def child(parent: etree._Element, namespace: str, local_name: str) -> etree._Element:
+    """Return the required direct child, raising :class:`MessageFormatError` if absent."""
+    element = optional_child(parent, namespace, local_name)
+    if element is None:
+        raise MessageFormatError(f"A camt element is missing <{local_name}>")
+    return element
+
+
+def optional_child(
+    parent: etree._Element, namespace: str, local_name: str
+) -> etree._Element | None:
+    """Return the direct child, or ``None`` if absent."""
+    return parent.find(f"{{{namespace}}}{local_name}")
+
+
+def children(parent: etree._Element, namespace: str, local_name: str) -> list[etree._Element]:
+    """Return every direct child with the given name, in document order."""
+    return parent.findall(f"{{{namespace}}}{local_name}")
+
+
+def text(element: etree._Element) -> str:
+    """Return the element's stripped text, raising if it is empty."""
+    value = element.text
+    if value is None:
+        raise MessageFormatError(f"A camt <{etree.QName(element).localname}> is empty")
+    return value.strip()
+
+
+def _parse_xml(data: bytes, message: str) -> etree._Element:
+    # Hardened parser: no entity expansion, no network access (see docs/06).
+    parser = etree.XMLParser(resolve_entities=False, no_network=True, huge_tree=False)
+    try:
+        return etree.fromstring(data, parser=parser)
+    except etree.XMLSyntaxError as error:
+        raise MessageFormatError(f"Malformed {message} XML: {error}") from error

ebicsclient-0.2.0/src/ebicsclient/formats/camt052.py

@@ -0,0 +1,39 @@
+"""Parser for ISO 20022 camt.052 intraday account reports.
+
+A ``STM/camt.052`` download yields either a single camt.052 XML document or a ZIP
+container holding several. An intraday report has the same shape as a camt.053
+statement — identification, account, optional balances (interim rather than closing
+codes), and booking entries — so :func:`parse` returns the same
+:class:`~ebicsclient.models.Statement` model; ``opening_balance``/``closing_balance``
+are usually ``None`` for intraday reports, with any interim balances in ``balances``.
+
+The parsing core is shared with the other camt types in :mod:`ebicsclient.formats.camt`.
+"""
+
+from ebicsclient.formats import camt
+from ebicsclient.formats.container import extract_documents
+from ebicsclient.models import Statement
+
+_MESSAGE = "camt.052"
+
+
+def parse(order_data: bytes) -> list[Statement]:
+    """Parse camt.052 order data into intraday account reports.
+
+    Args:
+        order_data: The raw order-data bytes a download returned — a single camt.052 XML
+            document or a ZIP container of them.
+
+    Returns:
+        Every report found, in document order (and, for a ZIP, in entry-name order).
+
+    Raises:
+        MessageFormatError: the data is not a readable camt.052 document or container.
+    """
+    return [
+        camt.parse_statement(element, namespace)
+        for document in extract_documents(order_data)
+        for element, namespace in camt.document_items(
+            document, _MESSAGE, "BkToCstmrAcctRpt", "Rpt"
+        )
+    ]

ebicsclient-0.2.0/src/ebicsclient/formats/camt053.py

@@ -0,0 +1,36 @@
+"""Parser for ISO 20022 camt.053 account statements.
+
+A ``EOP/camt.053`` download yields either a single camt.053 XML document or a ZIP
+container holding several (one per statement period). :func:`parse` accepts the raw
+order-data bytes from :meth:`ebicsclient.client.Client.download` in either form and
+returns the statements as normalised :class:`~ebicsclient.models.Statement` models —
+account, opening and closing booked balances, and booking entries.
+
+The parsing core is shared with the other camt types in :mod:`ebicsclient.formats.camt`.
+"""
+
+from ebicsclient.formats import camt
+from ebicsclient.formats.container import extract_documents
+from ebicsclient.models import Statement
+
+_MESSAGE = "camt.053"
+
+
+def parse(order_data: bytes) -> list[Statement]:
+    """Parse camt.053 order data into account statements.
+
+    Args:
+        order_data: The raw order-data bytes a download returned — a single camt.053 XML
+            document or a ZIP container of them.
+
+    Returns:
+        Every statement found, in document order (and, for a ZIP, in entry-name order).
+
+    Raises:
+        MessageFormatError: the data is not a readable camt.053 document or container.
+    """
+    return [
+        camt.parse_statement(element, namespace)
+        for document in extract_documents(order_data)
+        for element, namespace in camt.document_items(document, _MESSAGE, "BkToCstmrStmt", "Stmt")
+    ]

ebicsclient-0.2.0/src/ebicsclient/formats/camt054.py

@@ -0,0 +1,42 @@
+"""Parser for ISO 20022 camt.054 debit/credit notifications (booking advices).
+
+A ``REP/camt.054`` download yields either a single camt.054 XML document or a ZIP
+container holding several — Swiss banks deliver one notification per booking advice
+(credits, debits, and the QRR/SCOR/LSV collective resolutions as separate documents).
+:func:`parse` returns them as :class:`~ebicsclient.models.Notification` models —
+identification, account, and booking entries; notifications carry no balances.
+
+The parsing core is shared with the other camt types in :mod:`ebicsclient.formats.camt`.
+"""
+
+from ebicsclient.formats import camt
+from ebicsclient.formats.container import extract_documents
+from ebicsclient.models import Notification
+
+_MESSAGE = "camt.054"
+
+
+def parse(order_data: bytes) -> list[Notification]:
+    """Parse camt.054 order data into debit/credit notifications.
+
+    Args:
+        order_data: The raw order-data bytes a download returned — a single camt.054 XML
+            document or a ZIP container of them.
+
+    Returns:
+        Every notification found, in document order (and, for a ZIP, in entry-name order).
+
+    Raises:
+        MessageFormatError: the data is not a readable camt.054 document or container.
+    """
+    return [
+        Notification(
+            identification=camt.identification(element, namespace),
+            iban=camt.iban(element, namespace),
+            entries=camt.parse_entries(element, namespace),
+        )
+        for document in extract_documents(order_data)
+        for element, namespace in camt.document_items(
+            document, _MESSAGE, "BkToCstmrDbtCdtNtfctn", "Ntfctn"
+        )
+    ]

ebicsclient-0.2.0/src/ebicsclient/formats/container.py

@@ -0,0 +1,36 @@
+"""Container handling shared by the message-format parsers.
+
+EBICS download order data arrives either as a single XML document or as a ZIP container
+holding several (one per message). Every format parser accepts both, so the splitting
+logic lives here once.
+"""
+
+import io
+import zipfile
+
+from ebicsclient.errors import MessageFormatError
+
+_ZIP_MAGIC = b"PK\x03\x04"
+
+
+def extract_documents(order_data: bytes) -> list[bytes]:
+    """Split raw order data into its individual XML documents.
+
+    Args:
+        order_data: The raw order-data bytes a download returned — a single XML document
+            or a ZIP container of them.
+
+    Returns:
+        The contained documents; for a ZIP, in entry-name order (stable and reproducible),
+        otherwise the input as a single-element list.
+
+    Raises:
+        MessageFormatError: the data looks like a ZIP but cannot be read.
+    """
+    if not order_data.startswith(_ZIP_MAGIC):
+        return [order_data]
+    try:
+        with zipfile.ZipFile(io.BytesIO(order_data)) as archive:
+            return [archive.read(name) for name in sorted(archive.namelist())]
+    except (zipfile.BadZipFile, OSError) as error:
+        raise MessageFormatError("Order data is not a readable ZIP container") from error