Základné natívne pluginy Beancount, ktoré by ste mali poznať

Aktuálne k 2026-09-15.

Sila Beancount nespočíva len v jeho formáte čistého textu, ale aj v rozšíriteľnosti pomocou pluginov. Natívne pluginy sú vstavané moduly, ktoré zvyšujú funkčnosť Beancount, automatizujú zdĺhavé úlohy a presadzujú účtovné osvedčené postupy. V tomto komplexnom sprievodcovi preskúmame všetky natívne pluginy dostupné v Beancount a ako ich efektívne používať.

Pre syntax direktív, na ktorých tieto pluginy pracujú, pozri referenciu syntaxe Beancount. Pre reálne komunitné pracovné postupy, ktoré kombinujú pluginy s importérmi a Fava, pozri komunitnú prezentáciu. Možnosti ledgera, ktoré interagujú s pluginmi, nájdete v konfigurácii možností.

Čo sú to pluginy Beancount?​

Pluginy Beancount sú moduly Python, ktoré spracúvajú vaše účtovné zápisy s cieľom pridať automatizáciu, validáciu alebo transformačné schopnosti. Spúšťajú sa počas fázy načítavania vášho účtovného súboru a môžu:

• Automatizovať opakujúce sa úlohy (napr. vytváranie deklarácií účtov)
• Overovať integritu dát (napr. kontrola duplicitných transakcií)
• Transformovať zápisy (napr. generovanie cenových záznamov z transakcií)
• Presadzovať účtovné pravidlá (napr. jedna mena na účet)

Ako používať pluginy​

Ak chcete aktivovať plugin v súbore Beancount, pridajte direktívu plugin na začiatok vášho ledgera:

plugin "beancount.plugins.auto_accounts"
plugin "beancount.plugins.implicit_prices"

Niektoré pluginy akceptujú konfiguračné možnosti:

; @m49-fragment dateless
plugin "beancount.plugins.check_commodity" "{'Assets:Trading': '.*'}"

Kategórie natívnych pluginov​

Natívne pluginy Beancount spadajú do štyroch hlavných kategórií:

1. Automatizačné pluginy​

2. Validačné pluginy​

3. Transformačné pluginy​

4. Meta-pluginy​

1. Automatizačné pluginy​

Tieto pluginy automatizujú opakujúce sa účtovné úlohy, šetria vám čas a znižujú manuálne chyby.

auto_accounts – Automatické deklarácie účtov​

Čo robí: Automaticky vkladá direktívy Open pre účty, ktoré sa vyskytujú v transakciách, ale neboli explicitne deklarované.

Prečo ho použiť: Odstraňuje potrebu manuálne deklarovať každý účet pred jeho použitím. Ideálne pre rýchly štart alebo pre používateľov, ktorí preferujú minimálnu byrokraciu.

Príklad:

plugin "beancount.plugins.auto_accounts"
 
2026-01-01 * "Coffee shop"
  Expenses:Food:Coffee        4.50 USD
  Assets:Cash                -4.50 USD

Bez tohto pluginu by ste museli manuálne pridať:

2025-12-01 open Expenses:Food:Coffee
2025-12-01 open Assets:Cash

Kedy použiť: Ideálne pre začiatočníkov alebo tých, ktorí chcú menej verbose ledger. Avšak explicitné deklarácie účtov môžu pomôcť odhaliť preklepy.

close_tree – Automatické zatváranie hierarchie účtov​

Čo robí: Keď zatvoríte nadradený účet, tento plugin automaticky zatvorí všetky podradené účty.

Prečo ho použiť: Udržiava konzistenciu v hierarchii účtov. Ak zatvoríte Assets:Investments, všetky podúčty ako Assets:Investments:Stocks a Assets:Investments:Bonds sa zatvoria automaticky.

Príklad:

plugin "beancount.plugins.close_tree"
 
2025-06-30 close Assets:Investments
 
; These will be automatically closed:
; Assets:Investments:Stocks
; Assets:Investments:Bonds
; Assets:Investments:RealEstate

