rustfava 0.1.0__py3-none-any.whl

rustfava/ext/auto_commit.py

@@ -0,0 +1,61 @@
+"""Auto-commit hook for rustfava.
+
+This mainly serves as an example how rustfava's extension systems, which only
+really does hooks at the moment, works.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+from typing import TYPE_CHECKING
+from typing import override
+
+from rustfava.ext import RustfavaExtensionBase
+
+if TYPE_CHECKING:  # pragma: no cover
+    from rustfava.beans.abc import Directive
+
+
+class AutoCommit(RustfavaExtensionBase):  # pragma: no cover
+    """Auto-commit hook for rustfava."""
+
+    def _run(self, args: list[str]) -> None:
+        cwd = Path(self.ledger.beancount_file_path).parent
+        subprocess.run(args, cwd=cwd, stdout=subprocess.DEVNULL, check=False)
+
+    @override
+    def after_write_source(self, path: str, source: str) -> None:
+        """Add changed file to git and commit."""
+        message = "autocommit: file saved"
+        self._run(["git", "add", path])
+        self._run(["git", "commit", "-m", message])
+
+    @override
+    def after_insert_metadata(
+        self,
+        entry: Directive,
+        key: str,
+        value: str,
+    ) -> None:
+        """Commit all changes on `after_insert_metadata`."""
+        message = "autocommit: metadata added"
+        self._run(["git", "commit", "-am", message])
+
+    @override
+    def after_insert_entry(self, entry: Directive) -> None:
+        """Commit all changes on `after_insert_entry`."""
+        message = f"autocommit: entry on {entry.date}"
+        self._run(["git", "commit", "-am", message])
+
+    @override
+    def after_delete_entry(self, entry: Directive) -> None:
+        """Commit all changes on `after_delete_entry`."""
+        message = f"autocommit: deleted entry on {entry.date}"
+        self._run(["git", "commit", "-am", message])
+
+    @override
+    def after_entry_modified(self, entry: Directive, new_lines: str) -> None:
+        """Commit all changes on `after_entry_modified`."""
+        message = f"autocommit: modified entry on {entry.date}"
+        self._run(["git", "commit", "-am", message])

rustfava/ext/portfolio_list/PortfolioList.js

@@ -0,0 +1,34 @@
+// @ts-check
+
+/** @type import("../../../../frontend/src/extensions").ExtensionModule */
+export default {
+  init() {
+    console.log("initialising extension");
+  },
+  onPageLoad() {
+    console.log("a Fava report page has loaded", window.location.pathname);
+  },
+  onExtensionPageLoad() {
+    console.log(
+      "the page for the PortfolioList extension has loaded",
+      window.location.pathname,
+    );
+
+    const updateFilter = document.getElementById("portfolio-update-filter");
+    updateFilter?.addEventListener("click", () => {
+      const filterInput = document.getElementById("portfolio-list-filter");
+      if (filterInput instanceof HTMLInputElement && filterInput.value.length) {
+        const search = new URLSearchParams(window.location.search);
+        search.set("account_filter", filterInput.value);
+        window.location.search = search.toString();
+      }
+    });
+
+    const clearFilter = document.getElementById("portfolio-clear-filter");
+    clearFilter?.addEventListener("click", () => {
+      const search = new URLSearchParams(window.location.search);
+      search.delete("account_filter");
+      window.location.search = search.toString();
+    });
+  },
+};

rustfava/ext/portfolio_list/__init__.py

@@ -0,0 +1,29 @@
+"""Portfolio list extension for rustfava.
+
+This is a simple example of rustfava's extension reports system.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from rustfava.ext import RustfavaExtensionBase
+from rustfava.ext.rustfava_ext_test import portfolio_accounts
+
+if TYPE_CHECKING:  # pragma: no cover
+    from rustfava.ext.rustfava_ext_test import Portfolio
+
+
+class PortfolioList(RustfavaExtensionBase):  # pragma: no cover
+    """Sample Extension Report that just prints out an Portfolio List."""
+
+    report_title = "Portfolio List"
+
+    has_js_module = True
+
+    def portfolio_accounts(
+        self,
+        filter_str: str | None = None,
+    ) -> list[Portfolio]:
+        """Get an account tree based on matching regex patterns."""
+        return portfolio_accounts(self.config, filter_str)

