rustfava 0.1.0__py3-none-any.whl

rustfava/core/misc.py

@@ -0,0 +1,105 @@
+"""Some miscellaneous reports."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from rustfava.core.module_base import FavaModule
+from rustfava.helpers import BeancountError
+from rustfava.util.date import local_today
+
+if TYPE_CHECKING:  # pragma: no cover
+    from collections.abc import Sequence
+
+    from rustfava.beans.abc import Custom
+    from rustfava.beans.abc import Event
+    from rustfava.core import RustfavaLedger
+
+    SidebarLinks = Sequence[tuple[str, str]]
+
+
+class FavaError(BeancountError):
+    """Generic Fava-specific error."""
+
+
+NO_OPERATING_CURRENCY_ERROR = FavaError(
+    None,
+    "No operating currency specified. Please add one to your beancount file.",
+    None,
+)
+
+
+class FavaMisc(FavaModule):
+    """Provides access to some miscellaneous reports."""
+
+    def __init__(self, ledger: RustfavaLedger) -> None:
+        super().__init__(ledger)
+        #: User-chosen links to show in the sidebar.
+        self.sidebar_links: SidebarLinks = []
+        #: Upcoming events in the next few days.
+        self.upcoming_events: Sequence[Event] = []
+
+    def load_file(self) -> None:  # noqa: D102
+        custom_entries = self.ledger.all_entries_by_type.Custom
+        self.sidebar_links = sidebar_links(custom_entries)
+
+        self.upcoming_events = upcoming_events(
+            self.ledger.all_entries_by_type.Event,
+            self.ledger.fava_options.upcoming_events,
+        )
+
+    @property
+    def errors(self) -> Sequence[FavaError]:
+        """An error if no operating currency is set."""
+        return (
+            []
+            if self.ledger.options["operating_currency"]
+            else [NO_OPERATING_CURRENCY_ERROR]
+        )
+
+
+def sidebar_links(custom_entries: Sequence[Custom]) -> SidebarLinks:
+    """Parse custom entries for links.
+
+    They have the following format:
+
+    2016-04-01 custom "fava-sidebar-link" "2014" "/income_statement/?time=2014"
+    """
+    sidebar_link_entries = [
+        entry for entry in custom_entries if entry.type == "fava-sidebar-link"
+    ]
+    return [
+        (entry.values[0].value, entry.values[1].value)
+        for entry in sidebar_link_entries
+    ]
+
+
+def upcoming_events(
+    events: Sequence[Event], max_delta: int
+) -> Sequence[Event]:
+    """Parse entries for upcoming events.
+
+    Args:
+        events: A list of events.
+        max_delta: Number of days that should be considered.
+
+    Returns:
+        A list of the Events in entries that are less than `max_delta` days
+        away.
+    """
+    today = local_today()
+    upcoming = []
+
+    for event in events:
+        delta = event.date - today
+        if delta.days >= 0 and delta.days < max_delta:
+            upcoming.append(event)
+
+    return upcoming
+
+
+# Import align from beans.str for backwards compatibility
+# (It was moved there to avoid circular imports)
+from rustfava.beans.str import align
+
+__all__ = ["FavaMisc", "FavaError", "align"]

rustfava/core/module_base.py

@@ -0,0 +1,18 @@
+"""Base class for the "modules" of rustfavaLedger."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover
+    from rustfava.core import RustfavaLedger
+
+
+class FavaModule:
+    """Base class for the "modules" of rustfavaLedger."""
+
+    def __init__(self, ledger: RustfavaLedger) -> None:
+        self.ledger = ledger
+
+    def load_file(self) -> None:
+        """Run when the file has been (re)loaded."""

rustfava/core/number.py

