Ako Python skripty automatizujú Beancount a Fava

Beancount (nástroj na účtovníctvo v čistom texte s podvojným zápisom) a Fava (jeho webové rozhranie) sú vysoko rozšíriteľné a skriptovateľné. Ich dizajn vám umožňuje automatizovať finančné úlohy, generovať vlastné výkazy a nastavovať upozornenia písaním Python skriptov. Podľa slov jedného používateľa, „Naozaj sa mi páči mať svoje dáta v takom pohodlnom formáte a páči sa mi, že môžem automatizovať veci podľa svojho gusta. Neexistuje API ako súbor na vašom disku; je ľahké ho integrovať." Táto príručka vás prevedie vytváraním skriptovateľných pracovných postupov – od automatizácie vhodnej pre začiatočníkov až po pokročilé pluginy pre Fava.

Preskúmajte ukážkový ledger naživo:

Začnite s príkazovým riadkom bea​

Predtým, než napíšete akýkoľvek Python, overte, či bea už danú úlohu nezvládne. Validuje ledger, spúšťa BQL dotazy, vytvára štyri finančné výkazy a importuje bankové exporty, a globálny parameter --json premení každý z nich na parsovateľný obal, ktorý môže váš shell prepípať do jq. Jeho návratové kódy sú kontraktom, na ktorom sa vetví naplánovaná úloha, takže cron alebo CI nepotrebuje žiadny načítavací skript. Pozrite si automatizácia účtovníctva pomocou bea ohľadne rozlíšenia cieľa, obalu a vetvenia podľa návratových kódov, a vráťte sa sem, keď budete potrebovať vlastný výpočet, ktorý CLI neposkytuje.

Začíname: Spúšťanie Beancount ako Python skriptu​

Pre nižšie uvedené vlastné Python skripty nainštalujte skriptovacie knižnice (pip install beancount beanquery beangulp). Pracovné postupy príkazu bea používajú namiesto toho spravovaný engine; nainštalujte ho podľa rýchleho štartu CLI. Keďže Beancount je napísaný v Pythone, môžete ho použiť ako knižnicu vo svojich vlastných skriptoch. Skripty nižšie boli spustené s Beancount 3.2.3, beanquery 0.2.0 a beangulp 0.2.0. Všeobecný postup je:

• Načítajte svoj Beancount ledger: Použite loader Beancount na sparsovanie súboru .beancount do Python objektov. Napríklad:

  from beancount import loader
  entries, errors, options = loader.load_file("myledger.beancount")
  if errors:
      for error in errors:
          print(error)
      raise SystemExit(1)

  Loader vracia záznamy a chyby spolu. Nevyvážený alebo neplatný súbor stále vracia záznamy, takže skontrolujte errors a zastavte sa predtým, než budete dôverovať dátam. Všetky vaše účty, transakcie a zostatky sú teraz dostupné v kóde.

• Využite Beancount Query Language (BQL): Namiesto manuálneho iterovania môžete spúšťať dotazy podobné SQL na dátach. Dotazy žijú v samostatnom balíku beanquery. V Beancount 3.2.3 neexistuje modul beancount.query. Napríklad na získanie celkových výdavkov po mesiacoch pripojte načítané záznamy a spustite dotaz priamo:

  import beanquery
   
  conn = beanquery.connect("beancount:", entries=entries, errors=errors, options=options)
  cur = conn.execute(
      "SELECT year, month, sum(position) WHERE account ~ 'Expenses' GROUP BY year, month"
  )
  for row in cur.fetchall():
      print(row)

  Toto používa beanquery na agregáciu dát. Je to ten istý engine, ktorý stojí za bea query, ale tu ho voláte v skripte. To sa vyhýba volaniu externého príkazu v slučke cez shell.

• Nastavte štruktúru projektu: Usporiadajte svoje skripty vedľa svojho ledgeru. Bežné usporiadanie má adresáre pre importery (na načítanie/parsovanie externých dát), výkazy alebo dotazy (pre analytické skripty) a dokumenty (na ukladanie stiahnutých výpisov). Napríklad jeden používateľ si udržiava:

  • importers/ – vlastné Python importné skripty (s testami),
  • queries/ – skripty na generovanie výkazov (spustiteľné cez python3 queries/...),
  • documents/ – stiahnuté bankové CSV/PDF usporiadané podľa účtu.

S týmto nastavením môžete skripty spúšťať manuálne (napr. python3 queries/cash_flow.py) alebo ich naplánovať (cez cron alebo task runner) na automatizáciu vášho pracovného postupu.

Automatizácia úloh zosúladenia​

