Fluxos de Treball Scriptables amb Beancount i Fava

Beancount (una eina de comptabilitat de doble entrada en text pla) i Fava (la seva interfície web) són altament extensibles i scriptables. El seu disseny permet automatitzar tasques financeres, generar informes personalitzats i configurar alertes escrivint scripts de Python. En paraules d’un usuari, “M’agrada molt tenir les meves dades en un format tan convenient, i m’agrada poder automatitzar les coses tant com vulgui. No hi ha API com un fitxer al disc; és fàcil d’integrar.” Aquesta guia us guiarà a través de la creació de fluxos de treball scriptables, des de l’automatització per a principiants fins als plugins avançats de Fava.

Començant: Executant Beancount com un Script de Python

Abans d’endinsar-nos en tasques específiques, assegureu-vos de tenir Beancount instal·lat (per exemple, mitjançant pip install beancount). Com que Beancount està escrit en Python, podeu utilitzar-lo com a biblioteca als vostres propis scripts. L’enfocament general és:

• Carregar el vostre llibre major de Beancount: Utilitzeu el carregador de Beancount per analitzar el fitxer .beancount en objectes de Python. Per exemple:

  from beancount import loader
  entries, errors, options_map = loader.load_file("myledger.beancount")
  if errors:
      print("Errors:", errors)

  Això us proporciona una llista de entries (transaccions, saldos, etc.) i un options_map amb metadades. Tots els vostres comptes, transaccions i saldos ara són accessibles en codi.

• Aprofitar el llenguatge de consulta de Beancount (BQL): En lloc d’iterar manualment, podeu executar consultes semblants a SQL a les dades. Per exemple, per obtenir les despeses totals per mes, podeu utilitzar l’API de consulta:

  from beancount.query import query
  q = query.Query(entries, options_map)
  result = q.query("SELECT month, sum(position) WHERE account ~ 'Expenses' GROUP BY month")
  print(result)

  Això utilitza el sistema de consulta de Beancount per agregar dades. (En el fons, això és similar al que fa l’ordre bean-query, però aquí l’esteu utilitzant en un script.) De fet, l’autor de Beancount assenyala que podeu carregar el fitxer i cridar run_query() directament a través de l’API de Python, evitant la necessitat de cridar ordres externes en un bucle.

• Configurar una estructura de projecte: Organitzeu els vostres scripts al costat del vostre llibre major. Una disposició comuna és tenir directoris per a importadors (per obtenir/analitzar dades externes), informes o consultes (per a scripts d’anàlisi) i documents (per emmagatzemar extractes descarregats). Per exemple, un usuari manté:

  • importers/ – scripts d’importació de Python personalitzats (amb proves),
  • queries/ – scripts per generar informes (executables mitjançant python3 queries/...),
  • documents/ – CSV/PDF bancaris descarregats organitzats per compte.

Amb aquesta configuració, podeu executar scripts manualment (per exemple, python3 queries/cash_flow.py) o programar-los (mitjançant cron o un executor de tasques) per automatitzar el vostre flux de treball.

Automatització de Tasques de Conciliació

Conciliació significa assegurar-se que el vostre llibre major coincideixi amb els registres externs (extractes bancaris, informes de targetes de crèdit, etc.). El llibre major de text pla i l’API de Python de Beancount fan possible automatitzar gran part d’aquest procés.

Importació i Conciliació de Transaccions (Nivell Principiant)

Per als principiants, l’enfocament recomanat és utilitzar els plugins importadors de Beancount. Escriviu una petita classe de Python seguint el protocol d’importació de Beancount per analitzar un format determinat (CSV, OFX, PDF, etc.) i produir transaccions. A continuació, utilitzeu l’ordre bean-extract o un script per aplicar aquests importadors:

• Escriviu un importador (una classe de Python amb mètodes com identify(), extract()) per al format CSV del vostre banc. La documentació de Beancount proporciona una guia i exemples.
• Utilitzeu bean-extract en un script o Makefile (com l’exemple justfile) per analitzar nous extractes. Per exemple, un flux de treball executa bean-extract en tots els fitxers de ~/Downloads i genera transaccions en un fitxer temporal.
• Reviseu i copieu manualment les transaccions del fitxer temporal al vostre llibre major principal i, a continuació, executeu bean-check per assegurar-vos que els saldos coincideixen.

Tot i que aquest procés encara implica un pas de revisió, gran part del treball pesat d’anàlisi i format d’entrades està automatitzat. Els scripts d’importació també poden assignar automàticament categories i fins i tot establir assercions de saldo (declaracions dels saldos esperats) per detectar discrepàncies. Per exemple, després d’importar, podríeu tenir una línia com 2025-04-30 balance Assets:Bank:Checking 1234.56 USD que afirma el saldo de tancament. Quan executeu bean-check, Beancount verificarà que totes aquestes assercions de saldo siguin correctes i senyalarà qualsevol error si falten transaccions o estan duplicades. Aquesta és una bona pràctica: generar automàticament assercions de saldo per a cada període d’extracte per permetre que l’ordinador detecti diferències no conciliades per vosaltres.

Scripts de Conciliació Personalitzats (Nivell Intermig)

Per obtenir més control, podeu escriure un script de Python personalitzat per comparar la llista de transaccions d’un banc (CSV o mitjançant API) amb les entrades del vostre llibre major:

1. Llegir les dades externes: Analitzeu el fitxer CSV del banc utilitzant el mòdul csv de Python (o Pandas). Normalitzeu les dades en una llista de transaccions, per exemple, cadascuna amb una data, import i descripció.
2. Carregar les transaccions del llibre major: Utilitzeu loader.load_file com es va mostrar anteriorment per obtenir totes les entrades del llibre major. Filtreu aquesta llista al compte d’interès (per exemple, el vostre compte corrent) i potser l’interval de dates de l’extracte.
3. Comparar i trobar coincidències:

• Per a cada transacció externa, comproveu si existeix una entrada idèntica al llibre major (coincideix per data i import, potser descripció). Si no es troba, marqueu-la com a "nova" i possiblement genereu-la com una transacció amb format Beancount per a la vostra revisió.
• Per contra, identifiqueu qualsevol entrada del llibre major en aquest compte que no aparegui a la font externa: podrien ser errors d’entrada de dades o transaccions que no s’han liquidat al banc.

4. Generar resultats: Imprimiu un informe o creeu un nou fragment .beancount amb les transaccions que falten.

Com a exemple, un script de la comunitat anomenat reconcile.py fa exactament això: donat un fitxer Beancount i un CSV d’entrada, imprimeix una llista de noves transaccions que s’han d’importar, així com qualsevol publicació existent del llibre major que no estigui a l’entrada (potencialment un signe de classificació errònia). Amb un script així, la conciliació mensual pot ser tan senzilla com executar-lo i, a continuació, afegir les transaccions suggerides al vostre llibre major. Un usuari de Beancount assenyala que “fa un procés de conciliació a tots els comptes cada mes” i utilitza una col·lecció creixent de codi Python per eliminar gran part del treball manual en la importació i conciliació de dades.

Consell: Durant la conciliació, aprofiteu les eines de Beancount per obtenir precisió:

• Utilitzeu assercions de saldo com s’ha esmentat, per tenir comprovacions automatitzades dels saldos dels comptes.
• Utilitzeu la directiva pad si voleu, que pot inserir automàticament entrades de compensació per petites diferències d’arrodoniment (utilitzeu-la amb precaució).
• Escriviu proves unitàries per al vostre importador o lògica de conciliació (Beancount proporciona ajudants de prova). Per exemple, un flux de treball implicava prendre un CSV de mostra, escriure proves fallides amb les transaccions esperades i, a continuació, implementar l’importador fins que totes les proves passessin. Això garanteix que el vostre script d’importació funcioni correctament per a diversos casos.