Kedy použiť: Pri reštrukturalizácii hierarchie účtov alebo zatváraní celých kategórií účtov.

implicit_prices – Automatické generovanie cenových záznamov​

Čo robí: Syntetizuje direktívy Price z transakčných zápisov, ktoré obsahujú náklady (@) alebo ceny (@@).

Prečo ho použiť: Automaticky plní vašu cenovú databázu z transakcií, čo umožňuje presné vykazovanie trhovej hodnoty bez manuálnych cenových záznamov.

Príklad:

plugin "beancount.plugins.implicit_prices"
 
2026-01-02 * "Buy AAPL shares"
  Assets:Investments:Stocks    10 AAPL @ 150.00 USD
  Assets:Cash                 -1500.00 USD

Toto automaticky vygeneruje:

2026-01-02 price AAPL  150.00 USD

Kedy použiť: Nevyhnutné pre sledovanie investícií a viacmenové účtovníctvo, kde chcete automatickú históriu cien.

2. Validačné pluginy​

Tieto pluginy presadzujú integritu dát a účtovné osvedčené postupy, zachytávajú chyby skôr, ako sa stanú problémami.

noduplicates – Detekcia duplicitných transakcií​

Čo robí: Kontroluje, či žiadne dve transakcie nie sú identické, a to výpočtom a porovnaním hashov transakčných dát.

Prečo ho použiť: Zabraňuje náhodným duplicitným zápisom, najmä pri importovaní transakcií z viacerých zdrojov.

Príklad:

; @m49-fragment expected-failure
plugin "beancount.plugins.noduplicates"
 
2026-01-02 * "Rent payment"
  Expenses:Rent              1200.00 USD
  Assets:Checking           -1200.00 USD
 
; This would trigger an error:
2026-01-02 * "Rent payment"
  Expenses:Rent              1200.00 USD
  Assets:Checking           -1200.00 USD

Kedy použiť: Vždy odporúčané, najmä ak importujete z bankových výpisov alebo používate viacero dátových zdrojov.

check_commodity – Validácia deklarácií mien​

Čo robí: Zabezpečuje, aby všetky meny použité vo vašom ledgeri mali zodpovedajúce direktívy Commodity.

Prečo ho použiť: Presadzuje explicitné deklarácie mien, pomáha udržiavať čistý zoznam aktív a mien.

Príklad:

; @m49-fragment expected-failure
plugin "beancount.plugins.check_commodity"
 
2015-01-01 commodity USD
2020-01-01 commodity AAPL
 
; This would trigger an error without a commodity declaration:
2026-01-02 * "Buy Bitcoin"
  Assets:Crypto              0.5 BTC @ 45000 USD
  Assets:Cash             -22500.00 USD

Kedy použiť: Odporúčané pre udržiavanie prísneho sledovania mien a prevenciu preklepov v tickeroch.

check_average_cost – Validácia nákladovej základne​

Čo robí: Overuje, či je nákladová základňa správne zachovaná v transakciách, najmä pri použití priemerných nákladov.

Prečo ho použiť: Zabezpečuje presnosť nákladového účtovníctva pre daňové vykazovanie a výpočet kapitálových ziskov.

Kedy použiť: Kritické pre investičné portfóliá a akýkoľvek scenár, kde záleží na presnom sledovaní nákladov.

check_closing – Validácia uzatvárania zostatkov​

Čo robí: Rozširuje metadáta closing na kontroly zostatkov, čím zabezpečuje, že pozície sú po uzatváracích obchodoch nulové.

Prečo ho použiť: Potvrdzuje, že keď predáte celú pozíciu, zostatok je skutočne nulový (bez zvyškových akcií).

Príklad:

plugin "beancount.plugins.check_closing"
 
2026-01-02 * "Close entire AAPL position" #closing
  Assets:Investments:Stocks   -100 AAPL {150.00 USD}
  Assets:Cash                15500.00 USD
  Income:Investments:Gains    -500.00 USD