Zosúlaďovanie znamená uistiť sa, že váš ledger zodpovedá externým záznamom (bankové výpisy, výpisy z kreditných kariet atď.). Beancount ledger v čistom texte a Python API umožňujú automatizovať veľkú časť tohto procesu.

Importovanie a párovanie transakcií (začiatočník)​

Pre začiatočníkov je odporúčaný prístup použiť importery zo samostatného balíka beangulp. Beancount 3 odstránil modul ingest v2 a jeho príkaz extract. Napíšete malú Python triedu, ktorá dedí z beangulp.Importer, na parsovanie daného formátu (CSV, OFX, PDF atď.) a vytvorenie transakcií. Zaregistrujte ju v krátkom ingest skripte a potom ju spustite cez bea ingest v spravovanom engine:

• Napíšte importer (Python triedu s metódami identify(), account() a extract()) pre formát CSV vašej banky.
• Pridajte ingest skript, ktorý registruje vaše importery. bea ingest spúšťa príkazy skriptu identify, extract a archive. Napríklad jeden pracovný postup spúšťa extract na všetkých súboroch v ~/Downloads a vypisuje transakcie do dočasného súboru.
• Manuálne skontrolujte a skopírujte transakcie z dočasného súboru do svojho hlavného ledgeru, potom spustite bea check, aby ste sa uistili, že zostatky sedia.

Minimálny príklad: statement.csv so stĺpcami date,description,amount, parsovaný týmto importerom (checking_importer.py):

import csv
import datetime
from beancount.core import data
from beancount.core.amount import Amount
from beancount.core.number import D
import beangulp
 
 
class CheckingImporter(beangulp.Importer):
    def identify(self, filepath: str) -> bool:
        return filepath.endswith("statement.csv")
 
    def account(self, filepath: str) -> str:
        return "Assets:Bank:Checking"
 
    def extract(self, filepath: str, existing):
        entries = []
        with open(filepath, newline="") as f:
            for row in csv.DictReader(f):
                date = datetime.date.fromisoformat(row["date"])
                amount = Amount(D(row["amount"]), "USD")
                meta = data.new_metadata(filepath, 0)
                entries.append(
                    data.Transaction(
                        meta, date, "*", None, row["description"],
                        data.EMPTY_SET, data.EMPTY_SET, [
                            data.Posting("Expenses:Food:Groceries", amount,
                                         None, None, None, None),
                            data.Posting("Assets:Bank:Checking",
                                         Amount(-amount.number, "USD"),
                                         None, None, None, None),
                        ]))
        return entries

Ingest skript (ingest.py) ho zapojí:

from checking_importer import CheckingImporter
from beangulp import Ingest
 
ingest = Ingest([CheckingImporter()])
 
if __name__ == "__main__":
    ingest()

Spustite ho proti stiahnutému súboru. Pre lokálne CSV nie sú potrebné žiadne prihlasovacie údaje. Najprv nainštalujte systémovú knižnicu libmagic. Jednorazový príkaz na povolenie stiahne Beangulp do spravovaného engine:

bea engine enable beangulp
bea ingest identify --config ingest.py statement.csv
bea ingest extract --config ingest.py statement.csv -o new.beancount

identify nahlási pre súbor checking_importer.CheckingImporter. extract zapíše transakcie vo formáte Beancount:

2024-01-08 * "Grocery Store"
  Expenses:Food:Groceries   120.00 USD
  Assets:Bank:Checking     -120.00 USD

Skontrolujte new.beancount, skopírujte záznamy do svojho hlavného ledgeru a spustite bea check.

Hoci tento proces stále zahŕňa krok kontroly, veľká časť otravnej práce s parsovaním a formátovaním záznamov je automatizovaná. Importné skripty tiež môžu automaticky priraďovať kategórie a dokonca nastavovať assertions zostatkov (vyhlásenia o očakávaných zostatkoch) na zachytenie nezrovnalostí. Napríklad po importe môžete mať riadok ako 2025-04-30 balance Assets:Bank:Checking 1234.56 USD, ktorý deklaruje konečný zostatok. Keď spustíte bea check, Beancount overí, že všetky tieto assertions zostatkov sú správne, a označí akékoľvek chyby, ak transakcie chýbajú alebo sú duplikované. To je osvedčený postup: automaticky generujte assertions zostatkov pre každé obdobie výpisu, aby počítač našiel nezrovnalosti za vás.

Vlastné skripty pre zosúladenie (stredne pokročilé)​

Pre väčšiu kontrolu môžete napísať vlastný Python skript na porovnanie zoznamu transakcií banky (CSV alebo cez API) so záznamami vo vašom ledgeri:

1. Načítajte externé dáta: Parsujte CSV súbor banky pomocou Python modulu csv (alebo Pandas). Normalizujte dáta na zoznam transakcií, napr. každú s dátumom, sumou a popisom.
2. Načítajte transakcie ledgeru: Použite loader.load_file, ako je uvedené vyššie, na získanie všetkých záznamov ledgeru. Filtrujte tento zoznam na účet, ktorý vás zaujíma (napr. váš bežný účet), a prípadne na rozsah dátumov výpisu.
3. Porovnajte a nájdite nezrovnalosti:

• Pre každú externú transakciu skontrolujte, či v ledgeri existuje identický záznam (zhoda podľa dátumu a sumy, možno popisu). Ak sa nenájde, označte ju ako „novú" a prípadne ju vypíšte ako transakciu vo formáte Beancount na vašu kontrolu.
• Naopak, identifikujte akékoľvek záznamy ledgeru na danom účte, ktoré sa neobjavujú v externom zdroji – môžu to byť chyby v zadávaní dát alebo transakcie, ktoré ešte neboli zúčtované bankou.

4. Vypíšte výsledky: Vytlačte výkaz alebo vytvorte nový úryvok .beancount s chýbajúcimi transakciami.

Ako príklad, komunitný skript s názvom reconcile.py robí presne toto: vzhľadom na Beancount súbor a vstupné CSV vypíše zoznam nových transakcií, ktoré by mali byť importované, ako aj akékoľvek existujúce záznamy v ledgeri, ktoré nie sú vo vstupe (čo môže byť znakom nesprávnej klasifikácie). S takýmto skriptom môže byť mesačné zosúlaďovanie také jednoduché, ako jeho spustenie a následné pripojenie navrhovaných transakcií k vášmu ledgeru. Jeden používateľ Beancount poznamenáva, že „vykonáva proces zosúlaďovania na všetkých účtoch každý mesiac" a používa rastúcu zbierku Python kódu na elimináciu veľkej časti manuálnej práce pri importe a zosúlaďovaní dát.

Tip: Počas zosúlaďovania využite nástroje Beancount na presnosť:

• Použite assertions zostatkov, ako je uvedené, na automatizované kontroly zostatkov účtov.
• Použite direktívu pad, ak je to žiaduce, ktorá môže automaticky vložiť vyrovnávacie záznamy pre malé rozdiely v zaokrúhľovaní (používajte opatrne).
• Píšte unit testy pre svoju logiku importu alebo zosúlaďovania (Beancount poskytuje testovacie pomocníky). Napríklad jeden pracovný postup zahŕňal vzatie vzorového CSV, napísanie zlyhávajúcich testov s očakávanými transakciami a potom implementáciu importeru, kým všetky testy neprešli. To zaručuje, že váš importný skript funguje správne pre rôzne prípady.

Generovanie vlastných správ a súhrnov​

Hoci Fava poskytuje mnoho štandardných výkazov (Výkaz ziskov a strát, Súvaha atď.), môžete vytvárať vlastné výkazy pomocou skriptov. Môžu sa pohybovať od jednoduchých konzolových výstupov až po bohato formátované súbory alebo grafy.

Získavanie údajov na vytváranie správ (začiatočník)​

Na základnej úrovni môžete použiť Beancount Query Language (BQL) na získanie súhrnných dát a ich tlač alebo uloženie. Napríklad:

• Súhrn peňažných tokov: Použite dotaz na výpočet čistého peňažného toku. „Peňažný tok" môže byť definovaný ako zmena zostatku určitých účtov za obdobie. Pomocou BQL by ste mohli urobiť:

  SELECT year, month, sum(position)
  WHERE account ~ 'Income' OR account ~ 'Expenses'
  GROUP BY year, month

  Toto čistí všetky výnosové a nákladové záznamy po mesiacoch. Filtrujte pomocou ~ a regulárneho výrazu: LIKE je syntaktická chyba v beanquery 0.2.0. Záznamy nesú position, nie amount. Každý riadok obsahuje jeden Inventory, takže každá mena je uvedená samostatne namiesto konverzie. Výnosy prichádzajú záporné a náklady kladné. Mohli by ste to spustiť cez bea query alebo cez Python API beanquery uvedené vyššie, a potom výsledok naformátovať.

• Výkaz výdavkov podľa kategórie: Dotazujte celkové výdavky na kategóriu:

  SELECT account, sum(position)
  WHERE account ~ 'Expenses'
  GROUP BY account
  ORDER BY sum(position) ASC

  Toto poskytuje tabuľku výdavkov podľa kategórie. Každý súčet je Inventory v pôvodnej mene. Nezabalujte agregát do round(): neexistuje funkcia round(inventory, int), takže round(sum(position), 2) sa nepodarí skompilovať. V skripte môžete spustiť viacero dotazov a výstup výsledkov vo formáte text, CSV alebo dokonca JSON na ďalšie spracovanie.

