rustfava 0.1.0__py3-none-any.whl

rustfava/help/conversion.md

@@ -0,0 +1,29 @@
+# Conversion
+
+In most reports in rustfava, a conversion can be selected with the select dropdown
+at the top of the chart. These conversions will use the prices defined in the
+Beancount file, so these should defined manually or by some plugin (using
+`beancount.plugins.implicit_prices` is recommend to get prices for all costs in
+the Beancount file).
+
+- "At Cost" - Show all inventories at cost, e.g., a position of
+  `10 STOCK {4 USD}` would be converted to `40 USD`.
+- "At Market Value" - Show all inventories at their current market value, that
+  is, convert to the cost currency at the current price. E.g., a position of
+  `10 STOCK {4 USD}` would be converted to `50 USD` if the current price of
+  `STOCK` is `5 USD`.
+- "Units" - The plain units of all positions, e.g., `10 STOCK` for a position of
+  `10 STOCK {4 USD}`.
+- "Converted to X" - Convert to the currency `X`, e.g., a position of
+  `10 STOCK {4 USD}` would be converted to `20 X` if the current price of
+  `STOCK` is `2 X`. For positions with a price, a conversion via the cost
+  currency is attempted if no direct price exists, so the example position would
+  also successfully be converted if no price for `STOCK` in `X` exists but both
+  a price of `STOCK` in `USD` and a price of `X` in `USD` exists.
+- "Converted to X,Y" - It is also possible to chain conversions to currencies by
+  selecting multiple conversions in the dropdown. These conversions are done in
+  sequence, a position of `10 STOCK {4 USD}` would first be converted to `X` and
+  then this amount in `X` would be converted to `Y`.
+
+None of the conversions will silently drop amounts, so if a conversion is not
+possible, the un-converted units are shown.

rustfava/help/extensions.md

@@ -0,0 +1,111 @@
+# Extensions
+
+Rustfava supports extensions. Extensions allow you to register hooks and generate
+your own report pages.
+
+If you use this extension system and need it to do more or need other hooks,
+please open an issue on [GitHub](https://github.com/rustledger/rustfava/issues).
+
+A rustfava extension is simply a Python module which contains a class that inherits
+from `RustfavaExtensionBase` from `rustfava.ext`. Invoking an extension is done via the
+`fava-extension` option in the beancount file. Check out `rustfava.ext.auto_commit`
+for an example.
+
+Extensions may also contain a report - this is detected when the extension's
+class has a `report_title` attribute. The template for the report should be in a
+`templates` subdirectory with a report matching the class's name. For example,
+check out `rustfava.ext.portfolio_list` which has its template located at
+`rustfava/ext/portfolio_list/templates/PortfolioList.html`.
+
+Finally, extensions may contain a Javascript module to be loaded in the
+frontend. The module should be in a Javascript file matching the class's name
+and the extension should have its `has_js_module` attribute set to `True`. The
+module can define functions to be called when different events happen. Take a
+look at `rustfava/ext/portfolio_list/PortfolioList.js` for an example. Currently,
+the following events/functions can be specified:
+
+- `init`: is called when a rustfava report is first opened
+- `onPageLoad`: Is called when any page in rustfava is loaded (so on first open and
+  on any further navigation).
+- `onExtensionPageLoad`: Is called when the extension report is loaded.
+
+The whole extension system should be considered unstable and it might change
+drastically.
+
+## Rustfava Extension Setup Options
+
+______________________________________________________________________
+
+## `fava-extension`
+
+A Python module to load as extension. The path of the Beancount file is searched
+in addition to anything on the Python path. Single python files will also be
+searched - so for example a `my_extension.py` could be used by giving
+`my_extension`. Note that Python has a global namespace for currently loaded
+modules, so try avoiding simple names that might coincide with some Python
+library (as well as running rustfava on two files that have different extensions of
+the same name).
+
+Extensions allow for an optional configuration options string, whose structure
+is specified by the individual extension.
+
+<pre><textarea is="beancount-textarea">
+2010-01-01 custom "fava-extension" "extension-name"
+2010-01-01 custom "fava-extension" "extension-with-options" "{'option': 'config_value'}"</textarea></pre>
+
+______________________________________________________________________
+
+## Hooks
+
+Below is a list of all current hooks.
+
+### `after_load_file()`
+
+Called after a ledger file has been loaded. Use the `self.ledger` object to
+access the ledger data.
+
+______________________________________________________________________
+
+### `before_request()`
+
+Called when starting to process a request. Use Flask’s `request` object to
+access the request being processed (`from flask import request`).
+
+______________________________________________________________________
+
+### `after_write_source(path: str, source: str)`
+
+Called after the string `source` has been written to the Beancount file at
+`path`.
+
+______________________________________________________________________
+
+### `after_insert_metadata(entry: Directive, key: str, value: str)`
+
+Called after metadata (`key: value`) has been added to an `entry`.
+
+______________________________________________________________________
+
+### `after_insert_entry(entry: Directive)`
+
+Called after an `entry` has been inserted.
+
+______________________________________________________________________
+
+### `after_entry_modified(entry: Directive, new_lines: str)`
+
+Called after an `entry` has been modified, e.g., via the context popup.
+
+______________________________________________________________________
+
+### `after_delete_entry(entry: Directive)`
+
+Called after an `entry` has been deleted, e.g., via the context popup.
+
+______________________________________________________________________
+
+## Extension attributes
+
+### `report_title`
+
+Optional attribute to set extension report title used in the sidebar.

rustfava/help/features.md

@@ -0,0 +1,179 @@
+# rustfava's features
+
+This is an overview of some of the more advanced features that rustfava has to
+offer.
+
+## Editor
+
+The [editor](../editor) provides a convenient way to edit the source file. If
+you want to use a file different from the main file to be opened by default, use
+the [`default-file`](./options#default-file) option. If you have
+[`insert-entry`](./options#insert-entry) options set, the cursor will by default
+jump to the (date-wise) latest one in the opened file.
+
+The editor supports auto-completion for various entities, e.g., account names,
+payees, and tags. Trailing whitespace is highlighted in red. The Tab key in the
+editor can be used for indentation - to escape this keyboard trap, press Escape
+and then Tab directly after it.
+
+## Queries
+
+On the [Query](../query/) report you can execute queries using the Beancount
+Query Language (BQL). Rustfava uses rustledger's built-in query engine. For an
+explanation of how BQL queries work, see the
+[Beancount Query Language Reference](http://furius.ca/beancount/doc/query).
+
+Rustfava displays charts for BQL queries - if they have exactly two columns like the
+following example with the first being a date or string and the second an
+inventory, then a line chart or treemap chart is shown on the query page.
+
+```
+SELECT
+    payee,
+    SUM(COST(position)) AS balance
+WHERE
+    account ~ 'Expenses'
+GROUP BY payee, account
+```
+
+Rustfava supports downloading the result of these queries in various file formats.
+By default, only exporting to `csv` is supported. For support of `xlsx` and
+`ods`, install rustfava with the `excel` feature:
+
+```
+uv pip install rustfava[excel]
+```
+
+## Adding Transactions
+
+By clicking the `+` button or using the `n` keyboard shortcut you can open a
+form to insert a transaction to your Beancount file. The position that
+transactions are inserted at can be specified in a flexible way using the
+[`insert-entry`](./options#insert-entry) option. If you want to set a bookmark
+to this form, adding `#add-transaction` to any URL in rustfava will open it on load.
+Tags and links can be added in the form by adding them (separated by spaces) to
+the narration field, e.g., `narration #tag ^somelink`.
+
+## Up-to-date indicators
+
+Rustfava offers colored indicators that can help you keep your accounts up-to-date.
+They are shown next to accounts that have the metadata
+`fava-uptodate-indication: TRUE` set on their Open directive. The colors have
+the following meaning:
+
+- green: The last entry for this account is a balance check that passed.
+- red: The last entry is a balance check that failed.
+- yellow: The last entry is not a balance check.
+
+In addition, a grey dot will be shown if the account has not been updated in a
+while, as configured by the `uptodate-indicator-grey-lookback-days` option.
+
+## Displaying only relevant accounts
+
+To help display only the most relevant subset of accounts when managing a large
+number or a deep hierarchy of accounts, Rustfava offers the following options:
+
+- `show-closed-accounts`
+- `show-accounts-with-zero-balance`
+- `show-accounts-with-zero-transactions`
+- `collapse-pattern`
+
+## Opening an external editor
+
+Rustfava can open up your source file in your favorite editor directly from the web
+interface using the `use-external-editor` configuration variable through the
+`beancount://` URL handler. See the
+[Beancount urlscheme](https://github.com/aumayr/beancount_urlscheme) project for
+pre-configured URL handlers for macOS and Cygwin.
+
+## Multiple Beancount files
+
+When you start rustfava specifying multiple Beancount files, you can click the
+Beancount file name on the top left to switch between the files.
+
+## Custom links in the sidebar
+
+If you regularly use certain views in rustfava with different filters, you can put
+links to them in the sidebar. Custom links can be put in the Beancount file,
+utilizing the `custom` directive:
+
+```
+2016-05-04 custom "fava-sidebar-link" "Income 2014" "../income_statement?time=2014"
+```
+
+`"fava-sidebar-link"` specifies that this directive is for a custom sidebar
+link, followed by the title to display in the sidebar (`"Income 2014"` in this
+example), and finally the URL to link to. The URL can be relative, like in the
+example above, or absolute, even linking to an external site.
+
+Two frequently used custom links are for showing all Documents and all Notes
+found in the journal:
+
+- For all Documents: `/<slug>/journal/?show=document`
+- For all Notes: `/<slug>/journal/?show=note`
+
+There is a special URL handler `/jump` which can be used to jump to the current
+page with given URL parameters. For example, `/jump?time=month` will show the
+current page but change the time filter to the current month.
+
+## Language
+
+You can change the language of the interface by specifying the
+[`language`](./options#language) option. If no option is specified, rustfava tries
+to guess the language from your browser settings.
+
+## Documents upload
+
+One or more documents can be uploaded by drag and drop on account names or
+Journal rows.
+
+### Uploading documents
+
+To store a document in a specific account, just drag and drop the file on the
+account name in a tree-table.
+
+While still dragging, the background-color of the account name will switch to
+blue, indicating that you can drop a file there.
+
+Once dropped, a popup will be shown where you can rename the file before
+storing. If the filename does not already start with a date (`YYYY-MM-DD`), the
+current date will be added as a prefix automatically.
+
+The file will be then stored in your Beancount documents folder, in a sub-folder
+named after the account. You can set the path to the Beancount documents folder
+by specifying the `option "documents" "/Users/test/invoices"`-option (absolute
+or relative to your Beancount file) in your Beancount file.
+
+Beancount will automatically discover files in your `"documents"`-folders and
+generate Document entries for them.
+
+When enabling the `tag_discovered_documents`-plugin, these Document entries will
+be tagged with `#discovered` and can be filtered in the Journal:
+
+```
+plugin "rustfava.plugins.tag_discovered_documents"
+```
+
+### Uploading statements
+
+When dropping a file on a transaction (or one of its postings) in the Journal,
+the file will be uploaded as described above, and a `document`-metadata-entry
+inserted for the transaction in your Beancount file.
+
+When dropped on the description the subfolder corresponds to the account of the
+first posting.
+
+**Note**: Uploading statements modifies your Beancount file!
+
+When enabling the `link_documents`-plugin, the Document entries created by
+Beancount (see above) will be tagged with `#linked`, linked to the corresponding
+transaction and can be filtered in the Journal:
+
+```
+plugin "rustfava.plugins.link_documents"
+```
+
+### Exporting
+
+The entries that are currently shown in rustfava, with filters applied, can be
+downloaded in Beancount format by clicking the ⬇ (Export) button in the sidebar.

rustfava/help/filters.md

@@ -0,0 +1,103 @@
+# Filters
+
+With the text inputs at the top right of the page, you can filter the entries
+that are displayed in rustfava's reports. If you use multiple filters, the entries
+matching all of them will be selected.
+
+## Time
+
+Filter entries by their date. You can specify dates and intervals like years,
+quarters, months, weeks, and days (for example `2015`, `2012-Q1`, `2010-10`,
+`2016-W12`, or `2015-06-12`). You can specify a range of dates like
+`2010 - 2012-10` which will display all entries between the start of 2010 and
+the end of October 2012.
+
+To refer to dates relative to the current day, you can use the variables `year`,
+`quarter`, `month`, `week`, and `day`. These will be substituted with the
+current date expressed in the respective format, and support addition and
+subtraction. For example you can write `year - day` for all entries in the
+current year up to today, or `year-1 - year` for all entries of the last and
+current year. To prevent subtraction, use parentheses: `(month)-10` refers to
+the 10th of this month, whereas `month-10` would be 10 months ago.
+
+### Summarisation of previous balances and conversions
+
+When setting a time filter, rustfava does not just filter to the transactions in the
+interval but also summarises transactions in the following ways (using
+Beancount's "clamp" summarisation):
+
+- All balances for the Income and Expenses accounts previous to the filtered
+  period are transferred to the `account_previous_earnings` ("retained
+  earnings") account and all of the other transactions before begin date are
+  summarised against the `account_previous_balances` account (usually "opening
+  balances"). So the Income and Expenses start with a balance of zero whereas
+  Assets and Liabilities accounts start with their accumulated balance.
+- All the entries after the end date are removed.
+- A conversion entry is added to the `account_current_conversions` account for
+  the changes occurring within the filtered period.
+
+### ISO 8601 Week dates
+
+The week-based calendar follows
+[ISO 8601 week-numbering system](https://en.wikipedia.org/wiki/ISO_week_date)
+with each week starting on Mondays and the first week of the ISO week-based year
+being the first week that has the majority of its days in January. Equivalently,
+it is also the week to containing January 4th.
+
+Some examples where the ISO week-based calendar differs from the Gregorian
+calendar:
+
+- Week 1 of 2025 starts on Monday 30 December 2024 and ends on Sunday 5 January
+  2025\. As a result, 30 December 2024 belongs to the year 2025 of the ISO
+  week-based calendar, despite being in the year 2024 of the Gregorian calendar.
+- Week 53 of 2020 ends on Sunday 3 January 2021. As a result, 3 January 2021
+  belongs to the year 2020 of the ISO week-based calendar, despite being in the
+  year 2021 of the Gregorian calendar.
+
+Most years of ISO week-based calendars have 52 weeks, but as there are slightly
+more than 52 weeks in a year, some years contain a 53rd week.
+
+## Account
+
+Filter entries by account, matching any entry this account is part of. The
+filter can be an account name, either the full account name or a component of
+the account name, or a regular expression matching the account name, e.g.
+`.*Company.*` to filter for all that contain `Company`.
+
+## Filter by tag, link, payee and other metadata
+
+This final filter allows you to filter entries by various attributes.
+
+- Filter by `#tag` or `^link`.
+- Filter by amount, such as `= 100.20` or `>= 100` (comparing the absolute of
+  the units).
+- Filter by any entry attribute, such as payee `payee:"restaurant"` or narration
+  `narration:'Dinner with Joe'`. The argument is a regular expression which
+  needs to be quoted (with `'` or `"`) if it contains spaces or special
+  characters. If the argument is not a valid regular expression, rustfava will look
+  for an exact match instead.
+- Search in payee and narration if no specific entry attribute is given, e.g.
+  `"Cash withdrawal"`. For Note directives, the comment will be searched.
+- Filter for entries having certain metadata values: `document:"\.pdf$"`. Note
+  that if the entry has an attribute of the same name as the metadata key, the
+  filter will apply to the entry attribute, not the metadata value.
+- Exclude entries that match a filter by prepending a `-` to it, e.g. `-#tag` or
+  `-(^link #tag)`.
+- To match entries by posting attributes, you can use `any()` and `all()`, e.g.,
+  `any(id:'12', account:"Cash$")` for all entries that have at least one posting
+  with metadata `id: 12` or account ending in `Cash`, or
+  `all(-account:"^Expenses:Food")` to exclude all transactions having a posting
+  to the Expenses:Food account. To match by amount, you can use comparison
+  operators, e.g. `any(units > 80)` to filter for all entries where one posting
+  has a units with an absolute amount greater than 80.
+
+These filters can be combined by separating them by spaces to match all entries
+satisfying all given filters or by commas to match all entries satisfying at
+least one of the given filters. In other words, a space acts like an "and" and a
+comma like an "or". As usual, the logical "and" has a higher grouping power than
+"or" and you can use parentheses to group filters.
+
+When given regular expressions, Rustfava checks for a match anywhere in the
+corresponding attribute. Matching is always case-insensitive. To find out more
+about the specific syntax rustfava uses, refer to
+[Python's Regular Expression Syntax](https://docs.python.org/3/library/re.html?highlight=match#regular-expression-syntax).

rustfava/help/import.md

@@ -0,0 +1,27 @@
+# Import
+
+Rustfava can use Beancount's import system to semi-automatically import entries into
+your ledger. See [Importing External Data in Beancount](http://furius.ca/beancount/doc/ingest)
+for more information on how to write importers.
+
+**Note**: Import functionality requires the beancount compatibility package.
+Install it with: `uv pip install rustfava[beancount-compat]`
+
+You can override the hooks that should be run for your importers by specifying a
+variable `HOOKS` with a list of hooks to apply to the list of
+`(filename: str, entries: list[Directive])` tuples. If you want to use
+beangulp-style hooks that take lists of
+`(filename: str, entries: list[Directive], account: str, importer: Importer)`-tuples,
+you can annotate them with the appropriate Python types which rustfava will detect
+and call with these 4-tuples.
+
+Set the `import-config` option to point to your import config and set
+`import-dirs` to the directories that contain the files that you want to import.
+And if you wish to save new entries elsewhere than main file - use
+`insert-entry` option.
+
+Rustfava currently only supports entries of type `Transaction`, `Balance`, and
+`Note`. Set the special metadata key `__source__` to display the corresponding
+text (CSV-row, XML-fragment, etc.) for the entry in the list of entries to
+import. Note that this metadata (and all other metadata keys starting with an
+underscore) will be stripped before saving the entry to file.