@@ -0,0 +1,106 @@
+"""Formatting numbers."""
+
+from __future__ import annotations
+
+import copy
+from collections.abc import Callable
+from decimal import Decimal
+from typing import TYPE_CHECKING
+
+from babel.core import Locale
+
+from rustfava.core.module_base import FavaModule
+
+if TYPE_CHECKING:  # pragma: no cover
+    from rustfava.core import RustfavaLedger
+
+Formatter = Callable[[Decimal], str]
+
+
+def get_locale_format(locale: Locale | None, precision: int) -> Formatter:
+    """Obtain formatting pattern for the given locale and precision.
+
+    Arguments:
+        locale: An optional locale.
+        precision: The precision.
+
+    Returns:
+        A function that renders Decimals to strings as desired.
+    """
+    # Set a maximum precision of 14, half the default precision of Decimal
+    precision = min(precision, 14)
+    if locale is None:
+        fmt_string = "{:." + str(precision) + "f}"
+
+        def fmt(num: Decimal) -> str:
+            return fmt_string.format(num)
+
+        return fmt
+
+    pattern = copy.copy(locale.decimal_formats.get(None))
+    if not pattern:  # pragma: no cover
+        msg = "Expected Locale to have a decimal format pattern"
+        raise ValueError(msg)
+    pattern.frac_prec = (precision, precision)
+
+    def locale_fmt(num: Decimal) -> str:
+        return pattern.apply(num, locale)  # type: ignore[no-any-return]
+
+    return locale_fmt
+
+
+class DecimalFormatModule(FavaModule):
+    """Formatting numbers."""
+
+    def __init__(self, ledger: RustfavaLedger) -> None:
+        super().__init__(ledger)
+        self._locale: Locale | None = None
+        self._formatters: dict[str, Formatter] = {}
+        self._default_pattern = get_locale_format(None, 2)
+        self.precisions: dict[str, int] = {}
+
+    def load_file(self) -> None:  # noqa: D102
+        locale = None
+
+        locale_option = self.ledger.fava_options.locale
+        if (
+            self.ledger.options["render_commas"] and not locale_option
+        ):  # pragma: no cover
+            locale_option = "en"
+            self.ledger.fava_options.locale = locale_option
+
+        if locale_option:
+            locale = Locale.parse(locale_option)
+
+        dcontext = self.ledger.options["dcontext"]
+        precisions: dict[str, int] = {}
+
+        # Both beancount's DisplayContext and RLDisplayContext have ccontexts
+        for currency, ccontext in dcontext.ccontexts.items():
+            prec = ccontext.get_fractional(None)
+            if prec is not None:
+                precisions[currency] = prec
+
+        precisions.update(self.ledger.commodities.precisions)
+
+        self._locale = locale
+        self._default_pattern = get_locale_format(locale, 2)
+        self._formatters = {
+            currency: get_locale_format(locale, prec)
+            for currency, prec in precisions.items()
+        }
+        self.precisions = precisions
+
+    def __call__(self, value: Decimal, currency: str | None = None) -> str:
+        """Format a decimal to the right number of decimal digits with locale.
+
+        Arguments:
+            value: A decimal number.
+            currency: A currency string or None.
+
+        Returns:
+            A string, the formatted decimal.
+        """
+        if currency is None:
+            return self._default_pattern(value)
+        return self._formatters.get(currency, self._default_pattern)(value)

rustfava/core/query.py

@@ -0,0 +1,180 @@
+"""Query result types."""
+
+from __future__ import annotations
+
+import datetime
+from dataclasses import dataclass
+from decimal import Decimal
+from typing import TYPE_CHECKING
+
+from rustfava.rustledger.types import RLAmount
+from rustfava.rustledger.types import RLPosition
+from rustfava.core.conversion import UNITS
+
+if TYPE_CHECKING:  # pragma: no cover
+    from typing import Any
+    from typing import Literal
+    from typing import TypeAlias
+    from typing import TypeVar
+
+    from rustfava.core.inventory import SimpleCounterInventory
+
+    T = TypeVar("T")
+
+    QueryRowValue = Any
+
+    # This is not a complete enumeration of all possible column types but just
+    # of the ones we pass in some specific serialisation to the frontend.
+    # Everything unknown will be stringified (by ObjectColumn).
+    SerialisedQueryRowValue = (
+        bool
+        | int
+        | str
+        | datetime.date
+        | Decimal
+        | RLPosition
+        | SimpleCounterInventory
+        | None
+    )
+
+
+@dataclass(frozen=True)
+class QueryResultTable:
+    """Table query result."""
+
+    types: list[BaseColumn]
+    rows: list[tuple[SerialisedQueryRowValue, ...]]
+    t: Literal["table"] = "table"
+
+
+@dataclass(frozen=True)
+class QueryResultText:
+    """Text query result."""
+
+    contents: str
+    t: Literal["string"] = "string"
+
+
+QueryResult: TypeAlias = QueryResultTable | QueryResultText
+
+
+@dataclass(frozen=True)
+class BaseColumn:
+    """A query column."""
+
+    name: str
+    dtype: str
+
+    @staticmethod
+    def serialise(
+        val: QueryRowValue,
+    ) -> SerialisedQueryRowValue:
+        """Serialiseable version of the column value."""
+        return val  # type: ignore[no-any-return]
+
+
+@dataclass(frozen=True)
+class BoolColumn(BaseColumn):
+    """A boolean query column."""
+
+    dtype: str = "bool"
+
+
+@dataclass(frozen=True)
+class DecimalColumn(BaseColumn):
+    """A Decimal query column."""
+
+    dtype: str = "Decimal"
+
+
+@dataclass(frozen=True)
+class IntColumn(BaseColumn):
+    """A int query column."""
+
+    dtype: str = "int"
+
+
+@dataclass(frozen=True)
+class StrColumn(BaseColumn):
+    """A str query column."""
+
+    dtype: str = "str"
+
+
+@dataclass(frozen=True)
+class DateColumn(BaseColumn):
+    """A date query column."""
+
+    dtype: str = "date"
+
+
+@dataclass(frozen=True)
+class PositionColumn(BaseColumn):
+    """A Position query column."""
+
+    dtype: str = "Position"
+
+
+@dataclass(frozen=True)
+class SetColumn(BaseColumn):
+    """A set query column."""
+
+    dtype: str = "set"
+
+
+@dataclass(frozen=True)
+class AmountColumn(BaseColumn):
+    """An amount query column."""
+
+    dtype: str = "Amount"
+
+
+@dataclass(frozen=True)
+class ObjectColumn(BaseColumn):
+    """An object query column."""
+
+    dtype: str = "object"
+
+    @staticmethod
+    def serialise(val: object) -> str:
+        """Serialise an object of unknown type to a string."""
+        return str(val)
+
+
+@dataclass(frozen=True)
+class InventoryColumn(BaseColumn):
+    """An inventory query column."""
+
+    dtype: str = "Inventory"
+
+    @staticmethod
+    def serialise(
+        val: dict[str, Decimal] | None,
+    ) -> SimpleCounterInventory | None:
+        """Serialise an inventory.
+
+        Rustledger returns inventory as a dict of currency -> Decimal.
+        """
+        if val is None:
+            return None
+        # Rustledger already converts to {currency: Decimal} format
+        if isinstance(val, dict):
+            from rustfava.core.inventory import SimpleCounterInventory
+            return SimpleCounterInventory(val)
+        # Fallback for beancount Inventory type (for backwards compat)
+        return UNITS.apply_inventory(val) if val is not None else None
+
+
+COLUMNS = {
+    RLAmount: AmountColumn,
+    Decimal: DecimalColumn,
+    dict: InventoryColumn,  # Rustledger returns inventory as dict
+    RLPosition: PositionColumn,
+    object: ObjectColumn,  # Fallback for Position from rustledger
+    bool: BoolColumn,
+    datetime.date: DateColumn,
+    int: IntColumn,
+    set: SetColumn,
+    frozenset: SetColumn,  # Rustledger returns frozenset for sets
+    str: StrColumn,
+}

rustfava/core/query_shell.py