Značka #closing hovorí pluginu, aby overil, že vaša pozícia AAPL je po tejto transakcii nulová.

Kedy použiť: Pri predaji celých pozícií, aby ste sa uistili, že nič nezostalo.

coherent_cost – Kontrola konzistencie mien/nákladov​

Čo robí: Overuje, či meny nie sú používané nekonzistentne – s nákladovými poznámkami aj bez nich.

Prečo ho použiť: Zabraňuje miešaniu holých mien (napr. 100 USD) s menami s nákladmi (napr. 100 USD {1.2 CAD}), čo môže spôsobiť účtovné chyby.

Kedy použiť: Odporúčané pre viacmenové ledgere na udržanie konzistencie.

leafonly – Presadzovanie listových účtov​

Čo robí: Zabezpečuje, že len listové účty (účty bez podúčtov) prijímajú zápisy.

Prečo ho použiť: Presadzuje čistú hierarchiu účtov, kde súhrnné účty ako Expenses:Food nemajú priame zápisy, iba ich podúčty ako Expenses:Food:Groceries a Expenses:Food:Restaurants.

Príklad:

; @m49-fragment expected-failure
plugin "beancount.plugins.leafonly"
 
; This would trigger an error:
2026-01-02 * "Grocery shopping"
  Expenses:Food              50.00 USD  ; Error: Should post to a leaf account
  Assets:Cash               -50.00 USD
 
; Correct way:
2026-01-02 * "Grocery shopping"
  Expenses:Food:Groceries    50.00 USD  ; Correct: Posting to leaf account
  Assets:Cash               -50.00 USD

Kedy použiť: Keď chcete udržiavať prísne hierarchické účtovníctvo s jasnou kategorizáciou.

nounused – Detekcia nepoužitých účtov​

Čo robí: Identifikuje účty, ktoré boli otvorené, ale nikdy skutočne nepoužité v žiadnych transakciách.

Prečo ho použiť: Pomáha vyčistiť deklarácie účtov a identifikovať potenciálne preklepy alebo opustené účty.

Kedy použiť: Pravidelne, na audit a vyčistenie štruktúry účtov.

onecommodity – Jedna mena na účet​

Čo robí: Presadzuje, aby každý účet obsahoval iba jeden druh meny.

Prečo ho použiť: Zabraňuje miešaniu rôznych aktív v rovnakom účte, čo je vo všeobecnosti účtovný osvedčený postup.

Príklad:

; @m49-fragment expected-failure
plugin "beancount.plugins.onecommodity"
 
2026-01-02 * "Buy stocks"
  Assets:Investments         10 AAPL @ 150 USD
  Assets:Cash             -1500.00 USD
 
; This would trigger an error:
2026-01-03 * "Buy more stocks"
  Assets:Investments         5 GOOGL @ 140 USD  ; Error: Different commodity
  Assets:Cash              -700.00 USD

Kedy použiť: Keď preferujete prísne oddelenie účtov (jeden účet na akciu/aktívum).

sellgains – Validácia kapitálových ziskov​

Čo robí: Krížovo kontroluje deklarované kapitálové zisky proti vypočítaným ziskom z predajov lotov, čím zabezpečuje presnosť vašich výpočtov ziskov a strát.

Prečo ho použiť: Zachytáva chyby v manuálnych výpočtoch kapitálových ziskov, čo je kritické pre presné daňové vykazovanie.

Príklad:

plugin "beancount.plugins.sellgains"
 
2026-01-02 * "Sell AAPL shares"
  Assets:Investments:Stocks   -10 AAPL {140.00 USD}
  Assets:Cash                1500.00 USD
  Income:Investments:Gains   -100.00 USD  ; Plugin validates this is correct

Plugin overí: Výnosy z predaja (1500) - Nákladová základňa (1400) = Zisky (100)

Kedy použiť: Nevyhnutné pre každého, kto obchoduje akcie, kryptomeny alebo iné aktíva, kde záleží na kapitálových ziskoch.