Jeden používateľ považoval za „triviálne" analyzovať finančné dáta pomocou Fava alebo skriptov, pričom uviedol, že používa jeden Python skript na vytiahnutie dát z Beancount cez Query Language a ich vloženie do Pandas DataFrame na prípravu vlastného výkazu. Napríklad môžete získať mesačné súčty dotazom a potom použiť Pandas/Matplotlib na vykreslenie grafu peňažných tokov v čase. Kombinácia BQL a knižníc pre dátovú vedu vám umožňuje vytvárať výkazy nad rámec toho, čo Fava ponúka štandardne.

Pokročilé správy (grafy, výkonnosť atď.)​

Pre pokročilejšie potreby môžu vaše skripty počítať metriky ako výkonnosť investícií alebo vytvárať vizuálne výstupy:

• Výkonnosť investícií (IRR/XIRR): Keďže váš ledger obsahuje všetky peňažné toky (nákupy, predaje, dividendy), môžete vypočítať miery výnosu portfólia. Napríklad by ste mohli napísať skript, ktorý filtruje transakcie vašich investičných účtov a potom vypočíta vnútornú mieru výnosu (Internal Rate of Return). Existujú knižnice (alebo vzorce) na výpočet IRR pri daných dátach peňažných tokov. Niektoré komunitne vyvinuté rozšírenia Fava (ako PortfolioSummary alebo fava_investor) robia presne toto, počítajú IRR a ďalšie metriky pre investičné portfóliá. Ako skript by ste mohli použiť funkciu IRR (z NumPy alebo vlastnú) na sériu vkladov/výberov plus konečnú hodnotu.

• Viacobdobové alebo vlastné metriky: Chcete výkaz svojej miery úspor (pomer úspor k príjmu) každý mesiac? Python skript môže načítať ledger, sčítať všetky výnosové účty a všetky nákladové účty, potom vypočítať úspory = príjmy - výdavky a percento. To by mohlo vypísať peknú tabuľku alebo dokonca vygenerovať HTML/Markdown výkaz pre vaše záznamy.

• Visualizácia: Môžete generovať grafy mimo Fava. Napríklad použite matplotlib alebo altair v skripte na vytvorenie grafu čistého imania v čase pomocou dát ledgeru. Keďže ledger má všetky historické zostatky (alebo ich môžete nahromadiť iterovaním záznamov), môžete vytvárať časové rady grafov. Uložte tieto grafy ako obrázky alebo interaktívne HTML. (Ak uprednostňujete vizuály v aplikácii, pozrite si sekciu o rozšíreniach Fava nižšie pre pridávanie grafov v rámci Fava.)

Možnosti výstupu: Rozhodnite, ako doručiť výkaz:

• Pre jednorazovú analýzu môže stačiť tlač na obrazovku alebo uloženie do CSV/Excel súboru.
• Pre dashboardy zvážte generovanie HTML súboru s dátami (možno pomocou šablónovacej knižnice ako Jinja2 alebo jednoducho písaním Markdown), ktorý môžete otvoriť v prehliadači.
• Môžete tiež integrovať s Jupyter Notebooks pre interaktívne prostredie výkazníctva, hoci to je viac na prieskum než na automatizáciu.

Spúšťanie upozornení z vášho denníka​

Ďalším mocným využitím skriptovateľných pracovných postupov je nastavenie upozornení na základe podmienok vo vašich finančných dátach. Keďže váš ledger sa pravidelne aktualizuje (a môže obsahovať položky s budúcim dátumom, ako nadchádzajúce účty alebo rozpočty), môžete ho skenovať skriptom a byť informovaní o dôležitých udalostiach.

Varovania o nízkom zostatku na účte​

Aby ste sa vyhli prečerpaniu alebo udržali minimálny zostatok, môžete chcieť upozornenie, ak nejaký účet (napr. bežný alebo sporiaci) klesne pod prahovú hodnotu. Tu je postup, ako to implementovať:

1. Zistite aktuálne zostatky: Po načítaní entries cez loader vypočítajte najnovší zostatok účtov, ktoré vás zaujímajú. Môžete to urobiť agregáciou záznamov alebo použitím dotazu. Napríklad použite BQL dotaz na zostatok konkrétneho účtu:

   SELECT sum(position) WHERE account = 'Assets:Bank:Checking'

   Toto vracia aktuálny zostatok tohto účtu (súčet všetkých jeho záznamov). Alternatívne použite interné funkcie Beancount na zostavenie súvahy. Napríklad:

   from beancount.core import realization
   tree = realization.realize(entries)
   acct = realization.get_or_create(tree, "Assets:Bank:Checking")
   balance = acct.balance  # an Inventory of commodities

   Odovzdajte iba záznamy: druhý parameter je min_accounts, nie mapa možností. Potom extrahujte číselnú hodnotu (napr. balance.get_currency_units('USD') vracia Decimal sumu v USD). Podobne ako agregát dotazu, zostatok udržiava každú menu samostatne. Avšak použitie dotazu je pre väčšinu prípadov jednoduchšie.

2. Skontrolujte prahovú hodnotu: Porovnajte zostatok s vaším preddefinovaným limitom. Ak je nižší, spustite upozornenie.

3. Spustite notifikáciu: To môže byť také jednoduché, ako tlač varovania do konzoly, ale pre skutočné upozornenia môžete poslať e-mail alebo push notifikáciu. Môžete integrovať s e-mailom (cez smtplib) alebo službou ako IFTTT alebo webhook API Slacku na odoslanie upozornenia. Napríklad:

   if balance < 1000:
       send_email("Low balance alert", f"Account XYZ balance is {balance}")

   (Implementujte send_email s údajmi o vašom e-mailovom serveri.)

Spúšťaním tohto skriptu denne (cez cron job alebo Windows Task Scheduler) získate proaktívne varovania. Keďže používa ledger, môže brať do úvahy všetky transakcie vrátane tých, ktoré ste práve pridali.

Nadchádzajúce termíny platieb​

Ak používate Beancount na sledovanie účtov alebo termínov, môžete označiť budúce platby a nechať skripty, aby vám pripomínali. Dva spôsoby, ako reprezentovať nadchádzajúce záväzky v Beancount:

• Udalosti: Beancount podporuje direktívu event pre ľubovoľné datované poznámky. Napríklad:

  2025-05-10 event "BillDue" "Mortgage payment due"

  Toto neovplyvňuje zostatky, ale zaznamenáva dátum s označením. Skript môže skenovať entries pre záznamy Event, kde Event.type == "BillDue" (alebo akýkoľvek vlastný typ, ktorý si vyberiete) a skontrolovať, či je dátum v rámci, povedzme, nasledujúcich 7 dní od dneška. Ak áno, spustite upozornenie (e-mail, notifikácia alebo dokonca popup).

• Budúce transakcie: Niektorí ľudia zadávajú transakcie s budúcim dátumom (post-datované) pre veci ako naplánované platby. Tieto sa nezobrazia v zostatkoch, kým dátum neuplynie (pokiaľ nespúšťate výkazy k budúcim dátumom). Skript môže hľadať transakcie datované v blízkej budúcnosti a vypísať ich.

Pomocou týchto môžete vytvoriť „tickler" skript, ktorý po spustení vypíše zoznam úloh alebo účtov splatných čoskoro. Integrujte s API ako Google Calendar alebo správcom úloh, ak chcete automaticky vytvárať pripomienky tam.

Detekcia anomálií​

Nad rámec známych prahových hodnôt alebo dátumov môžete skriptovať vlastné upozornenia na neobvyklé vzory. Napríklad, ak sa normálne mesačný výdavok nevyskytol (možno ste zabudli zaplatiť účet), alebo ak sú výdavky kategórie tento mesiac abnormálne vysoké, váš skript to môže označiť. To typicky zahŕňa dotazovanie nedávnych dát a ich porovnanie s históriou (čo môže byť pokročilá téma – možno využívajúca štatistiku alebo ML).

V praxi sa mnohí používatelia spoliehajú na zosúlaďovanie na zachytenie anomálií (neočakávaných transakcií). Ak dostávate bankové notifikácie (ako e-maily pre každú transakciu), mohli by ste ich parsovať skriptom a automaticky ich pridať do Beancount, alebo aspoň overiť, že sú zaznamenané. Jeden nadšenec dokonca nakonfiguroval svoju banku na posielanie e-mailov s upozorneniami na transakcie s plánom parsovať a automaticky pripojiť tieto transakcie k ledgeru. Tento druh udalosťami riadených upozornení môže zaručiť, že žiadna transakcia nezostane nezaznamenaná.

Rozšírenie Fava pomocou vlastných pluginov a zobrazení​

Fava je už skriptovateľná prostredníctvom svojho systému rozšírení. Ak chcete, aby sa vaša automatizácia alebo výkazy integrovali priamo do webového rozhrania, môžete napísať rozšírenie Fava (nazývané aj plugin) v Pythone.