Generació d’Informes i Resums Personalitzats

Tot i que Fava proporciona molts informes estàndard (compte de resultats, balanç, etc.), podeu crear informes personalitzats mitjançant scripts. Aquests poden variar des de simples sortides de consola fins a fitxers o gràfics rics i formatats.

Consulta de Dades per a Informes (Nivell Principiant)

A un nivell bàsic, podeu utilitzar el llenguatge de consulta de Beancount (BQL) per obtenir dades resumides i imprimir-les o desar-les. Per exemple:

• Resum de Flux de Caixa: Utilitzeu una consulta per calcular el flux de caixa net. El "flux de caixa" es podria definir com el canvi en el saldo de determinats comptes durant un període. Utilitzant BQL, podríeu fer:

  SELECT year, month, sum(amount)
  WHERE account LIKE 'Income:%' OR account LIKE 'Expenses:%'
  GROUP BY year, month

  Això netejaria totes les publicacions d’ingressos i despeses per mes. Podríeu executar-ho mitjançant la CLI bean-query o mitjançant l’API de Python (query.Query com es va mostrar anteriorment) i, a continuació, formatar el resultat.

• Informe de Despeses per Categoria: Consulteu les despeses totals per categoria:

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

  Això genera una taula de despeses per categoria. Podeu executar diverses consultes en un script i generar els resultats com a text, CSV o fins i tot JSON per a un processament posterior.

Un usuari va trobar “trivial” analitzar dades financeres amb Fava o amb scripts, citant que utilitzen un script de Python per extreure dades de Beancount mitjançant el llenguatge de consulta i, a continuació, introduir-les en un DataFrame de Pandas per preparar un informe personalitzat. Per exemple, podríeu obtenir totals mensuals amb una consulta i, a continuació, utilitzar Pandas/Matplotlib per traçar un gràfic de flux de caixa al llarg del temps. La combinació de BQL i les biblioteques de ciència de dades us permet crear informes més enllà del que ofereix Fava per defecte.

Informes Avançats (Gràfics, Rendiment, etc.)

Per a necessitats més avançades, els vostres scripts poden calcular mètriques com el rendiment de la inversió o crear sortides visuals:

• Rendiment de la Inversió (IRR/XIRR): Com que el vostre llibre major conté tots els fluxos de caixa (compres, vendes, dividends), podeu calcular les taxes de rendiment de la cartera. Per exemple, podríeu escriure un script que filtri les transaccions dels vostres comptes d’inversió i, a continuació, calculi la taxa interna de rendiment. Hi ha biblioteques (o fórmules) per calcular l’IRR a partir de dades de flux de caixa. Algunes extensions de Fava desenvolupades per la comunitat (com PortfolioSummary o fava_investor) fan exactament això, calculant l’IRR i altres mètriques per a carteres d’inversió. Com a script, podríeu utilitzar una funció IRR (de NumPy o la vostra pròpia) a la sèrie de contribucions/retirades més el valor final.

• Mètriques Personalitzades o Multiperíode: Voleu un informe de la vostra taxa d’estalvi (relació entre l’estalvi i els ingressos) cada mes? Un script de Python pot carregar el llibre major, sumar tots els comptes d’ingressos i tots els comptes de despeses, i després calcular l’estalvi = ingressos - despeses i el percentatge. Això podria generar una taula agradable o fins i tot generar un informe HTML/Markdown per als vostres registres.

• Visualització: Podeu generar gràfics fora de Fava. Per exemple, utilitzeu matplotlib o altair en un script per crear un gràfic de valor net al llarg del temps, utilitzant dades del llibre major. Com que el llibre major té tots els saldos històrics (o podeu acumular-los iterant les entrades), podeu produir gràfics de sèries temporals. Deseu aquests gràfics com a imatges o HTML interactiu. (Si preferiu visuals a l’aplicació, consulteu la secció d’extensions de Fava a continuació per afegir gràfics dins de Fava.)