unique_prices – Kontrola jedinečnosti cien​

Čo robí: Zabezpečuje, že existuje len jeden cenový záznam na menu a deň.

Prečo ho použiť: Zabraňuje konfliktným cenovým dátam, ktoré by mohli viesť k nesprávnemu oceňovaniu.

Kedy použiť: Odporúčané pri manuálnom zadávaní cien alebo importovaní z viacerých cenových zdrojov.

check_drained – Validácia vyprázdnených účtov​

Čo robí: Označuje účty, ktoré stále držia zostatok (vrátane neoceňovaných mien alebo zvyškových lotov), keď ste očakávali, že budú po prevodoch alebo zatvorení prázdne.

Prečo ho použiť: Zachytáva zvyškové zostatky, ktoré môžu uniknúť kontrolám balance a značkám #closing – užitočné najmä po viacmenových prevodoch.

Stav (kontrola 2026-09-15): Prítomný v strome Beancount 3.x na beancount/plugins/check_drained.py v aktuálnej línii PyPI (3.2.3).

Kedy použiť: Po veľkých reorganizáciách portfólia alebo pri zatváraní brokerských účtov.

3. Transformačné pluginy​

Tieto pluginy upravujú alebo vylepšujú vaše účtovné dáta užitočným spôsobom.

currency_accounts – Účty pre obchodovanie s menami​

Čo robí: Implementuje účty pre obchodovanie s menami na explicitné sledovanie forexových konverzií.

Prečo ho použiť: Poskytuje podrobné sledovanie transakcií konverzie mien, užitočné pre účtovné štandardy, ktoré to vyžadujú.

Kedy použiť: Keď potrebujete sledovať forexové zisky/straty samostatne alebo spĺňať špecifické účtovné požiadavky.

commodity_attr – Validácia atribútov mien​

Čo robí: Overuje, či direktívy mien majú požadované atribúty (ako export, name atď.).

Prečo ho použiť: Zabezpečuje, že vaše metadáta mien sú úplné a konzistentné.

Kedy použiť: Keď udržiavate podrobné metadáta mien na vykazovanie alebo export.

4. Meta-pluginy​

Tieto pluginy sú kolekciami iných pluginov pre pohodlie.

auto – Všetky automatické pluginy​

Čo robí: Aktivuje kolekciu "voľných" alebo automatických pluginov v jednej direktíve.

Kedy použiť: Rýchle nastavenie pre používateľov, ktorí chcú maximálnu automatizáciu s minimálnou konfiguráciou.

pedantic – Všetky validačné pluginy​

Čo robí: Aktivuje naraz všetky prísne validačné pluginy.

Prečo ho použiť: Presadzuje maximálnu integritu dát a účtovnú prísnosť. Skvelé pre produkčné ledgere alebo keď je presnosť prvoradá.

Príklad:

plugin "beancount.plugins.pedantic"
 
; This is equivalent to enabling:
; - check_commodity
; - check_average_cost
; - coherent_cost
; - leafonly
; - noduplicates
; - nounused
; - onecommodity
; - sellgains
; - unique_prices

Kedy použiť: Pre produkčné ledgere, kde chcete maximálnu validáciu a ste ochotní dodržiavať prísnejšie účtovné postupy.

Odporúčané konfigurácie pluginov​

Pre začiatočníkov​

plugin "beancount.plugins.auto_accounts"
plugin "beancount.plugins.noduplicates"
plugin "beancount.plugins.implicit_prices"

Táto minimálna sada poskytuje automatizáciu a zároveň predchádza bežným chybám.

Pre investorov​

plugin "beancount.plugins.auto_accounts"
plugin "beancount.plugins.implicit_prices"
plugin "beancount.plugins.sellgains"
plugin "beancount.plugins.check_average_cost"
plugin "beancount.plugins.unique_prices"

Zameriava sa na sledovanie investícií a presnosť kapitálových ziskov.

Pre prísne účtovníctvo​