rustfava/ext/portfolio_list/templates/PortfolioList.html

@@ -0,0 +1,15 @@
+{% set arg_filter = request.args.get('account_filter') %}
+
+<h2>Portfolio List Sample Report Extension</h2>
+
+<p>
+<label for="portfolio-list-filter">Custom Account Filter:</label>
+<input id="portfolio-list-filter" value={{arg_filter or ""}}>
+<button id="portfolio-update-filter">Update Filter</button>
+<button id="portfolio-clear-filter">Clear Filter</button>
+</p>
+
+{% for portfolio in extension.portfolio_accounts(arg_filter) %}
+  <h3>{{ portfolio.title }}</h3>
+  <svelte-component type="query-table"><script type="application/json">{{portfolio.table|tojson}}</script></svelte-component>
+{% endfor %}

rustfava/ext/rustfava_ext_test/RustfavaExtTest.js

@@ -0,0 +1,42 @@
+// @ts-check
+
+/** @type import("../../../../frontend/src/extensions").ExtensionModule */
+export default {
+  init() {
+    console.log("initialising extension");
+  },
+  onPageLoad() {
+    console.log("a Fava report page has loaded", window.location.pathname);
+  },
+  onExtensionPageLoad(ctx) {
+    console.log(
+      "the page for the PortfolioList extension has loaded",
+      window.location.pathname,
+    );
+
+    const fetchedDataElement = document.getElementById("fetched-data");
+    if (fetchedDataElement) {
+      ctx.api.get("example_data", {}).then((d) => {
+        console.log("fetched data:", d);
+        fetchedDataElement.innerText = `fetched data: ${JSON.stringify(d)}`;
+      });
+    }
+
+    const updateFilter = document.getElementById("portfolio-update-filter");
+    updateFilter?.addEventListener("click", () => {
+      const filterInput = document.getElementById("portfolio-list-filter");
+      if (filterInput instanceof HTMLInputElement && filterInput.value.length) {
+        const search = new URLSearchParams(window.location.search);
+        search.set("account_filter", filterInput.value);
+        window.location.search = search.toString();
+      }
+    });
+
+    const clearFilter = document.getElementById("portfolio-clear-filter");
+    clearFilter?.addEventListener("click", () => {
+      const search = new URLSearchParams(window.location.search);
+      search.delete("account_filter");
+      window.location.search = search.toString();
+    });
+  },
+};

rustfava/ext/rustfava_ext_test/__init__.py