@@ -0,0 +1,301 @@
+"""For running BQL queries in Fava."""
+
+from __future__ import annotations
+
+import io
+import shlex
+from typing import TYPE_CHECKING
+
+from rustfava.core.module_base import FavaModule
+from rustfava.core.query import COLUMNS
+from rustfava.core.query import ObjectColumn
+from rustfava.core.query import QueryResultTable
+from rustfava.core.query import QueryResultText
+from rustfava.helpers import RustfavaAPIError
+from rustfava.rustledger.query import CompilationError
+from rustfava.rustledger.query import connect
+from rustfava.rustledger.query import ParseError
+from rustfava.rustledger.query import RLConnection
+from rustfava.rustledger.query import RLCursor
+from rustfava.util.excel import HAVE_EXCEL
+from rustfava.util.excel import to_csv
+from rustfava.util.excel import to_excel
+
+if TYPE_CHECKING:  # pragma: no cover
+    from collections.abc import Sequence
+
+    from rustfava.beans.abc import Directive
+    from rustfava.core import RustfavaLedger
+
+
+class FavaShellError(RustfavaAPIError):
+    """An error in the Fava BQL shell, will be turned into a string."""
+
+
+class QueryNotFoundError(FavaShellError):
+    """Query '{name}' not found."""
+
+    def __init__(self, name: str) -> None:
+        super().__init__(f"Query '{name}' not found.")
+
+
+class TooManyRunArgsError(FavaShellError):
+    """Too many args to run: '{args}'."""
+
+    def __init__(self, args: str) -> None:
+        super().__init__(f"Too many args to run: '{args}'.")
+
+
+class QueryCompilationError(FavaShellError):
+    """Query compilation error."""
+
+    def __init__(self, err: CompilationError) -> None:
+        super().__init__(f"Query compilation error: {err!s}.")
+
+
+class QueryParseError(FavaShellError):
+    """Query parse error."""
+
+    def __init__(self, err: ParseError) -> None:
+        super().__init__(f"Query parse error: {err!s}.")
+
+
+class NonExportableQueryError(FavaShellError):
+    """Only queries that return a table can be printed to a file."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "Only queries that return a table can be printed to a file."
+        )
+
+
+class FavaQueryRunner:
+    """Runs BQL queries using rustledger."""
+
+    def __init__(self, ledger: RustfavaLedger) -> None:
+        self.ledger = ledger
+
+    def run(
+        self, entries: Sequence[Directive], query: str
+    ) -> RLCursor | str:
+        """Run a query, returning cursor or text result."""
+        # Get the source from the ledger for queries
+        source = getattr(self.ledger, "_source", None)
+
+        # Create connection
+        conn = connect(
+            "rustledger:",
+            entries=entries,
+            errors=self.ledger.errors,
+            options=self.ledger.options,
+        )
+
+        if source:
+            conn.set_source(source)
+
+        # Parse the query to handle special commands
+        query = query.strip()
+        query_lower = query.lower()
+
+        # Handle noop commands (return fixed text)
+        noop_doc = "Doesn't do anything in rustfava's query shell."
+        if query_lower in (".exit", ".quit", "exit", "quit"):
+            return noop_doc
+
+        # Handle .run or run command
+        if query_lower.startswith((".run", "run")):
+            # Check if it's just "run" or ".run" (list queries) or "run name"
+            if query_lower in ("run", ".run") or query_lower.startswith(("run ", ".run ")):
+                return self._handle_run(query, conn)
+
+        # Handle help commands - return text
+        if query_lower.startswith((".help", "help")):
+            # ".help exit" or ".help <command>" returns noop doc
+            if " " in query_lower:
+                return noop_doc
+            return self._help_text()
+
+        # Handle .explain - return placeholder
+        if query_lower.startswith((".explain", "explain")):
+            return f"EXPLAIN: {query}"
+
+        # Handle SELECT/BALANCES/JOURNAL queries
+        try:
+            return conn.execute(query)
+        except ParseError as exc:
+            raise QueryParseError(exc) from exc
+        except CompilationError as exc:
+            raise QueryCompilationError(exc) from exc
+
+    def _handle_run(self, query: str, conn: RLConnection) -> RLCursor | str:
+        """Handle .run command to execute stored queries."""
+        queries = self.ledger.all_entries_by_type.Query
+
+        # Parse the run command
+        parts = shlex.split(query)
+        if len(parts) == 1:
+            # Just "run" - list available queries
+            return "\n".join(q.name for q in queries)
+
+        if len(parts) > 2:
+            raise TooManyRunArgsError(query)
+
+        name = parts[1].rstrip(";")
+        query_obj = next((q for q in queries if q.name == name), None)
+        if query_obj is None:
+            raise QueryNotFoundError(name)
+
+        try:
+            return conn.execute(query_obj.query_string)
+        except ParseError as exc:
+            raise QueryParseError(exc) from exc
+        except CompilationError as exc:
+            raise QueryCompilationError(exc) from exc
+
+    def _help_text(self) -> str:
+        """Return help text for the query shell."""
+        return """Fava Query Shell
+
+Commands:
+  SELECT ...     Run a BQL SELECT query
+  run <name>     Run a stored query by name
+  run            List all stored queries
+  help           Show this help message
+
+Example queries:
+  SELECT account, sum(position) GROUP BY account
+  SELECT date, narration, position WHERE account ~ "Expenses"
+"""
+
+
+class QueryShell(FavaModule):
+    """A Fava module to run BQL queries."""
+
+    def __init__(self, ledger: RustfavaLedger) -> None:
+        super().__init__(ledger)
+        self.runner = FavaQueryRunner(ledger)
+
+    def execute_query_serialised(
+        self, entries: Sequence[Directive], query: str
+    ) -> QueryResultTable | QueryResultText:
+        """Run a query and returns its serialised result.
+
+        Arguments:
+            entries: The entries to run the query on.
+            query: A query string.
+
+        Returns:
+            Either a table or a text result (depending on the query).
+
+        Raises:
+            RustfavaAPIError: If the query response is an error.
+        """
+        res = self.runner.run(entries, query)
+        return (
+            QueryResultText(res) if isinstance(res, str) else _serialise(res)
+        )
+
+    def query_to_file(
+        self,
+        entries: Sequence[Directive],
+        query_string: str,
+        result_format: str,
+    ) -> tuple[str, io.BytesIO]:
+        """Get query result as file.
+
+        Arguments:
+            entries: The entries to run the query on.
+            query_string: A string, the query to run.
+            result_format: The file format to save to.
+
+        Returns:
+            A tuple (name, data), where name is either 'query_result' or the
+            name of a custom query if the query string is 'run name_of_query'.
+            ``data`` contains the file contents.
+
+        Raises:
+            RustfavaAPIError: If the result format is not supported or the
+            query failed.
+        """
+        name = "query_result"
+
+        if query_string.lower().startswith((".run", "run ")):
+            parts = shlex.split(query_string)
+            if len(parts) > 2:
+                raise TooManyRunArgsError(query_string)
+            if len(parts) == 2:
+                name = parts[1].rstrip(";")
+                queries = self.ledger.all_entries_by_type.Query
+                query_obj = next((q for q in queries if q.name == name), None)
+                if query_obj is None:
+                    raise QueryNotFoundError(name)
+                query_string = query_obj.query_string
+
+        res = self.runner.run(entries, query_string)
+        if isinstance(res, str):
+            raise NonExportableQueryError
+
+        rrows = res.fetchall()
+        rtypes = res.description
+
+        # Convert rows to exportable format
+        rows = _numberify_rows(rrows, rtypes)
+
+        if result_format == "csv":
+            data = to_csv(list(rtypes), rows)
+        else:
+            if not HAVE_EXCEL:  # pragma: no cover
+                msg = "Result format not supported."
+                raise RustfavaAPIError(msg)
+            data = to_excel(list(rtypes), rows, result_format, query_string)
+        return name, data
+
+
+def _numberify_rows(
+    rows: list[tuple[object, ...]],
+    columns: tuple[object, ...],
+) -> list[tuple[object, ...]]:
+    """Convert row values to exportable format.
+
+    This replaces beanquery.numberify.numberify_results for our use case.
+    """
+    result: list[tuple[object, ...]] = []
+    for row in rows:
+        new_row: list[object] = []
+        for i, value in enumerate(row):
+            col = columns[i]
+            # Convert complex types to strings for export
+            if hasattr(value, "number") and hasattr(value, "currency"):
+                # Amount-like
+                new_row.append(f"{value.number} {value.currency}")
+            elif isinstance(value, dict):
+                # Inventory or other dict
+                if "positions" in value:
+                    # Inventory
+                    parts = []
+                    for pos in value.get("positions", []):
+                        units = pos.get("units", {})
+                        parts.append(f"{units.get('number', '')} {units.get('currency', '')}")
+                    new_row.append(", ".join(parts))
+                else:
+                    new_row.append(str(value))
+            elif isinstance(value, (list, set, frozenset)):
+                new_row.append(", ".join(str(v) for v in value))
+            else:
+                new_row.append(value)
+        result.append(tuple(new_row))
+    return result
+
+
+def _serialise(cursor: RLCursor) -> QueryResultTable:
+    """Serialise the query result."""
+    dtypes = [
+        COLUMNS.get(c.datatype, ObjectColumn)(c.name)
+        for c in cursor.description
+    ]
+    mappers = [d.serialise for d in dtypes]
+    mapped_rows = [
+        tuple(mapper(row[i]) for i, mapper in enumerate(mappers))
+        for row in cursor
+    ]
+    return QueryResultTable(dtypes, mapped_rows)