Opcions de Sortida: Decidiu com lliurar l’informe:

• Per a una anàlisi única, pot ser suficient amb imprimir a la pantalla o desar en un fitxer CSV/Excel.
• Per als taulers de control, considereu la possibilitat de generar un fitxer HTML amb les dades (possiblement utilitzant una biblioteca de plantilles com Jinja2 o fins i tot només escrivint Markdown) que pugueu obrir en un navegador.
• També podeu integrar-vos amb Jupyter Notebooks per a un entorn d’informes interactiu, tot i que això és més per a l’exploració que per a l’automatització.

Activació d’Alertes des del Vostre Llibre Major

Un altre ús potent dels fluxos de treball scriptables és la configuració d’alertes basades en condicions a les vostres dades financeres. Com que el vostre llibre major s’actualitza regularment (i pot incloure elements amb data futura com ara factures o pressupostos propers), podeu escanejar-lo amb un script i rebre notificacions d’esdeveniments importants.

Avisos de Saldo Baix del Compte

Per evitar descobertes o mantenir un saldo mínim, és possible que vulgueu una alerta si algun compte (per exemple, compte corrent o d’estalvi) cau per sota d’un llindar. Aquí teniu com podeu implementar-ho:

1. Determinar els saldos actuals: Després de carregar entries mitjançant el carregador, calculeu el saldo més recent dels comptes d’interès. Podeu fer-ho agregant publicacions o utilitzant una consulta. Per exemple, utilitzeu una consulta BQL per al saldo d’un compte específic:

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

   Això retorna el saldo actual d’aquest compte (suma de totes les seves publicacions). Alternativament, utilitzeu les funcions internes de Beancount per crear un balanç. Per exemple:

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

   A continuació, extraieu el valor numèric (per exemple, balance.get_currency_units('USD') podria donar el Decimal). Tot i això, utilitzar la consulta és més senzill per a la majoria dels casos.

2. Comprovar el llindar: Compareu el saldo amb el vostre límit predefinit. Si és inferior, activeu una alerta.

3. Activar la notificació: Això podria ser tan senzill com imprimir un avís a la consola, però per a les alertes reals, podríeu enviar un correu electrònic o una notificació push. Podeu integrar-vos amb el correu electrònic (mitjançant smtplib) o un servei com IFTTT o l’API de webhook de Slack per enviar l’alerta. Per exemple:

   if balance < 1000:
       send_email("Alerta de saldo baix", f"El saldo del compte XYZ és {balance}")

   (Implementeu send_email amb els detalls del vostre servidor de correu electrònic.)

En executar aquest script diàriament (mitjançant una feina cron o el programador de tasques de Windows), obtindreu avisos proactius. Com que utilitza el llibre major, pot tenir en compte totes les transaccions, incloses les que acabeu d’afegir.

Dates Límit de Pagament Properes

Si utilitzeu Beancount per fer un seguiment de les factures o les dates límit, podeu marcar els pagaments futurs i fer que els scripts us ho recordin. Dues maneres de representar les obligacions properes a Beancount:

• Esdeveniments: Beancount admet una directiva event per a notes datades arbitràries. Per exemple:

  2025-05-10 event "BillDue" "Pagament d'hipoteca degut"

  Això no afecta els saldos, però registra una data amb una etiqueta. Un script pot escanejar entries per a entrades Event on Event.type == "BillDue" (o qualsevol tipus personalitzat que trieu) i comprovar si la data es troba dins, per exemple, els propers 7 dies a partir d’avui. Si és així, activeu una alerta (correu electrònic, notificació o fins i tot una finestra emergent).