@@ -0,0 +1,207 @@
+"""Rustfava extension to test extension functionality.
+
+# This can be used mainly for testing of the extension functionality
+and usage of e.g. extension Javascript code or custom elements.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from datetime import date
+from decimal import Decimal
+from typing import Any
+from typing import TYPE_CHECKING
+
+from flask import jsonify
+
+from rustfava.context import g
+from rustfava.core.charts import DateAndBalance
+from rustfava.core.inventory import SimpleCounterInventory
+from rustfava.core.query import DecimalColumn
+from rustfava.core.query import QueryResultTable
+from rustfava.core.query import StrColumn
+from rustfava.ext import extension_endpoint
+from rustfava.ext import RustfavaExtensionBase
+from rustfava.helpers import RustfavaAPIError
+from rustfava.internal_api import BalancesChart
+
+if TYPE_CHECKING:  # pragma: no cover
+    from flask.wrappers import Response
+
+    from rustfava.core.tree import SerialisedTreeNode
+    from rustfava.core.tree import Tree
+    from rustfava.core.tree import TreeNode
+
+
+@dataclass(frozen=True)
+class Portfolio:
+    """A portfolio.
+
+    Consists of a title and the result table to render.
+    """
+
+    title: str
+    table: QueryResultTable
+
+
+def _portfolio_data(nodes: list[TreeNode]) -> QueryResultTable:
+    """Turn a portfolio of tree nodes into querytable-style data.
+
+    Args:
+        nodes: Account tree nodes.
+
+    Returns:
+        A QueryResultTable for the portfolio.
+    """
+    currency = g.ledger.options["operating_currency"][0]
+    account_balances: list[tuple[str, Decimal | None]] = []
+    total = Decimal()
+    for node in nodes:
+        balance = g.conv.apply(node.balance, g.ledger.prices)
+        if currency in balance:
+            balance_dec = balance[currency]
+            total += balance_dec
+            account_balances.append((node.name, balance_dec))
+        else:
+            account_balances.append((node.name, None))
+
+    return QueryResultTable(
+        [
+            StrColumn("account"),
+            DecimalColumn("balance"),
+            DecimalColumn("allocation"),
+        ],
+        [
+            (
+                account,
+                balance,
+                (round((balance / total) * 100, 2) if balance else None),
+            )
+            for account, balance in account_balances
+        ],
+    )
+
+
+def account_name_pattern_portfolio(tree: Tree, pattern: str) -> Portfolio:
+    """Return portfolio info based on matching account name.
+
+    Args:
+        tree: Ledger root tree node.
+        pattern: Account name regex pattern.
+
+    Returns:
+        A `Portfolio` for the accounts matching the pattern.
+    """
+    regexer = re.compile(pattern)
+    selected_nodes = [
+        node for account, node in tree.items() if regexer.match(account)
+    ]
+    return Portfolio(
+        f"Account names matching: '{pattern}'",
+        _portfolio_data(selected_nodes),
+    )
+
+
+def account_metadata_pattern_portfolio(
+    tree: Tree,
+    metadata_key: str,
+    pattern: str,
+) -> Portfolio:
+    """Return portfolio info based on matching account open metadata.
+
+    Args:
+        tree: Ledger root tree node.
+        metadata_key: Metadata key to match for in account open.
+        pattern: Metadata value's regex pattern to match for.
+
+    Returns:
+        A `Portfolio` for the accounts with matching open metadata.
+    """
+    regexer = re.compile(pattern)
+    selected_nodes = [
+        tree[entry.account]
+        for entry in g.ledger.all_entries_by_type.Open
+        if metadata_key in entry.meta
+        and regexer.match(str(entry.meta[metadata_key]))
+    ]
+    return Portfolio(
+        f"Accounts with '{metadata_key}' metadata matching: '{pattern}'",
+        _portfolio_data(selected_nodes),
+    )
+
+
+def portfolio_accounts(
+    config: Any,
+    filter_str: str | None = None,
+) -> list[Portfolio]:
+    """Get an account tree based on matching regex patterns."""
+    tree = g.filtered.root_tree
+
+    if filter_str:  # pragma: no cover
+        return [account_name_pattern_portfolio(tree, filter_str)]
+
+    portfolios = []
+    for key, value in config:
+        if key == "account_name_pattern":
+            portfolios.append(account_name_pattern_portfolio(tree, value))
+        elif key == "account_open_metadata_pattern":
+            metadata_key, metadata_pattern = value
+            portfolios.append(
+                account_metadata_pattern_portfolio(
+                    tree, metadata_key, metadata_pattern
+                )
+            )
+        else:  # pragma: no cover
+            msg = "Portfolio List: Invalid option."
+            raise RustfavaAPIError(msg)
+
+    return portfolios
+
+
+class RustfavaExtTest(RustfavaExtensionBase):
+    """Rustfava extension to test extension functionality."""
+
+    report_title = "Rustfava extension test"
+
+    has_js_module = True
+
+    def portfolio_accounts(
+        self,
+        filter_str: str | None = None,
+    ) -> list[Portfolio]:
+        """Get an account tree based on matching regex patterns."""
+        return portfolio_accounts(self.config, filter_str)
+
+    @extension_endpoint
+    def example_tree(self) -> SerialisedTreeNode:
+        """Return a tree to render as a tree-table."""
+        assets = g.ledger.options["name_assets"]
+        return g.filtered.root_tree.get(assets).serialise_with_context()
+
+    @extension_endpoint
+    def example_data(self) -> Response:
+        """Return some data with a GET endpoint."""
+        return jsonify(["some data"])
+
+    def chart_data(self) -> list[BalancesChart]:
+        """Return some chart data."""
+        return [
+            BalancesChart(
+                "nonsense data",
+                [
+                    DateAndBalance(
+                        date(2023, 1, 1),
+                        SimpleCounterInventory(EUR=Decimal(10)),
+                    ),
+                    DateAndBalance(
+                        date(2023, 2, 1),
+                        SimpleCounterInventory(EUR=Decimal(15)),
+                    ),
+                    DateAndBalance(
+                        date(2023, 3, 1),
+                        SimpleCounterInventory(EUR=Decimal(20)),
+                    ),
+                ],
+            )
+        ]

rustfava/ext/rustfava_ext_test/templates/RustfavaExtTest.html

@@ -0,0 +1,45 @@
+{% set arg_filter = request.args.get('account_filter') %}
+
+{% include 'RustfavaExtTestInclude.html' %}
+
+<p>
+  <label for="portfolio-list-filter">Custom Account Filter:</label>
+  <input id="portfolio-list-filter" value={{arg_filter or ""}}>
+  <button id="portfolio-update-filter">Update Filter</button>
+  <button id="portfolio-clear-filter">Clear Filter</button>
+</p>
+
+<hr>
+
+<h3>Test for asynchronously fetched data</h3>
+<p id="fetched-data"></p>
+
+<hr>
+
+<h3>Rustfava charts custom elements tests</h3>
+<h4>Expected error: missing type</h4>
+<svelte-component></svelte-component>
+<h4>Expected error: unknown type</h4>
+<svelte-component type="unknown"></svelte-component>
+<h4>Expected error: invalid data type</h4>
+<svelte-component type="charts"></svelte-component>
+<h4>This should render a chart</h4>
+<svelte-component type="charts"><script type="application/json">{{extension.chart_data()|tojson}}</script></svelte-component>
+
+<hr>
+
+<h3>Tree-table test</h3>
+{% set tree = extension.example_tree() %}
+<svelte-component type="tree-table"><script type="application/json">{{tree|tojson}}</script></svelte-component>
+<hr>
+
+<h3>Portfolio (renders a query-table)</h3>
+{% for portfolio in extension.portfolio_accounts(arg_filter) %}
+  <h4>{{ portfolio.title }}</h4>
+  <svelte-component type="query-table"><script type="application/json">{{portfolio.table|tojson}}</script></svelte-component>
+{% endfor %}
+<hr>
+
+<h3>Query table (postings by account) from BQL query.</h3>
+{% set postings_per_account = 'SELECT account, count(account) ORDER BY account' %}
+<svelte-component type="query-table"><script type="application/json">{{ledger.query_shell.execute_query_serialised(g.filtered.entries_with_all_prices, postings_per_account)|tojson}}</script></svelte-component>

rustfava/ext/rustfava_ext_test/templates/RustfavaExtTestInclude.html

@@ -0,0 +1 @@
+<h2>Fava Test Extension</h2>

rustfava/help/__init__.py

@@ -0,0 +1,15 @@
+"""List of all available help pages."""
+
+from __future__ import annotations
+
+HELP_PAGES = {
+    "_index": "Index",
+    "budgets": "Budgets",
+    "conversion": "Conversion",
+    "import": "Import",
+    "options": "Options",
+    "beancount_syntax": "Beancount Syntax",
+    "features": "Fava's features",
+    "filters": "Filtering entries",
+    "extensions": "Extensions",
+}

rustfava/help/_index.md

@@ -0,0 +1,29 @@
+Welcome to the help pages for rustfava! You are running rustfava
+`{{ rustfava_version }}` powered by rustledger. There are help pages for the
+following topics:
+
+- [Beancount Syntax](./beancount_syntax) - short overview of the syntax.
+- [Budgets](./budgets) - how to use rustfava's budgeting feature.
+- [rustfava's Features](./features) - the features in detail.
+- [Filtering entries](./filters) - how to filter the entries.
+- [Extensions](./extensions) - how rustfava can be extended.
+- [Conversion](./conversion) - how to convert between currencies.
+- [Import](./import) - the import system.
+- [Options](./options) - the available options.
+
+Rustfava comes with keyboard shortcuts - press <kbd>?</kbd> on any page to see the
+available ones.
+
+If you started rustfava from the command line, you can run `rustfava --help` to see all
+the available command line options.
+
+If you discover a bug in rustfava, or have some ideas for improvement, please open a
+[bug report](https://github.com/rustledger/rustfava/issues).
+
+### Related websites
+
+- Rustfava on [GitHub](https://github.com/rustledger/rustfava),
+- rustledger on [GitHub](https://github.com/rustledger/rustledger),
+- Beancount file format [documentation](http://furius.ca/beancount/doc/index),
+- An overview of other implementations of command-line accounting:
+  [Plain Text Accounting](http://plaintextaccounting.org).

rustfava/help/beancount_syntax.md

@@ -0,0 +1,156 @@
+# Beancount Syntax
+
+Below is a short reference of the Beancount language syntax. Also see the full
+[Syntax Documentation](http://furius.ca/beancount/doc/syntax) and the
+[Syntax Cheat Sheet](http://furius.ca/beancount/doc/cheatsheet).
+
+Beancount defines a language in which financial transactions are entered into a
+text-file, which then can be processed by Beancount. There are a few building
+blocks that are important to understand Beancount's syntax:
+
+- Commodities,
+- Accounts,
+- Directives.
+
+## Commodities
+
+All in CAPS: `USD`, `EUR`, `CAD`, `GOOG`, `AAPL`, `RBF1005`, `HOME_MAYST`,
+`AIRMILES`, `HOURS`.
+
+## Accounts
+
+Account are given by a colon-separated list of capitalized words. They must
+begin with one of the five root accounts listed in the table below. The
+separation by colons defines an implicit hierarchy, for example we say that
+`Assets:Cash` is a sub-account of `Assets`.
+
+| Name          | Type | Contains                     | Examples                  |
+| ------------- | ---- | ---------------------------- | ------------------------- |
+| `Assets`      | +    | Cash, Checking-Account, etc. | `Assets:Checking`         |
+| `Liabilities` | -    | Credit Card, etc.            | `Liabilities:CreditCard`  |
+| `Income`      | -    | Salary, etc.                 | `Income:EmployerA`        |
+| `Expenses`    | +    | Expense categories           | `Expenses:Fun:Cinema`     |
+| `Equity`      | -    | Almost always auto-generated | `Equity:Opening-Balances` |
+
+The names of the five root accounts can be changed with the following options:
+
+<pre><textarea is="beancount-textarea">
+option "name_assets"      "Vermoegen"
+option "name_liabilities" "Verbindlichkeiten"
+option "name_income"      "Einkommen"
+option "name_expenses"    "Ausgaben"
+option "name_equity"      "Eigenkapital"</textarea></pre>
+
+## Directives
+
+The basic building block are **directives** (also called **entries**). Most
+directives start with a date, then the type of the directive, and then
+directive-specific arguments. The ordering of directives in the input-file does
+not matter, because Beancount orders them based on the date of each directive.
+
+General syntax: `YYYY-MM-DD <directive> <arguments...>`
+
+### Open and Close accounts
+
+To open or close an account use the `open` and `close` directives:
+
+<pre><textarea is="beancount-textarea" is="beancount-textarea">
+2015-05-29 open Expenses:Restaurant
+; Account with some currency constraints:
+2015-05-29 open Assets:Checking     USD,EUR
+; ...
+2016-02-23 close Assets:Checking</textarea></pre>
+
+### Commodities
+
+Declaring commodities is optional. Use this if you want to attach metadata by
+currency. If you specify a `name` for a currency like below, this name will be
+displayed as a tooltip on hovering over currency names in rustfava. Likewise, with
+the `precision` metadata, you can specify the number of decimal digits to show
+in rustfava, overriding the precision that is otherwise automatically inferred from
+the input data.
+
+<pre><textarea is="beancount-textarea">
+1998-07-22 commodity AAPL
+  name: "Apple Computer Inc."
+  precision: 3</textarea></pre>
+
+### Prices
+
+You can use this directive to fill the historical price database:
+
+<pre><textarea is="beancount-textarea">
+2015-04-30 price AAPL   125.15 USD
+2015-05-30 price AAPL   130.28 USD</textarea></pre>
+
+### Notes
+
+<pre><textarea is="beancount-textarea">
+2013-03-20 note Assets:Checking "Called to ask about rebate"</textarea></pre>
+
+### Documents
+
+<pre><textarea is="beancount-textarea">
+2013-03-20 document Assets:Checking "path/to/statement.pdf"</textarea></pre>
+
+### Transactions
+
+<pre><textarea is="beancount-textarea">
+2015-05-30 * "Some narration about this transaction"
+  Liabilities:CreditCard   -101.23 USD
+  Expenses:Restaurant       101.23 USD
+
+2015-05-30 ! "Cable Co" "Phone Bill" #tag ^link
+  id: "TW378743437"
+  Expenses:Home:Phone  87.45 USD
+  Assets:Checking                 ; You may leave one amount out</textarea></pre>
+
+### Postings
+
+<pre><textarea is="beancount-textarea">
+2015-05-30 * "Example transaction with various postings"
+  Account:Name   123.45 USD                           ; simple units
+  Account:Name      10 GOOG {502.12 USD}              ; with cost
+  Account:Name  1000.00 USD  @ 1.10 CAD               ; with price
+  Account:Name      10 GOOG {502.12 USD} @ 1.10 CAD   ; with cost & price
+  Account:Name      10 GOOG {502.12 USD, 2014-05-12}  ; with cost date
+  ! Account:Name 123.45 USD                           ; with flag</textarea></pre>
+
+### Balance Assertions and Padding
+
+Asserts the amount for only the given currency:
+
+<pre><textarea is="beancount-textarea">
+2015-06-01 balance Liabilities:CreditCard  -634.30 USD</textarea></pre>
+
+Automatic insertion of transaction to fulfill the following assertion:
+
+<pre><textarea is="beancount-textarea">
+2015-06-01 pad Assets:Checking Equity:Opening-Balances</textarea></pre>
+
+### Events
+
+<pre><textarea is="beancount-textarea">
+2015-06-01 event "location" "New York, USA"
+2015-06-01 event "address" "123 May Street"</textarea></pre>
+
+### Options
+
+See the [Beancount Options Reference](http://furius.ca/beancount/doc/options)
+for the full list of supported options.
+
+<pre><textarea is="beancount-textarea">
+option "title" "My Personal Ledger"</textarea></pre>
+
+### Other
+
+<pre><textarea is="beancount-textarea">
+pushtag #trip-to-peru
+; ... the given tag will be added to all entries in between the pushtag and poptag
+poptag  #trip-to-peru</textarea></pre>
+
+### Comments
+
+<pre><textarea is="beancount-textarea">
+; inline comments begin with a semi-colon
+* any line not starting with a valid directive is also ignored silently</textarea></pre>

rustfava/help/budgets.md

@@ -0,0 +1,31 @@
+# Budgets
+
+Budgets on a per-account basis can be added via `custom` directives in the
+Beancount file:
+
+<pre><textarea is="beancount-textarea">
+2012-01-01 custom "budget" Expenses:Coffee       "daily"         4.00 EUR
+2013-01-01 custom "budget" Expenses:Books        "weekly"       20.00 EUR
+2014-02-10 custom "budget" Expenses:Groceries    "monthly"      40.00 EUR
+2015-05-01 custom "budget" Expenses:Electricity  "quarterly"    85.00 EUR
+2016-06-01 custom "budget" Expenses:Holiday      "yearly"     2500.00 EUR</textarea></pre>
+
+If budgets are specified, rustfava's reports and charts will display remaining
+budgets and related information.
+
+The budget directives can be specified `daily`, `weekly`, `monthly`, `quarterly`
+and `yearly`. The specified budget is valid until another budget directive for
+the account is specified. The budget is broken down to a daily budget, and
+summed up for a range of dates as needed.
+
+This makes the budgets very flexible, allowing for a monthly budget, being taken
+over by a weekly budget, and so on.
+
+Rustfava displays budgets in both charts and reports. You can find a visualization
+of the global budget in the `Net Profit` and `Expenses` charts for the Income
+Statement report.
+
+The Income Statement report is a good starting point for getting access to the
+full budget information in rustfava. The `Changes` charts visualize the data. The
+`Changes (monthly)` and `Balances (monthly)` reports show, respectively, the
+monthly and cumulative (over the selected period) budgets.