mt-940 5.0.0__py3-none-any.whl

mt940/__about__.py

@@ -0,0 +1,24 @@
+from importlib.metadata import (
+    PackageNotFoundError,
+    version as _version,
+)
+
+__title__ = 'MT940'
+__package_name__ = 'mt-940'
+__author__ = 'Rick van Hattem (wolph)'
+__description__ = (
+    'A library to parse MT940 files and returns smart Python collections for '
+    'statistics and manipulation.'
+)
+__email__ = 'wolph@wol.ph'
+__license__ = 'BSD'
+__copyright__ = 'Copyright 2015 Rick van Hattem (wolph)'
+__url__ = 'https://github.com/WoLpH/mt940'
+
+# The version is single-sourced from the installed package metadata
+# (pyproject.toml).
+__version__: str
+try:
+    __version__ = _version('mt-940')
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = '0.0.0'

mt940/__init__.py

@@ -0,0 +1,43 @@
+"""mt940 — parse MT940 bank statement files into rich Python objects.
+
+The high-level entry point is :func:`parse`, which accepts a filename, a file
+handle, or raw ``str``/``bytes`` and returns a
+:class:`~mt940.models.Transactions` collection you can iterate over. Use
+:func:`parse_statements` for files that concatenate several statements, and
+:class:`JSONEncoder` to serialize the result to JSON.
+
+Example:
+    >>> import mt940
+    >>> data = (
+    ...     ':20:REF\\n'
+    ...     ':25:NL00BANK0123456789\\n'
+    ...     ':28C:1/1\\n'
+    ...     ':60F:C091019EUR1000,00\\n'
+    ...     ':61:0910201020C500,00NTRFNONREF//B\\n'
+    ...     ':86:Example transaction\\n'
+    ...     ':62F:C091020EUR1500,00\\n'
+    ... )
+    >>> transactions = mt940.parse(data)
+    >>> len(transactions)
+    1
+    >>> transactions[0].data['amount']
+    <500.00 EUR>
+"""
+
+from . import json, models, parser, processors, tags, utils
+from .__about__ import __version__
+from .json import JSONEncoder
+from .parser import parse, parse_statements
+
+__all__ = [
+    'JSONEncoder',
+    '__version__',
+    'json',
+    'models',
+    'parse',
+    'parse_statements',
+    'parser',
+    'processors',
+    'tags',
+    'utils',
+]

mt940/_types.py

@@ -0,0 +1,57 @@
+"""Shared type aliases and processor protocols.
+
+These are the precise types used across the public API. The module is a *leaf*:
+it imports nothing from the rest of the package, so it never participates in an
+import cycle. The processor protocols therefore type their ``transactions`` and
+``tag`` arguments as :data:`~typing.Any`; the concrete processor functions in
+:mod:`mt940.processors` still annotate them precisely.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Callable
+from typing import IO, Any, Protocol
+
+#: Accepted input for :func:`mt940.parse` and :func:`mt940.parse_statements`:
+#: a path, raw ``str``/``bytes`` data, or an open binary/text file handle.
+Source = str | bytes | os.PathLike[str] | IO[str] | IO[bytes]
+
+#: A parsed tag dictionary. Intentionally dynamic: the available keys are
+#: tag- and bank-specific, so a precise ``TypedDict`` would misrepresent it.
+TagDict = dict[str, Any]
+
+
+class PreProcessor(Protocol):
+    """A callable run *before* a tag value is turned into a model object."""
+
+    def __call__(
+        self,
+        transactions: Any,
+        tag: Any,
+        tag_dict: TagDict,
+        /,
+        *args: Any,
+    ) -> TagDict: ...
+
+
+class PostProcessor(Protocol):
+    """A callable run *after* a tag value is turned into a model object."""
+
+    def __call__(
+        self,
+        transactions: Any,
+        tag: Any,
+        tag_dict: TagDict,
+        result: TagDict,
+        /,
+    ) -> TagDict: ...
+
+
+#: A pre- or post-processor as stored in :attr:`Transactions.processors`.
+#: The container mixes both kinds keyed by ``pre_*``/``post_*``, so the element
+#: type stays callable-flexible while pinning the return type.
+Processor = Callable[..., TagDict]
+
+#: Mapping of processor-slot name to the processors registered for it.
+Processors = dict[str, list[Processor]]

mt940/json.py

@@ -0,0 +1,78 @@
+"""JSON serialization for MT940 models.
+
+This module exposes :class:`JSONEncoder`, a :class:`json.JSONEncoder` subclass
+that knows how to serialize the model types returned by the parser (balances,
+amounts, dates and the transaction collections).
+
+Example:
+    >>> import json
+    >>> import mt940
+    >>> transactions = mt940.models.Transactions()
+    >>> json.dumps(transactions, cls=mt940.JSONEncoder)
+    '{"transactions": []}'
+"""
+
+from __future__ import annotations
+
+import datetime
+import decimal
+import json
+from typing import Any
+
+from . import models
+
+
+class JSONEncoder(json.JSONEncoder):
+    """Serialize MT940 model objects to JSON-compatible primitives.
+
+    Dates, datetimes, timedeltas, timezones and decimals are rendered as
+    strings; :class:`~mt940.models.Transactions`,
+    :class:`~mt940.models.Transaction`, :class:`~mt940.models.Balance` and
+    :class:`~mt940.models.Amount` are rendered as their ``data``/``__dict__``
+    mappings. Pass it as the ``cls`` argument to :func:`json.dumps`.
+    """
+
+    def default(self, o: Any) -> Any:
+        """Return a JSON-serializable representation of ``o``.
+
+        Args:
+            o: The object to serialize. ``o`` keeps the permissive ``Any`` type
+                of the overridden :meth:`json.JSONEncoder.default`.
+
+        Returns:
+            The serialized form of the object.
+        """
+        # The following types should simply be cast to strings
+        str_types = (
+            datetime.date,
+            datetime.datetime,
+            datetime.timedelta,
+            datetime.tzinfo,
+            decimal.Decimal,
+        )
+
+        dict_types = (models.Balance, models.Amount)
+
+        # Handle native types that should be converted to strings
+        if isinstance(o, str_types):
+            return str(o)
+
+        # Handling of the Transaction objects to include the
+        # actual transactions
+        elif isinstance(o, models.Transactions):
+            data: dict[str, Any] = o.data.copy()
+            data['transactions'] = o.transactions
+            return data
+
+        # If an object has a `data` attribute, return that instead of the
+        # `__dict__` to prevent loops
+        elif hasattr(o, 'data'):
+            return o.data
+
+        # Handle types that have a `__dict__` containing the data (doesn't work
+        # for classes using `__slots__` such as `datetime`)
+        elif isinstance(o, dict_types):
+            return o.__dict__
+
+        else:  # pragma: no cover
+            return super().default(o)