• Transaccions Futurs: Algunes persones introdueixen transaccions amb data futura (data posterior) per a coses com ara pagaments programats. Aquests no apareixeran als saldos fins que passi la data (tret que executeu informes a partir de dates futures). Un script pot buscar transaccions datades en un futur proper i llistar-les.

Utilitzant-los, podríeu crear un script “tickler” que, quan s’executi, generi una llista de tasques o factures que vencen aviat. Integreu-vos amb una API com Google Calendar o un gestor de tasques si voleu crear recordatoris automàticament allà.

Detecció d’Anomalies

Més enllà dels llindars o dates conegudes, podeu escriure alertes personalitzades per a patrons inusuals. Per exemple, si una despesa normalment mensual no s’ha produït (potser us heu oblidat de pagar una factura), o si la despesa d’una categoria és anormalment alta aquest mes, el vostre script podria marcar-la. Normalment, això implica consultar dades recents i comparar-les amb l’historial (que podria ser un tema avançat, possiblement utilitzant estadístiques o ML).

A la pràctica, molts usuaris confien en la conciliació per detectar anomalies (transaccions inesperades). Si rebeu notificacions bancàries (com ara correus electrònics per a cada transacció), podríeu analitzar-les amb un script i afegir-les automàticament a Beancount, o almenys verificar que estiguin registrades. Un entusiasta fins i tot va configurar el seu banc per enviar correus electrònics d’alerta de transaccions, amb el pla d’analitzar-los i afegir-los al llibre major automàticament. Aquest tipus d’alerta basada en esdeveniments pot garantir que cap transacció quedi sense registrar.

Ampliació de Fava amb Plugins i Vistes Personalitzades

Fava ja és scriptable a través del seu sistema d’extensió. Si voleu que la vostra automatització o informes s’integrin directament a la interfície web, podeu escriure una extensió de Fava (també anomenada plugin) en Python.

Com funcionen les extensions de Fava: Una extensió és un mòdul de Python que defineix una classe que hereta de fava.ext.FavaExtensionBase. L’enregistreu al vostre fitxer Beancount mitjançant una opció personalitzada. Per exemple, si teniu un fitxer myextension.py amb una classe MyAlerts(FavaExtensionBase), podeu activar-lo afegint-lo al vostre llibre major:

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

Quan Fava es carregui, importarà aquest mòdul i inicialitzarà la vostra classe MyAlerts.

Les extensions poden fer diverses coses:

• Hooks: Es poden connectar a esdeveniments en el cicle de vida de Fava. Per exemple, after_load_file() es crida després de carregar el llibre major. Podríeu utilitzar-ho per executar comprovacions o precalcular dades. Si volíeu implementar la comprovació de saldo baix dins de Fava, after_load_file podria iterar els saldos dels comptes i potser emmagatzemar avisos (tot i que fer-los aparèixer a la IU podria requerir una mica més de feina, com ara generar un FavaAPIError o utilitzar Javascript per mostrar una notificació).
• Informes/Pàgines Personalitzades: Si la vostra classe d’extensió estableix un atribut report_title, Fava afegirà una nova pàgina a la barra lateral. A continuació, proporcioneu una plantilla (HTML/Jinja2) per al contingut d’aquesta pàgina. Així és com creeu vistes completament noves, com ara un tauler de control o un resum que Fava no té per defecte. L’extensió pot recopilar les dades que necessita (podeu accedir a self.ledger, que té totes les entrades, saldos, etc.) i, a continuació, renderitzar la plantilla.

Per exemple, l’extensió integrada portfolio_list a Fava afegeix una pàgina que llista les posicions de la vostra cartera. Les extensions de la comunitat van més enllà:

• Taulers de control: El plugin fava-dashboards permet definir gràfics i panells personalitzats (utilitzant biblioteques com Apache ECharts). Llegeix una configuració YAML de consultes per executar, les executa mitjançant Beancount i genera una pàgina de tauler de control dinàmic a Fava. En essència, uneix les dades de Beancount i una biblioteca de gràfics JavaScript per produir visualitzacions interactives.
• Anàlisi de cartera: L’extensió PortfolioSummary (contribuint de l’usuari) calcula resums d’inversions (agrupant comptes, calculant l’IRR, etc.) i els mostra a la IU de Fava.
• Revisió de transaccions: Una altra extensió, fava-review, ajuda a revisar les transaccions al llarg del temps (per exemple, per assegurar-vos que no us heu perdut cap rebut).

Per crear una extensió senzilla per vosaltres mateixos, comenceu per subclassificar FavaExtensionBase. Per exemple, una extensió mínima que afegeix una pàgina podria ser semblant a:

from fava.ext import FavaExtensionBase

class HelloReport(FavaExtensionBase):
    report_title = "Hola món"

    def __init__(self, ledger, config):
        super().__init__(ledger, config)
        # qualsevol inicialització, potser analitzar la configuració si es proporciona

    def after_load_file(self):
        # (opcional) executar després de carregar el llibre major
        print("Llibre major carregat amb", len(self.ledger.entries), "entrades")

Si col·loqueu això a hello.py i afegiu custom "fava-extension" "hello" al vostre llibre major, Fava mostrarà una nova pàgina "Hola món" (també necessitareu un fitxer de plantilla HelloReport.html en una subcarpeta templates per definir el contingut de la pàgina, tret que l’extensió només utilitzi hooks). La plantilla pot utilitzar les dades que adjunteu a la classe d’extensió. Fava utilitza plantilles Jinja2, de manera que podríeu renderitzar les vostres dades en una taula HTML o un gràfic en aquesta plantilla.

Nota: El sistema d’extensió de Fava és potent, però es considera “inestable” (subjecte a canvis). Requereix certa familiaritat amb el desenvolupament web (HTML/JS) si esteu creant pàgines personalitzades. Si el vostre objectiu és simplement executar scripts o anàlisis, podria ser més fàcil mantenir-los com a scripts externs. Utilitzeu les extensions de Fava quan vulgueu una experiència a l’aplicació personalitzada per al vostre flux de treball.

Integració d’APIs i Dades de Tercers

Un dels avantatges dels fluxos de treball scriptables és la capacitat d’incorporar dades externes. Aquí teniu les integracions comunes:

• Tipus de Canvi i Matèries Primeres: Beancount no obté automàticament els preus per disseny (per mantenir els informes deterministes), però proporciona una directiva Price perquè pugueu subministrar tarifes. Podeu automatitzar l’obtenció d’aquests preus. Per exemple, un script pot consultar una API (Yahoo Finance, Alpha Vantage, etc.) per obtenir el tipus de canvi més recent o el preu de les accions i afegir una entrada de preu al vostre llibre major:

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

  Hi ha eines com bean-price (ara una eina externa sota l’ombrel·la de Beancount) que obté cotitzacions diàries i les genera en format Beancount. Podríeu programar bean-price per executar-se cada nit per actualitzar un fitxer d’inclusió prices.beancount. O utilitzar Python: per exemple, amb la biblioteca requests per cridar una API. La documentació de Beancount suggereix que per als actius que cotitzen en borsa, podeu “invocar algun codi que descarregarà els preus i generarà les directives per a vosaltres.” En altres paraules, deixeu que un script faci la cerca i insereixi les línies price, en lloc de fer-ho manualment.

• Dades de la Cartera d’Accions: De manera similar als tipus de canvi, podeu integrar-vos amb les API per obtenir dades detallades d’accions o dividends. Per exemple, l’API de Yahoo Finance (o biblioteques de la comunitat com yfinance) pot recuperar dades històriques per a un ticker. Un script podria actualitzar el vostre llibre major amb l’historial de preus mensual de cada acció que tingueu, cosa que permet informes històrics precisos del valor de mercat. Algunes extensions personalitzades (com fava_investor) fins i tot extreuen dades de preus sobre la marxa per a la visualització, però el més senzill és importar regularment els preus al llibre major.