Ako fungujú rozšírenia Fava: Rozšírenie je Python modul, ktorý definuje triedu dediacej z fava.ext.FavaExtensionBase. Zaregistrujete ho vo svojom Beancount súbore cez vlastnú možnosť. Napríklad, ak máte súbor myextension.py s triedou MyAlerts(FavaExtensionBase), môžete ho povoliť pridaním do svojho ledgeru:

1970-01-01 custom "fava-extension" "myextension"

Keď sa Fava načíta, importuje tento modul a inicializuje vašu triedu MyAlerts.

Rozšírenia môžu robiť niekoľko vecí:

• Hooky: Môžu sa napojiť na udalosti v životnom cykle Fava. Napríklad after_load_file() sa volá po načítaní ledgeru. Môžete to použiť na spustenie kontrol alebo predpočítanie dát. Ak by ste chceli implementovať kontrolu nízkeho zostatku vnútri Fava, after_load_file by mohol iterovať zostatky účtov a možno ukladať varovania (hoci ich zobrazenie v UI by mohlo vyžadovať trochu viac práce, ako vyvolanie FavaAPIError alebo použitie JavaScriptu na zobrazenie notifikácie).
• Vlastné výkazy/stránky: Ak vaša trieda rozšírenia nastaví atribút report_title, Fava pridá novú stránku v bočnom paneli pre ňu. Potom poskytnete šablónu (HTML/Jinja2) pre obsah tejto stránky. Takto vytvárate úplne nové zobrazenia, ako dashboard alebo súhrn, ktorý Fava štandardne nemá. Rozšírenie môže zhromaždiť akékoľvek dáta potrebuje (máte prístup k self.ledger, ktorý má všetky záznamy, zostatky atď.) a potom vykresliť šablónu.

Napríklad vstavané rozšírenie portfolio_list vo Fava pridáva stránku so zoznamom vašich pozícií portfólia. Komunitné rozšírenia idú ďalej:

• Dashboardy: Plugin fava-dashboards umožňuje definovanie vlastných grafov a panelov (pomocou knižníc ako Apache ECharts). Číta YAML konfiguráciu dotazov na spustenie, vykonáva ich cez Beancount a generuje dynamickú stránku dashboardu vo Fava. V podstate spája dáta Beancount a JavaScript knižnicu na grafy, aby vytvoril interaktívne vizualizácie.
• Analýza portfólia: Rozšírenie PortfolioSummary (príspevok používateľa) počíta investičné súhrny (zoskupovanie účtov, výpočet IRR atď.) a zobrazuje ich v UI Fava.
• Kontrola transakcií: Ďalšie rozšírenie, fava-review, pomáha kontrolovať transakcie v čase (napr. aby ste sa uistili, že vám neušli žiadne bločky).

Ak chcete vytvoriť jednoduché rozšírenie sami, začnite dedením z FavaExtensionBase. Napríklad minimálne rozšírenie, ktoré pridá stránku, by mohlo vyzerať takto:

from fava.ext import FavaExtensionBase
 
class HelloReport(FavaExtensionBase):
    report_title = "Hello World"
 
    def __init__(self, ledger, config):
        super().__init__(ledger, config)
        # any initialization, perhaps parse config if provided
 
    def after_load_file(self):
        # (optional) run after ledger is loaded
        print("Ledger loaded with", len(self.ledger.entries), "entries")

Ak by ste to umiestnili do hello.py a pridali custom "fava-extension" "hello" do svojho ledgeru, Fava by zobrazila novú stránku „Hello World" (tiež by ste potrebovali súbor šablóny HelloReport.html v podpriečinku templates na definovanie obsahu stránky, pokiaľ rozšírenie používa iba hooky). Šablóna môže používať dáta, ktoré pripojíte k triede rozšírenia. Fava používa šablóny Jinja2, takže by ste mohli vykresliť svoje dáta do HTML tabuľky alebo grafu v tejto šablóne.

Poznámka: Systém rozšírení Fava je mocný, ale považovaný za „nestabilný" (podlieha zmenám). Vyžaduje určitú znalosť webového vývoja (HTML/JS), ak vytvárate vlastné stránky. Ak je vaším cieľom jednoducho spúšťať skripty alebo analýzy, mohlo by byť jednoduchšie ponechať ich ako externé skripty. Použite rozšírenia Fava, keď chcete prispôsobený zážitok v aplikácii pre svoj pracovný postup.

Integrácia s API tretích strán a údajmi​

Jednou z výhod skriptovateľných pracovných postupov je schopnosť vťahovať externé dáta. Tu sú bežné integrácie:

