rustfava 0.1.0__py3-none-any.whl

rustfava/help/options.md

@@ -0,0 +1,289 @@
+# Options
+
+To customize some of rustfava's behaviour, you can add custom entries like the
+following to your Beancount file.
+
+<pre><textarea is="beancount-textarea">
+2016-06-14 custom "fava-option" "default-file"
+2016-04-14 custom "fava-option" "auto-reload" "true"
+2016-04-14 custom "fava-option" "currency-column" "100"</textarea></pre>
+
+Below is a list of all possible options for rustfava.
+
+______________________________________________________________________
+
+## `language`
+
+Default: Not set
+
+If this setting is not specified, rustfava will try to guess the language from your
+browser settings. Rustfava currently ships translations into the following
+languages:
+
+- Bulgarian (`bg`)
+- Catalan (`ca`)
+- Chinese (`zh_CN` and `zh_TW`)
+- Dutch (`nl`)
+- English (`en`)
+- French (`fr`)
+- German (`de`)
+- Japanese (`ja`)
+- Persian (`fa`)
+- Portuguese (`pt` and `pt_BR`)
+- Russian (`ru`)
+- Slovak (`sk`)
+- Spanish (`es`)
+- Swedish (`sv`)
+- Ukrainian (`uk`)
+
+______________________________________________________________________
+
+## `locale`
+
+Default: Not set or `en` if the Beancount `render_commas` option is set.
+
+This sets the locale that is used to render out numbers. For example, with the
+locale `en_IN` the number `1111111.33` will be rendered `11,11,111.33`,
+`1,111,111.33` with locale `en`, or `1.111.111,33` with locale `de`.
+
+______________________________________________________________________
+
+## `default-file`
+
+Use this option to specify a default file for the editor to open. This option
+may optionally take a value of a filename to be the default. If you don't
+provide a filename, the file this custom option is in is used.
+
+______________________________________________________________________
+
+## `default-page`
+
+Default: `income_statement/`
+
+Use this option to specify the page to be redirected to when visiting rustfava. If
+this option is not specified, you are taken to the income statement. You may
+also use this option to set filters. For example, a `default-page` of
+`balance_sheet/?time=year-2+-+year` would result in you being redirected to a
+balance sheet reporting the current year and the two previous years.
+
+Note that the supplied path is relative. It is probably easiest to navigate to
+the URL in your browser and copy the portion of the URL after the 'title' of
+your beancount file into this option.
+
+______________________________________________________________________
+
+## `fiscal-year-end`
+
+Default: `12-31`
+
+The last day of the fiscal (financial or tax) period for accounting purposes in
+`%m-%d` format. Allows for the use of `FY2018`, `FY2018-Q3`, `fiscal_year` and
+`fiscal_quarter` in the time filter, and `FY2018` as the start date, end date,
+or both dates in a date range in the time filter. Month can be a value larger
+than `12` to have `FY2018` end in 2019 for example.
+
+Examples are:
+
+- `04-05` - UK
+- `06-30` - Australia / NZ
+- `09-30` - US federal government
+- `15-31` - Japan
+
+See [Fiscal Year on WikiPedia](https://en.wikipedia.org/wiki/Fiscal_year) for
+more examples.
+
+______________________________________________________________________
+
+## `indent`
+
+Default: 2.
+
+The number spaces for indentation.
+
+______________________________________________________________________
+
+## `insert-entry`
+
+Default: Not set.
+
+This option can be used to specify where entries are inserted. The argument to
+this option should be a regular expression matching account names. This option
+can be given multiple times. When adding an entry, the account of the entry (for
+a transaction, the account of the last posting is used) is matched against all
+`insert-entry` options and the entry will be inserted before the datewise latest
+of the matching options before the entry date. If the entry is a Transaction and
+no `insert-entry` option matches the account of the last posting the account of
+the second to last posting and so on will be tried. If no `insert-entry` option
+matches or none is given, the entry will be inserted at the end of the default
+file.
+
+______________________________________________________________________
+
+## `auto-reload`
+
+Default: `false`
+
+Set this to `true` to make rustfava automatically reload the page whenever a file
+changes is detected. By default only a notification is shown which you can click
+to reload the page. If the file change is due to user interaction, e.g.,
+uploading a document or adding a transaction, rustfava will always reload the page
+automatically.
+
+______________________________________________________________________
+
+## `unrealized`
+
+Default: `Unrealized`
+
+The subaccount of the Equity account to post unrealized gains to if the account
+trees are shown at market value.
+
+______________________________________________________________________
+
+## `currency-column`
+
+Default: `61`
+
+This option can be used to configure how posting lines are aligned when saved to
+file or when using 'Align Amounts' in the editor. rustfava tries to align so that
+the currencies all occur in the given column. Also, rustfava will show a vertical
+line before this column in the editor.
+
+______________________________________________________________________
+
+## `sidebar-show-queries`
+
+Default: `5`
+
+The maximum number of queries to link to in the sidebar. Set this value to `0`
+to hide the links altogether.
+
+______________________________________________________________________
+
+## `upcoming-events`
+
+Default: `7`
+
+Show a notification bubble in the sidebar displaying the number of events less
+than `upcoming-events` days away. Set this value to `0` to disable this feature.
+
+______________________________________________________________________
+
+## `show-closed-accounts`
+
+Default: `false`
+
+## `show-accounts-with-zero-transactions`
+
+Default: `true`
+
+## `show-accounts-with-zero-balance`
+
+Default: `true`
+
+These three options specify which accounts (not) to show in the account trees,
+like on the income statement. Accounts with a non-zero balance will always be
+shown.
+
+______________________________________________________________________
+
+## `collapse-pattern`
+
+Default: Not set
+
+This option is used to specify accounts that will be collapsed in the displayed
+account trees. The argument to this option is a regular expression matching
+account names. This option can be specified multiple times.
+
+Collapsing all accounts below a specific depth in the account tree can be
+accomplished by a regex such as: `.*:.*:.*` (this example collapses all accounts
+that are three levels deep).
+
+______________________________________________________________________
+
+## `use-external-editor`
+
+Default: `false`
+
+If `true`, instead of using the internal editor, the `beancount://` URL scheme
+is used. See the
+[Beancount urlscheme](https://github.com/aumayr/beancount_urlscheme) project for
+details.
+
+______________________________________________________________________
+
+## `account-journal-include-children`
+
+Default: `true`
+
+This determines if the journal in the account report includes entries of
+sub-accounts.
+
+______________________________________________________________________
+
+## `uptodate-indicator-grey-lookback-days`
+
+Default: `60`
+
+If there has been no activity in given number of days since the last balance
+entry, then the grey uptodate-indicator is shown.
+
+______________________________________________________________________
+
+## `import-config`
+
+Default: Not set
+
+Path to a Beancount import configuration file. See the [Import](./import) help
+page for details.
+
+______________________________________________________________________
+
+## `import-dirs`
+
+Default: Not set
+
+Set a directory to be scanned by the Beancount import mechanism. This option can
+be specified multiple times to add multiple directories.
+
+______________________________________________________________________
+
+## `invert-gains-losses-colors`
+
+Default: `false`
+
+By default, rustfava uses green for unrealized gains (positive values) and red for
+unrealized losses (negative values) in the Balance Sheet and Trial Balance when
+displaying at market value.
+
+Set this to `true` to invert the color scheme, using red for gains and green for
+losses. This is useful for users from regions where the opposite convention is
+used, such as Chinese stock markets where red represents gains and green
+represents losses.
+
+______________________________________________________________________
+
+## `invert-income-liabilities-equity`
+
+Default: False
+
+In Beancount the Income, Liabilities and Equity accounts tend to have a negative
+balance (see
+[Types of Accounts](https://beancount.github.io/docs/the_double_entry_counting_method.html#types-of-accounts)).
+
+This rustfava option flips the sign of these three accounts in the income statement
+and the balance sheet. This way, the net profit chart will show positive numbers
+if the income is greater than the expenses for a given timespan.
+
+Note: To keep consistency with the internal accounting of beancount, the journal
+and the individual account pages are not affected by this configuration option.
+
+______________________________________________________________________
+
+## `conversion-currencies`
+
+Default: Not set
+
+When set, the currency conversion select dropdown in all charts will show the
+list of currencies specified in this option. By default, rustfava lists all
+operating currencies and those currencies that match ISO 4217 currency codes.

rustfava/helpers.py

@@ -0,0 +1,30 @@
+"""Exceptions and module base class."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover
+    from rustfava.beans.abc import Directive
+    from rustfava.beans.abc import Meta
+
+
+@dataclass(frozen=True, slots=True)
+class BeancountError:
+    """Dataclass for a Beancount-style error."""
+
+    source: Meta | None
+    message: str
+    entry: Directive | None
+
+
+class RustfavaAPIError(Exception):
+    """Fava's base exception class."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__()
+        self.message = message
+
+    def __str__(self) -> str:
+        return self.message

rustfava/internal_api.py

@@ -0,0 +1,221 @@
+"""Internal API.
+
+This is used to pre-process some data that is used in the templates, allowing
+this part of the functionality to be tested and allowing some end-to-end tests
+for the frontend data validation.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from flask import current_app
+from flask import url_for
+from flask_babel import gettext
+
+from rustfava.context import g
+from rustfava.util.excel import HAVE_EXCEL
+
+if TYPE_CHECKING:  # pragma: no cover
+    from collections.abc import Sequence
+    from typing import Literal
+
+    from rustfava.beans.abc import Meta
+    from rustfava.beans.abc import Query
+    from rustfava.core.accounts import AccountDict
+    from rustfava.core.charts import DateAndBalance
+    from rustfava.core.charts import DateAndBalanceWithBudget
+    from rustfava.core.extensions import ExtensionDetails
+    from rustfava.core.fava_options import RustfavaOptions
+    from rustfava.core.tree import SerialisedTreeNode
+    from rustfava.helpers import BeancountError
+    from rustfava.util.date import Interval
+
+
+@dataclass(frozen=True)
+class SerialisedError:
+    """A Beancount error, as passed to the frontend."""
+
+    type: str
+    source: Meta | None
+    message: str
+
+    @staticmethod
+    def from_beancount_error(err: BeancountError) -> SerialisedError:
+        """Get a serialisable error from a Beancount error."""
+        source = dict(err.source) if err.source is not None else None
+        if source is not None:
+            source.pop("__tolerances__", None)
+        return SerialisedError(err.__class__.__name__, source, err.message)
+
+
+@dataclass(frozen=True)
+class LedgerData:
+    """This is used as report-independent data in the frontend."""
+
+    accounts: Sequence[str]
+    account_details: AccountDict
+    base_url: str
+    currencies: Sequence[str]
+    currency_names: dict[str, str]
+    errors: Sequence[SerialisedError]
+    fava_options: RustfavaOptions
+    incognito: bool
+    have_excel: bool
+    links: Sequence[str]
+    options: dict[str, str | Sequence[str]]
+    payees: Sequence[str]
+    precisions: dict[str, int]
+    tags: Sequence[str]
+    years: Sequence[str]
+    user_queries: Sequence[Query]
+    upcoming_events_count: int
+    extensions: Sequence[ExtensionDetails]
+    sidebar_links: Sequence[tuple[str, str]]
+    other_ledgers: Sequence[tuple[str, str]]
+
+
+def get_errors() -> list[SerialisedError]:
+    """Serialise errors (do not pass entry as that might fail serialisation."""
+    return [SerialisedError.from_beancount_error(e) for e in g.ledger.errors]
+
+
+def _get_options() -> dict[str, str | Sequence[str]]:
+    options = g.ledger.options
+    return {
+        "documents": options["documents"],
+        "filename": options["filename"],
+        "include": options["include"],
+        "operating_currency": options["operating_currency"],
+        "title": options["title"],
+        "name_assets": options["name_assets"],
+        "name_liabilities": options["name_liabilities"],
+        "name_equity": options["name_equity"],
+        "name_income": options["name_income"],
+        "name_expenses": options["name_expenses"],
+    }
+
+
+def get_ledger_data() -> LedgerData:
+    """Get the report-independent ledger data."""
+    ledger = g.ledger
+    all_queries = ledger.all_entries_by_type.Query
+
+    return LedgerData(
+        ledger.attributes.accounts,
+        ledger.accounts,
+        url_for("index"),
+        ledger.attributes.currencies,
+        ledger.commodities.names,
+        get_errors(),
+        ledger.fava_options,
+        current_app.config["INCOGNITO"],
+        HAVE_EXCEL,
+        ledger.attributes.links,
+        _get_options(),
+        ledger.attributes.payees,
+        ledger.format_decimal.precisions,
+        ledger.attributes.tags,
+        ledger.attributes.years,
+        all_queries[: ledger.fava_options.sidebar_show_queries],
+        len(ledger.misc.upcoming_events),
+        ledger.extensions.extension_details,
+        ledger.misc.sidebar_links,
+        [
+            (ledger.options["title"], url_for("index", bfile=file_slug))
+            for (file_slug, ledger) in current_app.config["LEDGERS"].items()
+            if file_slug != g.beancount_file_slug
+        ],
+    )
+
+
+@dataclass(frozen=True)
+class BalancesChart:
+    """Data for a balances chart."""
+
+    label: str
+    data: Sequence[DateAndBalance]
+    type: Literal["balances"] = "balances"
+
+
+@dataclass(frozen=True)
+class BarChart:
+    """Data for a bar chart."""
+
+    label: str
+    data: Sequence[DateAndBalanceWithBudget]
+    type: Literal["bar"] = "bar"
+
+
+@dataclass(frozen=True)
+class HierarchyChart:
+    """Data for a hierarchy chart."""
+
+    label: str
+    data: SerialisedTreeNode
+    type: Literal["hierarchy"] = "hierarchy"
+
+
+if TYPE_CHECKING:  # pragma: no cover
+    ChartData = BalancesChart | BarChart | HierarchyChart
+
+
+class ChartApi:
+    """Functions to generate chart data."""
+
+    @staticmethod
+    def account_balance(account_name: str) -> ChartData:
+        """Generate data for an account balances chart."""
+        return BalancesChart(
+            gettext("Account Balance"),
+            g.ledger.charts.linechart(
+                g.filtered,
+                account_name,
+                g.conv,
+            ),
+        )
+
+    @staticmethod
+    def hierarchy(
+        account_name: str,
+        *,
+        label: str | None = None,
+    ) -> ChartData:
+        """Generate data for an account hierarchy chart."""
+        return HierarchyChart(
+            label or account_name,
+            g.ledger.charts.hierarchy(
+                g.filtered,
+                account_name,
+                g.conv,
+            ),
+        )
+
+    @staticmethod
+    def interval_totals(
+        interval: Interval,
+        account_name: str | tuple[str, ...],
+        label: str | None = None,
+        *,
+        invert: bool = False,
+    ) -> ChartData:
+        """Generate data for an account per interval chart."""
+        return BarChart(
+            label or str(account_name),
+            g.ledger.charts.interval_totals(
+                g.filtered,
+                interval,
+                account_name,
+                g.conv,
+                invert=invert,
+            ),
+        )
+
+    @staticmethod
+    def net_worth() -> ChartData:
+        """Generate data for net worth chart."""
+        return BalancesChart(
+            gettext("Net Worth"),
+            g.ledger.charts.net_worth(g.filtered, g.interval, g.conv),
+        )