• APIs Bancàries (Banca Oberta/Plaid): En lloc de descarregar CSV, podeu utilitzar les API per obtenir transaccions automàticament. Serveis com Plaid agreguen comptes bancaris i permeten l’accés programàtic a les transaccions. En una configuració avançada, podríeu tenir un script de Python que utilitzi l’API de Plaid per extreure noves transaccions diàriament i desar-les en un fitxer (o importar-les directament al llibre major). Un usuari avançat va crear un sistema on Plaid alimenta la seva línia d’importació, fent que els seus llibres siguin gairebé automàtics. Assenyalen que “res us impedeix registrar-vos a l’API de Plaid i fer el mateix localment”, és a dir, podeu escriure un script local per obtenir dades bancàries i, a continuació, utilitzar la vostra lògica d’importació de Beancount per analitzar-les en entrades del llibre major. Algunes regions tenen API de banca oberta proporcionades pels bancs; es podrien utilitzar de manera similar.

• Altres APIs: Podríeu integrar eines de pressupost (exportant pressupostos planificats per comparar-los amb els reals a Beancount), o utilitzar una API OCR per llegir rebuts i fer-los coincidir automàticament amb les transaccions. Com que els vostres scripts tenen accés complet a l’ecosistema de Python, podeu integrar-ho tot, des de serveis de correu electrònic (per enviar alertes) fins a Google Sheets (per exemple, actualitzar un full amb mètriques financeres mensuals) fins a aplicacions de missatgeria (enviar-vos un informe resum mitjançant el bot de Telegram).

Quan utilitzeu APIs de tercers, recordeu protegir les vostres credencials (utilitzeu variables d’entorn o fitxers de configuració per a les claus d’API) i gestioneu els errors (problemes de xarxa, temps d’inactivitat de l’API) de manera elegant als vostres scripts. Sovint és prudent emmagatzemar dades a la memòria cau (per exemple, emmagatzemar els tipus de canvi obtinguts perquè no sol·liciteu repetidament el mateix tipus històric).

Bones Pràctiques per a Scripts Modulars i Mantenibles

A mesura que creeu fluxos de treball scriptables, manteniu el vostre codi organitzat i robust:

• Modularitat: Dividiu les diferents preocupacions en diferents scripts o mòduls. Per exemple, tingueu scripts separats per a “importació/reconciliació de dades” vs. “generació d’informes” vs. “alertes”. Fins i tot podeu crear un petit paquet de Python per al vostre llibre major amb mòduls com ledger_import.py, ledger_reports.py, etc. Això fa que cada part sigui més fàcil d’entendre i provar.

• Configuració: Eviteu els valors de codificació dura. Utilitzeu un fitxer de configuració o variables de la part superior de l’script per a coses com ara noms de compte, llindars, claus d’API, intervals de dates, etc. Això fa que sigui fàcil d’ajustar sense editar el codi profundament. Per exemple, definiu LOW_BALANCE_THRESHOLDS = {"Assets:Bank:Checking": 500, "Assets:Savings": 1000} a la part superior i el vostre script d’alerta pot fer un bucle a través d’aquest diccionari.

• Prova: Tracteu la vostra automatització financera com a codi de missió crítica, perquè ho és! Escriviu proves per a lògica complexa. Beancount proporciona alguns ajudants de prova (utilitzats internament per a les proves d’importació) que podeu aprofitar per simular entrades del llibre major. Fins i tot sense marcs fantàstics, podeu tenir un CSV fictici i les transaccions de sortida esperades i afirmar que el vostre script d’importació produeix les entrades correctes. Si utilitzeu pytest, podeu integrar aquestes proves fàcilment (com va fer Alex Watt mitjançant una ordre just test que embolica pytest).

• Control de Versions: Manteniu el vostre llibre major i els vostres scripts sota control de