Pre hostované ocenené ceny ponúka Live Prices spravované includes bez naplánovaného skriptu na sťahovanie cien. Vyberte podporované páry aktív a menu kotácie vo výbere. Miestne pracovné postupy založené na súboroch nižšie zostávajú užitočné pre upstream Beancount, Fava a reprodukovateľné výkazy. Spravovaná aktualizácia nevytvára Git commit vo vašom ledgeri.

• Výmenné kurzy a komodity: Upstream Beancount sám nesťahuje ceny, ale poskytuje direktívu price na dodanie kurzov. Môžete automatizovať sťahovanie týchto cien. Napríklad skript môže dotazovať API (Yahoo Finance, Alpha Vantage atď.) na najnovší výmenný kurz alebo cenu akcie a pripojiť cenový záznam k vášmu ledgeru:

  2025-04-30 price BTC 30000 USD
  2025-04-30 price EUR 1.10 USD

  Existujú nástroje ako bea price, podporované Beanprice v spravovanom engine, ktoré sťahujú denné kotácie a vypisujú ich vo formáte Beancount. Mohli by ste ho raz povoliť pomocou bea engine enable beanprice, potom naplánovať bea price main.beancount na spúšťanie každú noc na aktualizáciu include súboru prices.beancount. Alebo použite Python: napr. s knižnicou requests na volanie API. Dokumentácia Beancount navrhuje, že pre verejne obchodované aktíva môžete „vyvolať nejaký kód, ktorý stiahne ceny a vypíše za vás direktívy." Inými slovami, nechajte skript robiť vyhľadávanie a vkladanie riadkov price, namiesto toho, aby ste to robili manuálne.

• Dáta o akciovom portfóliu: Podobne ako výmenné kurzy, môžete integrovať s API na získanie podrobných dát o akciách alebo dividendách. Napríklad Yahoo Finance API (alebo komunitné knižnice ako yfinance) môže získať historické dáta pre ticker. Skript môže aktualizovať váš ledger o mesačnú históriu cien pre každú akciu, ktorú vlastníte, čo umožňuje presné historické výkazy trhovej hodnoty. Niektoré vlastné rozšírenia (ako fava_investor) dokonca sťahujú cenové dáta za behu na zobrazenie, ale najjednoduchšie je pravidelne importovať ceny do ledgeru.

• Bankové API (Open Banking/Plaid): Namiesto sťahovania CSV môžete použiť API na automatické získavanie transakcií. Služby ako Plaid agregujú bankové účty a umožňujú programový prístup k transakciám. V pokročilom nastavení by ste mohli mať Python skript, ktorý používa Plaid API na denné získavanie nových transakcií a ich uloženie do súboru (alebo priamy import do ledgeru). Jeden power user vytvoril systém, kde Plaid napája ich importný pipeline, čím sa ich knihy stávajú takmer automatickými. Poznamenávajú, že „nič vám nebráni zaregistrovať sa v Plaid API a robiť to isté lokálne" – t.j. môžete napísať lokálny skript na získanie bankových dát, potom použiť logiku importeru Beancount na ich parsovanie do záznamov ledgeru. Niektoré regióny majú open banking API poskytované bankami; tie by sa dali použiť podobne.

• Ďalšie API: Môžete integrovať nástroje na rozpočtovanie (export plánovaných rozpočtov na porovnanie so skutočnosťou v Beancount), alebo použiť OCR API na čítanie bločkov a ich automatické párovanie s transakciami. Keďže vaše skripty majú plný prístup k ekosystému Pythonu, môžete integrovať všetko od e-mailových služieb (na odosielanie upozornení) po Google Sheets (napr. aktualizovať tabuľku s mesačnými finančnými metrikami) až po messaging aplikácie (poslať si súhrnný výkaz cez Telegram bota).

Pri používaní API tretích strán nezabudnite zabezpečiť svoje prihlasovacie údaje (použite premenné prostredia alebo konfiguračné súbory pre API kľúče) a elegantne ošetriť chyby (problémy so sieťou, výpadok API) vo svojich skriptoch. Často je rozumné cachovať dáta (napríklad uložiť stiahnuté výmenné kurzy, aby ste opakovane nežiadali ten istý historický kurz).

Najlepšie praktiky pre modulárne, udržiavateľné skripty​

Pri budovaní skriptovateľných pracovných postupov udržujte svoj kód organizovaný a robustný:

• Modularita: Rozdeľte rôzne záležitosti do rôznych skriptov alebo modulov. Napríklad majte samostatné skripty pre „import dát/zosúlaďovanie" vs. „generovanie výkazov" vs. „upozornenia". Môžete dokonca vytvoriť malý Python balík pre svoj ledger s modulmi ako ledger_import.py, ledger_reports.py atď. To robí každú časť ľahšie pochopiteľnou a testovateľnou.