plugin "beancount.plugins.pedantic"
plugin "beancount.plugins.sellgains"
plugin "beancount.plugins.check_closing"

Maximálna validácia pre produkčné prostredia.

Predvolená konfigurácia na Beancount.io​

Na Beancount.io zahŕňame plugin auto_accounts štandardne do všetkých nových účtovných súborov:

plugin "beancount.plugins.auto_accounts"

Toto poskytuje skvelú rovnováhu medzi jednoduchosťou použitia a funkčnosťou pre rýchly štart.

Stav pluginov kontrolovaný 2026-09-15​

Proti aktuálnemu stromu beancount/plugins na Beancount 3.2.3 (PyPI, 2026-09-15):

Nič z tejto natívnej sady nebolo odstránené medzi pôvodným návrhom tejto príručky a vyššie uvedeným dátumom. Komunitné (nenatívne) pluginy stále patria na zoznam Awesome Beancount plugins a do komunitnej prezentácie – tretie strany považujte za nezávisle verzované a pred aktiváciou na produkčnom ledgeri skontrolujte posledné vydanie každého repozitára.

Osvedčené postupy​

1. Začnite minimálne, pridávajte podľa potreby: Začnite s auto_accounts a noduplicates, potom pridávajte validačné pluginy, keď váš ledger dozrieva.

2. Testujte pluginy jednotlivo: Pri pridávaní viacerých pluginov ich aktivujte po jednom, aby ste pochopili ich účinky.

3. Pozorne čítajte chybové hlásenia: Chyby pluginov často poukazujú na skutočné účtovné problémy, ktoré treba opraviť.

4. Použite pedantic pre produkciu: Keď máte zavedený pracovný postup, zvážte zapnutie prísnej validácie.

5. Kombinujte s vlastnými pluginmi: Natívne pluginy fungujú spolu s vlastnými pluginmi, ako je plugin forecast, pre maximálnu funkčnosť.

Okrem natívnych pluginov​

Zatiaľ čo natívne pluginy poskytujú základnú funkčnosť, ekosystém Beancount zahŕňa mnoho komunitne vyvinutých pluginov pre špecializované potreby:

• fava.plugins.forecast – Pre prognózovanie opakujúcich sa transakcií
• fava.plugins.link_documents – Pre prepojenie transakcií so súbormi s účtenkami
• Vlastné importéry pre bankové špecifické formáty CSV
• Daňovo špecifické kalkulačky a správy

Preskúmajte ekosystém Beancount pre ďalšie možnosti a komunitnú prezentáciu pre to, ako ľudia kombinujú natívne pluginy s importérmi a Fava.

Záver​

Natívne pluginy Beancount transformujú účtovníctvo v čistom texte z manuálneho procesu na automatizovaný, validovaný a robustný systém finančného riadenia. Pochopením a využívaním týchto vstavaných nástrojov môžete:

• ✅ Automatizovať zdĺhavé účtovné úlohy
• ✅ Zachytiť chyby skôr, ako sa stanú problémami
• ✅ Udržiavať prísnu integritu dát
• ✅ Generovať presné finančné správy
• ✅ Sústrediť sa na finančné poznatky namiesto zadávania dát

Začnite experimentovať s týmito pluginmi vo vašom ledgeri ešte dnes. Začnite s auto_accounts a implicit_prices, potom postupne pridávajte validačné pluginy, keď vaše účtovné postupy dozrievajú.

Ste pripravení vyskúšať tieto pluginy? Prejdite na Beancount.io a začnite ich používať vo vašom účtovnom súbore ešte dnes!

Zdroje​

• Referencia API Beancount Plugins
• Sprievodca Beancount Scripting & Plugins
• Beancount Pluginy a možnosti od Bryana Alvesa
• Repozitár Beancount na GitHub

Máte otázky o pluginoch Beancount? Pripojte sa k diskusii na našom komunitnom fóre alebo si pozrite našu dokumentáciu.

Preskúmajte živý príklad kryptomenového ledgera: