Add type stubs for example import configuration

Author: mlell

stubs/beangulp/__init__.pyi

@@ -1,6 +1,7 @@
 import datetime
 from abc import ABC
 from abc import abstractmethod
+from collections.abc import Callable
 from collections.abc import Sequence
 
 from fava.beans.abc import Account
@@ -24,3 +25,23 @@ class Importer(ABC):
     def sort(
         self, entries: list[Directive], reverse: bool = False
     ) -> None: ...
+
+class Ingest:
+    def __init__(
+        self,
+        importer: Sequence[Importer],
+        hooks: Sequence[
+            Callable[
+                [
+                    Sequence[
+                        tuple[str, Sequence[Directive], str, Importer]
+                    ],  # new_entries
+                    Sequence[Directive],  # existing_entries
+                ],
+                Sequence[
+                    tuple[str, Sequence[Directive], str, Importer]
+                ],  # (return value)
+            ]
+        ],
+    ) -> None: ...
+    def __call__(self) -> None: ...

stubs/beangulp/importers/__init__.pyi

@@ -0,0 +1 @@
+# This file is intentionally left empty to make the directory a package

stubs/beangulp/importers/csvbase.pyi

@@ -0,0 +1,75 @@
+import csv
+import datetime
+import enum
+from collections.abc import Sequence
+from typing import Any
+from typing import NamedTuple
+from typing import TypeAlias
+
+import beancount.core.amount
+import beangulp
+from beancount.core import data
+
+from fava.beans.abc import Directive
+
+Row: TypeAlias = NamedTuple
+
+class Order(enum.Enum):
+    ASCENDING = ...
+    DESCENDING = ...
+
+class Column:
+    name: str
+    def __init__(self, name: str) -> None: ...
+    def parse(self, value: str) -> Any: ...
+
+class Date(Column):
+    format: str
+    def __init__(self, name: str, frmt: str) -> None: ...
+    def parse(self, value: str) -> datetime.date: ...
+
+class Amount(Column):
+    subs: dict[str, str]
+    def __init__(
+        self, name: str, subs: dict[str, str] | None = None
+    ) -> None: ...
+    def parse(self, value: str) -> beancount.core.amount.Amount: ...
+
+class Columns(Column):
+    columns: list[str]
+    sep: str
+    def __init__(self, *columns: str, sep: str = " ") -> None: ...
+    def parse(self, value: str) -> str: ...
+
+class CreditOrDebit(Column):
+    credit_name: str
+    debit_name: str
+    def __init__(self, credit_name: str, debit_name: str) -> None: ...
+    def parse(self, value: str) -> beancount.core.amount.Amount: ...
+
+class CSVMeta(type): ...
+
+class CSVReader:
+    encoding: str
+    skiplines: int
+    names: bool
+    dialect: str | csv.Dialect
+    comments: str
+    order: Order | None
+
+    def read(self, filepath: str) -> list[Row]: ...
+
+class Importer(beangulp.Importer, CSVReader):
+    def __init__(
+        self, account: str, currency: str, flag: str = "*"
+    ) -> None: ...
+    def account(self, filepath: str) -> str: ...
+    def date(self, filepath: str) -> datetime.date: ...
+    def extract(
+        self, filepath: str, existing: Sequence[Directive]
+    ) -> list[Directive]: ...
+    def finalize(
+        self, txn: data.Transaction, row: Row
+    ) -> data.Transaction | None: ...
+    def identify(self, filepath: str) -> bool: ...
+    def metadata(self, filepath: str, lineno: int, row: Row) -> data.Meta: ...

tests/data/import_example_for_docs.py

@@ -1,28 +1,29 @@
 # ruff: noqa: ERA001, INP001, ARG002
+# mypy: disable-error-code="assignment"
 """An example import configuration with explanations."""
 
 from __future__ import annotations
 
 import csv
 from pathlib import Path
 from tempfile import NamedTemporaryFile
+from typing import Any
 from typing import TYPE_CHECKING
 from typing import TypeAlias
 
 import beangulp  # Importing tools
-import beangulp.importer
 from beancount.core import data  # Transaction, Posting, ...
 from beangulp.importers import csvbase
 
 if TYPE_CHECKING:
     import beancount
 
-    Importer: TypeAlias = beangulp.importer.Importer
+    Importer: TypeAlias = beangulp.Importer
     Meta: TypeAlias = beancount.core.data.Meta
     Transaction: TypeAlias = beancount.core.data.Transaction
     Directive: TypeAlias = beancount.core.data.Directive
     # dynamically created NamedTuple, see docs of using functions
-    Row: TypeAlias = "Row"
+    Row: TypeAlias = Any
 
 
 class MyCSVImporter(csvbase.Importer):
@@ -149,7 +150,8 @@ def finalize(self, txn: Transaction, row: Row) -> Transaction:
         txn.postings.append(
             data.Posting(
                 "Expenses:Unknown",
-                -txn.postings[0].units,
+                # "and" handles case if .units is None
+                (txn.postings[0].units and -txn.postings[0].units),
                 None,
                 None,
                 None,
@@ -197,5 +199,5 @@ def example_hook(
 # Allows to call this script as './import extract <filename.csv>'. Not needed
 # for Fava, but useful for debugging
 if __name__ == "__main__":
-    ingest = beangulp.Ingest(CONFIG, HOOKS)
+    ingest = beangulp.Ingest(CONFIG, HOOKS)  # type: ignore[arg-type]
     ingest()

tests/importer.pyi

@@ -0,0 +1,28 @@
+import abc
+import datetime
+from collections.abc import Sequence
+
+from fava.beans.abc import Account
+from fava.beans.abc import Directive
+
+class Importer(abc.ABC):
+    @property
+    def name(self) -> str: ...
+    @abc.abstractmethod
+    def identify(self, filepath: str) -> bool: ...
+    @abc.abstractmethod
+    def account(self, filepath: str) -> Account: ...
+    def date(self, filepath: str) -> datetime.date | None: ...
+    def filename(self, filepath: str) -> str | None: ...
+    def extract(
+        self, filepath: str, existing: Sequence[Directive]
+    ) -> list[Directive]: ...
+    def deduplicate(
+        self, entries: list[Directive], existing: Sequence[Directive]
+    ) -> None: ...
+    def sort(
+        self, entries: list[Directive], reverse: bool = False
+    ) -> None: ...
+
+class ImporterProtocol: ...
+class Adapter: ...

tests/test_import_documentation_example.py

@@ -4,7 +4,7 @@
 from typing import TYPE_CHECKING
 
 import beangulp
-import beangulp.extract
+import beangulp.extract  # type: ignore[import-untyped]
 
 import fava
 from fava.core import FavaLedger
@@ -40,7 +40,7 @@ def test_example_import(test_data_dir: Path) -> None:
     # This tests needs multiple steps as the User clicks multiple buttons until
     # the import starts
 
-    ing = fava.core.IngestModule(ledger)
+    ing = fava.core.IngestModule(ledger)  # type: ignore[attr-defined]
     # Read import configuration as defined in the fava option "import-config"
     ing.load_file()
     # Identify (file, importer) pairs based on the files it sees in the import