• Konfigurácia: Vyhnite sa pevnému kódovaniu hodnôt. Použite konfiguračný súbor alebo premenné na začiatku skriptu pre veci ako názvy účtov, prahové hodnoty, API kľúče, rozsahy dátumov atď. To umožňuje ľahké úpravy bez hlbokého editovania kódu. Napríklad definujte LOW_BALANCE_THRESHOLDS = {"Assets:Bank:Checking": 500, "Assets:Savings": 1000} na začiatku a váš skript upozornení môže prechádzať tento dict.

• Testovanie: Zaobchádzajte so svojou finančnou automatizáciou ako s kódom kritickým pre misiu – pretože ním je! Píšte testy pre komplexnú logiku. Beancount poskytuje niektoré testovacie pomocníky (používané interne na testovanie importerov), ktoré môžete využiť na simuláciu vstupov ledgeru. Aj bez sofistikovaných frameworkov môžete mať fiktívne CSV a očakávané výstupné transakcie a overiť, že váš importný skript produkuje správne záznamy. Ak používate pytest, môžete tieto testy ľahko integrovať (ako to urobil Alex Watt cez príkaz just test obaľujúci pytest).

• Verzionovanie: Udržujte svoj ledger a skripty pod verzionovaním (git). To vám nielen poskytuje zálohy a históriu, ale povzbudzuje vás robiť zmeny kontrolovaným spôsobom. Môžete označovať vydania svojich „finančných skriptov" alebo kontrolovať rozdiely pri ladení problému. Niektorí používatelia dokonca sledujú svoje finančné záznamy v Git, aby videli zmeny v čase. Len dávajte pozor, aby ste v repozitári ignorovali citlivé dáta (ako surové súbory výpisov alebo API kľúče).

• Dokumentácia: Zdokumentujte svoje vlastné pracovné postupy pre budúce ja. README vo vašom repozitári vysvetľujúci, ako nastaviť prostredie, ako spúšťať každý skript a čo každý robí, bude po mesiacoch neoceniteľné. Tiež komentujte svoj kód, najmä akúkoľvek nie zjavnú účtovnú logiku alebo interakciu s API.

• Údržba pluginov Fava: Ak píšete rozšírenie Fava, udržujte ho jednoduché. Fava sa môže meniť, takže menšie rozšírenia s cielenou funkcionalitou sa ľahšie aktualizujú. Vyhnite sa prílišnému duplikovaniu logiky – použite query engine Beancount alebo existujúce pomocné funkcie vždy, keď je to možné, namiesto pevného kódovania výpočtov, ktoré môžu byť citlivé na zmeny ledgeru.

• Bezpečnosť: Keďže vaše skripty môžu spracúvať citlivé dáta a pripájať sa k externým službám, zaobchádzajte s nimi opatrne. Nevystavujte API kľúče a zvážte spúšťanie automatizácie na bezpečnom počítači. Ak používate hostované riešenie alebo cloud (ako plánovanie GitHub Actions alebo server na spustenie Fava), uistite sa, že vaše dáta ledgeru sú šifrované v pokoji a že ste spokojní s dôsledkami na súkromie.

Dodržiavaním týchto postupov zaistíte, že váš pracovný postup zostane spoľahlivý, aj keď sa vaše financie (a samotné nástroje) vyvíjajú. Chcete skripty, ktoré môžete opakovane používať rok čo rok, s minimálnymi úpravami.

Záver​

Beancount a Fava poskytujú mocnú, flexibilnú platformu pre technicky zdatných používateľov na úplné prispôsobenie sledovania osobných financií. Písaním Python skriptov môžete automatizovať zdĺhavé úlohy ako zosúlaďovanie výpisov, vytvárať bohaté výkazy prispôsobené vašim potrebám a mať prehľad o svojich financiách pomocou včasných upozornení. Prebrali sme celú škálu príkladov od základných po pokročilé – počnúc jednoduchými dotazmi a CSV importmi až po plnohodnotné pluginy Fava a integrácie externých API. Pri ich implementácii začnite jednoducho a postupne budujte. Dokonca aj niekoľko malých automatizačných skriptov môže ušetriť hodiny práce a výrazne zlepšiť presnosť. A pamätajte, keďže všetko je čistý text a Python, máte plnú kontrolu – váš finančný systém rastie s vami a prispôsobuje sa vašim konkrétnym potrebám. Šťastné skriptovanie!

Zdroje: Vyššie uvedené techniky sú čerpané z dokumentácie Beancount a skúseností komunity. Pre ďalšie čítanie pozrite oficiálnu dokumentáciu Beancount, komunitné príručky a blogy a repozitár Awesome Beancount pre odkazy na užitočné pluginy a nástroje.