diff --git a/public/rustfava/docs/deployment/index.html b/public/rustfava/docs/deployment/index.html
index 1017d94..9b00574 100644
--- a/public/rustfava/docs/deployment/index.html
+++ b/public/rustfava/docs/deployment/index.html
@@ -428,10 +428,93 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#apache-with-reverse-proxy" class="md-nav__link">
+  <a href="#desktop-app" class="md-nav__link">
     <span class="md-ellipsis">
       
-        Apache with reverse proxy
+        Desktop App
+      
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#docker" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Docker
+      
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#systemd-service" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Systemd Service
+      
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#reverse-proxy" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Reverse Proxy
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Reverse Proxy">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#apache" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Apache
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#nginx" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Nginx
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#caddy" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Caddy
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#security-considerations" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Security Considerations
       
     </span>
   </a>
@@ -500,10 +583,93 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#apache-with-reverse-proxy" class="md-nav__link">
+  <a href="#desktop-app" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Desktop App
+      
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#docker" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Docker
+      
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#systemd-service" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Systemd Service
+      
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#reverse-proxy" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Reverse Proxy
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Reverse Proxy">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#apache" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Apache
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#nginx" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Nginx
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#caddy" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Caddy
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#security-considerations" class="md-nav__link">
     <span class="md-ellipsis">
       
-        Apache with reverse proxy
+        Security Considerations
       
     </span>
   </a>
@@ -531,29 +697,66 @@
 
 
 <h1 id="deployment">Deployment<a class="headerlink" href="#deployment" title="Permanent link">&para;</a></h1>
-<p>There are a number of deployment options for persistently running rustfava on
-the Web, depending on your Web server and WSGI deployment choices. Below you
-can find some examples.</p>
-<h2 id="apache-with-reverse-proxy">Apache with reverse proxy<a class="headerlink" href="#apache-with-reverse-proxy" title="Permanent link">&para;</a></h2>
-<p>Apache configuration:</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nb">ProxyPass</span><span class="w"> </span><span class="s2">&quot;/rustfava&quot;</span><span class="w"> </span><span class="s2">&quot;http://localhost:5000/rustfava&quot;</span>
+<p>There are several ways to deploy rustfava depending on your needs.</p>
+<h2 id="desktop-app">Desktop App<a class="headerlink" href="#desktop-app" title="Permanent link">&para;</a></h2>
+<p>For personal use, the <a href="https://github.com/rustledger/rustfava/releases">desktop app</a> is the simplest option. It runs entirely locally with no server setup required.</p>
+<h2 id="docker">Docker<a class="headerlink" href="#docker" title="Permanent link">&para;</a></h2>
+<p>For server deployments, Docker is recommended:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>docker<span class="w"> </span>run<span class="w"> </span>-p<span class="w"> </span><span class="m">5000</span>:5000<span class="w"> </span>-v<span class="w"> </span>/path/to/ledger:/data<span class="w"> </span>ghcr.io/rustledger/rustfava<span class="w"> </span>/data/main.beancount
+</code></pre></div>
+<p>For advanced Docker configurations (authentication, HTTPS, docker-compose), see the <a href="../contrib/docker/README.md">Docker deployment guide</a>.</p>
+<h2 id="systemd-service">Systemd Service<a class="headerlink" href="#systemd-service" title="Permanent link">&para;</a></h2>
+<p>To run rustfava as a system service on Linux:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a><span class="c1"># /etc/systemd/system/rustfava.service</span>
+<a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a><span class="k">[Unit]</span>
+<a id="__codelineno-1-3" name="__codelineno-1-3" href="#__codelineno-1-3"></a><span class="na">Description</span><span class="o">=</span><span class="s">rustfava Web UI for Beancount</span>
+<a id="__codelineno-1-4" name="__codelineno-1-4" href="#__codelineno-1-4"></a><span class="na">After</span><span class="o">=</span><span class="s">network.target</span>
+<a id="__codelineno-1-5" name="__codelineno-1-5" href="#__codelineno-1-5"></a>
+<a id="__codelineno-1-6" name="__codelineno-1-6" href="#__codelineno-1-6"></a><span class="k">[Service]</span>
+<a id="__codelineno-1-7" name="__codelineno-1-7" href="#__codelineno-1-7"></a><span class="na">Type</span><span class="o">=</span><span class="s">simple</span>
+<a id="__codelineno-1-8" name="__codelineno-1-8" href="#__codelineno-1-8"></a><span class="na">ExecStart</span><span class="o">=</span><span class="s">/usr/bin/rustfava --host 127.0.0.1 --port 5000 /path/to/main.beancount</span>
+<a id="__codelineno-1-9" name="__codelineno-1-9" href="#__codelineno-1-9"></a><span class="na">User</span><span class="o">=</span><span class="s">your-user</span>
+<a id="__codelineno-1-10" name="__codelineno-1-10" href="#__codelineno-1-10"></a><span class="na">Restart</span><span class="o">=</span><span class="s">on-failure</span>
+<a id="__codelineno-1-11" name="__codelineno-1-11" href="#__codelineno-1-11"></a>
+<a id="__codelineno-1-12" name="__codelineno-1-12" href="#__codelineno-1-12"></a><span class="k">[Install]</span>
+<a id="__codelineno-1-13" name="__codelineno-1-13" href="#__codelineno-1-13"></a><span class="na">WantedBy</span><span class="o">=</span><span class="s">multi-user.target</span>
+</code></pre></div>
+<p>Then:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a>sudo<span class="w"> </span>systemctl<span class="w"> </span><span class="nb">enable</span><span class="w"> </span>rustfava
+<a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a>sudo<span class="w"> </span>systemctl<span class="w"> </span>start<span class="w"> </span>rustfava
+</code></pre></div>
+<h2 id="reverse-proxy">Reverse Proxy<a class="headerlink" href="#reverse-proxy" title="Permanent link">&para;</a></h2>
+<h3 id="apache">Apache<a class="headerlink" href="#apache" title="Permanent link">&para;</a></h3>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a><span class="nb">ProxyPass</span><span class="w"> </span><span class="s2">&quot;/rustfava&quot;</span><span class="w"> </span><span class="s2">&quot;http://localhost:5000/rustfava&quot;</span>
+<a id="__codelineno-3-2" name="__codelineno-3-2" href="#__codelineno-3-2"></a><span class="nb">ProxyPassReverse</span><span class="w"> </span><span class="s2">&quot;/rustfava&quot;</span><span class="w"> </span><span class="s2">&quot;http://localhost:5000/rustfava&quot;</span>
+</code></pre></div>
+<p>Run rustfava with the <code>--prefix</code> option:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a>rustfava<span class="w"> </span>--prefix<span class="w"> </span>/rustfava<span class="w"> </span>/path/to/main.beancount
 </code></pre></div>
-<p>The above will make rustfava accessible at the <code>/rustfava</code> URL and proxy requests
-arriving there to a locally running rustfava. To make rustfava work properly in
-that context, you should run it using the <code>--prefix</code> command line option, like
-this:</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>rustfava<span class="w"> </span>--prefix<span class="w"> </span>/rustfava<span class="w"> </span>/path/to/your/main.beancount
+<h3 id="nginx">Nginx<a class="headerlink" href="#nginx" title="Permanent link">&para;</a></h3>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a><span class="k">location</span><span class="w"> </span><span class="s">/rustfava/</span><span class="w"> </span><span class="p">{</span>
+<a id="__codelineno-5-2" name="__codelineno-5-2" href="#__codelineno-5-2"></a><span class="w">    </span><span class="kn">proxy_pass</span><span class="w"> </span><span class="s">http://127.0.0.1:5000/rustfava/</span><span class="p">;</span>
+<a id="__codelineno-5-3" name="__codelineno-5-3" href="#__codelineno-5-3"></a><span class="w">    </span><span class="kn">proxy_set_header</span><span class="w"> </span><span class="s">Host</span><span class="w"> </span><span class="nv">$host</span><span class="p">;</span>
+<a id="__codelineno-5-4" name="__codelineno-5-4" href="#__codelineno-5-4"></a><span class="w">    </span><span class="kn">proxy_set_header</span><span class="w"> </span><span class="s">X-Real-IP</span><span class="w"> </span><span class="nv">$remote_addr</span><span class="p">;</span>
+<a id="__codelineno-5-5" name="__codelineno-5-5" href="#__codelineno-5-5"></a><span class="w">    </span><span class="kn">proxy_set_header</span><span class="w"> </span><span class="s">X-Forwarded-For</span><span class="w"> </span><span class="nv">$proxy_add_x_forwarded_for</span><span class="p">;</span>
+<a id="__codelineno-5-6" name="__codelineno-5-6" href="#__codelineno-5-6"></a><span class="w">    </span><span class="kn">proxy_set_header</span><span class="w"> </span><span class="s">X-Forwarded-Proto</span><span class="w"> </span><span class="nv">$scheme</span><span class="p">;</span>
+<a id="__codelineno-5-7" name="__codelineno-5-7" href="#__codelineno-5-7"></a><span class="p">}</span>
 </code></pre></div>
-<p>To have rustfava run automatically at boot and manageable as a system service
-you might want to define a systemd unit file for it, for example:</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a><span class="k">[Unit]</span>
-<a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a><span class="na">Description</span><span class="o">=</span><span class="s">Rustfava Web UI for Beancount</span>
-<a id="__codelineno-2-3" name="__codelineno-2-3" href="#__codelineno-2-3"></a>
-<a id="__codelineno-2-4" name="__codelineno-2-4" href="#__codelineno-2-4"></a><span class="k">[Service]</span>
-<a id="__codelineno-2-5" name="__codelineno-2-5" href="#__codelineno-2-5"></a><span class="na">Type</span><span class="o">=</span><span class="s">simple</span>
-<a id="__codelineno-2-6" name="__codelineno-2-6" href="#__codelineno-2-6"></a><span class="na">ExecStart</span><span class="o">=</span><span class="s">/usr/bin/rustfava --host localhost --port 5000 --prefix /rustfava /path/to/your/main.beancount</span>
-<a id="__codelineno-2-7" name="__codelineno-2-7" href="#__codelineno-2-7"></a><span class="na">User</span><span class="o">=</span><span class="s">your-user</span>
+<h3 id="caddy">Caddy<a class="headerlink" href="#caddy" title="Permanent link">&para;</a></h3>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-6-1" name="__codelineno-6-1" href="#__codelineno-6-1"></a>your-domain.com {
+<a id="__codelineno-6-2" name="__codelineno-6-2" href="#__codelineno-6-2"></a>    reverse_proxy localhost:5000
+<a id="__codelineno-6-3" name="__codelineno-6-3" href="#__codelineno-6-3"></a>}
 </code></pre></div>
+<p>Caddy automatically handles HTTPS with Let's Encrypt.</p>
+<h2 id="security-considerations">Security Considerations<a class="headerlink" href="#security-considerations" title="Permanent link">&para;</a></h2>
+<p>When exposing rustfava to the internet:</p>
+<ol>
+<li><strong>Use HTTPS</strong> - Never expose plain HTTP to the public internet</li>
+<li><strong>Add authentication</strong> - Use a reverse proxy with OAuth2 or basic auth</li>
+<li><strong>Restrict access</strong> - Use firewall rules to limit access to trusted IPs</li>
+<li><strong>Keep updated</strong> - Regularly update rustfava for security patches</li>
+</ol>
+<p>See <a href="../SECURITY.md">SECURITY.md</a> for more security best practices.</p>
 
 
 
diff --git a/public/rustfava/docs/index.html b/public/rustfava/docs/index.html
index bd0ecfe..603bd67 100644
--- a/public/rustfava/docs/index.html
+++ b/public/rustfava/docs/index.html
@@ -267,6 +267,24 @@
         
       
       
+        <label class="md-nav__link md-nav__link--active" for="__toc">
+          
+  
+  
+  <span class="md-ellipsis">
+    
+  
+    Home
+  
+
+    
+  </span>
+  
+  
+
+          <span class="md-nav__icon md-icon"></span>
+        </label>
+      
       <a href="." class="md-nav__link md-nav__link--active">
         
   
@@ -284,6 +302,75 @@
 
       </a>
       
+        
+
+<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
+  
+  
+  
+    
+  
+  
+    <label class="md-nav__title" for="__toc">
+      <span class="md-nav__icon md-icon"></span>
+      Table of contents
+    </label>
+    <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
+      
+        <li class="md-nav__item">
+  <a href="#quick-start" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Quick Start
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Quick Start">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#desktop-app-recommended" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Desktop App (Recommended)
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#command-line" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Command Line
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#docker" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Docker
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+    </ul>
+  
+</nav>
+      
     </li>
   
 
@@ -443,6 +530,64 @@
     
   
   
+    <label class="md-nav__title" for="__toc">
+      <span class="md-nav__icon md-icon"></span>
+      Table of contents
+    </label>
+    <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
+      
+        <li class="md-nav__item">
+  <a href="#quick-start" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Quick Start
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Quick Start">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#desktop-app-recommended" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Desktop App (Recommended)
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#command-line" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Command Line
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#docker" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Docker
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+    </ul>
+  
 </nav>
                   </div>
                 </div>
@@ -462,21 +607,26 @@
 
 
 <h1 id="welcome-to-rustfava">Welcome to rustfava!<a class="headerlink" href="#welcome-to-rustfava" title="Permanent link">&para;</a></h1>
-<p>Rustfava is a web interface for double-entry bookkeeping, powered by
+<p>rustfava is a web interface for double-entry bookkeeping, powered by
 <a href="https://github.com/rustledger/rustledger">rustledger</a>, a Rust-based parser for
-the Beancount file format compiled to WebAssembly for fast in-browser
-processing.</p>
-<p>Rustfava is a fork of <a href="https://beancount.github.io/fava/">Fava</a> that replaces
+the Beancount file format compiled to WebAssembly for fast processing.</p>
+<p>rustfava is a fork of <a href="https://beancount.github.io/fava/">Fava</a> that replaces
 the Python Beancount parser with rustledger for improved performance. Your
 existing Beancount files are fully compatible.</p>
-<p><img alt="Rustfava Screenshot" src="https://i.imgbox.com/rfb9I7Zw.png" /></p>
+<p><img alt="rustfava dashboard" src="screenshot.png" /></p>
 <p>If you are new to rustfava or Beancount-format files, begin with the
 <a href="usage/">Getting Started</a> guide.</p>
-<p>This is enough to get you up and running:</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>uv<span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span>rustfava
+<h2 id="quick-start">Quick Start<a class="headerlink" href="#quick-start" title="Permanent link">&para;</a></h2>
+<h3 id="desktop-app-recommended">Desktop App (Recommended)<a class="headerlink" href="#desktop-app-recommended" title="Permanent link">&para;</a></h3>
+<p>Download the desktop app from <a href="https://github.com/rustledger/rustfava/releases">GitHub Releases</a> - no installation required, just double-click to run.</p>
+<h3 id="command-line">Command Line<a class="headerlink" href="#command-line" title="Permanent link">&para;</a></h3>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>uv<span class="w"> </span>tool<span class="w"> </span>install<span class="w"> </span>rustfava
 <a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a>rustfava<span class="w"> </span>ledger.beancount
 </code></pre></div>
-<p>and visit the web interface at <a href="http://localhost:5000">http://localhost:5000</a>.</p>
+<p>Then visit <a href="http://localhost:5000">http://localhost:5000</a>.</p>
+<h3 id="docker">Docker<a class="headerlink" href="#docker" title="Permanent link">&para;</a></h3>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>docker<span class="w"> </span>run<span class="w"> </span>-p<span class="w"> </span><span class="m">5000</span>:5000<span class="w"> </span>-v<span class="w"> </span>/path/to/ledger:/data<span class="w"> </span>ghcr.io/rustledger/rustfava<span class="w"> </span>/data/main.beancount
+</code></pre></div>
 
 
 
diff --git a/public/rustfava/docs/screenshot.png b/public/rustfava/docs/screenshot.png
new file mode 100644
index 0000000..3314105
Binary files /dev/null and b/public/rustfava/docs/screenshot.png differ
diff --git a/public/rustfava/docs/search/search_index.json b/public/rustfava/docs/search/search_index.json
index e8f197e..d7c11ab 100644
--- a/public/rustfava/docs/search/search_index.json
+++ b/public/rustfava/docs/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"Welcome to rustfava!","text":"<p>Rustfava is a web interface for double-entry bookkeeping, powered by rustledger, a Rust-based parser for the Beancount file format compiled to WebAssembly for fast in-browser processing.</p> <p>Rustfava is a fork of Fava that replaces the Python Beancount parser with rustledger for improved performance. Your existing Beancount files are fully compatible.</p> <p></p> <p>If you are new to rustfava or Beancount-format files, begin with the Getting Started guide.</p> <p>This is enough to get you up and running:</p> <pre><code>uv pip install rustfava\nrustfava ledger.beancount\n</code></pre> <p>and visit the web interface at http://localhost:5000.</p>"},{"location":"api/","title":"API Reference","text":"<p>Note</p> <p>There's no stability guarantee as this is just for internal purposes currently.</p>"},{"location":"api/#core-modules","title":"Core Modules","text":""},{"location":"api/#rustfava.core","title":"<code>rustfava.core</code>","text":"<p>This module provides the data required by Fava's reports.</p>"},{"location":"api/#rustfava.core.EntryNotFoundForHashError","title":"<code>EntryNotFoundForHashError</code>","text":"<p>               Bases: <code>RustfavaAPIError</code></p> <p>Entry not found for hash.</p> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>class EntryNotFoundForHashError(RustfavaAPIError):\n    \"\"\"Entry not found for hash.\"\"\"\n\n    def __init__(self, entry_hash: str) -&gt; None:\n        super().__init__(f'No entry found for hash \"{entry_hash}\"')\n</code></pre>"},{"location":"api/#rustfava.core.StatementNotFoundError","title":"<code>StatementNotFoundError</code>","text":"<p>               Bases: <code>RustfavaAPIError</code></p> <p>Statement not found.</p> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>class StatementNotFoundError(RustfavaAPIError):\n    \"\"\"Statement not found.\"\"\"\n\n    def __init__(self) -&gt; None:\n        super().__init__(\"Statement not found.\")\n</code></pre>"},{"location":"api/#rustfava.core.StatementMetadataInvalidError","title":"<code>StatementMetadataInvalidError</code>","text":"<p>               Bases: <code>RustfavaAPIError</code></p> <p>Statement metadata not found or invalid.</p> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>class StatementMetadataInvalidError(RustfavaAPIError):\n    \"\"\"Statement metadata not found or invalid.\"\"\"\n\n    def __init__(self, key: str) -&gt; None:\n        super().__init__(\n            f\"Statement path at key '{key}' missing or not a string.\"\n        )\n</code></pre>"},{"location":"api/#rustfava.core.JournalPage","title":"<code>JournalPage</code>  <code>dataclass</code>","text":"<p>A page of journal entries.</p> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>@dataclass(frozen=True)\nclass JournalPage:\n    \"\"\"A page of journal entries.\"\"\"\n\n    entries: Sequence[tuple[int, Directive]]\n    total_pages: int\n</code></pre>"},{"location":"api/#rustfava.core.FilteredLedger","title":"<code>FilteredLedger</code>","text":"<p>Filtered Beancount ledger.</p> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>class FilteredLedger:\n    \"\"\"Filtered Beancount ledger.\"\"\"\n\n    __slots__ = (\n        \"__dict__\",  # for the cached_property decorator\n        \"_date_first\",\n        \"_date_last\",\n        \"_pages\",\n        \"date_range\",\n        \"entries\",\n        \"ledger\",\n    )\n    _date_first: date | None\n    _date_last: date | None\n\n    def __init__(\n        self,\n        ledger: RustfavaLedger,\n        *,\n        account: str | None = None,\n        filter: str | None = None,  # noqa: A002\n        time: str | None = None,\n    ) -&gt; None:\n        \"\"\"Create a filtered view of a ledger.\n\n        Args:\n            ledger: The ledger to filter.\n            account: The account filter.\n            filter: The advanced filter.\n            time: The time filter.\n        \"\"\"\n        self.ledger = ledger\n        self.date_range: DateRange | None = None\n        self._pages: (\n            tuple[\n                int,\n                Literal[\"asc\", \"desc\"],\n                list[Sequence[tuple[int, Directive]]],\n            ]\n            | None\n        ) = None\n\n        entries = ledger.all_entries\n        if account:\n            entries = AccountFilter(account).apply(entries)\n        if filter and filter.strip():\n            entries = AdvancedFilter(filter.strip()).apply(entries)\n        if time:\n            time_filter = TimeFilter(ledger.options, ledger.fava_options, time)\n            entries = time_filter.apply(entries)\n            self.date_range = time_filter.date_range\n        self.entries = entries\n\n        if self.date_range:\n            self._date_first = self.date_range.begin\n            self._date_last = self.date_range.end\n            return\n\n        self._date_first = None\n        self._date_last = None\n        for entry in self.entries:\n            if isinstance(entry, Transaction):\n                self._date_first = entry.date\n                break\n        for entry in reversed(self.entries):\n            if isinstance(entry, (Transaction, Price)):\n                self._date_last = entry.date + timedelta(1)\n                break\n\n    @property\n    def end_date(self) -&gt; date | None:\n        \"\"\"The date to use for prices.\"\"\"\n        date_range = self.date_range\n        if date_range:\n            return date_range.end_inclusive\n        return None\n\n    @cached_property\n    def entries_with_all_prices(self) -&gt; Sequence[Directive]:\n        \"\"\"The filtered entries, with all prices added back in for queries.\"\"\"\n        entries = [*self.entries, *self.ledger.all_entries_by_type.Price]\n        entries.sort(key=_incomplete_sortkey)\n        return entries\n\n    @cached_property\n    def entries_without_prices(self) -&gt; Sequence[Directive]:\n        \"\"\"The filtered entries, without prices for journals.\"\"\"\n        return [e for e in self.entries if not isinstance(e, Price)]\n\n    @cached_property\n    def root_tree(self) -&gt; Tree:\n        \"\"\"A root tree.\"\"\"\n        return Tree(self.entries)\n\n    @cached_property\n    def root_tree_closed(self) -&gt; Tree:\n        \"\"\"A root tree for the balance sheet.\"\"\"\n        tree = Tree(self.entries)\n        tree.cap(self.ledger.options, self.ledger.fava_options.unrealized)\n        return tree\n\n    def interval_ranges(self, interval: Interval) -&gt; Sequence[DateRange]:\n        \"\"\"Yield date ranges corresponding to interval boundaries.\n\n        Args:\n            interval: The interval to yield ranges for.\n        \"\"\"\n        if not self._date_first or not self._date_last:\n            return []\n        complete = not self.date_range\n        return dateranges(\n            self._date_first, self._date_last, interval, complete=complete\n        )\n\n    def prices(self, base: str, quote: str) -&gt; Sequence[tuple[date, Decimal]]:\n        \"\"\"List all prices for a pair of commodities.\n\n        Args:\n            base: The price base.\n            quote: The price quote.\n        \"\"\"\n        all_prices = self.ledger.prices.get_all_prices((base, quote))\n        if all_prices is None:\n            return []\n\n        date_range = self.date_range\n        if date_range:\n            return [\n                price_point\n                for price_point in all_prices\n                if date_range.begin &lt;= price_point[0] &lt; date_range.end\n            ]\n        return all_prices\n\n    def account_is_closed(self, account_name: str) -&gt; bool:\n        \"\"\"Check if the account is closed.\n\n        Args:\n            account_name: An account name.\n\n        Returns:\n            True if the account is closed before the end date of the current\n            time filter.\n        \"\"\"\n        date_range = self.date_range\n        close_date = self.ledger.accounts[account_name].close_date\n        if close_date is None:\n            return False\n        return close_date &lt; date_range.end if date_range else True\n\n    def paginate_journal(\n        self,\n        page: int,\n        per_page: int = 1000,\n        order: Literal[\"asc\", \"desc\"] = \"desc\",\n    ) -&gt; JournalPage | None:\n        \"\"\"Get entries for a journal page with pagination info.\n\n        Args:\n            page: Page number (1-indexed).\n            order: Datewise order to sort in\n            per_page: Number of entries per page.\n\n        Returns:\n            A JournalPage, containing a list of entries as (global_index,\n            directive) tuples in reverse chronological order and the total\n            number of pages.\n        \"\"\"\n        if (\n            self._pages is None\n            or self._pages[0] != per_page\n            or self._pages[1] != order\n        ):\n            pages: list[Sequence[tuple[int, Directive]]] = []\n            enumerated = list(enumerate(self.entries_without_prices))\n            entries = (\n                iter(enumerated) if order == \"asc\" else reversed(enumerated)\n            )\n            while batch := tuple(islice(entries, per_page)):\n                pages.append(batch)\n            if not pages:\n                pages.append([])\n            self._pages = (per_page, order, pages)\n        _per_pages, _order, pages = self._pages\n        total = len(pages)\n        if page &gt; total:\n            return None\n        return JournalPage(pages[page - 1], total)\n</code></pre>"},{"location":"api/#rustfava.core.FilteredLedger.end_date","title":"<code>end_date</code>  <code>property</code>","text":"<p>The date to use for prices.</p>"},{"location":"api/#rustfava.core.FilteredLedger.entries_with_all_prices","title":"<code>entries_with_all_prices</code>  <code>cached</code> <code>property</code>","text":"<p>The filtered entries, with all prices added back in for queries.</p>"},{"location":"api/#rustfava.core.FilteredLedger.entries_without_prices","title":"<code>entries_without_prices</code>  <code>cached</code> <code>property</code>","text":"<p>The filtered entries, without prices for journals.</p>"},{"location":"api/#rustfava.core.FilteredLedger.root_tree","title":"<code>root_tree</code>  <code>cached</code> <code>property</code>","text":"<p>A root tree.</p>"},{"location":"api/#rustfava.core.FilteredLedger.root_tree_closed","title":"<code>root_tree_closed</code>  <code>cached</code> <code>property</code>","text":"<p>A root tree for the balance sheet.</p>"},{"location":"api/#rustfava.core.FilteredLedger.__init__","title":"<code>__init__(ledger, *, account=None, filter=None, time=None)</code>","text":"<p>Create a filtered view of a ledger.</p> <p>Parameters:</p> Name Type Description Default <code>ledger</code> <code>RustfavaLedger</code> <p>The ledger to filter.</p> required <code>account</code> <code>str | None</code> <p>The account filter.</p> <code>None</code> <code>filter</code> <code>str | None</code> <p>The advanced filter.</p> <code>None</code> <code>time</code> <code>str | None</code> <p>The time filter.</p> <code>None</code> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>def __init__(\n    self,\n    ledger: RustfavaLedger,\n    *,\n    account: str | None = None,\n    filter: str | None = None,  # noqa: A002\n    time: str | None = None,\n) -&gt; None:\n    \"\"\"Create a filtered view of a ledger.\n\n    Args:\n        ledger: The ledger to filter.\n        account: The account filter.\n        filter: The advanced filter.\n        time: The time filter.\n    \"\"\"\n    self.ledger = ledger\n    self.date_range: DateRange | None = None\n    self._pages: (\n        tuple[\n            int,\n            Literal[\"asc\", \"desc\"],\n            list[Sequence[tuple[int, Directive]]],\n        ]\n        | None\n    ) = None\n\n    entries = ledger.all_entries\n    if account:\n        entries = AccountFilter(account).apply(entries)\n    if filter and filter.strip():\n        entries = AdvancedFilter(filter.strip()).apply(entries)\n    if time:\n        time_filter = TimeFilter(ledger.options, ledger.fava_options, time)\n        entries = time_filter.apply(entries)\n        self.date_range = time_filter.date_range\n    self.entries = entries\n\n    if self.date_range:\n        self._date_first = self.date_range.begin\n        self._date_last = self.date_range.end\n        return\n\n    self._date_first = None\n    self._date_last = None\n    for entry in self.entries:\n        if isinstance(entry, Transaction):\n            self._date_first = entry.date\n            break\n    for entry in reversed(self.entries):\n        if isinstance(entry, (Transaction, Price)):\n            self._date_last = entry.date + timedelta(1)\n            break\n</code></pre>"},{"location":"api/#rustfava.core.FilteredLedger.interval_ranges","title":"<code>interval_ranges(interval)</code>","text":"<p>Yield date ranges corresponding to interval boundaries.</p> <p>Parameters:</p> Name Type Description Default <code>interval</code> <code>Interval</code> <p>The interval to yield ranges for.</p> required Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>def interval_ranges(self, interval: Interval) -&gt; Sequence[DateRange]:\n    \"\"\"Yield date ranges corresponding to interval boundaries.\n\n    Args:\n        interval: The interval to yield ranges for.\n    \"\"\"\n    if not self._date_first or not self._date_last:\n        return []\n    complete = not self.date_range\n    return dateranges(\n        self._date_first, self._date_last, interval, complete=complete\n    )\n</code></pre>"},{"location":"api/#rustfava.core.FilteredLedger.prices","title":"<code>prices(base, quote)</code>","text":"<p>List all prices for a pair of commodities.</p> <p>Parameters:</p> Name Type Description Default <code>base</code> <code>str</code> <p>The price base.</p> required <code>quote</code> <code>str</code> <p>The price quote.</p> required Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>def prices(self, base: str, quote: str) -&gt; Sequence[tuple[date, Decimal]]:\n    \"\"\"List all prices for a pair of commodities.\n\n    Args:\n        base: The price base.\n        quote: The price quote.\n    \"\"\"\n    all_prices = self.ledger.prices.get_all_prices((base, quote))\n    if all_prices is None:\n        return []\n\n    date_range = self.date_range\n    if date_range:\n        return [\n            price_point\n            for price_point in all_prices\n            if date_range.begin &lt;= price_point[0] &lt; date_range.end\n        ]\n    return all_prices\n</code></pre>"},{"location":"api/#rustfava.core.FilteredLedger.account_is_closed","title":"<code>account_is_closed(account_name)</code>","text":"<p>Check if the account is closed.</p> <p>Parameters:</p> Name Type Description Default <code>account_name</code> <code>str</code> <p>An account name.</p> required <p>Returns:</p> Type Description <code>bool</code> <p>True if the account is closed before the end date of the current</p> <code>bool</code> <p>time filter.</p> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>def account_is_closed(self, account_name: str) -&gt; bool:\n    \"\"\"Check if the account is closed.\n\n    Args:\n        account_name: An account name.\n\n    Returns:\n        True if the account is closed before the end date of the current\n        time filter.\n    \"\"\"\n    date_range = self.date_range\n    close_date = self.ledger.accounts[account_name].close_date\n    if close_date is None:\n        return False\n    return close_date &lt; date_range.end if date_range else True\n</code></pre>"},{"location":"api/#rustfava.core.FilteredLedger.paginate_journal","title":"<code>paginate_journal(page, per_page=1000, order='desc')</code>","text":"<p>Get entries for a journal page with pagination info.</p> <p>Parameters:</p> Name Type Description Default <code>page</code> <code>int</code> <p>Page number (1-indexed).</p> required <code>order</code> <code>Literal['asc', 'desc']</code> <p>Datewise order to sort in</p> <code>'desc'</code> <code>per_page</code> <code>int</code> <p>Number of entries per page.</p> <code>1000</code> <p>Returns:</p> Type Description <code>JournalPage | None</code> <p>A JournalPage, containing a list of entries as (global_index,</p> <code>JournalPage | None</code> <p>directive) tuples in reverse chronological order and the total</p> <code>JournalPage | None</code> <p>number of pages.</p> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>def paginate_journal(\n    self,\n    page: int,\n    per_page: int = 1000,\n    order: Literal[\"asc\", \"desc\"] = \"desc\",\n) -&gt; JournalPage | None:\n    \"\"\"Get entries for a journal page with pagination info.\n\n    Args:\n        page: Page number (1-indexed).\n        order: Datewise order to sort in\n        per_page: Number of entries per page.\n\n    Returns:\n        A JournalPage, containing a list of entries as (global_index,\n        directive) tuples in reverse chronological order and the total\n        number of pages.\n    \"\"\"\n    if (\n        self._pages is None\n        or self._pages[0] != per_page\n        or self._pages[1] != order\n    ):\n        pages: list[Sequence[tuple[int, Directive]]] = []\n        enumerated = list(enumerate(self.entries_without_prices))\n        entries = (\n            iter(enumerated) if order == \"asc\" else reversed(enumerated)\n        )\n        while batch := tuple(islice(entries, per_page)):\n            pages.append(batch)\n        if not pages:\n            pages.append([])\n        self._pages = (per_page, order, pages)\n    _per_pages, _order, pages = self._pages\n    total = len(pages)\n    if page &gt; total:\n        return None\n    return JournalPage(pages[page - 1], total)\n</code></pre>"},{"location":"api/#rustfava.core.RustfavaLedger","title":"<code>RustfavaLedger</code>","text":"<p>Interface for a Beancount ledger.</p> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>class RustfavaLedger:\n    \"\"\"Interface for a Beancount ledger.\"\"\"\n\n    __slots__ = (\n        \"_is_encrypted\",\n        \"accounts\",\n        \"accounts\",\n        \"all_entries\",\n        \"all_entries_by_type\",\n        \"attributes\",\n        \"beancount_file_path\",\n        \"budgets\",\n        \"charts\",\n        \"commodities\",\n        \"extensions\",\n        \"fava_options\",\n        \"fava_options_errors\",\n        \"file\",\n        \"format_decimal\",\n        \"get_entry\",\n        \"get_filtered\",\n        \"ingest\",\n        \"load_errors\",\n        \"misc\",\n        \"options\",\n        \"prices\",\n        \"query_shell\",\n        \"watcher\",\n    )\n\n    #: List of all (unfiltered) entries.\n    all_entries: Sequence[Directive]\n\n    #: A list of all errors reported by Beancount.\n    load_errors: Sequence[BeancountError]\n\n    #: The Beancount options map.\n    options: BeancountOptions\n\n    #: A dict with all of Fava's option values.\n    fava_options: RustfavaOptions\n\n    #: A list of all errors from parsing the custom options.\n    fava_options_errors: Sequence[BeancountError]\n\n    #: The price map.\n    prices: RustfavaPriceMap\n\n    #: Dict of list of all (unfiltered) entries by type.\n    all_entries_by_type: EntriesByType\n\n    #: A :class:`.AccountDict` module - details about the accounts.\n    accounts: AccountDict\n\n    #: An :class:`AttributesModule` instance.\n    attributes: AttributesModule\n\n    #: A :class:`.BudgetModule` instance.\n    budgets: BudgetModule\n\n    #: A :class:`.ChartModule` instance.\n    charts: ChartModule\n\n    #: A :class:`.CommoditiesModule` instance.\n    commodities: CommoditiesModule\n\n    #: A :class:`.ExtensionModule` instance.\n    extensions: ExtensionModule\n\n    #: A :class:`.FileModule` instance.\n    file: FileModule\n\n    #: A :class:`.DecimalFormatModule` instance.\n    format_decimal: DecimalFormatModule\n\n    #: A :class:`.IngestModule` instance.\n    ingest: IngestModule\n\n    #: A :class:`.FavaMisc` instance.\n    misc: FavaMisc\n\n    #: A :class:`.QueryShell` instance.\n    query_shell: QueryShell\n\n    def __init__(self, path: str, *, poll_watcher: bool = False) -&gt; None:\n        \"\"\"Create an interface for a Beancount ledger.\n\n        Arguments:\n            path: Path to the main Beancount file.\n            poll_watcher: Whether to use the polling file watcher.\n        \"\"\"\n        #: The path to the main Beancount file.\n        self.beancount_file_path = path\n        self._is_encrypted = is_encrypted_file(path)\n        self.get_filtered = lru_cache(maxsize=16)(self._get_filtered)\n        self.get_entry = lru_cache(maxsize=16)(self._get_entry)\n\n        self.accounts = AccountDict(self)\n        self.attributes = AttributesModule(self)\n        self.budgets = BudgetModule(self)\n        self.charts = ChartModule(self)\n        self.commodities = CommoditiesModule(self)\n        self.extensions = ExtensionModule(self)\n        self.file = FileModule(self)\n        self.format_decimal = DecimalFormatModule(self)\n        self.ingest = IngestModule(self)\n        self.misc = FavaMisc(self)\n        self.query_shell = QueryShell(self)\n\n        self.watcher = WatchfilesWatcher() if not poll_watcher else Watcher()\n\n        self.load_file()\n\n    def load_file(self) -&gt; None:\n        \"\"\"Load the main file and all included files and set attributes.\"\"\"\n        self.all_entries, self.load_errors, self.options = load_uncached(\n            self.beancount_file_path,\n            is_encrypted=self._is_encrypted,\n        )\n        self.get_filtered.cache_clear()\n        self.get_entry.cache_clear()\n\n        self.all_entries_by_type = group_entries_by_type(self.all_entries)\n        self.prices = RustfavaPriceMap(self.all_entries_by_type.Price)\n\n        self.fava_options, self.fava_options_errors = parse_options(\n            self.all_entries_by_type.Custom,\n        )\n\n        if self._is_encrypted:  # pragma: no cover\n            pass\n        else:\n            self.watcher.update(*self.paths_to_watch())\n\n        # Call load_file of all modules.\n        self.accounts.load_file()\n        self.attributes.load_file()\n        self.budgets.load_file()\n        self.charts.load_file()\n        self.commodities.load_file()\n        self.extensions.load_file()\n        self.file.load_file()\n        self.format_decimal.load_file()\n        self.misc.load_file()\n        self.query_shell.load_file()\n        self.ingest.load_file()\n\n        self.extensions.after_load_file()\n\n    def _get_filtered(\n        self,\n        account: str | None = None,\n        filter: str | None = None,  # noqa: A002\n        time: str | None = None,\n    ) -&gt; FilteredLedger:\n        \"\"\"Filter the ledger.\n\n        Args:\n            account: The account filter.\n            filter: The advanced filter.\n            time: The time filter.\n        \"\"\"\n        return FilteredLedger(\n            ledger=self, account=account, filter=filter, time=time\n        )\n\n    @property\n    def mtime(self) -&gt; int:\n        \"\"\"The timestamp to the latest change of the underlying files.\"\"\"\n        return self.watcher.last_checked\n\n    @property\n    def errors(self) -&gt; Sequence[BeancountError]:\n        \"\"\"The errors that the Beancount loading plus Fava module errors.\"\"\"\n        return [\n            *self.load_errors,\n            *self.fava_options_errors,\n            *self.budgets.errors,\n            *self.extensions.errors,\n            *self.misc.errors,\n            *self.ingest.errors,\n        ]\n\n    @property\n    def root_accounts(self) -&gt; tuple[str, str, str, str, str]:\n        \"\"\"The five root accounts.\"\"\"\n        options = self.options\n        return (\n            options[\"name_assets\"],\n            options[\"name_liabilities\"],\n            options[\"name_equity\"],\n            options[\"name_income\"],\n            options[\"name_expenses\"],\n        )\n\n    def join_path(self, *args: str) -&gt; Path:\n        \"\"\"Path relative to the directory of the ledger.\"\"\"\n        return Path(self.beancount_file_path).parent.joinpath(*args).resolve()\n\n    def paths_to_watch(self) -&gt; tuple[Sequence[Path], Sequence[Path]]:\n        \"\"\"Get paths to included files and document directories.\n\n        Returns:\n            A tuple (files, directories).\n        \"\"\"\n        files = [Path(i) for i in self.options[\"include\"]]\n        if self.ingest.module_path:\n            files.append(self.ingest.module_path)\n        return (\n            files,\n            [\n                self.join_path(path, account)\n                for account in self.root_accounts\n                for path in self.options[\"documents\"]\n            ],\n        )\n\n    def changed(self) -&gt; bool:\n        \"\"\"Check if the file needs to be reloaded.\n\n        Returns:\n            True if a change in one of the included files or a change in a\n            document folder was detected and the file has been reloaded.\n        \"\"\"\n        # We can't reload an encrypted file, so act like it never changes.\n        if self._is_encrypted:  # pragma: no cover\n            return False\n        changed = self.watcher.check()\n        if changed:\n            self.load_file()\n        return changed\n\n    def interval_balances(\n        self,\n        filtered: FilteredLedger,\n        interval: Interval,\n        account_name: str,\n        *,\n        accumulate: bool = False,\n    ) -&gt; tuple[Sequence[Tree], Sequence[DateRange]]:\n        \"\"\"Balances by interval.\n\n        Arguments:\n            filtered: The currently filtered ledger.\n            interval: An interval.\n            account_name: An account name.\n            accumulate: A boolean, ``True`` if the balances for an interval\n                should include all entries up to the end of the interval.\n\n        Returns:\n            A pair of a list of Tree instances and the intervals.\n        \"\"\"\n        min_accounts = [\n            account\n            for account in self.accounts\n            if account.startswith(account_name)\n        ]\n\n        interval_ranges = list(reversed(filtered.interval_ranges(interval)))\n        interval_balances = [\n            Tree(\n                slice_entry_dates(\n                    filtered.entries,\n                    date.min if accumulate else date_range.begin,\n                    date_range.end,\n                ),\n                min_accounts,\n            )\n            for date_range in interval_ranges\n        ]\n\n        return interval_balances, interval_ranges\n\n    @listify\n    def account_journal(\n        self,\n        filtered: FilteredLedger,\n        account_name: str,\n        conversion: str | Conversion,\n        *,\n        with_children: bool,\n    ) -&gt; Iterable[\n        tuple[int, Directive, SimpleCounterInventory, SimpleCounterInventory]\n    ]:\n        \"\"\"Journal for an account.\n\n        Args:\n            filtered: The currently filtered ledger.\n            account_name: An account name.\n            conversion: The conversion to use.\n            with_children: Whether to include postings of subaccounts of\n                           the account.\n\n        Yields:\n            Tuples of ``(index, entry, change, balance)``.\n        \"\"\"\n        conv = conversion_from_str(conversion)\n        relevant_account = account_tester(\n            account_name, with_children=with_children\n        )\n\n        prices = self.prices\n        balance = CounterInventory()\n        for index, entry in enumerate(filtered.entries_without_prices):\n            change = CounterInventory()\n            entry_is_relevant = False\n            postings = getattr(entry, \"postings\", None)\n            if postings is not None:\n                for posting in postings:\n                    if relevant_account(posting.account):\n                        entry_is_relevant = True\n                        balance.add_position(posting)\n                        change.add_position(posting)\n            elif any(relevant_account(a) for a in get_entry_accounts(entry)):\n                entry_is_relevant = True\n\n            if entry_is_relevant:\n                yield (\n                    index,\n                    entry,\n                    conv.apply(change, prices, entry.date),\n                    conv.apply(balance, prices, entry.date),\n                )\n\n    def _get_entry(self, entry_hash: str) -&gt; Directive:\n        \"\"\"Find an entry.\n\n        Arguments:\n            entry_hash: Hash of the entry.\n\n        Returns:\n            The entry with the given hash.\n\n        Raises:\n            EntryNotFoundForHashError: If there is no entry for the given hash.\n        \"\"\"\n        try:\n            return next(\n                entry\n                for entry in self.all_entries\n                if entry_hash == hash_entry(entry)\n            )\n        except StopIteration as exc:\n            raise EntryNotFoundForHashError(entry_hash) from exc\n\n    def context(\n        self,\n        entry_hash: str,\n    ) -&gt; tuple[\n        Directive,\n        Mapping[str, Sequence[str]] | None,\n        Mapping[str, Sequence[str]] | None,\n    ]:\n        \"\"\"Context for an entry.\n\n        Arguments:\n            entry_hash: Hash of entry.\n\n        Returns:\n            A tuple ``(entry, before, after, source_slice, sha256sum)`` of the\n            (unique) entry with the given ``entry_hash``. If the entry is a\n            Balance or Transaction then ``before`` and ``after`` contain\n            the balances before and after the entry of the affected accounts.\n        \"\"\"\n        entry = self.get_entry(entry_hash)\n\n        if not isinstance(entry, (Balance, Transaction)):\n            return entry, None, None\n\n        entry_accounts = get_entry_accounts(entry)\n        balances = {account: CounterInventory() for account in entry_accounts}\n        for entry_ in takewhile(lambda e: e is not entry, self.all_entries):\n            if isinstance(entry_, Transaction):\n                for posting in entry_.postings:\n                    balance = balances.get(posting.account, None)\n                    if balance is not None:\n                        balance.add_position(posting)\n\n        def visualise(inv: CounterInventory) -&gt; Sequence[str]:\n            return inv.to_strings()\n\n        before = {acc: visualise(inv) for acc, inv in balances.items()}\n\n        if isinstance(entry, Balance):\n            return entry, before, None\n\n        for posting in entry.postings:\n            balances[posting.account].add_position(posting)\n        after = {acc: visualise(inv) for acc, inv in balances.items()}\n        return entry, before, after\n\n    def commodity_pairs(self) -&gt; Sequence[tuple[str, str]]:\n        \"\"\"List pairs of commodities.\n\n        Returns:\n            A list of pairs of commodities. Pairs of operating currencies will\n            be given in both directions not just in the one found in file.\n        \"\"\"\n        return self.prices.commodity_pairs(self.options[\"operating_currency\"])\n\n    def statement_path(self, entry_hash: str, metadata_key: str) -&gt; str:\n        \"\"\"Get the path for a statement found in the specified entry.\n\n        The entry that we look up should contain a path to a document (absolute\n        or relative to the filename of the entry) or just its basename. We go\n        through all documents and match on the full path or if one of the\n        documents with a matching account has a matching file basename.\n\n        Arguments:\n            entry_hash: Hash of the entry containing the path in its metadata.\n            metadata_key: The key that the path should be in.\n\n        Returns:\n            The filename of the matching document entry.\n\n        Raises:\n            StatementMetadataInvalidError: If the metadata at the given key is\n                                           invalid.\n            StatementNotFoundError: If no matching document is found.\n        \"\"\"\n        entry = self.get_entry(entry_hash)\n        value = entry.meta.get(metadata_key, None)\n        if not isinstance(value, str):\n            raise StatementMetadataInvalidError(metadata_key)\n\n        accounts = set(get_entry_accounts(entry))\n        filename, _ = get_position(entry)\n        full_path = (Path(filename).parent / value).resolve()\n        for document in self.all_entries_by_type.Document:\n            document_path = Path(document.filename)\n            if document_path == full_path:\n                return document.filename\n            if document.account in accounts and document_path.name == value:\n                return document.filename\n\n        raise StatementNotFoundError\n\n    group_entries_by_type = staticmethod(group_entries_by_type)\n</code></pre>"},{"location":"api/#rustfava.core.RustfavaLedger.mtime","title":"<code>mtime</code>  <code>property</code>","text":"<p>The timestamp to the latest change of the underlying files.</p>"},{"location":"api/#rustfava.core.RustfavaLedger.errors","title":"<code>errors</code>  <code>property</code>","text":"<p>The errors that the Beancount loading plus Fava module errors.</p>"},{"location":"api/#rustfava.core.RustfavaLedger.root_accounts","title":"<code>root_accounts</code>  <code>property</code>","text":"<p>The five root accounts.</p>"},{"location":"api/#rustfava.core.RustfavaLedger.__init__","title":"<code>__init__(path, *, poll_watcher=False)</code>","text":"<p>Create an interface for a Beancount ledger.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>Path to the main Beancount file.</p> required <code>poll_watcher</code> <code>bool</code> <p>Whether to use the polling file watcher.</p> <code>False</code> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>def __init__(self, path: str, *, poll_watcher: bool = False) -&gt; None:\n    \"\"\"Create an interface for a Beancount ledger.\n\n    Arguments:\n        path: Path to the main Beancount file.\n        poll_watcher: Whether to use the polling file watcher.\n    \"\"\"\n    #: The path to the main Beancount file.\n    self.beancount_file_path = path\n    self._is_encrypted = is_encrypted_file(path)\n    self.get_filtered = lru_cache(maxsize=16)(self._get_filtered)\n    self.get_entry = lru_cache(maxsize=16)(self._get_entry)\n\n    self.accounts = AccountDict(self)\n    self.attributes = AttributesModule(self)\n    self.budgets = BudgetModule(self)\n    self.charts = ChartModule(self)\n    self.commodities = CommoditiesModule(self)\n    self.extensions = ExtensionModule(self)\n    self.file = FileModule(self)\n    self.format_decimal = DecimalFormatModule(self)\n    self.ingest = IngestModule(self)\n    self.misc = FavaMisc(self)\n    self.query_shell = QueryShell(self)\n\n    self.watcher = WatchfilesWatcher() if not poll_watcher else Watcher()\n\n    self.load_file()\n</code></pre>"},{"location":"api/#rustfava.core.RustfavaLedger.load_file","title":"<code>load_file()</code>","text":"<p>Load the main file and all included files and set attributes.</p> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>def load_file(self) -&gt; None:\n    \"\"\"Load the main file and all included files and set attributes.\"\"\"\n    self.all_entries, self.load_errors, self.options = load_uncached(\n        self.beancount_file_path,\n        is_encrypted=self._is_encrypted,\n    )\n    self.get_filtered.cache_clear()\n    self.get_entry.cache_clear()\n\n    self.all_entries_by_type = group_entries_by_type(self.all_entries)\n    self.prices = RustfavaPriceMap(self.all_entries_by_type.Price)\n\n    self.fava_options, self.fava_options_errors = parse_options(\n        self.all_entries_by_type.Custom,\n    )\n\n    if self._is_encrypted:  # pragma: no cover\n        pass\n    else:\n        self.watcher.update(*self.paths_to_watch())\n\n    # Call load_file of all modules.\n    self.accounts.load_file()\n    self.attributes.load_file()\n    self.budgets.load_file()\n    self.charts.load_file()\n    self.commodities.load_file()\n    self.extensions.load_file()\n    self.file.load_file()\n    self.format_decimal.load_file()\n    self.misc.load_file()\n    self.query_shell.load_file()\n    self.ingest.load_file()\n\n    self.extensions.after_load_file()\n</code></pre>"},{"location":"api/#rustfava.core.RustfavaLedger.join_path","title":"<code>join_path(*args)</code>","text":"<p>Path relative to the directory of the ledger.</p> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>def join_path(self, *args: str) -&gt; Path:\n    \"\"\"Path relative to the directory of the ledger.\"\"\"\n    return Path(self.beancount_file_path).parent.joinpath(*args).resolve()\n</code></pre>"},{"location":"api/#rustfava.core.RustfavaLedger.paths_to_watch","title":"<code>paths_to_watch()</code>","text":"<p>Get paths to included files and document directories.</p> <p>Returns:</p> Type Description <code>tuple[Sequence[Path], Sequence[Path]]</code> <p>A tuple (files, directories).</p> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>def paths_to_watch(self) -&gt; tuple[Sequence[Path], Sequence[Path]]:\n    \"\"\"Get paths to included files and document directories.\n\n    Returns:\n        A tuple (files, directories).\n    \"\"\"\n    files = [Path(i) for i in self.options[\"include\"]]\n    if self.ingest.module_path:\n        files.append(self.ingest.module_path)\n    return (\n        files,\n        [\n            self.join_path(path, account)\n            for account in self.root_accounts\n            for path in self.options[\"documents\"]\n        ],\n    )\n</code></pre>"},{"location":"api/#rustfava.core.RustfavaLedger.changed","title":"<code>changed()</code>","text":"<p>Check if the file needs to be reloaded.</p> <p>Returns:</p> Type Description <code>bool</code> <p>True if a change in one of the included files or a change in a</p> <code>bool</code> <p>document folder was detected and the file has been reloaded.</p> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>def changed(self) -&gt; bool:\n    \"\"\"Check if the file needs to be reloaded.\n\n    Returns:\n        True if a change in one of the included files or a change in a\n        document folder was detected and the file has been reloaded.\n    \"\"\"\n    # We can't reload an encrypted file, so act like it never changes.\n    if self._is_encrypted:  # pragma: no cover\n        return False\n    changed = self.watcher.check()\n    if changed:\n        self.load_file()\n    return changed\n</code></pre>"},{"location":"api/#rustfava.core.RustfavaLedger.interval_balances","title":"<code>interval_balances(filtered, interval, account_name, *, accumulate=False)</code>","text":"<p>Balances by interval.</p> <p>Parameters:</p> Name Type Description Default <code>filtered</code> <code>FilteredLedger</code> <p>The currently filtered ledger.</p> required <code>interval</code> <code>Interval</code> <p>An interval.</p> required <code>account_name</code> <code>str</code> <p>An account name.</p> required <code>accumulate</code> <code>bool</code> <p>A boolean, <code>True</code> if the balances for an interval should include all entries up to the end of the interval.</p> <code>False</code> <p>Returns:</p> Type Description <code>tuple[Sequence[Tree], Sequence[DateRange]]</code> <p>A pair of a list of Tree instances and the intervals.</p> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>def interval_balances(\n    self,\n    filtered: FilteredLedger,\n    interval: Interval,\n    account_name: str,\n    *,\n    accumulate: bool = False,\n) -&gt; tuple[Sequence[Tree], Sequence[DateRange]]:\n    \"\"\"Balances by interval.\n\n    Arguments:\n        filtered: The currently filtered ledger.\n        interval: An interval.\n        account_name: An account name.\n        accumulate: A boolean, ``True`` if the balances for an interval\n            should include all entries up to the end of the interval.\n\n    Returns:\n        A pair of a list of Tree instances and the intervals.\n    \"\"\"\n    min_accounts = [\n        account\n        for account in self.accounts\n        if account.startswith(account_name)\n    ]\n\n    interval_ranges = list(reversed(filtered.interval_ranges(interval)))\n    interval_balances = [\n        Tree(\n            slice_entry_dates(\n                filtered.entries,\n                date.min if accumulate else date_range.begin,\n                date_range.end,\n            ),\n            min_accounts,\n        )\n        for date_range in interval_ranges\n    ]\n\n    return interval_balances, interval_ranges\n</code></pre>"},{"location":"api/#rustfava.core.RustfavaLedger.account_journal","title":"<code>account_journal(filtered, account_name, conversion, *, with_children)</code>","text":"<p>Journal for an account.</p> <p>Parameters:</p> Name Type Description Default <code>filtered</code> <code>FilteredLedger</code> <p>The currently filtered ledger.</p> required <code>account_name</code> <code>str</code> <p>An account name.</p> required <code>conversion</code> <code>str | Conversion</code> <p>The conversion to use.</p> required <code>with_children</code> <code>bool</code> <p>Whether to include postings of subaccounts of            the account.</p> required <p>Yields:</p> Type Description <code>Iterable[tuple[int, Directive, SimpleCounterInventory, SimpleCounterInventory]]</code> <p>Tuples of <code>(index, entry, change, balance)</code>.</p> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>@listify\ndef account_journal(\n    self,\n    filtered: FilteredLedger,\n    account_name: str,\n    conversion: str | Conversion,\n    *,\n    with_children: bool,\n) -&gt; Iterable[\n    tuple[int, Directive, SimpleCounterInventory, SimpleCounterInventory]\n]:\n    \"\"\"Journal for an account.\n\n    Args:\n        filtered: The currently filtered ledger.\n        account_name: An account name.\n        conversion: The conversion to use.\n        with_children: Whether to include postings of subaccounts of\n                       the account.\n\n    Yields:\n        Tuples of ``(index, entry, change, balance)``.\n    \"\"\"\n    conv = conversion_from_str(conversion)\n    relevant_account = account_tester(\n        account_name, with_children=with_children\n    )\n\n    prices = self.prices\n    balance = CounterInventory()\n    for index, entry in enumerate(filtered.entries_without_prices):\n        change = CounterInventory()\n        entry_is_relevant = False\n        postings = getattr(entry, \"postings\", None)\n        if postings is not None:\n            for posting in postings:\n                if relevant_account(posting.account):\n                    entry_is_relevant = True\n                    balance.add_position(posting)\n                    change.add_position(posting)\n        elif any(relevant_account(a) for a in get_entry_accounts(entry)):\n            entry_is_relevant = True\n\n        if entry_is_relevant:\n            yield (\n                index,\n                entry,\n                conv.apply(change, prices, entry.date),\n                conv.apply(balance, prices, entry.date),\n            )\n</code></pre>"},{"location":"api/#rustfava.core.RustfavaLedger.context","title":"<code>context(entry_hash)</code>","text":"<p>Context for an entry.</p> <p>Parameters:</p> Name Type Description Default <code>entry_hash</code> <code>str</code> <p>Hash of entry.</p> required <p>Returns:</p> Type Description <code>Directive</code> <p>A tuple <code>(entry, before, after, source_slice, sha256sum)</code> of the</p> <code>Mapping[str, Sequence[str]] | None</code> <p>(unique) entry with the given <code>entry_hash</code>. If the entry is a</p> <code>Mapping[str, Sequence[str]] | None</code> <p>Balance or Transaction then <code>before</code> and <code>after</code> contain</p> <code>tuple[Directive, Mapping[str, Sequence[str]] | None, Mapping[str, Sequence[str]] | None]</code> <p>the balances before and after the entry of the affected accounts.</p> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>def context(\n    self,\n    entry_hash: str,\n) -&gt; tuple[\n    Directive,\n    Mapping[str, Sequence[str]] | None,\n    Mapping[str, Sequence[str]] | None,\n]:\n    \"\"\"Context for an entry.\n\n    Arguments:\n        entry_hash: Hash of entry.\n\n    Returns:\n        A tuple ``(entry, before, after, source_slice, sha256sum)`` of the\n        (unique) entry with the given ``entry_hash``. If the entry is a\n        Balance or Transaction then ``before`` and ``after`` contain\n        the balances before and after the entry of the affected accounts.\n    \"\"\"\n    entry = self.get_entry(entry_hash)\n\n    if not isinstance(entry, (Balance, Transaction)):\n        return entry, None, None\n\n    entry_accounts = get_entry_accounts(entry)\n    balances = {account: CounterInventory() for account in entry_accounts}\n    for entry_ in takewhile(lambda e: e is not entry, self.all_entries):\n        if isinstance(entry_, Transaction):\n            for posting in entry_.postings:\n                balance = balances.get(posting.account, None)\n                if balance is not None:\n                    balance.add_position(posting)\n\n    def visualise(inv: CounterInventory) -&gt; Sequence[str]:\n        return inv.to_strings()\n\n    before = {acc: visualise(inv) for acc, inv in balances.items()}\n\n    if isinstance(entry, Balance):\n        return entry, before, None\n\n    for posting in entry.postings:\n        balances[posting.account].add_position(posting)\n    after = {acc: visualise(inv) for acc, inv in balances.items()}\n    return entry, before, after\n</code></pre>"},{"location":"api/#rustfava.core.RustfavaLedger.commodity_pairs","title":"<code>commodity_pairs()</code>","text":"<p>List pairs of commodities.</p> <p>Returns:</p> Type Description <code>Sequence[tuple[str, str]]</code> <p>A list of pairs of commodities. Pairs of operating currencies will</p> <code>Sequence[tuple[str, str]]</code> <p>be given in both directions not just in the one found in file.</p> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>def commodity_pairs(self) -&gt; Sequence[tuple[str, str]]:\n    \"\"\"List pairs of commodities.\n\n    Returns:\n        A list of pairs of commodities. Pairs of operating currencies will\n        be given in both directions not just in the one found in file.\n    \"\"\"\n    return self.prices.commodity_pairs(self.options[\"operating_currency\"])\n</code></pre>"},{"location":"api/#rustfava.core.RustfavaLedger.statement_path","title":"<code>statement_path(entry_hash, metadata_key)</code>","text":"<p>Get the path for a statement found in the specified entry.</p> <p>The entry that we look up should contain a path to a document (absolute or relative to the filename of the entry) or just its basename. We go through all documents and match on the full path or if one of the documents with a matching account has a matching file basename.</p> <p>Parameters:</p> Name Type Description Default <code>entry_hash</code> <code>str</code> <p>Hash of the entry containing the path in its metadata.</p> required <code>metadata_key</code> <code>str</code> <p>The key that the path should be in.</p> required <p>Returns:</p> Type Description <code>str</code> <p>The filename of the matching document entry.</p> <p>Raises:</p> Type Description <code>StatementMetadataInvalidError</code> <p>If the metadata at the given key is                            invalid.</p> <code>StatementNotFoundError</code> <p>If no matching document is found.</p> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>def statement_path(self, entry_hash: str, metadata_key: str) -&gt; str:\n    \"\"\"Get the path for a statement found in the specified entry.\n\n    The entry that we look up should contain a path to a document (absolute\n    or relative to the filename of the entry) or just its basename. We go\n    through all documents and match on the full path or if one of the\n    documents with a matching account has a matching file basename.\n\n    Arguments:\n        entry_hash: Hash of the entry containing the path in its metadata.\n        metadata_key: The key that the path should be in.\n\n    Returns:\n        The filename of the matching document entry.\n\n    Raises:\n        StatementMetadataInvalidError: If the metadata at the given key is\n                                       invalid.\n        StatementNotFoundError: If no matching document is found.\n    \"\"\"\n    entry = self.get_entry(entry_hash)\n    value = entry.meta.get(metadata_key, None)\n    if not isinstance(value, str):\n        raise StatementMetadataInvalidError(metadata_key)\n\n    accounts = set(get_entry_accounts(entry))\n    filename, _ = get_position(entry)\n    full_path = (Path(filename).parent / value).resolve()\n    for document in self.all_entries_by_type.Document:\n        document_path = Path(document.filename)\n        if document_path == full_path:\n            return document.filename\n        if document.account in accounts and document_path.name == value:\n            return document.filename\n\n    raise StatementNotFoundError\n</code></pre>"},{"location":"api/#rustfava.core.accounts","title":"<code>accounts</code>","text":"<p>Account close date and metadata.</p>"},{"location":"api/#rustfava.core.accounts.LastEntry","title":"<code>LastEntry</code>  <code>dataclass</code>","text":"<p>Date and hash of the last entry for an account.</p> Source code in <code>src/rustfava/core/accounts.py</code> <pre><code>@dataclass(frozen=True)\nclass LastEntry:\n    \"\"\"Date and hash of the last entry for an account.\"\"\"\n\n    #: The entry date.\n    date: datetime.date\n\n    #: The entry hash.\n    entry_hash: str\n</code></pre>"},{"location":"api/#rustfava.core.accounts.AccountData","title":"<code>AccountData</code>  <code>dataclass</code>","text":"<p>Holds information about an account.</p> Source code in <code>src/rustfava/core/accounts.py</code> <pre><code>@dataclass\nclass AccountData:\n    \"\"\"Holds information about an account.\"\"\"\n\n    #: The date on which this account is closed (or datetime.date.max).\n    close_date: datetime.date | None = None\n\n    #: The metadata of the Open entry of this account.\n    meta: Meta = field(default_factory=dict)\n\n    #: Uptodate status. Is only computed if the account has a\n    #: \"fava-uptodate-indication\" meta attribute.\n    uptodate_status: Literal[\"green\", \"yellow\", \"red\"] | None = None\n\n    #: Balance directive if this account has an uptodate status.\n    balance_string: str | None = None\n\n    #: The last entry of the account (unless it is a close Entry)\n    last_entry: LastEntry | None = None\n</code></pre>"},{"location":"api/#rustfava.core.accounts.AccountDict","title":"<code>AccountDict</code>","text":"<p>               Bases: <code>FavaModule</code>, <code>dict[str, AccountData]</code></p> <p>Account info dictionary.</p> Source code in <code>src/rustfava/core/accounts.py</code> <pre><code>class AccountDict(FavaModule, dict[str, AccountData]):\n    \"\"\"Account info dictionary.\"\"\"\n\n    EMPTY = AccountData()\n\n    def __missing__(self, key: str) -&gt; AccountData:\n        return self.EMPTY\n\n    def setdefault(\n        self,\n        key: str,\n        _: AccountData | None = None,\n    ) -&gt; AccountData:\n        \"\"\"Get the account of the given name, insert one if it is missing.\"\"\"\n        if key not in self:\n            self[key] = AccountData()\n        return self[key]\n\n    def load_file(self) -&gt; None:  # noqa: D102\n        self.clear()\n        entries_by_account = group_entries_by_account(self.ledger.all_entries)\n        tree = Tree(self.ledger.all_entries)\n        for open_entry in self.ledger.all_entries_by_type.Open:\n            meta = open_entry.meta\n            account_data = self.setdefault(open_entry.account)\n            account_data.meta = meta\n\n            txn_postings = entries_by_account[open_entry.account]\n            last = get_last_entry(txn_postings)\n            if last is not None and not isinstance(last, Close):\n                account_data.last_entry = LastEntry(\n                    date=last.date,\n                    entry_hash=hash_entry(last),\n                )\n            if meta.get(\"fava-uptodate-indication\"):\n                account_data.uptodate_status = uptodate_status(txn_postings)\n                if account_data.uptodate_status != \"green\":\n                    account_data.balance_string = balance_string(\n                        tree.get(open_entry.account),\n                    )\n        for close in self.ledger.all_entries_by_type.Close:\n            self.setdefault(close.account).close_date = close.date\n\n    def all_balance_directives(self) -&gt; str:\n        \"\"\"Balance directives for all accounts.\"\"\"\n        return \"\".join(\n            account_details.balance_string\n            for account_details in self.values()\n            if account_details.balance_string\n        )\n</code></pre>"},{"location":"api/#rustfava.core.accounts.AccountDict.setdefault","title":"<code>setdefault(key, _=None)</code>","text":"<p>Get the account of the given name, insert one if it is missing.</p> Source code in <code>src/rustfava/core/accounts.py</code> <pre><code>def setdefault(\n    self,\n    key: str,\n    _: AccountData | None = None,\n) -&gt; AccountData:\n    \"\"\"Get the account of the given name, insert one if it is missing.\"\"\"\n    if key not in self:\n        self[key] = AccountData()\n    return self[key]\n</code></pre>"},{"location":"api/#rustfava.core.accounts.AccountDict.all_balance_directives","title":"<code>all_balance_directives()</code>","text":"<p>Balance directives for all accounts.</p> Source code in <code>src/rustfava/core/accounts.py</code> <pre><code>def all_balance_directives(self) -&gt; str:\n    \"\"\"Balance directives for all accounts.\"\"\"\n    return \"\".join(\n        account_details.balance_string\n        for account_details in self.values()\n        if account_details.balance_string\n    )\n</code></pre>"},{"location":"api/#rustfava.core.accounts.get_last_entry","title":"<code>get_last_entry(txn_postings)</code>","text":"<p>Last entry.</p> Source code in <code>src/rustfava/core/accounts.py</code> <pre><code>def get_last_entry(\n    txn_postings: Sequence[Directive | TransactionPosting],\n) -&gt; Directive | None:\n    \"\"\"Last entry.\"\"\"\n    for txn_posting in reversed(txn_postings):\n        if isinstance(txn_posting, TransactionPosting):\n            transaction = txn_posting.transaction\n            if transaction.flag != FLAG_UNREALIZED:\n                return transaction\n        else:\n            return txn_posting\n    return None\n</code></pre>"},{"location":"api/#rustfava.core.accounts.uptodate_status","title":"<code>uptodate_status(txn_postings)</code>","text":"<p>Status of the last balance or transaction.</p> <p>Parameters:</p> Name Type Description Default <code>txn_postings</code> <code>Sequence[Directive | TransactionPosting]</code> <p>The TransactionPosting for the account.</p> required <p>Returns:</p> Type Description <code>Literal['green', 'yellow', 'red'] | None</code> <p>A status string for the last balance or transaction of the account.</p> <code>Literal['green', 'yellow', 'red'] | None</code> <ul> <li>'green':  A balance check that passed.</li> </ul> <code>Literal['green', 'yellow', 'red'] | None</code> <ul> <li>'red':    A balance check that failed.</li> </ul> <code>Literal['green', 'yellow', 'red'] | None</code> <ul> <li>'yellow': Not a balance check.</li> </ul> Source code in <code>src/rustfava/core/accounts.py</code> <pre><code>def uptodate_status(\n    txn_postings: Sequence[Directive | TransactionPosting],\n) -&gt; Literal[\"green\", \"yellow\", \"red\"] | None:\n    \"\"\"Status of the last balance or transaction.\n\n    Args:\n        txn_postings: The TransactionPosting for the account.\n\n    Returns:\n        A status string for the last balance or transaction of the account.\n\n        - 'green':  A balance check that passed.\n        - 'red':    A balance check that failed.\n        - 'yellow': Not a balance check.\n    \"\"\"\n    for txn_posting in reversed(txn_postings):\n        if isinstance(txn_posting, Balance):\n            return \"red\" if txn_posting.diff_amount else \"green\"\n        if (\n            isinstance(txn_posting, TransactionPosting)\n            and txn_posting.transaction.flag != FLAG_UNREALIZED\n        ):\n            return \"yellow\"\n    return None\n</code></pre>"},{"location":"api/#rustfava.core.accounts.balance_string","title":"<code>balance_string(tree_node)</code>","text":"<p>Balance directive for the given account for today.</p> Source code in <code>src/rustfava/core/accounts.py</code> <pre><code>def balance_string(tree_node: TreeNode) -&gt; str:\n    \"\"\"Balance directive for the given account for today.\"\"\"\n    account = tree_node.name\n    today = str(local_today())\n    res = \"\"\n    for currency, number in UNITS.apply(tree_node.balance).items():\n        res += f\"{today} balance {account:&lt;28} {number:&gt;15} {currency}\\n\"\n    return res\n</code></pre>"},{"location":"api/#rustfava.core.attributes","title":"<code>attributes</code>","text":"<p>Attributes for auto-completion.</p>"},{"location":"api/#rustfava.core.attributes.AttributesModule","title":"<code>AttributesModule</code>","text":"<p>               Bases: <code>FavaModule</code></p> <p>Some attributes of the ledger (mostly for auto-completion).</p> Source code in <code>src/rustfava/core/attributes.py</code> <pre><code>class AttributesModule(FavaModule):\n    \"\"\"Some attributes of the ledger (mostly for auto-completion).\"\"\"\n\n    def __init__(self, ledger: RustfavaLedger) -&gt; None:\n        super().__init__(ledger)\n        self.accounts: Sequence[str] = []\n        self.currencies: Sequence[str] = []\n        self.payees: Sequence[str] = []\n        self.links: Sequence[str] = []\n        self.tags: Sequence[str] = []\n        self.years: Sequence[str] = []\n\n    def load_file(self) -&gt; None:  # noqa: D102\n        all_entries = self.ledger.all_entries\n\n        all_links = set()\n        all_tags = set()\n        for entry in all_entries:\n            links = getattr(entry, \"links\", None)\n            if links is not None:\n                all_links.update(links)\n            tags = getattr(entry, \"tags\", None)\n            if tags is not None:\n                all_tags.update(tags)\n        self.links = sorted(all_links)\n        self.tags = sorted(all_tags)\n\n        self.years = get_active_years(\n            all_entries,\n            self.ledger.fava_options.fiscal_year_end,\n        )\n\n        account_ranker = ExponentialDecayRanker(\n            sorted(self.ledger.accounts.keys()),\n        )\n        currency_ranker = ExponentialDecayRanker()\n        payee_ranker = ExponentialDecayRanker()\n\n        for txn in self.ledger.all_entries_by_type.Transaction:\n            if txn.payee:\n                payee_ranker.update(txn.payee, txn.date)\n            for posting in txn.postings:\n                account_ranker.update(posting.account, txn.date)\n                # Skip postings with missing units (can happen with parse errors)\n                if posting.units is not None:\n                    currency_ranker.update(posting.units.currency, txn.date)\n                if posting.cost and posting.cost.currency is not None:\n                    currency_ranker.update(posting.cost.currency, txn.date)\n\n        self.accounts = account_ranker.sort()\n        self.currencies = currency_ranker.sort()\n        self.payees = payee_ranker.sort()\n\n    def payee_accounts(self, payee: str) -&gt; Sequence[str]:\n        \"\"\"Rank accounts for the given payee.\"\"\"\n        account_ranker = ExponentialDecayRanker(self.accounts)\n        transactions = self.ledger.all_entries_by_type.Transaction\n        for txn in transactions:\n            if txn.payee == payee:\n                for posting in txn.postings:\n                    account_ranker.update(posting.account, txn.date)\n        return account_ranker.sort()\n\n    def payee_transaction(self, payee: str) -&gt; Transaction | None:\n        \"\"\"Get the last transaction for a payee.\"\"\"\n        transactions = self.ledger.all_entries_by_type.Transaction\n        for txn in reversed(transactions):\n            if txn.payee == payee:\n                return txn\n        return None\n\n    def narration_transaction(self, narration: str) -&gt; Transaction | None:\n        \"\"\"Get the last transaction for a narration.\"\"\"\n        transactions = self.ledger.all_entries_by_type.Transaction\n        for txn in reversed(transactions):\n            if txn.narration == narration:\n                return txn\n        return None\n\n    @property\n    def narrations(self) -&gt; Sequence[str]:\n        \"\"\"Get the narrations of all transactions.\"\"\"\n        narration_ranker = ExponentialDecayRanker()\n        for txn in self.ledger.all_entries_by_type.Transaction:\n            if txn.narration:\n                narration_ranker.update(txn.narration, txn.date)\n        return narration_ranker.sort()\n</code></pre>"},{"location":"api/#rustfava.core.attributes.AttributesModule.narrations","title":"<code>narrations</code>  <code>property</code>","text":"<p>Get the narrations of all transactions.</p>"},{"location":"api/#rustfava.core.attributes.AttributesModule.payee_accounts","title":"<code>payee_accounts(payee)</code>","text":"<p>Rank accounts for the given payee.</p> Source code in <code>src/rustfava/core/attributes.py</code> <pre><code>def payee_accounts(self, payee: str) -&gt; Sequence[str]:\n    \"\"\"Rank accounts for the given payee.\"\"\"\n    account_ranker = ExponentialDecayRanker(self.accounts)\n    transactions = self.ledger.all_entries_by_type.Transaction\n    for txn in transactions:\n        if txn.payee == payee:\n            for posting in txn.postings:\n                account_ranker.update(posting.account, txn.date)\n    return account_ranker.sort()\n</code></pre>"},{"location":"api/#rustfava.core.attributes.AttributesModule.payee_transaction","title":"<code>payee_transaction(payee)</code>","text":"<p>Get the last transaction for a payee.</p> Source code in <code>src/rustfava/core/attributes.py</code> <pre><code>def payee_transaction(self, payee: str) -&gt; Transaction | None:\n    \"\"\"Get the last transaction for a payee.\"\"\"\n    transactions = self.ledger.all_entries_by_type.Transaction\n    for txn in reversed(transactions):\n        if txn.payee == payee:\n            return txn\n    return None\n</code></pre>"},{"location":"api/#rustfava.core.attributes.AttributesModule.narration_transaction","title":"<code>narration_transaction(narration)</code>","text":"<p>Get the last transaction for a narration.</p> Source code in <code>src/rustfava/core/attributes.py</code> <pre><code>def narration_transaction(self, narration: str) -&gt; Transaction | None:\n    \"\"\"Get the last transaction for a narration.\"\"\"\n    transactions = self.ledger.all_entries_by_type.Transaction\n    for txn in reversed(transactions):\n        if txn.narration == narration:\n            return txn\n    return None\n</code></pre>"},{"location":"api/#rustfava.core.attributes.get_active_years","title":"<code>get_active_years(entries, fye)</code>","text":"<p>Return active years, with support for fiscal years.</p> <p>Parameters:</p> Name Type Description Default <code>entries</code> <code>Sequence[Directive]</code> <p>Beancount entries</p> required <code>fye</code> <code>FiscalYearEnd</code> <p>fiscal year end</p> required <p>Returns:</p> Type Description <code>list[str]</code> <p>A reverse sorted list of years or fiscal years that occur in the</p> <code>list[str]</code> <p>entries.</p> Source code in <code>src/rustfava/core/attributes.py</code> <pre><code>def get_active_years(\n    entries: Sequence[Directive],\n    fye: FiscalYearEnd,\n) -&gt; list[str]:\n    \"\"\"Return active years, with support for fiscal years.\n\n    Args:\n        entries: Beancount entries\n        fye: fiscal year end\n\n    Returns:\n        A reverse sorted list of years or fiscal years that occur in the\n        entries.\n    \"\"\"\n    years = []\n    if fye == END_OF_YEAR:\n        prev_year = None\n        for entry in entries:\n            year = entry.date.year\n            if year != prev_year:\n                prev_year = year\n                years.append(year)\n        return [f\"{year}\" for year in reversed(years)]\n    month = fye.month\n    day = fye.day\n    prev_year = None\n    for entry in entries:\n        date = entry.date\n        year = (\n            entry.date.year + 1\n            if date.month &gt; month or (date.month == month and date.day &gt; day)\n            else entry.date.year\n        )\n        if year != prev_year:\n            prev_year = year\n            years.append(year)\n    return [f\"FY{year}\" for year in reversed(years)]\n</code></pre>"},{"location":"api/#rustfava.core.budgets","title":"<code>budgets</code>","text":"<p>Parsing and computing budgets.</p>"},{"location":"api/#rustfava.core.budgets.BudgetDict","title":"<code>BudgetDict = dict[str, list[Budget]]</code>  <code>module-attribute</code>","text":"<p>A map of account names to lists of budget entries.</p>"},{"location":"api/#rustfava.core.budgets.Budget","title":"<code>Budget</code>","text":"<p>               Bases: <code>NamedTuple</code></p> <p>A budget entry.</p> Source code in <code>src/rustfava/core/budgets.py</code> <pre><code>class Budget(NamedTuple):\n    \"\"\"A budget entry.\"\"\"\n\n    account: str\n    date_start: datetime.date\n    period: Interval\n    number: Decimal\n    currency: str\n</code></pre>"},{"location":"api/#rustfava.core.budgets.BudgetError","title":"<code>BudgetError</code>  <code>dataclass</code>","text":"<p>               Bases: <code>BeancountError</code></p> <p>Error with a budget.</p> Source code in <code>src/rustfava/core/budgets.py</code> <pre><code>class BudgetError(BeancountError):\n    \"\"\"Error with a budget.\"\"\"\n</code></pre>"},{"location":"api/#rustfava.core.budgets.BudgetModule","title":"<code>BudgetModule</code>","text":"<p>               Bases: <code>FavaModule</code></p> <p>Parses budget entries.</p> Source code in <code>src/rustfava/core/budgets.py</code> <pre><code>class BudgetModule(FavaModule):\n    \"\"\"Parses budget entries.\"\"\"\n\n    def __init__(self, ledger: RustfavaLedger) -&gt; None:\n        super().__init__(ledger)\n        self._budget_entries: BudgetDict = {}\n        self.errors: Sequence[BudgetError] = []\n\n    def load_file(self) -&gt; None:  # noqa: D102\n        self._budget_entries, self.errors = parse_budgets(\n            self.ledger.all_entries_by_type.Custom,\n        )\n\n    def calculate(\n        self,\n        account: str,\n        begin_date: datetime.date,\n        end_date: datetime.date,\n    ) -&gt; Mapping[str, Decimal]:\n        \"\"\"Calculate the budget for an account in an interval.\"\"\"\n        return calculate_budget(\n            self._budget_entries,\n            account,\n            begin_date,\n            end_date,\n        )\n\n    def calculate_children(\n        self,\n        account: str,\n        begin_date: datetime.date,\n        end_date: datetime.date,\n    ) -&gt; Mapping[str, Decimal]:\n        \"\"\"Calculate the budget for an account including its children.\"\"\"\n        return calculate_budget_children(\n            self._budget_entries,\n            account,\n            begin_date,\n            end_date,\n        )\n</code></pre>"},{"location":"api/#rustfava.core.budgets.BudgetModule.calculate","title":"<code>calculate(account, begin_date, end_date)</code>","text":"<p>Calculate the budget for an account in an interval.</p> Source code in <code>src/rustfava/core/budgets.py</code> <pre><code>def calculate(\n    self,\n    account: str,\n    begin_date: datetime.date,\n    end_date: datetime.date,\n) -&gt; Mapping[str, Decimal]:\n    \"\"\"Calculate the budget for an account in an interval.\"\"\"\n    return calculate_budget(\n        self._budget_entries,\n        account,\n        begin_date,\n        end_date,\n    )\n</code></pre>"},{"location":"api/#rustfava.core.budgets.BudgetModule.calculate_children","title":"<code>calculate_children(account, begin_date, end_date)</code>","text":"<p>Calculate the budget for an account including its children.</p> Source code in <code>src/rustfava/core/budgets.py</code> <pre><code>def calculate_children(\n    self,\n    account: str,\n    begin_date: datetime.date,\n    end_date: datetime.date,\n) -&gt; Mapping[str, Decimal]:\n    \"\"\"Calculate the budget for an account including its children.\"\"\"\n    return calculate_budget_children(\n        self._budget_entries,\n        account,\n        begin_date,\n        end_date,\n    )\n</code></pre>"},{"location":"api/#rustfava.core.budgets.parse_budgets","title":"<code>parse_budgets(custom_entries)</code>","text":"<p>Parse budget directives from custom entries.</p> <p>Parameters:</p> Name Type Description Default <code>custom_entries</code> <code>Sequence[Custom]</code> <p>the Custom entries to parse budgets from.</p> required <p>Returns:</p> Type Description <code>tuple[BudgetDict, Sequence[BudgetError]]</code> <p>A dict of accounts to lists of budgets.</p> Example <p>2015-04-09 custom \"budget\" Expenses:Books \"monthly\" 20.00 EUR</p> Source code in <code>src/rustfava/core/budgets.py</code> <pre><code>def parse_budgets(\n    custom_entries: Sequence[Custom],\n) -&gt; tuple[BudgetDict, Sequence[BudgetError]]:\n    \"\"\"Parse budget directives from custom entries.\n\n    Args:\n        custom_entries: the Custom entries to parse budgets from.\n\n    Returns:\n        A dict of accounts to lists of budgets.\n\n    Example:\n        2015-04-09 custom \"budget\" Expenses:Books \"monthly\" 20.00 EUR\n    \"\"\"\n    budgets: BudgetDict = defaultdict(list)\n    errors = []\n\n    for entry in (entry for entry in custom_entries if entry.type == \"budget\"):\n        try:\n            interval = INTERVALS.get(str(entry.values[1].value).lower())\n            if not interval:\n                errors.append(\n                    BudgetError(\n                        entry.meta,\n                        \"Invalid interval for budget entry\",\n                        entry,\n                    ),\n                )\n                continue\n            budget = Budget(\n                entry.values[0].value,\n                entry.date,\n                interval,\n                entry.values[2].value.number,\n                entry.values[2].value.currency,\n            )\n            budgets[budget.account].append(budget)\n        except (IndexError, TypeError):\n            errors.append(\n                BudgetError(entry.meta, \"Failed to parse budget entry\", entry),\n            )\n\n    return budgets, errors\n</code></pre>"},{"location":"api/#rustfava.core.budgets.calculate_budget","title":"<code>calculate_budget(budgets, account, date_from, date_to)</code>","text":"<p>Calculate budget for an account.</p> <p>Parameters:</p> Name Type Description Default <code>budgets</code> <code>BudgetDict</code> <p>A list of :class:<code>Budget</code> entries.</p> required <code>account</code> <code>str</code> <p>An account name.</p> required <code>date_from</code> <code>date</code> <p>Starting date.</p> required <code>date_to</code> <code>date</code> <p>End date (exclusive).</p> required <p>Returns:</p> Type Description <code>Mapping[str, Decimal]</code> <p>A dictionary of currency to Decimal with the budget for the</p> <code>Mapping[str, Decimal]</code> <p>specified account and period.</p> Source code in <code>src/rustfava/core/budgets.py</code> <pre><code>def calculate_budget(\n    budgets: BudgetDict,\n    account: str,\n    date_from: datetime.date,\n    date_to: datetime.date,\n) -&gt; Mapping[str, Decimal]:\n    \"\"\"Calculate budget for an account.\n\n    Args:\n        budgets: A list of :class:`Budget` entries.\n        account: An account name.\n        date_from: Starting date.\n        date_to: End date (exclusive).\n\n    Returns:\n        A dictionary of currency to Decimal with the budget for the\n        specified account and period.\n    \"\"\"\n    budget_list = budgets.get(account, None)\n    if budget_list is None:\n        return {}\n\n    currency_dict: dict[str, Decimal] = defaultdict(Decimal)\n\n    for day in days_in_daterange(date_from, date_to):\n        matches = _matching_budgets(budget_list, day)\n        for budget in matches.values():\n            days_in_period = budget.period.number_of_days(day)\n            currency_dict[budget.currency] += budget.number / days_in_period\n    return dict(currency_dict)\n</code></pre>"},{"location":"api/#rustfava.core.budgets.calculate_budget_children","title":"<code>calculate_budget_children(budgets, account, date_from, date_to)</code>","text":"<p>Calculate budget for an account including budgets of its children.</p> <p>Parameters:</p> Name Type Description Default <code>budgets</code> <code>BudgetDict</code> <p>A list of :class:<code>Budget</code> entries.</p> required <code>account</code> <code>str</code> <p>An account name.</p> required <code>date_from</code> <code>date</code> <p>Starting date.</p> required <code>date_to</code> <code>date</code> <p>End date (exclusive).</p> required <p>Returns:</p> Type Description <code>Mapping[str, Decimal]</code> <p>A dictionary of currency to Decimal with the budget for the</p> <code>Mapping[str, Decimal]</code> <p>specified account and period.</p> Source code in <code>src/rustfava/core/budgets.py</code> <pre><code>def calculate_budget_children(\n    budgets: BudgetDict,\n    account: str,\n    date_from: datetime.date,\n    date_to: datetime.date,\n) -&gt; Mapping[str, Decimal]:\n    \"\"\"Calculate budget for an account including budgets of its children.\n\n    Args:\n        budgets: A list of :class:`Budget` entries.\n        account: An account name.\n        date_from: Starting date.\n        date_to: End date (exclusive).\n\n    Returns:\n        A dictionary of currency to Decimal with the budget for the\n        specified account and period.\n    \"\"\"\n    currency_dict: dict[str, Decimal] = Counter()  # type: ignore[assignment]\n\n    for child in budgets:\n        if child.startswith(account):\n            currency_dict.update(\n                calculate_budget(budgets, child, date_from, date_to),\n            )\n    return dict(currency_dict)\n</code></pre>"},{"location":"api/#rustfava.core.charts","title":"<code>charts</code>","text":"<p>Provide data suitable for rustfava's charts.</p>"},{"location":"api/#rustfava.core.charts.RustfavaJSONProvider","title":"<code>RustfavaJSONProvider</code>","text":"<p>               Bases: <code>JSONProvider</code></p> <p>Use custom JSON encoder and decoder.</p> Source code in <code>src/rustfava/core/charts.py</code> <pre><code>class RustfavaJSONProvider(JSONProvider):\n    \"\"\"Use custom JSON encoder and decoder.\"\"\"\n\n    def dumps(self, obj: Any, **_kwargs: Any) -&gt; str:  # noqa: D102\n        return json.dumps(\n            obj, sort_keys=True, separators=(\",\", \":\"), default=_json_default\n        )\n\n    def loads(self, s: str | bytes, **_kwargs: Any) -&gt; Any:  # noqa: D102\n        return json.loads(s)\n</code></pre>"},{"location":"api/#rustfava.core.charts.DateAndBalance","title":"<code>DateAndBalance</code>  <code>dataclass</code>","text":"<p>Balance at a date.</p> Source code in <code>src/rustfava/core/charts.py</code> <pre><code>@dataclass(frozen=True)\nclass DateAndBalance:\n    \"\"\"Balance at a date.\"\"\"\n\n    date: date\n    balance: SimpleCounterInventory\n</code></pre>"},{"location":"api/#rustfava.core.charts.DateAndBalanceWithBudget","title":"<code>DateAndBalanceWithBudget</code>  <code>dataclass</code>","text":"<p>Balance at a date with a budget.</p> Source code in <code>src/rustfava/core/charts.py</code> <pre><code>@dataclass(frozen=True)\nclass DateAndBalanceWithBudget:\n    \"\"\"Balance at a date with a budget.\"\"\"\n\n    date: date\n    balance: SimpleCounterInventory\n    account_balances: Mapping[str, SimpleCounterInventory]\n    budgets: Mapping[str, Decimal]\n</code></pre>"},{"location":"api/#rustfava.core.charts.ChartModule","title":"<code>ChartModule</code>","text":"<p>               Bases: <code>FavaModule</code></p> <p>Return data for the various charts in rustfava.</p> Source code in <code>src/rustfava/core/charts.py</code> <pre><code>class ChartModule(FavaModule):\n    \"\"\"Return data for the various charts in rustfava.\"\"\"\n\n    def hierarchy(\n        self,\n        filtered: FilteredLedger,\n        account_name: str,\n        conversion: Conversion,\n    ) -&gt; SerialisedTreeNode:\n        \"\"\"Render an account tree.\"\"\"\n        tree = filtered.root_tree\n        return tree.get(account_name).serialise(\n            conversion, self.ledger.prices, filtered.end_date\n        )\n\n    @listify\n    def interval_totals(\n        self,\n        filtered: FilteredLedger,\n        interval: Interval,\n        accounts: str | tuple[str, ...],\n        conversion: str | Conversion,\n        *,\n        invert: bool = False,\n    ) -&gt; Iterable[DateAndBalanceWithBudget]:\n        \"\"\"Render totals for account (or accounts) in the intervals.\n\n        Args:\n            filtered: The filtered ledger.\n            interval: An interval.\n            accounts: A single account (str) or a tuple of accounts.\n            conversion: The conversion to use.\n            invert: invert all numbers.\n\n        Yields:\n            The balances and budgets for the intervals.\n        \"\"\"\n        conv = conversion_from_str(conversion)\n        prices = self.ledger.prices\n\n        # limit the bar charts to 100 intervals\n        intervals = filtered.interval_ranges(interval)[-100:]\n\n        for date_range in intervals:\n            inventory = CounterInventory()\n            entries = slice_entry_dates(\n                filtered.entries, date_range.begin, date_range.end\n            )\n            account_inventories: dict[str, CounterInventory] = defaultdict(\n                CounterInventory,\n            )\n            for entry in entries:\n                for posting in getattr(entry, \"postings\", []):\n                    if posting.account.startswith(accounts):\n                        account_inventories[posting.account].add_position(\n                            posting,\n                        )\n                        inventory.add_position(posting)\n            balance = conv.apply(\n                inventory,\n                prices,\n                date_range.end_inclusive,\n            )\n            account_balances = {\n                account: conv.apply(\n                    acct_value,\n                    prices,\n                    date_range.end_inclusive,\n                )\n                for account, acct_value in account_inventories.items()\n            }\n            budgets = (\n                self.ledger.budgets.calculate_children(\n                    accounts,\n                    date_range.begin,\n                    date_range.end,\n                )\n                if isinstance(accounts, str)\n                else {}\n            )\n\n            if invert:\n                balance = -balance\n                budgets = {k: -v for k, v in budgets.items()}\n                account_balances = {k: -v for k, v in account_balances.items()}\n\n            yield DateAndBalanceWithBudget(\n                date_range.end_inclusive,\n                balance,\n                account_balances,\n                budgets,\n            )\n\n    @listify\n    def linechart(\n        self,\n        filtered: FilteredLedger,\n        account_name: str,\n        conversion: str | Conversion,\n    ) -&gt; Iterable[DateAndBalance]:\n        \"\"\"Get the balance of an account as a line chart.\n\n        Args:\n            filtered: The filtered ledger.\n            account_name: A string.\n            conversion: The conversion to use.\n\n        Yields:\n            Dicts for all dates on which the balance of the given\n            account has changed containing the balance (in units) of the\n            account at that date.\n        \"\"\"\n        conv = conversion_from_str(conversion)\n\n        def _balances() -&gt; Iterable[tuple[date, CounterInventory]]:\n            last_date = None\n            running_balance = CounterInventory()\n            is_child_account = account_tester(account_name, with_children=True)\n\n            for entry in filtered.entries:\n                for posting in getattr(entry, \"postings\", []):\n                    if is_child_account(posting.account):\n                        new_date = entry.date\n                        if last_date is not None and new_date &gt; last_date:\n                            yield (last_date, running_balance)\n                        running_balance.add_position(posting)\n                        last_date = new_date\n\n            if last_date is not None:\n                yield (last_date, running_balance)\n\n        # When the balance for a commodity just went to zero, it will be\n        # missing from the 'balance' so keep track of currencies that last had\n        # a balance.\n        last_currencies = None\n        prices = self.ledger.prices\n\n        for d, running_bal in _balances():\n            balance = conv.apply(running_bal, prices, d)\n            currencies = set(balance.keys())\n            if last_currencies:\n                for currency in last_currencies - currencies:\n                    balance[currency] = ZERO\n            last_currencies = currencies\n            yield DateAndBalance(d, balance)\n\n    @listify\n    def net_worth(\n        self,\n        filtered: FilteredLedger,\n        interval: Interval,\n        conversion: str | Conversion,\n    ) -&gt; Iterable[DateAndBalance]:\n        \"\"\"Compute net worth.\n\n        Args:\n            filtered: The filtered ledger.\n            interval: A string for the interval.\n            conversion: The conversion to use.\n\n        Yields:\n            Dicts for all ends of the given interval containing the\n            net worth (Assets + Liabilities) separately converted to all\n            operating currencies.\n        \"\"\"\n        conv = conversion_from_str(conversion)\n        transactions = (\n            entry\n            for entry in filtered.entries\n            if (\n                isinstance(entry, Transaction)\n                and entry.flag != FLAG_UNREALIZED\n            )\n        )\n\n        types = (\n            self.ledger.options[\"name_assets\"],\n            self.ledger.options[\"name_liabilities\"],\n        )\n\n        txn = next(transactions, None)\n        inventory = CounterInventory()\n\n        prices = self.ledger.prices\n        for date_range in filtered.interval_ranges(interval):\n            while txn and txn.date &lt; date_range.end:\n                for posting in txn.postings:\n                    if posting.account.startswith(types):\n                        inventory.add_position(posting)\n                txn = next(transactions, None)\n            yield DateAndBalance(\n                date_range.end_inclusive,\n                conv.apply(\n                    inventory,\n                    prices,\n                    date_range.end_inclusive,\n                ),\n            )\n</code></pre>"},{"location":"api/#rustfava.core.charts.ChartModule.hierarchy","title":"<code>hierarchy(filtered, account_name, conversion)</code>","text":"<p>Render an account tree.</p> Source code in <code>src/rustfava/core/charts.py</code> <pre><code>def hierarchy(\n    self,\n    filtered: FilteredLedger,\n    account_name: str,\n    conversion: Conversion,\n) -&gt; SerialisedTreeNode:\n    \"\"\"Render an account tree.\"\"\"\n    tree = filtered.root_tree\n    return tree.get(account_name).serialise(\n        conversion, self.ledger.prices, filtered.end_date\n    )\n</code></pre>"},{"location":"api/#rustfava.core.charts.ChartModule.interval_totals","title":"<code>interval_totals(filtered, interval, accounts, conversion, *, invert=False)</code>","text":"<p>Render totals for account (or accounts) in the intervals.</p> <p>Parameters:</p> Name Type Description Default <code>filtered</code> <code>FilteredLedger</code> <p>The filtered ledger.</p> required <code>interval</code> <code>Interval</code> <p>An interval.</p> required <code>accounts</code> <code>str | tuple[str, ...]</code> <p>A single account (str) or a tuple of accounts.</p> required <code>conversion</code> <code>str | Conversion</code> <p>The conversion to use.</p> required <code>invert</code> <code>bool</code> <p>invert all numbers.</p> <code>False</code> <p>Yields:</p> Type Description <code>Iterable[DateAndBalanceWithBudget]</code> <p>The balances and budgets for the intervals.</p> Source code in <code>src/rustfava/core/charts.py</code> <pre><code>@listify\ndef interval_totals(\n    self,\n    filtered: FilteredLedger,\n    interval: Interval,\n    accounts: str | tuple[str, ...],\n    conversion: str | Conversion,\n    *,\n    invert: bool = False,\n) -&gt; Iterable[DateAndBalanceWithBudget]:\n    \"\"\"Render totals for account (or accounts) in the intervals.\n\n    Args:\n        filtered: The filtered ledger.\n        interval: An interval.\n        accounts: A single account (str) or a tuple of accounts.\n        conversion: The conversion to use.\n        invert: invert all numbers.\n\n    Yields:\n        The balances and budgets for the intervals.\n    \"\"\"\n    conv = conversion_from_str(conversion)\n    prices = self.ledger.prices\n\n    # limit the bar charts to 100 intervals\n    intervals = filtered.interval_ranges(interval)[-100:]\n\n    for date_range in intervals:\n        inventory = CounterInventory()\n        entries = slice_entry_dates(\n            filtered.entries, date_range.begin, date_range.end\n        )\n        account_inventories: dict[str, CounterInventory] = defaultdict(\n            CounterInventory,\n        )\n        for entry in entries:\n            for posting in getattr(entry, \"postings\", []):\n                if posting.account.startswith(accounts):\n                    account_inventories[posting.account].add_position(\n                        posting,\n                    )\n                    inventory.add_position(posting)\n        balance = conv.apply(\n            inventory,\n            prices,\n            date_range.end_inclusive,\n        )\n        account_balances = {\n            account: conv.apply(\n                acct_value,\n                prices,\n                date_range.end_inclusive,\n            )\n            for account, acct_value in account_inventories.items()\n        }\n        budgets = (\n            self.ledger.budgets.calculate_children(\n                accounts,\n                date_range.begin,\n                date_range.end,\n            )\n            if isinstance(accounts, str)\n            else {}\n        )\n\n        if invert:\n            balance = -balance\n            budgets = {k: -v for k, v in budgets.items()}\n            account_balances = {k: -v for k, v in account_balances.items()}\n\n        yield DateAndBalanceWithBudget(\n            date_range.end_inclusive,\n            balance,\n            account_balances,\n            budgets,\n        )\n</code></pre>"},{"location":"api/#rustfava.core.charts.ChartModule.linechart","title":"<code>linechart(filtered, account_name, conversion)</code>","text":"<p>Get the balance of an account as a line chart.</p> <p>Parameters:</p> Name Type Description Default <code>filtered</code> <code>FilteredLedger</code> <p>The filtered ledger.</p> required <code>account_name</code> <code>str</code> <p>A string.</p> required <code>conversion</code> <code>str | Conversion</code> <p>The conversion to use.</p> required <p>Yields:</p> Type Description <code>Iterable[DateAndBalance]</code> <p>Dicts for all dates on which the balance of the given</p> <code>Iterable[DateAndBalance]</code> <p>account has changed containing the balance (in units) of the</p> <code>Iterable[DateAndBalance]</code> <p>account at that date.</p> Source code in <code>src/rustfava/core/charts.py</code> <pre><code>@listify\ndef linechart(\n    self,\n    filtered: FilteredLedger,\n    account_name: str,\n    conversion: str | Conversion,\n) -&gt; Iterable[DateAndBalance]:\n    \"\"\"Get the balance of an account as a line chart.\n\n    Args:\n        filtered: The filtered ledger.\n        account_name: A string.\n        conversion: The conversion to use.\n\n    Yields:\n        Dicts for all dates on which the balance of the given\n        account has changed containing the balance (in units) of the\n        account at that date.\n    \"\"\"\n    conv = conversion_from_str(conversion)\n\n    def _balances() -&gt; Iterable[tuple[date, CounterInventory]]:\n        last_date = None\n        running_balance = CounterInventory()\n        is_child_account = account_tester(account_name, with_children=True)\n\n        for entry in filtered.entries:\n            for posting in getattr(entry, \"postings\", []):\n                if is_child_account(posting.account):\n                    new_date = entry.date\n                    if last_date is not None and new_date &gt; last_date:\n                        yield (last_date, running_balance)\n                    running_balance.add_position(posting)\n                    last_date = new_date\n\n        if last_date is not None:\n            yield (last_date, running_balance)\n\n    # When the balance for a commodity just went to zero, it will be\n    # missing from the 'balance' so keep track of currencies that last had\n    # a balance.\n    last_currencies = None\n    prices = self.ledger.prices\n\n    for d, running_bal in _balances():\n        balance = conv.apply(running_bal, prices, d)\n        currencies = set(balance.keys())\n        if last_currencies:\n            for currency in last_currencies - currencies:\n                balance[currency] = ZERO\n        last_currencies = currencies\n        yield DateAndBalance(d, balance)\n</code></pre>"},{"location":"api/#rustfava.core.charts.ChartModule.net_worth","title":"<code>net_worth(filtered, interval, conversion)</code>","text":"<p>Compute net worth.</p> <p>Parameters:</p> Name Type Description Default <code>filtered</code> <code>FilteredLedger</code> <p>The filtered ledger.</p> required <code>interval</code> <code>Interval</code> <p>A string for the interval.</p> required <code>conversion</code> <code>str | Conversion</code> <p>The conversion to use.</p> required <p>Yields:</p> Type Description <code>Iterable[DateAndBalance]</code> <p>Dicts for all ends of the given interval containing the</p> <code>Iterable[DateAndBalance]</code> <p>net worth (Assets + Liabilities) separately converted to all</p> <code>Iterable[DateAndBalance]</code> <p>operating currencies.</p> Source code in <code>src/rustfava/core/charts.py</code> <pre><code>@listify\ndef net_worth(\n    self,\n    filtered: FilteredLedger,\n    interval: Interval,\n    conversion: str | Conversion,\n) -&gt; Iterable[DateAndBalance]:\n    \"\"\"Compute net worth.\n\n    Args:\n        filtered: The filtered ledger.\n        interval: A string for the interval.\n        conversion: The conversion to use.\n\n    Yields:\n        Dicts for all ends of the given interval containing the\n        net worth (Assets + Liabilities) separately converted to all\n        operating currencies.\n    \"\"\"\n    conv = conversion_from_str(conversion)\n    transactions = (\n        entry\n        for entry in filtered.entries\n        if (\n            isinstance(entry, Transaction)\n            and entry.flag != FLAG_UNREALIZED\n        )\n    )\n\n    types = (\n        self.ledger.options[\"name_assets\"],\n        self.ledger.options[\"name_liabilities\"],\n    )\n\n    txn = next(transactions, None)\n    inventory = CounterInventory()\n\n    prices = self.ledger.prices\n    for date_range in filtered.interval_ranges(interval):\n        while txn and txn.date &lt; date_range.end:\n            for posting in txn.postings:\n                if posting.account.startswith(types):\n                    inventory.add_position(posting)\n            txn = next(transactions, None)\n        yield DateAndBalance(\n            date_range.end_inclusive,\n            conv.apply(\n                inventory,\n                prices,\n                date_range.end_inclusive,\n            ),\n        )\n</code></pre>"},{"location":"api/#rustfava.core.charts.dumps","title":"<code>dumps(obj, **_kwargs)</code>","text":"<p>Dump as a JSON string.</p> Source code in <code>src/rustfava/core/charts.py</code> <pre><code>def dumps(obj: Any, **_kwargs: Any) -&gt; str:\n    \"\"\"Dump as a JSON string.\"\"\"\n    return json.dumps(\n        obj, sort_keys=True, separators=(\",\", \":\"), default=_json_default\n    )\n</code></pre>"},{"location":"api/#rustfava.core.charts.loads","title":"<code>loads(s)</code>","text":"<p>Load a JSON string.</p> Source code in <code>src/rustfava/core/charts.py</code> <pre><code>def loads(s: str | bytes) -&gt; Any:\n    \"\"\"Load a JSON string.\"\"\"\n    return json.loads(s)\n</code></pre>"},{"location":"api/#rustfava.core.commodities","title":"<code>commodities</code>","text":"<p>Attributes for auto-completion.</p>"},{"location":"api/#rustfava.core.commodities.CommoditiesModule","title":"<code>CommoditiesModule</code>","text":"<p>               Bases: <code>FavaModule</code></p> <p>Details about the currencies and commodities.</p> Source code in <code>src/rustfava/core/commodities.py</code> <pre><code>class CommoditiesModule(FavaModule):\n    \"\"\"Details about the currencies and commodities.\"\"\"\n\n    def __init__(self, ledger: RustfavaLedger) -&gt; None:\n        super().__init__(ledger)\n        self.names: dict[str, str] = {}\n        self.precisions: dict[str, int] = {}\n\n    def load_file(self) -&gt; None:  # noqa: D102\n        self.names = {}\n        self.precisions = {}\n        for commodity in self.ledger.all_entries_by_type.Commodity:\n            name = commodity.meta.get(\"name\")\n            if name:\n                self.names[commodity.currency] = str(name)\n            precision = commodity.meta.get(\"precision\")\n            if isinstance(precision, (str, int, Decimal)):\n                with suppress(ValueError):\n                    self.precisions[commodity.currency] = int(precision)\n\n    def name(self, commodity: str) -&gt; str:\n        \"\"\"Get the name of a commodity (or the commodity itself if not set).\"\"\"\n        return self.names.get(commodity, commodity)\n</code></pre>"},{"location":"api/#rustfava.core.commodities.CommoditiesModule.name","title":"<code>name(commodity)</code>","text":"<p>Get the name of a commodity (or the commodity itself if not set).</p> Source code in <code>src/rustfava/core/commodities.py</code> <pre><code>def name(self, commodity: str) -&gt; str:\n    \"\"\"Get the name of a commodity (or the commodity itself if not set).\"\"\"\n    return self.names.get(commodity, commodity)\n</code></pre>"},{"location":"api/#rustfava.core.conversion","title":"<code>conversion</code>","text":"<p>Commodity conversion helpers for Fava.</p> <p>All functions in this module will be automatically added as template filters.</p>"},{"location":"api/#rustfava.core.conversion.Conversion","title":"<code>Conversion</code>","text":"<p>               Bases: <code>ABC</code></p> <p>A conversion.</p> Source code in <code>src/rustfava/core/conversion.py</code> <pre><code>class Conversion(ABC):\n    \"\"\"A conversion.\"\"\"\n\n    @abstractmethod\n    def apply(\n        self,\n        inventory: CounterInventory,\n        prices: RustfavaPriceMap,\n        date: datetime.date | None = None,\n    ) -&gt; SimpleCounterInventory:\n        \"\"\"Apply the conversion to an inventory (CounterInventory).\"\"\"\n</code></pre>"},{"location":"api/#rustfava.core.conversion.Conversion.apply","title":"<code>apply(inventory, prices, date=None)</code>  <code>abstractmethod</code>","text":"<p>Apply the conversion to an inventory (CounterInventory).</p> Source code in <code>src/rustfava/core/conversion.py</code> <pre><code>@abstractmethod\ndef apply(\n    self,\n    inventory: CounterInventory,\n    prices: RustfavaPriceMap,\n    date: datetime.date | None = None,\n) -&gt; SimpleCounterInventory:\n    \"\"\"Apply the conversion to an inventory (CounterInventory).\"\"\"\n</code></pre>"},{"location":"api/#rustfava.core.conversion.get_cost","title":"<code>get_cost(pos)</code>","text":"<p>Return the total cost of a Position.</p> Source code in <code>src/rustfava/core/conversion.py</code> <pre><code>def get_cost(pos: Position) -&gt; Amount:\n    \"\"\"Return the total cost of a Position.\"\"\"\n    cost_ = pos.cost\n    return (\n        _Amount(cost_.number * pos.units.number, cost_.currency)\n        if cost_ is not None\n        else pos.units\n    )\n</code></pre>"},{"location":"api/#rustfava.core.conversion.get_market_value","title":"<code>get_market_value(pos, prices, date=None)</code>","text":"<p>Get the market value of a Position.</p> <p>This differs from the convert.get_value function in Beancount by returning the cost value if no price can be found.</p> <p>Parameters:</p> Name Type Description Default <code>pos</code> <code>Position</code> <p>A Position.</p> required <code>prices</code> <code>RustfavaPriceMap</code> <p>A rustfavaPriceMap</p> required <code>date</code> <code>date | None</code> <p>A datetime.date instance to evaluate the value at, or None.</p> <code>None</code> <p>Returns:</p> Type Description <code>Amount</code> <p>An Amount, with value converted or if the conversion failed just the</p> <code>Amount</code> <p>cost value (or the units if the position has no cost).</p> Source code in <code>src/rustfava/core/conversion.py</code> <pre><code>def get_market_value(\n    pos: Position,\n    prices: RustfavaPriceMap,\n    date: datetime.date | None = None,\n) -&gt; Amount:\n    \"\"\"Get the market value of a Position.\n\n    This differs from the convert.get_value function in Beancount by returning\n    the cost value if no price can be found.\n\n    Args:\n        pos: A Position.\n        prices: A rustfavaPriceMap\n        date: A datetime.date instance to evaluate the value at, or None.\n\n    Returns:\n        An Amount, with value converted or if the conversion failed just the\n        cost value (or the units if the position has no cost).\n    \"\"\"\n    units_ = pos.units\n    cost_ = pos.cost\n\n    if cost_ is not None:\n        value_currency = cost_.currency\n        base_quote = (units_.currency, value_currency)\n        price_number = prices.get_price(base_quote, date)\n        if price_number is not None:\n            return _Amount(\n                units_.number * price_number,\n                value_currency,\n            )\n        return _Amount(units_.number * cost_.number, value_currency)\n    return units_\n</code></pre>"},{"location":"api/#rustfava.core.conversion.convert_position","title":"<code>convert_position(pos, target_currency, prices, date=None)</code>","text":"<p>Get the value of a Position in a particular currency.</p> <p>Parameters:</p> Name Type Description Default <code>pos</code> <code>Position</code> <p>A Position.</p> required <code>target_currency</code> <code>str</code> <p>The target currency to convert to.</p> required <code>prices</code> <code>RustfavaPriceMap</code> <p>A rustfavaPriceMap</p> required <code>date</code> <code>date | None</code> <p>A datetime.date instance to evaluate the value at, or None.</p> <code>None</code> <p>Returns:</p> Type Description <code>Amount</code> <p>An Amount, with value converted or if the conversion failed just the</p> <code>Amount</code> <p>cost value (or the units if the position has no cost).</p> Source code in <code>src/rustfava/core/conversion.py</code> <pre><code>def convert_position(\n    pos: Position,\n    target_currency: str,\n    prices: RustfavaPriceMap,\n    date: datetime.date | None = None,\n) -&gt; Amount:\n    \"\"\"Get the value of a Position in a particular currency.\n\n    Args:\n        pos: A Position.\n        target_currency: The target currency to convert to.\n        prices: A rustfavaPriceMap\n        date: A datetime.date instance to evaluate the value at, or None.\n\n    Returns:\n        An Amount, with value converted or if the conversion failed just the\n        cost value (or the units if the position has no cost).\n    \"\"\"\n    units_ = pos.units\n\n    # try the direct conversion\n    base_quote = (units_.currency, target_currency)\n    price_number = prices.get_price(base_quote, date)\n    if price_number is not None:\n        return _Amount(units_.number * price_number, target_currency)\n\n    cost_ = pos.cost\n    if cost_ is not None:\n        cost_currency = cost_.currency\n        if cost_currency != target_currency:\n            base_quote1 = (units_.currency, cost_currency)\n            rate1 = prices.get_price(base_quote1, date)\n            if rate1 is not None:\n                base_quote2 = (cost_currency, target_currency)\n                rate2 = prices.get_price(base_quote2, date)\n                if rate2 is not None:\n                    return _Amount(\n                        units_.number * rate1 * rate2,\n                        target_currency,\n                    )\n    return units_\n</code></pre>"},{"location":"api/#rustfava.core.conversion.conversion_from_str","title":"<code>conversion_from_str(value)</code>","text":"<p>Parse a conversion string.</p> Source code in <code>src/rustfava/core/conversion.py</code> <pre><code>def conversion_from_str(value: str | Conversion) -&gt; Conversion:\n    \"\"\"Parse a conversion string.\"\"\"\n    if not isinstance(value, str):\n        return value\n    if value == \"at_cost\":\n        return AT_COST\n    if value == \"at_value\":\n        return AT_VALUE\n    if value == \"units\":\n        return UNITS\n\n    return _CurrencyConversion(value)\n</code></pre>"},{"location":"api/#rustfava.core.conversion.cost_or_value","title":"<code>cost_or_value(inventory, conversion, prices, date=None)</code>","text":"<p>Get the cost or value of an inventory.</p> Source code in <code>src/rustfava/core/conversion.py</code> <pre><code>def cost_or_value(\n    inventory: CounterInventory,\n    conversion: str | Conversion,\n    prices: RustfavaPriceMap,\n    date: datetime.date | None = None,\n) -&gt; SimpleCounterInventory:\n    \"\"\"Get the cost or value of an inventory.\"\"\"\n    conversion = conversion_from_str(conversion)\n    return conversion.apply(inventory, prices, date)\n</code></pre>"},{"location":"api/#rustfava.core.documents","title":"<code>documents</code>","text":"<p>Document path related helpers.</p>"},{"location":"api/#rustfava.core.documents.NotADocumentsFolderError","title":"<code>NotADocumentsFolderError</code>","text":"<p>               Bases: <code>RustfavaAPIError</code></p> <p>Not a documents folder.</p> Source code in <code>src/rustfava/core/documents.py</code> <pre><code>class NotADocumentsFolderError(RustfavaAPIError):\n    \"\"\"Not a documents folder.\"\"\"\n\n    def __init__(self, folder: str) -&gt; None:\n        super().__init__(f\"Not a documents folder: {folder}.\")\n</code></pre>"},{"location":"api/#rustfava.core.documents.NotAValidAccountError","title":"<code>NotAValidAccountError</code>","text":"<p>               Bases: <code>RustfavaAPIError</code></p> <p>Not a valid account.</p> Source code in <code>src/rustfava/core/documents.py</code> <pre><code>class NotAValidAccountError(RustfavaAPIError):\n    \"\"\"Not a valid account.\"\"\"\n\n    def __init__(self, account: str) -&gt; None:\n        super().__init__(f\"Not a valid account: '{account}'\")\n</code></pre>"},{"location":"api/#rustfava.core.documents.is_document_or_import_file","title":"<code>is_document_or_import_file(filename, ledger)</code>","text":"<p>Check whether the filename is a document or in an import directory.</p> <p>This is a security validation function that prevents path traversal.</p> <p>Parameters:</p> Name Type Description Default <code>filename</code> <code>str</code> <p>The filename to check.</p> required <code>ledger</code> <code>RustfavaLedger</code> <p>The RustfavaLedger.</p> required <p>Returns:</p> Type Description <code>bool</code> <p>Whether this is one of the documents or a path in an import dir.</p> Source code in <code>src/rustfava/core/documents.py</code> <pre><code>def is_document_or_import_file(filename: str, ledger: RustfavaLedger) -&gt; bool:\n    \"\"\"Check whether the filename is a document or in an import directory.\n\n    This is a security validation function that prevents path traversal.\n\n    Args:\n        filename: The filename to check.\n        ledger: The RustfavaLedger.\n\n    Returns:\n        Whether this is one of the documents or a path in an import dir.\n    \"\"\"\n    # Check if it's an exact match for a known document\n    if any(\n        filename == d.filename for d in ledger.all_entries_by_type.Document\n    ):\n        return True\n    # Check if resolved path is within an import directory (prevents path traversal)\n    file_path = Path(filename).resolve()\n    for import_dir in ledger.fava_options.import_dirs:\n        resolved_dir = ledger.join_path(import_dir).resolve()\n        if file_path.is_relative_to(resolved_dir):\n            return True\n    return False\n</code></pre>"},{"location":"api/#rustfava.core.documents.filepath_in_document_folder","title":"<code>filepath_in_document_folder(documents_folder, account, filename, ledger)</code>","text":"<p>File path for a document in the folder for an account.</p> <p>Parameters:</p> Name Type Description Default <code>documents_folder</code> <code>str</code> <p>The documents folder.</p> required <code>account</code> <code>str</code> <p>The account to choose the subfolder for.</p> required <code>filename</code> <code>str</code> <p>The filename of the document.</p> required <code>ledger</code> <code>RustfavaLedger</code> <p>The RustfavaLedger.</p> required <p>Returns:</p> Type Description <code>Path</code> <p>The path that the document should be saved at.</p> Source code in <code>src/rustfava/core/documents.py</code> <pre><code>def filepath_in_document_folder(\n    documents_folder: str,\n    account: str,\n    filename: str,\n    ledger: RustfavaLedger,\n) -&gt; Path:\n    \"\"\"File path for a document in the folder for an account.\n\n    Args:\n        documents_folder: The documents folder.\n        account: The account to choose the subfolder for.\n        filename: The filename of the document.\n        ledger: The RustfavaLedger.\n\n    Returns:\n        The path that the document should be saved at.\n    \"\"\"\n    if documents_folder not in ledger.options[\"documents\"]:\n        raise NotADocumentsFolderError(documents_folder)\n\n    if account not in ledger.attributes.accounts:\n        raise NotAValidAccountError(account)\n\n    filename = filename.replace(sep, \" \")\n    if altsep:  # pragma: no cover\n        filename = filename.replace(altsep, \" \")\n\n    return ledger.join_path(\n        documents_folder,\n        *account.split(\":\"),\n        filename,\n    )\n</code></pre>"},{"location":"api/#rustfava.core.extensions","title":"<code>extensions</code>","text":"<p>Fava extensions.</p>"},{"location":"api/#rustfava.core.extensions.ExtensionDetails","title":"<code>ExtensionDetails</code>  <code>dataclass</code>","text":"<p>The information about an extension that is needed for the frontend.</p> Source code in <code>src/rustfava/core/extensions.py</code> <pre><code>@dataclass\nclass ExtensionDetails:\n    \"\"\"The information about an extension that is needed for the frontend.\"\"\"\n\n    name: str\n    report_title: str | None\n    has_js_module: bool\n</code></pre>"},{"location":"api/#rustfava.core.extensions.ExtensionModule","title":"<code>ExtensionModule</code>","text":"<p>               Bases: <code>FavaModule</code></p> <p>Fava extensions.</p> Source code in <code>src/rustfava/core/extensions.py</code> <pre><code>class ExtensionModule(FavaModule):\n    \"\"\"Fava extensions.\"\"\"\n\n    def __init__(self, ledger: RustfavaLedger) -&gt; None:\n        super().__init__(ledger)\n        self._instances: dict[str, RustfavaExtensionBase] = {}\n        self._loaded_extensions: set[type[RustfavaExtensionBase]] = set()\n        self.errors: list[RustfavaExtensionError] = []\n\n    def load_file(self) -&gt; None:  # noqa: D102\n        self.errors = []\n\n        custom_entries = self.ledger.all_entries_by_type.Custom\n\n        seen = set()\n        for entry in (e for e in custom_entries if e.type == \"fava-extension\"):\n            extension = entry.values[0].value\n            if extension in seen:  # pragma: no cover\n                self.errors.append(\n                    RustfavaExtensionError(\n                        entry.meta, f\"Duplicate extension '{extension}'\", entry\n                    )\n                )\n                continue\n\n            seen.add(extension)\n            extensions, errors = find_extensions(\n                Path(self.ledger.beancount_file_path).parent,\n                extension,\n            )\n            self.errors.extend(errors)\n\n            for cls in extensions:\n                ext_config = (\n                    entry.values[1].value if len(entry.values) &gt; 1 else None\n                )\n                if cls not in self._loaded_extensions:\n                    self._loaded_extensions.add(cls)\n                    try:\n                        ext = cls(self.ledger, ext_config)\n                        self._instances[ext.name] = ext\n                    except ExtensionConfigError as error:  # pragma: no cover\n                        self.errors.append(\n                            RustfavaExtensionError(entry.meta, str(error), entry)\n                        )\n\n    @property\n    def _exts(self) -&gt; Iterable[RustfavaExtensionBase]:\n        return self._instances.values()\n\n    @property\n    def extension_details(self) -&gt; Sequence[ExtensionDetails]:\n        \"\"\"Extension information to provide to the Frontend.\"\"\"\n        return [\n            ExtensionDetails(ext.name, ext.report_title, ext.has_js_module)\n            for ext in self._exts\n        ]\n\n    def get_extension(self, name: str) -&gt; RustfavaExtensionBase | None:\n        \"\"\"Get the extension with the given name.\"\"\"\n        return self._instances.get(name, None)\n\n    def after_load_file(self) -&gt; None:\n        \"\"\"Run all `after_load_file` hooks.\"\"\"\n        for ext in self._exts:\n            ext.after_load_file()\n\n    def before_request(self) -&gt; None:\n        \"\"\"Run all `before_request` hooks.\"\"\"\n        for ext in self._exts:\n            ext.before_request()\n\n    def after_entry_modified(self, entry: Directive, new_lines: str) -&gt; None:\n        \"\"\"Run all `after_entry_modified` hooks.\"\"\"\n        for ext in self._exts:  # pragma: no cover\n            ext.after_entry_modified(entry, new_lines)\n\n    def after_insert_entry(self, entry: Directive) -&gt; None:\n        \"\"\"Run all `after_insert_entry` hooks.\"\"\"\n        for ext in self._exts:  # pragma: no cover\n            ext.after_insert_entry(entry)\n\n    def after_delete_entry(self, entry: Directive) -&gt; None:\n        \"\"\"Run all `after_delete_entry` hooks.\"\"\"\n        for ext in self._exts:  # pragma: no cover\n            ext.after_delete_entry(entry)\n\n    def after_insert_metadata(\n        self,\n        entry: Directive,\n        key: str,\n        value: str,\n    ) -&gt; None:\n        \"\"\"Run all `after_insert_metadata` hooks.\"\"\"\n        for ext in self._exts:  # pragma: no cover\n            ext.after_insert_metadata(entry, key, value)\n\n    def after_write_source(self, path: str, source: str) -&gt; None:\n        \"\"\"Run all `after_write_source` hooks.\"\"\"\n        for ext in self._exts:\n            ext.after_write_source(path, source)\n</code></pre>"},{"location":"api/#rustfava.core.extensions.ExtensionModule.extension_details","title":"<code>extension_details</code>  <code>property</code>","text":"<p>Extension information to provide to the Frontend.</p>"},{"location":"api/#rustfava.core.extensions.ExtensionModule.get_extension","title":"<code>get_extension(name)</code>","text":"<p>Get the extension with the given name.</p> Source code in <code>src/rustfava/core/extensions.py</code> <pre><code>def get_extension(self, name: str) -&gt; RustfavaExtensionBase | None:\n    \"\"\"Get the extension with the given name.\"\"\"\n    return self._instances.get(name, None)\n</code></pre>"},{"location":"api/#rustfava.core.extensions.ExtensionModule.after_load_file","title":"<code>after_load_file()</code>","text":"<p>Run all <code>after_load_file</code> hooks.</p> Source code in <code>src/rustfava/core/extensions.py</code> <pre><code>def after_load_file(self) -&gt; None:\n    \"\"\"Run all `after_load_file` hooks.\"\"\"\n    for ext in self._exts:\n        ext.after_load_file()\n</code></pre>"},{"location":"api/#rustfava.core.extensions.ExtensionModule.before_request","title":"<code>before_request()</code>","text":"<p>Run all <code>before_request</code> hooks.</p> Source code in <code>src/rustfava/core/extensions.py</code> <pre><code>def before_request(self) -&gt; None:\n    \"\"\"Run all `before_request` hooks.\"\"\"\n    for ext in self._exts:\n        ext.before_request()\n</code></pre>"},{"location":"api/#rustfava.core.extensions.ExtensionModule.after_entry_modified","title":"<code>after_entry_modified(entry, new_lines)</code>","text":"<p>Run all <code>after_entry_modified</code> hooks.</p> Source code in <code>src/rustfava/core/extensions.py</code> <pre><code>def after_entry_modified(self, entry: Directive, new_lines: str) -&gt; None:\n    \"\"\"Run all `after_entry_modified` hooks.\"\"\"\n    for ext in self._exts:  # pragma: no cover\n        ext.after_entry_modified(entry, new_lines)\n</code></pre>"},{"location":"api/#rustfava.core.extensions.ExtensionModule.after_insert_entry","title":"<code>after_insert_entry(entry)</code>","text":"<p>Run all <code>after_insert_entry</code> hooks.</p> Source code in <code>src/rustfava/core/extensions.py</code> <pre><code>def after_insert_entry(self, entry: Directive) -&gt; None:\n    \"\"\"Run all `after_insert_entry` hooks.\"\"\"\n    for ext in self._exts:  # pragma: no cover\n        ext.after_insert_entry(entry)\n</code></pre>"},{"location":"api/#rustfava.core.extensions.ExtensionModule.after_delete_entry","title":"<code>after_delete_entry(entry)</code>","text":"<p>Run all <code>after_delete_entry</code> hooks.</p> Source code in <code>src/rustfava/core/extensions.py</code> <pre><code>def after_delete_entry(self, entry: Directive) -&gt; None:\n    \"\"\"Run all `after_delete_entry` hooks.\"\"\"\n    for ext in self._exts:  # pragma: no cover\n        ext.after_delete_entry(entry)\n</code></pre>"},{"location":"api/#rustfava.core.extensions.ExtensionModule.after_insert_metadata","title":"<code>after_insert_metadata(entry, key, value)</code>","text":"<p>Run all <code>after_insert_metadata</code> hooks.</p> Source code in <code>src/rustfava/core/extensions.py</code> <pre><code>def after_insert_metadata(\n    self,\n    entry: Directive,\n    key: str,\n    value: str,\n) -&gt; None:\n    \"\"\"Run all `after_insert_metadata` hooks.\"\"\"\n    for ext in self._exts:  # pragma: no cover\n        ext.after_insert_metadata(entry, key, value)\n</code></pre>"},{"location":"api/#rustfava.core.extensions.ExtensionModule.after_write_source","title":"<code>after_write_source(path, source)</code>","text":"<p>Run all <code>after_write_source</code> hooks.</p> Source code in <code>src/rustfava/core/extensions.py</code> <pre><code>def after_write_source(self, path: str, source: str) -&gt; None:\n    \"\"\"Run all `after_write_source` hooks.\"\"\"\n    for ext in self._exts:\n        ext.after_write_source(path, source)\n</code></pre>"},{"location":"api/#rustfava.core.fava_options","title":"<code>fava_options</code>","text":"<p>rustfava's options.</p> <p>Options for rustfava can be specified through Custom entries in the Beancount file. This module contains a list of possible options, the defaults and the code for parsing the options.</p>"},{"location":"api/#rustfava.core.fava_options.OptionError","title":"<code>OptionError</code>  <code>dataclass</code>","text":"<p>               Bases: <code>BeancountError</code></p> <p>An error for one of the rustfava options.</p> Source code in <code>src/rustfava/core/fava_options.py</code> <pre><code>class OptionError(BeancountError):\n    \"\"\"An error for one of the rustfava options.\"\"\"\n</code></pre>"},{"location":"api/#rustfava.core.fava_options.InsertEntryOption","title":"<code>InsertEntryOption</code>  <code>dataclass</code>","text":"<p>Insert option.</p> <p>An option that determines where entries for matching accounts should be inserted.</p> Source code in <code>src/rustfava/core/fava_options.py</code> <pre><code>@dataclass(frozen=True)\nclass InsertEntryOption:\n    \"\"\"Insert option.\n\n    An option that determines where entries for matching accounts should be\n    inserted.\n    \"\"\"\n\n    date: datetime.date\n    re: Pattern[str]\n    filename: str\n    lineno: int\n</code></pre>"},{"location":"api/#rustfava.core.fava_options.RustfavaOptions","title":"<code>RustfavaOptions</code>  <code>dataclass</code>","text":"<p>Options for rustfava that can be set in the Beancount file.</p> Source code in <code>src/rustfava/core/fava_options.py</code> <pre><code>@dataclass\nclass RustfavaOptions:\n    \"\"\"Options for rustfava that can be set in the Beancount file.\"\"\"\n\n    account_journal_include_children: bool = True\n    auto_reload: bool = False\n    collapse_pattern: Sequence[Pattern[str]] = field(default_factory=list)\n    conversion_currencies: tuple[str, ...] = ()\n    currency_column: int = 61\n    default_file: str | None = None\n    default_page: str = \"income_statement/\"\n    fiscal_year_end: FiscalYearEnd = END_OF_YEAR\n    import_config: str | None = None\n    import_dirs: Sequence[str] = field(default_factory=list)\n    indent: int = 2\n    insert_entry: Sequence[InsertEntryOption] = field(default_factory=list)\n    invert_gains_losses_colors: bool = False\n    invert_income_liabilities_equity: bool = False\n    language: str | None = None\n    locale: str | None = None\n    show_accounts_with_zero_balance: bool = True\n    show_accounts_with_zero_transactions: bool = True\n    show_closed_accounts: bool = False\n    sidebar_show_queries: int = 5\n    unrealized: str = \"Unrealized\"\n    upcoming_events: int = 7\n    uptodate_indicator_grey_lookback_days: int = 60\n    use_external_editor: bool = False\n\n    def set_collapse_pattern(self, value: str) -&gt; None:\n        \"\"\"Set the collapse_pattern option.\"\"\"\n        try:\n            pattern = re.compile(value)\n        except re.error as err:\n            raise NotARegularExpressionError(value) from err\n        # It's typed as Sequence so that it's not externally mutated\n        self.collapse_pattern.append(pattern)  # type: ignore[attr-defined]\n\n    def set_default_file(self, value: str, filename: str) -&gt; None:\n        \"\"\"Set the default_file option.\"\"\"\n        self.default_file = (\n            str((Path(filename).parent / value).absolute())\n            if value\n            else filename\n        )\n\n    def set_fiscal_year_end(self, value: str) -&gt; None:\n        \"\"\"Set the fiscal_year_end option.\"\"\"\n        fye = parse_fye_string(value)\n        if fye is None:\n            raise InvalidFiscalYearEndOptionError(value)\n        self.fiscal_year_end = fye\n\n    def set_import_dirs(self, value: str) -&gt; None:\n        \"\"\"Add an import directory.\"\"\"\n        # It's typed as Sequence so that it's not externally mutated\n        self.import_dirs.append(value)  # type: ignore[attr-defined]\n\n    def set_insert_entry(\n        self, value: str, date: datetime.date, filename: str, lineno: int\n    ) -&gt; None:\n        \"\"\"Set the insert_entry option.\"\"\"\n        try:\n            pattern = re.compile(value)\n        except re.error as err:\n            raise NotARegularExpressionError(value) from err\n        opt = InsertEntryOption(date, pattern, filename, lineno)\n        # It's typed as Sequence so that it's not externally mutated\n        self.insert_entry.append(opt)  # type: ignore[attr-defined]\n\n    def set_language(self, value: str) -&gt; None:\n        \"\"\"Set the locale option.\"\"\"\n        try:\n            locale = Locale.parse(value)\n            if (\n                not locale.language == \"en\"\n                and get_translations(locale) is None\n            ):\n                raise UnsupportedLanguageOptionError(value)\n            self.language = value\n        except UnknownLocaleError as err:\n            raise UnknownLocaleOptionError(value) from err\n\n    def set_locale(self, value: str) -&gt; None:\n        \"\"\"Set the locale option.\"\"\"\n        try:\n            Locale.parse(value)\n            self.locale = value\n        except UnknownLocaleError as err:\n            raise UnknownLocaleOptionError(value) from err\n</code></pre>"},{"location":"api/#rustfava.core.fava_options.RustfavaOptions.set_collapse_pattern","title":"<code>set_collapse_pattern(value)</code>","text":"<p>Set the collapse_pattern option.</p> Source code in <code>src/rustfava/core/fava_options.py</code> <pre><code>def set_collapse_pattern(self, value: str) -&gt; None:\n    \"\"\"Set the collapse_pattern option.\"\"\"\n    try:\n        pattern = re.compile(value)\n    except re.error as err:\n        raise NotARegularExpressionError(value) from err\n    # It's typed as Sequence so that it's not externally mutated\n    self.collapse_pattern.append(pattern)  # type: ignore[attr-defined]\n</code></pre>"},{"location":"api/#rustfava.core.fava_options.RustfavaOptions.set_default_file","title":"<code>set_default_file(value, filename)</code>","text":"<p>Set the default_file option.</p> Source code in <code>src/rustfava/core/fava_options.py</code> <pre><code>def set_default_file(self, value: str, filename: str) -&gt; None:\n    \"\"\"Set the default_file option.\"\"\"\n    self.default_file = (\n        str((Path(filename).parent / value).absolute())\n        if value\n        else filename\n    )\n</code></pre>"},{"location":"api/#rustfava.core.fava_options.RustfavaOptions.set_fiscal_year_end","title":"<code>set_fiscal_year_end(value)</code>","text":"<p>Set the fiscal_year_end option.</p> Source code in <code>src/rustfava/core/fava_options.py</code> <pre><code>def set_fiscal_year_end(self, value: str) -&gt; None:\n    \"\"\"Set the fiscal_year_end option.\"\"\"\n    fye = parse_fye_string(value)\n    if fye is None:\n        raise InvalidFiscalYearEndOptionError(value)\n    self.fiscal_year_end = fye\n</code></pre>"},{"location":"api/#rustfava.core.fava_options.RustfavaOptions.set_import_dirs","title":"<code>set_import_dirs(value)</code>","text":"<p>Add an import directory.</p> Source code in <code>src/rustfava/core/fava_options.py</code> <pre><code>def set_import_dirs(self, value: str) -&gt; None:\n    \"\"\"Add an import directory.\"\"\"\n    # It's typed as Sequence so that it's not externally mutated\n    self.import_dirs.append(value)  # type: ignore[attr-defined]\n</code></pre>"},{"location":"api/#rustfava.core.fava_options.RustfavaOptions.set_insert_entry","title":"<code>set_insert_entry(value, date, filename, lineno)</code>","text":"<p>Set the insert_entry option.</p> Source code in <code>src/rustfava/core/fava_options.py</code> <pre><code>def set_insert_entry(\n    self, value: str, date: datetime.date, filename: str, lineno: int\n) -&gt; None:\n    \"\"\"Set the insert_entry option.\"\"\"\n    try:\n        pattern = re.compile(value)\n    except re.error as err:\n        raise NotARegularExpressionError(value) from err\n    opt = InsertEntryOption(date, pattern, filename, lineno)\n    # It's typed as Sequence so that it's not externally mutated\n    self.insert_entry.append(opt)  # type: ignore[attr-defined]\n</code></pre>"},{"location":"api/#rustfava.core.fava_options.RustfavaOptions.set_language","title":"<code>set_language(value)</code>","text":"<p>Set the locale option.</p> Source code in <code>src/rustfava/core/fava_options.py</code> <pre><code>def set_language(self, value: str) -&gt; None:\n    \"\"\"Set the locale option.\"\"\"\n    try:\n        locale = Locale.parse(value)\n        if (\n            not locale.language == \"en\"\n            and get_translations(locale) is None\n        ):\n            raise UnsupportedLanguageOptionError(value)\n        self.language = value\n    except UnknownLocaleError as err:\n        raise UnknownLocaleOptionError(value) from err\n</code></pre>"},{"location":"api/#rustfava.core.fava_options.RustfavaOptions.set_locale","title":"<code>set_locale(value)</code>","text":"<p>Set the locale option.</p> Source code in <code>src/rustfava/core/fava_options.py</code> <pre><code>def set_locale(self, value: str) -&gt; None:\n    \"\"\"Set the locale option.\"\"\"\n    try:\n        Locale.parse(value)\n        self.locale = value\n    except UnknownLocaleError as err:\n        raise UnknownLocaleOptionError(value) from err\n</code></pre>"},{"location":"api/#rustfava.core.fava_options.parse_option_custom_entry","title":"<code>parse_option_custom_entry(entry, options)</code>","text":"<p>Parse a single custom fava-option entry and set option accordingly.</p> Source code in <code>src/rustfava/core/fava_options.py</code> <pre><code>def parse_option_custom_entry(  # noqa: PLR0912\n    entry: Custom,\n    options: RustfavaOptions,\n) -&gt; None:\n    \"\"\"Parse a single custom fava-option entry and set option accordingly.\"\"\"\n    key = str(entry.values[0].value).replace(\"-\", \"_\")\n    if key not in All_OPTS:\n        raise UnknownOptionError(key)\n\n    value = entry.values[1].value if len(entry.values) &gt; 1 else \"\"\n    if not isinstance(value, str):\n        raise NotAStringOptionError(key)\n    filename, lineno = get_position(entry)\n\n    if key == \"collapse_pattern\":\n        options.set_collapse_pattern(value)\n    elif key == \"default_file\":\n        options.set_default_file(value, filename)\n    elif key == \"fiscal_year_end\":\n        options.set_fiscal_year_end(value)\n    elif key == \"import_dirs\":\n        options.set_import_dirs(value)\n    elif key == \"insert_entry\":\n        options.set_insert_entry(value, entry.date, filename, lineno)\n    elif key == \"language\":\n        options.set_language(value)\n    elif key == \"locale\":\n        options.set_locale(value)\n    elif key in STR_OPTS:\n        setattr(options, key, value)\n    elif key in BOOL_OPTS:\n        setattr(options, key, value.lower() == \"true\")\n    elif key in INT_OPTS:\n        setattr(options, key, int(value))\n    else:  # key in TUPLE_OPTS\n        setattr(options, key, tuple(value.strip().split(\" \")))\n</code></pre>"},{"location":"api/#rustfava.core.fava_options.parse_options","title":"<code>parse_options(custom_entries)</code>","text":"<p>Parse custom entries for rustfava options.</p> <p>The format for option entries is the following::</p> <pre><code>2016-04-01 custom \"fava-option\" \"[name]\" \"[value]\"\n</code></pre> <p>Parameters:</p> Name Type Description Default <code>custom_entries</code> <code>Sequence[Custom]</code> <p>A list of Custom entries.</p> required <p>Returns:</p> Type Description <code>RustfavaOptions</code> <p>A tuple (options, errors) where options is a dictionary of all options</p> <code>list[OptionError]</code> <p>to values, and errors contains possible parsing errors.</p> Source code in <code>src/rustfava/core/fava_options.py</code> <pre><code>def parse_options(\n    custom_entries: Sequence[Custom],\n) -&gt; tuple[RustfavaOptions, list[OptionError]]:\n    \"\"\"Parse custom entries for rustfava options.\n\n    The format for option entries is the following::\n\n        2016-04-01 custom \"fava-option\" \"[name]\" \"[value]\"\n\n    Args:\n        custom_entries: A list of Custom entries.\n\n    Returns:\n        A tuple (options, errors) where options is a dictionary of all options\n        to values, and errors contains possible parsing errors.\n    \"\"\"\n    options = RustfavaOptions()\n    errors = []\n\n    for entry in (e for e in custom_entries if e.type == \"fava-option\"):\n        try:\n            if not entry.values:\n                raise MissingOptionError\n            parse_option_custom_entry(entry, options)\n        except (IndexError, TypeError, ValueError) as err:\n            msg = f\"Failed to parse fava-option entry: {err!s}\"\n            errors.append(OptionError(entry.meta, msg, entry))\n\n    return options, errors\n</code></pre>"},{"location":"api/#rustfava.core.file","title":"<code>file</code>","text":"<p>Reading/writing Beancount files.</p>"},{"location":"api/#rustfava.core.file.NonSourceFileError","title":"<code>NonSourceFileError</code>","text":"<p>               Bases: <code>RustfavaAPIError</code></p> <p>Trying to read a non-source file.</p> Source code in <code>src/rustfava/core/file.py</code> <pre><code>class NonSourceFileError(RustfavaAPIError):\n    \"\"\"Trying to read a non-source file.\"\"\"\n\n    def __init__(self, path: Path) -&gt; None:\n        super().__init__(f\"Trying to read a non-source file at '{path}'\")\n</code></pre>"},{"location":"api/#rustfava.core.file.ExternallyChangedError","title":"<code>ExternallyChangedError</code>","text":"<p>               Bases: <code>RustfavaAPIError</code></p> <p>The file changed externally.</p> Source code in <code>src/rustfava/core/file.py</code> <pre><code>class ExternallyChangedError(RustfavaAPIError):\n    \"\"\"The file changed externally.\"\"\"\n\n    def __init__(self, path: Path) -&gt; None:\n        super().__init__(f\"The file at '{path}' changed externally.\")\n</code></pre>"},{"location":"api/#rustfava.core.file.GeneratedEntryError","title":"<code>GeneratedEntryError</code>","text":"<p>               Bases: <code>RustfavaAPIError</code></p> <p>The entry is generated and cannot be edited.</p> Source code in <code>src/rustfava/core/file.py</code> <pre><code>class GeneratedEntryError(RustfavaAPIError):\n    \"\"\"The entry is generated and cannot be edited.\"\"\"\n\n    def __init__(self) -&gt; None:\n        super().__init__(\"The entry is generated and cannot be edited.\")\n</code></pre>"},{"location":"api/#rustfava.core.file.InvalidUnicodeError","title":"<code>InvalidUnicodeError</code>","text":"<p>               Bases: <code>RustfavaAPIError</code></p> <p>The source file contains invalid unicode.</p> Source code in <code>src/rustfava/core/file.py</code> <pre><code>class InvalidUnicodeError(RustfavaAPIError):\n    \"\"\"The source file contains invalid unicode.\"\"\"\n\n    def __init__(self, reason: str) -&gt; None:\n        super().__init__(\n            f\"The source file contains invalid unicode: {reason}.\",\n        )\n</code></pre>"},{"location":"api/#rustfava.core.file.FileModule","title":"<code>FileModule</code>","text":"<p>               Bases: <code>FavaModule</code></p> <p>Functions related to reading/writing to Beancount files.</p> Source code in <code>src/rustfava/core/file.py</code> <pre><code>class FileModule(FavaModule):\n    \"\"\"Functions related to reading/writing to Beancount files.\"\"\"\n\n    def __init__(self, ledger: RustfavaLedger) -&gt; None:\n        super().__init__(ledger)\n        self._lock = threading.Lock()\n\n    def get_source(self, path: Path) -&gt; tuple[str, str]:\n        \"\"\"Get source files.\n\n        Args:\n            path: The path of the file.\n\n        Returns:\n            A string with the file contents and the `sha256sum` of the file.\n\n        Raises:\n            NonSourceFileError: If the file is not one of the source files.\n            InvalidUnicodeError: If the file contains invalid unicode.\n        \"\"\"\n        if str(path) not in self.ledger.options[\"include\"]:\n            raise NonSourceFileError(path)\n\n        try:\n            source = path.read_text(\"utf-8\")\n        except UnicodeDecodeError as exc:\n            raise InvalidUnicodeError(str(exc)) from exc\n\n        return source, _sha256_str(source)\n\n    def set_source(self, path: Path, source: str, sha256sum: str) -&gt; str:\n        \"\"\"Write to source file.\n\n        Args:\n            path: The path of the file.\n            source: A string with the file contents.\n            sha256sum: Hash of the file.\n\n        Returns:\n            The `sha256sum` of the updated file.\n\n        Raises:\n            NonSourceFileError: If the file is not one of the source files.\n            InvalidUnicodeError: If the file contains invalid unicode.\n            ExternallyChangedError: If the file was changed externally.\n        \"\"\"\n        with self._lock:\n            _, original_sha256sum = self.get_source(path)\n            if original_sha256sum != sha256sum:\n                raise ExternallyChangedError(path)\n\n            newline = _file_newline_character(path)\n            with path.open(\"w\", encoding=\"utf-8\", newline=newline) as file:\n                file.write(source)\n            self.ledger.watcher.notify(path)\n\n            self.ledger.extensions.after_write_source(str(path), source)\n            self.ledger.load_file()\n\n            return _sha256_str(source)\n\n    def insert_metadata(\n        self,\n        entry_hash: str,\n        basekey: str,\n        value: str,\n    ) -&gt; None:\n        \"\"\"Insert metadata into a file at lineno.\n\n        Also, prevent duplicate keys.\n\n        Args:\n            entry_hash: Hash of an entry.\n            basekey: Key to insert metadata for.\n            value: Metadate value to insert.\n        \"\"\"\n        with self._lock:\n            self.ledger.changed()\n            entry = self.ledger.get_entry(entry_hash)\n            key = next_key(basekey, entry.meta)\n            indent = self.ledger.fava_options.indent\n            path, lineno = _get_position(entry)\n            insert_metadata_in_file(path, lineno, indent, key, value)\n            self.ledger.watcher.notify(path)\n            self.ledger.extensions.after_insert_metadata(entry, key, value)\n\n    def save_entry_slice(\n        self,\n        entry_hash: str,\n        source_slice: str,\n        sha256sum: str,\n    ) -&gt; str:\n        \"\"\"Save slice of the source file for an entry.\n\n        Args:\n            entry_hash: Hash of an entry.\n            source_slice: The lines that the entry should be replaced with.\n            sha256sum: The sha256sum of the current lines of the entry.\n\n        Returns:\n            The `sha256sum` of the new lines of the entry.\n\n        Raises:\n            RustfavaAPIError: If the entry is not found or the file changed.\n        \"\"\"\n        with self._lock:\n            entry = self.ledger.get_entry(entry_hash)\n            new_sha256sum = save_entry_slice(entry, source_slice, sha256sum)\n            self.ledger.watcher.notify(Path(get_position(entry)[0]))\n            self.ledger.extensions.after_entry_modified(entry, source_slice)\n            return new_sha256sum\n\n    def delete_entry_slice(self, entry_hash: str, sha256sum: str) -&gt; None:\n        \"\"\"Delete slice of the source file for an entry.\n\n        Args:\n            entry_hash: Hash of an entry.\n            sha256sum: The sha256sum of the current lines of the entry.\n\n        Raises:\n            RustfavaAPIError: If the entry is not found or the file changed.\n        \"\"\"\n        with self._lock:\n            entry = self.ledger.get_entry(entry_hash)\n            delete_entry_slice(entry, sha256sum)\n            self.ledger.watcher.notify(Path(get_position(entry)[0]))\n            self.ledger.extensions.after_delete_entry(entry)\n\n    def insert_entries(self, entries: Sequence[Directive]) -&gt; None:\n        \"\"\"Insert entries.\n\n        Args:\n            entries: A list of entries.\n        \"\"\"\n        with self._lock:\n            self.ledger.changed()\n            fava_options = self.ledger.fava_options\n            for entry in sorted(entries, key=_incomplete_sortkey):\n                path, updated_insert_options = insert_entry(\n                    entry,\n                    (\n                        self.ledger.fava_options.default_file\n                        or self.ledger.beancount_file_path\n                    ),\n                    insert_options=fava_options.insert_entry,\n                    currency_column=fava_options.currency_column,\n                    indent=fava_options.indent,\n                )\n                self.ledger.watcher.notify(path)\n                self.ledger.fava_options.insert_entry = updated_insert_options\n                self.ledger.extensions.after_insert_entry(entry)\n\n    def render_entries(self, entries: Sequence[Directive]) -&gt; Iterable[Markup]:\n        \"\"\"Return entries in Beancount format.\n\n        Only renders :class:`.Balance` and :class:`.Transaction`.\n\n        Args:\n            entries: A list of entries.\n\n        Yields:\n            The entries rendered in Beancount format.\n        \"\"\"\n        indent = self.ledger.fava_options.indent\n        for entry in entries:\n            if isinstance(entry, (Balance, Transaction)):\n                if (\n                    isinstance(entry, Transaction)\n                    and entry.flag in _EXCL_FLAGS\n                ):\n                    continue\n                try:\n                    yield Markup(get_entry_slice(entry)[0] + \"\\n\")  # noqa: S704\n                except (KeyError, FileNotFoundError):\n                    yield Markup(  # noqa: S704\n                        to_string(\n                            entry,\n                            self.ledger.fava_options.currency_column,\n                            indent,\n                        ),\n                    )\n</code></pre>"},{"location":"api/#rustfava.core.file.FileModule.get_source","title":"<code>get_source(path)</code>","text":"<p>Get source files.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>Path</code> <p>The path of the file.</p> required <p>Returns:</p> Type Description <code>tuple[str, str]</code> <p>A string with the file contents and the <code>sha256sum</code> of the file.</p> <p>Raises:</p> Type Description <code>NonSourceFileError</code> <p>If the file is not one of the source files.</p> <code>InvalidUnicodeError</code> <p>If the file contains invalid unicode.</p> Source code in <code>src/rustfava/core/file.py</code> <pre><code>def get_source(self, path: Path) -&gt; tuple[str, str]:\n    \"\"\"Get source files.\n\n    Args:\n        path: The path of the file.\n\n    Returns:\n        A string with the file contents and the `sha256sum` of the file.\n\n    Raises:\n        NonSourceFileError: If the file is not one of the source files.\n        InvalidUnicodeError: If the file contains invalid unicode.\n    \"\"\"\n    if str(path) not in self.ledger.options[\"include\"]:\n        raise NonSourceFileError(path)\n\n    try:\n        source = path.read_text(\"utf-8\")\n    except UnicodeDecodeError as exc:\n        raise InvalidUnicodeError(str(exc)) from exc\n\n    return source, _sha256_str(source)\n</code></pre>"},{"location":"api/#rustfava.core.file.FileModule.set_source","title":"<code>set_source(path, source, sha256sum)</code>","text":"<p>Write to source file.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>Path</code> <p>The path of the file.</p> required <code>source</code> <code>str</code> <p>A string with the file contents.</p> required <code>sha256sum</code> <code>str</code> <p>Hash of the file.</p> required <p>Returns:</p> Type Description <code>str</code> <p>The <code>sha256sum</code> of the updated file.</p> <p>Raises:</p> Type Description <code>NonSourceFileError</code> <p>If the file is not one of the source files.</p> <code>InvalidUnicodeError</code> <p>If the file contains invalid unicode.</p> <code>ExternallyChangedError</code> <p>If the file was changed externally.</p> Source code in <code>src/rustfava/core/file.py</code> <pre><code>def set_source(self, path: Path, source: str, sha256sum: str) -&gt; str:\n    \"\"\"Write to source file.\n\n    Args:\n        path: The path of the file.\n        source: A string with the file contents.\n        sha256sum: Hash of the file.\n\n    Returns:\n        The `sha256sum` of the updated file.\n\n    Raises:\n        NonSourceFileError: If the file is not one of the source files.\n        InvalidUnicodeError: If the file contains invalid unicode.\n        ExternallyChangedError: If the file was changed externally.\n    \"\"\"\n    with self._lock:\n        _, original_sha256sum = self.get_source(path)\n        if original_sha256sum != sha256sum:\n            raise ExternallyChangedError(path)\n\n        newline = _file_newline_character(path)\n        with path.open(\"w\", encoding=\"utf-8\", newline=newline) as file:\n            file.write(source)\n        self.ledger.watcher.notify(path)\n\n        self.ledger.extensions.after_write_source(str(path), source)\n        self.ledger.load_file()\n\n        return _sha256_str(source)\n</code></pre>"},{"location":"api/#rustfava.core.file.FileModule.insert_metadata","title":"<code>insert_metadata(entry_hash, basekey, value)</code>","text":"<p>Insert metadata into a file at lineno.</p> <p>Also, prevent duplicate keys.</p> <p>Parameters:</p> Name Type Description Default <code>entry_hash</code> <code>str</code> <p>Hash of an entry.</p> required <code>basekey</code> <code>str</code> <p>Key to insert metadata for.</p> required <code>value</code> <code>str</code> <p>Metadate value to insert.</p> required Source code in <code>src/rustfava/core/file.py</code> <pre><code>def insert_metadata(\n    self,\n    entry_hash: str,\n    basekey: str,\n    value: str,\n) -&gt; None:\n    \"\"\"Insert metadata into a file at lineno.\n\n    Also, prevent duplicate keys.\n\n    Args:\n        entry_hash: Hash of an entry.\n        basekey: Key to insert metadata for.\n        value: Metadate value to insert.\n    \"\"\"\n    with self._lock:\n        self.ledger.changed()\n        entry = self.ledger.get_entry(entry_hash)\n        key = next_key(basekey, entry.meta)\n        indent = self.ledger.fava_options.indent\n        path, lineno = _get_position(entry)\n        insert_metadata_in_file(path, lineno, indent, key, value)\n        self.ledger.watcher.notify(path)\n        self.ledger.extensions.after_insert_metadata(entry, key, value)\n</code></pre>"},{"location":"api/#rustfava.core.file.FileModule.save_entry_slice","title":"<code>save_entry_slice(entry_hash, source_slice, sha256sum)</code>","text":"<p>Save slice of the source file for an entry.</p> <p>Parameters:</p> Name Type Description Default <code>entry_hash</code> <code>str</code> <p>Hash of an entry.</p> required <code>source_slice</code> <code>str</code> <p>The lines that the entry should be replaced with.</p> required <code>sha256sum</code> <code>str</code> <p>The sha256sum of the current lines of the entry.</p> required <p>Returns:</p> Type Description <code>str</code> <p>The <code>sha256sum</code> of the new lines of the entry.</p> <p>Raises:</p> Type Description <code>RustfavaAPIError</code> <p>If the entry is not found or the file changed.</p> Source code in <code>src/rustfava/core/file.py</code> <pre><code>def save_entry_slice(\n    self,\n    entry_hash: str,\n    source_slice: str,\n    sha256sum: str,\n) -&gt; str:\n    \"\"\"Save slice of the source file for an entry.\n\n    Args:\n        entry_hash: Hash of an entry.\n        source_slice: The lines that the entry should be replaced with.\n        sha256sum: The sha256sum of the current lines of the entry.\n\n    Returns:\n        The `sha256sum` of the new lines of the entry.\n\n    Raises:\n        RustfavaAPIError: If the entry is not found or the file changed.\n    \"\"\"\n    with self._lock:\n        entry = self.ledger.get_entry(entry_hash)\n        new_sha256sum = save_entry_slice(entry, source_slice, sha256sum)\n        self.ledger.watcher.notify(Path(get_position(entry)[0]))\n        self.ledger.extensions.after_entry_modified(entry, source_slice)\n        return new_sha256sum\n</code></pre>"},{"location":"api/#rustfava.core.file.FileModule.delete_entry_slice","title":"<code>delete_entry_slice(entry_hash, sha256sum)</code>","text":"<p>Delete slice of the source file for an entry.</p> <p>Parameters:</p> Name Type Description Default <code>entry_hash</code> <code>str</code> <p>Hash of an entry.</p> required <code>sha256sum</code> <code>str</code> <p>The sha256sum of the current lines of the entry.</p> required <p>Raises:</p> Type Description <code>RustfavaAPIError</code> <p>If the entry is not found or the file changed.</p> Source code in <code>src/rustfava/core/file.py</code> <pre><code>def delete_entry_slice(self, entry_hash: str, sha256sum: str) -&gt; None:\n    \"\"\"Delete slice of the source file for an entry.\n\n    Args:\n        entry_hash: Hash of an entry.\n        sha256sum: The sha256sum of the current lines of the entry.\n\n    Raises:\n        RustfavaAPIError: If the entry is not found or the file changed.\n    \"\"\"\n    with self._lock:\n        entry = self.ledger.get_entry(entry_hash)\n        delete_entry_slice(entry, sha256sum)\n        self.ledger.watcher.notify(Path(get_position(entry)[0]))\n        self.ledger.extensions.after_delete_entry(entry)\n</code></pre>"},{"location":"api/#rustfava.core.file.FileModule.insert_entries","title":"<code>insert_entries(entries)</code>","text":"<p>Insert entries.</p> <p>Parameters:</p> Name Type Description Default <code>entries</code> <code>Sequence[Directive]</code> <p>A list of entries.</p> required Source code in <code>src/rustfava/core/file.py</code> <pre><code>def insert_entries(self, entries: Sequence[Directive]) -&gt; None:\n    \"\"\"Insert entries.\n\n    Args:\n        entries: A list of entries.\n    \"\"\"\n    with self._lock:\n        self.ledger.changed()\n        fava_options = self.ledger.fava_options\n        for entry in sorted(entries, key=_incomplete_sortkey):\n            path, updated_insert_options = insert_entry(\n                entry,\n                (\n                    self.ledger.fava_options.default_file\n                    or self.ledger.beancount_file_path\n                ),\n                insert_options=fava_options.insert_entry,\n                currency_column=fava_options.currency_column,\n                indent=fava_options.indent,\n            )\n            self.ledger.watcher.notify(path)\n            self.ledger.fava_options.insert_entry = updated_insert_options\n            self.ledger.extensions.after_insert_entry(entry)\n</code></pre>"},{"location":"api/#rustfava.core.file.FileModule.render_entries","title":"<code>render_entries(entries)</code>","text":"<p>Return entries in Beancount format.</p> <p>Only renders :class:<code>.Balance</code> and :class:<code>.Transaction</code>.</p> <p>Parameters:</p> Name Type Description Default <code>entries</code> <code>Sequence[Directive]</code> <p>A list of entries.</p> required <p>Yields:</p> Type Description <code>Iterable[Markup]</code> <p>The entries rendered in Beancount format.</p> Source code in <code>src/rustfava/core/file.py</code> <pre><code>def render_entries(self, entries: Sequence[Directive]) -&gt; Iterable[Markup]:\n    \"\"\"Return entries in Beancount format.\n\n    Only renders :class:`.Balance` and :class:`.Transaction`.\n\n    Args:\n        entries: A list of entries.\n\n    Yields:\n        The entries rendered in Beancount format.\n    \"\"\"\n    indent = self.ledger.fava_options.indent\n    for entry in entries:\n        if isinstance(entry, (Balance, Transaction)):\n            if (\n                isinstance(entry, Transaction)\n                and entry.flag in _EXCL_FLAGS\n            ):\n                continue\n            try:\n                yield Markup(get_entry_slice(entry)[0] + \"\\n\")  # noqa: S704\n            except (KeyError, FileNotFoundError):\n                yield Markup(  # noqa: S704\n                    to_string(\n                        entry,\n                        self.ledger.fava_options.currency_column,\n                        indent,\n                    ),\n                )\n</code></pre>"},{"location":"api/#rustfava.core.file.insert_metadata_in_file","title":"<code>insert_metadata_in_file(path, lineno, indent, key, value)</code>","text":"<p>Insert the specified metadata in the file below lineno.</p> <p>Takes the whitespace in front of the line that lineno into account.</p> Source code in <code>src/rustfava/core/file.py</code> <pre><code>def insert_metadata_in_file(\n    path: Path,\n    lineno: int,\n    indent: int,\n    key: str,\n    value: str,\n) -&gt; None:\n    \"\"\"Insert the specified metadata in the file below lineno.\n\n    Takes the whitespace in front of the line that lineno into account.\n    \"\"\"\n    with path.open(encoding=\"utf-8\") as file:\n        contents = file.readlines()\n\n    contents.insert(lineno, f'{\" \" * indent}{key}: \"{value}\"\\n')\n    newline = _file_newline_character(path)\n    with path.open(\"w\", encoding=\"utf-8\", newline=newline) as file:\n        file.write(\"\".join(contents))\n</code></pre>"},{"location":"api/#rustfava.core.file.find_entry_lines","title":"<code>find_entry_lines(lines, lineno)</code>","text":"<p>Lines of entry starting at lineno.</p> <p>Parameters:</p> Name Type Description Default <code>lines</code> <code>Sequence[str]</code> <p>A list of lines.</p> required <code>lineno</code> <code>int</code> <p>The 0-based line-index to start at.</p> required Source code in <code>src/rustfava/core/file.py</code> <pre><code>def find_entry_lines(lines: Sequence[str], lineno: int) -&gt; Sequence[str]:\n    \"\"\"Lines of entry starting at lineno.\n\n    Args:\n        lines: A list of lines.\n        lineno: The 0-based line-index to start at.\n    \"\"\"\n    entry_lines = [lines[lineno]]\n    while True:\n        lineno += 1\n        try:\n            line = lines[lineno]\n        except IndexError:\n            return entry_lines\n        if not line.strip() or re.match(r\"\\S\", line[0]):\n            return entry_lines\n        entry_lines.append(line)\n</code></pre>"},{"location":"api/#rustfava.core.file.get_entry_slice","title":"<code>get_entry_slice(entry)</code>","text":"<p>Get slice of the source file for an entry.</p> <p>Parameters:</p> Name Type Description Default <code>entry</code> <code>Directive</code> <p>An entry.</p> required <p>Returns:</p> Type Description <code>str</code> <p>A string containing the lines of the entry and the <code>sha256sum</code> of</p> <code>str</code> <p>these lines.</p> <p>Raises:</p> Type Description <code>GeneratedEntryError</code> <p>If the entry is generated and cannot be edited.</p> Source code in <code>src/rustfava/core/file.py</code> <pre><code>def get_entry_slice(entry: Directive) -&gt; tuple[str, str]:\n    \"\"\"Get slice of the source file for an entry.\n\n    Args:\n        entry: An entry.\n\n    Returns:\n        A string containing the lines of the entry and the `sha256sum` of\n        these lines.\n\n    Raises:\n        GeneratedEntryError: If the entry is generated and cannot be edited.\n    \"\"\"\n    path, lineno = _get_position(entry)\n    with path.open(encoding=\"utf-8\") as file:\n        lines = file.readlines()\n\n    entry_lines = find_entry_lines(lines, lineno - 1)\n    entry_source = \"\".join(entry_lines).rstrip(\"\\n\")\n\n    return entry_source, _sha256_str(entry_source)\n</code></pre>"},{"location":"api/#rustfava.core.file.save_entry_slice","title":"<code>save_entry_slice(entry, source_slice, sha256sum)</code>","text":"<p>Save slice of the source file for an entry.</p> <p>Parameters:</p> Name Type Description Default <code>entry</code> <code>Directive</code> <p>An entry.</p> required <code>source_slice</code> <code>str</code> <p>The lines that the entry should be replaced with.</p> required <code>sha256sum</code> <code>str</code> <p>The sha256sum of the current lines of the entry.</p> required <p>Returns:</p> Type Description <code>str</code> <p>The <code>sha256sum</code> of the new lines of the entry.</p> <p>Raises:</p> Type Description <code>ExternallyChangedError</code> <p>If the file was changed externally.</p> <code>GeneratedEntryError</code> <p>If the entry is generated and cannot be edited.</p> Source code in <code>src/rustfava/core/file.py</code> <pre><code>def save_entry_slice(\n    entry: Directive,\n    source_slice: str,\n    sha256sum: str,\n) -&gt; str:\n    \"\"\"Save slice of the source file for an entry.\n\n    Args:\n        entry: An entry.\n        source_slice: The lines that the entry should be replaced with.\n        sha256sum: The sha256sum of the current lines of the entry.\n\n    Returns:\n        The `sha256sum` of the new lines of the entry.\n\n    Raises:\n        ExternallyChangedError: If the file was changed externally.\n        GeneratedEntryError: If the entry is generated and cannot be edited.\n    \"\"\"\n    path, lineno = _get_position(entry)\n    with path.open(encoding=\"utf-8\") as file:\n        lines = file.readlines()\n\n    first_entry_line = lineno - 1\n    entry_lines = find_entry_lines(lines, first_entry_line)\n    entry_source = \"\".join(entry_lines).rstrip(\"\\n\")\n    if _sha256_str(entry_source) != sha256sum:\n        raise ExternallyChangedError(path)\n\n    lines = [\n        *lines[:first_entry_line],\n        source_slice + \"\\n\",\n        *lines[first_entry_line + len(entry_lines) :],\n    ]\n    newline = _file_newline_character(path)\n    with path.open(\"w\", encoding=\"utf-8\", newline=newline) as file:\n        file.writelines(lines)\n\n    return _sha256_str(source_slice)\n</code></pre>"},{"location":"api/#rustfava.core.file.delete_entry_slice","title":"<code>delete_entry_slice(entry, sha256sum)</code>","text":"<p>Delete slice of the source file for an entry.</p> <p>Parameters:</p> Name Type Description Default <code>entry</code> <code>Directive</code> <p>An entry.</p> required <code>sha256sum</code> <code>str</code> <p>The sha256sum of the current lines of the entry.</p> required <p>Raises:</p> Type Description <code>ExternallyChangedError</code> <p>If the file was changed externally.</p> <code>GeneratedEntryError</code> <p>If the entry is generated and cannot be edited.</p> Source code in <code>src/rustfava/core/file.py</code> <pre><code>def delete_entry_slice(\n    entry: Directive,\n    sha256sum: str,\n) -&gt; None:\n    \"\"\"Delete slice of the source file for an entry.\n\n    Args:\n        entry: An entry.\n        sha256sum: The sha256sum of the current lines of the entry.\n\n    Raises:\n        ExternallyChangedError: If the file was changed externally.\n        GeneratedEntryError: If the entry is generated and cannot be edited.\n    \"\"\"\n    path, lineno = _get_position(entry)\n    with path.open(encoding=\"utf-8\") as file:\n        lines = file.readlines()\n\n    first_entry_line = lineno - 1\n    entry_lines = find_entry_lines(lines, first_entry_line)\n    entry_source = \"\".join(entry_lines).rstrip(\"\\n\")\n    if _sha256_str(entry_source) != sha256sum:\n        raise ExternallyChangedError(path)\n\n    # Also delete the whitespace following this entry\n    last_entry_line = first_entry_line + len(entry_lines)\n    while True:\n        try:\n            line = lines[last_entry_line]\n        except IndexError:\n            break\n        if line.strip():  # pragma: no cover\n            break\n        last_entry_line += 1  # pragma: no cover\n    lines = lines[:first_entry_line] + lines[last_entry_line:]\n    newline = _file_newline_character(path)\n    with path.open(\"w\", encoding=\"utf-8\", newline=newline) as file:\n        file.writelines(lines)\n</code></pre>"},{"location":"api/#rustfava.core.file.insert_entry","title":"<code>insert_entry(entry, default_filename, insert_options, currency_column, indent)</code>","text":"<p>Insert an entry.</p> <p>Parameters:</p> Name Type Description Default <code>entry</code> <code>Directive</code> <p>An entry.</p> required <code>default_filename</code> <code>str</code> <p>The default file to insert into if no option matches.</p> required <code>insert_options</code> <code>Sequence[InsertEntryOption]</code> <p>Insert options.</p> required <code>currency_column</code> <code>int</code> <p>The column to align currencies at.</p> required <code>indent</code> <code>int</code> <p>Number of indent spaces.</p> required <p>Returns:</p> Type Description <code>tuple[Path, Sequence[InsertEntryOption]]</code> <p>A changed path and list of updated insert options.</p> Source code in <code>src/rustfava/core/file.py</code> <pre><code>def insert_entry(\n    entry: Directive,\n    default_filename: str,\n    insert_options: Sequence[InsertEntryOption],\n    currency_column: int,\n    indent: int,\n) -&gt; tuple[Path, Sequence[InsertEntryOption]]:\n    \"\"\"Insert an entry.\n\n    Args:\n        entry: An entry.\n        default_filename: The default file to insert into if no option matches.\n        insert_options: Insert options.\n        currency_column: The column to align currencies at.\n        indent: Number of indent spaces.\n\n    Returns:\n        A changed path and list of updated insert options.\n    \"\"\"\n    filename, lineno = find_insert_position(\n        entry,\n        insert_options,\n        default_filename,\n    )\n    content = to_string(entry, currency_column, indent)\n\n    path = Path(filename)\n    with path.open(encoding=\"utf-8\") as file:\n        contents = file.readlines()\n\n    if lineno is None:\n        # Appending\n        contents += \"\\n\" + content\n    else:\n        contents.insert(lineno, content + \"\\n\")\n\n    newline = _file_newline_character(path)\n    with path.open(\"w\", encoding=\"utf-8\", newline=newline) as file:\n        file.writelines(contents)\n\n    if lineno is None:\n        return (path, insert_options)\n\n    added_lines = content.count(\"\\n\") + 1\n    return (\n        path,\n        [\n            (\n                replace(option, lineno=option.lineno + added_lines)\n                if option.filename == filename and option.lineno &gt; lineno\n                else option\n            )\n            for option in insert_options\n        ],\n    )\n</code></pre>"},{"location":"api/#rustfava.core.file.find_insert_position","title":"<code>find_insert_position(entry, insert_options, default_filename)</code>","text":"<p>Find insert position for an entry.</p> <p>Parameters:</p> Name Type Description Default <code>entry</code> <code>Directive</code> <p>An entry.</p> required <code>insert_options</code> <code>Sequence[InsertEntryOption]</code> <p>A list of InsertOption.</p> required <code>default_filename</code> <code>str</code> <p>The default file to insert into if no option matches.</p> required <p>Returns:</p> Type Description <code>tuple[str, int | None]</code> <p>A tuple of the filename and the line number.</p> Source code in <code>src/rustfava/core/file.py</code> <pre><code>def find_insert_position(\n    entry: Directive,\n    insert_options: Sequence[InsertEntryOption],\n    default_filename: str,\n) -&gt; tuple[str, int | None]:\n    \"\"\"Find insert position for an entry.\n\n    Args:\n        entry: An entry.\n        insert_options: A list of InsertOption.\n        default_filename: The default file to insert into if no option matches.\n\n    Returns:\n        A tuple of the filename and the line number.\n    \"\"\"\n    # Get the list of accounts that should be considered for the entry.\n    # For transactions, we want the reversed list of posting accounts.\n    accounts = get_entry_accounts(entry)\n\n    # Make no assumptions about the order of insert_options entries and instead\n    # sort them ourselves (by descending dates)\n    insert_options = sorted(\n        insert_options,\n        key=attrgetter(\"date\"),\n        reverse=True,\n    )\n\n    for account in accounts:\n        for insert_option in insert_options:\n            # Only consider InsertOptions before the entry date.\n            if insert_option.date &gt;= entry.date:\n                continue\n            if insert_option.re.match(account):\n                return (insert_option.filename, insert_option.lineno - 1)\n\n    return (default_filename, None)\n</code></pre>"},{"location":"api/#rustfava.core.filters","title":"<code>filters</code>","text":"<p>Entry filters.</p>"},{"location":"api/#rustfava.core.filters.FilterError","title":"<code>FilterError</code>","text":"<p>               Bases: <code>RustfavaAPIError</code></p> <p>Filter exception.</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>class FilterError(RustfavaAPIError):\n    \"\"\"Filter exception.\"\"\"\n\n    def __init__(self, filter_type: str, message: str) -&gt; None:\n        super().__init__(message)\n        self.filter_type = filter_type\n\n    def __str__(self) -&gt; str:\n        return self.message\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterParseError","title":"<code>FilterParseError</code>","text":"<p>               Bases: <code>FilterError</code></p> <p>Filter parse error.</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>class FilterParseError(FilterError):\n    \"\"\"Filter parse error.\"\"\"\n\n    def __init__(self) -&gt; None:\n        super().__init__(\"filter\", \"Failed to parse filter: \")\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterIllegalCharError","title":"<code>FilterIllegalCharError</code>","text":"<p>               Bases: <code>FilterError</code></p> <p>Filter illegal char error.</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>class FilterIllegalCharError(FilterError):\n    \"\"\"Filter illegal char error.\"\"\"\n\n    def __init__(self, char: str) -&gt; None:\n        super().__init__(\n            \"filter\",\n            f'Illegal character \"{char}\" in filter.',\n        )\n</code></pre>"},{"location":"api/#rustfava.core.filters.TimeFilterParseError","title":"<code>TimeFilterParseError</code>","text":"<p>               Bases: <code>FilterError</code></p> <p>Time filter parse error.</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>class TimeFilterParseError(FilterError):\n    \"\"\"Time filter parse error.\"\"\"\n\n    def __init__(self, value: str) -&gt; None:\n        super().__init__(\"time\", f\"Failed to parse date: {value}\")\n</code></pre>"},{"location":"api/#rustfava.core.filters.Token","title":"<code>Token</code>","text":"<p>A token having a certain type and value.</p> <p>The lexer attribute only exists since PLY writes to it in case of a parser error.</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>class Token:\n    \"\"\"A token having a certain type and value.\n\n    The lexer attribute only exists since PLY writes to it in case of a parser\n    error.\n    \"\"\"\n\n    __slots__ = (\"lexer\", \"type\", \"value\")\n\n    def __init__(self, type_: str, value: str) -&gt; None:\n        self.type = type_\n        self.value = value\n\n    def __repr__(self) -&gt; str:  # pragma: no cover\n        return f\"Token({self.type}, {self.value})\"\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterSyntaxLexer","title":"<code>FilterSyntaxLexer</code>","text":"<p>Lexer for Fava's filter syntax.</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>class FilterSyntaxLexer:\n    \"\"\"Lexer for Fava's filter syntax.\"\"\"\n\n    tokens = (\n        \"ANY\",\n        \"ALL\",\n        \"CMP_OP\",\n        \"EQ_OP\",\n        \"KEY\",\n        \"LINK\",\n        \"NUMBER\",\n        \"STRING\",\n        \"TAG\",\n    )\n\n    RULES = (\n        (\"LINK\", r\"\\^[A-Za-z0-9\\-_/.]+\"),\n        (\"TAG\", r\"\\#[A-Za-z0-9\\-_/.]+\"),\n        (\"ALL\", r\"all\\(\"),\n        (\"ANY\", r\"any\\(\"),\n        (\"KEY\", r\"[a-z][a-zA-Z0-9\\-_]+(?=\\s*(:|=|&gt;=|&lt;=|&lt;|&gt;))\"),\n        (\"EQ_OP\", r\":\"),\n        (\"CMP_OP\", r\"(=|&gt;=|&lt;=|&lt;|&gt;)\"),\n        (\"NUMBER\", r\"\\d*\\.?\\d+\"),\n        (\"STRING\", r\"\"\"\\w[-\\w]*|\"[^\"]*\"|'[^']*'\"\"\"),\n    )\n\n    regex = re.compile(\n        \"|\".join((f\"(?P&lt;{name}&gt;{rule})\" for name, rule in RULES)),\n    )\n\n    def LINK(self, token: str, value: str) -&gt; tuple[str, str]:  # noqa: N802\n        return token, value[1:]\n\n    def TAG(self, token: str, value: str) -&gt; tuple[str, str]:  # noqa: N802\n        return token, value[1:]\n\n    def KEY(self, token: str, value: str) -&gt; tuple[str, str]:  # noqa: N802\n        return token, value\n\n    def ALL(self, token: str, _: str) -&gt; tuple[str, str]:  # noqa: N802\n        return token, token\n\n    def ANY(self, token: str, _: str) -&gt; tuple[str, str]:  # noqa: N802\n        return token, token\n\n    def EQ_OP(self, token: str, value: str) -&gt; tuple[str, str]:  # noqa: N802\n        return token, value\n\n    def CMP_OP(self, token: str, value: str) -&gt; tuple[str, str]:  # noqa: N802\n        return token, value\n\n    def NUMBER(self, token: str, value: str) -&gt; tuple[str, Decimal]:  # noqa: N802\n        return token, Decimal(value)\n\n    def STRING(self, token: str, value: str) -&gt; tuple[str, str]:  # noqa: N802\n        if value[0] in {'\"', \"'\"}:\n            return token, value[1:-1]\n        return token, value\n\n    def lex(self, data: str) -&gt; Iterable[Token]:\n        \"\"\"A generator yielding all tokens in a given line.\n\n        Arguments:\n            data: A string, the line to lex.\n\n        Yields:\n            All Tokens in the line.\n        \"\"\"\n        ignore = \" \\t\"\n        literals = \"-,()\"\n        regex = self.regex.match\n\n        pos = 0\n        length = len(data)\n        while pos &lt; length:\n            char = data[pos]\n            if char in ignore:\n                pos += 1\n                continue\n            match = regex(data, pos)\n            if match:\n                value = match.group()\n                pos += len(value)\n                token = match.lastgroup\n                if token is None:  # pragma: no cover\n                    msg = \"Internal Error\"\n                    raise ValueError(msg)\n                func: Callable[[str, str], tuple[str, str]] = getattr(\n                    self,\n                    token,\n                )\n                ret = func(token, value)\n                yield Token(*ret)\n            elif char in literals:\n                yield Token(char, char)\n                pos += 1\n            else:\n                raise FilterIllegalCharError(char)\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterSyntaxLexer.lex","title":"<code>lex(data)</code>","text":"<p>A generator yielding all tokens in a given line.</p> <p>Parameters:</p> Name Type Description Default <code>data</code> <code>str</code> <p>A string, the line to lex.</p> required <p>Yields:</p> Type Description <code>Iterable[Token]</code> <p>All Tokens in the line.</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>def lex(self, data: str) -&gt; Iterable[Token]:\n    \"\"\"A generator yielding all tokens in a given line.\n\n    Arguments:\n        data: A string, the line to lex.\n\n    Yields:\n        All Tokens in the line.\n    \"\"\"\n    ignore = \" \\t\"\n    literals = \"-,()\"\n    regex = self.regex.match\n\n    pos = 0\n    length = len(data)\n    while pos &lt; length:\n        char = data[pos]\n        if char in ignore:\n            pos += 1\n            continue\n        match = regex(data, pos)\n        if match:\n            value = match.group()\n            pos += len(value)\n            token = match.lastgroup\n            if token is None:  # pragma: no cover\n                msg = \"Internal Error\"\n                raise ValueError(msg)\n            func: Callable[[str, str], tuple[str, str]] = getattr(\n                self,\n                token,\n            )\n            ret = func(token, value)\n            yield Token(*ret)\n        elif char in literals:\n            yield Token(char, char)\n            pos += 1\n        else:\n            raise FilterIllegalCharError(char)\n</code></pre>"},{"location":"api/#rustfava.core.filters.Match","title":"<code>Match</code>","text":"<p>Match a string.</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>class Match:\n    \"\"\"Match a string.\"\"\"\n\n    __slots__ = (\"match\",)\n\n    match: Callable[[str], bool]\n\n    def __init__(self, search: str) -&gt; None:\n        try:\n            match = re.compile(search, re.IGNORECASE).search\n            self.match = lambda s: bool(match(s))\n        except re.error:\n            self.match = lambda s: s == search\n\n    def __call__(self, obj: Any) -&gt; bool:\n        return self.match(str(obj))\n</code></pre>"},{"location":"api/#rustfava.core.filters.MatchAmount","title":"<code>MatchAmount</code>","text":"<p>Matches an amount.</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>class MatchAmount:\n    \"\"\"Matches an amount.\"\"\"\n\n    __slots__ = (\"match\",)\n\n    match: Callable[[Decimal], bool]\n\n    def __init__(self, op: str, value: Decimal) -&gt; None:\n        if op == \"=\":\n            self.match = lambda x: x == value\n        elif op == \"&gt;=\":\n            self.match = lambda x: x &gt;= value\n        elif op == \"&lt;=\":\n            self.match = lambda x: x &lt;= value\n        elif op == \"&gt;\":\n            self.match = lambda x: x &gt; value\n        else:  # op == \"&lt;\":\n            self.match = lambda x: x &lt; value\n\n    def __call__(self, obj: Any) -&gt; bool:\n        # Compare to the absolute value to simplify this filter.\n        number = getattr(obj, \"number\", None)\n        return self.match(abs(number)) if number is not None else False\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterSyntaxParser","title":"<code>FilterSyntaxParser</code>","text":"Source code in <code>src/rustfava/core/filters.py</code> <pre><code>class FilterSyntaxParser:\n    precedence = ((\"left\", \"AND\"), (\"right\", \"UMINUS\"))\n    tokens = FilterSyntaxLexer.tokens\n\n    def p_error(self, _: Any) -&gt; None:\n        raise FilterParseError\n\n    def p_filter(self, p: list[Any]) -&gt; None:\n        \"\"\"\n        filter : expr\n        \"\"\"\n        p[0] = p[1]\n\n    def p_expr(self, p: list[Any]) -&gt; None:\n        \"\"\"\n        expr : simple_expr\n        \"\"\"\n        p[0] = p[1]\n\n    def p_expr_all(self, p: list[Any]) -&gt; None:\n        \"\"\"\n        expr : ALL expr ')'\n        \"\"\"\n        expr = p[2]\n\n        def _match_postings(entry: Directive) -&gt; bool:\n            return all(\n                expr(posting) for posting in getattr(entry, \"postings\", [])\n            )\n\n        p[0] = _match_postings\n\n    def p_expr_any(self, p: list[Any]) -&gt; None:\n        \"\"\"\n        expr : ANY expr ')'\n        \"\"\"\n        expr = p[2]\n\n        def _match_postings(entry: Directive) -&gt; bool:\n            return any(\n                expr(posting) for posting in getattr(entry, \"postings\", [])\n            )\n\n        p[0] = _match_postings\n\n    def p_expr_parentheses(self, p: list[Any]) -&gt; None:\n        \"\"\"\n        expr : '(' expr ')'\n        \"\"\"\n        p[0] = p[2]\n\n    def p_expr_and(self, p: list[Any]) -&gt; None:\n        \"\"\"\n        expr : expr expr %prec AND\n        \"\"\"\n        left, right = p[1], p[2]\n\n        def _and(entry: Directive) -&gt; bool:\n            return left(entry) and right(entry)  # type: ignore[no-any-return]\n\n        p[0] = _and\n\n    def p_expr_or(self, p: list[Any]) -&gt; None:\n        \"\"\"\n        expr : expr ',' expr\n        \"\"\"\n        left, right = p[1], p[3]\n\n        def _or(entry: Directive) -&gt; bool:\n            return left(entry) or right(entry)  # type: ignore[no-any-return]\n\n        p[0] = _or\n\n    def p_expr_negated(self, p: list[Any]) -&gt; None:\n        \"\"\"\n        expr : '-' expr %prec UMINUS\n        \"\"\"\n        func = p[2]\n\n        def _neg(entry: Directive) -&gt; bool:\n            return not func(entry)\n\n        p[0] = _neg\n\n    def p_simple_expr_TAG(self, p: list[Any]) -&gt; None:  # noqa: N802\n        \"\"\"\n        simple_expr : TAG\n        \"\"\"\n        tag = p[1]\n\n        def _tag(entry: Directive) -&gt; bool:\n            tags = getattr(entry, \"tags\", None)\n            return (tag in tags) if tags is not None else False\n\n        p[0] = _tag\n\n    def p_simple_expr_LINK(self, p: list[Any]) -&gt; None:  # noqa: N802\n        \"\"\"\n        simple_expr : LINK\n        \"\"\"\n        link = p[1]\n\n        def _link(entry: Directive) -&gt; bool:\n            links = getattr(entry, \"links\", None)\n            return (link in links) if links is not None else False\n\n        p[0] = _link\n\n    def p_simple_expr_STRING(self, p: list[Any]) -&gt; None:  # noqa: N802\n        \"\"\"\n        simple_expr : STRING\n        \"\"\"\n        string = p[1]\n        match = Match(string)\n\n        def _string(entry: Directive) -&gt; bool:\n            for name in (\"narration\", \"payee\", \"comment\"):\n                value = getattr(entry, name, \"\")\n                if value and match(value):\n                    return True\n            return False\n\n        p[0] = _string\n\n    def p_simple_expr_key(self, p: list[Any]) -&gt; None:\n        \"\"\"\n        simple_expr : KEY EQ_OP STRING\n                    | KEY CMP_OP NUMBER\n        \"\"\"\n        key, op, value = p[1], p[2], p[3]\n        match: Match | MatchAmount = (\n            Match(value) if op == \":\" else MatchAmount(op, value)\n        )\n\n        def _key(entry: Directive) -&gt; bool:\n            if hasattr(entry, key):\n                return match(getattr(entry, key) or \"\")\n            if entry.meta is not None and key in entry.meta:\n                return match(entry.meta.get(key))\n            return False\n\n        p[0] = _key\n\n    def p_simple_expr_units(self, p: list[Any]) -&gt; None:\n        \"\"\"\n        simple_expr : CMP_OP NUMBER\n        \"\"\"\n        op, value = p[1], p[2]\n        match = MatchAmount(op, value)\n\n        def _range(entry: Directive) -&gt; bool:\n            return any(\n                match(posting.units)\n                for posting in getattr(entry, \"postings\", [])\n            )\n\n        p[0] = _range\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterSyntaxParser.p_filter","title":"<code>p_filter(p)</code>","text":"<p>filter : expr</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>def p_filter(self, p: list[Any]) -&gt; None:\n    \"\"\"\n    filter : expr\n    \"\"\"\n    p[0] = p[1]\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterSyntaxParser.p_expr","title":"<code>p_expr(p)</code>","text":"<p>expr : simple_expr</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>def p_expr(self, p: list[Any]) -&gt; None:\n    \"\"\"\n    expr : simple_expr\n    \"\"\"\n    p[0] = p[1]\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterSyntaxParser.p_expr_all","title":"<code>p_expr_all(p)</code>","text":"<p>expr : ALL expr ')'</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>def p_expr_all(self, p: list[Any]) -&gt; None:\n    \"\"\"\n    expr : ALL expr ')'\n    \"\"\"\n    expr = p[2]\n\n    def _match_postings(entry: Directive) -&gt; bool:\n        return all(\n            expr(posting) for posting in getattr(entry, \"postings\", [])\n        )\n\n    p[0] = _match_postings\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterSyntaxParser.p_expr_any","title":"<code>p_expr_any(p)</code>","text":"<p>expr : ANY expr ')'</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>def p_expr_any(self, p: list[Any]) -&gt; None:\n    \"\"\"\n    expr : ANY expr ')'\n    \"\"\"\n    expr = p[2]\n\n    def _match_postings(entry: Directive) -&gt; bool:\n        return any(\n            expr(posting) for posting in getattr(entry, \"postings\", [])\n        )\n\n    p[0] = _match_postings\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterSyntaxParser.p_expr_parentheses","title":"<code>p_expr_parentheses(p)</code>","text":"<p>expr : '(' expr ')'</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>def p_expr_parentheses(self, p: list[Any]) -&gt; None:\n    \"\"\"\n    expr : '(' expr ')'\n    \"\"\"\n    p[0] = p[2]\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterSyntaxParser.p_expr_and","title":"<code>p_expr_and(p)</code>","text":"<p>expr : expr expr %prec AND</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>def p_expr_and(self, p: list[Any]) -&gt; None:\n    \"\"\"\n    expr : expr expr %prec AND\n    \"\"\"\n    left, right = p[1], p[2]\n\n    def _and(entry: Directive) -&gt; bool:\n        return left(entry) and right(entry)  # type: ignore[no-any-return]\n\n    p[0] = _and\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterSyntaxParser.p_expr_or","title":"<code>p_expr_or(p)</code>","text":"<p>expr : expr ',' expr</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>def p_expr_or(self, p: list[Any]) -&gt; None:\n    \"\"\"\n    expr : expr ',' expr\n    \"\"\"\n    left, right = p[1], p[3]\n\n    def _or(entry: Directive) -&gt; bool:\n        return left(entry) or right(entry)  # type: ignore[no-any-return]\n\n    p[0] = _or\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterSyntaxParser.p_expr_negated","title":"<code>p_expr_negated(p)</code>","text":"<p>expr : '-' expr %prec UMINUS</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>def p_expr_negated(self, p: list[Any]) -&gt; None:\n    \"\"\"\n    expr : '-' expr %prec UMINUS\n    \"\"\"\n    func = p[2]\n\n    def _neg(entry: Directive) -&gt; bool:\n        return not func(entry)\n\n    p[0] = _neg\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterSyntaxParser.p_simple_expr_TAG","title":"<code>p_simple_expr_TAG(p)</code>","text":"<p>simple_expr : TAG</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>def p_simple_expr_TAG(self, p: list[Any]) -&gt; None:  # noqa: N802\n    \"\"\"\n    simple_expr : TAG\n    \"\"\"\n    tag = p[1]\n\n    def _tag(entry: Directive) -&gt; bool:\n        tags = getattr(entry, \"tags\", None)\n        return (tag in tags) if tags is not None else False\n\n    p[0] = _tag\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterSyntaxParser.p_simple_expr_LINK","title":"<code>p_simple_expr_LINK(p)</code>","text":"<p>simple_expr : LINK</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>def p_simple_expr_LINK(self, p: list[Any]) -&gt; None:  # noqa: N802\n    \"\"\"\n    simple_expr : LINK\n    \"\"\"\n    link = p[1]\n\n    def _link(entry: Directive) -&gt; bool:\n        links = getattr(entry, \"links\", None)\n        return (link in links) if links is not None else False\n\n    p[0] = _link\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterSyntaxParser.p_simple_expr_STRING","title":"<code>p_simple_expr_STRING(p)</code>","text":"<p>simple_expr : STRING</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>def p_simple_expr_STRING(self, p: list[Any]) -&gt; None:  # noqa: N802\n    \"\"\"\n    simple_expr : STRING\n    \"\"\"\n    string = p[1]\n    match = Match(string)\n\n    def _string(entry: Directive) -&gt; bool:\n        for name in (\"narration\", \"payee\", \"comment\"):\n            value = getattr(entry, name, \"\")\n            if value and match(value):\n                return True\n        return False\n\n    p[0] = _string\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterSyntaxParser.p_simple_expr_key","title":"<code>p_simple_expr_key(p)</code>","text":"KEY EQ_OP STRING <p>| KEY CMP_OP NUMBER</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>def p_simple_expr_key(self, p: list[Any]) -&gt; None:\n    \"\"\"\n    simple_expr : KEY EQ_OP STRING\n                | KEY CMP_OP NUMBER\n    \"\"\"\n    key, op, value = p[1], p[2], p[3]\n    match: Match | MatchAmount = (\n        Match(value) if op == \":\" else MatchAmount(op, value)\n    )\n\n    def _key(entry: Directive) -&gt; bool:\n        if hasattr(entry, key):\n            return match(getattr(entry, key) or \"\")\n        if entry.meta is not None and key in entry.meta:\n            return match(entry.meta.get(key))\n        return False\n\n    p[0] = _key\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterSyntaxParser.p_simple_expr_units","title":"<code>p_simple_expr_units(p)</code>","text":"<p>simple_expr : CMP_OP NUMBER</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>def p_simple_expr_units(self, p: list[Any]) -&gt; None:\n    \"\"\"\n    simple_expr : CMP_OP NUMBER\n    \"\"\"\n    op, value = p[1], p[2]\n    match = MatchAmount(op, value)\n\n    def _range(entry: Directive) -&gt; bool:\n        return any(\n            match(posting.units)\n            for posting in getattr(entry, \"postings\", [])\n        )\n\n    p[0] = _range\n</code></pre>"},{"location":"api/#rustfava.core.filters.EntryFilter","title":"<code>EntryFilter</code>","text":"<p>               Bases: <code>ABC</code></p> <p>Filters a list of entries.</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>class EntryFilter(ABC):\n    \"\"\"Filters a list of entries.\"\"\"\n\n    @abstractmethod\n    def apply(self, entries: Sequence[Directive]) -&gt; Sequence[Directive]:\n        \"\"\"Filter a list of directives.\"\"\"\n</code></pre>"},{"location":"api/#rustfava.core.filters.EntryFilter.apply","title":"<code>apply(entries)</code>  <code>abstractmethod</code>","text":"<p>Filter a list of directives.</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>@abstractmethod\ndef apply(self, entries: Sequence[Directive]) -&gt; Sequence[Directive]:\n    \"\"\"Filter a list of directives.\"\"\"\n</code></pre>"},{"location":"api/#rustfava.core.filters.TimeFilter","title":"<code>TimeFilter</code>","text":"<p>               Bases: <code>EntryFilter</code></p> <p>Filter by dates.</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>class TimeFilter(EntryFilter):\n    \"\"\"Filter by dates.\"\"\"\n\n    __slots__ = (\"date_range\",)\n\n    def __init__(\n        self,\n        options: BeancountOptions,\n        fava_options: RustfavaOptions,\n        value: str,\n    ) -&gt; None:\n        del options  # unused\n        begin, end = parse_date(value, fava_options.fiscal_year_end)\n        if not begin or not end:\n            raise TimeFilterParseError(value)\n        self.date_range = DateRange(begin, end)\n\n    def apply(self, entries: Sequence[Directive]) -&gt; Sequence[Directive]:\n        from rustfava.rustledger.engine import RustledgerEngine\n        from rustfava.rustledger.types import directives_from_json\n        from rustfava.rustledger.types import directives_to_json\n\n        # Use native rustledger clamp_entries\n        engine = RustledgerEngine.get_instance()\n        entries_json = directives_to_json(list(entries))\n        result = engine.clamp_entries(\n            entries_json,\n            str(self.date_range.begin),\n            str(self.date_range.end),\n        )\n        return directives_from_json(result.get(\"entries\", []))\n</code></pre>"},{"location":"api/#rustfava.core.filters.AdvancedFilter","title":"<code>AdvancedFilter</code>","text":"<p>               Bases: <code>EntryFilter</code></p> <p>Filter by tags and links and keys.</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>class AdvancedFilter(EntryFilter):\n    \"\"\"Filter by tags and links and keys.\"\"\"\n\n    __slots__ = (\"_include\",)\n\n    def __init__(self, value: str) -&gt; None:\n        try:\n            tokens = LEXER.lex(value)\n            self._include = PARSE(\n                lexer=\"NONE\",\n                tokenfunc=lambda toks=tokens: next(toks, None),  # ty:ignore[invalid-argument-type]\n            )\n        except FilterError as exception:\n            exception.message += value\n            raise\n\n    def apply(self, entries: Sequence[Directive]) -&gt; Sequence[Directive]:\n        include = self._include\n        return [entry for entry in entries if include(entry)]\n</code></pre>"},{"location":"api/#rustfava.core.filters.AccountFilter","title":"<code>AccountFilter</code>","text":"<p>               Bases: <code>EntryFilter</code></p> <p>Filter by account.</p> <p>The filter string can either be a regular expression or a parent account.</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>class AccountFilter(EntryFilter):\n    \"\"\"Filter by account.\n\n    The filter string can either be a regular expression or a parent account.\n    \"\"\"\n\n    __slots__ = (\"_match\", \"_value\")\n\n    def __init__(self, value: str) -&gt; None:\n        self._value = value\n        self._match = Match(value)\n\n    def apply(self, entries: Sequence[Directive]) -&gt; Sequence[Directive]:\n        value = self._value\n        if not value:\n            return entries\n        match = self._match\n        return [\n            entry\n            for entry in entries\n            if any(\n                _has_component(name, value) or match(name)\n                for name in get_entry_accounts(entry)\n            )\n        ]\n</code></pre>"},{"location":"api/#rustfava.core.group_entries","title":"<code>group_entries</code>","text":"<p>Entries grouped by type.</p>"},{"location":"api/#rustfava.core.group_entries.EntriesByType","title":"<code>EntriesByType</code>","text":"<p>               Bases: <code>NamedTuple</code></p> <p>Entries grouped by type.</p> Source code in <code>src/rustfava/core/group_entries.py</code> <pre><code>class EntriesByType(NamedTuple):\n    \"\"\"Entries grouped by type.\"\"\"\n\n    Balance: Sequence[abc.Balance]\n    Close: Sequence[abc.Close]\n    Commodity: Sequence[abc.Commodity]\n    Custom: Sequence[abc.Custom]\n    Document: Sequence[abc.Document]\n    Event: Sequence[abc.Event]\n    Note: Sequence[abc.Note]\n    Open: Sequence[abc.Open]\n    Pad: Sequence[abc.Pad]\n    Price: Sequence[abc.Price]\n    Query: Sequence[abc.Query]\n    Transaction: Sequence[abc.Transaction]\n</code></pre>"},{"location":"api/#rustfava.core.group_entries.TransactionPosting","title":"<code>TransactionPosting</code>","text":"<p>               Bases: <code>NamedTuple</code></p> <p>Pair of a transaction and a posting.</p> Source code in <code>src/rustfava/core/group_entries.py</code> <pre><code>class TransactionPosting(NamedTuple):\n    \"\"\"Pair of a transaction and a posting.\"\"\"\n\n    transaction: abc.Transaction\n    posting: abc.Posting\n</code></pre>"},{"location":"api/#rustfava.core.group_entries.group_entries_by_type","title":"<code>group_entries_by_type(entries)</code>","text":"<p>Group entries by type.</p> <p>Parameters:</p> Name Type Description Default <code>entries</code> <code>Sequence[Directive]</code> <p>A list of entries to group.</p> required <p>Returns:</p> Type Description <code>EntriesByType</code> <p>A namedtuple containing the grouped lists of entries.</p> Source code in <code>src/rustfava/core/group_entries.py</code> <pre><code>def group_entries_by_type(entries: Sequence[abc.Directive]) -&gt; EntriesByType:\n    \"\"\"Group entries by type.\n\n    Arguments:\n        entries: A list of entries to group.\n\n    Returns:\n        A namedtuple containing the grouped lists of entries.\n    \"\"\"\n    entries_by_type = EntriesByType(\n        [],\n        [],\n        [],\n        [],\n        [],\n        [],\n        [],\n        [],\n        [],\n        [],\n        [],\n        [],\n    )\n    for entry in entries:\n        # Handle both beancount types (e.g., \"Transaction\") and\n        # rustledger types (e.g., \"RLTransaction\")\n        type_name = entry.__class__.__name__\n        if type_name.startswith(\"RL\"):\n            type_name = type_name[2:]  # Strip \"RL\" prefix\n        getattr(entries_by_type, type_name).append(entry)\n    return entries_by_type\n</code></pre>"},{"location":"api/#rustfava.core.group_entries.group_entries_by_account","title":"<code>group_entries_by_account(entries)</code>","text":"<p>Group entries by account.</p> <p>Parameters:</p> Name Type Description Default <code>entries</code> <code>Sequence[Directive]</code> <p>A list of entries.</p> required <p>Returns:</p> Type Description <code>Mapping[str, Sequence[Directive | TransactionPosting]]</code> <p>A dict mapping account names to their entries.</p> Source code in <code>src/rustfava/core/group_entries.py</code> <pre><code>def group_entries_by_account(\n    entries: Sequence[abc.Directive],\n) -&gt; Mapping[str, Sequence[abc.Directive | TransactionPosting]]:\n    \"\"\"Group entries by account.\n\n    Arguments:\n        entries: A list of entries.\n\n    Returns:\n        A dict mapping account names to their entries.\n    \"\"\"\n    res: dict[str, list[abc.Directive | TransactionPosting]] = defaultdict(\n        list,\n    )\n\n    for entry in entries:\n        if isinstance(entry, abc.Transaction):\n            for posting in entry.postings:\n                res[posting.account].append(TransactionPosting(entry, posting))\n        else:\n            for account in get_entry_accounts(entry):\n                res[account].append(entry)\n\n    return dict(sorted(res.items()))\n</code></pre>"},{"location":"api/#rustfava.core.ingest","title":"<code>ingest</code>","text":"<p>Ingest helper functions.</p>"},{"location":"api/#rustfava.core.ingest.IngestError","title":"<code>IngestError</code>  <code>dataclass</code>","text":"<p>               Bases: <code>BeancountError</code></p> <p>An error with one of the importers.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>class IngestError(BeancountError):\n    \"\"\"An error with one of the importers.\"\"\"\n</code></pre>"},{"location":"api/#rustfava.core.ingest.ImporterMethodCallError","title":"<code>ImporterMethodCallError</code>","text":"<p>               Bases: <code>RustfavaAPIError</code></p> <p>Error calling one of the importer methods.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>class ImporterMethodCallError(RustfavaAPIError):\n    \"\"\"Error calling one of the importer methods.\"\"\"\n\n    def __init__(self) -&gt; None:\n        super().__init__(\n            f\"Error calling method on importer:\\n\\n{traceback.format_exc()}\"\n        )\n</code></pre>"},{"location":"api/#rustfava.core.ingest.ImporterInvalidTypeError","title":"<code>ImporterInvalidTypeError</code>","text":"<p>               Bases: <code>RustfavaAPIError</code></p> <p>One of the importer methods returned an unexpected type.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>class ImporterInvalidTypeError(RustfavaAPIError):\n    \"\"\"One of the importer methods returned an unexpected type.\"\"\"\n\n    def __init__(self, attr: str, expected: type[Any], actual: Any) -&gt; None:\n        super().__init__(\n            f\"Got unexpected type from importer as {attr}:\"\n            f\" expected {expected!s}, got {type(actual)!s}:\"\n        )\n</code></pre>"},{"location":"api/#rustfava.core.ingest.ImporterExtractError","title":"<code>ImporterExtractError</code>","text":"<p>               Bases: <code>ImporterMethodCallError</code></p> <p>Error calling extract for importer.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>class ImporterExtractError(ImporterMethodCallError):\n    \"\"\"Error calling extract for importer.\"\"\"\n</code></pre>"},{"location":"api/#rustfava.core.ingest.MissingImporterConfigError","title":"<code>MissingImporterConfigError</code>","text":"<p>               Bases: <code>RustfavaAPIError</code></p> <p>Missing import-config option.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>class MissingImporterConfigError(RustfavaAPIError):\n    \"\"\"Missing import-config option.\"\"\"\n\n    def __init__(self) -&gt; None:\n        super().__init__(\"Missing import-config option\")\n</code></pre>"},{"location":"api/#rustfava.core.ingest.MissingImporterDirsError","title":"<code>MissingImporterDirsError</code>","text":"<p>               Bases: <code>RustfavaAPIError</code></p> <p>You need to set at least one imports-dir.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>class MissingImporterDirsError(RustfavaAPIError):\n    \"\"\"You need to set at least one imports-dir.\"\"\"\n\n    def __init__(self) -&gt; None:\n        super().__init__(\"You need to set at least one imports-dir.\")\n</code></pre>"},{"location":"api/#rustfava.core.ingest.ImportConfigLoadError","title":"<code>ImportConfigLoadError</code>","text":"<p>               Bases: <code>RustfavaAPIError</code></p> <p>Error on loading the import config.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>class ImportConfigLoadError(RustfavaAPIError):\n    \"\"\"Error on loading the import config.\"\"\"\n</code></pre>"},{"location":"api/#rustfava.core.ingest.FileImportInfo","title":"<code>FileImportInfo</code>  <code>dataclass</code>","text":"<p>Info about one file/importer combination.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>@dataclass(frozen=True)\nclass FileImportInfo:\n    \"\"\"Info about one file/importer combination.\"\"\"\n\n    importer_name: str\n    account: str\n    date: datetime.date\n    name: str\n</code></pre>"},{"location":"api/#rustfava.core.ingest.FileImporters","title":"<code>FileImporters</code>  <code>dataclass</code>","text":"<p>Importers for a file.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>@dataclass(frozen=True)\nclass FileImporters:\n    \"\"\"Importers for a file.\"\"\"\n\n    name: str\n    basename: str\n    importers: list[FileImportInfo]\n</code></pre>"},{"location":"api/#rustfava.core.ingest.WrappedImporter","title":"<code>WrappedImporter</code>","text":"<p>A wrapper to safely call importer methods.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>class WrappedImporter:\n    \"\"\"A wrapper to safely call importer methods.\"\"\"\n\n    importer: BeanImporterProtocol | Importer\n\n    def __init__(self, importer: BeanImporterProtocol | Importer) -&gt; None:\n        self.importer = importer\n\n    @property\n    @_catch_any\n    def name(self) -&gt; str:\n        \"\"\"Get the name of the importer.\"\"\"\n        importer = self.importer\n        name = (\n            importer.name\n            if isinstance(importer, Importer)\n            else importer.name()\n        )\n        return _assert_type(\"name\", name, str)\n\n    @_catch_any\n    def identify(self: WrappedImporter, path: Path) -&gt; bool:\n        \"\"\"Whether the importer is matching the file.\"\"\"\n        importer = self.importer\n        matches = (\n            importer.identify(str(path))\n            if isinstance(importer, Importer)\n            else importer.identify(get_cached_file(path))\n        )\n        return _assert_type(\"identify\", matches, bool)\n\n    @_catch_any\n    def file_import_info(self, path: Path) -&gt; FileImportInfo:\n        \"\"\"Generate info about a file with an importer.\"\"\"\n        importer = self.importer\n        if isinstance(importer, Importer):\n            str_path = str(path)\n            account = importer.account(str_path)\n            date = importer.date(str_path)\n            filename = importer.filename(str_path)\n        else:\n            file = get_cached_file(path)\n            account = importer.file_account(file)\n            date = importer.file_date(file)\n            filename = importer.file_name(file)\n\n        return FileImportInfo(\n            self.name,\n            _assert_type(\"account\", account or \"\", str),\n            _assert_type(\"date\", date or local_today(), datetime.date),\n            _assert_type(\"filename\", filename or path.name, str),\n        )\n</code></pre>"},{"location":"api/#rustfava.core.ingest.WrappedImporter.name","title":"<code>name</code>  <code>property</code>","text":"<p>Get the name of the importer.</p>"},{"location":"api/#rustfava.core.ingest.WrappedImporter.identify","title":"<code>identify(path)</code>","text":"<p>Whether the importer is matching the file.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>@_catch_any\ndef identify(self: WrappedImporter, path: Path) -&gt; bool:\n    \"\"\"Whether the importer is matching the file.\"\"\"\n    importer = self.importer\n    matches = (\n        importer.identify(str(path))\n        if isinstance(importer, Importer)\n        else importer.identify(get_cached_file(path))\n    )\n    return _assert_type(\"identify\", matches, bool)\n</code></pre>"},{"location":"api/#rustfava.core.ingest.WrappedImporter.file_import_info","title":"<code>file_import_info(path)</code>","text":"<p>Generate info about a file with an importer.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>@_catch_any\ndef file_import_info(self, path: Path) -&gt; FileImportInfo:\n    \"\"\"Generate info about a file with an importer.\"\"\"\n    importer = self.importer\n    if isinstance(importer, Importer):\n        str_path = str(path)\n        account = importer.account(str_path)\n        date = importer.date(str_path)\n        filename = importer.filename(str_path)\n    else:\n        file = get_cached_file(path)\n        account = importer.file_account(file)\n        date = importer.file_date(file)\n        filename = importer.file_name(file)\n\n    return FileImportInfo(\n        self.name,\n        _assert_type(\"account\", account or \"\", str),\n        _assert_type(\"date\", date or local_today(), datetime.date),\n        _assert_type(\"filename\", filename or path.name, str),\n    )\n</code></pre>"},{"location":"api/#rustfava.core.ingest.IngestModule","title":"<code>IngestModule</code>","text":"<p>               Bases: <code>FavaModule</code></p> <p>Exposes ingest functionality.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>class IngestModule(FavaModule):\n    \"\"\"Exposes ingest functionality.\"\"\"\n\n    def __init__(self, ledger: RustfavaLedger) -&gt; None:\n        super().__init__(ledger)\n        self.importers: Mapping[str, WrappedImporter] = {}\n        self.hooks: Hooks = []\n        self.mtime: int | None = None\n        self.errors: list[IngestError] = []\n\n    @property\n    def module_path(self) -&gt; Path | None:\n        \"\"\"The path to the importer configuration.\"\"\"\n        config_path = self.ledger.fava_options.import_config\n        if not config_path:\n            return None\n        return self.ledger.join_path(config_path)\n\n    def _error(self, msg: str) -&gt; None:\n        self.errors.append(\n            IngestError(\n                {\"filename\": str(self.module_path), \"lineno\": 0},\n                msg,\n                None,\n            ),\n        )\n\n    def load_file(self) -&gt; None:  # noqa: D102\n        self.errors = []\n        module_path = self.module_path\n        if module_path is None:\n            return\n\n        if not module_path.exists():\n            self._error(\"Import config does not exist\")\n            return\n\n        new_mtime = module_path.stat().st_mtime_ns\n        if new_mtime == self.mtime:\n            return\n\n        try:\n            self.importers, self.hooks = load_import_config(module_path)\n            self.mtime = new_mtime\n        except RustfavaAPIError as error:  # pragma: no cover\n            msg = f\"Error in import config '{module_path}': {error!s}\"\n            self._error(msg)\n\n    def import_data(self) -&gt; list[FileImporters]:\n        \"\"\"Identify files and importers that can be imported.\n\n        Returns:\n            A list of :class:`.FileImportInfo`.\n        \"\"\"\n        if not self.importers:\n            return []\n\n        importers = list(self.importers.values())\n\n        ret: list[FileImporters] = []\n        for directory in self.ledger.fava_options.import_dirs:\n            full_path = self.ledger.join_path(directory)\n            ret.extend(find_imports(importers, full_path))\n\n        return ret\n\n    def extract(self, filename: str, importer_name: str) -&gt; list[Directive]:\n        \"\"\"Extract entries from filename with the specified importer.\n\n        Args:\n            filename: The full path to a file.\n            importer_name: The name of an importer that matched the file.\n\n        Returns:\n            A list of new imported entries.\n        \"\"\"\n        if not self.module_path:\n            raise MissingImporterConfigError\n\n        # reload (if changed)\n        self.load_file()\n\n        try:\n            path = Path(filename)\n            importer = self.importers[importer_name]\n            new_entries = extract_from_file(\n                importer,\n                path,\n                existing_entries=self.ledger.all_entries,\n            )\n        except Exception as exc:\n            raise ImporterExtractError from exc\n\n        for hook_fn in self.hooks:\n            annotations = get_annotations(hook_fn)\n            if any(\"Importer\" in a for a in annotations.values()):\n                importer_info = importer.file_import_info(path)\n                new_entries_list: HookOutput = [\n                    (\n                        filename,\n                        new_entries,\n                        importer_info.account,\n                        importer.importer,\n                    )\n                ]\n            else:\n                new_entries_list = [(filename, new_entries)]\n\n            new_entries_list = hook_fn(\n                new_entries_list,\n                self.ledger.all_entries,\n            )\n\n            new_entries = new_entries_list[0][1]\n\n        return new_entries\n</code></pre>"},{"location":"api/#rustfava.core.ingest.IngestModule.module_path","title":"<code>module_path</code>  <code>property</code>","text":"<p>The path to the importer configuration.</p>"},{"location":"api/#rustfava.core.ingest.IngestModule.import_data","title":"<code>import_data()</code>","text":"<p>Identify files and importers that can be imported.</p> <p>Returns:</p> Type Description <code>list[FileImporters]</code> <p>A list of :class:<code>.FileImportInfo</code>.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>def import_data(self) -&gt; list[FileImporters]:\n    \"\"\"Identify files and importers that can be imported.\n\n    Returns:\n        A list of :class:`.FileImportInfo`.\n    \"\"\"\n    if not self.importers:\n        return []\n\n    importers = list(self.importers.values())\n\n    ret: list[FileImporters] = []\n    for directory in self.ledger.fava_options.import_dirs:\n        full_path = self.ledger.join_path(directory)\n        ret.extend(find_imports(importers, full_path))\n\n    return ret\n</code></pre>"},{"location":"api/#rustfava.core.ingest.IngestModule.extract","title":"<code>extract(filename, importer_name)</code>","text":"<p>Extract entries from filename with the specified importer.</p> <p>Parameters:</p> Name Type Description Default <code>filename</code> <code>str</code> <p>The full path to a file.</p> required <code>importer_name</code> <code>str</code> <p>The name of an importer that matched the file.</p> required <p>Returns:</p> Type Description <code>list[Directive]</code> <p>A list of new imported entries.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>def extract(self, filename: str, importer_name: str) -&gt; list[Directive]:\n    \"\"\"Extract entries from filename with the specified importer.\n\n    Args:\n        filename: The full path to a file.\n        importer_name: The name of an importer that matched the file.\n\n    Returns:\n        A list of new imported entries.\n    \"\"\"\n    if not self.module_path:\n        raise MissingImporterConfigError\n\n    # reload (if changed)\n    self.load_file()\n\n    try:\n        path = Path(filename)\n        importer = self.importers[importer_name]\n        new_entries = extract_from_file(\n            importer,\n            path,\n            existing_entries=self.ledger.all_entries,\n        )\n    except Exception as exc:\n        raise ImporterExtractError from exc\n\n    for hook_fn in self.hooks:\n        annotations = get_annotations(hook_fn)\n        if any(\"Importer\" in a for a in annotations.values()):\n            importer_info = importer.file_import_info(path)\n            new_entries_list: HookOutput = [\n                (\n                    filename,\n                    new_entries,\n                    importer_info.account,\n                    importer.importer,\n                )\n            ]\n        else:\n            new_entries_list = [(filename, new_entries)]\n\n        new_entries_list = hook_fn(\n            new_entries_list,\n            self.ledger.all_entries,\n        )\n\n        new_entries = new_entries_list[0][1]\n\n    return new_entries\n</code></pre>"},{"location":"api/#rustfava.core.ingest.walk_dir","title":"<code>walk_dir(directory)</code>","text":"<p>Walk through all files in dir.</p> <p>Ignores common dot-directories like .git, .cache. .venv, see IGNORE_DIRS.</p> <p>Parameters:</p> Name Type Description Default <code>directory</code> <code>Path</code> <p>The directory to start in.</p> required <p>Yields:</p> Type Description <code>Iterable[Path]</code> <p>All full paths under directory, ignoring some directories.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>def walk_dir(directory: Path) -&gt; Iterable[Path]:\n    \"\"\"Walk through all files in dir.\n\n    Ignores common dot-directories like .git, .cache. .venv, see IGNORE_DIRS.\n\n    Args:\n        directory: The directory to start in.\n\n    Yields:\n        All full paths under directory, ignoring some directories.\n    \"\"\"\n    for root, dirs, filenames in os.walk(directory):\n        dirs[:] = sorted(d for d in dirs if d not in IGNORE_DIRS)\n        root_path = Path(root)\n        for filename in sorted(filenames):\n            yield root_path / filename\n</code></pre>"},{"location":"api/#rustfava.core.ingest.get_cached_file","title":"<code>get_cached_file(path)</code>","text":"<p>Get a cached FileMemo.</p> <p>This checks the file's mtime before getting it from the Cache. In addition to using the beangulp cache.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>def get_cached_file(path: Path) -&gt; FileMemo:\n    \"\"\"Get a cached FileMemo.\n\n    This checks the file's mtime before getting it from the Cache.\n    In addition to using the beangulp cache.\n    \"\"\"\n    mtime = path.stat().st_mtime_ns\n    filename = str(path)\n    cached = _CACHE.get(path)\n    if cached:\n        mtime_cached, memo_cached = cached\n        if mtime &lt;= mtime_cached:  # pragma: no cover\n            return memo_cached\n    memo: FileMemo = cache._FileMemo(filename)  # noqa: SLF001\n    cache._CACHE[filename] = memo  # noqa: SLF001\n    _CACHE[path] = (mtime, memo)\n    return memo\n</code></pre>"},{"location":"api/#rustfava.core.ingest.find_imports","title":"<code>find_imports(config, directory)</code>","text":"<p>Pair files and matching importers.</p> <p>Yields:</p> Type Description <code>Iterable[FileImporters]</code> <p>For each file in directory, a pair of its filename and the matching</p> <code>Iterable[FileImporters]</code> <p>importers.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>def find_imports(\n    config: Sequence[WrappedImporter], directory: Path\n) -&gt; Iterable[FileImporters]:\n    \"\"\"Pair files and matching importers.\n\n    Yields:\n        For each file in directory, a pair of its filename and the matching\n        importers.\n    \"\"\"\n    for path in walk_dir(directory):\n        stat = path.stat()\n        if stat.st_size &gt; _FILE_TOO_LARGE_THRESHOLD:  # pragma: no cover\n            continue\n\n        importers = [\n            importer.file_import_info(path)\n            for importer in config\n            if importer.identify(path)\n        ]\n        yield FileImporters(\n            name=str(path), basename=path.name, importers=importers\n        )\n</code></pre>"},{"location":"api/#rustfava.core.ingest.extract_from_file","title":"<code>extract_from_file(wrapped_importer, path, existing_entries)</code>","text":"<p>Import entries from a document.</p> <p>Parameters:</p> Name Type Description Default <code>wrapped_importer</code> <code>WrappedImporter</code> <p>The importer instance to handle the document.</p> required <code>path</code> <code>Path</code> <p>Filesystem path to the document.</p> required <code>existing_entries</code> <code>Sequence[Directive]</code> <p>Existing entries.</p> required <p>Returns:</p> Type Description <code>list[Directive]</code> <p>The list of imported entries.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>def extract_from_file(\n    wrapped_importer: WrappedImporter,\n    path: Path,\n    existing_entries: Sequence[Directive],\n) -&gt; list[Directive]:\n    \"\"\"Import entries from a document.\n\n    Args:\n      wrapped_importer: The importer instance to handle the document.\n      path: Filesystem path to the document.\n      existing_entries: Existing entries.\n\n    Returns:\n      The list of imported entries.\n    \"\"\"\n    filename = str(path)\n    importer = wrapped_importer.importer\n    if isinstance(importer, Importer):\n        entries = importer.extract(filename, existing=existing_entries)\n    else:\n        file = get_cached_file(path)\n        entries = (\n            importer.extract(file, existing_entries=existing_entries)\n            if \"existing_entries\" in signature(importer.extract).parameters\n            else importer.extract(file)\n        ) or []\n\n    if hasattr(importer, \"sort\"):\n        importer.sort(entries)\n    else:\n        entries.sort(key=_incomplete_sortkey)\n    if isinstance(importer, Importer):\n        importer.deduplicate(entries, existing=existing_entries)\n    return entries\n</code></pre>"},{"location":"api/#rustfava.core.ingest.load_import_config","title":"<code>load_import_config(module_path)</code>","text":"<p>Load the given import config and extract importers and hooks.</p> <p>Parameters:</p> Name Type Description Default <code>module_path</code> <code>Path</code> <p>Path to the import config.</p> required <p>Returns:</p> Type Description <code>tuple[Mapping[str, WrappedImporter], Hooks]</code> <p>A pair of the importers (by name) and the list of hooks.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>def load_import_config(\n    module_path: Path,\n) -&gt; tuple[Mapping[str, WrappedImporter], Hooks]:\n    \"\"\"Load the given import config and extract importers and hooks.\n\n    Args:\n        module_path: Path to the import config.\n\n    Returns:\n        A pair of the importers (by name) and the list of hooks.\n    \"\"\"\n    try:\n        mod = run_path(str(module_path))\n    except Exception as error:  # pragma: no cover\n        message = traceback.format_exc()\n        raise ImportConfigLoadError(message) from error\n\n    if \"CONFIG\" not in mod:\n        msg = \"CONFIG is missing\"\n        raise ImportConfigLoadError(msg)\n    if not isinstance(mod[\"CONFIG\"], list):  # pragma: no cover\n        msg = \"CONFIG is not a list\"\n        raise ImportConfigLoadError(msg)\n\n    config = mod[\"CONFIG\"]\n    hooks = DEFAULT_HOOKS\n    if \"HOOKS\" in mod:  # pragma: no cover\n        hooks = mod[\"HOOKS\"]\n        if not isinstance(hooks, list) or not all(\n            callable(fn) for fn in hooks\n        ):\n            msg = \"HOOKS is not a list of callables\"\n            raise ImportConfigLoadError(msg)\n    importers = {}\n    for importer in config:\n        if not isinstance(\n            importer, (BeanImporterProtocol, Importer)\n        ):  # pragma: no cover\n            name = importer.__class__.__name__\n            msg = (\n                f\"Importer class '{name}' in '{module_path}' does \"\n                \"not satisfy importer protocol\"\n            )\n            raise ImportConfigLoadError(msg)\n        wrapped_importer = WrappedImporter(importer)\n        if wrapped_importer.name in importers:\n            msg = f\"Duplicate importer name found: {wrapped_importer.name}\"\n            raise ImportConfigLoadError(msg)\n        importers[wrapped_importer.name] = wrapped_importer\n    return importers, hooks\n</code></pre>"},{"location":"api/#rustfava.core.ingest.filepath_in_primary_imports_folder","title":"<code>filepath_in_primary_imports_folder(filename, ledger)</code>","text":"<p>File path for a document to upload to the primary import folder.</p> <p>Parameters:</p> Name Type Description Default <code>filename</code> <code>str</code> <p>The filename of the document.</p> required <code>ledger</code> <code>RustfavaLedger</code> <p>The RustfavaLedger.</p> required <p>Returns:</p> Type Description <code>Path</code> <p>The path that the document should be saved at.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>def filepath_in_primary_imports_folder(\n    filename: str,\n    ledger: RustfavaLedger,\n) -&gt; Path:\n    \"\"\"File path for a document to upload to the primary import folder.\n\n    Args:\n        filename: The filename of the document.\n        ledger: The RustfavaLedger.\n\n    Returns:\n        The path that the document should be saved at.\n    \"\"\"\n    primary_imports_folder = next(iter(ledger.fava_options.import_dirs), None)\n    if primary_imports_folder is None:\n        raise MissingImporterDirsError\n\n    filename = filename.replace(sep, \" \")\n    if altsep:  # pragma: no cover\n        filename = filename.replace(altsep, \" \")\n\n    return ledger.join_path(primary_imports_folder, filename)\n</code></pre>"},{"location":"api/#rustfava.core.inventory","title":"<code>inventory</code>","text":"<p>Alternative implementation of Beancount's Inventory.</p>"},{"location":"api/#rustfava.core.inventory.SimpleCounterInventory","title":"<code>SimpleCounterInventory</code>","text":"<p>               Bases: <code>dict[str, Decimal]</code></p> <p>A simple inventory mapping just strings to numbers.</p> Source code in <code>src/rustfava/core/inventory.py</code> <pre><code>class SimpleCounterInventory(dict[str, Decimal]):\n    \"\"\"A simple inventory mapping just strings to numbers.\"\"\"\n\n    def is_empty(self) -&gt; bool:\n        \"\"\"Check if the inventory is empty.\"\"\"\n        return not bool(self)\n\n    def add(self, key: str, number: Decimal) -&gt; None:\n        \"\"\"Add a number to key.\"\"\"\n        new_num = number + self.get(key, ZERO)\n        if new_num == ZERO:\n            self.pop(key, None)\n        else:\n            self[key] = new_num\n\n    def __iter__(self) -&gt; Iterator[str]:\n        raise NotImplementedError\n\n    def __neg__(self) -&gt; SimpleCounterInventory:\n        return SimpleCounterInventory({key: -num for key, num in self.items()})\n\n    def reduce(\n        self,\n        reducer: Callable[Concatenate[Position, P], Amount],\n        *args: P.args,\n        **_kwargs: P.kwargs,\n    ) -&gt; SimpleCounterInventory:\n        \"\"\"Reduce inventory.\"\"\"\n        counter = SimpleCounterInventory()\n        for currency, number in self.items():\n            pos = _Position(_Amount(number, currency), None)\n            amount = reducer(pos, *args)  # type: ignore[call-arg]\n            counter.add(amount.currency, amount.number)\n        return counter\n</code></pre>"},{"location":"api/#rustfava.core.inventory.SimpleCounterInventory.is_empty","title":"<code>is_empty()</code>","text":"<p>Check if the inventory is empty.</p> Source code in <code>src/rustfava/core/inventory.py</code> <pre><code>def is_empty(self) -&gt; bool:\n    \"\"\"Check if the inventory is empty.\"\"\"\n    return not bool(self)\n</code></pre>"},{"location":"api/#rustfava.core.inventory.SimpleCounterInventory.add","title":"<code>add(key, number)</code>","text":"<p>Add a number to key.</p> Source code in <code>src/rustfava/core/inventory.py</code> <pre><code>def add(self, key: str, number: Decimal) -&gt; None:\n    \"\"\"Add a number to key.\"\"\"\n    new_num = number + self.get(key, ZERO)\n    if new_num == ZERO:\n        self.pop(key, None)\n    else:\n        self[key] = new_num\n</code></pre>"},{"location":"api/#rustfava.core.inventory.SimpleCounterInventory.reduce","title":"<code>reduce(reducer, *args, **_kwargs)</code>","text":"<p>Reduce inventory.</p> Source code in <code>src/rustfava/core/inventory.py</code> <pre><code>def reduce(\n    self,\n    reducer: Callable[Concatenate[Position, P], Amount],\n    *args: P.args,\n    **_kwargs: P.kwargs,\n) -&gt; SimpleCounterInventory:\n    \"\"\"Reduce inventory.\"\"\"\n    counter = SimpleCounterInventory()\n    for currency, number in self.items():\n        pos = _Position(_Amount(number, currency), None)\n        amount = reducer(pos, *args)  # type: ignore[call-arg]\n        counter.add(amount.currency, amount.number)\n    return counter\n</code></pre>"},{"location":"api/#rustfava.core.inventory.CounterInventory","title":"<code>CounterInventory</code>","text":"<p>               Bases: <code>dict[InventoryKey, Decimal]</code></p> <p>A lightweight inventory.</p> <p>This is intended as a faster alternative to Beancount's Inventory class. Due to not using a list, for inventories with a lot of different positions, inserting is much faster.</p> <p>The keys should be tuples <code>(currency, cost)</code>.</p> Source code in <code>src/rustfava/core/inventory.py</code> <pre><code>class CounterInventory(dict[InventoryKey, Decimal]):\n    \"\"\"A lightweight inventory.\n\n    This is intended as a faster alternative to Beancount's Inventory class.\n    Due to not using a list, for inventories with a lot of different positions,\n    inserting is much faster.\n\n    The keys should be tuples ``(currency, cost)``.\n    \"\"\"\n\n    def is_empty(self) -&gt; bool:\n        \"\"\"Check if the inventory is empty.\"\"\"\n        return not bool(self)\n\n    def add(self, key: InventoryKey, number: Decimal) -&gt; None:\n        \"\"\"Add a number to key.\"\"\"\n        new_num = number + self.get(key, ZERO)\n        if new_num == ZERO:\n            self.pop(key, None)\n        else:\n            self[key] = new_num\n\n    def __iter__(self) -&gt; Iterator[InventoryKey]:\n        raise NotImplementedError\n\n    def to_strings(self) -&gt; list[str]:\n        \"\"\"Print as a list of strings (e.g. for snapshot tests).\"\"\"\n        strings = []\n        for (currency, cost), number in self.items():\n            if cost is None:\n                strings.append(f\"{number} {currency}\")\n            else:\n                cost_str = cost_to_string(cost)\n                strings.append(f\"{number} {currency} {{{cost_str}}}\")\n        return strings\n\n    def reduce(\n        self,\n        reducer: Callable[Concatenate[Position, P], Amount],\n        *args: P.args,\n        **_kwargs: P.kwargs,\n    ) -&gt; SimpleCounterInventory:\n        \"\"\"Reduce inventory.\n\n        Note that this returns a simple :class:`CounterInventory` with just\n        currencies as keys.\n        \"\"\"\n        counter = SimpleCounterInventory()\n        for (currency, cost), number in self.items():\n            pos = _Position(_Amount(number, currency), cost)\n            amount = reducer(pos, *args)  # type: ignore[call-arg]\n            counter.add(amount.currency, amount.number)\n        return counter\n\n    def add_amount(self, amount: Amount, cost: Cost | None = None) -&gt; None:\n        \"\"\"Add an Amount to the inventory.\"\"\"\n        key = (amount.currency, cost)\n        self.add(key, amount.number)\n\n    def add_position(self, pos: Position) -&gt; None:\n        \"\"\"Add a Position or Posting to the inventory.\"\"\"\n        # Skip positions with missing units (can happen with parse errors)\n        if pos.units is None:\n            return\n        self.add_amount(pos.units, pos.cost)\n\n    def __neg__(self) -&gt; CounterInventory:\n        return CounterInventory({key: -num for key, num in self.items()})\n\n    def __add__(self, other: CounterInventory) -&gt; CounterInventory:\n        counter = CounterInventory(self)\n        counter.add_inventory(other)\n        return counter\n\n    def add_inventory(self, counter: CounterInventory) -&gt; None:\n        \"\"\"Add another :class:`CounterInventory`.\"\"\"\n        if not self:\n            self.update(counter)\n        else:\n            self_get = self.get\n            for key, num in counter.items():\n                new_num = num + self_get(key, ZERO)\n                if new_num == ZERO:\n                    self.pop(key, None)\n                else:\n                    self[key] = new_num\n</code></pre>"},{"location":"api/#rustfava.core.inventory.CounterInventory.is_empty","title":"<code>is_empty()</code>","text":"<p>Check if the inventory is empty.</p> Source code in <code>src/rustfava/core/inventory.py</code> <pre><code>def is_empty(self) -&gt; bool:\n    \"\"\"Check if the inventory is empty.\"\"\"\n    return not bool(self)\n</code></pre>"},{"location":"api/#rustfava.core.inventory.CounterInventory.add","title":"<code>add(key, number)</code>","text":"<p>Add a number to key.</p> Source code in <code>src/rustfava/core/inventory.py</code> <pre><code>def add(self, key: InventoryKey, number: Decimal) -&gt; None:\n    \"\"\"Add a number to key.\"\"\"\n    new_num = number + self.get(key, ZERO)\n    if new_num == ZERO:\n        self.pop(key, None)\n    else:\n        self[key] = new_num\n</code></pre>"},{"location":"api/#rustfava.core.inventory.CounterInventory.to_strings","title":"<code>to_strings()</code>","text":"<p>Print as a list of strings (e.g. for snapshot tests).</p> Source code in <code>src/rustfava/core/inventory.py</code> <pre><code>def to_strings(self) -&gt; list[str]:\n    \"\"\"Print as a list of strings (e.g. for snapshot tests).\"\"\"\n    strings = []\n    for (currency, cost), number in self.items():\n        if cost is None:\n            strings.append(f\"{number} {currency}\")\n        else:\n            cost_str = cost_to_string(cost)\n            strings.append(f\"{number} {currency} {{{cost_str}}}\")\n    return strings\n</code></pre>"},{"location":"api/#rustfava.core.inventory.CounterInventory.reduce","title":"<code>reduce(reducer, *args, **_kwargs)</code>","text":"<p>Reduce inventory.</p> <p>Note that this returns a simple :class:<code>CounterInventory</code> with just currencies as keys.</p> Source code in <code>src/rustfava/core/inventory.py</code> <pre><code>def reduce(\n    self,\n    reducer: Callable[Concatenate[Position, P], Amount],\n    *args: P.args,\n    **_kwargs: P.kwargs,\n) -&gt; SimpleCounterInventory:\n    \"\"\"Reduce inventory.\n\n    Note that this returns a simple :class:`CounterInventory` with just\n    currencies as keys.\n    \"\"\"\n    counter = SimpleCounterInventory()\n    for (currency, cost), number in self.items():\n        pos = _Position(_Amount(number, currency), cost)\n        amount = reducer(pos, *args)  # type: ignore[call-arg]\n        counter.add(amount.currency, amount.number)\n    return counter\n</code></pre>"},{"location":"api/#rustfava.core.inventory.CounterInventory.add_amount","title":"<code>add_amount(amount, cost=None)</code>","text":"<p>Add an Amount to the inventory.</p> Source code in <code>src/rustfava/core/inventory.py</code> <pre><code>def add_amount(self, amount: Amount, cost: Cost | None = None) -&gt; None:\n    \"\"\"Add an Amount to the inventory.\"\"\"\n    key = (amount.currency, cost)\n    self.add(key, amount.number)\n</code></pre>"},{"location":"api/#rustfava.core.inventory.CounterInventory.add_position","title":"<code>add_position(pos)</code>","text":"<p>Add a Position or Posting to the inventory.</p> Source code in <code>src/rustfava/core/inventory.py</code> <pre><code>def add_position(self, pos: Position) -&gt; None:\n    \"\"\"Add a Position or Posting to the inventory.\"\"\"\n    # Skip positions with missing units (can happen with parse errors)\n    if pos.units is None:\n        return\n    self.add_amount(pos.units, pos.cost)\n</code></pre>"},{"location":"api/#rustfava.core.inventory.CounterInventory.add_inventory","title":"<code>add_inventory(counter)</code>","text":"<p>Add another :class:<code>CounterInventory</code>.</p> Source code in <code>src/rustfava/core/inventory.py</code> <pre><code>def add_inventory(self, counter: CounterInventory) -&gt; None:\n    \"\"\"Add another :class:`CounterInventory`.\"\"\"\n    if not self:\n        self.update(counter)\n    else:\n        self_get = self.get\n        for key, num in counter.items():\n            new_num = num + self_get(key, ZERO)\n            if new_num == ZERO:\n                self.pop(key, None)\n            else:\n                self[key] = new_num\n</code></pre>"},{"location":"api/#rustfava.core.misc","title":"<code>misc</code>","text":"<p>Some miscellaneous reports.</p>"},{"location":"api/#rustfava.core.misc.FavaError","title":"<code>FavaError</code>  <code>dataclass</code>","text":"<p>               Bases: <code>BeancountError</code></p> <p>Generic Fava-specific error.</p> Source code in <code>src/rustfava/core/misc.py</code> <pre><code>class FavaError(BeancountError):\n    \"\"\"Generic Fava-specific error.\"\"\"\n</code></pre>"},{"location":"api/#rustfava.core.misc.FavaMisc","title":"<code>FavaMisc</code>","text":"<p>               Bases: <code>FavaModule</code></p> <p>Provides access to some miscellaneous reports.</p> Source code in <code>src/rustfava/core/misc.py</code> <pre><code>class FavaMisc(FavaModule):\n    \"\"\"Provides access to some miscellaneous reports.\"\"\"\n\n    def __init__(self, ledger: RustfavaLedger) -&gt; None:\n        super().__init__(ledger)\n        #: User-chosen links to show in the sidebar.\n        self.sidebar_links: SidebarLinks = []\n        #: Upcoming events in the next few days.\n        self.upcoming_events: Sequence[Event] = []\n\n    def load_file(self) -&gt; None:  # noqa: D102\n        custom_entries = self.ledger.all_entries_by_type.Custom\n        self.sidebar_links = sidebar_links(custom_entries)\n\n        self.upcoming_events = upcoming_events(\n            self.ledger.all_entries_by_type.Event,\n            self.ledger.fava_options.upcoming_events,\n        )\n\n    @property\n    def errors(self) -&gt; Sequence[FavaError]:\n        \"\"\"An error if no operating currency is set.\"\"\"\n        return (\n            []\n            if self.ledger.options[\"operating_currency\"]\n            else [NO_OPERATING_CURRENCY_ERROR]\n        )\n</code></pre>"},{"location":"api/#rustfava.core.misc.FavaMisc.errors","title":"<code>errors</code>  <code>property</code>","text":"<p>An error if no operating currency is set.</p>"},{"location":"api/#rustfava.core.misc.sidebar_links","title":"<code>sidebar_links(custom_entries)</code>","text":"<p>Parse custom entries for links.</p> <p>They have the following format:</p> <p>2016-04-01 custom \"fava-sidebar-link\" \"2014\" \"/income_statement/?time=2014\"</p> Source code in <code>src/rustfava/core/misc.py</code> <pre><code>def sidebar_links(custom_entries: Sequence[Custom]) -&gt; SidebarLinks:\n    \"\"\"Parse custom entries for links.\n\n    They have the following format:\n\n    2016-04-01 custom \"fava-sidebar-link\" \"2014\" \"/income_statement/?time=2014\"\n    \"\"\"\n    sidebar_link_entries = [\n        entry for entry in custom_entries if entry.type == \"fava-sidebar-link\"\n    ]\n    return [\n        (entry.values[0].value, entry.values[1].value)\n        for entry in sidebar_link_entries\n    ]\n</code></pre>"},{"location":"api/#rustfava.core.misc.upcoming_events","title":"<code>upcoming_events(events, max_delta)</code>","text":"<p>Parse entries for upcoming events.</p> <p>Parameters:</p> Name Type Description Default <code>events</code> <code>Sequence[Event]</code> <p>A list of events.</p> required <code>max_delta</code> <code>int</code> <p>Number of days that should be considered.</p> required <p>Returns:</p> Type Description <code>Sequence[Event]</code> <p>A list of the Events in entries that are less than <code>max_delta</code> days</p> <code>Sequence[Event]</code> <p>away.</p> Source code in <code>src/rustfava/core/misc.py</code> <pre><code>def upcoming_events(\n    events: Sequence[Event], max_delta: int\n) -&gt; Sequence[Event]:\n    \"\"\"Parse entries for upcoming events.\n\n    Args:\n        events: A list of events.\n        max_delta: Number of days that should be considered.\n\n    Returns:\n        A list of the Events in entries that are less than `max_delta` days\n        away.\n    \"\"\"\n    today = local_today()\n    upcoming = []\n\n    for event in events:\n        delta = event.date - today\n        if delta.days &gt;= 0 and delta.days &lt; max_delta:\n            upcoming.append(event)\n\n    return upcoming\n</code></pre>"},{"location":"api/#rustfava.core.misc.align","title":"<code>align(string, currency_column)</code>","text":"<p>Align currencies in one column.</p> Source code in <code>src/rustfava/beans/str.py</code> <pre><code>def align(string: str, currency_column: int) -&gt; str:\n    \"\"\"Align currencies in one column.\"\"\"\n    output = io.StringIO()\n    for line in string.splitlines():\n        match = ALIGN_RE.match(line)\n        if match:\n            prefix, number, rest = match.groups()\n            num_of_spaces = currency_column - len(prefix) - len(number) - 4\n            spaces = \" \" * num_of_spaces\n            output.write(prefix + spaces + \"  \" + number + \" \" + rest)\n        else:\n            output.write(line)\n        output.write(\"\\n\")\n\n    return output.getvalue()\n</code></pre>"},{"location":"api/#rustfava.core.module_base","title":"<code>module_base</code>","text":"<p>Base class for the \"modules\" of rustfavaLedger.</p>"},{"location":"api/#rustfava.core.module_base.FavaModule","title":"<code>FavaModule</code>","text":"<p>Base class for the \"modules\" of rustfavaLedger.</p> Source code in <code>src/rustfava/core/module_base.py</code> <pre><code>class FavaModule:\n    \"\"\"Base class for the \"modules\" of rustfavaLedger.\"\"\"\n\n    def __init__(self, ledger: RustfavaLedger) -&gt; None:\n        self.ledger = ledger\n\n    def load_file(self) -&gt; None:\n        \"\"\"Run when the file has been (re)loaded.\"\"\"\n</code></pre>"},{"location":"api/#rustfava.core.module_base.FavaModule.load_file","title":"<code>load_file()</code>","text":"<p>Run when the file has been (re)loaded.</p> Source code in <code>src/rustfava/core/module_base.py</code> <pre><code>def load_file(self) -&gt; None:\n    \"\"\"Run when the file has been (re)loaded.\"\"\"\n</code></pre>"},{"location":"api/#rustfava.core.number","title":"<code>number</code>","text":"<p>Formatting numbers.</p>"},{"location":"api/#rustfava.core.number.DecimalFormatModule","title":"<code>DecimalFormatModule</code>","text":"<p>               Bases: <code>FavaModule</code></p> <p>Formatting numbers.</p> Source code in <code>src/rustfava/core/number.py</code> <pre><code>class DecimalFormatModule(FavaModule):\n    \"\"\"Formatting numbers.\"\"\"\n\n    def __init__(self, ledger: RustfavaLedger) -&gt; None:\n        super().__init__(ledger)\n        self._locale: Locale | None = None\n        self._formatters: dict[str, Formatter] = {}\n        self._default_pattern = get_locale_format(None, 2)\n        self.precisions: dict[str, int] = {}\n\n    def load_file(self) -&gt; None:  # noqa: D102\n        locale = None\n\n        locale_option = self.ledger.fava_options.locale\n        if (\n            self.ledger.options[\"render_commas\"] and not locale_option\n        ):  # pragma: no cover\n            locale_option = \"en\"\n            self.ledger.fava_options.locale = locale_option\n\n        if locale_option:\n            locale = Locale.parse(locale_option)\n\n        dcontext = self.ledger.options[\"dcontext\"]\n        precisions: dict[str, int] = {}\n\n        # Both beancount's DisplayContext and RLDisplayContext have ccontexts\n        for currency, ccontext in dcontext.ccontexts.items():\n            prec = ccontext.get_fractional(None)\n            if prec is not None:\n                precisions[currency] = prec\n\n        precisions.update(self.ledger.commodities.precisions)\n\n        self._locale = locale\n        self._default_pattern = get_locale_format(locale, 2)\n        self._formatters = {\n            currency: get_locale_format(locale, prec)\n            for currency, prec in precisions.items()\n        }\n        self.precisions = precisions\n\n    def __call__(self, value: Decimal, currency: str | None = None) -&gt; str:\n        \"\"\"Format a decimal to the right number of decimal digits with locale.\n\n        Arguments:\n            value: A decimal number.\n            currency: A currency string or None.\n\n        Returns:\n            A string, the formatted decimal.\n        \"\"\"\n        if currency is None:\n            return self._default_pattern(value)\n        return self._formatters.get(currency, self._default_pattern)(value)\n</code></pre>"},{"location":"api/#rustfava.core.number.DecimalFormatModule.__call__","title":"<code>__call__(value, currency=None)</code>","text":"<p>Format a decimal to the right number of decimal digits with locale.</p> <p>Parameters:</p> Name Type Description Default <code>value</code> <code>Decimal</code> <p>A decimal number.</p> required <code>currency</code> <code>str | None</code> <p>A currency string or None.</p> <code>None</code> <p>Returns:</p> Type Description <code>str</code> <p>A string, the formatted decimal.</p> Source code in <code>src/rustfava/core/number.py</code> <pre><code>def __call__(self, value: Decimal, currency: str | None = None) -&gt; str:\n    \"\"\"Format a decimal to the right number of decimal digits with locale.\n\n    Arguments:\n        value: A decimal number.\n        currency: A currency string or None.\n\n    Returns:\n        A string, the formatted decimal.\n    \"\"\"\n    if currency is None:\n        return self._default_pattern(value)\n    return self._formatters.get(currency, self._default_pattern)(value)\n</code></pre>"},{"location":"api/#rustfava.core.number.get_locale_format","title":"<code>get_locale_format(locale, precision)</code>","text":"<p>Obtain formatting pattern for the given locale and precision.</p> <p>Parameters:</p> Name Type Description Default <code>locale</code> <code>Locale | None</code> <p>An optional locale.</p> required <code>precision</code> <code>int</code> <p>The precision.</p> required <p>Returns:</p> Type Description <code>Formatter</code> <p>A function that renders Decimals to strings as desired.</p> Source code in <code>src/rustfava/core/number.py</code> <pre><code>def get_locale_format(locale: Locale | None, precision: int) -&gt; Formatter:\n    \"\"\"Obtain formatting pattern for the given locale and precision.\n\n    Arguments:\n        locale: An optional locale.\n        precision: The precision.\n\n    Returns:\n        A function that renders Decimals to strings as desired.\n    \"\"\"\n    # Set a maximum precision of 14, half the default precision of Decimal\n    precision = min(precision, 14)\n    if locale is None:\n        fmt_string = \"{:.\" + str(precision) + \"f}\"\n\n        def fmt(num: Decimal) -&gt; str:\n            return fmt_string.format(num)\n\n        return fmt\n\n    pattern = copy.copy(locale.decimal_formats.get(None))\n    if not pattern:  # pragma: no cover\n        msg = \"Expected Locale to have a decimal format pattern\"\n        raise ValueError(msg)\n    pattern.frac_prec = (precision, precision)\n\n    def locale_fmt(num: Decimal) -&gt; str:\n        return pattern.apply(num, locale)  # type: ignore[no-any-return]\n\n    return locale_fmt\n</code></pre>"},{"location":"api/#rustfava.core.query","title":"<code>query</code>","text":"<p>Query result types.</p>"},{"location":"api/#rustfava.core.query.QueryResultTable","title":"<code>QueryResultTable</code>  <code>dataclass</code>","text":"<p>Table query result.</p> Source code in <code>src/rustfava/core/query.py</code> <pre><code>@dataclass(frozen=True)\nclass QueryResultTable:\n    \"\"\"Table query result.\"\"\"\n\n    types: list[BaseColumn]\n    rows: list[tuple[SerialisedQueryRowValue, ...]]\n    t: Literal[\"table\"] = \"table\"\n</code></pre>"},{"location":"api/#rustfava.core.query.QueryResultText","title":"<code>QueryResultText</code>  <code>dataclass</code>","text":"<p>Text query result.</p> Source code in <code>src/rustfava/core/query.py</code> <pre><code>@dataclass(frozen=True)\nclass QueryResultText:\n    \"\"\"Text query result.\"\"\"\n\n    contents: str\n    t: Literal[\"string\"] = \"string\"\n</code></pre>"},{"location":"api/#rustfava.core.query.BaseColumn","title":"<code>BaseColumn</code>  <code>dataclass</code>","text":"<p>A query column.</p> Source code in <code>src/rustfava/core/query.py</code> <pre><code>@dataclass(frozen=True)\nclass BaseColumn:\n    \"\"\"A query column.\"\"\"\n\n    name: str\n    dtype: str\n\n    @staticmethod\n    def serialise(\n        val: QueryRowValue,\n    ) -&gt; SerialisedQueryRowValue:\n        \"\"\"Serialiseable version of the column value.\"\"\"\n        return val  # type: ignore[no-any-return]\n</code></pre>"},{"location":"api/#rustfava.core.query.BaseColumn.serialise","title":"<code>serialise(val)</code>  <code>staticmethod</code>","text":"<p>Serialiseable version of the column value.</p> Source code in <code>src/rustfava/core/query.py</code> <pre><code>@staticmethod\ndef serialise(\n    val: QueryRowValue,\n) -&gt; SerialisedQueryRowValue:\n    \"\"\"Serialiseable version of the column value.\"\"\"\n    return val  # type: ignore[no-any-return]\n</code></pre>"},{"location":"api/#rustfava.core.query.BoolColumn","title":"<code>BoolColumn</code>  <code>dataclass</code>","text":"<p>               Bases: <code>BaseColumn</code></p> <p>A boolean query column.</p> Source code in <code>src/rustfava/core/query.py</code> <pre><code>@dataclass(frozen=True)\nclass BoolColumn(BaseColumn):\n    \"\"\"A boolean query column.\"\"\"\n\n    dtype: str = \"bool\"\n</code></pre>"},{"location":"api/#rustfava.core.query.DecimalColumn","title":"<code>DecimalColumn</code>  <code>dataclass</code>","text":"<p>               Bases: <code>BaseColumn</code></p> <p>A Decimal query column.</p> Source code in <code>src/rustfava/core/query.py</code> <pre><code>@dataclass(frozen=True)\nclass DecimalColumn(BaseColumn):\n    \"\"\"A Decimal query column.\"\"\"\n\n    dtype: str = \"Decimal\"\n</code></pre>"},{"location":"api/#rustfava.core.query.IntColumn","title":"<code>IntColumn</code>  <code>dataclass</code>","text":"<p>               Bases: <code>BaseColumn</code></p> <p>A int query column.</p> Source code in <code>src/rustfava/core/query.py</code> <pre><code>@dataclass(frozen=True)\nclass IntColumn(BaseColumn):\n    \"\"\"A int query column.\"\"\"\n\n    dtype: str = \"int\"\n</code></pre>"},{"location":"api/#rustfava.core.query.StrColumn","title":"<code>StrColumn</code>  <code>dataclass</code>","text":"<p>               Bases: <code>BaseColumn</code></p> <p>A str query column.</p> Source code in <code>src/rustfava/core/query.py</code> <pre><code>@dataclass(frozen=True)\nclass StrColumn(BaseColumn):\n    \"\"\"A str query column.\"\"\"\n\n    dtype: str = \"str\"\n</code></pre>"},{"location":"api/#rustfava.core.query.DateColumn","title":"<code>DateColumn</code>  <code>dataclass</code>","text":"<p>               Bases: <code>BaseColumn</code></p> <p>A date query column.</p> Source code in <code>src/rustfava/core/query.py</code> <pre><code>@dataclass(frozen=True)\nclass DateColumn(BaseColumn):\n    \"\"\"A date query column.\"\"\"\n\n    dtype: str = \"date\"\n</code></pre>"},{"location":"api/#rustfava.core.query.PositionColumn","title":"<code>PositionColumn</code>  <code>dataclass</code>","text":"<p>               Bases: <code>BaseColumn</code></p> <p>A Position query column.</p> Source code in <code>src/rustfava/core/query.py</code> <pre><code>@dataclass(frozen=True)\nclass PositionColumn(BaseColumn):\n    \"\"\"A Position query column.\"\"\"\n\n    dtype: str = \"Position\"\n</code></pre>"},{"location":"api/#rustfava.core.query.SetColumn","title":"<code>SetColumn</code>  <code>dataclass</code>","text":"<p>               Bases: <code>BaseColumn</code></p> <p>A set query column.</p> Source code in <code>src/rustfava/core/query.py</code> <pre><code>@dataclass(frozen=True)\nclass SetColumn(BaseColumn):\n    \"\"\"A set query column.\"\"\"\n\n    dtype: str = \"set\"\n</code></pre>"},{"location":"api/#rustfava.core.query.AmountColumn","title":"<code>AmountColumn</code>  <code>dataclass</code>","text":"<p>               Bases: <code>BaseColumn</code></p> <p>An amount query column.</p> Source code in <code>src/rustfava/core/query.py</code> <pre><code>@dataclass(frozen=True)\nclass AmountColumn(BaseColumn):\n    \"\"\"An amount query column.\"\"\"\n\n    dtype: str = \"Amount\"\n</code></pre>"},{"location":"api/#rustfava.core.query.ObjectColumn","title":"<code>ObjectColumn</code>  <code>dataclass</code>","text":"<p>               Bases: <code>BaseColumn</code></p> <p>An object query column.</p> Source code in <code>src/rustfava/core/query.py</code> <pre><code>@dataclass(frozen=True)\nclass ObjectColumn(BaseColumn):\n    \"\"\"An object query column.\"\"\"\n\n    dtype: str = \"object\"\n\n    @staticmethod\n    def serialise(val: object) -&gt; str:\n        \"\"\"Serialise an object of unknown type to a string.\"\"\"\n        return str(val)\n</code></pre>"},{"location":"api/#rustfava.core.query.ObjectColumn.serialise","title":"<code>serialise(val)</code>  <code>staticmethod</code>","text":"<p>Serialise an object of unknown type to a string.</p> Source code in <code>src/rustfava/core/query.py</code> <pre><code>@staticmethod\ndef serialise(val: object) -&gt; str:\n    \"\"\"Serialise an object of unknown type to a string.\"\"\"\n    return str(val)\n</code></pre>"},{"location":"api/#rustfava.core.query.InventoryColumn","title":"<code>InventoryColumn</code>  <code>dataclass</code>","text":"<p>               Bases: <code>BaseColumn</code></p> <p>An inventory query column.</p> Source code in <code>src/rustfava/core/query.py</code> <pre><code>@dataclass(frozen=True)\nclass InventoryColumn(BaseColumn):\n    \"\"\"An inventory query column.\"\"\"\n\n    dtype: str = \"Inventory\"\n\n    @staticmethod\n    def serialise(\n        val: dict[str, Decimal] | None,\n    ) -&gt; SimpleCounterInventory | None:\n        \"\"\"Serialise an inventory.\n\n        Rustledger returns inventory as a dict of currency -&gt; Decimal.\n        \"\"\"\n        if val is None:\n            return None\n        # Rustledger already converts to {currency: Decimal} format\n        if isinstance(val, dict):\n            from rustfava.core.inventory import SimpleCounterInventory\n            return SimpleCounterInventory(val)\n        # Fallback for beancount Inventory type (for backwards compat)\n        return UNITS.apply_inventory(val) if val is not None else None\n</code></pre>"},{"location":"api/#rustfava.core.query.InventoryColumn.serialise","title":"<code>serialise(val)</code>  <code>staticmethod</code>","text":"<p>Serialise an inventory.</p> <p>Rustledger returns inventory as a dict of currency -&gt; Decimal.</p> Source code in <code>src/rustfava/core/query.py</code> <pre><code>@staticmethod\ndef serialise(\n    val: dict[str, Decimal] | None,\n) -&gt; SimpleCounterInventory | None:\n    \"\"\"Serialise an inventory.\n\n    Rustledger returns inventory as a dict of currency -&gt; Decimal.\n    \"\"\"\n    if val is None:\n        return None\n    # Rustledger already converts to {currency: Decimal} format\n    if isinstance(val, dict):\n        from rustfava.core.inventory import SimpleCounterInventory\n        return SimpleCounterInventory(val)\n    # Fallback for beancount Inventory type (for backwards compat)\n    return UNITS.apply_inventory(val) if val is not None else None\n</code></pre>"},{"location":"api/#rustfava.core.query_shell","title":"<code>query_shell</code>","text":"<p>For running BQL queries in Fava.</p>"},{"location":"api/#rustfava.core.query_shell.FavaShellError","title":"<code>FavaShellError</code>","text":"<p>               Bases: <code>RustfavaAPIError</code></p> <p>An error in the Fava BQL shell, will be turned into a string.</p> Source code in <code>src/rustfava/core/query_shell.py</code> <pre><code>class FavaShellError(RustfavaAPIError):\n    \"\"\"An error in the Fava BQL shell, will be turned into a string.\"\"\"\n</code></pre>"},{"location":"api/#rustfava.core.query_shell.QueryNotFoundError","title":"<code>QueryNotFoundError</code>","text":"<p>               Bases: <code>FavaShellError</code></p> <p>Query '{name}' not found.</p> Source code in <code>src/rustfava/core/query_shell.py</code> <pre><code>class QueryNotFoundError(FavaShellError):\n    \"\"\"Query '{name}' not found.\"\"\"\n\n    def __init__(self, name: str) -&gt; None:\n        super().__init__(f\"Query '{name}' not found.\")\n</code></pre>"},{"location":"api/#rustfava.core.query_shell.TooManyRunArgsError","title":"<code>TooManyRunArgsError</code>","text":"<p>               Bases: <code>FavaShellError</code></p> <p>Too many args to run: '{args}'.</p> Source code in <code>src/rustfava/core/query_shell.py</code> <pre><code>class TooManyRunArgsError(FavaShellError):\n    \"\"\"Too many args to run: '{args}'.\"\"\"\n\n    def __init__(self, args: str) -&gt; None:\n        super().__init__(f\"Too many args to run: '{args}'.\")\n</code></pre>"},{"location":"api/#rustfava.core.query_shell.QueryCompilationError","title":"<code>QueryCompilationError</code>","text":"<p>               Bases: <code>FavaShellError</code></p> <p>Query compilation error.</p> Source code in <code>src/rustfava/core/query_shell.py</code> <pre><code>class QueryCompilationError(FavaShellError):\n    \"\"\"Query compilation error.\"\"\"\n\n    def __init__(self, err: CompilationError) -&gt; None:\n        super().__init__(f\"Query compilation error: {err!s}.\")\n</code></pre>"},{"location":"api/#rustfava.core.query_shell.QueryParseError","title":"<code>QueryParseError</code>","text":"<p>               Bases: <code>FavaShellError</code></p> <p>Query parse error.</p> Source code in <code>src/rustfava/core/query_shell.py</code> <pre><code>class QueryParseError(FavaShellError):\n    \"\"\"Query parse error.\"\"\"\n\n    def __init__(self, err: ParseError) -&gt; None:\n        super().__init__(f\"Query parse error: {err!s}.\")\n</code></pre>"},{"location":"api/#rustfava.core.query_shell.NonExportableQueryError","title":"<code>NonExportableQueryError</code>","text":"<p>               Bases: <code>FavaShellError</code></p> <p>Only queries that return a table can be printed to a file.</p> Source code in <code>src/rustfava/core/query_shell.py</code> <pre><code>class NonExportableQueryError(FavaShellError):\n    \"\"\"Only queries that return a table can be printed to a file.\"\"\"\n\n    def __init__(self) -&gt; None:\n        super().__init__(\n            \"Only queries that return a table can be printed to a file.\"\n        )\n</code></pre>"},{"location":"api/#rustfava.core.query_shell.FavaQueryRunner","title":"<code>FavaQueryRunner</code>","text":"<p>Runs BQL queries using rustledger.</p> Source code in <code>src/rustfava/core/query_shell.py</code> <pre><code>class FavaQueryRunner:\n    \"\"\"Runs BQL queries using rustledger.\"\"\"\n\n    def __init__(self, ledger: RustfavaLedger) -&gt; None:\n        self.ledger = ledger\n\n    def run(\n        self, entries: Sequence[Directive], query: str\n    ) -&gt; RLCursor | str:\n        \"\"\"Run a query, returning cursor or text result.\"\"\"\n        # Get the source from the ledger for queries\n        source = getattr(self.ledger, \"_source\", None)\n\n        # Create connection\n        conn = connect(\n            \"rustledger:\",\n            entries=entries,\n            errors=self.ledger.errors,\n            options=self.ledger.options,\n        )\n\n        if source:\n            conn.set_source(source)\n\n        # Parse the query to handle special commands\n        query = query.strip()\n        query_lower = query.lower()\n\n        # Handle noop commands (return fixed text)\n        noop_doc = \"Doesn't do anything in rustfava's query shell.\"\n        if query_lower in (\".exit\", \".quit\", \"exit\", \"quit\"):\n            return noop_doc\n\n        # Handle .run or run command\n        if query_lower.startswith((\".run\", \"run\")):\n            # Check if it's just \"run\" or \".run\" (list queries) or \"run name\"\n            if query_lower in (\"run\", \".run\") or query_lower.startswith((\"run \", \".run \")):\n                return self._handle_run(query, conn)\n\n        # Handle help commands - return text\n        if query_lower.startswith((\".help\", \"help\")):\n            # \".help exit\" or \".help &lt;command&gt;\" returns noop doc\n            if \" \" in query_lower:\n                return noop_doc\n            return self._help_text()\n\n        # Handle .explain - return placeholder\n        if query_lower.startswith((\".explain\", \"explain\")):\n            return f\"EXPLAIN: {query}\"\n\n        # Handle SELECT/BALANCES/JOURNAL queries\n        try:\n            return conn.execute(query)\n        except ParseError as exc:\n            raise QueryParseError(exc) from exc\n        except CompilationError as exc:\n            raise QueryCompilationError(exc) from exc\n\n    def _handle_run(self, query: str, conn: RLConnection) -&gt; RLCursor | str:\n        \"\"\"Handle .run command to execute stored queries.\"\"\"\n        queries = self.ledger.all_entries_by_type.Query\n\n        # Parse the run command\n        parts = shlex.split(query)\n        if len(parts) == 1:\n            # Just \"run\" - list available queries\n            return \"\\n\".join(q.name for q in queries)\n\n        if len(parts) &gt; 2:\n            raise TooManyRunArgsError(query)\n\n        name = parts[1].rstrip(\";\")\n        query_obj = next((q for q in queries if q.name == name), None)\n        if query_obj is None:\n            raise QueryNotFoundError(name)\n\n        try:\n            return conn.execute(query_obj.query_string)\n        except ParseError as exc:\n            raise QueryParseError(exc) from exc\n        except CompilationError as exc:\n            raise QueryCompilationError(exc) from exc\n\n    def _help_text(self) -&gt; str:\n        \"\"\"Return help text for the query shell.\"\"\"\n        return \"\"\"Fava Query Shell\n\nCommands:\n  SELECT ...     Run a BQL SELECT query\n  run &lt;name&gt;     Run a stored query by name\n  run            List all stored queries\n  help           Show this help message\n\nExample queries:\n  SELECT account, sum(position) GROUP BY account\n  SELECT date, narration, position WHERE account ~ \"Expenses\"\n\"\"\"\n</code></pre>"},{"location":"api/#rustfava.core.query_shell.FavaQueryRunner.run","title":"<code>run(entries, query)</code>","text":"<p>Run a query, returning cursor or text result.</p> Source code in <code>src/rustfava/core/query_shell.py</code> <pre><code>def run(\n    self, entries: Sequence[Directive], query: str\n) -&gt; RLCursor | str:\n    \"\"\"Run a query, returning cursor or text result.\"\"\"\n    # Get the source from the ledger for queries\n    source = getattr(self.ledger, \"_source\", None)\n\n    # Create connection\n    conn = connect(\n        \"rustledger:\",\n        entries=entries,\n        errors=self.ledger.errors,\n        options=self.ledger.options,\n    )\n\n    if source:\n        conn.set_source(source)\n\n    # Parse the query to handle special commands\n    query = query.strip()\n    query_lower = query.lower()\n\n    # Handle noop commands (return fixed text)\n    noop_doc = \"Doesn't do anything in rustfava's query shell.\"\n    if query_lower in (\".exit\", \".quit\", \"exit\", \"quit\"):\n        return noop_doc\n\n    # Handle .run or run command\n    if query_lower.startswith((\".run\", \"run\")):\n        # Check if it's just \"run\" or \".run\" (list queries) or \"run name\"\n        if query_lower in (\"run\", \".run\") or query_lower.startswith((\"run \", \".run \")):\n            return self._handle_run(query, conn)\n\n    # Handle help commands - return text\n    if query_lower.startswith((\".help\", \"help\")):\n        # \".help exit\" or \".help &lt;command&gt;\" returns noop doc\n        if \" \" in query_lower:\n            return noop_doc\n        return self._help_text()\n\n    # Handle .explain - return placeholder\n    if query_lower.startswith((\".explain\", \"explain\")):\n        return f\"EXPLAIN: {query}\"\n\n    # Handle SELECT/BALANCES/JOURNAL queries\n    try:\n        return conn.execute(query)\n    except ParseError as exc:\n        raise QueryParseError(exc) from exc\n    except CompilationError as exc:\n        raise QueryCompilationError(exc) from exc\n</code></pre>"},{"location":"api/#rustfava.core.query_shell.QueryShell","title":"<code>QueryShell</code>","text":"<p>               Bases: <code>FavaModule</code></p> <p>A Fava module to run BQL queries.</p> Source code in <code>src/rustfava/core/query_shell.py</code> <pre><code>class QueryShell(FavaModule):\n    \"\"\"A Fava module to run BQL queries.\"\"\"\n\n    def __init__(self, ledger: RustfavaLedger) -&gt; None:\n        super().__init__(ledger)\n        self.runner = FavaQueryRunner(ledger)\n\n    def execute_query_serialised(\n        self, entries: Sequence[Directive], query: str\n    ) -&gt; QueryResultTable | QueryResultText:\n        \"\"\"Run a query and returns its serialised result.\n\n        Arguments:\n            entries: The entries to run the query on.\n            query: A query string.\n\n        Returns:\n            Either a table or a text result (depending on the query).\n\n        Raises:\n            RustfavaAPIError: If the query response is an error.\n        \"\"\"\n        res = self.runner.run(entries, query)\n        return (\n            QueryResultText(res) if isinstance(res, str) else _serialise(res)\n        )\n\n    def query_to_file(\n        self,\n        entries: Sequence[Directive],\n        query_string: str,\n        result_format: str,\n    ) -&gt; tuple[str, io.BytesIO]:\n        \"\"\"Get query result as file.\n\n        Arguments:\n            entries: The entries to run the query on.\n            query_string: A string, the query to run.\n            result_format: The file format to save to.\n\n        Returns:\n            A tuple (name, data), where name is either 'query_result' or the\n            name of a custom query if the query string is 'run name_of_query'.\n            ``data`` contains the file contents.\n\n        Raises:\n            RustfavaAPIError: If the result format is not supported or the\n            query failed.\n        \"\"\"\n        name = \"query_result\"\n\n        if query_string.lower().startswith((\".run\", \"run \")):\n            parts = shlex.split(query_string)\n            if len(parts) &gt; 2:\n                raise TooManyRunArgsError(query_string)\n            if len(parts) == 2:\n                name = parts[1].rstrip(\";\")\n                queries = self.ledger.all_entries_by_type.Query\n                query_obj = next((q for q in queries if q.name == name), None)\n                if query_obj is None:\n                    raise QueryNotFoundError(name)\n                query_string = query_obj.query_string\n\n        res = self.runner.run(entries, query_string)\n        if isinstance(res, str):\n            raise NonExportableQueryError\n\n        rrows = res.fetchall()\n        rtypes = res.description\n\n        # Convert rows to exportable format\n        rows = _numberify_rows(rrows, rtypes)\n\n        if result_format == \"csv\":\n            data = to_csv(list(rtypes), rows)\n        else:\n            if not HAVE_EXCEL:  # pragma: no cover\n                msg = \"Result format not supported.\"\n                raise RustfavaAPIError(msg)\n            data = to_excel(list(rtypes), rows, result_format, query_string)\n        return name, data\n</code></pre>"},{"location":"api/#rustfava.core.query_shell.QueryShell.execute_query_serialised","title":"<code>execute_query_serialised(entries, query)</code>","text":"<p>Run a query and returns its serialised result.</p> <p>Parameters:</p> Name Type Description Default <code>entries</code> <code>Sequence[Directive]</code> <p>The entries to run the query on.</p> required <code>query</code> <code>str</code> <p>A query string.</p> required <p>Returns:</p> Type Description <code>QueryResultTable | QueryResultText</code> <p>Either a table or a text result (depending on the query).</p> <p>Raises:</p> Type Description <code>RustfavaAPIError</code> <p>If the query response is an error.</p> Source code in <code>src/rustfava/core/query_shell.py</code> <pre><code>def execute_query_serialised(\n    self, entries: Sequence[Directive], query: str\n) -&gt; QueryResultTable | QueryResultText:\n    \"\"\"Run a query and returns its serialised result.\n\n    Arguments:\n        entries: The entries to run the query on.\n        query: A query string.\n\n    Returns:\n        Either a table or a text result (depending on the query).\n\n    Raises:\n        RustfavaAPIError: If the query response is an error.\n    \"\"\"\n    res = self.runner.run(entries, query)\n    return (\n        QueryResultText(res) if isinstance(res, str) else _serialise(res)\n    )\n</code></pre>"},{"location":"api/#rustfava.core.query_shell.QueryShell.query_to_file","title":"<code>query_to_file(entries, query_string, result_format)</code>","text":"<p>Get query result as file.</p> <p>Parameters:</p> Name Type Description Default <code>entries</code> <code>Sequence[Directive]</code> <p>The entries to run the query on.</p> required <code>query_string</code> <code>str</code> <p>A string, the query to run.</p> required <code>result_format</code> <code>str</code> <p>The file format to save to.</p> required <p>Returns:</p> Type Description <code>str</code> <p>A tuple (name, data), where name is either 'query_result' or the</p> <code>BytesIO</code> <p>name of a custom query if the query string is 'run name_of_query'.</p> <code>tuple[str, BytesIO]</code> <p><code>data</code> contains the file contents.</p> <p>Raises:</p> Type Description <code>RustfavaAPIError</code> <p>If the result format is not supported or the</p> Source code in <code>src/rustfava/core/query_shell.py</code> <pre><code>def query_to_file(\n    self,\n    entries: Sequence[Directive],\n    query_string: str,\n    result_format: str,\n) -&gt; tuple[str, io.BytesIO]:\n    \"\"\"Get query result as file.\n\n    Arguments:\n        entries: The entries to run the query on.\n        query_string: A string, the query to run.\n        result_format: The file format to save to.\n\n    Returns:\n        A tuple (name, data), where name is either 'query_result' or the\n        name of a custom query if the query string is 'run name_of_query'.\n        ``data`` contains the file contents.\n\n    Raises:\n        RustfavaAPIError: If the result format is not supported or the\n        query failed.\n    \"\"\"\n    name = \"query_result\"\n\n    if query_string.lower().startswith((\".run\", \"run \")):\n        parts = shlex.split(query_string)\n        if len(parts) &gt; 2:\n            raise TooManyRunArgsError(query_string)\n        if len(parts) == 2:\n            name = parts[1].rstrip(\";\")\n            queries = self.ledger.all_entries_by_type.Query\n            query_obj = next((q for q in queries if q.name == name), None)\n            if query_obj is None:\n                raise QueryNotFoundError(name)\n            query_string = query_obj.query_string\n\n    res = self.runner.run(entries, query_string)\n    if isinstance(res, str):\n        raise NonExportableQueryError\n\n    rrows = res.fetchall()\n    rtypes = res.description\n\n    # Convert rows to exportable format\n    rows = _numberify_rows(rrows, rtypes)\n\n    if result_format == \"csv\":\n        data = to_csv(list(rtypes), rows)\n    else:\n        if not HAVE_EXCEL:  # pragma: no cover\n            msg = \"Result format not supported.\"\n            raise RustfavaAPIError(msg)\n        data = to_excel(list(rtypes), rows, result_format, query_string)\n    return name, data\n</code></pre>"},{"location":"api/#rustfava.core.tree","title":"<code>tree</code>","text":"<p>Account balance trees.</p>"},{"location":"api/#rustfava.core.tree.SerialisedTreeNode","title":"<code>SerialisedTreeNode</code>  <code>dataclass</code>","text":"<p>A serialised TreeNode.</p> Source code in <code>src/rustfava/core/tree.py</code> <pre><code>@dataclass(frozen=True)\nclass SerialisedTreeNode:\n    \"\"\"A serialised TreeNode.\"\"\"\n\n    account: str\n    balance: SimpleCounterInventory\n    balance_children: SimpleCounterInventory\n    children: Sequence[SerialisedTreeNode]\n    has_txns: bool\n    cost: SimpleCounterInventory | None = None\n    cost_children: SimpleCounterInventory | None = None\n</code></pre>"},{"location":"api/#rustfava.core.tree.TreeNode","title":"<code>TreeNode</code>","text":"<p>A node in the account tree.</p> Source code in <code>src/rustfava/core/tree.py</code> <pre><code>class TreeNode:\n    \"\"\"A node in the account tree.\"\"\"\n\n    __slots__ = (\"balance\", \"balance_children\", \"children\", \"has_txns\", \"name\")\n\n    def __init__(self, name: str) -&gt; None:\n        #: Account name.\n        self.name: str = name\n        #: A list of :class:`.TreeNode`, its children.\n        self.children: list[TreeNode] = []\n        #: The cumulative account balance.\n        self.balance_children = CounterInventory()\n        #: The account balance.\n        self.balance = CounterInventory()\n        #: Whether the account has any transactions.\n        self.has_txns = False\n\n    def serialise(\n        self,\n        conversion: Conversion,\n        prices: RustfavaPriceMap,\n        end: datetime.date | None,\n        *,\n        with_cost: bool = False,\n    ) -&gt; SerialisedTreeNode:\n        \"\"\"Serialise the account.\n\n        Args:\n            conversion: The conversion to use.\n            prices: The price map to use.\n            end: A date to use for cost conversions.\n            with_cost: Additionally convert to cost.\n        \"\"\"\n        children = [\n            child.serialise(conversion, prices, end, with_cost=with_cost)\n            for child in sorted(self.children, key=attrgetter(\"name\"))\n        ]\n        return (\n            SerialisedTreeNode(\n                self.name,\n                conversion.apply(self.balance, prices, end),\n                conversion.apply(self.balance_children, prices, end),\n                children,\n                self.has_txns,\n                AT_COST.apply(self.balance),\n                AT_COST.apply(self.balance_children),\n            )\n            if with_cost\n            else SerialisedTreeNode(\n                self.name,\n                conversion.apply(self.balance, prices, end),\n                conversion.apply(self.balance_children, prices, end),\n                children,\n                self.has_txns,\n            )\n        )\n\n    def serialise_with_context(self) -&gt; SerialisedTreeNode:\n        \"\"\"Serialise, getting all parameters from Flask context.\"\"\"\n        return self.serialise(\n            g.conv,\n            g.ledger.prices,\n            g.filtered.end_date,\n            with_cost=g.conv == AT_VALUE,\n        )\n</code></pre>"},{"location":"api/#rustfava.core.tree.TreeNode.serialise","title":"<code>serialise(conversion, prices, end, *, with_cost=False)</code>","text":"<p>Serialise the account.</p> <p>Parameters:</p> Name Type Description Default <code>conversion</code> <code>Conversion</code> <p>The conversion to use.</p> required <code>prices</code> <code>RustfavaPriceMap</code> <p>The price map to use.</p> required <code>end</code> <code>date | None</code> <p>A date to use for cost conversions.</p> required <code>with_cost</code> <code>bool</code> <p>Additionally convert to cost.</p> <code>False</code> Source code in <code>src/rustfava/core/tree.py</code> <pre><code>def serialise(\n    self,\n    conversion: Conversion,\n    prices: RustfavaPriceMap,\n    end: datetime.date | None,\n    *,\n    with_cost: bool = False,\n) -&gt; SerialisedTreeNode:\n    \"\"\"Serialise the account.\n\n    Args:\n        conversion: The conversion to use.\n        prices: The price map to use.\n        end: A date to use for cost conversions.\n        with_cost: Additionally convert to cost.\n    \"\"\"\n    children = [\n        child.serialise(conversion, prices, end, with_cost=with_cost)\n        for child in sorted(self.children, key=attrgetter(\"name\"))\n    ]\n    return (\n        SerialisedTreeNode(\n            self.name,\n            conversion.apply(self.balance, prices, end),\n            conversion.apply(self.balance_children, prices, end),\n            children,\n            self.has_txns,\n            AT_COST.apply(self.balance),\n            AT_COST.apply(self.balance_children),\n        )\n        if with_cost\n        else SerialisedTreeNode(\n            self.name,\n            conversion.apply(self.balance, prices, end),\n            conversion.apply(self.balance_children, prices, end),\n            children,\n            self.has_txns,\n        )\n    )\n</code></pre>"},{"location":"api/#rustfava.core.tree.TreeNode.serialise_with_context","title":"<code>serialise_with_context()</code>","text":"<p>Serialise, getting all parameters from Flask context.</p> Source code in <code>src/rustfava/core/tree.py</code> <pre><code>def serialise_with_context(self) -&gt; SerialisedTreeNode:\n    \"\"\"Serialise, getting all parameters from Flask context.\"\"\"\n    return self.serialise(\n        g.conv,\n        g.ledger.prices,\n        g.filtered.end_date,\n        with_cost=g.conv == AT_VALUE,\n    )\n</code></pre>"},{"location":"api/#rustfava.core.tree.Tree","title":"<code>Tree</code>","text":"<p>               Bases: <code>dict[str, TreeNode]</code></p> <p>Account tree.</p> <p>Parameters:</p> Name Type Description Default <code>entries</code> <code>Iterable[Directive | Directive] | None</code> <p>A list of entries to compute balances from.</p> <code>None</code> <code>create_accounts</code> <code>list[str] | None</code> <p>A list of accounts that the tree should contain.</p> <code>None</code> Source code in <code>src/rustfava/core/tree.py</code> <pre><code>class Tree(dict[str, TreeNode]):\n    \"\"\"Account tree.\n\n    Args:\n        entries: A list of entries to compute balances from.\n        create_accounts: A list of accounts that the tree should contain.\n    \"\"\"\n\n    def __init__(\n        self,\n        entries: Iterable[Directive | data.Directive] | None = None,\n        create_accounts: list[str] | None = None,\n    ) -&gt; None:\n        super().__init__(self)\n        self.get(\"\", insert=True)\n        if create_accounts:\n            for account in create_accounts:\n                self.get(account, insert=True)\n        if entries:\n            account_balances: dict[str, CounterInventory]\n            account_balances = defaultdict(CounterInventory)\n            for entry in entries:\n                if isinstance(entry, Open):\n                    self.get(entry.account, insert=True)\n                for posting in getattr(entry, \"postings\", []):\n                    account_balances[posting.account].add_position(posting)\n\n            for name, balance in sorted(account_balances.items()):\n                self.insert(name, balance)\n\n    @property\n    def accounts(self) -&gt; list[str]:\n        \"\"\"The accounts in this tree.\"\"\"\n        return sorted(self.keys())\n\n    def ancestors(self, name: str) -&gt; Iterable[TreeNode]:\n        \"\"\"Ancestors of an account.\n\n        Args:\n            name: An account name.\n\n        Yields:\n            The ancestors of the given account from the bottom up.\n        \"\"\"\n        while name:\n            name = account_parent(name) or \"\"\n            yield self.get(name)\n\n    def insert(self, name: str, balance: CounterInventory) -&gt; None:\n        \"\"\"Insert account with a balance.\n\n        Insert account and update its balance and the balances of its\n        ancestors.\n\n        Args:\n            name: An account name.\n            balance: The balance of the account.\n        \"\"\"\n        node = self.get(name, insert=True)\n        node.balance.add_inventory(balance)\n        node.balance_children.add_inventory(balance)\n        node.has_txns = True\n        for parent_node in self.ancestors(name):\n            parent_node.balance_children.add_inventory(balance)\n\n    def get(  # type: ignore[override]\n        self,\n        name: str,\n        *,\n        insert: bool = False,\n    ) -&gt; TreeNode:\n        \"\"\"Get an account.\n\n        Args:\n            name: An account name.\n            insert: If True, insert the name into the tree if it does not\n                exist.\n\n        Returns:\n            TreeNode: The account of that name or an empty account if the\n            account is not in the tree.\n        \"\"\"\n        try:\n            return self[name]\n        except KeyError:\n            node = TreeNode(name)\n            if insert:\n                if name:\n                    parent = self.get(account_parent(name) or \"\", insert=True)\n                    parent.children.append(node)\n                self[name] = node\n            return node\n\n    def net_profit(\n        self,\n        options: BeancountOptions,\n        account_name: str,\n    ) -&gt; TreeNode:\n        \"\"\"Calculate the net profit.\n\n        Args:\n            options: The Beancount options.\n            account_name: The name to use for the account containing the net\n                profit.\n        \"\"\"\n        income = self.get(options[\"name_income\"])\n        expenses = self.get(options[\"name_expenses\"])\n\n        net_profit = Tree()\n        net_profit.insert(\n            account_name,\n            income.balance_children + expenses.balance_children,\n        )\n\n        return net_profit.get(account_name)\n\n    def cap(self, options: BeancountOptions, unrealized_account: str) -&gt; None:\n        \"\"\"Transfer Income and Expenses, add conversions and unrealized gains.\n\n        Args:\n            options: The Beancount options.\n            unrealized_account: The name of the account to post unrealized\n                gains to (as a subaccount of Equity).\n        \"\"\"\n        equity = options[\"name_equity\"]\n        conversions = CounterInventory(\n            {\n                (currency, None): -number\n                for currency, number in AT_COST.apply(\n                    self.get(\"\").balance_children\n                ).items()\n            },\n        )\n\n        # Add conversions\n        self.insert(\n            equity + \":\" + options[\"account_current_conversions\"],\n            conversions,\n        )\n\n        # Insert unrealized gains.\n        self.insert(\n            equity + \":\" + unrealized_account,\n            -self.get(\"\").balance_children,\n        )\n\n        # Transfer Income and Expenses\n        self.insert(\n            equity + \":\" + options[\"account_current_earnings\"],\n            self.get(options[\"name_income\"]).balance_children,\n        )\n        self.insert(\n            equity + \":\" + options[\"account_current_earnings\"],\n            self.get(options[\"name_expenses\"]).balance_children,\n        )\n</code></pre>"},{"location":"api/#rustfava.core.tree.Tree.accounts","title":"<code>accounts</code>  <code>property</code>","text":"<p>The accounts in this tree.</p>"},{"location":"api/#rustfava.core.tree.Tree.ancestors","title":"<code>ancestors(name)</code>","text":"<p>Ancestors of an account.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>An account name.</p> required <p>Yields:</p> Type Description <code>Iterable[TreeNode]</code> <p>The ancestors of the given account from the bottom up.</p> Source code in <code>src/rustfava/core/tree.py</code> <pre><code>def ancestors(self, name: str) -&gt; Iterable[TreeNode]:\n    \"\"\"Ancestors of an account.\n\n    Args:\n        name: An account name.\n\n    Yields:\n        The ancestors of the given account from the bottom up.\n    \"\"\"\n    while name:\n        name = account_parent(name) or \"\"\n        yield self.get(name)\n</code></pre>"},{"location":"api/#rustfava.core.tree.Tree.insert","title":"<code>insert(name, balance)</code>","text":"<p>Insert account with a balance.</p> <p>Insert account and update its balance and the balances of its ancestors.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>An account name.</p> required <code>balance</code> <code>CounterInventory</code> <p>The balance of the account.</p> required Source code in <code>src/rustfava/core/tree.py</code> <pre><code>def insert(self, name: str, balance: CounterInventory) -&gt; None:\n    \"\"\"Insert account with a balance.\n\n    Insert account and update its balance and the balances of its\n    ancestors.\n\n    Args:\n        name: An account name.\n        balance: The balance of the account.\n    \"\"\"\n    node = self.get(name, insert=True)\n    node.balance.add_inventory(balance)\n    node.balance_children.add_inventory(balance)\n    node.has_txns = True\n    for parent_node in self.ancestors(name):\n        parent_node.balance_children.add_inventory(balance)\n</code></pre>"},{"location":"api/#rustfava.core.tree.Tree.get","title":"<code>get(name, *, insert=False)</code>","text":"<p>Get an account.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>An account name.</p> required <code>insert</code> <code>bool</code> <p>If True, insert the name into the tree if it does not exist.</p> <code>False</code> <p>Returns:</p> Name Type Description <code>TreeNode</code> <code>TreeNode</code> <p>The account of that name or an empty account if the</p> <code>TreeNode</code> <p>account is not in the tree.</p> Source code in <code>src/rustfava/core/tree.py</code> <pre><code>def get(  # type: ignore[override]\n    self,\n    name: str,\n    *,\n    insert: bool = False,\n) -&gt; TreeNode:\n    \"\"\"Get an account.\n\n    Args:\n        name: An account name.\n        insert: If True, insert the name into the tree if it does not\n            exist.\n\n    Returns:\n        TreeNode: The account of that name or an empty account if the\n        account is not in the tree.\n    \"\"\"\n    try:\n        return self[name]\n    except KeyError:\n        node = TreeNode(name)\n        if insert:\n            if name:\n                parent = self.get(account_parent(name) or \"\", insert=True)\n                parent.children.append(node)\n            self[name] = node\n        return node\n</code></pre>"},{"location":"api/#rustfava.core.tree.Tree.net_profit","title":"<code>net_profit(options, account_name)</code>","text":"<p>Calculate the net profit.</p> <p>Parameters:</p> Name Type Description Default <code>options</code> <code>BeancountOptions</code> <p>The Beancount options.</p> required <code>account_name</code> <code>str</code> <p>The name to use for the account containing the net profit.</p> required Source code in <code>src/rustfava/core/tree.py</code> <pre><code>def net_profit(\n    self,\n    options: BeancountOptions,\n    account_name: str,\n) -&gt; TreeNode:\n    \"\"\"Calculate the net profit.\n\n    Args:\n        options: The Beancount options.\n        account_name: The name to use for the account containing the net\n            profit.\n    \"\"\"\n    income = self.get(options[\"name_income\"])\n    expenses = self.get(options[\"name_expenses\"])\n\n    net_profit = Tree()\n    net_profit.insert(\n        account_name,\n        income.balance_children + expenses.balance_children,\n    )\n\n    return net_profit.get(account_name)\n</code></pre>"},{"location":"api/#rustfava.core.tree.Tree.cap","title":"<code>cap(options, unrealized_account)</code>","text":"<p>Transfer Income and Expenses, add conversions and unrealized gains.</p> <p>Parameters:</p> Name Type Description Default <code>options</code> <code>BeancountOptions</code> <p>The Beancount options.</p> required <code>unrealized_account</code> <code>str</code> <p>The name of the account to post unrealized gains to (as a subaccount of Equity).</p> required Source code in <code>src/rustfava/core/tree.py</code> <pre><code>def cap(self, options: BeancountOptions, unrealized_account: str) -&gt; None:\n    \"\"\"Transfer Income and Expenses, add conversions and unrealized gains.\n\n    Args:\n        options: The Beancount options.\n        unrealized_account: The name of the account to post unrealized\n            gains to (as a subaccount of Equity).\n    \"\"\"\n    equity = options[\"name_equity\"]\n    conversions = CounterInventory(\n        {\n            (currency, None): -number\n            for currency, number in AT_COST.apply(\n                self.get(\"\").balance_children\n            ).items()\n        },\n    )\n\n    # Add conversions\n    self.insert(\n        equity + \":\" + options[\"account_current_conversions\"],\n        conversions,\n    )\n\n    # Insert unrealized gains.\n    self.insert(\n        equity + \":\" + unrealized_account,\n        -self.get(\"\").balance_children,\n    )\n\n    # Transfer Income and Expenses\n    self.insert(\n        equity + \":\" + options[\"account_current_earnings\"],\n        self.get(options[\"name_income\"]).balance_children,\n    )\n    self.insert(\n        equity + \":\" + options[\"account_current_earnings\"],\n        self.get(options[\"name_expenses\"]).balance_children,\n    )\n</code></pre>"},{"location":"api/#rustfava.core.watcher","title":"<code>watcher</code>","text":"<p>A simple file and folder watcher.</p>"},{"location":"api/#rustfava.core.watcher.WatcherBase","title":"<code>WatcherBase</code>","text":"<p>               Bases: <code>ABC</code></p> <p>ABC for rustfava ledger file watchers.</p> Source code in <code>src/rustfava/core/watcher.py</code> <pre><code>class WatcherBase(abc.ABC):\n    \"\"\"ABC for rustfava ledger file watchers.\"\"\"\n\n    last_checked: int\n    \"\"\"Timestamp of the latest change noticed by the file watcher.\"\"\"\n\n    last_notified: int\n    \"\"\"Timestamp of the latest change that the watcher was notified of.\"\"\"\n\n    @abc.abstractmethod\n    def update(self, files: Iterable[Path], folders: Iterable[Path]) -&gt; None:\n        \"\"\"Update the folders/files to watch.\n\n        Args:\n            files: A list of file paths.\n            folders: A list of paths to folders.\n        \"\"\"\n\n    def check(self) -&gt; bool:\n        \"\"\"Check for changes.\n\n        Returns:\n            `True` if there was a file change in one of the files or folders,\n            `False` otherwise.\n        \"\"\"\n        latest_mtime = max(self._get_latest_mtime(), self.last_notified)\n        has_higher_mtime = latest_mtime &gt; self.last_checked\n        if has_higher_mtime:\n            self.last_checked = latest_mtime\n        return has_higher_mtime\n\n    def notify(self, path: Path) -&gt; None:\n        \"\"\"Notify the watcher of a change to a path.\"\"\"\n        try:\n            change_mtime = Path(path).stat().st_mtime_ns\n        except FileNotFoundError:\n            change_mtime = max(self.last_notified, self.last_checked) + 1\n        self.last_notified = max(self.last_notified, change_mtime)\n\n    @abc.abstractmethod\n    def _get_latest_mtime(self) -&gt; int:\n        \"\"\"Get the latest change mtime.\"\"\"\n</code></pre>"},{"location":"api/#rustfava.core.watcher.WatcherBase.last_checked","title":"<code>last_checked</code>  <code>instance-attribute</code>","text":"<p>Timestamp of the latest change noticed by the file watcher.</p>"},{"location":"api/#rustfava.core.watcher.WatcherBase.last_notified","title":"<code>last_notified</code>  <code>instance-attribute</code>","text":"<p>Timestamp of the latest change that the watcher was notified of.</p>"},{"location":"api/#rustfava.core.watcher.WatcherBase.update","title":"<code>update(files, folders)</code>  <code>abstractmethod</code>","text":"<p>Update the folders/files to watch.</p> <p>Parameters:</p> Name Type Description Default <code>files</code> <code>Iterable[Path]</code> <p>A list of file paths.</p> required <code>folders</code> <code>Iterable[Path]</code> <p>A list of paths to folders.</p> required Source code in <code>src/rustfava/core/watcher.py</code> <pre><code>@abc.abstractmethod\ndef update(self, files: Iterable[Path], folders: Iterable[Path]) -&gt; None:\n    \"\"\"Update the folders/files to watch.\n\n    Args:\n        files: A list of file paths.\n        folders: A list of paths to folders.\n    \"\"\"\n</code></pre>"},{"location":"api/#rustfava.core.watcher.WatcherBase.check","title":"<code>check()</code>","text":"<p>Check for changes.</p> <p>Returns:</p> Type Description <code>bool</code> <p><code>True</code> if there was a file change in one of the files or folders,</p> <code>bool</code> <p><code>False</code> otherwise.</p> Source code in <code>src/rustfava/core/watcher.py</code> <pre><code>def check(self) -&gt; bool:\n    \"\"\"Check for changes.\n\n    Returns:\n        `True` if there was a file change in one of the files or folders,\n        `False` otherwise.\n    \"\"\"\n    latest_mtime = max(self._get_latest_mtime(), self.last_notified)\n    has_higher_mtime = latest_mtime &gt; self.last_checked\n    if has_higher_mtime:\n        self.last_checked = latest_mtime\n    return has_higher_mtime\n</code></pre>"},{"location":"api/#rustfava.core.watcher.WatcherBase.notify","title":"<code>notify(path)</code>","text":"<p>Notify the watcher of a change to a path.</p> Source code in <code>src/rustfava/core/watcher.py</code> <pre><code>def notify(self, path: Path) -&gt; None:\n    \"\"\"Notify the watcher of a change to a path.\"\"\"\n    try:\n        change_mtime = Path(path).stat().st_mtime_ns\n    except FileNotFoundError:\n        change_mtime = max(self.last_notified, self.last_checked) + 1\n    self.last_notified = max(self.last_notified, change_mtime)\n</code></pre>"},{"location":"api/#rustfava.core.watcher.WatchfilesWatcher","title":"<code>WatchfilesWatcher</code>","text":"<p>               Bases: <code>WatcherBase</code></p> <p>A file and folder watcher using the watchfiles library.</p> Source code in <code>src/rustfava/core/watcher.py</code> <pre><code>class WatchfilesWatcher(WatcherBase):\n    \"\"\"A file and folder watcher using the watchfiles library.\"\"\"\n\n    def __init__(self) -&gt; None:\n        self.last_checked = 0\n        self.last_notified = 0\n        self._paths: tuple[set[Path], set[Path]] | None = None\n        self._watchers: tuple[_WatchfilesThread, _WatchfilesThread] | None = (\n            None\n        )\n\n    def update(self, files: Iterable[Path], folders: Iterable[Path]) -&gt; None:\n        \"\"\"Update the folders/files to watch.\"\"\"\n        files_set = {p.absolute() for p in files if p.exists()}\n        folders_set = {p.absolute() for p in folders if p.is_dir()}\n        new_paths = (files_set, folders_set)\n        if self._watchers and new_paths == self._paths:\n            self.check()\n            return\n        self._paths = new_paths\n        if self._watchers:\n            self._watchers[0].stop()\n            self._watchers[1].stop()\n        self._watchers = (\n            _FilesWatchfilesThread(files_set, self.last_checked),\n            _WatchfilesThread(folders_set, self.last_checked, recursive=True),\n        )\n        self._watchers[0].start()\n        self._watchers[1].start()\n        self.check()\n\n    def __enter__(self) -&gt; None:\n        pass\n\n    def __exit__(\n        self,\n        exc_type: type[BaseException] | None,\n        exc_value: BaseException | None,\n        traceback: types.TracebackType | None,\n    ) -&gt; None:\n        if self._watchers:\n            self._watchers[0].stop()\n            self._watchers[1].stop()\n\n    def _get_latest_mtime(self) -&gt; int:\n        return (\n            max(self._watchers[0].mtime, self._watchers[1].mtime)\n            if self._watchers\n            else 0\n        )\n</code></pre>"},{"location":"api/#rustfava.core.watcher.WatchfilesWatcher.update","title":"<code>update(files, folders)</code>","text":"<p>Update the folders/files to watch.</p> Source code in <code>src/rustfava/core/watcher.py</code> <pre><code>def update(self, files: Iterable[Path], folders: Iterable[Path]) -&gt; None:\n    \"\"\"Update the folders/files to watch.\"\"\"\n    files_set = {p.absolute() for p in files if p.exists()}\n    folders_set = {p.absolute() for p in folders if p.is_dir()}\n    new_paths = (files_set, folders_set)\n    if self._watchers and new_paths == self._paths:\n        self.check()\n        return\n    self._paths = new_paths\n    if self._watchers:\n        self._watchers[0].stop()\n        self._watchers[1].stop()\n    self._watchers = (\n        _FilesWatchfilesThread(files_set, self.last_checked),\n        _WatchfilesThread(folders_set, self.last_checked, recursive=True),\n    )\n    self._watchers[0].start()\n    self._watchers[1].start()\n    self.check()\n</code></pre>"},{"location":"api/#rustfava.core.watcher.Watcher","title":"<code>Watcher</code>","text":"<p>               Bases: <code>WatcherBase</code></p> <p>A simple file and folder watcher.</p> <p>For folders, only checks mtime of the folder and all subdirectories. So a file change won't be noticed, but only new/deleted files.</p> Source code in <code>src/rustfava/core/watcher.py</code> <pre><code>class Watcher(WatcherBase):\n    \"\"\"A simple file and folder watcher.\n\n    For folders, only checks mtime of the folder and all subdirectories.\n    So a file change won't be noticed, but only new/deleted files.\n    \"\"\"\n\n    def __init__(self) -&gt; None:\n        self.last_checked = 0\n        self.last_notified = 0\n        self._files: Sequence[Path] = []\n        self._folders: Sequence[Path] = []\n\n    def update(self, files: Iterable[Path], folders: Iterable[Path]) -&gt; None:\n        \"\"\"Update the folders/files to watch.\"\"\"\n        self._files = list(files)\n        self._folders = list(folders)\n        self.check()\n\n    def _mtimes(self) -&gt; Iterable[int]:\n        for path in self._files:\n            try:\n                yield path.stat().st_mtime_ns\n            except FileNotFoundError:\n                yield max(self.last_notified, self.last_checked) + 1\n        for path in self._folders:\n            for dirpath, _, _ in walk(path):\n                yield Path(dirpath).stat().st_mtime_ns\n\n    def _get_latest_mtime(self) -&gt; int:\n        return max(self._mtimes())\n</code></pre>"},{"location":"api/#rustfava.core.watcher.Watcher.update","title":"<code>update(files, folders)</code>","text":"<p>Update the folders/files to watch.</p> Source code in <code>src/rustfava/core/watcher.py</code> <pre><code>def update(self, files: Iterable[Path], folders: Iterable[Path]) -&gt; None:\n    \"\"\"Update the folders/files to watch.\"\"\"\n    self._files = list(files)\n    self._folders = list(folders)\n    self.check()\n</code></pre>"},{"location":"api/#application","title":"Application","text":""},{"location":"api/#rustfava.application","title":"<code>rustfava.application</code>","text":"<p>rustfava's main WSGI application.</p> <p>you can use <code>create_app</code> to create a rustfava WSGI app for a given list of files. To start a simple server::</p> <pre><code>from rustfava.application import create_app\n\napp = create_app(['/path/to/file.beancount'])\napp.run('localhost', 5000)\n</code></pre>"},{"location":"api/#rustfava.application.static_url","title":"<code>static_url(filename)</code>","text":"<p>Return a static url with an mtime query string for cache busting.</p> Source code in <code>src/rustfava/application.py</code> <pre><code>def static_url(filename: str) -&gt; str:\n    \"\"\"Return a static url with an mtime query string for cache busting.\"\"\"\n    file_path = Path(__file__).parent / \"static\" / filename\n    try:\n        mtime = str(int(file_path.stat().st_mtime))\n    except FileNotFoundError:\n        mtime = \"0\"\n    return url_for(\"static\", filename=filename, mtime=mtime)\n</code></pre>"},{"location":"api/#rustfava.application.url_for","title":"<code>url_for(endpoint, **values)</code>","text":"<p>Wrap flask.url_for using a cache.</p> Source code in <code>src/rustfava/application.py</code> <pre><code>def url_for(endpoint: str, **values: str) -&gt; str:\n    \"\"\"Wrap flask.url_for using a cache.\"\"\"\n    _inject_filters(endpoint, values)\n    return _cached_url_for(endpoint, **values)\n</code></pre>"},{"location":"api/#rustfava.application.translations","title":"<code>translations()</code>","text":"<p>Get translations catalog.</p> Source code in <code>src/rustfava/application.py</code> <pre><code>def translations() -&gt; dict[str, str]:\n    \"\"\"Get translations catalog.\"\"\"\n    catalog = get_translations()._catalog  # noqa: SLF001\n    return {k: v for k, v in catalog.items() if isinstance(k, str) and k}\n</code></pre>"},{"location":"api/#rustfava.application.create_app","title":"<code>create_app(files, *, load=False, incognito=False, read_only=False, poll_watcher=False)</code>","text":"<p>Create a rustfava Flask application.</p> <p>Parameters:</p> Name Type Description Default <code>files</code> <code>Iterable[Path | str]</code> <p>The list of Beancount files (paths).</p> required <code>load</code> <code>bool</code> <p>Whether to load the Beancount files directly.</p> <code>False</code> <code>incognito</code> <code>bool</code> <p>Whether to run in incognito mode.</p> <code>False</code> <code>read_only</code> <code>bool</code> <p>Whether to run in read-only mode.</p> <code>False</code> <code>poll_watcher</code> <code>bool</code> <p>Whether to use old poll watcher</p> <code>False</code> Source code in <code>src/rustfava/application.py</code> <pre><code>def create_app(\n    files: Iterable[Path | str],\n    *,\n    load: bool = False,\n    incognito: bool = False,\n    read_only: bool = False,\n    poll_watcher: bool = False,\n) -&gt; Flask:\n    \"\"\"Create a rustfava Flask application.\n\n    Arguments:\n        files: The list of Beancount files (paths).\n        load: Whether to load the Beancount files directly.\n        incognito: Whether to run in incognito mode.\n        read_only: Whether to run in read-only mode.\n        poll_watcher: Whether to use old poll watcher\n    \"\"\"\n    fava_app = Flask(\"rustfava\")\n    fava_app.register_blueprint(json_api, url_prefix=\"/&lt;bfile&gt;/api\")\n    fava_app.json = RustfavaJSONProvider(fava_app)\n    fava_app.app_ctx_globals_class = Context  # type: ignore[assignment]\n    _setup_template_config(fava_app, incognito=incognito)\n    _setup_babel(fava_app)\n    _setup_filters(fava_app, read_only=read_only)\n    _setup_routes(fava_app)\n\n    fava_app.config[\"HAVE_EXCEL\"] = HAVE_EXCEL\n    fava_app.config[\"BEANCOUNT_FILES\"] = [str(f) for f in files]\n    fava_app.config[\"INCOGNITO\"] = incognito\n    fava_app.config[\"LEDGERS\"] = _LedgerSlugLoader(\n        fava_app, load=load, poll_watcher=poll_watcher\n    )\n\n    return fava_app\n</code></pre>"},{"location":"api/#cli","title":"CLI","text":""},{"location":"api/#rustfava.cli","title":"<code>rustfava.cli</code>","text":"<p>The command-line interface for rustfava.</p>"},{"location":"api/#rustfava.cli.main","title":"<code>main(*, filenames=(), port=5000, host='localhost', prefix=None, incognito=False, read_only=False, debug=False, profile=False, profile_dir=None, poll_watcher=False)</code>","text":"<p>Start Rustfava for FILENAMES on http://:. <p>If the <code>BEANCOUNT_FILE</code> environment variable is set, Rustfava will use the files (delimited by ';' on Windows and ':' on POSIX) given there in addition to FILENAMES.</p> <p>Note you can also specify command-line options via environment variables with the <code>RUSTFAVA_</code> prefix. For example, <code>--host=0.0.0.0</code> is equivalent to setting the environment variable <code>RUSTFAVA_HOST=0.0.0.0</code>.</p> Source code in <code>src/rustfava/cli.py</code> <pre><code>@click.command(context_settings={\"auto_envvar_prefix\": \"RUSTFAVA\"})\n@click.argument(\n    \"filenames\",\n    nargs=-1,\n    type=click.Path(exists=True, dir_okay=False, resolve_path=True),\n)\n@click.option(\n    \"-p\",\n    \"--port\",\n    type=int,\n    default=5000,\n    show_default=True,\n    metavar=\"&lt;port&gt;\",\n    help=\"The port to listen on.\",\n)\n@click.option(\n    \"-H\",\n    \"--host\",\n    type=str,\n    default=\"localhost\",\n    show_default=True,\n    metavar=\"&lt;host&gt;\",\n    help=\"The host to listen on.\",\n)\n@click.option(\"--prefix\", type=str, help=\"Set an URL prefix.\")\n@click.option(\n    \"--incognito\",\n    is_flag=True,\n    help=\"Run in incognito mode and obscure all numbers.\",\n)\n@click.option(\n    \"--read-only\",\n    is_flag=True,\n    help=\"Run in read-only mode, disable any change through rustfava.\",\n)\n@click.option(\"-d\", \"--debug\", is_flag=True, help=\"Turn on debugging.\")\n@click.option(\n    \"--profile\",\n    is_flag=True,\n    help=\"Turn on profiling. Implies --debug.\",\n)\n@click.option(\n    \"--profile-dir\",\n    type=click.Path(),\n    help=\"Output directory for profiling data.\",\n)\n@click.option(\n    \"--poll-watcher\", is_flag=True, help=\"Use old polling-based watcher.\"\n)\n@click.version_option(package_name=\"rustfava\")\ndef main(  # noqa: PLR0913\n    *,\n    filenames: tuple[str, ...] = (),\n    port: int = 5000,\n    host: str = \"localhost\",\n    prefix: str | None = None,\n    incognito: bool = False,\n    read_only: bool = False,\n    debug: bool = False,\n    profile: bool = False,\n    profile_dir: str | None = None,\n    poll_watcher: bool = False,\n) -&gt; None:  # pragma: no cover\n    \"\"\"Start Rustfava for FILENAMES on http://&lt;host&gt;:&lt;port&gt;.\n\n    If the `BEANCOUNT_FILE` environment variable is set, Rustfava will use the\n    files (delimited by ';' on Windows and ':' on POSIX) given there in\n    addition to FILENAMES.\n\n    Note you can also specify command-line options via environment variables\n    with the `RUSTFAVA_` prefix. For example, `--host=0.0.0.0` is equivalent to\n    setting the environment variable `RUSTFAVA_HOST=0.0.0.0`.\n    \"\"\"\n    all_filenames = _add_env_filenames(filenames)\n\n    if not all_filenames:\n        raise NoFileSpecifiedError\n\n    from rustfava.application import create_app\n\n    app = create_app(\n        all_filenames,\n        incognito=incognito,\n        read_only=read_only,\n        poll_watcher=poll_watcher,\n    )\n\n    if prefix:\n        from werkzeug.middleware.dispatcher import DispatcherMiddleware\n\n        from rustfava.util import simple_wsgi\n\n        app.wsgi_app = DispatcherMiddleware(  # type: ignore[method-assign]\n            simple_wsgi,\n            {prefix: app.wsgi_app},\n        )\n\n    # ensure that cheroot does not use IP6 for localhost\n    host = \"127.0.0.1\" if host == \"localhost\" else host\n    # Debug mode if profiling is active\n    debug = debug or profile\n\n    click.secho(f\"Starting Fava on http://{host}:{port}\", fg=\"green\")\n    if not debug:\n        from cheroot.wsgi import Server\n\n        server = Server((host, port), app)\n        try:\n            server.start()\n        except KeyboardInterrupt:\n            click.echo(\"Keyboard interrupt received: stopping Fava\", err=True)\n            server.stop()\n        except OSError as error:\n            if \"No socket could be created\" in str(error):\n                raise AddressInUse(port) from error\n            raise click.Abort from error\n    else:\n        from werkzeug.middleware.profiler import ProfilerMiddleware\n\n        from rustfava.util import setup_debug_logging\n\n        setup_debug_logging()\n        if profile:\n            app.wsgi_app = ProfilerMiddleware(  # type: ignore[method-assign]\n                app.wsgi_app,\n                restrictions=(30,),\n                profile_dir=profile_dir or None,\n            )\n\n        app.jinja_env.auto_reload = True\n        try:\n            app.run(host, port, debug)\n        except OSError as error:\n            if error.errno == errno.EADDRINUSE:\n                raise AddressInUse(port) from error\n            raise\n</code></pre>"},{"location":"changelog/","title":"Changelog","text":""},{"location":"changelog/#rustfava-2025","title":"Rustfava (2025)","text":"<p>This is a fork of Fava that replaces the Python Beancount parser and beanquery with rustledger, a Rust-based implementation of the Beancount format compiled to WebAssembly.</p> <p>Key changes from Fava:</p> <ul> <li>No Beancount dependency: Rustfava uses rustledger for parsing, so you   don't need to install Python's beancount package. Your existing Beancount   files are fully compatible.</li> <li>Query support: BQL queries are now handled by rustledger's built-in query   engine instead of beanquery. The query syntax remains largely compatible.</li> <li>Optional beancount compatibility: If you need to use Beancount plugins or   the import system, install with <code>uv pip install rustfava[beancount-compat]</code>.</li> </ul>"},{"location":"changelog/#v130-2024-12-29","title":"v1.30 (2024-12-29)","text":"<p>Note: This entry describes the original Fava release. Rustfava is based on this version with the rustledger integration.</p> <p>Under the hood, this also upgrades Svelte (the framework used for the frontend parts) to version 5.</p>"},{"location":"changelog/#v129-2024-10-09","title":"v1.29 (2024-10-09)","text":"<p>With this release, query results are now rendered in the frontend. The templates for HTML rendering are still available but extension authors are encouraged to switch, see the statistics report for an example how this can be done. This release adds CSS styles for dark-mode. Numerical comparisons on the units, price or cost are now possible in rustfava filters. As the watchfiles based watcher might not work correctly in some setups with network file systems, you can switch to the (slower) polling based watcher as well. The <code>default-file</code> option, if set, is now considered instead of the \"main\" file when inserting an entry.</p>"},{"location":"changelog/#v128-2024-07-07","title":"v1.28 (2024-07-07)","text":"<p>This release accumulates a couple of minor fixes and improvements. Under the hood, the file change detection is now powered by watchfiles instead of polling, which is more performant.</p>"},{"location":"changelog/#v127-2024-01-06","title":"v1.27 (2024-01-06)","text":"<p>It is now possible to convert to a sequence of currencies. Posting metadata is now supported in the entry forms. The editor should now be a bit more performant as the previous parses will be reused better. For compatibility with extensions using them, the Javascript and CSS for the \"old\" account trees has been re-added.</p>"},{"location":"changelog/#v126-2023-09-04","title":"v1.26 (2023-09-04)","text":"<p>This release brings various improvements to the charts, like allowing the toggling of currencies by clicking on their names in the chart legend. The account balance trees in rustfava are now rendered in the frontend, fixing some minor bugs in the process and easing maintenance. rustfava extensions can now also provide their own endpoints.</p>"},{"location":"changelog/#v125-2023-07-17","title":"v1.25 (2023-07-17)","text":"<p>With this release, extensions can now ship Javascript code to run in the frontend. The editor in rustfava now uses a tree-sitter grammar to obtain a full parsed syntax tree, which makes editor functionality more maintainable and should improve the autocompletion. The Flask WSGI app is now created using the application factory pattern - users who use the rustfava WSGI app directly should switch from <code>rustfava.application.app</code> to the <code>create_app</code> function in <code>rustfava.application</code>. This release also drops support for Python 3.7 and contains a couple of minor fixes and changes, in particular various styling fixes.</p>"},{"location":"changelog/#v124-2023-02-21","title":"v1.24 (2023-02-21)","text":"<p>With this release, the rendering of some report like the documents report has been moved completely to the frontend, which should be slightly more perfomant and easier to maintain. This release also contains a couple of minor fixes and changes.</p>"},{"location":"changelog/#v123-2022-10-15","title":"v1.23 (2022-10-15)","text":"<p>This release accumulates a couple of minor fixes and changes.</p>"},{"location":"changelog/#v122-2022-07-03","title":"v1.22 (2022-07-03)","text":"<p>This release brings stacked bar charts, which are a great way to visualise income broken down per account per month for example. The inferred display precision for currencies is now also used in the frontend and can be overwritten with commodity metadata.</p> <p>The <code>journal-show</code>, <code>journal-show-document</code>, and <code>journal-show-transaction</code> rustfava-options have been removed. The types of entries that to show in the journal are now automatically stored in the browser of the user (in localStorage).</p> <p>As usual, this release also includes a couple of bug fixes and minor improvements. To avoid some race conditions and improve perfomance, the per-file Ledger class is not filtered anymore in-place but rather the filtered data is generated per request - some extensions might have to adjust for this and use <code>g.filtered</code> instead of <code>ledger</code> for some attributes.</p>"},{"location":"changelog/#v121-2022-02-06","title":"v1.21 (2022-02-06)","text":"<p>This release of rustfava drops support for Python 3.6. It mainly consists of various small improvements and fixes.</p>"},{"location":"changelog/#v1201-2021-09-22","title":"v1.20.1 (2021-09-22)","text":"<p>Bugfix release to fix loading of translations for the browser-rendered frontend parts.</p>"},{"location":"changelog/#v120-2021-09-19","title":"v1.20 (2021-09-19)","text":"<p>In this release, the document page now shows counts in the account tree and allows collapsing of accounts in the tree. Parts of the charts in the future are now desaturated. This release contains a couple of bug fixes as usual.</p>"},{"location":"changelog/#v119-2021-05-18","title":"v1.19 (2021-05-18)","text":"<p>The <code>conversion</code> and <code>interval</code> options have been removed. Their functionality can be achieved with the new <code>default-page</code> option. The editor components have been completely reworked, include autocompletion in more places and are now based on version 6 of CodeMirror. An option <code>invert-income-liabilities-equity</code> has been added to invert the numbers of those accounts on the income statement and the balance sheet. This release also adds a Bulgarian translation and features various smaller improvements and fixes as usual.</p>"},{"location":"changelog/#v118-2021-01-16","title":"v1.18 (2021-01-16)","text":"<p>This release contains couple of small improvements and various bug fixes.</p>"},{"location":"changelog/#v117-2020-11-15","title":"v1.17 (2020-11-15)","text":"<p>This release adds a document preview to the import page, as well as support for Python 3.9. It also fixes a couple of bugs.</p>"},{"location":"changelog/#v116-2020-10-18","title":"v1.16 (2020-10-18)","text":"<p>This release brings area charts as an alternative option to view the various line charts in rustfava and a Catalan translation for rustfava. There is also now an option to set the indentation of inserted Beancount entries. As usual this release also includes various minor fixes and improvements.</p>"},{"location":"changelog/#v115-2020-05-30","title":"v1.15 (2020-05-30)","text":"<p>This release accumulates various minor fixes and improvements, for example the setting of filters from payees and metadata in the Journal report.</p>"},{"location":"changelog/#v114-2020-02-16","title":"v1.14 (2020-02-16)","text":"<p>This is mainly a bugfix release to fix compatibility with one of the main dependencies (werkzeug). Also, a <code>default-conversion</code> option was added, which allows setting a default conversion.</p>"},{"location":"changelog/#v113-2020-02-01","title":"v1.13 (2020-02-01)","text":"<p>Rustfava can now display charts for BQL queries - if they have exactly two columns 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.</p>"},{"location":"changelog/#v112-2019-12-03","title":"v1.12 (2019-12-03)","text":"<p>Apart from plenty of bug fixes, this release mainly contains improvements to the forms to add transactions: postings can now be dragged and the full cost syntax of Beancount should supported.</p>"},{"location":"changelog/#v111-2019-08-20","title":"v1.11 (2019-08-20)","text":"<p>The import page of rustfava has been reworked - it now supports moving files to the documents folder and the import process should be a bit more interactive. This release also contains various fixes and a new <code>collapse-pattern</code> option to collapse accounts in account trees based on regular expressions (and replaces the use of the <code>rustfava-collapse-account</code> metadata entry).</p> <p>Other changes:</p> <ul> <li>Command line flags can be specified by setting environment variables.</li> <li>A Taiwanese translation has been added.</li> </ul>"},{"location":"changelog/#v110-2019-01-31","title":"v1.10 (2019-01-31)","text":"<p>This release contains mostly smaller changes and fixes. In particular, the net worth chart will now follow the selected conversion.</p>"},{"location":"changelog/#v19-2018-10-08","title":"v1.9 (2018-10-08)","text":"<p>In this release, the click behaviour has been updated to allow filtering for payees. The entry input forms now allow inputting prices and costs. As always, bugs have been fixed.</p>"},{"location":"changelog/#v18-2018-07-25","title":"v1.8 (2018-07-25)","text":"<p>The journal design has been updated and should now have a clearer structure. Starting with this version, there will not be any more GUI releases of rustfava. The GUI broke frequently and does not seem to worth the maintenance burden.</p> <p>Other changes:</p> <ul> <li>When downloading documents, the original filename will be used.</li> <li><code>any()</code> and <code>all()</code> functions have been added to the filter syntax to allow   filtering entries by properties of their postings.</li> <li>As always, bugs have been fixed.</li> </ul>"},{"location":"changelog/#v17-2018-03-09","title":"v1.7 (2018-03-09)","text":"<p>The entry filters have been reworked in this release and should now support for more flexible filtering of the entries. See the help page on how the new syntax works. Also, when completing the payee in the transaction form, the postings of the last transaction for this payee will be auto-filled.</p> <p>Other changes:</p> <ul> <li>The rustfava-option to hide the charts has been removed. This is now tracked in   the page URL.</li> <li>As always, bugs have been fixed.</li> </ul>"},{"location":"changelog/#v16-2017-10-06","title":"v1.6 (2017-10-06)","text":"<p>This is a release with various small changes and mainly some speed improvements to the Balance Sheet and the net worth calculation. Also, if 'At Value' is selected, the current unrealized gain is shown in parentheses in the Balance Sheet.</p> <p>Other changes:</p> <ul> <li>The currently filtered entries can now be exported from the Journal page.</li> <li>The CLI now has a <code>--version</code> flag.</li> </ul>"},{"location":"changelog/#v15-2017-07-23","title":"v1.5 (2017-07-23)","text":"<p>Rustfava now has an interface to edit single entries. Clicking on the entry date in the Journal will open an overlay that shows the entry context and allows editing just the lines of that entry.</p> <p>Other changes:</p> <ul> <li>The source editor now has a menu that gives access to editor commands like   \"fold all\".</li> <li>Entries with matching tags or links can now be excluded with <code>-#tag</code>.</li> <li>The keyboard shortcuts are now displayed in-place.</li> <li>The <code>incognito</code> option has been removed and replaced with a <code>--incognito</code>   command line switch.</li> <li>As always, several bugs have been fixed.</li> </ul>"},{"location":"changelog/#v14-2017-05-14","title":"v1.4 (2017-05-14)","text":"<p>Rustfava now provides an interface for Beancount's import system that allows you to import transactions from your bank for example.</p> <p>Rustfava can now show your balances at market value or convert them to a single currency if your file contains the necessary price information.</p> <p>We now also provide a compiled GUI version of rustfava for Linux and macOS. This version might still be a bit buggy so any feedback/help on it is very welcome.</p> <p>Other changes:</p> <ul> <li>The <code>insert-entry</code> option can be used to control where transactions are   inserted.</li> <li>The transaction form now accepts tags and links in the narration field.</li> <li>Budgets are now accumulated over all children where appropriate.</li> <li>As always, several bugs have been fixed.</li> </ul>"},{"location":"changelog/#v13-2017-03-15","title":"v1.3 (2017-03-15)","text":"<p>The translations of rustfava are on POEditor.com, which has helped us get translations in five more languages: Chinese (simplified), Dutch, French, Portuguese, and Spanish. A big thank you to the new translators!</p> <p>The transaction form has been improved, it now supports adding metadata and the suggestions will be ranked by how often and recently they occur (using exponential decay).</p> <p>The Query page supports all commands of the <code>bean-query</code> shell and shares its history of recently used queries.</p> <p>Rustfava has gained a basic extension mechanism. Extensions allow you to run hooks at various points, e.g., after adding a transaction. They are specified using the <code>extensions</code> option and for an example, see the <code>rustfava.ext.auto_commit</code> extension.</p> <p>Other changes:</p> <ul> <li>The default sort order in journals has been reversed so that the most recent   entries come first.</li> <li>The new <code>incognito</code> option can be used to obscure all numbers.</li> <li>As always, several bugs have been fixed.</li> </ul>"},{"location":"changelog/#v12-2016-12-25","title":"v1.2 (2016-12-25)","text":"<p>You can now add transactions from within rustfava. The form supports autocompletion for most fields.</p> <p>Rustfava will now show a little bubble in the sidebar for the number of events in the next week. This can be configured with the <code>upcoming-events</code> option.</p> <p>Other changes:</p> <ul> <li>The payee filter can filter by regular expression.</li> <li>The tag filter can filter for links, too.</li> <li>There's a nice spinning indicator during asynchronous page loads.</li> <li>The Journal shows little indicators for metadata.</li> <li>As always, several bugs have been fixed.</li> </ul>"},{"location":"changelog/#v11-2016-11-19","title":"v1.1 (2016-11-19)","text":"<p>You can now upload documents by dropping them onto transactions, which will also add the file path as <code>statement</code> metadata to the transaction. rustfava also ships with a plugin to link these transactions with the generated documents. See the help pages for details.</p> <p>This is the first release for which we provide compiled binaries (for macOS and Linux). These do not have any dependencies and can simply be executed from the terminal.</p> <p>Other changes:</p> <ul> <li>The bar charts on account pages now also show budgets.</li> <li>The Journal can now be sorted by date, flag and narration.</li> <li>Rustfava now has a Russian translation.</li> <li>As always, several bugs have been fixed.</li> </ul>"},{"location":"changelog/#v10-2016-10-19","title":"v1.0 (2016-10-19)","text":"<p>This is a major new release that includes too many improvements and changes to list. Some highlights:</p> <ul> <li>The layout has been tweaked and we use some nicer fonts.</li> <li>Rustfava looks and works much better on smaller screens.</li> <li>Rustfava loads most pages asynchronously, so navigating rustfava is much faster and   responsive.</li> </ul> <p>rustfava's configuration is not read from a configuration file anymore but can rather be specified using custom entries in the Beancount file. Some options have also been removed or renamed, so check rustfava's help page on the available options when upgrading from v0.3.0.</p> <p>There have been many changes under the hood to improve rustfava's codebase and a lot of bugs have been squashed.</p>"},{"location":"changelog/#v030-2016-03-24","title":"v0.3.0 (2016-03-24)","text":""},{"location":"changelog/#additions","title":"Additions","text":"<ul> <li>Support for switching between multiple beancount files.</li> <li>New sunburst charts.</li> <li>Add \"Clear filter\" button when filters are active.</li> <li>Simple budgeting functionality in the Account view. See help pages on how to   use budgets.</li> <li>German translation.</li> <li>The Beancount is now being reloaded when it is saved in the Source Editor.</li> <li>New Journal filter controls.</li> <li>Tree-tables are now displayed in a hierarchical way.</li> </ul>"},{"location":"changelog/#changes","title":"Changes","text":"<ul> <li>All charts are now rendered with d3.js.</li> <li>The title of a page is now shown in the header to save screen space.</li> <li>Changed shortcut for Journal from <code>g g</code> to <code>g j</code> as the Journal was   renamed from \"General Journal\" to \"Journal\".</li> </ul>"},{"location":"changelog/#new-configuration-options","title":"New configuration options","text":"<ul> <li><code>language</code>: The language to use. Valid languages are <code>\"en\"</code> and <code>\"de\"</code>   (default: <code>\"en\"</code>).</li> <li><code>treemaps-show-negative-numbers</code> was removed.</li> </ul>"},{"location":"changelog/#fixes","title":"Fixes","text":"<ul> <li>Commodity prices are now filtered when a Time filter is enabled.</li> <li>Some improvements to the help pages.</li> <li>Many small bug fixes.</li> </ul>"},{"location":"changelog/#v026-2016-03-20","title":"v0.2.6 (2016-03-20)","text":""},{"location":"changelog/#additions_1","title":"Additions","text":"<ul> <li>There are now more interval options available for charts and the account   balances report. The interval can be selected from a dropdown next to the   charts.</li> <li>Show metadata for postings in the Journal.</li> <li>The editor now supports org-mode style folding.</li> <li>Show colored dots for all the postings of a transaction in the Journal   report. This way flagged postings can be quickly spotted.</li> <li>Add keyboard shortcuts for save to source editor.</li> </ul>"},{"location":"changelog/#changes_1","title":"Changes","text":"<ul> <li>Use beancount's DisplayContext to determine the correct precision at which to   render numbers.</li> <li>Improve the way that query results are serialized to XLS etc.</li> <li>Show inverse rates for pairs of operating currencies on the commodities   report.</li> <li>Use Click for the CLI and check if beancount file exists on startup.</li> <li>Hide closed accounts in tree tables. Also see new configuration option below.</li> </ul>"},{"location":"changelog/#new-configuration-options_1","title":"New configuration options","text":"<ul> <li><code>editor-strip-trailing-whitespace</code> to enable trimming of trailing   whitespace in the Source editor (default: \"false\").</li> <li><code>show-closed-accounts</code> to show closed accounts in tree tables, for example   on the balance sheet (default: \"false\").</li> <li><code>show-accounts-with-zero-balance</code> to show accounts with a balance of zero   in tree tables (default: \"true\").</li> <li><code>show-accounts-with-zero-transactions</code> to show accounts with no   transactions in tree tables (default: \"true\").</li> </ul>"},{"location":"changelog/#fixes_1","title":"Fixes","text":"<ul> <li>Fixed a bug where the months would be off by one for the interval reports.</li> <li>Fix the net worth report for more than one currency.</li> <li>Some improvements to the help pages.</li> <li>Many small bug fixes.</li> </ul>"},{"location":"changelog/#v025-2016-02-28","title":"v0.2.5 (2016-02-28)","text":"<p>Bump release to remove unused draft code.</p>"},{"location":"changelog/#v024-2016-02-18","title":"v0.2.4 (2016-02-18)","text":""},{"location":"changelog/#additions_2","title":"Additions","text":"<ul> <li>Added missing Holdings views compared to <code>bean-web</code>.</li> <li>Custom queries are now shown in sidebar.</li> <li>The user settings file is now editable in the Source editor.</li> <li>Added second theme.</li> <li>Added Help pages.</li> <li>Query results can now be downloaded as CSV, XLS, XLSX and ODS.</li> <li>Documents can now be uploaded by dragging and dropping files over an Account   name on the Account page and all tree-tables.</li> <li>Journal can now be filtered by transaction type.</li> </ul>"},{"location":"changelog/#changes_2","title":"Changes","text":"<ul> <li>The uptodate-indicator is now shown everywhere by default, but only enabled   for accounts that have the metadata <code>rustfava-uptodate-indication: \"True\"</code> set   on their <code>open</code>-directives.</li> <li>Speedier Journal rendering.</li> <li>Only basenames will be shown for documents in the Journal.</li> <li>Slightly reordered the sidebar menu.</li> <li>Minor UI tweaks.</li> </ul>"},{"location":"changelog/#new-configuration-options_2","title":"New configuration options","text":"<ul> <li><code>sidebar-show-queries</code>: The maximum number of custom queries to show in the   sidebar (default: 5).</li> <li><code>theme</code>: The theme to use. Valid themes are <code>\"default\"</code> and <code>\"alternative\"</code>   (default: <code>\"default\"</code>).</li> <li><code>editor-print-margin-column</code>: Set the column for the print margin in the   Source editor (default: 60).</li> <li><code>uptodate-indicator-show-everywhere</code> (default: \"true\"). See Changes above.</li> </ul>"},{"location":"changelog/#removed-configuration-options","title":"Removed configuration options","text":"<ul> <li><code>uptodate-indicator-exclude-accounts</code>, see Changes above.</li> </ul>"},{"location":"changelog/#fixes_2","title":"Fixes","text":"<ul> <li>Fixed Net worth calculation.</li> <li>Many small bug fixes.</li> </ul>"},{"location":"changelog/#v023-2016-02-15","title":"v0.2.3 (2016-02-15)","text":"<p>Bumped version to communicate that installing via <code>pip install</code> now works, all requirements included.</p>"},{"location":"changelog/#earlier-versions","title":"Earlier Versions","text":"<p>It was not possible to install any of the earlier versions only using <code>pip</code> and you may consult the git log for earlier changes. The first commit in the git repository was on December 4th, 2015.</p>"},{"location":"deployment/","title":"Deployment","text":"<p>There are a number of deployment options for persistently running rustfava on the Web, depending on your Web server and WSGI deployment choices. Below you can find some examples.</p>"},{"location":"deployment/#apache-with-reverse-proxy","title":"Apache with reverse proxy","text":"<p>Apache configuration:</p> <pre><code>ProxyPass \"/rustfava\" \"http://localhost:5000/rustfava\"\n</code></pre> <p>The above will make rustfava accessible at the <code>/rustfava</code> URL and proxy requests arriving there to a locally running rustfava. To make rustfava work properly in that context, you should run it using the <code>--prefix</code> command line option, like this:</p> <pre><code>rustfava --prefix /rustfava /path/to/your/main.beancount\n</code></pre> <p>To have rustfava run automatically at boot and manageable as a system service you might want to define a systemd unit file for it, for example:</p> <pre><code>[Unit]\nDescription=Rustfava Web UI for Beancount\n\n[Service]\nType=simple\nExecStart=/usr/bin/rustfava --host localhost --port 5000 --prefix /rustfava /path/to/your/main.beancount\nUser=your-user\n</code></pre>"},{"location":"development/","title":"Development","text":""},{"location":"development/#setting-up-a-development-environment","title":"Setting up a development environment","text":"<p>If you want to hack on rustfava or run the latest development version, make sure you have recent enough versions of the following installed (ideally with your system package manager):</p> <ul> <li>Python 3.13+ - as rustfava is written in Python</li> <li>Bun - to build the frontend</li> <li>just - to run various build / lint / test targets</li> <li>uv - to install the development environment and run scripts</li> </ul> <p>Then this will get you up and running:</p> <pre><code>git clone https://github.com/rustledger/rustfava.git\ncd rustfava\n# setup a virtual environment (at .venv) and install rustfava and development\n# dependencies into it:\njust dev\n</code></pre> <p>You can start rustfava in the virtual environment as usual by running <code>rustfava</code>. Running in debug mode with <code>rustfava --debug</code> is useful for development.</p> <p>You can run the tests with <code>just test</code> and the linters by running <code>just lint</code>. Run <code>just --list</code> to see all available recipes. After any changes to the Javascript code, you will need to re-build the frontend, which you can do by running <code>just frontend</code>. If you are working on the frontend code, running <code>bun run dev</code> in the <code>frontend</code> folder will watch for file changes and rebuild the Javascript bundle continuously.</p> <p>Contributions are very welcome, just open a PR on GitHub.</p> <p>Rustfava is released under the MIT License.</p>"},{"location":"usage/","title":"Getting Started","text":"<p>If you're new to Beancount-format files or double-entry accounting in general, we recommend Command-line Accounting in Context, a motivational document written by Martin Blais, the creator of the Beancount format.</p> <p>To learn how to create your ledger file, refer to Getting Started with Beancount guide. There is extensive documentation for the Beancount file format at the Beancount Documentation page.</p>"},{"location":"usage/#installation","title":"Installation","text":"<p>Rustfava runs on macOS, Linux, and Windows. You will need Python 3 and uv.</p> <p>Then you can install rustfava or update your existing installation by running:</p> <pre><code>uv pip install --upgrade rustfava\n</code></pre> <p>Rustfava uses rustledger, a Rust-based parser compiled to WebAssembly, to parse your Beancount files. No separate Beancount installation is required.</p> <p>If you want to export query results to Microsoft Excel or LibreOffice Calc, use the following command to install the optional dependencies for this feature:</p> <pre><code>uv pip install --upgrade rustfava[excel]\n</code></pre>"},{"location":"usage/#starting-rustfava","title":"Starting Rustfava","text":"<p>After installing rustfava, you can start it by running:</p> <pre><code>rustfava ledger.beancount\n</code></pre> <p>pointing it to your Beancount file -- and visit the web interface at http://localhost:5000.</p> <p>There are some command-line options available, run <code>rustfava --help</code> for an overview.</p> <p>For more information on rustfava's features, refer to the help pages that are available through rustfava's web-interface. Rustfava comes with Gmail-style keyboard shortcuts; press <code>?</code> to show an overview.</p>"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"Welcome to rustfava!","text":"<p>rustfava is a web interface for double-entry bookkeeping, powered by rustledger, a Rust-based parser for the Beancount file format compiled to WebAssembly for fast processing.</p> <p>rustfava is a fork of Fava that replaces the Python Beancount parser with rustledger for improved performance. Your existing Beancount files are fully compatible.</p> <p></p> <p>If you are new to rustfava or Beancount-format files, begin with the Getting Started guide.</p>"},{"location":"#quick-start","title":"Quick Start","text":""},{"location":"#desktop-app-recommended","title":"Desktop App (Recommended)","text":"<p>Download the desktop app from GitHub Releases - no installation required, just double-click to run.</p>"},{"location":"#command-line","title":"Command Line","text":"<pre><code>uv tool install rustfava\nrustfava ledger.beancount\n</code></pre> <p>Then visit http://localhost:5000.</p>"},{"location":"#docker","title":"Docker","text":"<pre><code>docker run -p 5000:5000 -v /path/to/ledger:/data ghcr.io/rustledger/rustfava /data/main.beancount\n</code></pre>"},{"location":"api/","title":"API Reference","text":"<p>Note</p> <p>There's no stability guarantee as this is just for internal purposes currently.</p>"},{"location":"api/#core-modules","title":"Core Modules","text":""},{"location":"api/#rustfava.core","title":"<code>rustfava.core</code>","text":"<p>This module provides the data required by Fava's reports.</p>"},{"location":"api/#rustfava.core.EntryNotFoundForHashError","title":"<code>EntryNotFoundForHashError</code>","text":"<p>               Bases: <code>RustfavaAPIError</code></p> <p>Entry not found for hash.</p> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>class EntryNotFoundForHashError(RustfavaAPIError):\n    \"\"\"Entry not found for hash.\"\"\"\n\n    def __init__(self, entry_hash: str) -&gt; None:\n        super().__init__(f'No entry found for hash \"{entry_hash}\"')\n</code></pre>"},{"location":"api/#rustfava.core.StatementNotFoundError","title":"<code>StatementNotFoundError</code>","text":"<p>               Bases: <code>RustfavaAPIError</code></p> <p>Statement not found.</p> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>class StatementNotFoundError(RustfavaAPIError):\n    \"\"\"Statement not found.\"\"\"\n\n    def __init__(self) -&gt; None:\n        super().__init__(\"Statement not found.\")\n</code></pre>"},{"location":"api/#rustfava.core.StatementMetadataInvalidError","title":"<code>StatementMetadataInvalidError</code>","text":"<p>               Bases: <code>RustfavaAPIError</code></p> <p>Statement metadata not found or invalid.</p> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>class StatementMetadataInvalidError(RustfavaAPIError):\n    \"\"\"Statement metadata not found or invalid.\"\"\"\n\n    def __init__(self, key: str) -&gt; None:\n        super().__init__(\n            f\"Statement path at key '{key}' missing or not a string.\"\n        )\n</code></pre>"},{"location":"api/#rustfava.core.JournalPage","title":"<code>JournalPage</code>  <code>dataclass</code>","text":"<p>A page of journal entries.</p> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>@dataclass(frozen=True)\nclass JournalPage:\n    \"\"\"A page of journal entries.\"\"\"\n\n    entries: Sequence[tuple[int, Directive]]\n    total_pages: int\n</code></pre>"},{"location":"api/#rustfava.core.FilteredLedger","title":"<code>FilteredLedger</code>","text":"<p>Filtered Beancount ledger.</p> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>class FilteredLedger:\n    \"\"\"Filtered Beancount ledger.\"\"\"\n\n    __slots__ = (\n        \"__dict__\",  # for the cached_property decorator\n        \"_date_first\",\n        \"_date_last\",\n        \"_pages\",\n        \"date_range\",\n        \"entries\",\n        \"ledger\",\n    )\n    _date_first: date | None\n    _date_last: date | None\n\n    def __init__(\n        self,\n        ledger: RustfavaLedger,\n        *,\n        account: str | None = None,\n        filter: str | None = None,  # noqa: A002\n        time: str | None = None,\n    ) -&gt; None:\n        \"\"\"Create a filtered view of a ledger.\n\n        Args:\n            ledger: The ledger to filter.\n            account: The account filter.\n            filter: The advanced filter.\n            time: The time filter.\n        \"\"\"\n        self.ledger = ledger\n        self.date_range: DateRange | None = None\n        self._pages: (\n            tuple[\n                int,\n                Literal[\"asc\", \"desc\"],\n                list[Sequence[tuple[int, Directive]]],\n            ]\n            | None\n        ) = None\n\n        entries = ledger.all_entries\n        if account:\n            entries = AccountFilter(account).apply(entries)\n        if filter and filter.strip():\n            entries = AdvancedFilter(filter.strip()).apply(entries)\n        if time:\n            time_filter = TimeFilter(ledger.options, ledger.fava_options, time)\n            entries = time_filter.apply(entries)\n            self.date_range = time_filter.date_range\n        self.entries = entries\n\n        if self.date_range:\n            self._date_first = self.date_range.begin\n            self._date_last = self.date_range.end\n            return\n\n        self._date_first = None\n        self._date_last = None\n        for entry in self.entries:\n            if isinstance(entry, Transaction):\n                self._date_first = entry.date\n                break\n        for entry in reversed(self.entries):\n            if isinstance(entry, (Transaction, Price)):\n                self._date_last = entry.date + timedelta(1)\n                break\n\n    @property\n    def end_date(self) -&gt; date | None:\n        \"\"\"The date to use for prices.\"\"\"\n        date_range = self.date_range\n        if date_range:\n            return date_range.end_inclusive\n        return None\n\n    @cached_property\n    def entries_with_all_prices(self) -&gt; Sequence[Directive]:\n        \"\"\"The filtered entries, with all prices added back in for queries.\"\"\"\n        entries = [*self.entries, *self.ledger.all_entries_by_type.Price]\n        entries.sort(key=_incomplete_sortkey)\n        return entries\n\n    @cached_property\n    def entries_without_prices(self) -&gt; Sequence[Directive]:\n        \"\"\"The filtered entries, without prices for journals.\"\"\"\n        return [e for e in self.entries if not isinstance(e, Price)]\n\n    @cached_property\n    def root_tree(self) -&gt; Tree:\n        \"\"\"A root tree.\"\"\"\n        return Tree(self.entries)\n\n    @cached_property\n    def root_tree_closed(self) -&gt; Tree:\n        \"\"\"A root tree for the balance sheet.\"\"\"\n        tree = Tree(self.entries)\n        tree.cap(self.ledger.options, self.ledger.fava_options.unrealized)\n        return tree\n\n    def interval_ranges(self, interval: Interval) -&gt; Sequence[DateRange]:\n        \"\"\"Yield date ranges corresponding to interval boundaries.\n\n        Args:\n            interval: The interval to yield ranges for.\n        \"\"\"\n        if not self._date_first or not self._date_last:\n            return []\n        complete = not self.date_range\n        return dateranges(\n            self._date_first, self._date_last, interval, complete=complete\n        )\n\n    def prices(self, base: str, quote: str) -&gt; Sequence[tuple[date, Decimal]]:\n        \"\"\"List all prices for a pair of commodities.\n\n        Args:\n            base: The price base.\n            quote: The price quote.\n        \"\"\"\n        all_prices = self.ledger.prices.get_all_prices((base, quote))\n        if all_prices is None:\n            return []\n\n        date_range = self.date_range\n        if date_range:\n            return [\n                price_point\n                for price_point in all_prices\n                if date_range.begin &lt;= price_point[0] &lt; date_range.end\n            ]\n        return all_prices\n\n    def account_is_closed(self, account_name: str) -&gt; bool:\n        \"\"\"Check if the account is closed.\n\n        Args:\n            account_name: An account name.\n\n        Returns:\n            True if the account is closed before the end date of the current\n            time filter.\n        \"\"\"\n        date_range = self.date_range\n        close_date = self.ledger.accounts[account_name].close_date\n        if close_date is None:\n            return False\n        return close_date &lt; date_range.end if date_range else True\n\n    def paginate_journal(\n        self,\n        page: int,\n        per_page: int = 1000,\n        order: Literal[\"asc\", \"desc\"] = \"desc\",\n    ) -&gt; JournalPage | None:\n        \"\"\"Get entries for a journal page with pagination info.\n\n        Args:\n            page: Page number (1-indexed).\n            order: Datewise order to sort in\n            per_page: Number of entries per page.\n\n        Returns:\n            A JournalPage, containing a list of entries as (global_index,\n            directive) tuples in reverse chronological order and the total\n            number of pages.\n        \"\"\"\n        if (\n            self._pages is None\n            or self._pages[0] != per_page\n            or self._pages[1] != order\n        ):\n            pages: list[Sequence[tuple[int, Directive]]] = []\n            enumerated = list(enumerate(self.entries_without_prices))\n            entries = (\n                iter(enumerated) if order == \"asc\" else reversed(enumerated)\n            )\n            while batch := tuple(islice(entries, per_page)):\n                pages.append(batch)\n            if not pages:\n                pages.append([])\n            self._pages = (per_page, order, pages)\n        _per_pages, _order, pages = self._pages\n        total = len(pages)\n        if page &gt; total:\n            return None\n        return JournalPage(pages[page - 1], total)\n</code></pre>"},{"location":"api/#rustfava.core.FilteredLedger.end_date","title":"<code>end_date</code>  <code>property</code>","text":"<p>The date to use for prices.</p>"},{"location":"api/#rustfava.core.FilteredLedger.entries_with_all_prices","title":"<code>entries_with_all_prices</code>  <code>cached</code> <code>property</code>","text":"<p>The filtered entries, with all prices added back in for queries.</p>"},{"location":"api/#rustfava.core.FilteredLedger.entries_without_prices","title":"<code>entries_without_prices</code>  <code>cached</code> <code>property</code>","text":"<p>The filtered entries, without prices for journals.</p>"},{"location":"api/#rustfava.core.FilteredLedger.root_tree","title":"<code>root_tree</code>  <code>cached</code> <code>property</code>","text":"<p>A root tree.</p>"},{"location":"api/#rustfava.core.FilteredLedger.root_tree_closed","title":"<code>root_tree_closed</code>  <code>cached</code> <code>property</code>","text":"<p>A root tree for the balance sheet.</p>"},{"location":"api/#rustfava.core.FilteredLedger.__init__","title":"<code>__init__(ledger, *, account=None, filter=None, time=None)</code>","text":"<p>Create a filtered view of a ledger.</p> <p>Parameters:</p> Name Type Description Default <code>ledger</code> <code>RustfavaLedger</code> <p>The ledger to filter.</p> required <code>account</code> <code>str | None</code> <p>The account filter.</p> <code>None</code> <code>filter</code> <code>str | None</code> <p>The advanced filter.</p> <code>None</code> <code>time</code> <code>str | None</code> <p>The time filter.</p> <code>None</code> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>def __init__(\n    self,\n    ledger: RustfavaLedger,\n    *,\n    account: str | None = None,\n    filter: str | None = None,  # noqa: A002\n    time: str | None = None,\n) -&gt; None:\n    \"\"\"Create a filtered view of a ledger.\n\n    Args:\n        ledger: The ledger to filter.\n        account: The account filter.\n        filter: The advanced filter.\n        time: The time filter.\n    \"\"\"\n    self.ledger = ledger\n    self.date_range: DateRange | None = None\n    self._pages: (\n        tuple[\n            int,\n            Literal[\"asc\", \"desc\"],\n            list[Sequence[tuple[int, Directive]]],\n        ]\n        | None\n    ) = None\n\n    entries = ledger.all_entries\n    if account:\n        entries = AccountFilter(account).apply(entries)\n    if filter and filter.strip():\n        entries = AdvancedFilter(filter.strip()).apply(entries)\n    if time:\n        time_filter = TimeFilter(ledger.options, ledger.fava_options, time)\n        entries = time_filter.apply(entries)\n        self.date_range = time_filter.date_range\n    self.entries = entries\n\n    if self.date_range:\n        self._date_first = self.date_range.begin\n        self._date_last = self.date_range.end\n        return\n\n    self._date_first = None\n    self._date_last = None\n    for entry in self.entries:\n        if isinstance(entry, Transaction):\n            self._date_first = entry.date\n            break\n    for entry in reversed(self.entries):\n        if isinstance(entry, (Transaction, Price)):\n            self._date_last = entry.date + timedelta(1)\n            break\n</code></pre>"},{"location":"api/#rustfava.core.FilteredLedger.interval_ranges","title":"<code>interval_ranges(interval)</code>","text":"<p>Yield date ranges corresponding to interval boundaries.</p> <p>Parameters:</p> Name Type Description Default <code>interval</code> <code>Interval</code> <p>The interval to yield ranges for.</p> required Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>def interval_ranges(self, interval: Interval) -&gt; Sequence[DateRange]:\n    \"\"\"Yield date ranges corresponding to interval boundaries.\n\n    Args:\n        interval: The interval to yield ranges for.\n    \"\"\"\n    if not self._date_first or not self._date_last:\n        return []\n    complete = not self.date_range\n    return dateranges(\n        self._date_first, self._date_last, interval, complete=complete\n    )\n</code></pre>"},{"location":"api/#rustfava.core.FilteredLedger.prices","title":"<code>prices(base, quote)</code>","text":"<p>List all prices for a pair of commodities.</p> <p>Parameters:</p> Name Type Description Default <code>base</code> <code>str</code> <p>The price base.</p> required <code>quote</code> <code>str</code> <p>The price quote.</p> required Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>def prices(self, base: str, quote: str) -&gt; Sequence[tuple[date, Decimal]]:\n    \"\"\"List all prices for a pair of commodities.\n\n    Args:\n        base: The price base.\n        quote: The price quote.\n    \"\"\"\n    all_prices = self.ledger.prices.get_all_prices((base, quote))\n    if all_prices is None:\n        return []\n\n    date_range = self.date_range\n    if date_range:\n        return [\n            price_point\n            for price_point in all_prices\n            if date_range.begin &lt;= price_point[0] &lt; date_range.end\n        ]\n    return all_prices\n</code></pre>"},{"location":"api/#rustfava.core.FilteredLedger.account_is_closed","title":"<code>account_is_closed(account_name)</code>","text":"<p>Check if the account is closed.</p> <p>Parameters:</p> Name Type Description Default <code>account_name</code> <code>str</code> <p>An account name.</p> required <p>Returns:</p> Type Description <code>bool</code> <p>True if the account is closed before the end date of the current</p> <code>bool</code> <p>time filter.</p> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>def account_is_closed(self, account_name: str) -&gt; bool:\n    \"\"\"Check if the account is closed.\n\n    Args:\n        account_name: An account name.\n\n    Returns:\n        True if the account is closed before the end date of the current\n        time filter.\n    \"\"\"\n    date_range = self.date_range\n    close_date = self.ledger.accounts[account_name].close_date\n    if close_date is None:\n        return False\n    return close_date &lt; date_range.end if date_range else True\n</code></pre>"},{"location":"api/#rustfava.core.FilteredLedger.paginate_journal","title":"<code>paginate_journal(page, per_page=1000, order='desc')</code>","text":"<p>Get entries for a journal page with pagination info.</p> <p>Parameters:</p> Name Type Description Default <code>page</code> <code>int</code> <p>Page number (1-indexed).</p> required <code>order</code> <code>Literal['asc', 'desc']</code> <p>Datewise order to sort in</p> <code>'desc'</code> <code>per_page</code> <code>int</code> <p>Number of entries per page.</p> <code>1000</code> <p>Returns:</p> Type Description <code>JournalPage | None</code> <p>A JournalPage, containing a list of entries as (global_index,</p> <code>JournalPage | None</code> <p>directive) tuples in reverse chronological order and the total</p> <code>JournalPage | None</code> <p>number of pages.</p> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>def paginate_journal(\n    self,\n    page: int,\n    per_page: int = 1000,\n    order: Literal[\"asc\", \"desc\"] = \"desc\",\n) -&gt; JournalPage | None:\n    \"\"\"Get entries for a journal page with pagination info.\n\n    Args:\n        page: Page number (1-indexed).\n        order: Datewise order to sort in\n        per_page: Number of entries per page.\n\n    Returns:\n        A JournalPage, containing a list of entries as (global_index,\n        directive) tuples in reverse chronological order and the total\n        number of pages.\n    \"\"\"\n    if (\n        self._pages is None\n        or self._pages[0] != per_page\n        or self._pages[1] != order\n    ):\n        pages: list[Sequence[tuple[int, Directive]]] = []\n        enumerated = list(enumerate(self.entries_without_prices))\n        entries = (\n            iter(enumerated) if order == \"asc\" else reversed(enumerated)\n        )\n        while batch := tuple(islice(entries, per_page)):\n            pages.append(batch)\n        if not pages:\n            pages.append([])\n        self._pages = (per_page, order, pages)\n    _per_pages, _order, pages = self._pages\n    total = len(pages)\n    if page &gt; total:\n        return None\n    return JournalPage(pages[page - 1], total)\n</code></pre>"},{"location":"api/#rustfava.core.RustfavaLedger","title":"<code>RustfavaLedger</code>","text":"<p>Interface for a Beancount ledger.</p> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>class RustfavaLedger:\n    \"\"\"Interface for a Beancount ledger.\"\"\"\n\n    __slots__ = (\n        \"_is_encrypted\",\n        \"accounts\",\n        \"accounts\",\n        \"all_entries\",\n        \"all_entries_by_type\",\n        \"attributes\",\n        \"beancount_file_path\",\n        \"budgets\",\n        \"charts\",\n        \"commodities\",\n        \"extensions\",\n        \"fava_options\",\n        \"fava_options_errors\",\n        \"file\",\n        \"format_decimal\",\n        \"get_entry\",\n        \"get_filtered\",\n        \"ingest\",\n        \"load_errors\",\n        \"misc\",\n        \"options\",\n        \"prices\",\n        \"query_shell\",\n        \"watcher\",\n    )\n\n    #: List of all (unfiltered) entries.\n    all_entries: Sequence[Directive]\n\n    #: A list of all errors reported by Beancount.\n    load_errors: Sequence[BeancountError]\n\n    #: The Beancount options map.\n    options: BeancountOptions\n\n    #: A dict with all of Fava's option values.\n    fava_options: RustfavaOptions\n\n    #: A list of all errors from parsing the custom options.\n    fava_options_errors: Sequence[BeancountError]\n\n    #: The price map.\n    prices: RustfavaPriceMap\n\n    #: Dict of list of all (unfiltered) entries by type.\n    all_entries_by_type: EntriesByType\n\n    #: A :class:`.AccountDict` module - details about the accounts.\n    accounts: AccountDict\n\n    #: An :class:`AttributesModule` instance.\n    attributes: AttributesModule\n\n    #: A :class:`.BudgetModule` instance.\n    budgets: BudgetModule\n\n    #: A :class:`.ChartModule` instance.\n    charts: ChartModule\n\n    #: A :class:`.CommoditiesModule` instance.\n    commodities: CommoditiesModule\n\n    #: A :class:`.ExtensionModule` instance.\n    extensions: ExtensionModule\n\n    #: A :class:`.FileModule` instance.\n    file: FileModule\n\n    #: A :class:`.DecimalFormatModule` instance.\n    format_decimal: DecimalFormatModule\n\n    #: A :class:`.IngestModule` instance.\n    ingest: IngestModule\n\n    #: A :class:`.FavaMisc` instance.\n    misc: FavaMisc\n\n    #: A :class:`.QueryShell` instance.\n    query_shell: QueryShell\n\n    def __init__(self, path: str, *, poll_watcher: bool = False) -&gt; None:\n        \"\"\"Create an interface for a Beancount ledger.\n\n        Arguments:\n            path: Path to the main Beancount file.\n            poll_watcher: Whether to use the polling file watcher.\n        \"\"\"\n        #: The path to the main Beancount file.\n        self.beancount_file_path = path\n        self._is_encrypted = is_encrypted_file(path)\n        self.get_filtered = lru_cache(maxsize=16)(self._get_filtered)\n        self.get_entry = lru_cache(maxsize=16)(self._get_entry)\n\n        self.accounts = AccountDict(self)\n        self.attributes = AttributesModule(self)\n        self.budgets = BudgetModule(self)\n        self.charts = ChartModule(self)\n        self.commodities = CommoditiesModule(self)\n        self.extensions = ExtensionModule(self)\n        self.file = FileModule(self)\n        self.format_decimal = DecimalFormatModule(self)\n        self.ingest = IngestModule(self)\n        self.misc = FavaMisc(self)\n        self.query_shell = QueryShell(self)\n\n        self.watcher = WatchfilesWatcher() if not poll_watcher else Watcher()\n\n        self.load_file()\n\n    def load_file(self) -&gt; None:\n        \"\"\"Load the main file and all included files and set attributes.\"\"\"\n        self.all_entries, self.load_errors, self.options = load_uncached(\n            self.beancount_file_path,\n            is_encrypted=self._is_encrypted,\n        )\n        self.get_filtered.cache_clear()\n        self.get_entry.cache_clear()\n\n        self.all_entries_by_type = group_entries_by_type(self.all_entries)\n        self.prices = RustfavaPriceMap(self.all_entries_by_type.Price)\n\n        self.fava_options, self.fava_options_errors = parse_options(\n            self.all_entries_by_type.Custom,\n        )\n\n        if self._is_encrypted:  # pragma: no cover\n            pass\n        else:\n            self.watcher.update(*self.paths_to_watch())\n\n        # Call load_file of all modules.\n        self.accounts.load_file()\n        self.attributes.load_file()\n        self.budgets.load_file()\n        self.charts.load_file()\n        self.commodities.load_file()\n        self.extensions.load_file()\n        self.file.load_file()\n        self.format_decimal.load_file()\n        self.misc.load_file()\n        self.query_shell.load_file()\n        self.ingest.load_file()\n\n        self.extensions.after_load_file()\n\n    def _get_filtered(\n        self,\n        account: str | None = None,\n        filter: str | None = None,  # noqa: A002\n        time: str | None = None,\n    ) -&gt; FilteredLedger:\n        \"\"\"Filter the ledger.\n\n        Args:\n            account: The account filter.\n            filter: The advanced filter.\n            time: The time filter.\n        \"\"\"\n        return FilteredLedger(\n            ledger=self, account=account, filter=filter, time=time\n        )\n\n    @property\n    def mtime(self) -&gt; int:\n        \"\"\"The timestamp to the latest change of the underlying files.\"\"\"\n        return self.watcher.last_checked\n\n    @property\n    def errors(self) -&gt; Sequence[BeancountError]:\n        \"\"\"The errors that the Beancount loading plus Fava module errors.\"\"\"\n        return [\n            *self.load_errors,\n            *self.fava_options_errors,\n            *self.budgets.errors,\n            *self.extensions.errors,\n            *self.misc.errors,\n            *self.ingest.errors,\n        ]\n\n    @property\n    def root_accounts(self) -&gt; tuple[str, str, str, str, str]:\n        \"\"\"The five root accounts.\"\"\"\n        options = self.options\n        return (\n            options[\"name_assets\"],\n            options[\"name_liabilities\"],\n            options[\"name_equity\"],\n            options[\"name_income\"],\n            options[\"name_expenses\"],\n        )\n\n    def join_path(self, *args: str) -&gt; Path:\n        \"\"\"Path relative to the directory of the ledger.\"\"\"\n        return Path(self.beancount_file_path).parent.joinpath(*args).resolve()\n\n    def paths_to_watch(self) -&gt; tuple[Sequence[Path], Sequence[Path]]:\n        \"\"\"Get paths to included files and document directories.\n\n        Returns:\n            A tuple (files, directories).\n        \"\"\"\n        files = [Path(i) for i in self.options[\"include\"]]\n        if self.ingest.module_path:\n            files.append(self.ingest.module_path)\n        return (\n            files,\n            [\n                self.join_path(path, account)\n                for account in self.root_accounts\n                for path in self.options[\"documents\"]\n            ],\n        )\n\n    def changed(self) -&gt; bool:\n        \"\"\"Check if the file needs to be reloaded.\n\n        Returns:\n            True if a change in one of the included files or a change in a\n            document folder was detected and the file has been reloaded.\n        \"\"\"\n        # We can't reload an encrypted file, so act like it never changes.\n        if self._is_encrypted:  # pragma: no cover\n            return False\n        changed = self.watcher.check()\n        if changed:\n            self.load_file()\n        return changed\n\n    def interval_balances(\n        self,\n        filtered: FilteredLedger,\n        interval: Interval,\n        account_name: str,\n        *,\n        accumulate: bool = False,\n    ) -&gt; tuple[Sequence[Tree], Sequence[DateRange]]:\n        \"\"\"Balances by interval.\n\n        Arguments:\n            filtered: The currently filtered ledger.\n            interval: An interval.\n            account_name: An account name.\n            accumulate: A boolean, ``True`` if the balances for an interval\n                should include all entries up to the end of the interval.\n\n        Returns:\n            A pair of a list of Tree instances and the intervals.\n        \"\"\"\n        min_accounts = [\n            account\n            for account in self.accounts\n            if account.startswith(account_name)\n        ]\n\n        interval_ranges = list(reversed(filtered.interval_ranges(interval)))\n        interval_balances = [\n            Tree(\n                slice_entry_dates(\n                    filtered.entries,\n                    date.min if accumulate else date_range.begin,\n                    date_range.end,\n                ),\n                min_accounts,\n            )\n            for date_range in interval_ranges\n        ]\n\n        return interval_balances, interval_ranges\n\n    @listify\n    def account_journal(\n        self,\n        filtered: FilteredLedger,\n        account_name: str,\n        conversion: str | Conversion,\n        *,\n        with_children: bool,\n    ) -&gt; Iterable[\n        tuple[int, Directive, SimpleCounterInventory, SimpleCounterInventory]\n    ]:\n        \"\"\"Journal for an account.\n\n        Args:\n            filtered: The currently filtered ledger.\n            account_name: An account name.\n            conversion: The conversion to use.\n            with_children: Whether to include postings of subaccounts of\n                           the account.\n\n        Yields:\n            Tuples of ``(index, entry, change, balance)``.\n        \"\"\"\n        conv = conversion_from_str(conversion)\n        relevant_account = account_tester(\n            account_name, with_children=with_children\n        )\n\n        prices = self.prices\n        balance = CounterInventory()\n        for index, entry in enumerate(filtered.entries_without_prices):\n            change = CounterInventory()\n            entry_is_relevant = False\n            postings = getattr(entry, \"postings\", None)\n            if postings is not None:\n                for posting in postings:\n                    if relevant_account(posting.account):\n                        entry_is_relevant = True\n                        balance.add_position(posting)\n                        change.add_position(posting)\n            elif any(relevant_account(a) for a in get_entry_accounts(entry)):\n                entry_is_relevant = True\n\n            if entry_is_relevant:\n                yield (\n                    index,\n                    entry,\n                    conv.apply(change, prices, entry.date),\n                    conv.apply(balance, prices, entry.date),\n                )\n\n    def _get_entry(self, entry_hash: str) -&gt; Directive:\n        \"\"\"Find an entry.\n\n        Arguments:\n            entry_hash: Hash of the entry.\n\n        Returns:\n            The entry with the given hash.\n\n        Raises:\n            EntryNotFoundForHashError: If there is no entry for the given hash.\n        \"\"\"\n        try:\n            return next(\n                entry\n                for entry in self.all_entries\n                if entry_hash == hash_entry(entry)\n            )\n        except StopIteration as exc:\n            raise EntryNotFoundForHashError(entry_hash) from exc\n\n    def context(\n        self,\n        entry_hash: str,\n    ) -&gt; tuple[\n        Directive,\n        Mapping[str, Sequence[str]] | None,\n        Mapping[str, Sequence[str]] | None,\n    ]:\n        \"\"\"Context for an entry.\n\n        Arguments:\n            entry_hash: Hash of entry.\n\n        Returns:\n            A tuple ``(entry, before, after, source_slice, sha256sum)`` of the\n            (unique) entry with the given ``entry_hash``. If the entry is a\n            Balance or Transaction then ``before`` and ``after`` contain\n            the balances before and after the entry of the affected accounts.\n        \"\"\"\n        entry = self.get_entry(entry_hash)\n\n        if not isinstance(entry, (Balance, Transaction)):\n            return entry, None, None\n\n        entry_accounts = get_entry_accounts(entry)\n        balances = {account: CounterInventory() for account in entry_accounts}\n        for entry_ in takewhile(lambda e: e is not entry, self.all_entries):\n            if isinstance(entry_, Transaction):\n                for posting in entry_.postings:\n                    balance = balances.get(posting.account, None)\n                    if balance is not None:\n                        balance.add_position(posting)\n\n        def visualise(inv: CounterInventory) -&gt; Sequence[str]:\n            return inv.to_strings()\n\n        before = {acc: visualise(inv) for acc, inv in balances.items()}\n\n        if isinstance(entry, Balance):\n            return entry, before, None\n\n        for posting in entry.postings:\n            balances[posting.account].add_position(posting)\n        after = {acc: visualise(inv) for acc, inv in balances.items()}\n        return entry, before, after\n\n    def commodity_pairs(self) -&gt; Sequence[tuple[str, str]]:\n        \"\"\"List pairs of commodities.\n\n        Returns:\n            A list of pairs of commodities. Pairs of operating currencies will\n            be given in both directions not just in the one found in file.\n        \"\"\"\n        return self.prices.commodity_pairs(self.options[\"operating_currency\"])\n\n    def statement_path(self, entry_hash: str, metadata_key: str) -&gt; str:\n        \"\"\"Get the path for a statement found in the specified entry.\n\n        The entry that we look up should contain a path to a document (absolute\n        or relative to the filename of the entry) or just its basename. We go\n        through all documents and match on the full path or if one of the\n        documents with a matching account has a matching file basename.\n\n        Arguments:\n            entry_hash: Hash of the entry containing the path in its metadata.\n            metadata_key: The key that the path should be in.\n\n        Returns:\n            The filename of the matching document entry.\n\n        Raises:\n            StatementMetadataInvalidError: If the metadata at the given key is\n                                           invalid.\n            StatementNotFoundError: If no matching document is found.\n        \"\"\"\n        entry = self.get_entry(entry_hash)\n        value = entry.meta.get(metadata_key, None)\n        if not isinstance(value, str):\n            raise StatementMetadataInvalidError(metadata_key)\n\n        accounts = set(get_entry_accounts(entry))\n        filename, _ = get_position(entry)\n        full_path = (Path(filename).parent / value).resolve()\n        for document in self.all_entries_by_type.Document:\n            document_path = Path(document.filename)\n            if document_path == full_path:\n                return document.filename\n            if document.account in accounts and document_path.name == value:\n                return document.filename\n\n        raise StatementNotFoundError\n\n    group_entries_by_type = staticmethod(group_entries_by_type)\n</code></pre>"},{"location":"api/#rustfava.core.RustfavaLedger.mtime","title":"<code>mtime</code>  <code>property</code>","text":"<p>The timestamp to the latest change of the underlying files.</p>"},{"location":"api/#rustfava.core.RustfavaLedger.errors","title":"<code>errors</code>  <code>property</code>","text":"<p>The errors that the Beancount loading plus Fava module errors.</p>"},{"location":"api/#rustfava.core.RustfavaLedger.root_accounts","title":"<code>root_accounts</code>  <code>property</code>","text":"<p>The five root accounts.</p>"},{"location":"api/#rustfava.core.RustfavaLedger.__init__","title":"<code>__init__(path, *, poll_watcher=False)</code>","text":"<p>Create an interface for a Beancount ledger.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>Path to the main Beancount file.</p> required <code>poll_watcher</code> <code>bool</code> <p>Whether to use the polling file watcher.</p> <code>False</code> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>def __init__(self, path: str, *, poll_watcher: bool = False) -&gt; None:\n    \"\"\"Create an interface for a Beancount ledger.\n\n    Arguments:\n        path: Path to the main Beancount file.\n        poll_watcher: Whether to use the polling file watcher.\n    \"\"\"\n    #: The path to the main Beancount file.\n    self.beancount_file_path = path\n    self._is_encrypted = is_encrypted_file(path)\n    self.get_filtered = lru_cache(maxsize=16)(self._get_filtered)\n    self.get_entry = lru_cache(maxsize=16)(self._get_entry)\n\n    self.accounts = AccountDict(self)\n    self.attributes = AttributesModule(self)\n    self.budgets = BudgetModule(self)\n    self.charts = ChartModule(self)\n    self.commodities = CommoditiesModule(self)\n    self.extensions = ExtensionModule(self)\n    self.file = FileModule(self)\n    self.format_decimal = DecimalFormatModule(self)\n    self.ingest = IngestModule(self)\n    self.misc = FavaMisc(self)\n    self.query_shell = QueryShell(self)\n\n    self.watcher = WatchfilesWatcher() if not poll_watcher else Watcher()\n\n    self.load_file()\n</code></pre>"},{"location":"api/#rustfava.core.RustfavaLedger.load_file","title":"<code>load_file()</code>","text":"<p>Load the main file and all included files and set attributes.</p> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>def load_file(self) -&gt; None:\n    \"\"\"Load the main file and all included files and set attributes.\"\"\"\n    self.all_entries, self.load_errors, self.options = load_uncached(\n        self.beancount_file_path,\n        is_encrypted=self._is_encrypted,\n    )\n    self.get_filtered.cache_clear()\n    self.get_entry.cache_clear()\n\n    self.all_entries_by_type = group_entries_by_type(self.all_entries)\n    self.prices = RustfavaPriceMap(self.all_entries_by_type.Price)\n\n    self.fava_options, self.fava_options_errors = parse_options(\n        self.all_entries_by_type.Custom,\n    )\n\n    if self._is_encrypted:  # pragma: no cover\n        pass\n    else:\n        self.watcher.update(*self.paths_to_watch())\n\n    # Call load_file of all modules.\n    self.accounts.load_file()\n    self.attributes.load_file()\n    self.budgets.load_file()\n    self.charts.load_file()\n    self.commodities.load_file()\n    self.extensions.load_file()\n    self.file.load_file()\n    self.format_decimal.load_file()\n    self.misc.load_file()\n    self.query_shell.load_file()\n    self.ingest.load_file()\n\n    self.extensions.after_load_file()\n</code></pre>"},{"location":"api/#rustfava.core.RustfavaLedger.join_path","title":"<code>join_path(*args)</code>","text":"<p>Path relative to the directory of the ledger.</p> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>def join_path(self, *args: str) -&gt; Path:\n    \"\"\"Path relative to the directory of the ledger.\"\"\"\n    return Path(self.beancount_file_path).parent.joinpath(*args).resolve()\n</code></pre>"},{"location":"api/#rustfava.core.RustfavaLedger.paths_to_watch","title":"<code>paths_to_watch()</code>","text":"<p>Get paths to included files and document directories.</p> <p>Returns:</p> Type Description <code>tuple[Sequence[Path], Sequence[Path]]</code> <p>A tuple (files, directories).</p> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>def paths_to_watch(self) -&gt; tuple[Sequence[Path], Sequence[Path]]:\n    \"\"\"Get paths to included files and document directories.\n\n    Returns:\n        A tuple (files, directories).\n    \"\"\"\n    files = [Path(i) for i in self.options[\"include\"]]\n    if self.ingest.module_path:\n        files.append(self.ingest.module_path)\n    return (\n        files,\n        [\n            self.join_path(path, account)\n            for account in self.root_accounts\n            for path in self.options[\"documents\"]\n        ],\n    )\n</code></pre>"},{"location":"api/#rustfava.core.RustfavaLedger.changed","title":"<code>changed()</code>","text":"<p>Check if the file needs to be reloaded.</p> <p>Returns:</p> Type Description <code>bool</code> <p>True if a change in one of the included files or a change in a</p> <code>bool</code> <p>document folder was detected and the file has been reloaded.</p> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>def changed(self) -&gt; bool:\n    \"\"\"Check if the file needs to be reloaded.\n\n    Returns:\n        True if a change in one of the included files or a change in a\n        document folder was detected and the file has been reloaded.\n    \"\"\"\n    # We can't reload an encrypted file, so act like it never changes.\n    if self._is_encrypted:  # pragma: no cover\n        return False\n    changed = self.watcher.check()\n    if changed:\n        self.load_file()\n    return changed\n</code></pre>"},{"location":"api/#rustfava.core.RustfavaLedger.interval_balances","title":"<code>interval_balances(filtered, interval, account_name, *, accumulate=False)</code>","text":"<p>Balances by interval.</p> <p>Parameters:</p> Name Type Description Default <code>filtered</code> <code>FilteredLedger</code> <p>The currently filtered ledger.</p> required <code>interval</code> <code>Interval</code> <p>An interval.</p> required <code>account_name</code> <code>str</code> <p>An account name.</p> required <code>accumulate</code> <code>bool</code> <p>A boolean, <code>True</code> if the balances for an interval should include all entries up to the end of the interval.</p> <code>False</code> <p>Returns:</p> Type Description <code>tuple[Sequence[Tree], Sequence[DateRange]]</code> <p>A pair of a list of Tree instances and the intervals.</p> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>def interval_balances(\n    self,\n    filtered: FilteredLedger,\n    interval: Interval,\n    account_name: str,\n    *,\n    accumulate: bool = False,\n) -&gt; tuple[Sequence[Tree], Sequence[DateRange]]:\n    \"\"\"Balances by interval.\n\n    Arguments:\n        filtered: The currently filtered ledger.\n        interval: An interval.\n        account_name: An account name.\n        accumulate: A boolean, ``True`` if the balances for an interval\n            should include all entries up to the end of the interval.\n\n    Returns:\n        A pair of a list of Tree instances and the intervals.\n    \"\"\"\n    min_accounts = [\n        account\n        for account in self.accounts\n        if account.startswith(account_name)\n    ]\n\n    interval_ranges = list(reversed(filtered.interval_ranges(interval)))\n    interval_balances = [\n        Tree(\n            slice_entry_dates(\n                filtered.entries,\n                date.min if accumulate else date_range.begin,\n                date_range.end,\n            ),\n            min_accounts,\n        )\n        for date_range in interval_ranges\n    ]\n\n    return interval_balances, interval_ranges\n</code></pre>"},{"location":"api/#rustfava.core.RustfavaLedger.account_journal","title":"<code>account_journal(filtered, account_name, conversion, *, with_children)</code>","text":"<p>Journal for an account.</p> <p>Parameters:</p> Name Type Description Default <code>filtered</code> <code>FilteredLedger</code> <p>The currently filtered ledger.</p> required <code>account_name</code> <code>str</code> <p>An account name.</p> required <code>conversion</code> <code>str | Conversion</code> <p>The conversion to use.</p> required <code>with_children</code> <code>bool</code> <p>Whether to include postings of subaccounts of            the account.</p> required <p>Yields:</p> Type Description <code>Iterable[tuple[int, Directive, SimpleCounterInventory, SimpleCounterInventory]]</code> <p>Tuples of <code>(index, entry, change, balance)</code>.</p> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>@listify\ndef account_journal(\n    self,\n    filtered: FilteredLedger,\n    account_name: str,\n    conversion: str | Conversion,\n    *,\n    with_children: bool,\n) -&gt; Iterable[\n    tuple[int, Directive, SimpleCounterInventory, SimpleCounterInventory]\n]:\n    \"\"\"Journal for an account.\n\n    Args:\n        filtered: The currently filtered ledger.\n        account_name: An account name.\n        conversion: The conversion to use.\n        with_children: Whether to include postings of subaccounts of\n                       the account.\n\n    Yields:\n        Tuples of ``(index, entry, change, balance)``.\n    \"\"\"\n    conv = conversion_from_str(conversion)\n    relevant_account = account_tester(\n        account_name, with_children=with_children\n    )\n\n    prices = self.prices\n    balance = CounterInventory()\n    for index, entry in enumerate(filtered.entries_without_prices):\n        change = CounterInventory()\n        entry_is_relevant = False\n        postings = getattr(entry, \"postings\", None)\n        if postings is not None:\n            for posting in postings:\n                if relevant_account(posting.account):\n                    entry_is_relevant = True\n                    balance.add_position(posting)\n                    change.add_position(posting)\n        elif any(relevant_account(a) for a in get_entry_accounts(entry)):\n            entry_is_relevant = True\n\n        if entry_is_relevant:\n            yield (\n                index,\n                entry,\n                conv.apply(change, prices, entry.date),\n                conv.apply(balance, prices, entry.date),\n            )\n</code></pre>"},{"location":"api/#rustfava.core.RustfavaLedger.context","title":"<code>context(entry_hash)</code>","text":"<p>Context for an entry.</p> <p>Parameters:</p> Name Type Description Default <code>entry_hash</code> <code>str</code> <p>Hash of entry.</p> required <p>Returns:</p> Type Description <code>Directive</code> <p>A tuple <code>(entry, before, after, source_slice, sha256sum)</code> of the</p> <code>Mapping[str, Sequence[str]] | None</code> <p>(unique) entry with the given <code>entry_hash</code>. If the entry is a</p> <code>Mapping[str, Sequence[str]] | None</code> <p>Balance or Transaction then <code>before</code> and <code>after</code> contain</p> <code>tuple[Directive, Mapping[str, Sequence[str]] | None, Mapping[str, Sequence[str]] | None]</code> <p>the balances before and after the entry of the affected accounts.</p> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>def context(\n    self,\n    entry_hash: str,\n) -&gt; tuple[\n    Directive,\n    Mapping[str, Sequence[str]] | None,\n    Mapping[str, Sequence[str]] | None,\n]:\n    \"\"\"Context for an entry.\n\n    Arguments:\n        entry_hash: Hash of entry.\n\n    Returns:\n        A tuple ``(entry, before, after, source_slice, sha256sum)`` of the\n        (unique) entry with the given ``entry_hash``. If the entry is a\n        Balance or Transaction then ``before`` and ``after`` contain\n        the balances before and after the entry of the affected accounts.\n    \"\"\"\n    entry = self.get_entry(entry_hash)\n\n    if not isinstance(entry, (Balance, Transaction)):\n        return entry, None, None\n\n    entry_accounts = get_entry_accounts(entry)\n    balances = {account: CounterInventory() for account in entry_accounts}\n    for entry_ in takewhile(lambda e: e is not entry, self.all_entries):\n        if isinstance(entry_, Transaction):\n            for posting in entry_.postings:\n                balance = balances.get(posting.account, None)\n                if balance is not None:\n                    balance.add_position(posting)\n\n    def visualise(inv: CounterInventory) -&gt; Sequence[str]:\n        return inv.to_strings()\n\n    before = {acc: visualise(inv) for acc, inv in balances.items()}\n\n    if isinstance(entry, Balance):\n        return entry, before, None\n\n    for posting in entry.postings:\n        balances[posting.account].add_position(posting)\n    after = {acc: visualise(inv) for acc, inv in balances.items()}\n    return entry, before, after\n</code></pre>"},{"location":"api/#rustfava.core.RustfavaLedger.commodity_pairs","title":"<code>commodity_pairs()</code>","text":"<p>List pairs of commodities.</p> <p>Returns:</p> Type Description <code>Sequence[tuple[str, str]]</code> <p>A list of pairs of commodities. Pairs of operating currencies will</p> <code>Sequence[tuple[str, str]]</code> <p>be given in both directions not just in the one found in file.</p> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>def commodity_pairs(self) -&gt; Sequence[tuple[str, str]]:\n    \"\"\"List pairs of commodities.\n\n    Returns:\n        A list of pairs of commodities. Pairs of operating currencies will\n        be given in both directions not just in the one found in file.\n    \"\"\"\n    return self.prices.commodity_pairs(self.options[\"operating_currency\"])\n</code></pre>"},{"location":"api/#rustfava.core.RustfavaLedger.statement_path","title":"<code>statement_path(entry_hash, metadata_key)</code>","text":"<p>Get the path for a statement found in the specified entry.</p> <p>The entry that we look up should contain a path to a document (absolute or relative to the filename of the entry) or just its basename. We go through all documents and match on the full path or if one of the documents with a matching account has a matching file basename.</p> <p>Parameters:</p> Name Type Description Default <code>entry_hash</code> <code>str</code> <p>Hash of the entry containing the path in its metadata.</p> required <code>metadata_key</code> <code>str</code> <p>The key that the path should be in.</p> required <p>Returns:</p> Type Description <code>str</code> <p>The filename of the matching document entry.</p> <p>Raises:</p> Type Description <code>StatementMetadataInvalidError</code> <p>If the metadata at the given key is                            invalid.</p> <code>StatementNotFoundError</code> <p>If no matching document is found.</p> Source code in <code>src/rustfava/core/__init__.py</code> <pre><code>def statement_path(self, entry_hash: str, metadata_key: str) -&gt; str:\n    \"\"\"Get the path for a statement found in the specified entry.\n\n    The entry that we look up should contain a path to a document (absolute\n    or relative to the filename of the entry) or just its basename. We go\n    through all documents and match on the full path or if one of the\n    documents with a matching account has a matching file basename.\n\n    Arguments:\n        entry_hash: Hash of the entry containing the path in its metadata.\n        metadata_key: The key that the path should be in.\n\n    Returns:\n        The filename of the matching document entry.\n\n    Raises:\n        StatementMetadataInvalidError: If the metadata at the given key is\n                                       invalid.\n        StatementNotFoundError: If no matching document is found.\n    \"\"\"\n    entry = self.get_entry(entry_hash)\n    value = entry.meta.get(metadata_key, None)\n    if not isinstance(value, str):\n        raise StatementMetadataInvalidError(metadata_key)\n\n    accounts = set(get_entry_accounts(entry))\n    filename, _ = get_position(entry)\n    full_path = (Path(filename).parent / value).resolve()\n    for document in self.all_entries_by_type.Document:\n        document_path = Path(document.filename)\n        if document_path == full_path:\n            return document.filename\n        if document.account in accounts and document_path.name == value:\n            return document.filename\n\n    raise StatementNotFoundError\n</code></pre>"},{"location":"api/#rustfava.core.accounts","title":"<code>accounts</code>","text":"<p>Account close date and metadata.</p>"},{"location":"api/#rustfava.core.accounts.LastEntry","title":"<code>LastEntry</code>  <code>dataclass</code>","text":"<p>Date and hash of the last entry for an account.</p> Source code in <code>src/rustfava/core/accounts.py</code> <pre><code>@dataclass(frozen=True)\nclass LastEntry:\n    \"\"\"Date and hash of the last entry for an account.\"\"\"\n\n    #: The entry date.\n    date: datetime.date\n\n    #: The entry hash.\n    entry_hash: str\n</code></pre>"},{"location":"api/#rustfava.core.accounts.AccountData","title":"<code>AccountData</code>  <code>dataclass</code>","text":"<p>Holds information about an account.</p> Source code in <code>src/rustfava/core/accounts.py</code> <pre><code>@dataclass\nclass AccountData:\n    \"\"\"Holds information about an account.\"\"\"\n\n    #: The date on which this account is closed (or datetime.date.max).\n    close_date: datetime.date | None = None\n\n    #: The metadata of the Open entry of this account.\n    meta: Meta = field(default_factory=dict)\n\n    #: Uptodate status. Is only computed if the account has a\n    #: \"fava-uptodate-indication\" meta attribute.\n    uptodate_status: Literal[\"green\", \"yellow\", \"red\"] | None = None\n\n    #: Balance directive if this account has an uptodate status.\n    balance_string: str | None = None\n\n    #: The last entry of the account (unless it is a close Entry)\n    last_entry: LastEntry | None = None\n</code></pre>"},{"location":"api/#rustfava.core.accounts.AccountDict","title":"<code>AccountDict</code>","text":"<p>               Bases: <code>FavaModule</code>, <code>dict[str, AccountData]</code></p> <p>Account info dictionary.</p> Source code in <code>src/rustfava/core/accounts.py</code> <pre><code>class AccountDict(FavaModule, dict[str, AccountData]):\n    \"\"\"Account info dictionary.\"\"\"\n\n    EMPTY = AccountData()\n\n    def __missing__(self, key: str) -&gt; AccountData:\n        return self.EMPTY\n\n    def setdefault(\n        self,\n        key: str,\n        _: AccountData | None = None,\n    ) -&gt; AccountData:\n        \"\"\"Get the account of the given name, insert one if it is missing.\"\"\"\n        if key not in self:\n            self[key] = AccountData()\n        return self[key]\n\n    def load_file(self) -&gt; None:  # noqa: D102\n        self.clear()\n        entries_by_account = group_entries_by_account(self.ledger.all_entries)\n        tree = Tree(self.ledger.all_entries)\n        for open_entry in self.ledger.all_entries_by_type.Open:\n            meta = open_entry.meta\n            account_data = self.setdefault(open_entry.account)\n            account_data.meta = meta\n\n            txn_postings = entries_by_account[open_entry.account]\n            last = get_last_entry(txn_postings)\n            if last is not None and not isinstance(last, Close):\n                account_data.last_entry = LastEntry(\n                    date=last.date,\n                    entry_hash=hash_entry(last),\n                )\n            if meta.get(\"fava-uptodate-indication\"):\n                account_data.uptodate_status = uptodate_status(txn_postings)\n                if account_data.uptodate_status != \"green\":\n                    account_data.balance_string = balance_string(\n                        tree.get(open_entry.account),\n                    )\n        for close in self.ledger.all_entries_by_type.Close:\n            self.setdefault(close.account).close_date = close.date\n\n    def all_balance_directives(self) -&gt; str:\n        \"\"\"Balance directives for all accounts.\"\"\"\n        return \"\".join(\n            account_details.balance_string\n            for account_details in self.values()\n            if account_details.balance_string\n        )\n</code></pre>"},{"location":"api/#rustfava.core.accounts.AccountDict.setdefault","title":"<code>setdefault(key, _=None)</code>","text":"<p>Get the account of the given name, insert one if it is missing.</p> Source code in <code>src/rustfava/core/accounts.py</code> <pre><code>def setdefault(\n    self,\n    key: str,\n    _: AccountData | None = None,\n) -&gt; AccountData:\n    \"\"\"Get the account of the given name, insert one if it is missing.\"\"\"\n    if key not in self:\n        self[key] = AccountData()\n    return self[key]\n</code></pre>"},{"location":"api/#rustfava.core.accounts.AccountDict.all_balance_directives","title":"<code>all_balance_directives()</code>","text":"<p>Balance directives for all accounts.</p> Source code in <code>src/rustfava/core/accounts.py</code> <pre><code>def all_balance_directives(self) -&gt; str:\n    \"\"\"Balance directives for all accounts.\"\"\"\n    return \"\".join(\n        account_details.balance_string\n        for account_details in self.values()\n        if account_details.balance_string\n    )\n</code></pre>"},{"location":"api/#rustfava.core.accounts.get_last_entry","title":"<code>get_last_entry(txn_postings)</code>","text":"<p>Last entry.</p> Source code in <code>src/rustfava/core/accounts.py</code> <pre><code>def get_last_entry(\n    txn_postings: Sequence[Directive | TransactionPosting],\n) -&gt; Directive | None:\n    \"\"\"Last entry.\"\"\"\n    for txn_posting in reversed(txn_postings):\n        if isinstance(txn_posting, TransactionPosting):\n            transaction = txn_posting.transaction\n            if transaction.flag != FLAG_UNREALIZED:\n                return transaction\n        else:\n            return txn_posting\n    return None\n</code></pre>"},{"location":"api/#rustfava.core.accounts.uptodate_status","title":"<code>uptodate_status(txn_postings)</code>","text":"<p>Status of the last balance or transaction.</p> <p>Parameters:</p> Name Type Description Default <code>txn_postings</code> <code>Sequence[Directive | TransactionPosting]</code> <p>The TransactionPosting for the account.</p> required <p>Returns:</p> Type Description <code>Literal['green', 'yellow', 'red'] | None</code> <p>A status string for the last balance or transaction of the account.</p> <code>Literal['green', 'yellow', 'red'] | None</code> <ul> <li>'green':  A balance check that passed.</li> </ul> <code>Literal['green', 'yellow', 'red'] | None</code> <ul> <li>'red':    A balance check that failed.</li> </ul> <code>Literal['green', 'yellow', 'red'] | None</code> <ul> <li>'yellow': Not a balance check.</li> </ul> Source code in <code>src/rustfava/core/accounts.py</code> <pre><code>def uptodate_status(\n    txn_postings: Sequence[Directive | TransactionPosting],\n) -&gt; Literal[\"green\", \"yellow\", \"red\"] | None:\n    \"\"\"Status of the last balance or transaction.\n\n    Args:\n        txn_postings: The TransactionPosting for the account.\n\n    Returns:\n        A status string for the last balance or transaction of the account.\n\n        - 'green':  A balance check that passed.\n        - 'red':    A balance check that failed.\n        - 'yellow': Not a balance check.\n    \"\"\"\n    for txn_posting in reversed(txn_postings):\n        if isinstance(txn_posting, Balance):\n            return \"red\" if txn_posting.diff_amount else \"green\"\n        if (\n            isinstance(txn_posting, TransactionPosting)\n            and txn_posting.transaction.flag != FLAG_UNREALIZED\n        ):\n            return \"yellow\"\n    return None\n</code></pre>"},{"location":"api/#rustfava.core.accounts.balance_string","title":"<code>balance_string(tree_node)</code>","text":"<p>Balance directive for the given account for today.</p> Source code in <code>src/rustfava/core/accounts.py</code> <pre><code>def balance_string(tree_node: TreeNode) -&gt; str:\n    \"\"\"Balance directive for the given account for today.\"\"\"\n    account = tree_node.name\n    today = str(local_today())\n    res = \"\"\n    for currency, number in UNITS.apply(tree_node.balance).items():\n        res += f\"{today} balance {account:&lt;28} {number:&gt;15} {currency}\\n\"\n    return res\n</code></pre>"},{"location":"api/#rustfava.core.attributes","title":"<code>attributes</code>","text":"<p>Attributes for auto-completion.</p>"},{"location":"api/#rustfava.core.attributes.AttributesModule","title":"<code>AttributesModule</code>","text":"<p>               Bases: <code>FavaModule</code></p> <p>Some attributes of the ledger (mostly for auto-completion).</p> Source code in <code>src/rustfava/core/attributes.py</code> <pre><code>class AttributesModule(FavaModule):\n    \"\"\"Some attributes of the ledger (mostly for auto-completion).\"\"\"\n\n    def __init__(self, ledger: RustfavaLedger) -&gt; None:\n        super().__init__(ledger)\n        self.accounts: Sequence[str] = []\n        self.currencies: Sequence[str] = []\n        self.payees: Sequence[str] = []\n        self.links: Sequence[str] = []\n        self.tags: Sequence[str] = []\n        self.years: Sequence[str] = []\n\n    def load_file(self) -&gt; None:  # noqa: D102\n        all_entries = self.ledger.all_entries\n\n        all_links = set()\n        all_tags = set()\n        for entry in all_entries:\n            links = getattr(entry, \"links\", None)\n            if links is not None:\n                all_links.update(links)\n            tags = getattr(entry, \"tags\", None)\n            if tags is not None:\n                all_tags.update(tags)\n        self.links = sorted(all_links)\n        self.tags = sorted(all_tags)\n\n        self.years = get_active_years(\n            all_entries,\n            self.ledger.fava_options.fiscal_year_end,\n        )\n\n        account_ranker = ExponentialDecayRanker(\n            sorted(self.ledger.accounts.keys()),\n        )\n        currency_ranker = ExponentialDecayRanker()\n        payee_ranker = ExponentialDecayRanker()\n\n        for txn in self.ledger.all_entries_by_type.Transaction:\n            if txn.payee:\n                payee_ranker.update(txn.payee, txn.date)\n            for posting in txn.postings:\n                account_ranker.update(posting.account, txn.date)\n                # Skip postings with missing units (can happen with parse errors)\n                if posting.units is not None:\n                    currency_ranker.update(posting.units.currency, txn.date)\n                if posting.cost and posting.cost.currency is not None:\n                    currency_ranker.update(posting.cost.currency, txn.date)\n\n        self.accounts = account_ranker.sort()\n        self.currencies = currency_ranker.sort()\n        self.payees = payee_ranker.sort()\n\n    def payee_accounts(self, payee: str) -&gt; Sequence[str]:\n        \"\"\"Rank accounts for the given payee.\"\"\"\n        account_ranker = ExponentialDecayRanker(self.accounts)\n        transactions = self.ledger.all_entries_by_type.Transaction\n        for txn in transactions:\n            if txn.payee == payee:\n                for posting in txn.postings:\n                    account_ranker.update(posting.account, txn.date)\n        return account_ranker.sort()\n\n    def payee_transaction(self, payee: str) -&gt; Transaction | None:\n        \"\"\"Get the last transaction for a payee.\"\"\"\n        transactions = self.ledger.all_entries_by_type.Transaction\n        for txn in reversed(transactions):\n            if txn.payee == payee:\n                return txn\n        return None\n\n    def narration_transaction(self, narration: str) -&gt; Transaction | None:\n        \"\"\"Get the last transaction for a narration.\"\"\"\n        transactions = self.ledger.all_entries_by_type.Transaction\n        for txn in reversed(transactions):\n            if txn.narration == narration:\n                return txn\n        return None\n\n    @property\n    def narrations(self) -&gt; Sequence[str]:\n        \"\"\"Get the narrations of all transactions.\"\"\"\n        narration_ranker = ExponentialDecayRanker()\n        for txn in self.ledger.all_entries_by_type.Transaction:\n            if txn.narration:\n                narration_ranker.update(txn.narration, txn.date)\n        return narration_ranker.sort()\n</code></pre>"},{"location":"api/#rustfava.core.attributes.AttributesModule.narrations","title":"<code>narrations</code>  <code>property</code>","text":"<p>Get the narrations of all transactions.</p>"},{"location":"api/#rustfava.core.attributes.AttributesModule.payee_accounts","title":"<code>payee_accounts(payee)</code>","text":"<p>Rank accounts for the given payee.</p> Source code in <code>src/rustfava/core/attributes.py</code> <pre><code>def payee_accounts(self, payee: str) -&gt; Sequence[str]:\n    \"\"\"Rank accounts for the given payee.\"\"\"\n    account_ranker = ExponentialDecayRanker(self.accounts)\n    transactions = self.ledger.all_entries_by_type.Transaction\n    for txn in transactions:\n        if txn.payee == payee:\n            for posting in txn.postings:\n                account_ranker.update(posting.account, txn.date)\n    return account_ranker.sort()\n</code></pre>"},{"location":"api/#rustfava.core.attributes.AttributesModule.payee_transaction","title":"<code>payee_transaction(payee)</code>","text":"<p>Get the last transaction for a payee.</p> Source code in <code>src/rustfava/core/attributes.py</code> <pre><code>def payee_transaction(self, payee: str) -&gt; Transaction | None:\n    \"\"\"Get the last transaction for a payee.\"\"\"\n    transactions = self.ledger.all_entries_by_type.Transaction\n    for txn in reversed(transactions):\n        if txn.payee == payee:\n            return txn\n    return None\n</code></pre>"},{"location":"api/#rustfava.core.attributes.AttributesModule.narration_transaction","title":"<code>narration_transaction(narration)</code>","text":"<p>Get the last transaction for a narration.</p> Source code in <code>src/rustfava/core/attributes.py</code> <pre><code>def narration_transaction(self, narration: str) -&gt; Transaction | None:\n    \"\"\"Get the last transaction for a narration.\"\"\"\n    transactions = self.ledger.all_entries_by_type.Transaction\n    for txn in reversed(transactions):\n        if txn.narration == narration:\n            return txn\n    return None\n</code></pre>"},{"location":"api/#rustfava.core.attributes.get_active_years","title":"<code>get_active_years(entries, fye)</code>","text":"<p>Return active years, with support for fiscal years.</p> <p>Parameters:</p> Name Type Description Default <code>entries</code> <code>Sequence[Directive]</code> <p>Beancount entries</p> required <code>fye</code> <code>FiscalYearEnd</code> <p>fiscal year end</p> required <p>Returns:</p> Type Description <code>list[str]</code> <p>A reverse sorted list of years or fiscal years that occur in the</p> <code>list[str]</code> <p>entries.</p> Source code in <code>src/rustfava/core/attributes.py</code> <pre><code>def get_active_years(\n    entries: Sequence[Directive],\n    fye: FiscalYearEnd,\n) -&gt; list[str]:\n    \"\"\"Return active years, with support for fiscal years.\n\n    Args:\n        entries: Beancount entries\n        fye: fiscal year end\n\n    Returns:\n        A reverse sorted list of years or fiscal years that occur in the\n        entries.\n    \"\"\"\n    years = []\n    if fye == END_OF_YEAR:\n        prev_year = None\n        for entry in entries:\n            year = entry.date.year\n            if year != prev_year:\n                prev_year = year\n                years.append(year)\n        return [f\"{year}\" for year in reversed(years)]\n    month = fye.month\n    day = fye.day\n    prev_year = None\n    for entry in entries:\n        date = entry.date\n        year = (\n            entry.date.year + 1\n            if date.month &gt; month or (date.month == month and date.day &gt; day)\n            else entry.date.year\n        )\n        if year != prev_year:\n            prev_year = year\n            years.append(year)\n    return [f\"FY{year}\" for year in reversed(years)]\n</code></pre>"},{"location":"api/#rustfava.core.budgets","title":"<code>budgets</code>","text":"<p>Parsing and computing budgets.</p>"},{"location":"api/#rustfava.core.budgets.BudgetDict","title":"<code>BudgetDict = dict[str, list[Budget]]</code>  <code>module-attribute</code>","text":"<p>A map of account names to lists of budget entries.</p>"},{"location":"api/#rustfava.core.budgets.Budget","title":"<code>Budget</code>","text":"<p>               Bases: <code>NamedTuple</code></p> <p>A budget entry.</p> Source code in <code>src/rustfava/core/budgets.py</code> <pre><code>class Budget(NamedTuple):\n    \"\"\"A budget entry.\"\"\"\n\n    account: str\n    date_start: datetime.date\n    period: Interval\n    number: Decimal\n    currency: str\n</code></pre>"},{"location":"api/#rustfava.core.budgets.BudgetError","title":"<code>BudgetError</code>  <code>dataclass</code>","text":"<p>               Bases: <code>BeancountError</code></p> <p>Error with a budget.</p> Source code in <code>src/rustfava/core/budgets.py</code> <pre><code>class BudgetError(BeancountError):\n    \"\"\"Error with a budget.\"\"\"\n</code></pre>"},{"location":"api/#rustfava.core.budgets.BudgetModule","title":"<code>BudgetModule</code>","text":"<p>               Bases: <code>FavaModule</code></p> <p>Parses budget entries.</p> Source code in <code>src/rustfava/core/budgets.py</code> <pre><code>class BudgetModule(FavaModule):\n    \"\"\"Parses budget entries.\"\"\"\n\n    def __init__(self, ledger: RustfavaLedger) -&gt; None:\n        super().__init__(ledger)\n        self._budget_entries: BudgetDict = {}\n        self.errors: Sequence[BudgetError] = []\n\n    def load_file(self) -&gt; None:  # noqa: D102\n        self._budget_entries, self.errors = parse_budgets(\n            self.ledger.all_entries_by_type.Custom,\n        )\n\n    def calculate(\n        self,\n        account: str,\n        begin_date: datetime.date,\n        end_date: datetime.date,\n    ) -&gt; Mapping[str, Decimal]:\n        \"\"\"Calculate the budget for an account in an interval.\"\"\"\n        return calculate_budget(\n            self._budget_entries,\n            account,\n            begin_date,\n            end_date,\n        )\n\n    def calculate_children(\n        self,\n        account: str,\n        begin_date: datetime.date,\n        end_date: datetime.date,\n    ) -&gt; Mapping[str, Decimal]:\n        \"\"\"Calculate the budget for an account including its children.\"\"\"\n        return calculate_budget_children(\n            self._budget_entries,\n            account,\n            begin_date,\n            end_date,\n        )\n</code></pre>"},{"location":"api/#rustfava.core.budgets.BudgetModule.calculate","title":"<code>calculate(account, begin_date, end_date)</code>","text":"<p>Calculate the budget for an account in an interval.</p> Source code in <code>src/rustfava/core/budgets.py</code> <pre><code>def calculate(\n    self,\n    account: str,\n    begin_date: datetime.date,\n    end_date: datetime.date,\n) -&gt; Mapping[str, Decimal]:\n    \"\"\"Calculate the budget for an account in an interval.\"\"\"\n    return calculate_budget(\n        self._budget_entries,\n        account,\n        begin_date,\n        end_date,\n    )\n</code></pre>"},{"location":"api/#rustfava.core.budgets.BudgetModule.calculate_children","title":"<code>calculate_children(account, begin_date, end_date)</code>","text":"<p>Calculate the budget for an account including its children.</p> Source code in <code>src/rustfava/core/budgets.py</code> <pre><code>def calculate_children(\n    self,\n    account: str,\n    begin_date: datetime.date,\n    end_date: datetime.date,\n) -&gt; Mapping[str, Decimal]:\n    \"\"\"Calculate the budget for an account including its children.\"\"\"\n    return calculate_budget_children(\n        self._budget_entries,\n        account,\n        begin_date,\n        end_date,\n    )\n</code></pre>"},{"location":"api/#rustfava.core.budgets.parse_budgets","title":"<code>parse_budgets(custom_entries)</code>","text":"<p>Parse budget directives from custom entries.</p> <p>Parameters:</p> Name Type Description Default <code>custom_entries</code> <code>Sequence[Custom]</code> <p>the Custom entries to parse budgets from.</p> required <p>Returns:</p> Type Description <code>tuple[BudgetDict, Sequence[BudgetError]]</code> <p>A dict of accounts to lists of budgets.</p> Example <p>2015-04-09 custom \"budget\" Expenses:Books \"monthly\" 20.00 EUR</p> Source code in <code>src/rustfava/core/budgets.py</code> <pre><code>def parse_budgets(\n    custom_entries: Sequence[Custom],\n) -&gt; tuple[BudgetDict, Sequence[BudgetError]]:\n    \"\"\"Parse budget directives from custom entries.\n\n    Args:\n        custom_entries: the Custom entries to parse budgets from.\n\n    Returns:\n        A dict of accounts to lists of budgets.\n\n    Example:\n        2015-04-09 custom \"budget\" Expenses:Books \"monthly\" 20.00 EUR\n    \"\"\"\n    budgets: BudgetDict = defaultdict(list)\n    errors = []\n\n    for entry in (entry for entry in custom_entries if entry.type == \"budget\"):\n        try:\n            interval = INTERVALS.get(str(entry.values[1].value).lower())\n            if not interval:\n                errors.append(\n                    BudgetError(\n                        entry.meta,\n                        \"Invalid interval for budget entry\",\n                        entry,\n                    ),\n                )\n                continue\n            budget = Budget(\n                entry.values[0].value,\n                entry.date,\n                interval,\n                entry.values[2].value.number,\n                entry.values[2].value.currency,\n            )\n            budgets[budget.account].append(budget)\n        except (IndexError, TypeError):\n            errors.append(\n                BudgetError(entry.meta, \"Failed to parse budget entry\", entry),\n            )\n\n    return budgets, errors\n</code></pre>"},{"location":"api/#rustfava.core.budgets.calculate_budget","title":"<code>calculate_budget(budgets, account, date_from, date_to)</code>","text":"<p>Calculate budget for an account.</p> <p>Parameters:</p> Name Type Description Default <code>budgets</code> <code>BudgetDict</code> <p>A list of :class:<code>Budget</code> entries.</p> required <code>account</code> <code>str</code> <p>An account name.</p> required <code>date_from</code> <code>date</code> <p>Starting date.</p> required <code>date_to</code> <code>date</code> <p>End date (exclusive).</p> required <p>Returns:</p> Type Description <code>Mapping[str, Decimal]</code> <p>A dictionary of currency to Decimal with the budget for the</p> <code>Mapping[str, Decimal]</code> <p>specified account and period.</p> Source code in <code>src/rustfava/core/budgets.py</code> <pre><code>def calculate_budget(\n    budgets: BudgetDict,\n    account: str,\n    date_from: datetime.date,\n    date_to: datetime.date,\n) -&gt; Mapping[str, Decimal]:\n    \"\"\"Calculate budget for an account.\n\n    Args:\n        budgets: A list of :class:`Budget` entries.\n        account: An account name.\n        date_from: Starting date.\n        date_to: End date (exclusive).\n\n    Returns:\n        A dictionary of currency to Decimal with the budget for the\n        specified account and period.\n    \"\"\"\n    budget_list = budgets.get(account, None)\n    if budget_list is None:\n        return {}\n\n    currency_dict: dict[str, Decimal] = defaultdict(Decimal)\n\n    for day in days_in_daterange(date_from, date_to):\n        matches = _matching_budgets(budget_list, day)\n        for budget in matches.values():\n            days_in_period = budget.period.number_of_days(day)\n            currency_dict[budget.currency] += budget.number / days_in_period\n    return dict(currency_dict)\n</code></pre>"},{"location":"api/#rustfava.core.budgets.calculate_budget_children","title":"<code>calculate_budget_children(budgets, account, date_from, date_to)</code>","text":"<p>Calculate budget for an account including budgets of its children.</p> <p>Parameters:</p> Name Type Description Default <code>budgets</code> <code>BudgetDict</code> <p>A list of :class:<code>Budget</code> entries.</p> required <code>account</code> <code>str</code> <p>An account name.</p> required <code>date_from</code> <code>date</code> <p>Starting date.</p> required <code>date_to</code> <code>date</code> <p>End date (exclusive).</p> required <p>Returns:</p> Type Description <code>Mapping[str, Decimal]</code> <p>A dictionary of currency to Decimal with the budget for the</p> <code>Mapping[str, Decimal]</code> <p>specified account and period.</p> Source code in <code>src/rustfava/core/budgets.py</code> <pre><code>def calculate_budget_children(\n    budgets: BudgetDict,\n    account: str,\n    date_from: datetime.date,\n    date_to: datetime.date,\n) -&gt; Mapping[str, Decimal]:\n    \"\"\"Calculate budget for an account including budgets of its children.\n\n    Args:\n        budgets: A list of :class:`Budget` entries.\n        account: An account name.\n        date_from: Starting date.\n        date_to: End date (exclusive).\n\n    Returns:\n        A dictionary of currency to Decimal with the budget for the\n        specified account and period.\n    \"\"\"\n    currency_dict: dict[str, Decimal] = Counter()  # type: ignore[assignment]\n\n    for child in budgets:\n        if child.startswith(account):\n            currency_dict.update(\n                calculate_budget(budgets, child, date_from, date_to),\n            )\n    return dict(currency_dict)\n</code></pre>"},{"location":"api/#rustfava.core.charts","title":"<code>charts</code>","text":"<p>Provide data suitable for rustfava's charts.</p>"},{"location":"api/#rustfava.core.charts.RustfavaJSONProvider","title":"<code>RustfavaJSONProvider</code>","text":"<p>               Bases: <code>JSONProvider</code></p> <p>Use custom JSON encoder and decoder.</p> Source code in <code>src/rustfava/core/charts.py</code> <pre><code>class RustfavaJSONProvider(JSONProvider):\n    \"\"\"Use custom JSON encoder and decoder.\"\"\"\n\n    def dumps(self, obj: Any, **_kwargs: Any) -&gt; str:  # noqa: D102\n        return json.dumps(\n            obj, sort_keys=True, separators=(\",\", \":\"), default=_json_default\n        )\n\n    def loads(self, s: str | bytes, **_kwargs: Any) -&gt; Any:  # noqa: D102\n        return json.loads(s)\n</code></pre>"},{"location":"api/#rustfava.core.charts.DateAndBalance","title":"<code>DateAndBalance</code>  <code>dataclass</code>","text":"<p>Balance at a date.</p> Source code in <code>src/rustfava/core/charts.py</code> <pre><code>@dataclass(frozen=True)\nclass DateAndBalance:\n    \"\"\"Balance at a date.\"\"\"\n\n    date: date\n    balance: SimpleCounterInventory\n</code></pre>"},{"location":"api/#rustfava.core.charts.DateAndBalanceWithBudget","title":"<code>DateAndBalanceWithBudget</code>  <code>dataclass</code>","text":"<p>Balance at a date with a budget.</p> Source code in <code>src/rustfava/core/charts.py</code> <pre><code>@dataclass(frozen=True)\nclass DateAndBalanceWithBudget:\n    \"\"\"Balance at a date with a budget.\"\"\"\n\n    date: date\n    balance: SimpleCounterInventory\n    account_balances: Mapping[str, SimpleCounterInventory]\n    budgets: Mapping[str, Decimal]\n</code></pre>"},{"location":"api/#rustfava.core.charts.ChartModule","title":"<code>ChartModule</code>","text":"<p>               Bases: <code>FavaModule</code></p> <p>Return data for the various charts in rustfava.</p> Source code in <code>src/rustfava/core/charts.py</code> <pre><code>class ChartModule(FavaModule):\n    \"\"\"Return data for the various charts in rustfava.\"\"\"\n\n    def hierarchy(\n        self,\n        filtered: FilteredLedger,\n        account_name: str,\n        conversion: Conversion,\n    ) -&gt; SerialisedTreeNode:\n        \"\"\"Render an account tree.\"\"\"\n        tree = filtered.root_tree\n        return tree.get(account_name).serialise(\n            conversion, self.ledger.prices, filtered.end_date\n        )\n\n    @listify\n    def interval_totals(\n        self,\n        filtered: FilteredLedger,\n        interval: Interval,\n        accounts: str | tuple[str, ...],\n        conversion: str | Conversion,\n        *,\n        invert: bool = False,\n    ) -&gt; Iterable[DateAndBalanceWithBudget]:\n        \"\"\"Render totals for account (or accounts) in the intervals.\n\n        Args:\n            filtered: The filtered ledger.\n            interval: An interval.\n            accounts: A single account (str) or a tuple of accounts.\n            conversion: The conversion to use.\n            invert: invert all numbers.\n\n        Yields:\n            The balances and budgets for the intervals.\n        \"\"\"\n        conv = conversion_from_str(conversion)\n        prices = self.ledger.prices\n\n        # limit the bar charts to 100 intervals\n        intervals = filtered.interval_ranges(interval)[-100:]\n\n        for date_range in intervals:\n            inventory = CounterInventory()\n            entries = slice_entry_dates(\n                filtered.entries, date_range.begin, date_range.end\n            )\n            account_inventories: dict[str, CounterInventory] = defaultdict(\n                CounterInventory,\n            )\n            for entry in entries:\n                for posting in getattr(entry, \"postings\", []):\n                    if posting.account.startswith(accounts):\n                        account_inventories[posting.account].add_position(\n                            posting,\n                        )\n                        inventory.add_position(posting)\n            balance = conv.apply(\n                inventory,\n                prices,\n                date_range.end_inclusive,\n            )\n            account_balances = {\n                account: conv.apply(\n                    acct_value,\n                    prices,\n                    date_range.end_inclusive,\n                )\n                for account, acct_value in account_inventories.items()\n            }\n            budgets = (\n                self.ledger.budgets.calculate_children(\n                    accounts,\n                    date_range.begin,\n                    date_range.end,\n                )\n                if isinstance(accounts, str)\n                else {}\n            )\n\n            if invert:\n                balance = -balance\n                budgets = {k: -v for k, v in budgets.items()}\n                account_balances = {k: -v for k, v in account_balances.items()}\n\n            yield DateAndBalanceWithBudget(\n                date_range.end_inclusive,\n                balance,\n                account_balances,\n                budgets,\n            )\n\n    @listify\n    def linechart(\n        self,\n        filtered: FilteredLedger,\n        account_name: str,\n        conversion: str | Conversion,\n    ) -&gt; Iterable[DateAndBalance]:\n        \"\"\"Get the balance of an account as a line chart.\n\n        Args:\n            filtered: The filtered ledger.\n            account_name: A string.\n            conversion: The conversion to use.\n\n        Yields:\n            Dicts for all dates on which the balance of the given\n            account has changed containing the balance (in units) of the\n            account at that date.\n        \"\"\"\n        conv = conversion_from_str(conversion)\n\n        def _balances() -&gt; Iterable[tuple[date, CounterInventory]]:\n            last_date = None\n            running_balance = CounterInventory()\n            is_child_account = account_tester(account_name, with_children=True)\n\n            for entry in filtered.entries:\n                for posting in getattr(entry, \"postings\", []):\n                    if is_child_account(posting.account):\n                        new_date = entry.date\n                        if last_date is not None and new_date &gt; last_date:\n                            yield (last_date, running_balance)\n                        running_balance.add_position(posting)\n                        last_date = new_date\n\n            if last_date is not None:\n                yield (last_date, running_balance)\n\n        # When the balance for a commodity just went to zero, it will be\n        # missing from the 'balance' so keep track of currencies that last had\n        # a balance.\n        last_currencies = None\n        prices = self.ledger.prices\n\n        for d, running_bal in _balances():\n            balance = conv.apply(running_bal, prices, d)\n            currencies = set(balance.keys())\n            if last_currencies:\n                for currency in last_currencies - currencies:\n                    balance[currency] = ZERO\n            last_currencies = currencies\n            yield DateAndBalance(d, balance)\n\n    @listify\n    def net_worth(\n        self,\n        filtered: FilteredLedger,\n        interval: Interval,\n        conversion: str | Conversion,\n    ) -&gt; Iterable[DateAndBalance]:\n        \"\"\"Compute net worth.\n\n        Args:\n            filtered: The filtered ledger.\n            interval: A string for the interval.\n            conversion: The conversion to use.\n\n        Yields:\n            Dicts for all ends of the given interval containing the\n            net worth (Assets + Liabilities) separately converted to all\n            operating currencies.\n        \"\"\"\n        conv = conversion_from_str(conversion)\n        transactions = (\n            entry\n            for entry in filtered.entries\n            if (\n                isinstance(entry, Transaction)\n                and entry.flag != FLAG_UNREALIZED\n            )\n        )\n\n        types = (\n            self.ledger.options[\"name_assets\"],\n            self.ledger.options[\"name_liabilities\"],\n        )\n\n        txn = next(transactions, None)\n        inventory = CounterInventory()\n\n        prices = self.ledger.prices\n        for date_range in filtered.interval_ranges(interval):\n            while txn and txn.date &lt; date_range.end:\n                for posting in txn.postings:\n                    if posting.account.startswith(types):\n                        inventory.add_position(posting)\n                txn = next(transactions, None)\n            yield DateAndBalance(\n                date_range.end_inclusive,\n                conv.apply(\n                    inventory,\n                    prices,\n                    date_range.end_inclusive,\n                ),\n            )\n</code></pre>"},{"location":"api/#rustfava.core.charts.ChartModule.hierarchy","title":"<code>hierarchy(filtered, account_name, conversion)</code>","text":"<p>Render an account tree.</p> Source code in <code>src/rustfava/core/charts.py</code> <pre><code>def hierarchy(\n    self,\n    filtered: FilteredLedger,\n    account_name: str,\n    conversion: Conversion,\n) -&gt; SerialisedTreeNode:\n    \"\"\"Render an account tree.\"\"\"\n    tree = filtered.root_tree\n    return tree.get(account_name).serialise(\n        conversion, self.ledger.prices, filtered.end_date\n    )\n</code></pre>"},{"location":"api/#rustfava.core.charts.ChartModule.interval_totals","title":"<code>interval_totals(filtered, interval, accounts, conversion, *, invert=False)</code>","text":"<p>Render totals for account (or accounts) in the intervals.</p> <p>Parameters:</p> Name Type Description Default <code>filtered</code> <code>FilteredLedger</code> <p>The filtered ledger.</p> required <code>interval</code> <code>Interval</code> <p>An interval.</p> required <code>accounts</code> <code>str | tuple[str, ...]</code> <p>A single account (str) or a tuple of accounts.</p> required <code>conversion</code> <code>str | Conversion</code> <p>The conversion to use.</p> required <code>invert</code> <code>bool</code> <p>invert all numbers.</p> <code>False</code> <p>Yields:</p> Type Description <code>Iterable[DateAndBalanceWithBudget]</code> <p>The balances and budgets for the intervals.</p> Source code in <code>src/rustfava/core/charts.py</code> <pre><code>@listify\ndef interval_totals(\n    self,\n    filtered: FilteredLedger,\n    interval: Interval,\n    accounts: str | tuple[str, ...],\n    conversion: str | Conversion,\n    *,\n    invert: bool = False,\n) -&gt; Iterable[DateAndBalanceWithBudget]:\n    \"\"\"Render totals for account (or accounts) in the intervals.\n\n    Args:\n        filtered: The filtered ledger.\n        interval: An interval.\n        accounts: A single account (str) or a tuple of accounts.\n        conversion: The conversion to use.\n        invert: invert all numbers.\n\n    Yields:\n        The balances and budgets for the intervals.\n    \"\"\"\n    conv = conversion_from_str(conversion)\n    prices = self.ledger.prices\n\n    # limit the bar charts to 100 intervals\n    intervals = filtered.interval_ranges(interval)[-100:]\n\n    for date_range in intervals:\n        inventory = CounterInventory()\n        entries = slice_entry_dates(\n            filtered.entries, date_range.begin, date_range.end\n        )\n        account_inventories: dict[str, CounterInventory] = defaultdict(\n            CounterInventory,\n        )\n        for entry in entries:\n            for posting in getattr(entry, \"postings\", []):\n                if posting.account.startswith(accounts):\n                    account_inventories[posting.account].add_position(\n                        posting,\n                    )\n                    inventory.add_position(posting)\n        balance = conv.apply(\n            inventory,\n            prices,\n            date_range.end_inclusive,\n        )\n        account_balances = {\n            account: conv.apply(\n                acct_value,\n                prices,\n                date_range.end_inclusive,\n            )\n            for account, acct_value in account_inventories.items()\n        }\n        budgets = (\n            self.ledger.budgets.calculate_children(\n                accounts,\n                date_range.begin,\n                date_range.end,\n            )\n            if isinstance(accounts, str)\n            else {}\n        )\n\n        if invert:\n            balance = -balance\n            budgets = {k: -v for k, v in budgets.items()}\n            account_balances = {k: -v for k, v in account_balances.items()}\n\n        yield DateAndBalanceWithBudget(\n            date_range.end_inclusive,\n            balance,\n            account_balances,\n            budgets,\n        )\n</code></pre>"},{"location":"api/#rustfava.core.charts.ChartModule.linechart","title":"<code>linechart(filtered, account_name, conversion)</code>","text":"<p>Get the balance of an account as a line chart.</p> <p>Parameters:</p> Name Type Description Default <code>filtered</code> <code>FilteredLedger</code> <p>The filtered ledger.</p> required <code>account_name</code> <code>str</code> <p>A string.</p> required <code>conversion</code> <code>str | Conversion</code> <p>The conversion to use.</p> required <p>Yields:</p> Type Description <code>Iterable[DateAndBalance]</code> <p>Dicts for all dates on which the balance of the given</p> <code>Iterable[DateAndBalance]</code> <p>account has changed containing the balance (in units) of the</p> <code>Iterable[DateAndBalance]</code> <p>account at that date.</p> Source code in <code>src/rustfava/core/charts.py</code> <pre><code>@listify\ndef linechart(\n    self,\n    filtered: FilteredLedger,\n    account_name: str,\n    conversion: str | Conversion,\n) -&gt; Iterable[DateAndBalance]:\n    \"\"\"Get the balance of an account as a line chart.\n\n    Args:\n        filtered: The filtered ledger.\n        account_name: A string.\n        conversion: The conversion to use.\n\n    Yields:\n        Dicts for all dates on which the balance of the given\n        account has changed containing the balance (in units) of the\n        account at that date.\n    \"\"\"\n    conv = conversion_from_str(conversion)\n\n    def _balances() -&gt; Iterable[tuple[date, CounterInventory]]:\n        last_date = None\n        running_balance = CounterInventory()\n        is_child_account = account_tester(account_name, with_children=True)\n\n        for entry in filtered.entries:\n            for posting in getattr(entry, \"postings\", []):\n                if is_child_account(posting.account):\n                    new_date = entry.date\n                    if last_date is not None and new_date &gt; last_date:\n                        yield (last_date, running_balance)\n                    running_balance.add_position(posting)\n                    last_date = new_date\n\n        if last_date is not None:\n            yield (last_date, running_balance)\n\n    # When the balance for a commodity just went to zero, it will be\n    # missing from the 'balance' so keep track of currencies that last had\n    # a balance.\n    last_currencies = None\n    prices = self.ledger.prices\n\n    for d, running_bal in _balances():\n        balance = conv.apply(running_bal, prices, d)\n        currencies = set(balance.keys())\n        if last_currencies:\n            for currency in last_currencies - currencies:\n                balance[currency] = ZERO\n        last_currencies = currencies\n        yield DateAndBalance(d, balance)\n</code></pre>"},{"location":"api/#rustfava.core.charts.ChartModule.net_worth","title":"<code>net_worth(filtered, interval, conversion)</code>","text":"<p>Compute net worth.</p> <p>Parameters:</p> Name Type Description Default <code>filtered</code> <code>FilteredLedger</code> <p>The filtered ledger.</p> required <code>interval</code> <code>Interval</code> <p>A string for the interval.</p> required <code>conversion</code> <code>str | Conversion</code> <p>The conversion to use.</p> required <p>Yields:</p> Type Description <code>Iterable[DateAndBalance]</code> <p>Dicts for all ends of the given interval containing the</p> <code>Iterable[DateAndBalance]</code> <p>net worth (Assets + Liabilities) separately converted to all</p> <code>Iterable[DateAndBalance]</code> <p>operating currencies.</p> Source code in <code>src/rustfava/core/charts.py</code> <pre><code>@listify\ndef net_worth(\n    self,\n    filtered: FilteredLedger,\n    interval: Interval,\n    conversion: str | Conversion,\n) -&gt; Iterable[DateAndBalance]:\n    \"\"\"Compute net worth.\n\n    Args:\n        filtered: The filtered ledger.\n        interval: A string for the interval.\n        conversion: The conversion to use.\n\n    Yields:\n        Dicts for all ends of the given interval containing the\n        net worth (Assets + Liabilities) separately converted to all\n        operating currencies.\n    \"\"\"\n    conv = conversion_from_str(conversion)\n    transactions = (\n        entry\n        for entry in filtered.entries\n        if (\n            isinstance(entry, Transaction)\n            and entry.flag != FLAG_UNREALIZED\n        )\n    )\n\n    types = (\n        self.ledger.options[\"name_assets\"],\n        self.ledger.options[\"name_liabilities\"],\n    )\n\n    txn = next(transactions, None)\n    inventory = CounterInventory()\n\n    prices = self.ledger.prices\n    for date_range in filtered.interval_ranges(interval):\n        while txn and txn.date &lt; date_range.end:\n            for posting in txn.postings:\n                if posting.account.startswith(types):\n                    inventory.add_position(posting)\n            txn = next(transactions, None)\n        yield DateAndBalance(\n            date_range.end_inclusive,\n            conv.apply(\n                inventory,\n                prices,\n                date_range.end_inclusive,\n            ),\n        )\n</code></pre>"},{"location":"api/#rustfava.core.charts.dumps","title":"<code>dumps(obj, **_kwargs)</code>","text":"<p>Dump as a JSON string.</p> Source code in <code>src/rustfava/core/charts.py</code> <pre><code>def dumps(obj: Any, **_kwargs: Any) -&gt; str:\n    \"\"\"Dump as a JSON string.\"\"\"\n    return json.dumps(\n        obj, sort_keys=True, separators=(\",\", \":\"), default=_json_default\n    )\n</code></pre>"},{"location":"api/#rustfava.core.charts.loads","title":"<code>loads(s)</code>","text":"<p>Load a JSON string.</p> Source code in <code>src/rustfava/core/charts.py</code> <pre><code>def loads(s: str | bytes) -&gt; Any:\n    \"\"\"Load a JSON string.\"\"\"\n    return json.loads(s)\n</code></pre>"},{"location":"api/#rustfava.core.commodities","title":"<code>commodities</code>","text":"<p>Attributes for auto-completion.</p>"},{"location":"api/#rustfava.core.commodities.CommoditiesModule","title":"<code>CommoditiesModule</code>","text":"<p>               Bases: <code>FavaModule</code></p> <p>Details about the currencies and commodities.</p> Source code in <code>src/rustfava/core/commodities.py</code> <pre><code>class CommoditiesModule(FavaModule):\n    \"\"\"Details about the currencies and commodities.\"\"\"\n\n    def __init__(self, ledger: RustfavaLedger) -&gt; None:\n        super().__init__(ledger)\n        self.names: dict[str, str] = {}\n        self.precisions: dict[str, int] = {}\n\n    def load_file(self) -&gt; None:  # noqa: D102\n        self.names = {}\n        self.precisions = {}\n        for commodity in self.ledger.all_entries_by_type.Commodity:\n            name = commodity.meta.get(\"name\")\n            if name:\n                self.names[commodity.currency] = str(name)\n            precision = commodity.meta.get(\"precision\")\n            if isinstance(precision, (str, int, Decimal)):\n                with suppress(ValueError):\n                    self.precisions[commodity.currency] = int(precision)\n\n    def name(self, commodity: str) -&gt; str:\n        \"\"\"Get the name of a commodity (or the commodity itself if not set).\"\"\"\n        return self.names.get(commodity, commodity)\n</code></pre>"},{"location":"api/#rustfava.core.commodities.CommoditiesModule.name","title":"<code>name(commodity)</code>","text":"<p>Get the name of a commodity (or the commodity itself if not set).</p> Source code in <code>src/rustfava/core/commodities.py</code> <pre><code>def name(self, commodity: str) -&gt; str:\n    \"\"\"Get the name of a commodity (or the commodity itself if not set).\"\"\"\n    return self.names.get(commodity, commodity)\n</code></pre>"},{"location":"api/#rustfava.core.conversion","title":"<code>conversion</code>","text":"<p>Commodity conversion helpers for Fava.</p> <p>All functions in this module will be automatically added as template filters.</p>"},{"location":"api/#rustfava.core.conversion.Conversion","title":"<code>Conversion</code>","text":"<p>               Bases: <code>ABC</code></p> <p>A conversion.</p> Source code in <code>src/rustfava/core/conversion.py</code> <pre><code>class Conversion(ABC):\n    \"\"\"A conversion.\"\"\"\n\n    @abstractmethod\n    def apply(\n        self,\n        inventory: CounterInventory,\n        prices: RustfavaPriceMap,\n        date: datetime.date | None = None,\n    ) -&gt; SimpleCounterInventory:\n        \"\"\"Apply the conversion to an inventory (CounterInventory).\"\"\"\n</code></pre>"},{"location":"api/#rustfava.core.conversion.Conversion.apply","title":"<code>apply(inventory, prices, date=None)</code>  <code>abstractmethod</code>","text":"<p>Apply the conversion to an inventory (CounterInventory).</p> Source code in <code>src/rustfava/core/conversion.py</code> <pre><code>@abstractmethod\ndef apply(\n    self,\n    inventory: CounterInventory,\n    prices: RustfavaPriceMap,\n    date: datetime.date | None = None,\n) -&gt; SimpleCounterInventory:\n    \"\"\"Apply the conversion to an inventory (CounterInventory).\"\"\"\n</code></pre>"},{"location":"api/#rustfava.core.conversion.get_cost","title":"<code>get_cost(pos)</code>","text":"<p>Return the total cost of a Position.</p> Source code in <code>src/rustfava/core/conversion.py</code> <pre><code>def get_cost(pos: Position) -&gt; Amount:\n    \"\"\"Return the total cost of a Position.\"\"\"\n    cost_ = pos.cost\n    return (\n        _Amount(cost_.number * pos.units.number, cost_.currency)\n        if cost_ is not None\n        else pos.units\n    )\n</code></pre>"},{"location":"api/#rustfava.core.conversion.get_market_value","title":"<code>get_market_value(pos, prices, date=None)</code>","text":"<p>Get the market value of a Position.</p> <p>This differs from the convert.get_value function in Beancount by returning the cost value if no price can be found.</p> <p>Parameters:</p> Name Type Description Default <code>pos</code> <code>Position</code> <p>A Position.</p> required <code>prices</code> <code>RustfavaPriceMap</code> <p>A rustfavaPriceMap</p> required <code>date</code> <code>date | None</code> <p>A datetime.date instance to evaluate the value at, or None.</p> <code>None</code> <p>Returns:</p> Type Description <code>Amount</code> <p>An Amount, with value converted or if the conversion failed just the</p> <code>Amount</code> <p>cost value (or the units if the position has no cost).</p> Source code in <code>src/rustfava/core/conversion.py</code> <pre><code>def get_market_value(\n    pos: Position,\n    prices: RustfavaPriceMap,\n    date: datetime.date | None = None,\n) -&gt; Amount:\n    \"\"\"Get the market value of a Position.\n\n    This differs from the convert.get_value function in Beancount by returning\n    the cost value if no price can be found.\n\n    Args:\n        pos: A Position.\n        prices: A rustfavaPriceMap\n        date: A datetime.date instance to evaluate the value at, or None.\n\n    Returns:\n        An Amount, with value converted or if the conversion failed just the\n        cost value (or the units if the position has no cost).\n    \"\"\"\n    units_ = pos.units\n    cost_ = pos.cost\n\n    if cost_ is not None:\n        value_currency = cost_.currency\n        base_quote = (units_.currency, value_currency)\n        price_number = prices.get_price(base_quote, date)\n        if price_number is not None:\n            return _Amount(\n                units_.number * price_number,\n                value_currency,\n            )\n        return _Amount(units_.number * cost_.number, value_currency)\n    return units_\n</code></pre>"},{"location":"api/#rustfava.core.conversion.convert_position","title":"<code>convert_position(pos, target_currency, prices, date=None)</code>","text":"<p>Get the value of a Position in a particular currency.</p> <p>Parameters:</p> Name Type Description Default <code>pos</code> <code>Position</code> <p>A Position.</p> required <code>target_currency</code> <code>str</code> <p>The target currency to convert to.</p> required <code>prices</code> <code>RustfavaPriceMap</code> <p>A rustfavaPriceMap</p> required <code>date</code> <code>date | None</code> <p>A datetime.date instance to evaluate the value at, or None.</p> <code>None</code> <p>Returns:</p> Type Description <code>Amount</code> <p>An Amount, with value converted or if the conversion failed just the</p> <code>Amount</code> <p>cost value (or the units if the position has no cost).</p> Source code in <code>src/rustfava/core/conversion.py</code> <pre><code>def convert_position(\n    pos: Position,\n    target_currency: str,\n    prices: RustfavaPriceMap,\n    date: datetime.date | None = None,\n) -&gt; Amount:\n    \"\"\"Get the value of a Position in a particular currency.\n\n    Args:\n        pos: A Position.\n        target_currency: The target currency to convert to.\n        prices: A rustfavaPriceMap\n        date: A datetime.date instance to evaluate the value at, or None.\n\n    Returns:\n        An Amount, with value converted or if the conversion failed just the\n        cost value (or the units if the position has no cost).\n    \"\"\"\n    units_ = pos.units\n\n    # try the direct conversion\n    base_quote = (units_.currency, target_currency)\n    price_number = prices.get_price(base_quote, date)\n    if price_number is not None:\n        return _Amount(units_.number * price_number, target_currency)\n\n    cost_ = pos.cost\n    if cost_ is not None:\n        cost_currency = cost_.currency\n        if cost_currency != target_currency:\n            base_quote1 = (units_.currency, cost_currency)\n            rate1 = prices.get_price(base_quote1, date)\n            if rate1 is not None:\n                base_quote2 = (cost_currency, target_currency)\n                rate2 = prices.get_price(base_quote2, date)\n                if rate2 is not None:\n                    return _Amount(\n                        units_.number * rate1 * rate2,\n                        target_currency,\n                    )\n    return units_\n</code></pre>"},{"location":"api/#rustfava.core.conversion.conversion_from_str","title":"<code>conversion_from_str(value)</code>","text":"<p>Parse a conversion string.</p> Source code in <code>src/rustfava/core/conversion.py</code> <pre><code>def conversion_from_str(value: str | Conversion) -&gt; Conversion:\n    \"\"\"Parse a conversion string.\"\"\"\n    if not isinstance(value, str):\n        return value\n    if value == \"at_cost\":\n        return AT_COST\n    if value == \"at_value\":\n        return AT_VALUE\n    if value == \"units\":\n        return UNITS\n\n    return _CurrencyConversion(value)\n</code></pre>"},{"location":"api/#rustfava.core.conversion.cost_or_value","title":"<code>cost_or_value(inventory, conversion, prices, date=None)</code>","text":"<p>Get the cost or value of an inventory.</p> Source code in <code>src/rustfava/core/conversion.py</code> <pre><code>def cost_or_value(\n    inventory: CounterInventory,\n    conversion: str | Conversion,\n    prices: RustfavaPriceMap,\n    date: datetime.date | None = None,\n) -&gt; SimpleCounterInventory:\n    \"\"\"Get the cost or value of an inventory.\"\"\"\n    conversion = conversion_from_str(conversion)\n    return conversion.apply(inventory, prices, date)\n</code></pre>"},{"location":"api/#rustfava.core.documents","title":"<code>documents</code>","text":"<p>Document path related helpers.</p>"},{"location":"api/#rustfava.core.documents.NotADocumentsFolderError","title":"<code>NotADocumentsFolderError</code>","text":"<p>               Bases: <code>RustfavaAPIError</code></p> <p>Not a documents folder.</p> Source code in <code>src/rustfava/core/documents.py</code> <pre><code>class NotADocumentsFolderError(RustfavaAPIError):\n    \"\"\"Not a documents folder.\"\"\"\n\n    def __init__(self, folder: str) -&gt; None:\n        super().__init__(f\"Not a documents folder: {folder}.\")\n</code></pre>"},{"location":"api/#rustfava.core.documents.NotAValidAccountError","title":"<code>NotAValidAccountError</code>","text":"<p>               Bases: <code>RustfavaAPIError</code></p> <p>Not a valid account.</p> Source code in <code>src/rustfava/core/documents.py</code> <pre><code>class NotAValidAccountError(RustfavaAPIError):\n    \"\"\"Not a valid account.\"\"\"\n\n    def __init__(self, account: str) -&gt; None:\n        super().__init__(f\"Not a valid account: '{account}'\")\n</code></pre>"},{"location":"api/#rustfava.core.documents.is_document_or_import_file","title":"<code>is_document_or_import_file(filename, ledger)</code>","text":"<p>Check whether the filename is a document or in an import directory.</p> <p>This is a security validation function that prevents path traversal.</p> <p>Parameters:</p> Name Type Description Default <code>filename</code> <code>str</code> <p>The filename to check.</p> required <code>ledger</code> <code>RustfavaLedger</code> <p>The RustfavaLedger.</p> required <p>Returns:</p> Type Description <code>bool</code> <p>Whether this is one of the documents or a path in an import dir.</p> Source code in <code>src/rustfava/core/documents.py</code> <pre><code>def is_document_or_import_file(filename: str, ledger: RustfavaLedger) -&gt; bool:\n    \"\"\"Check whether the filename is a document or in an import directory.\n\n    This is a security validation function that prevents path traversal.\n\n    Args:\n        filename: The filename to check.\n        ledger: The RustfavaLedger.\n\n    Returns:\n        Whether this is one of the documents or a path in an import dir.\n    \"\"\"\n    # Check if it's an exact match for a known document\n    if any(\n        filename == d.filename for d in ledger.all_entries_by_type.Document\n    ):\n        return True\n    # Check if resolved path is within an import directory (prevents path traversal)\n    file_path = Path(filename).resolve()\n    for import_dir in ledger.fava_options.import_dirs:\n        resolved_dir = ledger.join_path(import_dir).resolve()\n        if file_path.is_relative_to(resolved_dir):\n            return True\n    return False\n</code></pre>"},{"location":"api/#rustfava.core.documents.filepath_in_document_folder","title":"<code>filepath_in_document_folder(documents_folder, account, filename, ledger)</code>","text":"<p>File path for a document in the folder for an account.</p> <p>Parameters:</p> Name Type Description Default <code>documents_folder</code> <code>str</code> <p>The documents folder.</p> required <code>account</code> <code>str</code> <p>The account to choose the subfolder for.</p> required <code>filename</code> <code>str</code> <p>The filename of the document.</p> required <code>ledger</code> <code>RustfavaLedger</code> <p>The RustfavaLedger.</p> required <p>Returns:</p> Type Description <code>Path</code> <p>The path that the document should be saved at.</p> Source code in <code>src/rustfava/core/documents.py</code> <pre><code>def filepath_in_document_folder(\n    documents_folder: str,\n    account: str,\n    filename: str,\n    ledger: RustfavaLedger,\n) -&gt; Path:\n    \"\"\"File path for a document in the folder for an account.\n\n    Args:\n        documents_folder: The documents folder.\n        account: The account to choose the subfolder for.\n        filename: The filename of the document.\n        ledger: The RustfavaLedger.\n\n    Returns:\n        The path that the document should be saved at.\n    \"\"\"\n    if documents_folder not in ledger.options[\"documents\"]:\n        raise NotADocumentsFolderError(documents_folder)\n\n    if account not in ledger.attributes.accounts:\n        raise NotAValidAccountError(account)\n\n    filename = filename.replace(sep, \" \")\n    if altsep:  # pragma: no cover\n        filename = filename.replace(altsep, \" \")\n\n    return ledger.join_path(\n        documents_folder,\n        *account.split(\":\"),\n        filename,\n    )\n</code></pre>"},{"location":"api/#rustfava.core.extensions","title":"<code>extensions</code>","text":"<p>Fava extensions.</p>"},{"location":"api/#rustfava.core.extensions.ExtensionDetails","title":"<code>ExtensionDetails</code>  <code>dataclass</code>","text":"<p>The information about an extension that is needed for the frontend.</p> Source code in <code>src/rustfava/core/extensions.py</code> <pre><code>@dataclass\nclass ExtensionDetails:\n    \"\"\"The information about an extension that is needed for the frontend.\"\"\"\n\n    name: str\n    report_title: str | None\n    has_js_module: bool\n</code></pre>"},{"location":"api/#rustfava.core.extensions.ExtensionModule","title":"<code>ExtensionModule</code>","text":"<p>               Bases: <code>FavaModule</code></p> <p>Fava extensions.</p> Source code in <code>src/rustfava/core/extensions.py</code> <pre><code>class ExtensionModule(FavaModule):\n    \"\"\"Fava extensions.\"\"\"\n\n    def __init__(self, ledger: RustfavaLedger) -&gt; None:\n        super().__init__(ledger)\n        self._instances: dict[str, RustfavaExtensionBase] = {}\n        self._loaded_extensions: set[type[RustfavaExtensionBase]] = set()\n        self.errors: list[RustfavaExtensionError] = []\n\n    def load_file(self) -&gt; None:  # noqa: D102\n        self.errors = []\n\n        custom_entries = self.ledger.all_entries_by_type.Custom\n\n        seen = set()\n        for entry in (e for e in custom_entries if e.type == \"fava-extension\"):\n            extension = entry.values[0].value\n            if extension in seen:  # pragma: no cover\n                self.errors.append(\n                    RustfavaExtensionError(\n                        entry.meta, f\"Duplicate extension '{extension}'\", entry\n                    )\n                )\n                continue\n\n            seen.add(extension)\n            extensions, errors = find_extensions(\n                Path(self.ledger.beancount_file_path).parent,\n                extension,\n            )\n            self.errors.extend(errors)\n\n            for cls in extensions:\n                ext_config = (\n                    entry.values[1].value if len(entry.values) &gt; 1 else None\n                )\n                if cls not in self._loaded_extensions:\n                    self._loaded_extensions.add(cls)\n                    try:\n                        ext = cls(self.ledger, ext_config)\n                        self._instances[ext.name] = ext\n                    except ExtensionConfigError as error:  # pragma: no cover\n                        self.errors.append(\n                            RustfavaExtensionError(entry.meta, str(error), entry)\n                        )\n\n    @property\n    def _exts(self) -&gt; Iterable[RustfavaExtensionBase]:\n        return self._instances.values()\n\n    @property\n    def extension_details(self) -&gt; Sequence[ExtensionDetails]:\n        \"\"\"Extension information to provide to the Frontend.\"\"\"\n        return [\n            ExtensionDetails(ext.name, ext.report_title, ext.has_js_module)\n            for ext in self._exts\n        ]\n\n    def get_extension(self, name: str) -&gt; RustfavaExtensionBase | None:\n        \"\"\"Get the extension with the given name.\"\"\"\n        return self._instances.get(name, None)\n\n    def after_load_file(self) -&gt; None:\n        \"\"\"Run all `after_load_file` hooks.\"\"\"\n        for ext in self._exts:\n            ext.after_load_file()\n\n    def before_request(self) -&gt; None:\n        \"\"\"Run all `before_request` hooks.\"\"\"\n        for ext in self._exts:\n            ext.before_request()\n\n    def after_entry_modified(self, entry: Directive, new_lines: str) -&gt; None:\n        \"\"\"Run all `after_entry_modified` hooks.\"\"\"\n        for ext in self._exts:  # pragma: no cover\n            ext.after_entry_modified(entry, new_lines)\n\n    def after_insert_entry(self, entry: Directive) -&gt; None:\n        \"\"\"Run all `after_insert_entry` hooks.\"\"\"\n        for ext in self._exts:  # pragma: no cover\n            ext.after_insert_entry(entry)\n\n    def after_delete_entry(self, entry: Directive) -&gt; None:\n        \"\"\"Run all `after_delete_entry` hooks.\"\"\"\n        for ext in self._exts:  # pragma: no cover\n            ext.after_delete_entry(entry)\n\n    def after_insert_metadata(\n        self,\n        entry: Directive,\n        key: str,\n        value: str,\n    ) -&gt; None:\n        \"\"\"Run all `after_insert_metadata` hooks.\"\"\"\n        for ext in self._exts:  # pragma: no cover\n            ext.after_insert_metadata(entry, key, value)\n\n    def after_write_source(self, path: str, source: str) -&gt; None:\n        \"\"\"Run all `after_write_source` hooks.\"\"\"\n        for ext in self._exts:\n            ext.after_write_source(path, source)\n</code></pre>"},{"location":"api/#rustfava.core.extensions.ExtensionModule.extension_details","title":"<code>extension_details</code>  <code>property</code>","text":"<p>Extension information to provide to the Frontend.</p>"},{"location":"api/#rustfava.core.extensions.ExtensionModule.get_extension","title":"<code>get_extension(name)</code>","text":"<p>Get the extension with the given name.</p> Source code in <code>src/rustfava/core/extensions.py</code> <pre><code>def get_extension(self, name: str) -&gt; RustfavaExtensionBase | None:\n    \"\"\"Get the extension with the given name.\"\"\"\n    return self._instances.get(name, None)\n</code></pre>"},{"location":"api/#rustfava.core.extensions.ExtensionModule.after_load_file","title":"<code>after_load_file()</code>","text":"<p>Run all <code>after_load_file</code> hooks.</p> Source code in <code>src/rustfava/core/extensions.py</code> <pre><code>def after_load_file(self) -&gt; None:\n    \"\"\"Run all `after_load_file` hooks.\"\"\"\n    for ext in self._exts:\n        ext.after_load_file()\n</code></pre>"},{"location":"api/#rustfava.core.extensions.ExtensionModule.before_request","title":"<code>before_request()</code>","text":"<p>Run all <code>before_request</code> hooks.</p> Source code in <code>src/rustfava/core/extensions.py</code> <pre><code>def before_request(self) -&gt; None:\n    \"\"\"Run all `before_request` hooks.\"\"\"\n    for ext in self._exts:\n        ext.before_request()\n</code></pre>"},{"location":"api/#rustfava.core.extensions.ExtensionModule.after_entry_modified","title":"<code>after_entry_modified(entry, new_lines)</code>","text":"<p>Run all <code>after_entry_modified</code> hooks.</p> Source code in <code>src/rustfava/core/extensions.py</code> <pre><code>def after_entry_modified(self, entry: Directive, new_lines: str) -&gt; None:\n    \"\"\"Run all `after_entry_modified` hooks.\"\"\"\n    for ext in self._exts:  # pragma: no cover\n        ext.after_entry_modified(entry, new_lines)\n</code></pre>"},{"location":"api/#rustfava.core.extensions.ExtensionModule.after_insert_entry","title":"<code>after_insert_entry(entry)</code>","text":"<p>Run all <code>after_insert_entry</code> hooks.</p> Source code in <code>src/rustfava/core/extensions.py</code> <pre><code>def after_insert_entry(self, entry: Directive) -&gt; None:\n    \"\"\"Run all `after_insert_entry` hooks.\"\"\"\n    for ext in self._exts:  # pragma: no cover\n        ext.after_insert_entry(entry)\n</code></pre>"},{"location":"api/#rustfava.core.extensions.ExtensionModule.after_delete_entry","title":"<code>after_delete_entry(entry)</code>","text":"<p>Run all <code>after_delete_entry</code> hooks.</p> Source code in <code>src/rustfava/core/extensions.py</code> <pre><code>def after_delete_entry(self, entry: Directive) -&gt; None:\n    \"\"\"Run all `after_delete_entry` hooks.\"\"\"\n    for ext in self._exts:  # pragma: no cover\n        ext.after_delete_entry(entry)\n</code></pre>"},{"location":"api/#rustfava.core.extensions.ExtensionModule.after_insert_metadata","title":"<code>after_insert_metadata(entry, key, value)</code>","text":"<p>Run all <code>after_insert_metadata</code> hooks.</p> Source code in <code>src/rustfava/core/extensions.py</code> <pre><code>def after_insert_metadata(\n    self,\n    entry: Directive,\n    key: str,\n    value: str,\n) -&gt; None:\n    \"\"\"Run all `after_insert_metadata` hooks.\"\"\"\n    for ext in self._exts:  # pragma: no cover\n        ext.after_insert_metadata(entry, key, value)\n</code></pre>"},{"location":"api/#rustfava.core.extensions.ExtensionModule.after_write_source","title":"<code>after_write_source(path, source)</code>","text":"<p>Run all <code>after_write_source</code> hooks.</p> Source code in <code>src/rustfava/core/extensions.py</code> <pre><code>def after_write_source(self, path: str, source: str) -&gt; None:\n    \"\"\"Run all `after_write_source` hooks.\"\"\"\n    for ext in self._exts:\n        ext.after_write_source(path, source)\n</code></pre>"},{"location":"api/#rustfava.core.fava_options","title":"<code>fava_options</code>","text":"<p>rustfava's options.</p> <p>Options for rustfava can be specified through Custom entries in the Beancount file. This module contains a list of possible options, the defaults and the code for parsing the options.</p>"},{"location":"api/#rustfava.core.fava_options.OptionError","title":"<code>OptionError</code>  <code>dataclass</code>","text":"<p>               Bases: <code>BeancountError</code></p> <p>An error for one of the rustfava options.</p> Source code in <code>src/rustfava/core/fava_options.py</code> <pre><code>class OptionError(BeancountError):\n    \"\"\"An error for one of the rustfava options.\"\"\"\n</code></pre>"},{"location":"api/#rustfava.core.fava_options.InsertEntryOption","title":"<code>InsertEntryOption</code>  <code>dataclass</code>","text":"<p>Insert option.</p> <p>An option that determines where entries for matching accounts should be inserted.</p> Source code in <code>src/rustfava/core/fava_options.py</code> <pre><code>@dataclass(frozen=True)\nclass InsertEntryOption:\n    \"\"\"Insert option.\n\n    An option that determines where entries for matching accounts should be\n    inserted.\n    \"\"\"\n\n    date: datetime.date\n    re: Pattern[str]\n    filename: str\n    lineno: int\n</code></pre>"},{"location":"api/#rustfava.core.fava_options.RustfavaOptions","title":"<code>RustfavaOptions</code>  <code>dataclass</code>","text":"<p>Options for rustfava that can be set in the Beancount file.</p> Source code in <code>src/rustfava/core/fava_options.py</code> <pre><code>@dataclass\nclass RustfavaOptions:\n    \"\"\"Options for rustfava that can be set in the Beancount file.\"\"\"\n\n    account_journal_include_children: bool = True\n    auto_reload: bool = False\n    collapse_pattern: Sequence[Pattern[str]] = field(default_factory=list)\n    conversion_currencies: tuple[str, ...] = ()\n    currency_column: int = 61\n    default_file: str | None = None\n    default_page: str = \"income_statement/\"\n    fiscal_year_end: FiscalYearEnd = END_OF_YEAR\n    import_config: str | None = None\n    import_dirs: Sequence[str] = field(default_factory=list)\n    indent: int = 2\n    insert_entry: Sequence[InsertEntryOption] = field(default_factory=list)\n    invert_gains_losses_colors: bool = False\n    invert_income_liabilities_equity: bool = False\n    language: str | None = None\n    locale: str | None = None\n    show_accounts_with_zero_balance: bool = True\n    show_accounts_with_zero_transactions: bool = True\n    show_closed_accounts: bool = False\n    sidebar_show_queries: int = 5\n    unrealized: str = \"Unrealized\"\n    upcoming_events: int = 7\n    uptodate_indicator_grey_lookback_days: int = 60\n    use_external_editor: bool = False\n\n    def set_collapse_pattern(self, value: str) -&gt; None:\n        \"\"\"Set the collapse_pattern option.\"\"\"\n        try:\n            pattern = re.compile(value)\n        except re.error as err:\n            raise NotARegularExpressionError(value) from err\n        # It's typed as Sequence so that it's not externally mutated\n        self.collapse_pattern.append(pattern)  # type: ignore[attr-defined]\n\n    def set_default_file(self, value: str, filename: str) -&gt; None:\n        \"\"\"Set the default_file option.\"\"\"\n        self.default_file = (\n            str((Path(filename).parent / value).absolute())\n            if value\n            else filename\n        )\n\n    def set_fiscal_year_end(self, value: str) -&gt; None:\n        \"\"\"Set the fiscal_year_end option.\"\"\"\n        fye = parse_fye_string(value)\n        if fye is None:\n            raise InvalidFiscalYearEndOptionError(value)\n        self.fiscal_year_end = fye\n\n    def set_import_dirs(self, value: str) -&gt; None:\n        \"\"\"Add an import directory.\"\"\"\n        # It's typed as Sequence so that it's not externally mutated\n        self.import_dirs.append(value)  # type: ignore[attr-defined]\n\n    def set_insert_entry(\n        self, value: str, date: datetime.date, filename: str, lineno: int\n    ) -&gt; None:\n        \"\"\"Set the insert_entry option.\"\"\"\n        try:\n            pattern = re.compile(value)\n        except re.error as err:\n            raise NotARegularExpressionError(value) from err\n        opt = InsertEntryOption(date, pattern, filename, lineno)\n        # It's typed as Sequence so that it's not externally mutated\n        self.insert_entry.append(opt)  # type: ignore[attr-defined]\n\n    def set_language(self, value: str) -&gt; None:\n        \"\"\"Set the locale option.\"\"\"\n        try:\n            locale = Locale.parse(value)\n            if (\n                not locale.language == \"en\"\n                and get_translations(locale) is None\n            ):\n                raise UnsupportedLanguageOptionError(value)\n            self.language = value\n        except UnknownLocaleError as err:\n            raise UnknownLocaleOptionError(value) from err\n\n    def set_locale(self, value: str) -&gt; None:\n        \"\"\"Set the locale option.\"\"\"\n        try:\n            Locale.parse(value)\n            self.locale = value\n        except UnknownLocaleError as err:\n            raise UnknownLocaleOptionError(value) from err\n</code></pre>"},{"location":"api/#rustfava.core.fava_options.RustfavaOptions.set_collapse_pattern","title":"<code>set_collapse_pattern(value)</code>","text":"<p>Set the collapse_pattern option.</p> Source code in <code>src/rustfava/core/fava_options.py</code> <pre><code>def set_collapse_pattern(self, value: str) -&gt; None:\n    \"\"\"Set the collapse_pattern option.\"\"\"\n    try:\n        pattern = re.compile(value)\n    except re.error as err:\n        raise NotARegularExpressionError(value) from err\n    # It's typed as Sequence so that it's not externally mutated\n    self.collapse_pattern.append(pattern)  # type: ignore[attr-defined]\n</code></pre>"},{"location":"api/#rustfava.core.fava_options.RustfavaOptions.set_default_file","title":"<code>set_default_file(value, filename)</code>","text":"<p>Set the default_file option.</p> Source code in <code>src/rustfava/core/fava_options.py</code> <pre><code>def set_default_file(self, value: str, filename: str) -&gt; None:\n    \"\"\"Set the default_file option.\"\"\"\n    self.default_file = (\n        str((Path(filename).parent / value).absolute())\n        if value\n        else filename\n    )\n</code></pre>"},{"location":"api/#rustfava.core.fava_options.RustfavaOptions.set_fiscal_year_end","title":"<code>set_fiscal_year_end(value)</code>","text":"<p>Set the fiscal_year_end option.</p> Source code in <code>src/rustfava/core/fava_options.py</code> <pre><code>def set_fiscal_year_end(self, value: str) -&gt; None:\n    \"\"\"Set the fiscal_year_end option.\"\"\"\n    fye = parse_fye_string(value)\n    if fye is None:\n        raise InvalidFiscalYearEndOptionError(value)\n    self.fiscal_year_end = fye\n</code></pre>"},{"location":"api/#rustfava.core.fava_options.RustfavaOptions.set_import_dirs","title":"<code>set_import_dirs(value)</code>","text":"<p>Add an import directory.</p> Source code in <code>src/rustfava/core/fava_options.py</code> <pre><code>def set_import_dirs(self, value: str) -&gt; None:\n    \"\"\"Add an import directory.\"\"\"\n    # It's typed as Sequence so that it's not externally mutated\n    self.import_dirs.append(value)  # type: ignore[attr-defined]\n</code></pre>"},{"location":"api/#rustfava.core.fava_options.RustfavaOptions.set_insert_entry","title":"<code>set_insert_entry(value, date, filename, lineno)</code>","text":"<p>Set the insert_entry option.</p> Source code in <code>src/rustfava/core/fava_options.py</code> <pre><code>def set_insert_entry(\n    self, value: str, date: datetime.date, filename: str, lineno: int\n) -&gt; None:\n    \"\"\"Set the insert_entry option.\"\"\"\n    try:\n        pattern = re.compile(value)\n    except re.error as err:\n        raise NotARegularExpressionError(value) from err\n    opt = InsertEntryOption(date, pattern, filename, lineno)\n    # It's typed as Sequence so that it's not externally mutated\n    self.insert_entry.append(opt)  # type: ignore[attr-defined]\n</code></pre>"},{"location":"api/#rustfava.core.fava_options.RustfavaOptions.set_language","title":"<code>set_language(value)</code>","text":"<p>Set the locale option.</p> Source code in <code>src/rustfava/core/fava_options.py</code> <pre><code>def set_language(self, value: str) -&gt; None:\n    \"\"\"Set the locale option.\"\"\"\n    try:\n        locale = Locale.parse(value)\n        if (\n            not locale.language == \"en\"\n            and get_translations(locale) is None\n        ):\n            raise UnsupportedLanguageOptionError(value)\n        self.language = value\n    except UnknownLocaleError as err:\n        raise UnknownLocaleOptionError(value) from err\n</code></pre>"},{"location":"api/#rustfava.core.fava_options.RustfavaOptions.set_locale","title":"<code>set_locale(value)</code>","text":"<p>Set the locale option.</p> Source code in <code>src/rustfava/core/fava_options.py</code> <pre><code>def set_locale(self, value: str) -&gt; None:\n    \"\"\"Set the locale option.\"\"\"\n    try:\n        Locale.parse(value)\n        self.locale = value\n    except UnknownLocaleError as err:\n        raise UnknownLocaleOptionError(value) from err\n</code></pre>"},{"location":"api/#rustfava.core.fava_options.parse_option_custom_entry","title":"<code>parse_option_custom_entry(entry, options)</code>","text":"<p>Parse a single custom fava-option entry and set option accordingly.</p> Source code in <code>src/rustfava/core/fava_options.py</code> <pre><code>def parse_option_custom_entry(  # noqa: PLR0912\n    entry: Custom,\n    options: RustfavaOptions,\n) -&gt; None:\n    \"\"\"Parse a single custom fava-option entry and set option accordingly.\"\"\"\n    key = str(entry.values[0].value).replace(\"-\", \"_\")\n    if key not in All_OPTS:\n        raise UnknownOptionError(key)\n\n    value = entry.values[1].value if len(entry.values) &gt; 1 else \"\"\n    if not isinstance(value, str):\n        raise NotAStringOptionError(key)\n    filename, lineno = get_position(entry)\n\n    if key == \"collapse_pattern\":\n        options.set_collapse_pattern(value)\n    elif key == \"default_file\":\n        options.set_default_file(value, filename)\n    elif key == \"fiscal_year_end\":\n        options.set_fiscal_year_end(value)\n    elif key == \"import_dirs\":\n        options.set_import_dirs(value)\n    elif key == \"insert_entry\":\n        options.set_insert_entry(value, entry.date, filename, lineno)\n    elif key == \"language\":\n        options.set_language(value)\n    elif key == \"locale\":\n        options.set_locale(value)\n    elif key in STR_OPTS:\n        setattr(options, key, value)\n    elif key in BOOL_OPTS:\n        setattr(options, key, value.lower() == \"true\")\n    elif key in INT_OPTS:\n        setattr(options, key, int(value))\n    else:  # key in TUPLE_OPTS\n        setattr(options, key, tuple(value.strip().split(\" \")))\n</code></pre>"},{"location":"api/#rustfava.core.fava_options.parse_options","title":"<code>parse_options(custom_entries)</code>","text":"<p>Parse custom entries for rustfava options.</p> <p>The format for option entries is the following::</p> <pre><code>2016-04-01 custom \"fava-option\" \"[name]\" \"[value]\"\n</code></pre> <p>Parameters:</p> Name Type Description Default <code>custom_entries</code> <code>Sequence[Custom]</code> <p>A list of Custom entries.</p> required <p>Returns:</p> Type Description <code>RustfavaOptions</code> <p>A tuple (options, errors) where options is a dictionary of all options</p> <code>list[OptionError]</code> <p>to values, and errors contains possible parsing errors.</p> Source code in <code>src/rustfava/core/fava_options.py</code> <pre><code>def parse_options(\n    custom_entries: Sequence[Custom],\n) -&gt; tuple[RustfavaOptions, list[OptionError]]:\n    \"\"\"Parse custom entries for rustfava options.\n\n    The format for option entries is the following::\n\n        2016-04-01 custom \"fava-option\" \"[name]\" \"[value]\"\n\n    Args:\n        custom_entries: A list of Custom entries.\n\n    Returns:\n        A tuple (options, errors) where options is a dictionary of all options\n        to values, and errors contains possible parsing errors.\n    \"\"\"\n    options = RustfavaOptions()\n    errors = []\n\n    for entry in (e for e in custom_entries if e.type == \"fava-option\"):\n        try:\n            if not entry.values:\n                raise MissingOptionError\n            parse_option_custom_entry(entry, options)\n        except (IndexError, TypeError, ValueError) as err:\n            msg = f\"Failed to parse fava-option entry: {err!s}\"\n            errors.append(OptionError(entry.meta, msg, entry))\n\n    return options, errors\n</code></pre>"},{"location":"api/#rustfava.core.file","title":"<code>file</code>","text":"<p>Reading/writing Beancount files.</p>"},{"location":"api/#rustfava.core.file.NonSourceFileError","title":"<code>NonSourceFileError</code>","text":"<p>               Bases: <code>RustfavaAPIError</code></p> <p>Trying to read a non-source file.</p> Source code in <code>src/rustfava/core/file.py</code> <pre><code>class NonSourceFileError(RustfavaAPIError):\n    \"\"\"Trying to read a non-source file.\"\"\"\n\n    def __init__(self, path: Path) -&gt; None:\n        super().__init__(f\"Trying to read a non-source file at '{path}'\")\n</code></pre>"},{"location":"api/#rustfava.core.file.ExternallyChangedError","title":"<code>ExternallyChangedError</code>","text":"<p>               Bases: <code>RustfavaAPIError</code></p> <p>The file changed externally.</p> Source code in <code>src/rustfava/core/file.py</code> <pre><code>class ExternallyChangedError(RustfavaAPIError):\n    \"\"\"The file changed externally.\"\"\"\n\n    def __init__(self, path: Path) -&gt; None:\n        super().__init__(f\"The file at '{path}' changed externally.\")\n</code></pre>"},{"location":"api/#rustfava.core.file.GeneratedEntryError","title":"<code>GeneratedEntryError</code>","text":"<p>               Bases: <code>RustfavaAPIError</code></p> <p>The entry is generated and cannot be edited.</p> Source code in <code>src/rustfava/core/file.py</code> <pre><code>class GeneratedEntryError(RustfavaAPIError):\n    \"\"\"The entry is generated and cannot be edited.\"\"\"\n\n    def __init__(self) -&gt; None:\n        super().__init__(\"The entry is generated and cannot be edited.\")\n</code></pre>"},{"location":"api/#rustfava.core.file.InvalidUnicodeError","title":"<code>InvalidUnicodeError</code>","text":"<p>               Bases: <code>RustfavaAPIError</code></p> <p>The source file contains invalid unicode.</p> Source code in <code>src/rustfava/core/file.py</code> <pre><code>class InvalidUnicodeError(RustfavaAPIError):\n    \"\"\"The source file contains invalid unicode.\"\"\"\n\n    def __init__(self, reason: str) -&gt; None:\n        super().__init__(\n            f\"The source file contains invalid unicode: {reason}.\",\n        )\n</code></pre>"},{"location":"api/#rustfava.core.file.FileModule","title":"<code>FileModule</code>","text":"<p>               Bases: <code>FavaModule</code></p> <p>Functions related to reading/writing to Beancount files.</p> Source code in <code>src/rustfava/core/file.py</code> <pre><code>class FileModule(FavaModule):\n    \"\"\"Functions related to reading/writing to Beancount files.\"\"\"\n\n    def __init__(self, ledger: RustfavaLedger) -&gt; None:\n        super().__init__(ledger)\n        self._lock = threading.Lock()\n\n    def get_source(self, path: Path) -&gt; tuple[str, str]:\n        \"\"\"Get source files.\n\n        Args:\n            path: The path of the file.\n\n        Returns:\n            A string with the file contents and the `sha256sum` of the file.\n\n        Raises:\n            NonSourceFileError: If the file is not one of the source files.\n            InvalidUnicodeError: If the file contains invalid unicode.\n        \"\"\"\n        if str(path) not in self.ledger.options[\"include\"]:\n            raise NonSourceFileError(path)\n\n        try:\n            source = path.read_text(\"utf-8\")\n        except UnicodeDecodeError as exc:\n            raise InvalidUnicodeError(str(exc)) from exc\n\n        return source, _sha256_str(source)\n\n    def set_source(self, path: Path, source: str, sha256sum: str) -&gt; str:\n        \"\"\"Write to source file.\n\n        Args:\n            path: The path of the file.\n            source: A string with the file contents.\n            sha256sum: Hash of the file.\n\n        Returns:\n            The `sha256sum` of the updated file.\n\n        Raises:\n            NonSourceFileError: If the file is not one of the source files.\n            InvalidUnicodeError: If the file contains invalid unicode.\n            ExternallyChangedError: If the file was changed externally.\n        \"\"\"\n        with self._lock:\n            _, original_sha256sum = self.get_source(path)\n            if original_sha256sum != sha256sum:\n                raise ExternallyChangedError(path)\n\n            newline = _file_newline_character(path)\n            with path.open(\"w\", encoding=\"utf-8\", newline=newline) as file:\n                file.write(source)\n            self.ledger.watcher.notify(path)\n\n            self.ledger.extensions.after_write_source(str(path), source)\n            self.ledger.load_file()\n\n            return _sha256_str(source)\n\n    def insert_metadata(\n        self,\n        entry_hash: str,\n        basekey: str,\n        value: str,\n    ) -&gt; None:\n        \"\"\"Insert metadata into a file at lineno.\n\n        Also, prevent duplicate keys.\n\n        Args:\n            entry_hash: Hash of an entry.\n            basekey: Key to insert metadata for.\n            value: Metadate value to insert.\n        \"\"\"\n        with self._lock:\n            self.ledger.changed()\n            entry = self.ledger.get_entry(entry_hash)\n            key = next_key(basekey, entry.meta)\n            indent = self.ledger.fava_options.indent\n            path, lineno = _get_position(entry)\n            insert_metadata_in_file(path, lineno, indent, key, value)\n            self.ledger.watcher.notify(path)\n            self.ledger.extensions.after_insert_metadata(entry, key, value)\n\n    def save_entry_slice(\n        self,\n        entry_hash: str,\n        source_slice: str,\n        sha256sum: str,\n    ) -&gt; str:\n        \"\"\"Save slice of the source file for an entry.\n\n        Args:\n            entry_hash: Hash of an entry.\n            source_slice: The lines that the entry should be replaced with.\n            sha256sum: The sha256sum of the current lines of the entry.\n\n        Returns:\n            The `sha256sum` of the new lines of the entry.\n\n        Raises:\n            RustfavaAPIError: If the entry is not found or the file changed.\n        \"\"\"\n        with self._lock:\n            entry = self.ledger.get_entry(entry_hash)\n            new_sha256sum = save_entry_slice(entry, source_slice, sha256sum)\n            self.ledger.watcher.notify(Path(get_position(entry)[0]))\n            self.ledger.extensions.after_entry_modified(entry, source_slice)\n            return new_sha256sum\n\n    def delete_entry_slice(self, entry_hash: str, sha256sum: str) -&gt; None:\n        \"\"\"Delete slice of the source file for an entry.\n\n        Args:\n            entry_hash: Hash of an entry.\n            sha256sum: The sha256sum of the current lines of the entry.\n\n        Raises:\n            RustfavaAPIError: If the entry is not found or the file changed.\n        \"\"\"\n        with self._lock:\n            entry = self.ledger.get_entry(entry_hash)\n            delete_entry_slice(entry, sha256sum)\n            self.ledger.watcher.notify(Path(get_position(entry)[0]))\n            self.ledger.extensions.after_delete_entry(entry)\n\n    def insert_entries(self, entries: Sequence[Directive]) -&gt; None:\n        \"\"\"Insert entries.\n\n        Args:\n            entries: A list of entries.\n        \"\"\"\n        with self._lock:\n            self.ledger.changed()\n            fava_options = self.ledger.fava_options\n            for entry in sorted(entries, key=_incomplete_sortkey):\n                path, updated_insert_options = insert_entry(\n                    entry,\n                    (\n                        self.ledger.fava_options.default_file\n                        or self.ledger.beancount_file_path\n                    ),\n                    insert_options=fava_options.insert_entry,\n                    currency_column=fava_options.currency_column,\n                    indent=fava_options.indent,\n                )\n                self.ledger.watcher.notify(path)\n                self.ledger.fava_options.insert_entry = updated_insert_options\n                self.ledger.extensions.after_insert_entry(entry)\n\n    def render_entries(self, entries: Sequence[Directive]) -&gt; Iterable[Markup]:\n        \"\"\"Return entries in Beancount format.\n\n        Only renders :class:`.Balance` and :class:`.Transaction`.\n\n        Args:\n            entries: A list of entries.\n\n        Yields:\n            The entries rendered in Beancount format.\n        \"\"\"\n        indent = self.ledger.fava_options.indent\n        for entry in entries:\n            if isinstance(entry, (Balance, Transaction)):\n                if (\n                    isinstance(entry, Transaction)\n                    and entry.flag in _EXCL_FLAGS\n                ):\n                    continue\n                try:\n                    yield Markup(get_entry_slice(entry)[0] + \"\\n\")  # noqa: S704\n                except (KeyError, FileNotFoundError):\n                    yield Markup(  # noqa: S704\n                        to_string(\n                            entry,\n                            self.ledger.fava_options.currency_column,\n                            indent,\n                        ),\n                    )\n</code></pre>"},{"location":"api/#rustfava.core.file.FileModule.get_source","title":"<code>get_source(path)</code>","text":"<p>Get source files.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>Path</code> <p>The path of the file.</p> required <p>Returns:</p> Type Description <code>tuple[str, str]</code> <p>A string with the file contents and the <code>sha256sum</code> of the file.</p> <p>Raises:</p> Type Description <code>NonSourceFileError</code> <p>If the file is not one of the source files.</p> <code>InvalidUnicodeError</code> <p>If the file contains invalid unicode.</p> Source code in <code>src/rustfava/core/file.py</code> <pre><code>def get_source(self, path: Path) -&gt; tuple[str, str]:\n    \"\"\"Get source files.\n\n    Args:\n        path: The path of the file.\n\n    Returns:\n        A string with the file contents and the `sha256sum` of the file.\n\n    Raises:\n        NonSourceFileError: If the file is not one of the source files.\n        InvalidUnicodeError: If the file contains invalid unicode.\n    \"\"\"\n    if str(path) not in self.ledger.options[\"include\"]:\n        raise NonSourceFileError(path)\n\n    try:\n        source = path.read_text(\"utf-8\")\n    except UnicodeDecodeError as exc:\n        raise InvalidUnicodeError(str(exc)) from exc\n\n    return source, _sha256_str(source)\n</code></pre>"},{"location":"api/#rustfava.core.file.FileModule.set_source","title":"<code>set_source(path, source, sha256sum)</code>","text":"<p>Write to source file.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>Path</code> <p>The path of the file.</p> required <code>source</code> <code>str</code> <p>A string with the file contents.</p> required <code>sha256sum</code> <code>str</code> <p>Hash of the file.</p> required <p>Returns:</p> Type Description <code>str</code> <p>The <code>sha256sum</code> of the updated file.</p> <p>Raises:</p> Type Description <code>NonSourceFileError</code> <p>If the file is not one of the source files.</p> <code>InvalidUnicodeError</code> <p>If the file contains invalid unicode.</p> <code>ExternallyChangedError</code> <p>If the file was changed externally.</p> Source code in <code>src/rustfava/core/file.py</code> <pre><code>def set_source(self, path: Path, source: str, sha256sum: str) -&gt; str:\n    \"\"\"Write to source file.\n\n    Args:\n        path: The path of the file.\n        source: A string with the file contents.\n        sha256sum: Hash of the file.\n\n    Returns:\n        The `sha256sum` of the updated file.\n\n    Raises:\n        NonSourceFileError: If the file is not one of the source files.\n        InvalidUnicodeError: If the file contains invalid unicode.\n        ExternallyChangedError: If the file was changed externally.\n    \"\"\"\n    with self._lock:\n        _, original_sha256sum = self.get_source(path)\n        if original_sha256sum != sha256sum:\n            raise ExternallyChangedError(path)\n\n        newline = _file_newline_character(path)\n        with path.open(\"w\", encoding=\"utf-8\", newline=newline) as file:\n            file.write(source)\n        self.ledger.watcher.notify(path)\n\n        self.ledger.extensions.after_write_source(str(path), source)\n        self.ledger.load_file()\n\n        return _sha256_str(source)\n</code></pre>"},{"location":"api/#rustfava.core.file.FileModule.insert_metadata","title":"<code>insert_metadata(entry_hash, basekey, value)</code>","text":"<p>Insert metadata into a file at lineno.</p> <p>Also, prevent duplicate keys.</p> <p>Parameters:</p> Name Type Description Default <code>entry_hash</code> <code>str</code> <p>Hash of an entry.</p> required <code>basekey</code> <code>str</code> <p>Key to insert metadata for.</p> required <code>value</code> <code>str</code> <p>Metadate value to insert.</p> required Source code in <code>src/rustfava/core/file.py</code> <pre><code>def insert_metadata(\n    self,\n    entry_hash: str,\n    basekey: str,\n    value: str,\n) -&gt; None:\n    \"\"\"Insert metadata into a file at lineno.\n\n    Also, prevent duplicate keys.\n\n    Args:\n        entry_hash: Hash of an entry.\n        basekey: Key to insert metadata for.\n        value: Metadate value to insert.\n    \"\"\"\n    with self._lock:\n        self.ledger.changed()\n        entry = self.ledger.get_entry(entry_hash)\n        key = next_key(basekey, entry.meta)\n        indent = self.ledger.fava_options.indent\n        path, lineno = _get_position(entry)\n        insert_metadata_in_file(path, lineno, indent, key, value)\n        self.ledger.watcher.notify(path)\n        self.ledger.extensions.after_insert_metadata(entry, key, value)\n</code></pre>"},{"location":"api/#rustfava.core.file.FileModule.save_entry_slice","title":"<code>save_entry_slice(entry_hash, source_slice, sha256sum)</code>","text":"<p>Save slice of the source file for an entry.</p> <p>Parameters:</p> Name Type Description Default <code>entry_hash</code> <code>str</code> <p>Hash of an entry.</p> required <code>source_slice</code> <code>str</code> <p>The lines that the entry should be replaced with.</p> required <code>sha256sum</code> <code>str</code> <p>The sha256sum of the current lines of the entry.</p> required <p>Returns:</p> Type Description <code>str</code> <p>The <code>sha256sum</code> of the new lines of the entry.</p> <p>Raises:</p> Type Description <code>RustfavaAPIError</code> <p>If the entry is not found or the file changed.</p> Source code in <code>src/rustfava/core/file.py</code> <pre><code>def save_entry_slice(\n    self,\n    entry_hash: str,\n    source_slice: str,\n    sha256sum: str,\n) -&gt; str:\n    \"\"\"Save slice of the source file for an entry.\n\n    Args:\n        entry_hash: Hash of an entry.\n        source_slice: The lines that the entry should be replaced with.\n        sha256sum: The sha256sum of the current lines of the entry.\n\n    Returns:\n        The `sha256sum` of the new lines of the entry.\n\n    Raises:\n        RustfavaAPIError: If the entry is not found or the file changed.\n    \"\"\"\n    with self._lock:\n        entry = self.ledger.get_entry(entry_hash)\n        new_sha256sum = save_entry_slice(entry, source_slice, sha256sum)\n        self.ledger.watcher.notify(Path(get_position(entry)[0]))\n        self.ledger.extensions.after_entry_modified(entry, source_slice)\n        return new_sha256sum\n</code></pre>"},{"location":"api/#rustfava.core.file.FileModule.delete_entry_slice","title":"<code>delete_entry_slice(entry_hash, sha256sum)</code>","text":"<p>Delete slice of the source file for an entry.</p> <p>Parameters:</p> Name Type Description Default <code>entry_hash</code> <code>str</code> <p>Hash of an entry.</p> required <code>sha256sum</code> <code>str</code> <p>The sha256sum of the current lines of the entry.</p> required <p>Raises:</p> Type Description <code>RustfavaAPIError</code> <p>If the entry is not found or the file changed.</p> Source code in <code>src/rustfava/core/file.py</code> <pre><code>def delete_entry_slice(self, entry_hash: str, sha256sum: str) -&gt; None:\n    \"\"\"Delete slice of the source file for an entry.\n\n    Args:\n        entry_hash: Hash of an entry.\n        sha256sum: The sha256sum of the current lines of the entry.\n\n    Raises:\n        RustfavaAPIError: If the entry is not found or the file changed.\n    \"\"\"\n    with self._lock:\n        entry = self.ledger.get_entry(entry_hash)\n        delete_entry_slice(entry, sha256sum)\n        self.ledger.watcher.notify(Path(get_position(entry)[0]))\n        self.ledger.extensions.after_delete_entry(entry)\n</code></pre>"},{"location":"api/#rustfava.core.file.FileModule.insert_entries","title":"<code>insert_entries(entries)</code>","text":"<p>Insert entries.</p> <p>Parameters:</p> Name Type Description Default <code>entries</code> <code>Sequence[Directive]</code> <p>A list of entries.</p> required Source code in <code>src/rustfava/core/file.py</code> <pre><code>def insert_entries(self, entries: Sequence[Directive]) -&gt; None:\n    \"\"\"Insert entries.\n\n    Args:\n        entries: A list of entries.\n    \"\"\"\n    with self._lock:\n        self.ledger.changed()\n        fava_options = self.ledger.fava_options\n        for entry in sorted(entries, key=_incomplete_sortkey):\n            path, updated_insert_options = insert_entry(\n                entry,\n                (\n                    self.ledger.fava_options.default_file\n                    or self.ledger.beancount_file_path\n                ),\n                insert_options=fava_options.insert_entry,\n                currency_column=fava_options.currency_column,\n                indent=fava_options.indent,\n            )\n            self.ledger.watcher.notify(path)\n            self.ledger.fava_options.insert_entry = updated_insert_options\n            self.ledger.extensions.after_insert_entry(entry)\n</code></pre>"},{"location":"api/#rustfava.core.file.FileModule.render_entries","title":"<code>render_entries(entries)</code>","text":"<p>Return entries in Beancount format.</p> <p>Only renders :class:<code>.Balance</code> and :class:<code>.Transaction</code>.</p> <p>Parameters:</p> Name Type Description Default <code>entries</code> <code>Sequence[Directive]</code> <p>A list of entries.</p> required <p>Yields:</p> Type Description <code>Iterable[Markup]</code> <p>The entries rendered in Beancount format.</p> Source code in <code>src/rustfava/core/file.py</code> <pre><code>def render_entries(self, entries: Sequence[Directive]) -&gt; Iterable[Markup]:\n    \"\"\"Return entries in Beancount format.\n\n    Only renders :class:`.Balance` and :class:`.Transaction`.\n\n    Args:\n        entries: A list of entries.\n\n    Yields:\n        The entries rendered in Beancount format.\n    \"\"\"\n    indent = self.ledger.fava_options.indent\n    for entry in entries:\n        if isinstance(entry, (Balance, Transaction)):\n            if (\n                isinstance(entry, Transaction)\n                and entry.flag in _EXCL_FLAGS\n            ):\n                continue\n            try:\n                yield Markup(get_entry_slice(entry)[0] + \"\\n\")  # noqa: S704\n            except (KeyError, FileNotFoundError):\n                yield Markup(  # noqa: S704\n                    to_string(\n                        entry,\n                        self.ledger.fava_options.currency_column,\n                        indent,\n                    ),\n                )\n</code></pre>"},{"location":"api/#rustfava.core.file.insert_metadata_in_file","title":"<code>insert_metadata_in_file(path, lineno, indent, key, value)</code>","text":"<p>Insert the specified metadata in the file below lineno.</p> <p>Takes the whitespace in front of the line that lineno into account.</p> Source code in <code>src/rustfava/core/file.py</code> <pre><code>def insert_metadata_in_file(\n    path: Path,\n    lineno: int,\n    indent: int,\n    key: str,\n    value: str,\n) -&gt; None:\n    \"\"\"Insert the specified metadata in the file below lineno.\n\n    Takes the whitespace in front of the line that lineno into account.\n    \"\"\"\n    with path.open(encoding=\"utf-8\") as file:\n        contents = file.readlines()\n\n    contents.insert(lineno, f'{\" \" * indent}{key}: \"{value}\"\\n')\n    newline = _file_newline_character(path)\n    with path.open(\"w\", encoding=\"utf-8\", newline=newline) as file:\n        file.write(\"\".join(contents))\n</code></pre>"},{"location":"api/#rustfava.core.file.find_entry_lines","title":"<code>find_entry_lines(lines, lineno)</code>","text":"<p>Lines of entry starting at lineno.</p> <p>Parameters:</p> Name Type Description Default <code>lines</code> <code>Sequence[str]</code> <p>A list of lines.</p> required <code>lineno</code> <code>int</code> <p>The 0-based line-index to start at.</p> required Source code in <code>src/rustfava/core/file.py</code> <pre><code>def find_entry_lines(lines: Sequence[str], lineno: int) -&gt; Sequence[str]:\n    \"\"\"Lines of entry starting at lineno.\n\n    Args:\n        lines: A list of lines.\n        lineno: The 0-based line-index to start at.\n    \"\"\"\n    entry_lines = [lines[lineno]]\n    while True:\n        lineno += 1\n        try:\n            line = lines[lineno]\n        except IndexError:\n            return entry_lines\n        if not line.strip() or re.match(r\"\\S\", line[0]):\n            return entry_lines\n        entry_lines.append(line)\n</code></pre>"},{"location":"api/#rustfava.core.file.get_entry_slice","title":"<code>get_entry_slice(entry)</code>","text":"<p>Get slice of the source file for an entry.</p> <p>Parameters:</p> Name Type Description Default <code>entry</code> <code>Directive</code> <p>An entry.</p> required <p>Returns:</p> Type Description <code>str</code> <p>A string containing the lines of the entry and the <code>sha256sum</code> of</p> <code>str</code> <p>these lines.</p> <p>Raises:</p> Type Description <code>GeneratedEntryError</code> <p>If the entry is generated and cannot be edited.</p> Source code in <code>src/rustfava/core/file.py</code> <pre><code>def get_entry_slice(entry: Directive) -&gt; tuple[str, str]:\n    \"\"\"Get slice of the source file for an entry.\n\n    Args:\n        entry: An entry.\n\n    Returns:\n        A string containing the lines of the entry and the `sha256sum` of\n        these lines.\n\n    Raises:\n        GeneratedEntryError: If the entry is generated and cannot be edited.\n    \"\"\"\n    path, lineno = _get_position(entry)\n    with path.open(encoding=\"utf-8\") as file:\n        lines = file.readlines()\n\n    entry_lines = find_entry_lines(lines, lineno - 1)\n    entry_source = \"\".join(entry_lines).rstrip(\"\\n\")\n\n    return entry_source, _sha256_str(entry_source)\n</code></pre>"},{"location":"api/#rustfava.core.file.save_entry_slice","title":"<code>save_entry_slice(entry, source_slice, sha256sum)</code>","text":"<p>Save slice of the source file for an entry.</p> <p>Parameters:</p> Name Type Description Default <code>entry</code> <code>Directive</code> <p>An entry.</p> required <code>source_slice</code> <code>str</code> <p>The lines that the entry should be replaced with.</p> required <code>sha256sum</code> <code>str</code> <p>The sha256sum of the current lines of the entry.</p> required <p>Returns:</p> Type Description <code>str</code> <p>The <code>sha256sum</code> of the new lines of the entry.</p> <p>Raises:</p> Type Description <code>ExternallyChangedError</code> <p>If the file was changed externally.</p> <code>GeneratedEntryError</code> <p>If the entry is generated and cannot be edited.</p> Source code in <code>src/rustfava/core/file.py</code> <pre><code>def save_entry_slice(\n    entry: Directive,\n    source_slice: str,\n    sha256sum: str,\n) -&gt; str:\n    \"\"\"Save slice of the source file for an entry.\n\n    Args:\n        entry: An entry.\n        source_slice: The lines that the entry should be replaced with.\n        sha256sum: The sha256sum of the current lines of the entry.\n\n    Returns:\n        The `sha256sum` of the new lines of the entry.\n\n    Raises:\n        ExternallyChangedError: If the file was changed externally.\n        GeneratedEntryError: If the entry is generated and cannot be edited.\n    \"\"\"\n    path, lineno = _get_position(entry)\n    with path.open(encoding=\"utf-8\") as file:\n        lines = file.readlines()\n\n    first_entry_line = lineno - 1\n    entry_lines = find_entry_lines(lines, first_entry_line)\n    entry_source = \"\".join(entry_lines).rstrip(\"\\n\")\n    if _sha256_str(entry_source) != sha256sum:\n        raise ExternallyChangedError(path)\n\n    lines = [\n        *lines[:first_entry_line],\n        source_slice + \"\\n\",\n        *lines[first_entry_line + len(entry_lines) :],\n    ]\n    newline = _file_newline_character(path)\n    with path.open(\"w\", encoding=\"utf-8\", newline=newline) as file:\n        file.writelines(lines)\n\n    return _sha256_str(source_slice)\n</code></pre>"},{"location":"api/#rustfava.core.file.delete_entry_slice","title":"<code>delete_entry_slice(entry, sha256sum)</code>","text":"<p>Delete slice of the source file for an entry.</p> <p>Parameters:</p> Name Type Description Default <code>entry</code> <code>Directive</code> <p>An entry.</p> required <code>sha256sum</code> <code>str</code> <p>The sha256sum of the current lines of the entry.</p> required <p>Raises:</p> Type Description <code>ExternallyChangedError</code> <p>If the file was changed externally.</p> <code>GeneratedEntryError</code> <p>If the entry is generated and cannot be edited.</p> Source code in <code>src/rustfava/core/file.py</code> <pre><code>def delete_entry_slice(\n    entry: Directive,\n    sha256sum: str,\n) -&gt; None:\n    \"\"\"Delete slice of the source file for an entry.\n\n    Args:\n        entry: An entry.\n        sha256sum: The sha256sum of the current lines of the entry.\n\n    Raises:\n        ExternallyChangedError: If the file was changed externally.\n        GeneratedEntryError: If the entry is generated and cannot be edited.\n    \"\"\"\n    path, lineno = _get_position(entry)\n    with path.open(encoding=\"utf-8\") as file:\n        lines = file.readlines()\n\n    first_entry_line = lineno - 1\n    entry_lines = find_entry_lines(lines, first_entry_line)\n    entry_source = \"\".join(entry_lines).rstrip(\"\\n\")\n    if _sha256_str(entry_source) != sha256sum:\n        raise ExternallyChangedError(path)\n\n    # Also delete the whitespace following this entry\n    last_entry_line = first_entry_line + len(entry_lines)\n    while True:\n        try:\n            line = lines[last_entry_line]\n        except IndexError:\n            break\n        if line.strip():  # pragma: no cover\n            break\n        last_entry_line += 1  # pragma: no cover\n    lines = lines[:first_entry_line] + lines[last_entry_line:]\n    newline = _file_newline_character(path)\n    with path.open(\"w\", encoding=\"utf-8\", newline=newline) as file:\n        file.writelines(lines)\n</code></pre>"},{"location":"api/#rustfava.core.file.insert_entry","title":"<code>insert_entry(entry, default_filename, insert_options, currency_column, indent)</code>","text":"<p>Insert an entry.</p> <p>Parameters:</p> Name Type Description Default <code>entry</code> <code>Directive</code> <p>An entry.</p> required <code>default_filename</code> <code>str</code> <p>The default file to insert into if no option matches.</p> required <code>insert_options</code> <code>Sequence[InsertEntryOption]</code> <p>Insert options.</p> required <code>currency_column</code> <code>int</code> <p>The column to align currencies at.</p> required <code>indent</code> <code>int</code> <p>Number of indent spaces.</p> required <p>Returns:</p> Type Description <code>tuple[Path, Sequence[InsertEntryOption]]</code> <p>A changed path and list of updated insert options.</p> Source code in <code>src/rustfava/core/file.py</code> <pre><code>def insert_entry(\n    entry: Directive,\n    default_filename: str,\n    insert_options: Sequence[InsertEntryOption],\n    currency_column: int,\n    indent: int,\n) -&gt; tuple[Path, Sequence[InsertEntryOption]]:\n    \"\"\"Insert an entry.\n\n    Args:\n        entry: An entry.\n        default_filename: The default file to insert into if no option matches.\n        insert_options: Insert options.\n        currency_column: The column to align currencies at.\n        indent: Number of indent spaces.\n\n    Returns:\n        A changed path and list of updated insert options.\n    \"\"\"\n    filename, lineno = find_insert_position(\n        entry,\n        insert_options,\n        default_filename,\n    )\n    content = to_string(entry, currency_column, indent)\n\n    path = Path(filename)\n    with path.open(encoding=\"utf-8\") as file:\n        contents = file.readlines()\n\n    if lineno is None:\n        # Appending\n        contents += \"\\n\" + content\n    else:\n        contents.insert(lineno, content + \"\\n\")\n\n    newline = _file_newline_character(path)\n    with path.open(\"w\", encoding=\"utf-8\", newline=newline) as file:\n        file.writelines(contents)\n\n    if lineno is None:\n        return (path, insert_options)\n\n    added_lines = content.count(\"\\n\") + 1\n    return (\n        path,\n        [\n            (\n                replace(option, lineno=option.lineno + added_lines)\n                if option.filename == filename and option.lineno &gt; lineno\n                else option\n            )\n            for option in insert_options\n        ],\n    )\n</code></pre>"},{"location":"api/#rustfava.core.file.find_insert_position","title":"<code>find_insert_position(entry, insert_options, default_filename)</code>","text":"<p>Find insert position for an entry.</p> <p>Parameters:</p> Name Type Description Default <code>entry</code> <code>Directive</code> <p>An entry.</p> required <code>insert_options</code> <code>Sequence[InsertEntryOption]</code> <p>A list of InsertOption.</p> required <code>default_filename</code> <code>str</code> <p>The default file to insert into if no option matches.</p> required <p>Returns:</p> Type Description <code>tuple[str, int | None]</code> <p>A tuple of the filename and the line number.</p> Source code in <code>src/rustfava/core/file.py</code> <pre><code>def find_insert_position(\n    entry: Directive,\n    insert_options: Sequence[InsertEntryOption],\n    default_filename: str,\n) -&gt; tuple[str, int | None]:\n    \"\"\"Find insert position for an entry.\n\n    Args:\n        entry: An entry.\n        insert_options: A list of InsertOption.\n        default_filename: The default file to insert into if no option matches.\n\n    Returns:\n        A tuple of the filename and the line number.\n    \"\"\"\n    # Get the list of accounts that should be considered for the entry.\n    # For transactions, we want the reversed list of posting accounts.\n    accounts = get_entry_accounts(entry)\n\n    # Make no assumptions about the order of insert_options entries and instead\n    # sort them ourselves (by descending dates)\n    insert_options = sorted(\n        insert_options,\n        key=attrgetter(\"date\"),\n        reverse=True,\n    )\n\n    for account in accounts:\n        for insert_option in insert_options:\n            # Only consider InsertOptions before the entry date.\n            if insert_option.date &gt;= entry.date:\n                continue\n            if insert_option.re.match(account):\n                return (insert_option.filename, insert_option.lineno - 1)\n\n    return (default_filename, None)\n</code></pre>"},{"location":"api/#rustfava.core.filters","title":"<code>filters</code>","text":"<p>Entry filters.</p>"},{"location":"api/#rustfava.core.filters.FilterError","title":"<code>FilterError</code>","text":"<p>               Bases: <code>RustfavaAPIError</code></p> <p>Filter exception.</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>class FilterError(RustfavaAPIError):\n    \"\"\"Filter exception.\"\"\"\n\n    def __init__(self, filter_type: str, message: str) -&gt; None:\n        super().__init__(message)\n        self.filter_type = filter_type\n\n    def __str__(self) -&gt; str:\n        return self.message\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterParseError","title":"<code>FilterParseError</code>","text":"<p>               Bases: <code>FilterError</code></p> <p>Filter parse error.</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>class FilterParseError(FilterError):\n    \"\"\"Filter parse error.\"\"\"\n\n    def __init__(self) -&gt; None:\n        super().__init__(\"filter\", \"Failed to parse filter: \")\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterIllegalCharError","title":"<code>FilterIllegalCharError</code>","text":"<p>               Bases: <code>FilterError</code></p> <p>Filter illegal char error.</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>class FilterIllegalCharError(FilterError):\n    \"\"\"Filter illegal char error.\"\"\"\n\n    def __init__(self, char: str) -&gt; None:\n        super().__init__(\n            \"filter\",\n            f'Illegal character \"{char}\" in filter.',\n        )\n</code></pre>"},{"location":"api/#rustfava.core.filters.TimeFilterParseError","title":"<code>TimeFilterParseError</code>","text":"<p>               Bases: <code>FilterError</code></p> <p>Time filter parse error.</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>class TimeFilterParseError(FilterError):\n    \"\"\"Time filter parse error.\"\"\"\n\n    def __init__(self, value: str) -&gt; None:\n        super().__init__(\"time\", f\"Failed to parse date: {value}\")\n</code></pre>"},{"location":"api/#rustfava.core.filters.Token","title":"<code>Token</code>","text":"<p>A token having a certain type and value.</p> <p>The lexer attribute only exists since PLY writes to it in case of a parser error.</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>class Token:\n    \"\"\"A token having a certain type and value.\n\n    The lexer attribute only exists since PLY writes to it in case of a parser\n    error.\n    \"\"\"\n\n    __slots__ = (\"lexer\", \"type\", \"value\")\n\n    def __init__(self, type_: str, value: str) -&gt; None:\n        self.type = type_\n        self.value = value\n\n    def __repr__(self) -&gt; str:  # pragma: no cover\n        return f\"Token({self.type}, {self.value})\"\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterSyntaxLexer","title":"<code>FilterSyntaxLexer</code>","text":"<p>Lexer for Fava's filter syntax.</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>class FilterSyntaxLexer:\n    \"\"\"Lexer for Fava's filter syntax.\"\"\"\n\n    tokens = (\n        \"ANY\",\n        \"ALL\",\n        \"CMP_OP\",\n        \"EQ_OP\",\n        \"KEY\",\n        \"LINK\",\n        \"NUMBER\",\n        \"STRING\",\n        \"TAG\",\n    )\n\n    RULES = (\n        (\"LINK\", r\"\\^[A-Za-z0-9\\-_/.]+\"),\n        (\"TAG\", r\"\\#[A-Za-z0-9\\-_/.]+\"),\n        (\"ALL\", r\"all\\(\"),\n        (\"ANY\", r\"any\\(\"),\n        (\"KEY\", r\"[a-z][a-zA-Z0-9\\-_]+(?=\\s*(:|=|&gt;=|&lt;=|&lt;|&gt;))\"),\n        (\"EQ_OP\", r\":\"),\n        (\"CMP_OP\", r\"(=|&gt;=|&lt;=|&lt;|&gt;)\"),\n        (\"NUMBER\", r\"\\d*\\.?\\d+\"),\n        (\"STRING\", r\"\"\"\\w[-\\w]*|\"[^\"]*\"|'[^']*'\"\"\"),\n    )\n\n    regex = re.compile(\n        \"|\".join((f\"(?P&lt;{name}&gt;{rule})\" for name, rule in RULES)),\n    )\n\n    def LINK(self, token: str, value: str) -&gt; tuple[str, str]:  # noqa: N802\n        return token, value[1:]\n\n    def TAG(self, token: str, value: str) -&gt; tuple[str, str]:  # noqa: N802\n        return token, value[1:]\n\n    def KEY(self, token: str, value: str) -&gt; tuple[str, str]:  # noqa: N802\n        return token, value\n\n    def ALL(self, token: str, _: str) -&gt; tuple[str, str]:  # noqa: N802\n        return token, token\n\n    def ANY(self, token: str, _: str) -&gt; tuple[str, str]:  # noqa: N802\n        return token, token\n\n    def EQ_OP(self, token: str, value: str) -&gt; tuple[str, str]:  # noqa: N802\n        return token, value\n\n    def CMP_OP(self, token: str, value: str) -&gt; tuple[str, str]:  # noqa: N802\n        return token, value\n\n    def NUMBER(self, token: str, value: str) -&gt; tuple[str, Decimal]:  # noqa: N802\n        return token, Decimal(value)\n\n    def STRING(self, token: str, value: str) -&gt; tuple[str, str]:  # noqa: N802\n        if value[0] in {'\"', \"'\"}:\n            return token, value[1:-1]\n        return token, value\n\n    def lex(self, data: str) -&gt; Iterable[Token]:\n        \"\"\"A generator yielding all tokens in a given line.\n\n        Arguments:\n            data: A string, the line to lex.\n\n        Yields:\n            All Tokens in the line.\n        \"\"\"\n        ignore = \" \\t\"\n        literals = \"-,()\"\n        regex = self.regex.match\n\n        pos = 0\n        length = len(data)\n        while pos &lt; length:\n            char = data[pos]\n            if char in ignore:\n                pos += 1\n                continue\n            match = regex(data, pos)\n            if match:\n                value = match.group()\n                pos += len(value)\n                token = match.lastgroup\n                if token is None:  # pragma: no cover\n                    msg = \"Internal Error\"\n                    raise ValueError(msg)\n                func: Callable[[str, str], tuple[str, str]] = getattr(\n                    self,\n                    token,\n                )\n                ret = func(token, value)\n                yield Token(*ret)\n            elif char in literals:\n                yield Token(char, char)\n                pos += 1\n            else:\n                raise FilterIllegalCharError(char)\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterSyntaxLexer.lex","title":"<code>lex(data)</code>","text":"<p>A generator yielding all tokens in a given line.</p> <p>Parameters:</p> Name Type Description Default <code>data</code> <code>str</code> <p>A string, the line to lex.</p> required <p>Yields:</p> Type Description <code>Iterable[Token]</code> <p>All Tokens in the line.</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>def lex(self, data: str) -&gt; Iterable[Token]:\n    \"\"\"A generator yielding all tokens in a given line.\n\n    Arguments:\n        data: A string, the line to lex.\n\n    Yields:\n        All Tokens in the line.\n    \"\"\"\n    ignore = \" \\t\"\n    literals = \"-,()\"\n    regex = self.regex.match\n\n    pos = 0\n    length = len(data)\n    while pos &lt; length:\n        char = data[pos]\n        if char in ignore:\n            pos += 1\n            continue\n        match = regex(data, pos)\n        if match:\n            value = match.group()\n            pos += len(value)\n            token = match.lastgroup\n            if token is None:  # pragma: no cover\n                msg = \"Internal Error\"\n                raise ValueError(msg)\n            func: Callable[[str, str], tuple[str, str]] = getattr(\n                self,\n                token,\n            )\n            ret = func(token, value)\n            yield Token(*ret)\n        elif char in literals:\n            yield Token(char, char)\n            pos += 1\n        else:\n            raise FilterIllegalCharError(char)\n</code></pre>"},{"location":"api/#rustfava.core.filters.Match","title":"<code>Match</code>","text":"<p>Match a string.</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>class Match:\n    \"\"\"Match a string.\"\"\"\n\n    __slots__ = (\"match\",)\n\n    match: Callable[[str], bool]\n\n    def __init__(self, search: str) -&gt; None:\n        try:\n            match = re.compile(search, re.IGNORECASE).search\n            self.match = lambda s: bool(match(s))\n        except re.error:\n            self.match = lambda s: s == search\n\n    def __call__(self, obj: Any) -&gt; bool:\n        return self.match(str(obj))\n</code></pre>"},{"location":"api/#rustfava.core.filters.MatchAmount","title":"<code>MatchAmount</code>","text":"<p>Matches an amount.</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>class MatchAmount:\n    \"\"\"Matches an amount.\"\"\"\n\n    __slots__ = (\"match\",)\n\n    match: Callable[[Decimal], bool]\n\n    def __init__(self, op: str, value: Decimal) -&gt; None:\n        if op == \"=\":\n            self.match = lambda x: x == value\n        elif op == \"&gt;=\":\n            self.match = lambda x: x &gt;= value\n        elif op == \"&lt;=\":\n            self.match = lambda x: x &lt;= value\n        elif op == \"&gt;\":\n            self.match = lambda x: x &gt; value\n        else:  # op == \"&lt;\":\n            self.match = lambda x: x &lt; value\n\n    def __call__(self, obj: Any) -&gt; bool:\n        # Compare to the absolute value to simplify this filter.\n        number = getattr(obj, \"number\", None)\n        return self.match(abs(number)) if number is not None else False\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterSyntaxParser","title":"<code>FilterSyntaxParser</code>","text":"Source code in <code>src/rustfava/core/filters.py</code> <pre><code>class FilterSyntaxParser:\n    precedence = ((\"left\", \"AND\"), (\"right\", \"UMINUS\"))\n    tokens = FilterSyntaxLexer.tokens\n\n    def p_error(self, _: Any) -&gt; None:\n        raise FilterParseError\n\n    def p_filter(self, p: list[Any]) -&gt; None:\n        \"\"\"\n        filter : expr\n        \"\"\"\n        p[0] = p[1]\n\n    def p_expr(self, p: list[Any]) -&gt; None:\n        \"\"\"\n        expr : simple_expr\n        \"\"\"\n        p[0] = p[1]\n\n    def p_expr_all(self, p: list[Any]) -&gt; None:\n        \"\"\"\n        expr : ALL expr ')'\n        \"\"\"\n        expr = p[2]\n\n        def _match_postings(entry: Directive) -&gt; bool:\n            return all(\n                expr(posting) for posting in getattr(entry, \"postings\", [])\n            )\n\n        p[0] = _match_postings\n\n    def p_expr_any(self, p: list[Any]) -&gt; None:\n        \"\"\"\n        expr : ANY expr ')'\n        \"\"\"\n        expr = p[2]\n\n        def _match_postings(entry: Directive) -&gt; bool:\n            return any(\n                expr(posting) for posting in getattr(entry, \"postings\", [])\n            )\n\n        p[0] = _match_postings\n\n    def p_expr_parentheses(self, p: list[Any]) -&gt; None:\n        \"\"\"\n        expr : '(' expr ')'\n        \"\"\"\n        p[0] = p[2]\n\n    def p_expr_and(self, p: list[Any]) -&gt; None:\n        \"\"\"\n        expr : expr expr %prec AND\n        \"\"\"\n        left, right = p[1], p[2]\n\n        def _and(entry: Directive) -&gt; bool:\n            return left(entry) and right(entry)  # type: ignore[no-any-return]\n\n        p[0] = _and\n\n    def p_expr_or(self, p: list[Any]) -&gt; None:\n        \"\"\"\n        expr : expr ',' expr\n        \"\"\"\n        left, right = p[1], p[3]\n\n        def _or(entry: Directive) -&gt; bool:\n            return left(entry) or right(entry)  # type: ignore[no-any-return]\n\n        p[0] = _or\n\n    def p_expr_negated(self, p: list[Any]) -&gt; None:\n        \"\"\"\n        expr : '-' expr %prec UMINUS\n        \"\"\"\n        func = p[2]\n\n        def _neg(entry: Directive) -&gt; bool:\n            return not func(entry)\n\n        p[0] = _neg\n\n    def p_simple_expr_TAG(self, p: list[Any]) -&gt; None:  # noqa: N802\n        \"\"\"\n        simple_expr : TAG\n        \"\"\"\n        tag = p[1]\n\n        def _tag(entry: Directive) -&gt; bool:\n            tags = getattr(entry, \"tags\", None)\n            return (tag in tags) if tags is not None else False\n\n        p[0] = _tag\n\n    def p_simple_expr_LINK(self, p: list[Any]) -&gt; None:  # noqa: N802\n        \"\"\"\n        simple_expr : LINK\n        \"\"\"\n        link = p[1]\n\n        def _link(entry: Directive) -&gt; bool:\n            links = getattr(entry, \"links\", None)\n            return (link in links) if links is not None else False\n\n        p[0] = _link\n\n    def p_simple_expr_STRING(self, p: list[Any]) -&gt; None:  # noqa: N802\n        \"\"\"\n        simple_expr : STRING\n        \"\"\"\n        string = p[1]\n        match = Match(string)\n\n        def _string(entry: Directive) -&gt; bool:\n            for name in (\"narration\", \"payee\", \"comment\"):\n                value = getattr(entry, name, \"\")\n                if value and match(value):\n                    return True\n            return False\n\n        p[0] = _string\n\n    def p_simple_expr_key(self, p: list[Any]) -&gt; None:\n        \"\"\"\n        simple_expr : KEY EQ_OP STRING\n                    | KEY CMP_OP NUMBER\n        \"\"\"\n        key, op, value = p[1], p[2], p[3]\n        match: Match | MatchAmount = (\n            Match(value) if op == \":\" else MatchAmount(op, value)\n        )\n\n        def _key(entry: Directive) -&gt; bool:\n            if hasattr(entry, key):\n                return match(getattr(entry, key) or \"\")\n            if entry.meta is not None and key in entry.meta:\n                return match(entry.meta.get(key))\n            return False\n\n        p[0] = _key\n\n    def p_simple_expr_units(self, p: list[Any]) -&gt; None:\n        \"\"\"\n        simple_expr : CMP_OP NUMBER\n        \"\"\"\n        op, value = p[1], p[2]\n        match = MatchAmount(op, value)\n\n        def _range(entry: Directive) -&gt; bool:\n            return any(\n                match(posting.units)\n                for posting in getattr(entry, \"postings\", [])\n            )\n\n        p[0] = _range\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterSyntaxParser.p_filter","title":"<code>p_filter(p)</code>","text":"<p>filter : expr</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>def p_filter(self, p: list[Any]) -&gt; None:\n    \"\"\"\n    filter : expr\n    \"\"\"\n    p[0] = p[1]\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterSyntaxParser.p_expr","title":"<code>p_expr(p)</code>","text":"<p>expr : simple_expr</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>def p_expr(self, p: list[Any]) -&gt; None:\n    \"\"\"\n    expr : simple_expr\n    \"\"\"\n    p[0] = p[1]\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterSyntaxParser.p_expr_all","title":"<code>p_expr_all(p)</code>","text":"<p>expr : ALL expr ')'</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>def p_expr_all(self, p: list[Any]) -&gt; None:\n    \"\"\"\n    expr : ALL expr ')'\n    \"\"\"\n    expr = p[2]\n\n    def _match_postings(entry: Directive) -&gt; bool:\n        return all(\n            expr(posting) for posting in getattr(entry, \"postings\", [])\n        )\n\n    p[0] = _match_postings\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterSyntaxParser.p_expr_any","title":"<code>p_expr_any(p)</code>","text":"<p>expr : ANY expr ')'</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>def p_expr_any(self, p: list[Any]) -&gt; None:\n    \"\"\"\n    expr : ANY expr ')'\n    \"\"\"\n    expr = p[2]\n\n    def _match_postings(entry: Directive) -&gt; bool:\n        return any(\n            expr(posting) for posting in getattr(entry, \"postings\", [])\n        )\n\n    p[0] = _match_postings\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterSyntaxParser.p_expr_parentheses","title":"<code>p_expr_parentheses(p)</code>","text":"<p>expr : '(' expr ')'</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>def p_expr_parentheses(self, p: list[Any]) -&gt; None:\n    \"\"\"\n    expr : '(' expr ')'\n    \"\"\"\n    p[0] = p[2]\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterSyntaxParser.p_expr_and","title":"<code>p_expr_and(p)</code>","text":"<p>expr : expr expr %prec AND</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>def p_expr_and(self, p: list[Any]) -&gt; None:\n    \"\"\"\n    expr : expr expr %prec AND\n    \"\"\"\n    left, right = p[1], p[2]\n\n    def _and(entry: Directive) -&gt; bool:\n        return left(entry) and right(entry)  # type: ignore[no-any-return]\n\n    p[0] = _and\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterSyntaxParser.p_expr_or","title":"<code>p_expr_or(p)</code>","text":"<p>expr : expr ',' expr</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>def p_expr_or(self, p: list[Any]) -&gt; None:\n    \"\"\"\n    expr : expr ',' expr\n    \"\"\"\n    left, right = p[1], p[3]\n\n    def _or(entry: Directive) -&gt; bool:\n        return left(entry) or right(entry)  # type: ignore[no-any-return]\n\n    p[0] = _or\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterSyntaxParser.p_expr_negated","title":"<code>p_expr_negated(p)</code>","text":"<p>expr : '-' expr %prec UMINUS</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>def p_expr_negated(self, p: list[Any]) -&gt; None:\n    \"\"\"\n    expr : '-' expr %prec UMINUS\n    \"\"\"\n    func = p[2]\n\n    def _neg(entry: Directive) -&gt; bool:\n        return not func(entry)\n\n    p[0] = _neg\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterSyntaxParser.p_simple_expr_TAG","title":"<code>p_simple_expr_TAG(p)</code>","text":"<p>simple_expr : TAG</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>def p_simple_expr_TAG(self, p: list[Any]) -&gt; None:  # noqa: N802\n    \"\"\"\n    simple_expr : TAG\n    \"\"\"\n    tag = p[1]\n\n    def _tag(entry: Directive) -&gt; bool:\n        tags = getattr(entry, \"tags\", None)\n        return (tag in tags) if tags is not None else False\n\n    p[0] = _tag\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterSyntaxParser.p_simple_expr_LINK","title":"<code>p_simple_expr_LINK(p)</code>","text":"<p>simple_expr : LINK</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>def p_simple_expr_LINK(self, p: list[Any]) -&gt; None:  # noqa: N802\n    \"\"\"\n    simple_expr : LINK\n    \"\"\"\n    link = p[1]\n\n    def _link(entry: Directive) -&gt; bool:\n        links = getattr(entry, \"links\", None)\n        return (link in links) if links is not None else False\n\n    p[0] = _link\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterSyntaxParser.p_simple_expr_STRING","title":"<code>p_simple_expr_STRING(p)</code>","text":"<p>simple_expr : STRING</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>def p_simple_expr_STRING(self, p: list[Any]) -&gt; None:  # noqa: N802\n    \"\"\"\n    simple_expr : STRING\n    \"\"\"\n    string = p[1]\n    match = Match(string)\n\n    def _string(entry: Directive) -&gt; bool:\n        for name in (\"narration\", \"payee\", \"comment\"):\n            value = getattr(entry, name, \"\")\n            if value and match(value):\n                return True\n        return False\n\n    p[0] = _string\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterSyntaxParser.p_simple_expr_key","title":"<code>p_simple_expr_key(p)</code>","text":"KEY EQ_OP STRING <p>| KEY CMP_OP NUMBER</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>def p_simple_expr_key(self, p: list[Any]) -&gt; None:\n    \"\"\"\n    simple_expr : KEY EQ_OP STRING\n                | KEY CMP_OP NUMBER\n    \"\"\"\n    key, op, value = p[1], p[2], p[3]\n    match: Match | MatchAmount = (\n        Match(value) if op == \":\" else MatchAmount(op, value)\n    )\n\n    def _key(entry: Directive) -&gt; bool:\n        if hasattr(entry, key):\n            return match(getattr(entry, key) or \"\")\n        if entry.meta is not None and key in entry.meta:\n            return match(entry.meta.get(key))\n        return False\n\n    p[0] = _key\n</code></pre>"},{"location":"api/#rustfava.core.filters.FilterSyntaxParser.p_simple_expr_units","title":"<code>p_simple_expr_units(p)</code>","text":"<p>simple_expr : CMP_OP NUMBER</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>def p_simple_expr_units(self, p: list[Any]) -&gt; None:\n    \"\"\"\n    simple_expr : CMP_OP NUMBER\n    \"\"\"\n    op, value = p[1], p[2]\n    match = MatchAmount(op, value)\n\n    def _range(entry: Directive) -&gt; bool:\n        return any(\n            match(posting.units)\n            for posting in getattr(entry, \"postings\", [])\n        )\n\n    p[0] = _range\n</code></pre>"},{"location":"api/#rustfava.core.filters.EntryFilter","title":"<code>EntryFilter</code>","text":"<p>               Bases: <code>ABC</code></p> <p>Filters a list of entries.</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>class EntryFilter(ABC):\n    \"\"\"Filters a list of entries.\"\"\"\n\n    @abstractmethod\n    def apply(self, entries: Sequence[Directive]) -&gt; Sequence[Directive]:\n        \"\"\"Filter a list of directives.\"\"\"\n</code></pre>"},{"location":"api/#rustfava.core.filters.EntryFilter.apply","title":"<code>apply(entries)</code>  <code>abstractmethod</code>","text":"<p>Filter a list of directives.</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>@abstractmethod\ndef apply(self, entries: Sequence[Directive]) -&gt; Sequence[Directive]:\n    \"\"\"Filter a list of directives.\"\"\"\n</code></pre>"},{"location":"api/#rustfava.core.filters.TimeFilter","title":"<code>TimeFilter</code>","text":"<p>               Bases: <code>EntryFilter</code></p> <p>Filter by dates.</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>class TimeFilter(EntryFilter):\n    \"\"\"Filter by dates.\"\"\"\n\n    __slots__ = (\"date_range\",)\n\n    def __init__(\n        self,\n        options: BeancountOptions,\n        fava_options: RustfavaOptions,\n        value: str,\n    ) -&gt; None:\n        del options  # unused\n        begin, end = parse_date(value, fava_options.fiscal_year_end)\n        if not begin or not end:\n            raise TimeFilterParseError(value)\n        self.date_range = DateRange(begin, end)\n\n    def apply(self, entries: Sequence[Directive]) -&gt; Sequence[Directive]:\n        from rustfava.rustledger.engine import RustledgerEngine\n        from rustfava.rustledger.types import directives_from_json\n        from rustfava.rustledger.types import directives_to_json\n\n        # Use native rustledger clamp_entries\n        engine = RustledgerEngine.get_instance()\n        entries_json = directives_to_json(list(entries))\n        result = engine.clamp_entries(\n            entries_json,\n            str(self.date_range.begin),\n            str(self.date_range.end),\n        )\n        return directives_from_json(result.get(\"entries\", []))\n</code></pre>"},{"location":"api/#rustfava.core.filters.AdvancedFilter","title":"<code>AdvancedFilter</code>","text":"<p>               Bases: <code>EntryFilter</code></p> <p>Filter by tags and links and keys.</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>class AdvancedFilter(EntryFilter):\n    \"\"\"Filter by tags and links and keys.\"\"\"\n\n    __slots__ = (\"_include\",)\n\n    def __init__(self, value: str) -&gt; None:\n        try:\n            tokens = LEXER.lex(value)\n            self._include = PARSE(\n                lexer=\"NONE\",\n                tokenfunc=lambda toks=tokens: next(toks, None),  # ty:ignore[invalid-argument-type]\n            )\n        except FilterError as exception:\n            exception.message += value\n            raise\n\n    def apply(self, entries: Sequence[Directive]) -&gt; Sequence[Directive]:\n        include = self._include\n        return [entry for entry in entries if include(entry)]\n</code></pre>"},{"location":"api/#rustfava.core.filters.AccountFilter","title":"<code>AccountFilter</code>","text":"<p>               Bases: <code>EntryFilter</code></p> <p>Filter by account.</p> <p>The filter string can either be a regular expression or a parent account.</p> Source code in <code>src/rustfava/core/filters.py</code> <pre><code>class AccountFilter(EntryFilter):\n    \"\"\"Filter by account.\n\n    The filter string can either be a regular expression or a parent account.\n    \"\"\"\n\n    __slots__ = (\"_match\", \"_value\")\n\n    def __init__(self, value: str) -&gt; None:\n        self._value = value\n        self._match = Match(value)\n\n    def apply(self, entries: Sequence[Directive]) -&gt; Sequence[Directive]:\n        value = self._value\n        if not value:\n            return entries\n        match = self._match\n        return [\n            entry\n            for entry in entries\n            if any(\n                _has_component(name, value) or match(name)\n                for name in get_entry_accounts(entry)\n            )\n        ]\n</code></pre>"},{"location":"api/#rustfava.core.group_entries","title":"<code>group_entries</code>","text":"<p>Entries grouped by type.</p>"},{"location":"api/#rustfava.core.group_entries.EntriesByType","title":"<code>EntriesByType</code>","text":"<p>               Bases: <code>NamedTuple</code></p> <p>Entries grouped by type.</p> Source code in <code>src/rustfava/core/group_entries.py</code> <pre><code>class EntriesByType(NamedTuple):\n    \"\"\"Entries grouped by type.\"\"\"\n\n    Balance: Sequence[abc.Balance]\n    Close: Sequence[abc.Close]\n    Commodity: Sequence[abc.Commodity]\n    Custom: Sequence[abc.Custom]\n    Document: Sequence[abc.Document]\n    Event: Sequence[abc.Event]\n    Note: Sequence[abc.Note]\n    Open: Sequence[abc.Open]\n    Pad: Sequence[abc.Pad]\n    Price: Sequence[abc.Price]\n    Query: Sequence[abc.Query]\n    Transaction: Sequence[abc.Transaction]\n</code></pre>"},{"location":"api/#rustfava.core.group_entries.TransactionPosting","title":"<code>TransactionPosting</code>","text":"<p>               Bases: <code>NamedTuple</code></p> <p>Pair of a transaction and a posting.</p> Source code in <code>src/rustfava/core/group_entries.py</code> <pre><code>class TransactionPosting(NamedTuple):\n    \"\"\"Pair of a transaction and a posting.\"\"\"\n\n    transaction: abc.Transaction\n    posting: abc.Posting\n</code></pre>"},{"location":"api/#rustfava.core.group_entries.group_entries_by_type","title":"<code>group_entries_by_type(entries)</code>","text":"<p>Group entries by type.</p> <p>Parameters:</p> Name Type Description Default <code>entries</code> <code>Sequence[Directive]</code> <p>A list of entries to group.</p> required <p>Returns:</p> Type Description <code>EntriesByType</code> <p>A namedtuple containing the grouped lists of entries.</p> Source code in <code>src/rustfava/core/group_entries.py</code> <pre><code>def group_entries_by_type(entries: Sequence[abc.Directive]) -&gt; EntriesByType:\n    \"\"\"Group entries by type.\n\n    Arguments:\n        entries: A list of entries to group.\n\n    Returns:\n        A namedtuple containing the grouped lists of entries.\n    \"\"\"\n    entries_by_type = EntriesByType(\n        [],\n        [],\n        [],\n        [],\n        [],\n        [],\n        [],\n        [],\n        [],\n        [],\n        [],\n        [],\n    )\n    for entry in entries:\n        # Handle both beancount types (e.g., \"Transaction\") and\n        # rustledger types (e.g., \"RLTransaction\")\n        type_name = entry.__class__.__name__\n        if type_name.startswith(\"RL\"):\n            type_name = type_name[2:]  # Strip \"RL\" prefix\n        getattr(entries_by_type, type_name).append(entry)\n    return entries_by_type\n</code></pre>"},{"location":"api/#rustfava.core.group_entries.group_entries_by_account","title":"<code>group_entries_by_account(entries)</code>","text":"<p>Group entries by account.</p> <p>Parameters:</p> Name Type Description Default <code>entries</code> <code>Sequence[Directive]</code> <p>A list of entries.</p> required <p>Returns:</p> Type Description <code>Mapping[str, Sequence[Directive | TransactionPosting]]</code> <p>A dict mapping account names to their entries.</p> Source code in <code>src/rustfava/core/group_entries.py</code> <pre><code>def group_entries_by_account(\n    entries: Sequence[abc.Directive],\n) -&gt; Mapping[str, Sequence[abc.Directive | TransactionPosting]]:\n    \"\"\"Group entries by account.\n\n    Arguments:\n        entries: A list of entries.\n\n    Returns:\n        A dict mapping account names to their entries.\n    \"\"\"\n    res: dict[str, list[abc.Directive | TransactionPosting]] = defaultdict(\n        list,\n    )\n\n    for entry in entries:\n        if isinstance(entry, abc.Transaction):\n            for posting in entry.postings:\n                res[posting.account].append(TransactionPosting(entry, posting))\n        else:\n            for account in get_entry_accounts(entry):\n                res[account].append(entry)\n\n    return dict(sorted(res.items()))\n</code></pre>"},{"location":"api/#rustfava.core.ingest","title":"<code>ingest</code>","text":"<p>Ingest helper functions.</p>"},{"location":"api/#rustfava.core.ingest.IngestError","title":"<code>IngestError</code>  <code>dataclass</code>","text":"<p>               Bases: <code>BeancountError</code></p> <p>An error with one of the importers.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>class IngestError(BeancountError):\n    \"\"\"An error with one of the importers.\"\"\"\n</code></pre>"},{"location":"api/#rustfava.core.ingest.ImporterMethodCallError","title":"<code>ImporterMethodCallError</code>","text":"<p>               Bases: <code>RustfavaAPIError</code></p> <p>Error calling one of the importer methods.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>class ImporterMethodCallError(RustfavaAPIError):\n    \"\"\"Error calling one of the importer methods.\"\"\"\n\n    def __init__(self) -&gt; None:\n        super().__init__(\n            f\"Error calling method on importer:\\n\\n{traceback.format_exc()}\"\n        )\n</code></pre>"},{"location":"api/#rustfava.core.ingest.ImporterInvalidTypeError","title":"<code>ImporterInvalidTypeError</code>","text":"<p>               Bases: <code>RustfavaAPIError</code></p> <p>One of the importer methods returned an unexpected type.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>class ImporterInvalidTypeError(RustfavaAPIError):\n    \"\"\"One of the importer methods returned an unexpected type.\"\"\"\n\n    def __init__(self, attr: str, expected: type[Any], actual: Any) -&gt; None:\n        super().__init__(\n            f\"Got unexpected type from importer as {attr}:\"\n            f\" expected {expected!s}, got {type(actual)!s}:\"\n        )\n</code></pre>"},{"location":"api/#rustfava.core.ingest.ImporterExtractError","title":"<code>ImporterExtractError</code>","text":"<p>               Bases: <code>ImporterMethodCallError</code></p> <p>Error calling extract for importer.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>class ImporterExtractError(ImporterMethodCallError):\n    \"\"\"Error calling extract for importer.\"\"\"\n</code></pre>"},{"location":"api/#rustfava.core.ingest.MissingImporterConfigError","title":"<code>MissingImporterConfigError</code>","text":"<p>               Bases: <code>RustfavaAPIError</code></p> <p>Missing import-config option.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>class MissingImporterConfigError(RustfavaAPIError):\n    \"\"\"Missing import-config option.\"\"\"\n\n    def __init__(self) -&gt; None:\n        super().__init__(\"Missing import-config option\")\n</code></pre>"},{"location":"api/#rustfava.core.ingest.MissingImporterDirsError","title":"<code>MissingImporterDirsError</code>","text":"<p>               Bases: <code>RustfavaAPIError</code></p> <p>You need to set at least one imports-dir.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>class MissingImporterDirsError(RustfavaAPIError):\n    \"\"\"You need to set at least one imports-dir.\"\"\"\n\n    def __init__(self) -&gt; None:\n        super().__init__(\"You need to set at least one imports-dir.\")\n</code></pre>"},{"location":"api/#rustfava.core.ingest.ImportConfigLoadError","title":"<code>ImportConfigLoadError</code>","text":"<p>               Bases: <code>RustfavaAPIError</code></p> <p>Error on loading the import config.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>class ImportConfigLoadError(RustfavaAPIError):\n    \"\"\"Error on loading the import config.\"\"\"\n</code></pre>"},{"location":"api/#rustfava.core.ingest.FileImportInfo","title":"<code>FileImportInfo</code>  <code>dataclass</code>","text":"<p>Info about one file/importer combination.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>@dataclass(frozen=True)\nclass FileImportInfo:\n    \"\"\"Info about one file/importer combination.\"\"\"\n\n    importer_name: str\n    account: str\n    date: datetime.date\n    name: str\n</code></pre>"},{"location":"api/#rustfava.core.ingest.FileImporters","title":"<code>FileImporters</code>  <code>dataclass</code>","text":"<p>Importers for a file.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>@dataclass(frozen=True)\nclass FileImporters:\n    \"\"\"Importers for a file.\"\"\"\n\n    name: str\n    basename: str\n    importers: list[FileImportInfo]\n</code></pre>"},{"location":"api/#rustfava.core.ingest.WrappedImporter","title":"<code>WrappedImporter</code>","text":"<p>A wrapper to safely call importer methods.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>class WrappedImporter:\n    \"\"\"A wrapper to safely call importer methods.\"\"\"\n\n    importer: BeanImporterProtocol | Importer\n\n    def __init__(self, importer: BeanImporterProtocol | Importer) -&gt; None:\n        self.importer = importer\n\n    @property\n    @_catch_any\n    def name(self) -&gt; str:\n        \"\"\"Get the name of the importer.\"\"\"\n        importer = self.importer\n        name = (\n            importer.name\n            if isinstance(importer, Importer)\n            else importer.name()\n        )\n        return _assert_type(\"name\", name, str)\n\n    @_catch_any\n    def identify(self: WrappedImporter, path: Path) -&gt; bool:\n        \"\"\"Whether the importer is matching the file.\"\"\"\n        importer = self.importer\n        matches = (\n            importer.identify(str(path))\n            if isinstance(importer, Importer)\n            else importer.identify(get_cached_file(path))\n        )\n        return _assert_type(\"identify\", matches, bool)\n\n    @_catch_any\n    def file_import_info(self, path: Path) -&gt; FileImportInfo:\n        \"\"\"Generate info about a file with an importer.\"\"\"\n        importer = self.importer\n        if isinstance(importer, Importer):\n            str_path = str(path)\n            account = importer.account(str_path)\n            date = importer.date(str_path)\n            filename = importer.filename(str_path)\n        else:\n            file = get_cached_file(path)\n            account = importer.file_account(file)\n            date = importer.file_date(file)\n            filename = importer.file_name(file)\n\n        return FileImportInfo(\n            self.name,\n            _assert_type(\"account\", account or \"\", str),\n            _assert_type(\"date\", date or local_today(), datetime.date),\n            _assert_type(\"filename\", filename or path.name, str),\n        )\n</code></pre>"},{"location":"api/#rustfava.core.ingest.WrappedImporter.name","title":"<code>name</code>  <code>property</code>","text":"<p>Get the name of the importer.</p>"},{"location":"api/#rustfava.core.ingest.WrappedImporter.identify","title":"<code>identify(path)</code>","text":"<p>Whether the importer is matching the file.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>@_catch_any\ndef identify(self: WrappedImporter, path: Path) -&gt; bool:\n    \"\"\"Whether the importer is matching the file.\"\"\"\n    importer = self.importer\n    matches = (\n        importer.identify(str(path))\n        if isinstance(importer, Importer)\n        else importer.identify(get_cached_file(path))\n    )\n    return _assert_type(\"identify\", matches, bool)\n</code></pre>"},{"location":"api/#rustfava.core.ingest.WrappedImporter.file_import_info","title":"<code>file_import_info(path)</code>","text":"<p>Generate info about a file with an importer.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>@_catch_any\ndef file_import_info(self, path: Path) -&gt; FileImportInfo:\n    \"\"\"Generate info about a file with an importer.\"\"\"\n    importer = self.importer\n    if isinstance(importer, Importer):\n        str_path = str(path)\n        account = importer.account(str_path)\n        date = importer.date(str_path)\n        filename = importer.filename(str_path)\n    else:\n        file = get_cached_file(path)\n        account = importer.file_account(file)\n        date = importer.file_date(file)\n        filename = importer.file_name(file)\n\n    return FileImportInfo(\n        self.name,\n        _assert_type(\"account\", account or \"\", str),\n        _assert_type(\"date\", date or local_today(), datetime.date),\n        _assert_type(\"filename\", filename or path.name, str),\n    )\n</code></pre>"},{"location":"api/#rustfava.core.ingest.IngestModule","title":"<code>IngestModule</code>","text":"<p>               Bases: <code>FavaModule</code></p> <p>Exposes ingest functionality.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>class IngestModule(FavaModule):\n    \"\"\"Exposes ingest functionality.\"\"\"\n\n    def __init__(self, ledger: RustfavaLedger) -&gt; None:\n        super().__init__(ledger)\n        self.importers: Mapping[str, WrappedImporter] = {}\n        self.hooks: Hooks = []\n        self.mtime: int | None = None\n        self.errors: list[IngestError] = []\n\n    @property\n    def module_path(self) -&gt; Path | None:\n        \"\"\"The path to the importer configuration.\"\"\"\n        config_path = self.ledger.fava_options.import_config\n        if not config_path:\n            return None\n        return self.ledger.join_path(config_path)\n\n    def _error(self, msg: str) -&gt; None:\n        self.errors.append(\n            IngestError(\n                {\"filename\": str(self.module_path), \"lineno\": 0},\n                msg,\n                None,\n            ),\n        )\n\n    def load_file(self) -&gt; None:  # noqa: D102\n        self.errors = []\n        module_path = self.module_path\n        if module_path is None:\n            return\n\n        if not module_path.exists():\n            self._error(\"Import config does not exist\")\n            return\n\n        new_mtime = module_path.stat().st_mtime_ns\n        if new_mtime == self.mtime:\n            return\n\n        try:\n            self.importers, self.hooks = load_import_config(module_path)\n            self.mtime = new_mtime\n        except RustfavaAPIError as error:  # pragma: no cover\n            msg = f\"Error in import config '{module_path}': {error!s}\"\n            self._error(msg)\n\n    def import_data(self) -&gt; list[FileImporters]:\n        \"\"\"Identify files and importers that can be imported.\n\n        Returns:\n            A list of :class:`.FileImportInfo`.\n        \"\"\"\n        if not self.importers:\n            return []\n\n        importers = list(self.importers.values())\n\n        ret: list[FileImporters] = []\n        for directory in self.ledger.fava_options.import_dirs:\n            full_path = self.ledger.join_path(directory)\n            ret.extend(find_imports(importers, full_path))\n\n        return ret\n\n    def extract(self, filename: str, importer_name: str) -&gt; list[Directive]:\n        \"\"\"Extract entries from filename with the specified importer.\n\n        Args:\n            filename: The full path to a file.\n            importer_name: The name of an importer that matched the file.\n\n        Returns:\n            A list of new imported entries.\n        \"\"\"\n        if not self.module_path:\n            raise MissingImporterConfigError\n\n        # reload (if changed)\n        self.load_file()\n\n        try:\n            path = Path(filename)\n            importer = self.importers[importer_name]\n            new_entries = extract_from_file(\n                importer,\n                path,\n                existing_entries=self.ledger.all_entries,\n            )\n        except Exception as exc:\n            raise ImporterExtractError from exc\n\n        for hook_fn in self.hooks:\n            annotations = get_annotations(hook_fn)\n            if any(\"Importer\" in a for a in annotations.values()):\n                importer_info = importer.file_import_info(path)\n                new_entries_list: HookOutput = [\n                    (\n                        filename,\n                        new_entries,\n                        importer_info.account,\n                        importer.importer,\n                    )\n                ]\n            else:\n                new_entries_list = [(filename, new_entries)]\n\n            new_entries_list = hook_fn(\n                new_entries_list,\n                self.ledger.all_entries,\n            )\n\n            new_entries = new_entries_list[0][1]\n\n        return new_entries\n</code></pre>"},{"location":"api/#rustfava.core.ingest.IngestModule.module_path","title":"<code>module_path</code>  <code>property</code>","text":"<p>The path to the importer configuration.</p>"},{"location":"api/#rustfava.core.ingest.IngestModule.import_data","title":"<code>import_data()</code>","text":"<p>Identify files and importers that can be imported.</p> <p>Returns:</p> Type Description <code>list[FileImporters]</code> <p>A list of :class:<code>.FileImportInfo</code>.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>def import_data(self) -&gt; list[FileImporters]:\n    \"\"\"Identify files and importers that can be imported.\n\n    Returns:\n        A list of :class:`.FileImportInfo`.\n    \"\"\"\n    if not self.importers:\n        return []\n\n    importers = list(self.importers.values())\n\n    ret: list[FileImporters] = []\n    for directory in self.ledger.fava_options.import_dirs:\n        full_path = self.ledger.join_path(directory)\n        ret.extend(find_imports(importers, full_path))\n\n    return ret\n</code></pre>"},{"location":"api/#rustfava.core.ingest.IngestModule.extract","title":"<code>extract(filename, importer_name)</code>","text":"<p>Extract entries from filename with the specified importer.</p> <p>Parameters:</p> Name Type Description Default <code>filename</code> <code>str</code> <p>The full path to a file.</p> required <code>importer_name</code> <code>str</code> <p>The name of an importer that matched the file.</p> required <p>Returns:</p> Type Description <code>list[Directive]</code> <p>A list of new imported entries.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>def extract(self, filename: str, importer_name: str) -&gt; list[Directive]:\n    \"\"\"Extract entries from filename with the specified importer.\n\n    Args:\n        filename: The full path to a file.\n        importer_name: The name of an importer that matched the file.\n\n    Returns:\n        A list of new imported entries.\n    \"\"\"\n    if not self.module_path:\n        raise MissingImporterConfigError\n\n    # reload (if changed)\n    self.load_file()\n\n    try:\n        path = Path(filename)\n        importer = self.importers[importer_name]\n        new_entries = extract_from_file(\n            importer,\n            path,\n            existing_entries=self.ledger.all_entries,\n        )\n    except Exception as exc:\n        raise ImporterExtractError from exc\n\n    for hook_fn in self.hooks:\n        annotations = get_annotations(hook_fn)\n        if any(\"Importer\" in a for a in annotations.values()):\n            importer_info = importer.file_import_info(path)\n            new_entries_list: HookOutput = [\n                (\n                    filename,\n                    new_entries,\n                    importer_info.account,\n                    importer.importer,\n                )\n            ]\n        else:\n            new_entries_list = [(filename, new_entries)]\n\n        new_entries_list = hook_fn(\n            new_entries_list,\n            self.ledger.all_entries,\n        )\n\n        new_entries = new_entries_list[0][1]\n\n    return new_entries\n</code></pre>"},{"location":"api/#rustfava.core.ingest.walk_dir","title":"<code>walk_dir(directory)</code>","text":"<p>Walk through all files in dir.</p> <p>Ignores common dot-directories like .git, .cache. .venv, see IGNORE_DIRS.</p> <p>Parameters:</p> Name Type Description Default <code>directory</code> <code>Path</code> <p>The directory to start in.</p> required <p>Yields:</p> Type Description <code>Iterable[Path]</code> <p>All full paths under directory, ignoring some directories.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>def walk_dir(directory: Path) -&gt; Iterable[Path]:\n    \"\"\"Walk through all files in dir.\n\n    Ignores common dot-directories like .git, .cache. .venv, see IGNORE_DIRS.\n\n    Args:\n        directory: The directory to start in.\n\n    Yields:\n        All full paths under directory, ignoring some directories.\n    \"\"\"\n    for root, dirs, filenames in os.walk(directory):\n        dirs[:] = sorted(d for d in dirs if d not in IGNORE_DIRS)\n        root_path = Path(root)\n        for filename in sorted(filenames):\n            yield root_path / filename\n</code></pre>"},{"location":"api/#rustfava.core.ingest.get_cached_file","title":"<code>get_cached_file(path)</code>","text":"<p>Get a cached FileMemo.</p> <p>This checks the file's mtime before getting it from the Cache. In addition to using the beangulp cache.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>def get_cached_file(path: Path) -&gt; FileMemo:\n    \"\"\"Get a cached FileMemo.\n\n    This checks the file's mtime before getting it from the Cache.\n    In addition to using the beangulp cache.\n    \"\"\"\n    mtime = path.stat().st_mtime_ns\n    filename = str(path)\n    cached = _CACHE.get(path)\n    if cached:\n        mtime_cached, memo_cached = cached\n        if mtime &lt;= mtime_cached:  # pragma: no cover\n            return memo_cached\n    memo: FileMemo = cache._FileMemo(filename)  # noqa: SLF001\n    cache._CACHE[filename] = memo  # noqa: SLF001\n    _CACHE[path] = (mtime, memo)\n    return memo\n</code></pre>"},{"location":"api/#rustfava.core.ingest.find_imports","title":"<code>find_imports(config, directory)</code>","text":"<p>Pair files and matching importers.</p> <p>Yields:</p> Type Description <code>Iterable[FileImporters]</code> <p>For each file in directory, a pair of its filename and the matching</p> <code>Iterable[FileImporters]</code> <p>importers.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>def find_imports(\n    config: Sequence[WrappedImporter], directory: Path\n) -&gt; Iterable[FileImporters]:\n    \"\"\"Pair files and matching importers.\n\n    Yields:\n        For each file in directory, a pair of its filename and the matching\n        importers.\n    \"\"\"\n    for path in walk_dir(directory):\n        stat = path.stat()\n        if stat.st_size &gt; _FILE_TOO_LARGE_THRESHOLD:  # pragma: no cover\n            continue\n\n        importers = [\n            importer.file_import_info(path)\n            for importer in config\n            if importer.identify(path)\n        ]\n        yield FileImporters(\n            name=str(path), basename=path.name, importers=importers\n        )\n</code></pre>"},{"location":"api/#rustfava.core.ingest.extract_from_file","title":"<code>extract_from_file(wrapped_importer, path, existing_entries)</code>","text":"<p>Import entries from a document.</p> <p>Parameters:</p> Name Type Description Default <code>wrapped_importer</code> <code>WrappedImporter</code> <p>The importer instance to handle the document.</p> required <code>path</code> <code>Path</code> <p>Filesystem path to the document.</p> required <code>existing_entries</code> <code>Sequence[Directive]</code> <p>Existing entries.</p> required <p>Returns:</p> Type Description <code>list[Directive]</code> <p>The list of imported entries.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>def extract_from_file(\n    wrapped_importer: WrappedImporter,\n    path: Path,\n    existing_entries: Sequence[Directive],\n) -&gt; list[Directive]:\n    \"\"\"Import entries from a document.\n\n    Args:\n      wrapped_importer: The importer instance to handle the document.\n      path: Filesystem path to the document.\n      existing_entries: Existing entries.\n\n    Returns:\n      The list of imported entries.\n    \"\"\"\n    filename = str(path)\n    importer = wrapped_importer.importer\n    if isinstance(importer, Importer):\n        entries = importer.extract(filename, existing=existing_entries)\n    else:\n        file = get_cached_file(path)\n        entries = (\n            importer.extract(file, existing_entries=existing_entries)\n            if \"existing_entries\" in signature(importer.extract).parameters\n            else importer.extract(file)\n        ) or []\n\n    if hasattr(importer, \"sort\"):\n        importer.sort(entries)\n    else:\n        entries.sort(key=_incomplete_sortkey)\n    if isinstance(importer, Importer):\n        importer.deduplicate(entries, existing=existing_entries)\n    return entries\n</code></pre>"},{"location":"api/#rustfava.core.ingest.load_import_config","title":"<code>load_import_config(module_path)</code>","text":"<p>Load the given import config and extract importers and hooks.</p> <p>Parameters:</p> Name Type Description Default <code>module_path</code> <code>Path</code> <p>Path to the import config.</p> required <p>Returns:</p> Type Description <code>tuple[Mapping[str, WrappedImporter], Hooks]</code> <p>A pair of the importers (by name) and the list of hooks.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>def load_import_config(\n    module_path: Path,\n) -&gt; tuple[Mapping[str, WrappedImporter], Hooks]:\n    \"\"\"Load the given import config and extract importers and hooks.\n\n    Args:\n        module_path: Path to the import config.\n\n    Returns:\n        A pair of the importers (by name) and the list of hooks.\n    \"\"\"\n    try:\n        mod = run_path(str(module_path))\n    except Exception as error:  # pragma: no cover\n        message = traceback.format_exc()\n        raise ImportConfigLoadError(message) from error\n\n    if \"CONFIG\" not in mod:\n        msg = \"CONFIG is missing\"\n        raise ImportConfigLoadError(msg)\n    if not isinstance(mod[\"CONFIG\"], list):  # pragma: no cover\n        msg = \"CONFIG is not a list\"\n        raise ImportConfigLoadError(msg)\n\n    config = mod[\"CONFIG\"]\n    hooks = DEFAULT_HOOKS\n    if \"HOOKS\" in mod:  # pragma: no cover\n        hooks = mod[\"HOOKS\"]\n        if not isinstance(hooks, list) or not all(\n            callable(fn) for fn in hooks\n        ):\n            msg = \"HOOKS is not a list of callables\"\n            raise ImportConfigLoadError(msg)\n    importers = {}\n    for importer in config:\n        if not isinstance(\n            importer, (BeanImporterProtocol, Importer)\n        ):  # pragma: no cover\n            name = importer.__class__.__name__\n            msg = (\n                f\"Importer class '{name}' in '{module_path}' does \"\n                \"not satisfy importer protocol\"\n            )\n            raise ImportConfigLoadError(msg)\n        wrapped_importer = WrappedImporter(importer)\n        if wrapped_importer.name in importers:\n            msg = f\"Duplicate importer name found: {wrapped_importer.name}\"\n            raise ImportConfigLoadError(msg)\n        importers[wrapped_importer.name] = wrapped_importer\n    return importers, hooks\n</code></pre>"},{"location":"api/#rustfava.core.ingest.filepath_in_primary_imports_folder","title":"<code>filepath_in_primary_imports_folder(filename, ledger)</code>","text":"<p>File path for a document to upload to the primary import folder.</p> <p>Parameters:</p> Name Type Description Default <code>filename</code> <code>str</code> <p>The filename of the document.</p> required <code>ledger</code> <code>RustfavaLedger</code> <p>The RustfavaLedger.</p> required <p>Returns:</p> Type Description <code>Path</code> <p>The path that the document should be saved at.</p> Source code in <code>src/rustfava/core/ingest.py</code> <pre><code>def filepath_in_primary_imports_folder(\n    filename: str,\n    ledger: RustfavaLedger,\n) -&gt; Path:\n    \"\"\"File path for a document to upload to the primary import folder.\n\n    Args:\n        filename: The filename of the document.\n        ledger: The RustfavaLedger.\n\n    Returns:\n        The path that the document should be saved at.\n    \"\"\"\n    primary_imports_folder = next(iter(ledger.fava_options.import_dirs), None)\n    if primary_imports_folder is None:\n        raise MissingImporterDirsError\n\n    filename = filename.replace(sep, \" \")\n    if altsep:  # pragma: no cover\n        filename = filename.replace(altsep, \" \")\n\n    return ledger.join_path(primary_imports_folder, filename)\n</code></pre>"},{"location":"api/#rustfava.core.inventory","title":"<code>inventory</code>","text":"<p>Alternative implementation of Beancount's Inventory.</p>"},{"location":"api/#rustfava.core.inventory.SimpleCounterInventory","title":"<code>SimpleCounterInventory</code>","text":"<p>               Bases: <code>dict[str, Decimal]</code></p> <p>A simple inventory mapping just strings to numbers.</p> Source code in <code>src/rustfava/core/inventory.py</code> <pre><code>class SimpleCounterInventory(dict[str, Decimal]):\n    \"\"\"A simple inventory mapping just strings to numbers.\"\"\"\n\n    def is_empty(self) -&gt; bool:\n        \"\"\"Check if the inventory is empty.\"\"\"\n        return not bool(self)\n\n    def add(self, key: str, number: Decimal) -&gt; None:\n        \"\"\"Add a number to key.\"\"\"\n        new_num = number + self.get(key, ZERO)\n        if new_num == ZERO:\n            self.pop(key, None)\n        else:\n            self[key] = new_num\n\n    def __iter__(self) -&gt; Iterator[str]:\n        raise NotImplementedError\n\n    def __neg__(self) -&gt; SimpleCounterInventory:\n        return SimpleCounterInventory({key: -num for key, num in self.items()})\n\n    def reduce(\n        self,\n        reducer: Callable[Concatenate[Position, P], Amount],\n        *args: P.args,\n        **_kwargs: P.kwargs,\n    ) -&gt; SimpleCounterInventory:\n        \"\"\"Reduce inventory.\"\"\"\n        counter = SimpleCounterInventory()\n        for currency, number in self.items():\n            pos = _Position(_Amount(number, currency), None)\n            amount = reducer(pos, *args)  # type: ignore[call-arg]\n            counter.add(amount.currency, amount.number)\n        return counter\n</code></pre>"},{"location":"api/#rustfava.core.inventory.SimpleCounterInventory.is_empty","title":"<code>is_empty()</code>","text":"<p>Check if the inventory is empty.</p> Source code in <code>src/rustfava/core/inventory.py</code> <pre><code>def is_empty(self) -&gt; bool:\n    \"\"\"Check if the inventory is empty.\"\"\"\n    return not bool(self)\n</code></pre>"},{"location":"api/#rustfava.core.inventory.SimpleCounterInventory.add","title":"<code>add(key, number)</code>","text":"<p>Add a number to key.</p> Source code in <code>src/rustfava/core/inventory.py</code> <pre><code>def add(self, key: str, number: Decimal) -&gt; None:\n    \"\"\"Add a number to key.\"\"\"\n    new_num = number + self.get(key, ZERO)\n    if new_num == ZERO:\n        self.pop(key, None)\n    else:\n        self[key] = new_num\n</code></pre>"},{"location":"api/#rustfava.core.inventory.SimpleCounterInventory.reduce","title":"<code>reduce(reducer, *args, **_kwargs)</code>","text":"<p>Reduce inventory.</p> Source code in <code>src/rustfava/core/inventory.py</code> <pre><code>def reduce(\n    self,\n    reducer: Callable[Concatenate[Position, P], Amount],\n    *args: P.args,\n    **_kwargs: P.kwargs,\n) -&gt; SimpleCounterInventory:\n    \"\"\"Reduce inventory.\"\"\"\n    counter = SimpleCounterInventory()\n    for currency, number in self.items():\n        pos = _Position(_Amount(number, currency), None)\n        amount = reducer(pos, *args)  # type: ignore[call-arg]\n        counter.add(amount.currency, amount.number)\n    return counter\n</code></pre>"},{"location":"api/#rustfava.core.inventory.CounterInventory","title":"<code>CounterInventory</code>","text":"<p>               Bases: <code>dict[InventoryKey, Decimal]</code></p> <p>A lightweight inventory.</p> <p>This is intended as a faster alternative to Beancount's Inventory class. Due to not using a list, for inventories with a lot of different positions, inserting is much faster.</p> <p>The keys should be tuples <code>(currency, cost)</code>.</p> Source code in <code>src/rustfava/core/inventory.py</code> <pre><code>class CounterInventory(dict[InventoryKey, Decimal]):\n    \"\"\"A lightweight inventory.\n\n    This is intended as a faster alternative to Beancount's Inventory class.\n    Due to not using a list, for inventories with a lot of different positions,\n    inserting is much faster.\n\n    The keys should be tuples ``(currency, cost)``.\n    \"\"\"\n\n    def is_empty(self) -&gt; bool:\n        \"\"\"Check if the inventory is empty.\"\"\"\n        return not bool(self)\n\n    def add(self, key: InventoryKey, number: Decimal) -&gt; None:\n        \"\"\"Add a number to key.\"\"\"\n        new_num = number + self.get(key, ZERO)\n        if new_num == ZERO:\n            self.pop(key, None)\n        else:\n            self[key] = new_num\n\n    def __iter__(self) -&gt; Iterator[InventoryKey]:\n        raise NotImplementedError\n\n    def to_strings(self) -&gt; list[str]:\n        \"\"\"Print as a list of strings (e.g. for snapshot tests).\"\"\"\n        strings = []\n        for (currency, cost), number in self.items():\n            if cost is None:\n                strings.append(f\"{number} {currency}\")\n            else:\n                cost_str = cost_to_string(cost)\n                strings.append(f\"{number} {currency} {{{cost_str}}}\")\n        return strings\n\n    def reduce(\n        self,\n        reducer: Callable[Concatenate[Position, P], Amount],\n        *args: P.args,\n        **_kwargs: P.kwargs,\n    ) -&gt; SimpleCounterInventory:\n        \"\"\"Reduce inventory.\n\n        Note that this returns a simple :class:`CounterInventory` with just\n        currencies as keys.\n        \"\"\"\n        counter = SimpleCounterInventory()\n        for (currency, cost), number in self.items():\n            pos = _Position(_Amount(number, currency), cost)\n            amount = reducer(pos, *args)  # type: ignore[call-arg]\n            counter.add(amount.currency, amount.number)\n        return counter\n\n    def add_amount(self, amount: Amount, cost: Cost | None = None) -&gt; None:\n        \"\"\"Add an Amount to the inventory.\"\"\"\n        key = (amount.currency, cost)\n        self.add(key, amount.number)\n\n    def add_position(self, pos: Position) -&gt; None:\n        \"\"\"Add a Position or Posting to the inventory.\"\"\"\n        # Skip positions with missing units (can happen with parse errors)\n        if pos.units is None:\n            return\n        self.add_amount(pos.units, pos.cost)\n\n    def __neg__(self) -&gt; CounterInventory:\n        return CounterInventory({key: -num for key, num in self.items()})\n\n    def __add__(self, other: CounterInventory) -&gt; CounterInventory:\n        counter = CounterInventory(self)\n        counter.add_inventory(other)\n        return counter\n\n    def add_inventory(self, counter: CounterInventory) -&gt; None:\n        \"\"\"Add another :class:`CounterInventory`.\"\"\"\n        if not self:\n            self.update(counter)\n        else:\n            self_get = self.get\n            for key, num in counter.items():\n                new_num = num + self_get(key, ZERO)\n                if new_num == ZERO:\n                    self.pop(key, None)\n                else:\n                    self[key] = new_num\n</code></pre>"},{"location":"api/#rustfava.core.inventory.CounterInventory.is_empty","title":"<code>is_empty()</code>","text":"<p>Check if the inventory is empty.</p> Source code in <code>src/rustfava/core/inventory.py</code> <pre><code>def is_empty(self) -&gt; bool:\n    \"\"\"Check if the inventory is empty.\"\"\"\n    return not bool(self)\n</code></pre>"},{"location":"api/#rustfava.core.inventory.CounterInventory.add","title":"<code>add(key, number)</code>","text":"<p>Add a number to key.</p> Source code in <code>src/rustfava/core/inventory.py</code> <pre><code>def add(self, key: InventoryKey, number: Decimal) -&gt; None:\n    \"\"\"Add a number to key.\"\"\"\n    new_num = number + self.get(key, ZERO)\n    if new_num == ZERO:\n        self.pop(key, None)\n    else:\n        self[key] = new_num\n</code></pre>"},{"location":"api/#rustfava.core.inventory.CounterInventory.to_strings","title":"<code>to_strings()</code>","text":"<p>Print as a list of strings (e.g. for snapshot tests).</p> Source code in <code>src/rustfava/core/inventory.py</code> <pre><code>def to_strings(self) -&gt; list[str]:\n    \"\"\"Print as a list of strings (e.g. for snapshot tests).\"\"\"\n    strings = []\n    for (currency, cost), number in self.items():\n        if cost is None:\n            strings.append(f\"{number} {currency}\")\n        else:\n            cost_str = cost_to_string(cost)\n            strings.append(f\"{number} {currency} {{{cost_str}}}\")\n    return strings\n</code></pre>"},{"location":"api/#rustfava.core.inventory.CounterInventory.reduce","title":"<code>reduce(reducer, *args, **_kwargs)</code>","text":"<p>Reduce inventory.</p> <p>Note that this returns a simple :class:<code>CounterInventory</code> with just currencies as keys.</p> Source code in <code>src/rustfava/core/inventory.py</code> <pre><code>def reduce(\n    self,\n    reducer: Callable[Concatenate[Position, P], Amount],\n    *args: P.args,\n    **_kwargs: P.kwargs,\n) -&gt; SimpleCounterInventory:\n    \"\"\"Reduce inventory.\n\n    Note that this returns a simple :class:`CounterInventory` with just\n    currencies as keys.\n    \"\"\"\n    counter = SimpleCounterInventory()\n    for (currency, cost), number in self.items():\n        pos = _Position(_Amount(number, currency), cost)\n        amount = reducer(pos, *args)  # type: ignore[call-arg]\n        counter.add(amount.currency, amount.number)\n    return counter\n</code></pre>"},{"location":"api/#rustfava.core.inventory.CounterInventory.add_amount","title":"<code>add_amount(amount, cost=None)</code>","text":"<p>Add an Amount to the inventory.</p> Source code in <code>src/rustfava/core/inventory.py</code> <pre><code>def add_amount(self, amount: Amount, cost: Cost | None = None) -&gt; None:\n    \"\"\"Add an Amount to the inventory.\"\"\"\n    key = (amount.currency, cost)\n    self.add(key, amount.number)\n</code></pre>"},{"location":"api/#rustfava.core.inventory.CounterInventory.add_position","title":"<code>add_position(pos)</code>","text":"<p>Add a Position or Posting to the inventory.</p> Source code in <code>src/rustfava/core/inventory.py</code> <pre><code>def add_position(self, pos: Position) -&gt; None:\n    \"\"\"Add a Position or Posting to the inventory.\"\"\"\n    # Skip positions with missing units (can happen with parse errors)\n    if pos.units is None:\n        return\n    self.add_amount(pos.units, pos.cost)\n</code></pre>"},{"location":"api/#rustfava.core.inventory.CounterInventory.add_inventory","title":"<code>add_inventory(counter)</code>","text":"<p>Add another :class:<code>CounterInventory</code>.</p> Source code in <code>src/rustfava/core/inventory.py</code> <pre><code>def add_inventory(self, counter: CounterInventory) -&gt; None:\n    \"\"\"Add another :class:`CounterInventory`.\"\"\"\n    if not self:\n        self.update(counter)\n    else:\n        self_get = self.get\n        for key, num in counter.items():\n            new_num = num + self_get(key, ZERO)\n            if new_num == ZERO:\n                self.pop(key, None)\n            else:\n                self[key] = new_num\n</code></pre>"},{"location":"api/#rustfava.core.misc","title":"<code>misc</code>","text":"<p>Some miscellaneous reports.</p>"},{"location":"api/#rustfava.core.misc.FavaError","title":"<code>FavaError</code>  <code>dataclass</code>","text":"<p>               Bases: <code>BeancountError</code></p> <p>Generic Fava-specific error.</p> Source code in <code>src/rustfava/core/misc.py</code> <pre><code>class FavaError(BeancountError):\n    \"\"\"Generic Fava-specific error.\"\"\"\n</code></pre>"},{"location":"api/#rustfava.core.misc.FavaMisc","title":"<code>FavaMisc</code>","text":"<p>               Bases: <code>FavaModule</code></p> <p>Provides access to some miscellaneous reports.</p> Source code in <code>src/rustfava/core/misc.py</code> <pre><code>class FavaMisc(FavaModule):\n    \"\"\"Provides access to some miscellaneous reports.\"\"\"\n\n    def __init__(self, ledger: RustfavaLedger) -&gt; None:\n        super().__init__(ledger)\n        #: User-chosen links to show in the sidebar.\n        self.sidebar_links: SidebarLinks = []\n        #: Upcoming events in the next few days.\n        self.upcoming_events: Sequence[Event] = []\n\n    def load_file(self) -&gt; None:  # noqa: D102\n        custom_entries = self.ledger.all_entries_by_type.Custom\n        self.sidebar_links = sidebar_links(custom_entries)\n\n        self.upcoming_events = upcoming_events(\n            self.ledger.all_entries_by_type.Event,\n            self.ledger.fava_options.upcoming_events,\n        )\n\n    @property\n    def errors(self) -&gt; Sequence[FavaError]:\n        \"\"\"An error if no operating currency is set.\"\"\"\n        return (\n            []\n            if self.ledger.options[\"operating_currency\"]\n            else [NO_OPERATING_CURRENCY_ERROR]\n        )\n</code></pre>"},{"location":"api/#rustfava.core.misc.FavaMisc.errors","title":"<code>errors</code>  <code>property</code>","text":"<p>An error if no operating currency is set.</p>"},{"location":"api/#rustfava.core.misc.sidebar_links","title":"<code>sidebar_links(custom_entries)</code>","text":"<p>Parse custom entries for links.</p> <p>They have the following format:</p> <p>2016-04-01 custom \"fava-sidebar-link\" \"2014\" \"/income_statement/?time=2014\"</p> Source code in <code>src/rustfava/core/misc.py</code> <pre><code>def sidebar_links(custom_entries: Sequence[Custom]) -&gt; SidebarLinks:\n    \"\"\"Parse custom entries for links.\n\n    They have the following format:\n\n    2016-04-01 custom \"fava-sidebar-link\" \"2014\" \"/income_statement/?time=2014\"\n    \"\"\"\n    sidebar_link_entries = [\n        entry for entry in custom_entries if entry.type == \"fava-sidebar-link\"\n    ]\n    return [\n        (entry.values[0].value, entry.values[1].value)\n        for entry in sidebar_link_entries\n    ]\n</code></pre>"},{"location":"api/#rustfava.core.misc.upcoming_events","title":"<code>upcoming_events(events, max_delta)</code>","text":"<p>Parse entries for upcoming events.</p> <p>Parameters:</p> Name Type Description Default <code>events</code> <code>Sequence[Event]</code> <p>A list of events.</p> required <code>max_delta</code> <code>int</code> <p>Number of days that should be considered.</p> required <p>Returns:</p> Type Description <code>Sequence[Event]</code> <p>A list of the Events in entries that are less than <code>max_delta</code> days</p> <code>Sequence[Event]</code> <p>away.</p> Source code in <code>src/rustfava/core/misc.py</code> <pre><code>def upcoming_events(\n    events: Sequence[Event], max_delta: int\n) -&gt; Sequence[Event]:\n    \"\"\"Parse entries for upcoming events.\n\n    Args:\n        events: A list of events.\n        max_delta: Number of days that should be considered.\n\n    Returns:\n        A list of the Events in entries that are less than `max_delta` days\n        away.\n    \"\"\"\n    today = local_today()\n    upcoming = []\n\n    for event in events:\n        delta = event.date - today\n        if delta.days &gt;= 0 and delta.days &lt; max_delta:\n            upcoming.append(event)\n\n    return upcoming\n</code></pre>"},{"location":"api/#rustfava.core.misc.align","title":"<code>align(string, currency_column)</code>","text":"<p>Align currencies in one column.</p> Source code in <code>src/rustfava/beans/str.py</code> <pre><code>def align(string: str, currency_column: int) -&gt; str:\n    \"\"\"Align currencies in one column.\"\"\"\n    output = io.StringIO()\n    for line in string.splitlines():\n        match = ALIGN_RE.match(line)\n        if match:\n            prefix, number, rest = match.groups()\n            num_of_spaces = currency_column - len(prefix) - len(number) - 4\n            spaces = \" \" * num_of_spaces\n            output.write(prefix + spaces + \"  \" + number + \" \" + rest)\n        else:\n            output.write(line)\n        output.write(\"\\n\")\n\n    return output.getvalue()\n</code></pre>"},{"location":"api/#rustfava.core.module_base","title":"<code>module_base</code>","text":"<p>Base class for the \"modules\" of rustfavaLedger.</p>"},{"location":"api/#rustfava.core.module_base.FavaModule","title":"<code>FavaModule</code>","text":"<p>Base class for the \"modules\" of rustfavaLedger.</p> Source code in <code>src/rustfava/core/module_base.py</code> <pre><code>class FavaModule:\n    \"\"\"Base class for the \"modules\" of rustfavaLedger.\"\"\"\n\n    def __init__(self, ledger: RustfavaLedger) -&gt; None:\n        self.ledger = ledger\n\n    def load_file(self) -&gt; None:\n        \"\"\"Run when the file has been (re)loaded.\"\"\"\n</code></pre>"},{"location":"api/#rustfava.core.module_base.FavaModule.load_file","title":"<code>load_file()</code>","text":"<p>Run when the file has been (re)loaded.</p> Source code in <code>src/rustfava/core/module_base.py</code> <pre><code>def load_file(self) -&gt; None:\n    \"\"\"Run when the file has been (re)loaded.\"\"\"\n</code></pre>"},{"location":"api/#rustfava.core.number","title":"<code>number</code>","text":"<p>Formatting numbers.</p>"},{"location":"api/#rustfava.core.number.DecimalFormatModule","title":"<code>DecimalFormatModule</code>","text":"<p>               Bases: <code>FavaModule</code></p> <p>Formatting numbers.</p> Source code in <code>src/rustfava/core/number.py</code> <pre><code>class DecimalFormatModule(FavaModule):\n    \"\"\"Formatting numbers.\"\"\"\n\n    def __init__(self, ledger: RustfavaLedger) -&gt; None:\n        super().__init__(ledger)\n        self._locale: Locale | None = None\n        self._formatters: dict[str, Formatter] = {}\n        self._default_pattern = get_locale_format(None, 2)\n        self.precisions: dict[str, int] = {}\n\n    def load_file(self) -&gt; None:  # noqa: D102\n        locale = None\n\n        locale_option = self.ledger.fava_options.locale\n        if (\n            self.ledger.options[\"render_commas\"] and not locale_option\n        ):  # pragma: no cover\n            locale_option = \"en\"\n            self.ledger.fava_options.locale = locale_option\n\n        if locale_option:\n            locale = Locale.parse(locale_option)\n\n        dcontext = self.ledger.options[\"dcontext\"]\n        precisions: dict[str, int] = {}\n\n        # Both beancount's DisplayContext and RLDisplayContext have ccontexts\n        for currency, ccontext in dcontext.ccontexts.items():\n            prec = ccontext.get_fractional(None)\n            if prec is not None:\n                precisions[currency] = prec\n\n        precisions.update(self.ledger.commodities.precisions)\n\n        self._locale = locale\n        self._default_pattern = get_locale_format(locale, 2)\n        self._formatters = {\n            currency: get_locale_format(locale, prec)\n            for currency, prec in precisions.items()\n        }\n        self.precisions = precisions\n\n    def __call__(self, value: Decimal, currency: str | None = None) -&gt; str:\n        \"\"\"Format a decimal to the right number of decimal digits with locale.\n\n        Arguments:\n            value: A decimal number.\n            currency: A currency string or None.\n\n        Returns:\n            A string, the formatted decimal.\n        \"\"\"\n        if currency is None:\n            return self._default_pattern(value)\n        return self._formatters.get(currency, self._default_pattern)(value)\n</code></pre>"},{"location":"api/#rustfava.core.number.DecimalFormatModule.__call__","title":"<code>__call__(value, currency=None)</code>","text":"<p>Format a decimal to the right number of decimal digits with locale.</p> <p>Parameters:</p> Name Type Description Default <code>value</code> <code>Decimal</code> <p>A decimal number.</p> required <code>currency</code> <code>str | None</code> <p>A currency string or None.</p> <code>None</code> <p>Returns:</p> Type Description <code>str</code> <p>A string, the formatted decimal.</p> Source code in <code>src/rustfava/core/number.py</code> <pre><code>def __call__(self, value: Decimal, currency: str | None = None) -&gt; str:\n    \"\"\"Format a decimal to the right number of decimal digits with locale.\n\n    Arguments:\n        value: A decimal number.\n        currency: A currency string or None.\n\n    Returns:\n        A string, the formatted decimal.\n    \"\"\"\n    if currency is None:\n        return self._default_pattern(value)\n    return self._formatters.get(currency, self._default_pattern)(value)\n</code></pre>"},{"location":"api/#rustfava.core.number.get_locale_format","title":"<code>get_locale_format(locale, precision)</code>","text":"<p>Obtain formatting pattern for the given locale and precision.</p> <p>Parameters:</p> Name Type Description Default <code>locale</code> <code>Locale | None</code> <p>An optional locale.</p> required <code>precision</code> <code>int</code> <p>The precision.</p> required <p>Returns:</p> Type Description <code>Formatter</code> <p>A function that renders Decimals to strings as desired.</p> Source code in <code>src/rustfava/core/number.py</code> <pre><code>def get_locale_format(locale: Locale | None, precision: int) -&gt; Formatter:\n    \"\"\"Obtain formatting pattern for the given locale and precision.\n\n    Arguments:\n        locale: An optional locale.\n        precision: The precision.\n\n    Returns:\n        A function that renders Decimals to strings as desired.\n    \"\"\"\n    # Set a maximum precision of 14, half the default precision of Decimal\n    precision = min(precision, 14)\n    if locale is None:\n        fmt_string = \"{:.\" + str(precision) + \"f}\"\n\n        def fmt(num: Decimal) -&gt; str:\n            return fmt_string.format(num)\n\n        return fmt\n\n    pattern = copy.copy(locale.decimal_formats.get(None))\n    if not pattern:  # pragma: no cover\n        msg = \"Expected Locale to have a decimal format pattern\"\n        raise ValueError(msg)\n    pattern.frac_prec = (precision, precision)\n\n    def locale_fmt(num: Decimal) -&gt; str:\n        return pattern.apply(num, locale)  # type: ignore[no-any-return]\n\n    return locale_fmt\n</code></pre>"},{"location":"api/#rustfava.core.query","title":"<code>query</code>","text":"<p>Query result types.</p>"},{"location":"api/#rustfava.core.query.QueryResultTable","title":"<code>QueryResultTable</code>  <code>dataclass</code>","text":"<p>Table query result.</p> Source code in <code>src/rustfava/core/query.py</code> <pre><code>@dataclass(frozen=True)\nclass QueryResultTable:\n    \"\"\"Table query result.\"\"\"\n\n    types: list[BaseColumn]\n    rows: list[tuple[SerialisedQueryRowValue, ...]]\n    t: Literal[\"table\"] = \"table\"\n</code></pre>"},{"location":"api/#rustfava.core.query.QueryResultText","title":"<code>QueryResultText</code>  <code>dataclass</code>","text":"<p>Text query result.</p> Source code in <code>src/rustfava/core/query.py</code> <pre><code>@dataclass(frozen=True)\nclass QueryResultText:\n    \"\"\"Text query result.\"\"\"\n\n    contents: str\n    t: Literal[\"string\"] = \"string\"\n</code></pre>"},{"location":"api/#rustfava.core.query.BaseColumn","title":"<code>BaseColumn</code>  <code>dataclass</code>","text":"<p>A query column.</p> Source code in <code>src/rustfava/core/query.py</code> <pre><code>@dataclass(frozen=True)\nclass BaseColumn:\n    \"\"\"A query column.\"\"\"\n\n    name: str\n    dtype: str\n\n    @staticmethod\n    def serialise(\n        val: QueryRowValue,\n    ) -&gt; SerialisedQueryRowValue:\n        \"\"\"Serialiseable version of the column value.\"\"\"\n        return val  # type: ignore[no-any-return]\n</code></pre>"},{"location":"api/#rustfava.core.query.BaseColumn.serialise","title":"<code>serialise(val)</code>  <code>staticmethod</code>","text":"<p>Serialiseable version of the column value.</p> Source code in <code>src/rustfava/core/query.py</code> <pre><code>@staticmethod\ndef serialise(\n    val: QueryRowValue,\n) -&gt; SerialisedQueryRowValue:\n    \"\"\"Serialiseable version of the column value.\"\"\"\n    return val  # type: ignore[no-any-return]\n</code></pre>"},{"location":"api/#rustfava.core.query.BoolColumn","title":"<code>BoolColumn</code>  <code>dataclass</code>","text":"<p>               Bases: <code>BaseColumn</code></p> <p>A boolean query column.</p> Source code in <code>src/rustfava/core/query.py</code> <pre><code>@dataclass(frozen=True)\nclass BoolColumn(BaseColumn):\n    \"\"\"A boolean query column.\"\"\"\n\n    dtype: str = \"bool\"\n</code></pre>"},{"location":"api/#rustfava.core.query.DecimalColumn","title":"<code>DecimalColumn</code>  <code>dataclass</code>","text":"<p>               Bases: <code>BaseColumn</code></p> <p>A Decimal query column.</p> Source code in <code>src/rustfava/core/query.py</code> <pre><code>@dataclass(frozen=True)\nclass DecimalColumn(BaseColumn):\n    \"\"\"A Decimal query column.\"\"\"\n\n    dtype: str = \"Decimal\"\n</code></pre>"},{"location":"api/#rustfava.core.query.IntColumn","title":"<code>IntColumn</code>  <code>dataclass</code>","text":"<p>               Bases: <code>BaseColumn</code></p> <p>A int query column.</p> Source code in <code>src/rustfava/core/query.py</code> <pre><code>@dataclass(frozen=True)\nclass IntColumn(BaseColumn):\n    \"\"\"A int query column.\"\"\"\n\n    dtype: str = \"int\"\n</code></pre>"},{"location":"api/#rustfava.core.query.StrColumn","title":"<code>StrColumn</code>  <code>dataclass</code>","text":"<p>               Bases: <code>BaseColumn</code></p> <p>A str query column.</p> Source code in <code>src/rustfava/core/query.py</code> <pre><code>@dataclass(frozen=True)\nclass StrColumn(BaseColumn):\n    \"\"\"A str query column.\"\"\"\n\n    dtype: str = \"str\"\n</code></pre>"},{"location":"api/#rustfava.core.query.DateColumn","title":"<code>DateColumn</code>  <code>dataclass</code>","text":"<p>               Bases: <code>BaseColumn</code></p> <p>A date query column.</p> Source code in <code>src/rustfava/core/query.py</code> <pre><code>@dataclass(frozen=True)\nclass DateColumn(BaseColumn):\n    \"\"\"A date query column.\"\"\"\n\n    dtype: str = \"date\"\n</code></pre>"},{"location":"api/#rustfava.core.query.PositionColumn","title":"<code>PositionColumn</code>  <code>dataclass</code>","text":"<p>               Bases: <code>BaseColumn</code></p> <p>A Position query column.</p> Source code in <code>src/rustfava/core/query.py</code> <pre><code>@dataclass(frozen=True)\nclass PositionColumn(BaseColumn):\n    \"\"\"A Position query column.\"\"\"\n\n    dtype: str = \"Position\"\n</code></pre>"},{"location":"api/#rustfava.core.query.SetColumn","title":"<code>SetColumn</code>  <code>dataclass</code>","text":"<p>               Bases: <code>BaseColumn</code></p> <p>A set query column.</p> Source code in <code>src/rustfava/core/query.py</code> <pre><code>@dataclass(frozen=True)\nclass SetColumn(BaseColumn):\n    \"\"\"A set query column.\"\"\"\n\n    dtype: str = \"set\"\n</code></pre>"},{"location":"api/#rustfava.core.query.AmountColumn","title":"<code>AmountColumn</code>  <code>dataclass</code>","text":"<p>               Bases: <code>BaseColumn</code></p> <p>An amount query column.</p> Source code in <code>src/rustfava/core/query.py</code> <pre><code>@dataclass(frozen=True)\nclass AmountColumn(BaseColumn):\n    \"\"\"An amount query column.\"\"\"\n\n    dtype: str = \"Amount\"\n</code></pre>"},{"location":"api/#rustfava.core.query.ObjectColumn","title":"<code>ObjectColumn</code>  <code>dataclass</code>","text":"<p>               Bases: <code>BaseColumn</code></p> <p>An object query column.</p> Source code in <code>src/rustfava/core/query.py</code> <pre><code>@dataclass(frozen=True)\nclass ObjectColumn(BaseColumn):\n    \"\"\"An object query column.\"\"\"\n\n    dtype: str = \"object\"\n\n    @staticmethod\n    def serialise(val: object) -&gt; str:\n        \"\"\"Serialise an object of unknown type to a string.\"\"\"\n        return str(val)\n</code></pre>"},{"location":"api/#rustfava.core.query.ObjectColumn.serialise","title":"<code>serialise(val)</code>  <code>staticmethod</code>","text":"<p>Serialise an object of unknown type to a string.</p> Source code in <code>src/rustfava/core/query.py</code> <pre><code>@staticmethod\ndef serialise(val: object) -&gt; str:\n    \"\"\"Serialise an object of unknown type to a string.\"\"\"\n    return str(val)\n</code></pre>"},{"location":"api/#rustfava.core.query.InventoryColumn","title":"<code>InventoryColumn</code>  <code>dataclass</code>","text":"<p>               Bases: <code>BaseColumn</code></p> <p>An inventory query column.</p> Source code in <code>src/rustfava/core/query.py</code> <pre><code>@dataclass(frozen=True)\nclass InventoryColumn(BaseColumn):\n    \"\"\"An inventory query column.\"\"\"\n\n    dtype: str = \"Inventory\"\n\n    @staticmethod\n    def serialise(\n        val: dict[str, Decimal] | None,\n    ) -&gt; SimpleCounterInventory | None:\n        \"\"\"Serialise an inventory.\n\n        Rustledger returns inventory as a dict of currency -&gt; Decimal.\n        \"\"\"\n        if val is None:\n            return None\n        # Rustledger already converts to {currency: Decimal} format\n        if isinstance(val, dict):\n            from rustfava.core.inventory import SimpleCounterInventory\n            return SimpleCounterInventory(val)\n        # Fallback for beancount Inventory type (for backwards compat)\n        return UNITS.apply_inventory(val) if val is not None else None\n</code></pre>"},{"location":"api/#rustfava.core.query.InventoryColumn.serialise","title":"<code>serialise(val)</code>  <code>staticmethod</code>","text":"<p>Serialise an inventory.</p> <p>Rustledger returns inventory as a dict of currency -&gt; Decimal.</p> Source code in <code>src/rustfava/core/query.py</code> <pre><code>@staticmethod\ndef serialise(\n    val: dict[str, Decimal] | None,\n) -&gt; SimpleCounterInventory | None:\n    \"\"\"Serialise an inventory.\n\n    Rustledger returns inventory as a dict of currency -&gt; Decimal.\n    \"\"\"\n    if val is None:\n        return None\n    # Rustledger already converts to {currency: Decimal} format\n    if isinstance(val, dict):\n        from rustfava.core.inventory import SimpleCounterInventory\n        return SimpleCounterInventory(val)\n    # Fallback for beancount Inventory type (for backwards compat)\n    return UNITS.apply_inventory(val) if val is not None else None\n</code></pre>"},{"location":"api/#rustfava.core.query_shell","title":"<code>query_shell</code>","text":"<p>For running BQL queries in Fava.</p>"},{"location":"api/#rustfava.core.query_shell.FavaShellError","title":"<code>FavaShellError</code>","text":"<p>               Bases: <code>RustfavaAPIError</code></p> <p>An error in the Fava BQL shell, will be turned into a string.</p> Source code in <code>src/rustfava/core/query_shell.py</code> <pre><code>class FavaShellError(RustfavaAPIError):\n    \"\"\"An error in the Fava BQL shell, will be turned into a string.\"\"\"\n</code></pre>"},{"location":"api/#rustfava.core.query_shell.QueryNotFoundError","title":"<code>QueryNotFoundError</code>","text":"<p>               Bases: <code>FavaShellError</code></p> <p>Query '{name}' not found.</p> Source code in <code>src/rustfava/core/query_shell.py</code> <pre><code>class QueryNotFoundError(FavaShellError):\n    \"\"\"Query '{name}' not found.\"\"\"\n\n    def __init__(self, name: str) -&gt; None:\n        super().__init__(f\"Query '{name}' not found.\")\n</code></pre>"},{"location":"api/#rustfava.core.query_shell.TooManyRunArgsError","title":"<code>TooManyRunArgsError</code>","text":"<p>               Bases: <code>FavaShellError</code></p> <p>Too many args to run: '{args}'.</p> Source code in <code>src/rustfava/core/query_shell.py</code> <pre><code>class TooManyRunArgsError(FavaShellError):\n    \"\"\"Too many args to run: '{args}'.\"\"\"\n\n    def __init__(self, args: str) -&gt; None:\n        super().__init__(f\"Too many args to run: '{args}'.\")\n</code></pre>"},{"location":"api/#rustfava.core.query_shell.QueryCompilationError","title":"<code>QueryCompilationError</code>","text":"<p>               Bases: <code>FavaShellError</code></p> <p>Query compilation error.</p> Source code in <code>src/rustfava/core/query_shell.py</code> <pre><code>class QueryCompilationError(FavaShellError):\n    \"\"\"Query compilation error.\"\"\"\n\n    def __init__(self, err: CompilationError) -&gt; None:\n        super().__init__(f\"Query compilation error: {err!s}.\")\n</code></pre>"},{"location":"api/#rustfava.core.query_shell.QueryParseError","title":"<code>QueryParseError</code>","text":"<p>               Bases: <code>FavaShellError</code></p> <p>Query parse error.</p> Source code in <code>src/rustfava/core/query_shell.py</code> <pre><code>class QueryParseError(FavaShellError):\n    \"\"\"Query parse error.\"\"\"\n\n    def __init__(self, err: ParseError) -&gt; None:\n        super().__init__(f\"Query parse error: {err!s}.\")\n</code></pre>"},{"location":"api/#rustfava.core.query_shell.NonExportableQueryError","title":"<code>NonExportableQueryError</code>","text":"<p>               Bases: <code>FavaShellError</code></p> <p>Only queries that return a table can be printed to a file.</p> Source code in <code>src/rustfava/core/query_shell.py</code> <pre><code>class NonExportableQueryError(FavaShellError):\n    \"\"\"Only queries that return a table can be printed to a file.\"\"\"\n\n    def __init__(self) -&gt; None:\n        super().__init__(\n            \"Only queries that return a table can be printed to a file.\"\n        )\n</code></pre>"},{"location":"api/#rustfava.core.query_shell.FavaQueryRunner","title":"<code>FavaQueryRunner</code>","text":"<p>Runs BQL queries using rustledger.</p> Source code in <code>src/rustfava/core/query_shell.py</code> <pre><code>class FavaQueryRunner:\n    \"\"\"Runs BQL queries using rustledger.\"\"\"\n\n    def __init__(self, ledger: RustfavaLedger) -&gt; None:\n        self.ledger = ledger\n\n    def run(\n        self, entries: Sequence[Directive], query: str\n    ) -&gt; RLCursor | str:\n        \"\"\"Run a query, returning cursor or text result.\"\"\"\n        # Get the source from the ledger for queries\n        source = getattr(self.ledger, \"_source\", None)\n\n        # Create connection\n        conn = connect(\n            \"rustledger:\",\n            entries=entries,\n            errors=self.ledger.errors,\n            options=self.ledger.options,\n        )\n\n        if source:\n            conn.set_source(source)\n\n        # Parse the query to handle special commands\n        query = query.strip()\n        query_lower = query.lower()\n\n        # Handle noop commands (return fixed text)\n        noop_doc = \"Doesn't do anything in rustfava's query shell.\"\n        if query_lower in (\".exit\", \".quit\", \"exit\", \"quit\"):\n            return noop_doc\n\n        # Handle .run or run command\n        if query_lower.startswith((\".run\", \"run\")):\n            # Check if it's just \"run\" or \".run\" (list queries) or \"run name\"\n            if query_lower in (\"run\", \".run\") or query_lower.startswith((\"run \", \".run \")):\n                return self._handle_run(query, conn)\n\n        # Handle help commands - return text\n        if query_lower.startswith((\".help\", \"help\")):\n            # \".help exit\" or \".help &lt;command&gt;\" returns noop doc\n            if \" \" in query_lower:\n                return noop_doc\n            return self._help_text()\n\n        # Handle .explain - return placeholder\n        if query_lower.startswith((\".explain\", \"explain\")):\n            return f\"EXPLAIN: {query}\"\n\n        # Handle SELECT/BALANCES/JOURNAL queries\n        try:\n            return conn.execute(query)\n        except ParseError as exc:\n            raise QueryParseError(exc) from exc\n        except CompilationError as exc:\n            raise QueryCompilationError(exc) from exc\n\n    def _handle_run(self, query: str, conn: RLConnection) -&gt; RLCursor | str:\n        \"\"\"Handle .run command to execute stored queries.\"\"\"\n        queries = self.ledger.all_entries_by_type.Query\n\n        # Parse the run command\n        parts = shlex.split(query)\n        if len(parts) == 1:\n            # Just \"run\" - list available queries\n            return \"\\n\".join(q.name for q in queries)\n\n        if len(parts) &gt; 2:\n            raise TooManyRunArgsError(query)\n\n        name = parts[1].rstrip(\";\")\n        query_obj = next((q for q in queries if q.name == name), None)\n        if query_obj is None:\n            raise QueryNotFoundError(name)\n\n        try:\n            return conn.execute(query_obj.query_string)\n        except ParseError as exc:\n            raise QueryParseError(exc) from exc\n        except CompilationError as exc:\n            raise QueryCompilationError(exc) from exc\n\n    def _help_text(self) -&gt; str:\n        \"\"\"Return help text for the query shell.\"\"\"\n        return \"\"\"Fava Query Shell\n\nCommands:\n  SELECT ...     Run a BQL SELECT query\n  run &lt;name&gt;     Run a stored query by name\n  run            List all stored queries\n  help           Show this help message\n\nExample queries:\n  SELECT account, sum(position) GROUP BY account\n  SELECT date, narration, position WHERE account ~ \"Expenses\"\n\"\"\"\n</code></pre>"},{"location":"api/#rustfava.core.query_shell.FavaQueryRunner.run","title":"<code>run(entries, query)</code>","text":"<p>Run a query, returning cursor or text result.</p> Source code in <code>src/rustfava/core/query_shell.py</code> <pre><code>def run(\n    self, entries: Sequence[Directive], query: str\n) -&gt; RLCursor | str:\n    \"\"\"Run a query, returning cursor or text result.\"\"\"\n    # Get the source from the ledger for queries\n    source = getattr(self.ledger, \"_source\", None)\n\n    # Create connection\n    conn = connect(\n        \"rustledger:\",\n        entries=entries,\n        errors=self.ledger.errors,\n        options=self.ledger.options,\n    )\n\n    if source:\n        conn.set_source(source)\n\n    # Parse the query to handle special commands\n    query = query.strip()\n    query_lower = query.lower()\n\n    # Handle noop commands (return fixed text)\n    noop_doc = \"Doesn't do anything in rustfava's query shell.\"\n    if query_lower in (\".exit\", \".quit\", \"exit\", \"quit\"):\n        return noop_doc\n\n    # Handle .run or run command\n    if query_lower.startswith((\".run\", \"run\")):\n        # Check if it's just \"run\" or \".run\" (list queries) or \"run name\"\n        if query_lower in (\"run\", \".run\") or query_lower.startswith((\"run \", \".run \")):\n            return self._handle_run(query, conn)\n\n    # Handle help commands - return text\n    if query_lower.startswith((\".help\", \"help\")):\n        # \".help exit\" or \".help &lt;command&gt;\" returns noop doc\n        if \" \" in query_lower:\n            return noop_doc\n        return self._help_text()\n\n    # Handle .explain - return placeholder\n    if query_lower.startswith((\".explain\", \"explain\")):\n        return f\"EXPLAIN: {query}\"\n\n    # Handle SELECT/BALANCES/JOURNAL queries\n    try:\n        return conn.execute(query)\n    except ParseError as exc:\n        raise QueryParseError(exc) from exc\n    except CompilationError as exc:\n        raise QueryCompilationError(exc) from exc\n</code></pre>"},{"location":"api/#rustfava.core.query_shell.QueryShell","title":"<code>QueryShell</code>","text":"<p>               Bases: <code>FavaModule</code></p> <p>A Fava module to run BQL queries.</p> Source code in <code>src/rustfava/core/query_shell.py</code> <pre><code>class QueryShell(FavaModule):\n    \"\"\"A Fava module to run BQL queries.\"\"\"\n\n    def __init__(self, ledger: RustfavaLedger) -&gt; None:\n        super().__init__(ledger)\n        self.runner = FavaQueryRunner(ledger)\n\n    def execute_query_serialised(\n        self, entries: Sequence[Directive], query: str\n    ) -&gt; QueryResultTable | QueryResultText:\n        \"\"\"Run a query and returns its serialised result.\n\n        Arguments:\n            entries: The entries to run the query on.\n            query: A query string.\n\n        Returns:\n            Either a table or a text result (depending on the query).\n\n        Raises:\n            RustfavaAPIError: If the query response is an error.\n        \"\"\"\n        res = self.runner.run(entries, query)\n        return (\n            QueryResultText(res) if isinstance(res, str) else _serialise(res)\n        )\n\n    def query_to_file(\n        self,\n        entries: Sequence[Directive],\n        query_string: str,\n        result_format: str,\n    ) -&gt; tuple[str, io.BytesIO]:\n        \"\"\"Get query result as file.\n\n        Arguments:\n            entries: The entries to run the query on.\n            query_string: A string, the query to run.\n            result_format: The file format to save to.\n\n        Returns:\n            A tuple (name, data), where name is either 'query_result' or the\n            name of a custom query if the query string is 'run name_of_query'.\n            ``data`` contains the file contents.\n\n        Raises:\n            RustfavaAPIError: If the result format is not supported or the\n            query failed.\n        \"\"\"\n        name = \"query_result\"\n\n        if query_string.lower().startswith((\".run\", \"run \")):\n            parts = shlex.split(query_string)\n            if len(parts) &gt; 2:\n                raise TooManyRunArgsError(query_string)\n            if len(parts) == 2:\n                name = parts[1].rstrip(\";\")\n                queries = self.ledger.all_entries_by_type.Query\n                query_obj = next((q for q in queries if q.name == name), None)\n                if query_obj is None:\n                    raise QueryNotFoundError(name)\n                query_string = query_obj.query_string\n\n        res = self.runner.run(entries, query_string)\n        if isinstance(res, str):\n            raise NonExportableQueryError\n\n        rrows = res.fetchall()\n        rtypes = res.description\n\n        # Convert rows to exportable format\n        rows = _numberify_rows(rrows, rtypes)\n\n        if result_format == \"csv\":\n            data = to_csv(list(rtypes), rows)\n        else:\n            if not HAVE_EXCEL:  # pragma: no cover\n                msg = \"Result format not supported.\"\n                raise RustfavaAPIError(msg)\n            data = to_excel(list(rtypes), rows, result_format, query_string)\n        return name, data\n</code></pre>"},{"location":"api/#rustfava.core.query_shell.QueryShell.execute_query_serialised","title":"<code>execute_query_serialised(entries, query)</code>","text":"<p>Run a query and returns its serialised result.</p> <p>Parameters:</p> Name Type Description Default <code>entries</code> <code>Sequence[Directive]</code> <p>The entries to run the query on.</p> required <code>query</code> <code>str</code> <p>A query string.</p> required <p>Returns:</p> Type Description <code>QueryResultTable | QueryResultText</code> <p>Either a table or a text result (depending on the query).</p> <p>Raises:</p> Type Description <code>RustfavaAPIError</code> <p>If the query response is an error.</p> Source code in <code>src/rustfava/core/query_shell.py</code> <pre><code>def execute_query_serialised(\n    self, entries: Sequence[Directive], query: str\n) -&gt; QueryResultTable | QueryResultText:\n    \"\"\"Run a query and returns its serialised result.\n\n    Arguments:\n        entries: The entries to run the query on.\n        query: A query string.\n\n    Returns:\n        Either a table or a text result (depending on the query).\n\n    Raises:\n        RustfavaAPIError: If the query response is an error.\n    \"\"\"\n    res = self.runner.run(entries, query)\n    return (\n        QueryResultText(res) if isinstance(res, str) else _serialise(res)\n    )\n</code></pre>"},{"location":"api/#rustfava.core.query_shell.QueryShell.query_to_file","title":"<code>query_to_file(entries, query_string, result_format)</code>","text":"<p>Get query result as file.</p> <p>Parameters:</p> Name Type Description Default <code>entries</code> <code>Sequence[Directive]</code> <p>The entries to run the query on.</p> required <code>query_string</code> <code>str</code> <p>A string, the query to run.</p> required <code>result_format</code> <code>str</code> <p>The file format to save to.</p> required <p>Returns:</p> Type Description <code>str</code> <p>A tuple (name, data), where name is either 'query_result' or the</p> <code>BytesIO</code> <p>name of a custom query if the query string is 'run name_of_query'.</p> <code>tuple[str, BytesIO]</code> <p><code>data</code> contains the file contents.</p> <p>Raises:</p> Type Description <code>RustfavaAPIError</code> <p>If the result format is not supported or the</p> Source code in <code>src/rustfava/core/query_shell.py</code> <pre><code>def query_to_file(\n    self,\n    entries: Sequence[Directive],\n    query_string: str,\n    result_format: str,\n) -&gt; tuple[str, io.BytesIO]:\n    \"\"\"Get query result as file.\n\n    Arguments:\n        entries: The entries to run the query on.\n        query_string: A string, the query to run.\n        result_format: The file format to save to.\n\n    Returns:\n        A tuple (name, data), where name is either 'query_result' or the\n        name of a custom query if the query string is 'run name_of_query'.\n        ``data`` contains the file contents.\n\n    Raises:\n        RustfavaAPIError: If the result format is not supported or the\n        query failed.\n    \"\"\"\n    name = \"query_result\"\n\n    if query_string.lower().startswith((\".run\", \"run \")):\n        parts = shlex.split(query_string)\n        if len(parts) &gt; 2:\n            raise TooManyRunArgsError(query_string)\n        if len(parts) == 2:\n            name = parts[1].rstrip(\";\")\n            queries = self.ledger.all_entries_by_type.Query\n            query_obj = next((q for q in queries if q.name == name), None)\n            if query_obj is None:\n                raise QueryNotFoundError(name)\n            query_string = query_obj.query_string\n\n    res = self.runner.run(entries, query_string)\n    if isinstance(res, str):\n        raise NonExportableQueryError\n\n    rrows = res.fetchall()\n    rtypes = res.description\n\n    # Convert rows to exportable format\n    rows = _numberify_rows(rrows, rtypes)\n\n    if result_format == \"csv\":\n        data = to_csv(list(rtypes), rows)\n    else:\n        if not HAVE_EXCEL:  # pragma: no cover\n            msg = \"Result format not supported.\"\n            raise RustfavaAPIError(msg)\n        data = to_excel(list(rtypes), rows, result_format, query_string)\n    return name, data\n</code></pre>"},{"location":"api/#rustfava.core.tree","title":"<code>tree</code>","text":"<p>Account balance trees.</p>"},{"location":"api/#rustfava.core.tree.SerialisedTreeNode","title":"<code>SerialisedTreeNode</code>  <code>dataclass</code>","text":"<p>A serialised TreeNode.</p> Source code in <code>src/rustfava/core/tree.py</code> <pre><code>@dataclass(frozen=True)\nclass SerialisedTreeNode:\n    \"\"\"A serialised TreeNode.\"\"\"\n\n    account: str\n    balance: SimpleCounterInventory\n    balance_children: SimpleCounterInventory\n    children: Sequence[SerialisedTreeNode]\n    has_txns: bool\n    cost: SimpleCounterInventory | None = None\n    cost_children: SimpleCounterInventory | None = None\n</code></pre>"},{"location":"api/#rustfava.core.tree.TreeNode","title":"<code>TreeNode</code>","text":"<p>A node in the account tree.</p> Source code in <code>src/rustfava/core/tree.py</code> <pre><code>class TreeNode:\n    \"\"\"A node in the account tree.\"\"\"\n\n    __slots__ = (\"balance\", \"balance_children\", \"children\", \"has_txns\", \"name\")\n\n    def __init__(self, name: str) -&gt; None:\n        #: Account name.\n        self.name: str = name\n        #: A list of :class:`.TreeNode`, its children.\n        self.children: list[TreeNode] = []\n        #: The cumulative account balance.\n        self.balance_children = CounterInventory()\n        #: The account balance.\n        self.balance = CounterInventory()\n        #: Whether the account has any transactions.\n        self.has_txns = False\n\n    def serialise(\n        self,\n        conversion: Conversion,\n        prices: RustfavaPriceMap,\n        end: datetime.date | None,\n        *,\n        with_cost: bool = False,\n    ) -&gt; SerialisedTreeNode:\n        \"\"\"Serialise the account.\n\n        Args:\n            conversion: The conversion to use.\n            prices: The price map to use.\n            end: A date to use for cost conversions.\n            with_cost: Additionally convert to cost.\n        \"\"\"\n        children = [\n            child.serialise(conversion, prices, end, with_cost=with_cost)\n            for child in sorted(self.children, key=attrgetter(\"name\"))\n        ]\n        return (\n            SerialisedTreeNode(\n                self.name,\n                conversion.apply(self.balance, prices, end),\n                conversion.apply(self.balance_children, prices, end),\n                children,\n                self.has_txns,\n                AT_COST.apply(self.balance),\n                AT_COST.apply(self.balance_children),\n            )\n            if with_cost\n            else SerialisedTreeNode(\n                self.name,\n                conversion.apply(self.balance, prices, end),\n                conversion.apply(self.balance_children, prices, end),\n                children,\n                self.has_txns,\n            )\n        )\n\n    def serialise_with_context(self) -&gt; SerialisedTreeNode:\n        \"\"\"Serialise, getting all parameters from Flask context.\"\"\"\n        return self.serialise(\n            g.conv,\n            g.ledger.prices,\n            g.filtered.end_date,\n            with_cost=g.conv == AT_VALUE,\n        )\n</code></pre>"},{"location":"api/#rustfava.core.tree.TreeNode.serialise","title":"<code>serialise(conversion, prices, end, *, with_cost=False)</code>","text":"<p>Serialise the account.</p> <p>Parameters:</p> Name Type Description Default <code>conversion</code> <code>Conversion</code> <p>The conversion to use.</p> required <code>prices</code> <code>RustfavaPriceMap</code> <p>The price map to use.</p> required <code>end</code> <code>date | None</code> <p>A date to use for cost conversions.</p> required <code>with_cost</code> <code>bool</code> <p>Additionally convert to cost.</p> <code>False</code> Source code in <code>src/rustfava/core/tree.py</code> <pre><code>def serialise(\n    self,\n    conversion: Conversion,\n    prices: RustfavaPriceMap,\n    end: datetime.date | None,\n    *,\n    with_cost: bool = False,\n) -&gt; SerialisedTreeNode:\n    \"\"\"Serialise the account.\n\n    Args:\n        conversion: The conversion to use.\n        prices: The price map to use.\n        end: A date to use for cost conversions.\n        with_cost: Additionally convert to cost.\n    \"\"\"\n    children = [\n        child.serialise(conversion, prices, end, with_cost=with_cost)\n        for child in sorted(self.children, key=attrgetter(\"name\"))\n    ]\n    return (\n        SerialisedTreeNode(\n            self.name,\n            conversion.apply(self.balance, prices, end),\n            conversion.apply(self.balance_children, prices, end),\n            children,\n            self.has_txns,\n            AT_COST.apply(self.balance),\n            AT_COST.apply(self.balance_children),\n        )\n        if with_cost\n        else SerialisedTreeNode(\n            self.name,\n            conversion.apply(self.balance, prices, end),\n            conversion.apply(self.balance_children, prices, end),\n            children,\n            self.has_txns,\n        )\n    )\n</code></pre>"},{"location":"api/#rustfava.core.tree.TreeNode.serialise_with_context","title":"<code>serialise_with_context()</code>","text":"<p>Serialise, getting all parameters from Flask context.</p> Source code in <code>src/rustfava/core/tree.py</code> <pre><code>def serialise_with_context(self) -&gt; SerialisedTreeNode:\n    \"\"\"Serialise, getting all parameters from Flask context.\"\"\"\n    return self.serialise(\n        g.conv,\n        g.ledger.prices,\n        g.filtered.end_date,\n        with_cost=g.conv == AT_VALUE,\n    )\n</code></pre>"},{"location":"api/#rustfava.core.tree.Tree","title":"<code>Tree</code>","text":"<p>               Bases: <code>dict[str, TreeNode]</code></p> <p>Account tree.</p> <p>Parameters:</p> Name Type Description Default <code>entries</code> <code>Iterable[Directive | Directive] | None</code> <p>A list of entries to compute balances from.</p> <code>None</code> <code>create_accounts</code> <code>list[str] | None</code> <p>A list of accounts that the tree should contain.</p> <code>None</code> Source code in <code>src/rustfava/core/tree.py</code> <pre><code>class Tree(dict[str, TreeNode]):\n    \"\"\"Account tree.\n\n    Args:\n        entries: A list of entries to compute balances from.\n        create_accounts: A list of accounts that the tree should contain.\n    \"\"\"\n\n    def __init__(\n        self,\n        entries: Iterable[Directive | data.Directive] | None = None,\n        create_accounts: list[str] | None = None,\n    ) -&gt; None:\n        super().__init__(self)\n        self.get(\"\", insert=True)\n        if create_accounts:\n            for account in create_accounts:\n                self.get(account, insert=True)\n        if entries:\n            account_balances: dict[str, CounterInventory]\n            account_balances = defaultdict(CounterInventory)\n            for entry in entries:\n                if isinstance(entry, Open):\n                    self.get(entry.account, insert=True)\n                for posting in getattr(entry, \"postings\", []):\n                    account_balances[posting.account].add_position(posting)\n\n            for name, balance in sorted(account_balances.items()):\n                self.insert(name, balance)\n\n    @property\n    def accounts(self) -&gt; list[str]:\n        \"\"\"The accounts in this tree.\"\"\"\n        return sorted(self.keys())\n\n    def ancestors(self, name: str) -&gt; Iterable[TreeNode]:\n        \"\"\"Ancestors of an account.\n\n        Args:\n            name: An account name.\n\n        Yields:\n            The ancestors of the given account from the bottom up.\n        \"\"\"\n        while name:\n            name = account_parent(name) or \"\"\n            yield self.get(name)\n\n    def insert(self, name: str, balance: CounterInventory) -&gt; None:\n        \"\"\"Insert account with a balance.\n\n        Insert account and update its balance and the balances of its\n        ancestors.\n\n        Args:\n            name: An account name.\n            balance: The balance of the account.\n        \"\"\"\n        node = self.get(name, insert=True)\n        node.balance.add_inventory(balance)\n        node.balance_children.add_inventory(balance)\n        node.has_txns = True\n        for parent_node in self.ancestors(name):\n            parent_node.balance_children.add_inventory(balance)\n\n    def get(  # type: ignore[override]\n        self,\n        name: str,\n        *,\n        insert: bool = False,\n    ) -&gt; TreeNode:\n        \"\"\"Get an account.\n\n        Args:\n            name: An account name.\n            insert: If True, insert the name into the tree if it does not\n                exist.\n\n        Returns:\n            TreeNode: The account of that name or an empty account if the\n            account is not in the tree.\n        \"\"\"\n        try:\n            return self[name]\n        except KeyError:\n            node = TreeNode(name)\n            if insert:\n                if name:\n                    parent = self.get(account_parent(name) or \"\", insert=True)\n                    parent.children.append(node)\n                self[name] = node\n            return node\n\n    def net_profit(\n        self,\n        options: BeancountOptions,\n        account_name: str,\n    ) -&gt; TreeNode:\n        \"\"\"Calculate the net profit.\n\n        Args:\n            options: The Beancount options.\n            account_name: The name to use for the account containing the net\n                profit.\n        \"\"\"\n        income = self.get(options[\"name_income\"])\n        expenses = self.get(options[\"name_expenses\"])\n\n        net_profit = Tree()\n        net_profit.insert(\n            account_name,\n            income.balance_children + expenses.balance_children,\n        )\n\n        return net_profit.get(account_name)\n\n    def cap(self, options: BeancountOptions, unrealized_account: str) -&gt; None:\n        \"\"\"Transfer Income and Expenses, add conversions and unrealized gains.\n\n        Args:\n            options: The Beancount options.\n            unrealized_account: The name of the account to post unrealized\n                gains to (as a subaccount of Equity).\n        \"\"\"\n        equity = options[\"name_equity\"]\n        conversions = CounterInventory(\n            {\n                (currency, None): -number\n                for currency, number in AT_COST.apply(\n                    self.get(\"\").balance_children\n                ).items()\n            },\n        )\n\n        # Add conversions\n        self.insert(\n            equity + \":\" + options[\"account_current_conversions\"],\n            conversions,\n        )\n\n        # Insert unrealized gains.\n        self.insert(\n            equity + \":\" + unrealized_account,\n            -self.get(\"\").balance_children,\n        )\n\n        # Transfer Income and Expenses\n        self.insert(\n            equity + \":\" + options[\"account_current_earnings\"],\n            self.get(options[\"name_income\"]).balance_children,\n        )\n        self.insert(\n            equity + \":\" + options[\"account_current_earnings\"],\n            self.get(options[\"name_expenses\"]).balance_children,\n        )\n</code></pre>"},{"location":"api/#rustfava.core.tree.Tree.accounts","title":"<code>accounts</code>  <code>property</code>","text":"<p>The accounts in this tree.</p>"},{"location":"api/#rustfava.core.tree.Tree.ancestors","title":"<code>ancestors(name)</code>","text":"<p>Ancestors of an account.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>An account name.</p> required <p>Yields:</p> Type Description <code>Iterable[TreeNode]</code> <p>The ancestors of the given account from the bottom up.</p> Source code in <code>src/rustfava/core/tree.py</code> <pre><code>def ancestors(self, name: str) -&gt; Iterable[TreeNode]:\n    \"\"\"Ancestors of an account.\n\n    Args:\n        name: An account name.\n\n    Yields:\n        The ancestors of the given account from the bottom up.\n    \"\"\"\n    while name:\n        name = account_parent(name) or \"\"\n        yield self.get(name)\n</code></pre>"},{"location":"api/#rustfava.core.tree.Tree.insert","title":"<code>insert(name, balance)</code>","text":"<p>Insert account with a balance.</p> <p>Insert account and update its balance and the balances of its ancestors.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>An account name.</p> required <code>balance</code> <code>CounterInventory</code> <p>The balance of the account.</p> required Source code in <code>src/rustfava/core/tree.py</code> <pre><code>def insert(self, name: str, balance: CounterInventory) -&gt; None:\n    \"\"\"Insert account with a balance.\n\n    Insert account and update its balance and the balances of its\n    ancestors.\n\n    Args:\n        name: An account name.\n        balance: The balance of the account.\n    \"\"\"\n    node = self.get(name, insert=True)\n    node.balance.add_inventory(balance)\n    node.balance_children.add_inventory(balance)\n    node.has_txns = True\n    for parent_node in self.ancestors(name):\n        parent_node.balance_children.add_inventory(balance)\n</code></pre>"},{"location":"api/#rustfava.core.tree.Tree.get","title":"<code>get(name, *, insert=False)</code>","text":"<p>Get an account.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>An account name.</p> required <code>insert</code> <code>bool</code> <p>If True, insert the name into the tree if it does not exist.</p> <code>False</code> <p>Returns:</p> Name Type Description <code>TreeNode</code> <code>TreeNode</code> <p>The account of that name or an empty account if the</p> <code>TreeNode</code> <p>account is not in the tree.</p> Source code in <code>src/rustfava/core/tree.py</code> <pre><code>def get(  # type: ignore[override]\n    self,\n    name: str,\n    *,\n    insert: bool = False,\n) -&gt; TreeNode:\n    \"\"\"Get an account.\n\n    Args:\n        name: An account name.\n        insert: If True, insert the name into the tree if it does not\n            exist.\n\n    Returns:\n        TreeNode: The account of that name or an empty account if the\n        account is not in the tree.\n    \"\"\"\n    try:\n        return self[name]\n    except KeyError:\n        node = TreeNode(name)\n        if insert:\n            if name:\n                parent = self.get(account_parent(name) or \"\", insert=True)\n                parent.children.append(node)\n            self[name] = node\n        return node\n</code></pre>"},{"location":"api/#rustfava.core.tree.Tree.net_profit","title":"<code>net_profit(options, account_name)</code>","text":"<p>Calculate the net profit.</p> <p>Parameters:</p> Name Type Description Default <code>options</code> <code>BeancountOptions</code> <p>The Beancount options.</p> required <code>account_name</code> <code>str</code> <p>The name to use for the account containing the net profit.</p> required Source code in <code>src/rustfava/core/tree.py</code> <pre><code>def net_profit(\n    self,\n    options: BeancountOptions,\n    account_name: str,\n) -&gt; TreeNode:\n    \"\"\"Calculate the net profit.\n\n    Args:\n        options: The Beancount options.\n        account_name: The name to use for the account containing the net\n            profit.\n    \"\"\"\n    income = self.get(options[\"name_income\"])\n    expenses = self.get(options[\"name_expenses\"])\n\n    net_profit = Tree()\n    net_profit.insert(\n        account_name,\n        income.balance_children + expenses.balance_children,\n    )\n\n    return net_profit.get(account_name)\n</code></pre>"},{"location":"api/#rustfava.core.tree.Tree.cap","title":"<code>cap(options, unrealized_account)</code>","text":"<p>Transfer Income and Expenses, add conversions and unrealized gains.</p> <p>Parameters:</p> Name Type Description Default <code>options</code> <code>BeancountOptions</code> <p>The Beancount options.</p> required <code>unrealized_account</code> <code>str</code> <p>The name of the account to post unrealized gains to (as a subaccount of Equity).</p> required Source code in <code>src/rustfava/core/tree.py</code> <pre><code>def cap(self, options: BeancountOptions, unrealized_account: str) -&gt; None:\n    \"\"\"Transfer Income and Expenses, add conversions and unrealized gains.\n\n    Args:\n        options: The Beancount options.\n        unrealized_account: The name of the account to post unrealized\n            gains to (as a subaccount of Equity).\n    \"\"\"\n    equity = options[\"name_equity\"]\n    conversions = CounterInventory(\n        {\n            (currency, None): -number\n            for currency, number in AT_COST.apply(\n                self.get(\"\").balance_children\n            ).items()\n        },\n    )\n\n    # Add conversions\n    self.insert(\n        equity + \":\" + options[\"account_current_conversions\"],\n        conversions,\n    )\n\n    # Insert unrealized gains.\n    self.insert(\n        equity + \":\" + unrealized_account,\n        -self.get(\"\").balance_children,\n    )\n\n    # Transfer Income and Expenses\n    self.insert(\n        equity + \":\" + options[\"account_current_earnings\"],\n        self.get(options[\"name_income\"]).balance_children,\n    )\n    self.insert(\n        equity + \":\" + options[\"account_current_earnings\"],\n        self.get(options[\"name_expenses\"]).balance_children,\n    )\n</code></pre>"},{"location":"api/#rustfava.core.watcher","title":"<code>watcher</code>","text":"<p>A simple file and folder watcher.</p>"},{"location":"api/#rustfava.core.watcher.WatcherBase","title":"<code>WatcherBase</code>","text":"<p>               Bases: <code>ABC</code></p> <p>ABC for rustfava ledger file watchers.</p> Source code in <code>src/rustfava/core/watcher.py</code> <pre><code>class WatcherBase(abc.ABC):\n    \"\"\"ABC for rustfava ledger file watchers.\"\"\"\n\n    last_checked: int\n    \"\"\"Timestamp of the latest change noticed by the file watcher.\"\"\"\n\n    last_notified: int\n    \"\"\"Timestamp of the latest change that the watcher was notified of.\"\"\"\n\n    @abc.abstractmethod\n    def update(self, files: Iterable[Path], folders: Iterable[Path]) -&gt; None:\n        \"\"\"Update the folders/files to watch.\n\n        Args:\n            files: A list of file paths.\n            folders: A list of paths to folders.\n        \"\"\"\n\n    def check(self) -&gt; bool:\n        \"\"\"Check for changes.\n\n        Returns:\n            `True` if there was a file change in one of the files or folders,\n            `False` otherwise.\n        \"\"\"\n        latest_mtime = max(self._get_latest_mtime(), self.last_notified)\n        has_higher_mtime = latest_mtime &gt; self.last_checked\n        if has_higher_mtime:\n            self.last_checked = latest_mtime\n        return has_higher_mtime\n\n    def notify(self, path: Path) -&gt; None:\n        \"\"\"Notify the watcher of a change to a path.\"\"\"\n        try:\n            change_mtime = Path(path).stat().st_mtime_ns\n        except FileNotFoundError:\n            change_mtime = max(self.last_notified, self.last_checked) + 1\n        self.last_notified = max(self.last_notified, change_mtime)\n\n    @abc.abstractmethod\n    def _get_latest_mtime(self) -&gt; int:\n        \"\"\"Get the latest change mtime.\"\"\"\n</code></pre>"},{"location":"api/#rustfava.core.watcher.WatcherBase.last_checked","title":"<code>last_checked</code>  <code>instance-attribute</code>","text":"<p>Timestamp of the latest change noticed by the file watcher.</p>"},{"location":"api/#rustfava.core.watcher.WatcherBase.last_notified","title":"<code>last_notified</code>  <code>instance-attribute</code>","text":"<p>Timestamp of the latest change that the watcher was notified of.</p>"},{"location":"api/#rustfava.core.watcher.WatcherBase.update","title":"<code>update(files, folders)</code>  <code>abstractmethod</code>","text":"<p>Update the folders/files to watch.</p> <p>Parameters:</p> Name Type Description Default <code>files</code> <code>Iterable[Path]</code> <p>A list of file paths.</p> required <code>folders</code> <code>Iterable[Path]</code> <p>A list of paths to folders.</p> required Source code in <code>src/rustfava/core/watcher.py</code> <pre><code>@abc.abstractmethod\ndef update(self, files: Iterable[Path], folders: Iterable[Path]) -&gt; None:\n    \"\"\"Update the folders/files to watch.\n\n    Args:\n        files: A list of file paths.\n        folders: A list of paths to folders.\n    \"\"\"\n</code></pre>"},{"location":"api/#rustfava.core.watcher.WatcherBase.check","title":"<code>check()</code>","text":"<p>Check for changes.</p> <p>Returns:</p> Type Description <code>bool</code> <p><code>True</code> if there was a file change in one of the files or folders,</p> <code>bool</code> <p><code>False</code> otherwise.</p> Source code in <code>src/rustfava/core/watcher.py</code> <pre><code>def check(self) -&gt; bool:\n    \"\"\"Check for changes.\n\n    Returns:\n        `True` if there was a file change in one of the files or folders,\n        `False` otherwise.\n    \"\"\"\n    latest_mtime = max(self._get_latest_mtime(), self.last_notified)\n    has_higher_mtime = latest_mtime &gt; self.last_checked\n    if has_higher_mtime:\n        self.last_checked = latest_mtime\n    return has_higher_mtime\n</code></pre>"},{"location":"api/#rustfava.core.watcher.WatcherBase.notify","title":"<code>notify(path)</code>","text":"<p>Notify the watcher of a change to a path.</p> Source code in <code>src/rustfava/core/watcher.py</code> <pre><code>def notify(self, path: Path) -&gt; None:\n    \"\"\"Notify the watcher of a change to a path.\"\"\"\n    try:\n        change_mtime = Path(path).stat().st_mtime_ns\n    except FileNotFoundError:\n        change_mtime = max(self.last_notified, self.last_checked) + 1\n    self.last_notified = max(self.last_notified, change_mtime)\n</code></pre>"},{"location":"api/#rustfava.core.watcher.WatchfilesWatcher","title":"<code>WatchfilesWatcher</code>","text":"<p>               Bases: <code>WatcherBase</code></p> <p>A file and folder watcher using the watchfiles library.</p> Source code in <code>src/rustfava/core/watcher.py</code> <pre><code>class WatchfilesWatcher(WatcherBase):\n    \"\"\"A file and folder watcher using the watchfiles library.\"\"\"\n\n    def __init__(self) -&gt; None:\n        self.last_checked = 0\n        self.last_notified = 0\n        self._paths: tuple[set[Path], set[Path]] | None = None\n        self._watchers: tuple[_WatchfilesThread, _WatchfilesThread] | None = (\n            None\n        )\n\n    def update(self, files: Iterable[Path], folders: Iterable[Path]) -&gt; None:\n        \"\"\"Update the folders/files to watch.\"\"\"\n        files_set = {p.absolute() for p in files if p.exists()}\n        folders_set = {p.absolute() for p in folders if p.is_dir()}\n        new_paths = (files_set, folders_set)\n        if self._watchers and new_paths == self._paths:\n            self.check()\n            return\n        self._paths = new_paths\n        if self._watchers:\n            self._watchers[0].stop()\n            self._watchers[1].stop()\n        self._watchers = (\n            _FilesWatchfilesThread(files_set, self.last_checked),\n            _WatchfilesThread(folders_set, self.last_checked, recursive=True),\n        )\n        self._watchers[0].start()\n        self._watchers[1].start()\n        self.check()\n\n    def __enter__(self) -&gt; None:\n        pass\n\n    def __exit__(\n        self,\n        exc_type: type[BaseException] | None,\n        exc_value: BaseException | None,\n        traceback: types.TracebackType | None,\n    ) -&gt; None:\n        if self._watchers:\n            self._watchers[0].stop()\n            self._watchers[1].stop()\n\n    def _get_latest_mtime(self) -&gt; int:\n        return (\n            max(self._watchers[0].mtime, self._watchers[1].mtime)\n            if self._watchers\n            else 0\n        )\n</code></pre>"},{"location":"api/#rustfava.core.watcher.WatchfilesWatcher.update","title":"<code>update(files, folders)</code>","text":"<p>Update the folders/files to watch.</p> Source code in <code>src/rustfava/core/watcher.py</code> <pre><code>def update(self, files: Iterable[Path], folders: Iterable[Path]) -&gt; None:\n    \"\"\"Update the folders/files to watch.\"\"\"\n    files_set = {p.absolute() for p in files if p.exists()}\n    folders_set = {p.absolute() for p in folders if p.is_dir()}\n    new_paths = (files_set, folders_set)\n    if self._watchers and new_paths == self._paths:\n        self.check()\n        return\n    self._paths = new_paths\n    if self._watchers:\n        self._watchers[0].stop()\n        self._watchers[1].stop()\n    self._watchers = (\n        _FilesWatchfilesThread(files_set, self.last_checked),\n        _WatchfilesThread(folders_set, self.last_checked, recursive=True),\n    )\n    self._watchers[0].start()\n    self._watchers[1].start()\n    self.check()\n</code></pre>"},{"location":"api/#rustfava.core.watcher.Watcher","title":"<code>Watcher</code>","text":"<p>               Bases: <code>WatcherBase</code></p> <p>A simple file and folder watcher.</p> <p>For folders, only checks mtime of the folder and all subdirectories. So a file change won't be noticed, but only new/deleted files.</p> Source code in <code>src/rustfava/core/watcher.py</code> <pre><code>class Watcher(WatcherBase):\n    \"\"\"A simple file and folder watcher.\n\n    For folders, only checks mtime of the folder and all subdirectories.\n    So a file change won't be noticed, but only new/deleted files.\n    \"\"\"\n\n    def __init__(self) -&gt; None:\n        self.last_checked = 0\n        self.last_notified = 0\n        self._files: Sequence[Path] = []\n        self._folders: Sequence[Path] = []\n\n    def update(self, files: Iterable[Path], folders: Iterable[Path]) -&gt; None:\n        \"\"\"Update the folders/files to watch.\"\"\"\n        self._files = list(files)\n        self._folders = list(folders)\n        self.check()\n\n    def _mtimes(self) -&gt; Iterable[int]:\n        for path in self._files:\n            try:\n                yield path.stat().st_mtime_ns\n            except FileNotFoundError:\n                yield max(self.last_notified, self.last_checked) + 1\n        for path in self._folders:\n            for dirpath, _, _ in walk(path):\n                yield Path(dirpath).stat().st_mtime_ns\n\n    def _get_latest_mtime(self) -&gt; int:\n        return max(self._mtimes())\n</code></pre>"},{"location":"api/#rustfava.core.watcher.Watcher.update","title":"<code>update(files, folders)</code>","text":"<p>Update the folders/files to watch.</p> Source code in <code>src/rustfava/core/watcher.py</code> <pre><code>def update(self, files: Iterable[Path], folders: Iterable[Path]) -&gt; None:\n    \"\"\"Update the folders/files to watch.\"\"\"\n    self._files = list(files)\n    self._folders = list(folders)\n    self.check()\n</code></pre>"},{"location":"api/#application","title":"Application","text":""},{"location":"api/#rustfava.application","title":"<code>rustfava.application</code>","text":"<p>rustfava's main WSGI application.</p> <p>you can use <code>create_app</code> to create a rustfava WSGI app for a given list of files. To start a simple server::</p> <pre><code>from rustfava.application import create_app\n\napp = create_app(['/path/to/file.beancount'])\napp.run('localhost', 5000)\n</code></pre>"},{"location":"api/#rustfava.application.static_url","title":"<code>static_url(filename)</code>","text":"<p>Return a static url with an mtime query string for cache busting.</p> Source code in <code>src/rustfava/application.py</code> <pre><code>def static_url(filename: str) -&gt; str:\n    \"\"\"Return a static url with an mtime query string for cache busting.\"\"\"\n    file_path = Path(__file__).parent / \"static\" / filename\n    try:\n        mtime = str(int(file_path.stat().st_mtime))\n    except FileNotFoundError:\n        mtime = \"0\"\n    return url_for(\"static\", filename=filename, mtime=mtime)\n</code></pre>"},{"location":"api/#rustfava.application.url_for","title":"<code>url_for(endpoint, **values)</code>","text":"<p>Wrap flask.url_for using a cache.</p> Source code in <code>src/rustfava/application.py</code> <pre><code>def url_for(endpoint: str, **values: str) -&gt; str:\n    \"\"\"Wrap flask.url_for using a cache.\"\"\"\n    _inject_filters(endpoint, values)\n    return _cached_url_for(endpoint, **values)\n</code></pre>"},{"location":"api/#rustfava.application.translations","title":"<code>translations()</code>","text":"<p>Get translations catalog.</p> Source code in <code>src/rustfava/application.py</code> <pre><code>def translations() -&gt; dict[str, str]:\n    \"\"\"Get translations catalog.\"\"\"\n    catalog = get_translations()._catalog  # noqa: SLF001\n    return {k: v for k, v in catalog.items() if isinstance(k, str) and k}\n</code></pre>"},{"location":"api/#rustfava.application.create_app","title":"<code>create_app(files, *, load=False, incognito=False, read_only=False, poll_watcher=False)</code>","text":"<p>Create a rustfava Flask application.</p> <p>Parameters:</p> Name Type Description Default <code>files</code> <code>Iterable[Path | str]</code> <p>The list of Beancount files (paths).</p> required <code>load</code> <code>bool</code> <p>Whether to load the Beancount files directly.</p> <code>False</code> <code>incognito</code> <code>bool</code> <p>Whether to run in incognito mode.</p> <code>False</code> <code>read_only</code> <code>bool</code> <p>Whether to run in read-only mode.</p> <code>False</code> <code>poll_watcher</code> <code>bool</code> <p>Whether to use old poll watcher</p> <code>False</code> Source code in <code>src/rustfava/application.py</code> <pre><code>def create_app(\n    files: Iterable[Path | str],\n    *,\n    load: bool = False,\n    incognito: bool = False,\n    read_only: bool = False,\n    poll_watcher: bool = False,\n) -&gt; Flask:\n    \"\"\"Create a rustfava Flask application.\n\n    Arguments:\n        files: The list of Beancount files (paths).\n        load: Whether to load the Beancount files directly.\n        incognito: Whether to run in incognito mode.\n        read_only: Whether to run in read-only mode.\n        poll_watcher: Whether to use old poll watcher\n    \"\"\"\n    fava_app = Flask(\"rustfava\")\n    fava_app.register_blueprint(json_api, url_prefix=\"/&lt;bfile&gt;/api\")\n    fava_app.json = RustfavaJSONProvider(fava_app)\n    fava_app.app_ctx_globals_class = Context  # type: ignore[assignment]\n    _setup_template_config(fava_app, incognito=incognito)\n    _setup_babel(fava_app)\n    _setup_filters(fava_app, read_only=read_only)\n    _setup_routes(fava_app)\n\n    fava_app.config[\"HAVE_EXCEL\"] = HAVE_EXCEL\n    fava_app.config[\"BEANCOUNT_FILES\"] = [str(f) for f in files]\n    fava_app.config[\"INCOGNITO\"] = incognito\n    fava_app.config[\"LEDGERS\"] = _LedgerSlugLoader(\n        fava_app, load=load, poll_watcher=poll_watcher\n    )\n\n    return fava_app\n</code></pre>"},{"location":"api/#cli","title":"CLI","text":""},{"location":"api/#rustfava.cli","title":"<code>rustfava.cli</code>","text":"<p>The command-line interface for rustfava.</p>"},{"location":"api/#rustfava.cli.main","title":"<code>main(*, filenames=(), port=5000, host='localhost', prefix=None, incognito=False, read_only=False, debug=False, profile=False, profile_dir=None, poll_watcher=False)</code>","text":"<p>Start Rustfava for FILENAMES on http://:. <p>If the <code>BEANCOUNT_FILE</code> environment variable is set, Rustfava will use the files (delimited by ';' on Windows and ':' on POSIX) given there in addition to FILENAMES.</p> <p>Note you can also specify command-line options via environment variables with the <code>RUSTFAVA_</code> prefix. For example, <code>--host=0.0.0.0</code> is equivalent to setting the environment variable <code>RUSTFAVA_HOST=0.0.0.0</code>.</p> Source code in <code>src/rustfava/cli.py</code> <pre><code>@click.command(context_settings={\"auto_envvar_prefix\": \"RUSTFAVA\"})\n@click.argument(\n    \"filenames\",\n    nargs=-1,\n    type=click.Path(exists=True, dir_okay=False, resolve_path=True),\n)\n@click.option(\n    \"-p\",\n    \"--port\",\n    type=int,\n    default=5000,\n    show_default=True,\n    metavar=\"&lt;port&gt;\",\n    help=\"The port to listen on.\",\n)\n@click.option(\n    \"-H\",\n    \"--host\",\n    type=str,\n    default=\"localhost\",\n    show_default=True,\n    metavar=\"&lt;host&gt;\",\n    help=\"The host to listen on.\",\n)\n@click.option(\"--prefix\", type=str, help=\"Set an URL prefix.\")\n@click.option(\n    \"--incognito\",\n    is_flag=True,\n    help=\"Run in incognito mode and obscure all numbers.\",\n)\n@click.option(\n    \"--read-only\",\n    is_flag=True,\n    help=\"Run in read-only mode, disable any change through rustfava.\",\n)\n@click.option(\"-d\", \"--debug\", is_flag=True, help=\"Turn on debugging.\")\n@click.option(\n    \"--profile\",\n    is_flag=True,\n    help=\"Turn on profiling. Implies --debug.\",\n)\n@click.option(\n    \"--profile-dir\",\n    type=click.Path(),\n    help=\"Output directory for profiling data.\",\n)\n@click.option(\n    \"--poll-watcher\", is_flag=True, help=\"Use old polling-based watcher.\"\n)\n@click.version_option(package_name=\"rustfava\")\ndef main(  # noqa: PLR0913\n    *,\n    filenames: tuple[str, ...] = (),\n    port: int = 5000,\n    host: str = \"localhost\",\n    prefix: str | None = None,\n    incognito: bool = False,\n    read_only: bool = False,\n    debug: bool = False,\n    profile: bool = False,\n    profile_dir: str | None = None,\n    poll_watcher: bool = False,\n) -&gt; None:  # pragma: no cover\n    \"\"\"Start Rustfava for FILENAMES on http://&lt;host&gt;:&lt;port&gt;.\n\n    If the `BEANCOUNT_FILE` environment variable is set, Rustfava will use the\n    files (delimited by ';' on Windows and ':' on POSIX) given there in\n    addition to FILENAMES.\n\n    Note you can also specify command-line options via environment variables\n    with the `RUSTFAVA_` prefix. For example, `--host=0.0.0.0` is equivalent to\n    setting the environment variable `RUSTFAVA_HOST=0.0.0.0`.\n    \"\"\"\n    all_filenames = _add_env_filenames(filenames)\n\n    if not all_filenames:\n        raise NoFileSpecifiedError\n\n    from rustfava.application import create_app\n\n    app = create_app(\n        all_filenames,\n        incognito=incognito,\n        read_only=read_only,\n        poll_watcher=poll_watcher,\n    )\n\n    if prefix:\n        from werkzeug.middleware.dispatcher import DispatcherMiddleware\n\n        from rustfava.util import simple_wsgi\n\n        app.wsgi_app = DispatcherMiddleware(  # type: ignore[method-assign]\n            simple_wsgi,\n            {prefix: app.wsgi_app},\n        )\n\n    # ensure that cheroot does not use IP6 for localhost\n    host = \"127.0.0.1\" if host == \"localhost\" else host\n    # Debug mode if profiling is active\n    debug = debug or profile\n\n    click.secho(f\"Starting Fava on http://{host}:{port}\", fg=\"green\")\n    if not debug:\n        from cheroot.wsgi import Server\n\n        server = Server((host, port), app)\n        try:\n            server.start()\n        except KeyboardInterrupt:\n            click.echo(\"Keyboard interrupt received: stopping Fava\", err=True)\n            server.stop()\n        except OSError as error:\n            if \"No socket could be created\" in str(error):\n                raise AddressInUse(port) from error\n            raise click.Abort from error\n    else:\n        from werkzeug.middleware.profiler import ProfilerMiddleware\n\n        from rustfava.util import setup_debug_logging\n\n        setup_debug_logging()\n        if profile:\n            app.wsgi_app = ProfilerMiddleware(  # type: ignore[method-assign]\n                app.wsgi_app,\n                restrictions=(30,),\n                profile_dir=profile_dir or None,\n            )\n\n        app.jinja_env.auto_reload = True\n        try:\n            app.run(host, port, debug)\n        except OSError as error:\n            if error.errno == errno.EADDRINUSE:\n                raise AddressInUse(port) from error\n            raise\n</code></pre>"},{"location":"changelog/","title":"Changelog","text":""},{"location":"changelog/#rustfava-2025","title":"Rustfava (2025)","text":"<p>This is a fork of Fava that replaces the Python Beancount parser and beanquery with rustledger, a Rust-based implementation of the Beancount format compiled to WebAssembly.</p> <p>Key changes from Fava:</p> <ul> <li>No Beancount dependency: Rustfava uses rustledger for parsing, so you   don't need to install Python's beancount package. Your existing Beancount   files are fully compatible.</li> <li>Query support: BQL queries are now handled by rustledger's built-in query   engine instead of beanquery. The query syntax remains largely compatible.</li> <li>Optional beancount compatibility: If you need to use Beancount plugins or   the import system, install with <code>uv pip install rustfava[beancount-compat]</code>.</li> </ul>"},{"location":"changelog/#v130-2024-12-29","title":"v1.30 (2024-12-29)","text":"<p>Note: This entry describes the original Fava release. Rustfava is based on this version with the rustledger integration.</p> <p>Under the hood, this also upgrades Svelte (the framework used for the frontend parts) to version 5.</p>"},{"location":"changelog/#v129-2024-10-09","title":"v1.29 (2024-10-09)","text":"<p>With this release, query results are now rendered in the frontend. The templates for HTML rendering are still available but extension authors are encouraged to switch, see the statistics report for an example how this can be done. This release adds CSS styles for dark-mode. Numerical comparisons on the units, price or cost are now possible in rustfava filters. As the watchfiles based watcher might not work correctly in some setups with network file systems, you can switch to the (slower) polling based watcher as well. The <code>default-file</code> option, if set, is now considered instead of the \"main\" file when inserting an entry.</p>"},{"location":"changelog/#v128-2024-07-07","title":"v1.28 (2024-07-07)","text":"<p>This release accumulates a couple of minor fixes and improvements. Under the hood, the file change detection is now powered by watchfiles instead of polling, which is more performant.</p>"},{"location":"changelog/#v127-2024-01-06","title":"v1.27 (2024-01-06)","text":"<p>It is now possible to convert to a sequence of currencies. Posting metadata is now supported in the entry forms. The editor should now be a bit more performant as the previous parses will be reused better. For compatibility with extensions using them, the Javascript and CSS for the \"old\" account trees has been re-added.</p>"},{"location":"changelog/#v126-2023-09-04","title":"v1.26 (2023-09-04)","text":"<p>This release brings various improvements to the charts, like allowing the toggling of currencies by clicking on their names in the chart legend. The account balance trees in rustfava are now rendered in the frontend, fixing some minor bugs in the process and easing maintenance. rustfava extensions can now also provide their own endpoints.</p>"},{"location":"changelog/#v125-2023-07-17","title":"v1.25 (2023-07-17)","text":"<p>With this release, extensions can now ship Javascript code to run in the frontend. The editor in rustfava now uses a tree-sitter grammar to obtain a full parsed syntax tree, which makes editor functionality more maintainable and should improve the autocompletion. The Flask WSGI app is now created using the application factory pattern - users who use the rustfava WSGI app directly should switch from <code>rustfava.application.app</code> to the <code>create_app</code> function in <code>rustfava.application</code>. This release also drops support for Python 3.7 and contains a couple of minor fixes and changes, in particular various styling fixes.</p>"},{"location":"changelog/#v124-2023-02-21","title":"v1.24 (2023-02-21)","text":"<p>With this release, the rendering of some report like the documents report has been moved completely to the frontend, which should be slightly more perfomant and easier to maintain. This release also contains a couple of minor fixes and changes.</p>"},{"location":"changelog/#v123-2022-10-15","title":"v1.23 (2022-10-15)","text":"<p>This release accumulates a couple of minor fixes and changes.</p>"},{"location":"changelog/#v122-2022-07-03","title":"v1.22 (2022-07-03)","text":"<p>This release brings stacked bar charts, which are a great way to visualise income broken down per account per month for example. The inferred display precision for currencies is now also used in the frontend and can be overwritten with commodity metadata.</p> <p>The <code>journal-show</code>, <code>journal-show-document</code>, and <code>journal-show-transaction</code> rustfava-options have been removed. The types of entries that to show in the journal are now automatically stored in the browser of the user (in localStorage).</p> <p>As usual, this release also includes a couple of bug fixes and minor improvements. To avoid some race conditions and improve perfomance, the per-file Ledger class is not filtered anymore in-place but rather the filtered data is generated per request - some extensions might have to adjust for this and use <code>g.filtered</code> instead of <code>ledger</code> for some attributes.</p>"},{"location":"changelog/#v121-2022-02-06","title":"v1.21 (2022-02-06)","text":"<p>This release of rustfava drops support for Python 3.6. It mainly consists of various small improvements and fixes.</p>"},{"location":"changelog/#v1201-2021-09-22","title":"v1.20.1 (2021-09-22)","text":"<p>Bugfix release to fix loading of translations for the browser-rendered frontend parts.</p>"},{"location":"changelog/#v120-2021-09-19","title":"v1.20 (2021-09-19)","text":"<p>In this release, the document page now shows counts in the account tree and allows collapsing of accounts in the tree. Parts of the charts in the future are now desaturated. This release contains a couple of bug fixes as usual.</p>"},{"location":"changelog/#v119-2021-05-18","title":"v1.19 (2021-05-18)","text":"<p>The <code>conversion</code> and <code>interval</code> options have been removed. Their functionality can be achieved with the new <code>default-page</code> option. The editor components have been completely reworked, include autocompletion in more places and are now based on version 6 of CodeMirror. An option <code>invert-income-liabilities-equity</code> has been added to invert the numbers of those accounts on the income statement and the balance sheet. This release also adds a Bulgarian translation and features various smaller improvements and fixes as usual.</p>"},{"location":"changelog/#v118-2021-01-16","title":"v1.18 (2021-01-16)","text":"<p>This release contains couple of small improvements and various bug fixes.</p>"},{"location":"changelog/#v117-2020-11-15","title":"v1.17 (2020-11-15)","text":"<p>This release adds a document preview to the import page, as well as support for Python 3.9. It also fixes a couple of bugs.</p>"},{"location":"changelog/#v116-2020-10-18","title":"v1.16 (2020-10-18)","text":"<p>This release brings area charts as an alternative option to view the various line charts in rustfava and a Catalan translation for rustfava. There is also now an option to set the indentation of inserted Beancount entries. As usual this release also includes various minor fixes and improvements.</p>"},{"location":"changelog/#v115-2020-05-30","title":"v1.15 (2020-05-30)","text":"<p>This release accumulates various minor fixes and improvements, for example the setting of filters from payees and metadata in the Journal report.</p>"},{"location":"changelog/#v114-2020-02-16","title":"v1.14 (2020-02-16)","text":"<p>This is mainly a bugfix release to fix compatibility with one of the main dependencies (werkzeug). Also, a <code>default-conversion</code> option was added, which allows setting a default conversion.</p>"},{"location":"changelog/#v113-2020-02-01","title":"v1.13 (2020-02-01)","text":"<p>Rustfava can now display charts for BQL queries - if they have exactly two columns 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.</p>"},{"location":"changelog/#v112-2019-12-03","title":"v1.12 (2019-12-03)","text":"<p>Apart from plenty of bug fixes, this release mainly contains improvements to the forms to add transactions: postings can now be dragged and the full cost syntax of Beancount should supported.</p>"},{"location":"changelog/#v111-2019-08-20","title":"v1.11 (2019-08-20)","text":"<p>The import page of rustfava has been reworked - it now supports moving files to the documents folder and the import process should be a bit more interactive. This release also contains various fixes and a new <code>collapse-pattern</code> option to collapse accounts in account trees based on regular expressions (and replaces the use of the <code>rustfava-collapse-account</code> metadata entry).</p> <p>Other changes:</p> <ul> <li>Command line flags can be specified by setting environment variables.</li> <li>A Taiwanese translation has been added.</li> </ul>"},{"location":"changelog/#v110-2019-01-31","title":"v1.10 (2019-01-31)","text":"<p>This release contains mostly smaller changes and fixes. In particular, the net worth chart will now follow the selected conversion.</p>"},{"location":"changelog/#v19-2018-10-08","title":"v1.9 (2018-10-08)","text":"<p>In this release, the click behaviour has been updated to allow filtering for payees. The entry input forms now allow inputting prices and costs. As always, bugs have been fixed.</p>"},{"location":"changelog/#v18-2018-07-25","title":"v1.8 (2018-07-25)","text":"<p>The journal design has been updated and should now have a clearer structure. Starting with this version, there will not be any more GUI releases of rustfava. The GUI broke frequently and does not seem to worth the maintenance burden.</p> <p>Other changes:</p> <ul> <li>When downloading documents, the original filename will be used.</li> <li><code>any()</code> and <code>all()</code> functions have been added to the filter syntax to allow   filtering entries by properties of their postings.</li> <li>As always, bugs have been fixed.</li> </ul>"},{"location":"changelog/#v17-2018-03-09","title":"v1.7 (2018-03-09)","text":"<p>The entry filters have been reworked in this release and should now support for more flexible filtering of the entries. See the help page on how the new syntax works. Also, when completing the payee in the transaction form, the postings of the last transaction for this payee will be auto-filled.</p> <p>Other changes:</p> <ul> <li>The rustfava-option to hide the charts has been removed. This is now tracked in   the page URL.</li> <li>As always, bugs have been fixed.</li> </ul>"},{"location":"changelog/#v16-2017-10-06","title":"v1.6 (2017-10-06)","text":"<p>This is a release with various small changes and mainly some speed improvements to the Balance Sheet and the net worth calculation. Also, if 'At Value' is selected, the current unrealized gain is shown in parentheses in the Balance Sheet.</p> <p>Other changes:</p> <ul> <li>The currently filtered entries can now be exported from the Journal page.</li> <li>The CLI now has a <code>--version</code> flag.</li> </ul>"},{"location":"changelog/#v15-2017-07-23","title":"v1.5 (2017-07-23)","text":"<p>Rustfava now has an interface to edit single entries. Clicking on the entry date in the Journal will open an overlay that shows the entry context and allows editing just the lines of that entry.</p> <p>Other changes:</p> <ul> <li>The source editor now has a menu that gives access to editor commands like   \"fold all\".</li> <li>Entries with matching tags or links can now be excluded with <code>-#tag</code>.</li> <li>The keyboard shortcuts are now displayed in-place.</li> <li>The <code>incognito</code> option has been removed and replaced with a <code>--incognito</code>   command line switch.</li> <li>As always, several bugs have been fixed.</li> </ul>"},{"location":"changelog/#v14-2017-05-14","title":"v1.4 (2017-05-14)","text":"<p>Rustfava now provides an interface for Beancount's import system that allows you to import transactions from your bank for example.</p> <p>Rustfava can now show your balances at market value or convert them to a single currency if your file contains the necessary price information.</p> <p>We now also provide a compiled GUI version of rustfava for Linux and macOS. This version might still be a bit buggy so any feedback/help on it is very welcome.</p> <p>Other changes:</p> <ul> <li>The <code>insert-entry</code> option can be used to control where transactions are   inserted.</li> <li>The transaction form now accepts tags and links in the narration field.</li> <li>Budgets are now accumulated over all children where appropriate.</li> <li>As always, several bugs have been fixed.</li> </ul>"},{"location":"changelog/#v13-2017-03-15","title":"v1.3 (2017-03-15)","text":"<p>The translations of rustfava are on POEditor.com, which has helped us get translations in five more languages: Chinese (simplified), Dutch, French, Portuguese, and Spanish. A big thank you to the new translators!</p> <p>The transaction form has been improved, it now supports adding metadata and the suggestions will be ranked by how often and recently they occur (using exponential decay).</p> <p>The Query page supports all commands of the <code>bean-query</code> shell and shares its history of recently used queries.</p> <p>Rustfava has gained a basic extension mechanism. Extensions allow you to run hooks at various points, e.g., after adding a transaction. They are specified using the <code>extensions</code> option and for an example, see the <code>rustfava.ext.auto_commit</code> extension.</p> <p>Other changes:</p> <ul> <li>The default sort order in journals has been reversed so that the most recent   entries come first.</li> <li>The new <code>incognito</code> option can be used to obscure all numbers.</li> <li>As always, several bugs have been fixed.</li> </ul>"},{"location":"changelog/#v12-2016-12-25","title":"v1.2 (2016-12-25)","text":"<p>You can now add transactions from within rustfava. The form supports autocompletion for most fields.</p> <p>Rustfava will now show a little bubble in the sidebar for the number of events in the next week. This can be configured with the <code>upcoming-events</code> option.</p> <p>Other changes:</p> <ul> <li>The payee filter can filter by regular expression.</li> <li>The tag filter can filter for links, too.</li> <li>There's a nice spinning indicator during asynchronous page loads.</li> <li>The Journal shows little indicators for metadata.</li> <li>As always, several bugs have been fixed.</li> </ul>"},{"location":"changelog/#v11-2016-11-19","title":"v1.1 (2016-11-19)","text":"<p>You can now upload documents by dropping them onto transactions, which will also add the file path as <code>statement</code> metadata to the transaction. rustfava also ships with a plugin to link these transactions with the generated documents. See the help pages for details.</p> <p>This is the first release for which we provide compiled binaries (for macOS and Linux). These do not have any dependencies and can simply be executed from the terminal.</p> <p>Other changes:</p> <ul> <li>The bar charts on account pages now also show budgets.</li> <li>The Journal can now be sorted by date, flag and narration.</li> <li>Rustfava now has a Russian translation.</li> <li>As always, several bugs have been fixed.</li> </ul>"},{"location":"changelog/#v10-2016-10-19","title":"v1.0 (2016-10-19)","text":"<p>This is a major new release that includes too many improvements and changes to list. Some highlights:</p> <ul> <li>The layout has been tweaked and we use some nicer fonts.</li> <li>Rustfava looks and works much better on smaller screens.</li> <li>Rustfava loads most pages asynchronously, so navigating rustfava is much faster and   responsive.</li> </ul> <p>rustfava's configuration is not read from a configuration file anymore but can rather be specified using custom entries in the Beancount file. Some options have also been removed or renamed, so check rustfava's help page on the available options when upgrading from v0.3.0.</p> <p>There have been many changes under the hood to improve rustfava's codebase and a lot of bugs have been squashed.</p>"},{"location":"changelog/#v030-2016-03-24","title":"v0.3.0 (2016-03-24)","text":""},{"location":"changelog/#additions","title":"Additions","text":"<ul> <li>Support for switching between multiple beancount files.</li> <li>New sunburst charts.</li> <li>Add \"Clear filter\" button when filters are active.</li> <li>Simple budgeting functionality in the Account view. See help pages on how to   use budgets.</li> <li>German translation.</li> <li>The Beancount is now being reloaded when it is saved in the Source Editor.</li> <li>New Journal filter controls.</li> <li>Tree-tables are now displayed in a hierarchical way.</li> </ul>"},{"location":"changelog/#changes","title":"Changes","text":"<ul> <li>All charts are now rendered with d3.js.</li> <li>The title of a page is now shown in the header to save screen space.</li> <li>Changed shortcut for Journal from <code>g g</code> to <code>g j</code> as the Journal was   renamed from \"General Journal\" to \"Journal\".</li> </ul>"},{"location":"changelog/#new-configuration-options","title":"New configuration options","text":"<ul> <li><code>language</code>: The language to use. Valid languages are <code>\"en\"</code> and <code>\"de\"</code>   (default: <code>\"en\"</code>).</li> <li><code>treemaps-show-negative-numbers</code> was removed.</li> </ul>"},{"location":"changelog/#fixes","title":"Fixes","text":"<ul> <li>Commodity prices are now filtered when a Time filter is enabled.</li> <li>Some improvements to the help pages.</li> <li>Many small bug fixes.</li> </ul>"},{"location":"changelog/#v026-2016-03-20","title":"v0.2.6 (2016-03-20)","text":""},{"location":"changelog/#additions_1","title":"Additions","text":"<ul> <li>There are now more interval options available for charts and the account   balances report. The interval can be selected from a dropdown next to the   charts.</li> <li>Show metadata for postings in the Journal.</li> <li>The editor now supports org-mode style folding.</li> <li>Show colored dots for all the postings of a transaction in the Journal   report. This way flagged postings can be quickly spotted.</li> <li>Add keyboard shortcuts for save to source editor.</li> </ul>"},{"location":"changelog/#changes_1","title":"Changes","text":"<ul> <li>Use beancount's DisplayContext to determine the correct precision at which to   render numbers.</li> <li>Improve the way that query results are serialized to XLS etc.</li> <li>Show inverse rates for pairs of operating currencies on the commodities   report.</li> <li>Use Click for the CLI and check if beancount file exists on startup.</li> <li>Hide closed accounts in tree tables. Also see new configuration option below.</li> </ul>"},{"location":"changelog/#new-configuration-options_1","title":"New configuration options","text":"<ul> <li><code>editor-strip-trailing-whitespace</code> to enable trimming of trailing   whitespace in the Source editor (default: \"false\").</li> <li><code>show-closed-accounts</code> to show closed accounts in tree tables, for example   on the balance sheet (default: \"false\").</li> <li><code>show-accounts-with-zero-balance</code> to show accounts with a balance of zero   in tree tables (default: \"true\").</li> <li><code>show-accounts-with-zero-transactions</code> to show accounts with no   transactions in tree tables (default: \"true\").</li> </ul>"},{"location":"changelog/#fixes_1","title":"Fixes","text":"<ul> <li>Fixed a bug where the months would be off by one for the interval reports.</li> <li>Fix the net worth report for more than one currency.</li> <li>Some improvements to the help pages.</li> <li>Many small bug fixes.</li> </ul>"},{"location":"changelog/#v025-2016-02-28","title":"v0.2.5 (2016-02-28)","text":"<p>Bump release to remove unused draft code.</p>"},{"location":"changelog/#v024-2016-02-18","title":"v0.2.4 (2016-02-18)","text":""},{"location":"changelog/#additions_2","title":"Additions","text":"<ul> <li>Added missing Holdings views compared to <code>bean-web</code>.</li> <li>Custom queries are now shown in sidebar.</li> <li>The user settings file is now editable in the Source editor.</li> <li>Added second theme.</li> <li>Added Help pages.</li> <li>Query results can now be downloaded as CSV, XLS, XLSX and ODS.</li> <li>Documents can now be uploaded by dragging and dropping files over an Account   name on the Account page and all tree-tables.</li> <li>Journal can now be filtered by transaction type.</li> </ul>"},{"location":"changelog/#changes_2","title":"Changes","text":"<ul> <li>The uptodate-indicator is now shown everywhere by default, but only enabled   for accounts that have the metadata <code>rustfava-uptodate-indication: \"True\"</code> set   on their <code>open</code>-directives.</li> <li>Speedier Journal rendering.</li> <li>Only basenames will be shown for documents in the Journal.</li> <li>Slightly reordered the sidebar menu.</li> <li>Minor UI tweaks.</li> </ul>"},{"location":"changelog/#new-configuration-options_2","title":"New configuration options","text":"<ul> <li><code>sidebar-show-queries</code>: The maximum number of custom queries to show in the   sidebar (default: 5).</li> <li><code>theme</code>: The theme to use. Valid themes are <code>\"default\"</code> and <code>\"alternative\"</code>   (default: <code>\"default\"</code>).</li> <li><code>editor-print-margin-column</code>: Set the column for the print margin in the   Source editor (default: 60).</li> <li><code>uptodate-indicator-show-everywhere</code> (default: \"true\"). See Changes above.</li> </ul>"},{"location":"changelog/#removed-configuration-options","title":"Removed configuration options","text":"<ul> <li><code>uptodate-indicator-exclude-accounts</code>, see Changes above.</li> </ul>"},{"location":"changelog/#fixes_2","title":"Fixes","text":"<ul> <li>Fixed Net worth calculation.</li> <li>Many small bug fixes.</li> </ul>"},{"location":"changelog/#v023-2016-02-15","title":"v0.2.3 (2016-02-15)","text":"<p>Bumped version to communicate that installing via <code>pip install</code> now works, all requirements included.</p>"},{"location":"changelog/#earlier-versions","title":"Earlier Versions","text":"<p>It was not possible to install any of the earlier versions only using <code>pip</code> and you may consult the git log for earlier changes. The first commit in the git repository was on December 4th, 2015.</p>"},{"location":"deployment/","title":"Deployment","text":"<p>There are several ways to deploy rustfava depending on your needs.</p>"},{"location":"deployment/#desktop-app","title":"Desktop App","text":"<p>For personal use, the desktop app is the simplest option. It runs entirely locally with no server setup required.</p>"},{"location":"deployment/#docker","title":"Docker","text":"<p>For server deployments, Docker is recommended:</p> <pre><code>docker run -p 5000:5000 -v /path/to/ledger:/data ghcr.io/rustledger/rustfava /data/main.beancount\n</code></pre> <p>For advanced Docker configurations (authentication, HTTPS, docker-compose), see the Docker deployment guide.</p>"},{"location":"deployment/#systemd-service","title":"Systemd Service","text":"<p>To run rustfava as a system service on Linux:</p> <pre><code># /etc/systemd/system/rustfava.service\n[Unit]\nDescription=rustfava Web UI for Beancount\nAfter=network.target\n\n[Service]\nType=simple\nExecStart=/usr/bin/rustfava --host 127.0.0.1 --port 5000 /path/to/main.beancount\nUser=your-user\nRestart=on-failure\n\n[Install]\nWantedBy=multi-user.target\n</code></pre> <p>Then:</p> <pre><code>sudo systemctl enable rustfava\nsudo systemctl start rustfava\n</code></pre>"},{"location":"deployment/#reverse-proxy","title":"Reverse Proxy","text":""},{"location":"deployment/#apache","title":"Apache","text":"<pre><code>ProxyPass \"/rustfava\" \"http://localhost:5000/rustfava\"\nProxyPassReverse \"/rustfava\" \"http://localhost:5000/rustfava\"\n</code></pre> <p>Run rustfava with the <code>--prefix</code> option:</p> <pre><code>rustfava --prefix /rustfava /path/to/main.beancount\n</code></pre>"},{"location":"deployment/#nginx","title":"Nginx","text":"<pre><code>location /rustfava/ {\n    proxy_pass http://127.0.0.1:5000/rustfava/;\n    proxy_set_header Host $host;\n    proxy_set_header X-Real-IP $remote_addr;\n    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n    proxy_set_header X-Forwarded-Proto $scheme;\n}\n</code></pre>"},{"location":"deployment/#caddy","title":"Caddy","text":"<pre><code>your-domain.com {\n    reverse_proxy localhost:5000\n}\n</code></pre> <p>Caddy automatically handles HTTPS with Let's Encrypt.</p>"},{"location":"deployment/#security-considerations","title":"Security Considerations","text":"<p>When exposing rustfava to the internet:</p> <ol> <li>Use HTTPS - Never expose plain HTTP to the public internet</li> <li>Add authentication - Use a reverse proxy with OAuth2 or basic auth</li> <li>Restrict access - Use firewall rules to limit access to trusted IPs</li> <li>Keep updated - Regularly update rustfava for security patches</li> </ol> <p>See SECURITY.md for more security best practices.</p>"},{"location":"development/","title":"Development","text":""},{"location":"development/#setting-up-a-development-environment","title":"Setting up a development environment","text":"<p>If you want to hack on rustfava or run the latest development version, make sure you have recent enough versions of the following installed (ideally with your system package manager):</p> <ul> <li>Python 3.13+ - as rustfava is written in Python</li> <li>Bun - to build the frontend</li> <li>just - to run various build / lint / test targets</li> <li>uv - to install the development environment and run scripts</li> </ul> <p>Then this will get you up and running:</p> <pre><code>git clone https://github.com/rustledger/rustfava.git\ncd rustfava\n# setup a virtual environment (at .venv) and install rustfava and development\n# dependencies into it:\njust dev\n</code></pre> <p>You can start rustfava in the virtual environment as usual by running <code>rustfava</code>. Running in debug mode with <code>rustfava --debug</code> is useful for development.</p> <p>You can run the tests with <code>just test</code> and the linters by running <code>just lint</code>. Run <code>just --list</code> to see all available recipes. After any changes to the Javascript code, you will need to re-build the frontend, which you can do by running <code>just frontend</code>. If you are working on the frontend code, running <code>bun run dev</code> in the <code>frontend</code> folder will watch for file changes and rebuild the Javascript bundle continuously.</p> <p>Contributions are very welcome, just open a PR on GitHub.</p> <p>Rustfava is released under the MIT License.</p>"},{"location":"upstream-sync/","title":"Syncing with Upstream Fava","text":"<p>rustfava is a fork of Fava that replaces the beancount parser with rustledger. This document describes how to sync relevant changes from upstream.</p>"},{"location":"upstream-sync/#background","title":"Background","text":"<p>The fork diverges significantly from upstream in the backend:</p> Component Fava rustfava Parser Python beancount rustledger (WASM) Core modules <code>fava/core/</code>, <code>fava/beans/</code> <code>rustfava/rustledger/</code> Package manager npm bun <p>The frontend is largely unchanged and can usually accept upstream patches.</p>"},{"location":"upstream-sync/#checking-for-upstream-changes","title":"Checking for Upstream Changes","text":"<pre><code># Fetch upstream\ngit fetch upstream\n\n# Find the common ancestor (fork point)\ngit merge-base main upstream/main\n\n# Count commits since fork\ngit rev-list --count $(git merge-base main upstream/main)..upstream/main\n\n# List upstream commits since fork\ngit log --oneline $(git merge-base main upstream/main)..upstream/main\n</code></pre>"},{"location":"upstream-sync/#categorizing-commits","title":"Categorizing Commits","text":"<p>Review each upstream commit and categorize:</p>"},{"location":"upstream-sync/#safe-to-cherry-pick","title":"Safe to cherry-pick","text":"<ul> <li>Frontend changes (<code>frontend/src/</code>) - UI, routing, components</li> <li>Documentation (<code>docs/</code>, <code>*.md</code>)</li> <li>Templates (<code>src/fava/templates/</code>)</li> <li>Static assets (<code>src/fava/static/</code>)</li> <li>Extension API (if not touching core)</li> </ul>"},{"location":"upstream-sync/#requires-review","title":"Requires review","text":"<ul> <li>Tests - may reference beancount-specific behavior</li> <li>API endpoints - check if they depend on beancount types</li> </ul>"},{"location":"upstream-sync/#cannot-cherry-pick","title":"Cannot cherry-pick","text":"<ul> <li>Core modules - <code>src/fava/core/</code>, <code>src/fava/beans/</code></li> <li>Beancount imports - anything importing from <code>beancount.*</code></li> <li>Inventory/position logic - replaced by rustledger</li> </ul>"},{"location":"upstream-sync/#cherry-pick-workflow","title":"Cherry-Pick Workflow","text":"<pre><code># 1. Create a sync branch\ngit checkout main\ngit pull origin main\ngit checkout -b sync/upstream-YYYY-MM\n\n# 2. Cherry-pick safe commits (oldest first)\ngit cherry-pick &lt;commit-hash&gt;\n\n# 3. If conflicts occur, resolve them:\n#    - For package-lock.json conflicts: git rm frontend/package-lock.json\n#    - For renamed files (fava -&gt; rustfava): update paths\n#    - For deleted files: skip the commit with git cherry-pick --skip\n\n# 4. Update lockfile if package.json changed\nnix develop --command bash -c \"cd frontend &amp;&amp; bun install\"\ngit add frontend/bun.lock\ngit commit -m \"chore: update bun.lock for upstream sync\"\n\n# 5. Test the build\nnix develop --command bash -c \"cd frontend &amp;&amp; bun run build\"\nnix develop --command bash -c \"just test\"\n\n# 6. Push and create PR\ngit push -u origin sync/upstream-YYYY-MM\ngh pr create --title \"chore: sync upstream fava changes (Month YYYY)\"\n</code></pre>"},{"location":"upstream-sync/#common-conflicts","title":"Common Conflicts","text":""},{"location":"upstream-sync/#package-lockjson","title":"package-lock.json","text":"<p>rustfava uses bun instead of npm. Remove the conflicting file:</p> <pre><code>git rm frontend/package-lock.json\ngit cherry-pick --continue\n</code></pre>"},{"location":"upstream-sync/#file-renames-fava-rustfava","title":"File renames (fava -&gt; rustfava)","text":"<p>Upstream references <code>src/fava/</code> but rustfava uses <code>src/rustfava/</code>. The cherry-pick usually handles this via directory mapping, but manual fixes may be needed.</p>"},{"location":"upstream-sync/#deleted-core-files","title":"Deleted core files","text":"<p>If upstream modifies files that rustfava deleted (like <code>core/inventory.py</code>), skip the commit:</p> <pre><code>git cherry-pick --skip\n</code></pre>"},{"location":"upstream-sync/#after-syncing","title":"After Syncing","text":"<ol> <li>Run the test suite: <code>just test</code></li> <li>Build the frontend: <code>just frontend</code></li> <li>Manual testing: Start the app and verify functionality</li> <li>Update this doc: Note the last sync date and any new patterns</li> </ol>"},{"location":"upstream-sync/#sync-history","title":"Sync History","text":"Date PR Commits Notes 2026-01-25 #22 2 Extension types, router improvements"},{"location":"upstream-sync/#upstream-monitoring","title":"Upstream Monitoring","text":"<p>Consider setting up notifications for upstream releases:</p> <ol> <li>Watch the beancount/fava repository</li> <li>Review the Fava changelog periodically</li> <li>Sync quarterly or when significant features are added</li> </ol>"},{"location":"usage/","title":"Getting Started","text":"<p>If you're new to Beancount-format files or double-entry accounting in general, we recommend Command-line Accounting in Context, a motivational document written by Martin Blais, the creator of the Beancount format.</p> <p>To learn how to create your ledger file, refer to Getting Started with Beancount guide. There is extensive documentation for the Beancount file format at the Beancount Documentation page.</p>"},{"location":"usage/#installation","title":"Installation","text":""},{"location":"usage/#option-1-desktop-app-recommended","title":"Option 1: Desktop App (Recommended)","text":"<p>Download the desktop app from GitHub Releases:</p> Platform Download macOS <code>rustfava_x.x.x_aarch64.dmg</code> Windows <code>rustfava_x.x.x_x64-setup.exe</code> Linux <code>rustfava_x.x.x_amd64.AppImage</code> <p>Double-click to launch, then open your <code>.beancount</code> file. No Python or other dependencies required.</p>"},{"location":"usage/#option-2-command-line-pypi","title":"Option 2: Command Line (PyPI)","text":"<p>rustfava runs on macOS, Linux, and Windows. You will need Python 3.13+ and uv.</p> <pre><code>uv tool install rustfava\n</code></pre> <p>Or to install into a virtual environment:</p> <pre><code>uv pip install rustfava\n</code></pre> <p>rustfava uses rustledger, a Rust-based parser compiled to WebAssembly, to parse your Beancount files. No separate Beancount installation is required.</p> <p>To export query results to Microsoft Excel or LibreOffice Calc:</p> <pre><code>uv tool install rustfava[excel]\n</code></pre>"},{"location":"usage/#option-3-docker","title":"Option 3: Docker","text":"<pre><code>docker run -p 5000:5000 -v /path/to/ledger:/data ghcr.io/rustledger/rustfava /data/main.beancount\n</code></pre> <p>See Docker deployment for advanced options.</p>"},{"location":"usage/#starting-rustfava","title":"Starting rustfava","text":""},{"location":"usage/#desktop-app","title":"Desktop App","text":"<ol> <li>Launch the app</li> <li>Click \"Open File\" or use File \u2192 Open</li> <li>Select your <code>.beancount</code> file</li> </ol>"},{"location":"usage/#command-line","title":"Command Line","text":"<pre><code>rustfava ledger.beancount\n</code></pre> <p>Then visit http://localhost:5000.</p> <p>Run <code>rustfava --help</code> for available options.</p>"},{"location":"usage/#using-rustfava","title":"Using rustfava","text":"<p>For more information on rustfava's features, refer to the help pages available through rustfava's web interface. rustfava comes with Gmail-style keyboard shortcuts; press <code>?</code> to show an overview.</p>"}]}
\ No newline at end of file
diff --git a/public/rustfava/docs/sitemap.xml b/public/rustfava/docs/sitemap.xml
index 4001337..576c65b 100644
--- a/public/rustfava/docs/sitemap.xml
+++ b/public/rustfava/docs/sitemap.xml
@@ -2,26 +2,30 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
     <url>
          <loc>https://rustledger.github.io/rustfava/docs/</loc>
-         <lastmod>2026-01-25</lastmod>
+         <lastmod>2026-01-26</lastmod>
     </url>
     <url>
          <loc>https://rustledger.github.io/rustfava/docs/api/</loc>
-         <lastmod>2026-01-25</lastmod>
+         <lastmod>2026-01-26</lastmod>
     </url>
     <url>
          <loc>https://rustledger.github.io/rustfava/docs/changelog/</loc>
-         <lastmod>2026-01-25</lastmod>
+         <lastmod>2026-01-26</lastmod>
     </url>
     <url>
          <loc>https://rustledger.github.io/rustfava/docs/deployment/</loc>
-         <lastmod>2026-01-25</lastmod>
+         <lastmod>2026-01-26</lastmod>
     </url>
     <url>
          <loc>https://rustledger.github.io/rustfava/docs/development/</loc>
-         <lastmod>2026-01-25</lastmod>
+         <lastmod>2026-01-26</lastmod>
+    </url>
+    <url>
+         <loc>https://rustledger.github.io/rustfava/docs/upstream-sync/</loc>
+         <lastmod>2026-01-26</lastmod>
     </url>
     <url>
          <loc>https://rustledger.github.io/rustfava/docs/usage/</loc>
-         <lastmod>2026-01-25</lastmod>
+         <lastmod>2026-01-26</lastmod>
     </url>
 </urlset>
\ No newline at end of file
diff --git a/public/rustfava/docs/sitemap.xml.gz b/public/rustfava/docs/sitemap.xml.gz
index 76c7579..6dda17a 100644
Binary files a/public/rustfava/docs/sitemap.xml.gz and b/public/rustfava/docs/sitemap.xml.gz differ
diff --git a/public/rustfava/docs/upstream-sync/index.html b/public/rustfava/docs/upstream-sync/index.html
new file mode 100644
index 0000000..7244b61
--- /dev/null
+++ b/public/rustfava/docs/upstream-sync/index.html
@@ -0,0 +1,819 @@
+
+<!doctype html>
+<html lang="en" class="no-js">
+  <head>
+    
+      <meta charset="utf-8">
+      <meta name="viewport" content="width=device-width,initial-scale=1">
+      
+        <meta name="description" content="Web interface for rustledger, a Rust-based Beancount parser">
+      
+      
+      
+        <link rel="canonical" href="https://rustledger.github.io/rustfava/docs/upstream-sync/">
+      
+      
+      
+      
+        
+      
+      
+      <link rel="icon" href="../assets/images/favicon.png">
+      <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.7.1">
+    
+    
+      
+        <title>Syncing with Upstream Fava - Rustfava</title>
+      
+    
+    
+      <link rel="stylesheet" href="../assets/stylesheets/main.484c7ddc.min.css">
+      
+        
+        <link rel="stylesheet" href="../assets/stylesheets/palette.ab4e12ef.min.css">
+      
+      
+
+
+    
+    
+      
+    
+    
+      
+        
+        
+        <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+        <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,300i,400,400i,700,700i%7CRoboto+Mono:400,400i,700,700i&display=fallback">
+        <style>:root{--md-text-font:"Roboto";--md-code-font:"Roboto Mono"}</style>
+      
+    
+    
+      <link rel="stylesheet" href="../assets/_mkdocstrings.css">
+    
+    <script>__md_scope=new URL("..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
+    
+      
+
+    
+    
+  </head>
+  
+  
+    
+    
+      
+    
+    
+    
+    
+    <body dir="ltr" data-md-color-scheme="default" data-md-color-primary="teal" data-md-color-accent="teal">
+  
+    
+    <input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
+    <input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
+    <label class="md-overlay" for="__drawer"></label>
+    <div data-md-component="skip">
+      
+        
+        <a href="#syncing-with-upstream-fava" class="md-skip">
+          Skip to content
+        </a>
+      
+    </div>
+    <div data-md-component="announce">
+      
+    </div>
+    
+    
+      
+
+  
+
+<header class="md-header md-header--shadow" data-md-component="header">
+  <nav class="md-header__inner md-grid" aria-label="Header">
+    <a href=".." title="Rustfava" class="md-header__button md-logo" aria-label="Rustfava" data-md-component="logo">
+      
+  <img src="../logo.svg" alt="logo">
+
+    </a>
+    <label class="md-header__button md-icon" for="__drawer">
+      
+      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg>
+    </label>
+    <div class="md-header__title" data-md-component="header-title">
+      <div class="md-header__ellipsis">
+        <div class="md-header__topic">
+          <span class="md-ellipsis">
+            Rustfava
+          </span>
+        </div>
+        <div class="md-header__topic" data-md-component="header-topic">
+          <span class="md-ellipsis">
+            
+              Syncing with Upstream Fava
+            
+          </span>
+        </div>
+      </div>
+    </div>
+    
+      
+        <form class="md-header__option" data-md-component="palette">
+  
+    
+    
+    
+    <input class="md-option" data-md-color-media="" data-md-color-scheme="default" data-md-color-primary="teal" data-md-color-accent="teal"  aria-label="Switch to dark mode"  type="radio" name="__palette" id="__palette_0">
+    
+      <label class="md-header__button md-icon" title="Switch to dark mode" for="__palette_1" hidden>
+        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg>
+      </label>
+    
+  
+    
+    
+    
+    <input class="md-option" data-md-color-media="" data-md-color-scheme="slate" data-md-color-primary="teal" data-md-color-accent="teal"  aria-label="Switch to light mode"  type="radio" name="__palette" id="__palette_1">
+    
+      <label class="md-header__button md-icon" title="Switch to light mode" for="__palette_0" hidden>
+        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg>
+      </label>
+    
+  
+</form>
+      
+    
+    
+      <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script>
+    
+    
+    
+      
+      
+        <label class="md-header__button md-icon" for="__search">
+          
+          <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
+        </label>
+        <div class="md-search" data-md-component="search" role="dialog">
+  <label class="md-search__overlay" for="__search"></label>
+  <div class="md-search__inner" role="search">
+    <form class="md-search__form" name="search">
+      <input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required>
+      <label class="md-search__icon md-icon" for="__search">
+        
+        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
+        
+        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg>
+      </label>
+      <nav class="md-search__options" aria-label="Search">
+        
+        <button type="reset" class="md-search__icon md-icon" title="Clear" aria-label="Clear" tabindex="-1">
+          
+          <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg>
+        </button>
+      </nav>
+      
+    </form>
+    <div class="md-search__output">
+      <div class="md-search__scrollwrap" tabindex="0" data-md-scrollfix>
+        <div class="md-search-result" data-md-component="search-result">
+          <div class="md-search-result__meta">
+            Initializing search
+          </div>
+          <ol class="md-search-result__list" role="presentation"></ol>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>
+      
+    
+    
+      <div class="md-header__source">
+        <a href="https://github.com/rustledger/rustfava" title="Go to repository" class="md-source" data-md-component="source">
+  <div class="md-source__icon md-icon">
+    
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M439.6 236.1 244 40.5c-5.4-5.5-12.8-8.5-20.4-8.5s-15 3-20.4 8.4L162.5 81l51.5 51.5c27.1-9.1 52.7 16.8 43.4 43.7l49.7 49.7c34.2-11.8 61.2 31 35.5 56.7-26.5 26.5-70.2-2.9-56-37.3L240.3 199v121.9c25.3 12.5 22.3 41.8 9.1 55-6.4 6.4-15.2 10.1-24.3 10.1s-17.8-3.6-24.3-10.1c-17.6-17.6-11.1-46.9 11.2-56v-123c-20.8-8.5-24.6-30.7-18.6-45L142.6 101 8.5 235.1C3 240.6 0 247.9 0 255.5s3 15 8.5 20.4l195.6 195.7c5.4 5.4 12.7 8.4 20.4 8.4s15-3 20.4-8.4l194.7-194.7c5.4-5.4 8.4-12.8 8.4-20.4s-3-15-8.4-20.4"/></svg>
+  </div>
+  <div class="md-source__repository">
+    rustledger/rustfava
+  </div>
+</a>
+      </div>
+    
+  </nav>
+  
+</header>
+    
+    <div class="md-container" data-md-component="container">
+      
+      
+        
+          
+        
+      
+      <main class="md-main" data-md-component="main">
+        <div class="md-main__inner md-grid">
+          
+            
+              
+              <div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
+                <div class="md-sidebar__scrollwrap">
+                  <div class="md-sidebar__inner">
+                    
+
+
+
+<nav class="md-nav md-nav--primary" aria-label="Navigation" data-md-level="0">
+  <label class="md-nav__title" for="__drawer">
+    <a href=".." title="Rustfava" class="md-nav__button md-logo" aria-label="Rustfava" data-md-component="logo">
+      
+  <img src="../logo.svg" alt="logo">
+
+    </a>
+    Rustfava
+  </label>
+  
+    <div class="md-nav__source">
+      <a href="https://github.com/rustledger/rustfava" title="Go to repository" class="md-source" data-md-component="source">
+  <div class="md-source__icon md-icon">
+    
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M439.6 236.1 244 40.5c-5.4-5.5-12.8-8.5-20.4-8.5s-15 3-20.4 8.4L162.5 81l51.5 51.5c27.1-9.1 52.7 16.8 43.4 43.7l49.7 49.7c34.2-11.8 61.2 31 35.5 56.7-26.5 26.5-70.2-2.9-56-37.3L240.3 199v121.9c25.3 12.5 22.3 41.8 9.1 55-6.4 6.4-15.2 10.1-24.3 10.1s-17.8-3.6-24.3-10.1c-17.6-17.6-11.1-46.9 11.2-56v-123c-20.8-8.5-24.6-30.7-18.6-45L142.6 101 8.5 235.1C3 240.6 0 247.9 0 255.5s3 15 8.5 20.4l195.6 195.7c5.4 5.4 12.7 8.4 20.4 8.4s15-3 20.4-8.4l194.7-194.7c5.4-5.4 8.4-12.8 8.4-20.4s-3-15-8.4-20.4"/></svg>
+  </div>
+  <div class="md-source__repository">
+    rustledger/rustfava
+  </div>
+</a>
+    </div>
+  
+  <ul class="md-nav__list" data-md-scrollfix>
+    
+      
+      
+  
+  
+  
+  
+    <li class="md-nav__item">
+      <a href=".." class="md-nav__link">
+        
+  
+  
+  <span class="md-ellipsis">
+    
+  
+    Home
+  
+
+    
+  </span>
+  
+  
+
+      </a>
+    </li>
+  
+
+    
+      
+      
+  
+  
+  
+  
+    <li class="md-nav__item">
+      <a href="../usage/" class="md-nav__link">
+        
+  
+  
+  <span class="md-ellipsis">
+    
+  
+    Getting Started
+  
+
+    
+  </span>
+  
+  
+
+      </a>
+    </li>
+  
+
+    
+      
+      
+  
+  
+  
+  
+    <li class="md-nav__item">
+      <a href="../changelog/" class="md-nav__link">
+        
+  
+  
+  <span class="md-ellipsis">
+    
+  
+    Changelog
+  
+
+    
+  </span>
+  
+  
+
+      </a>
+    </li>
+  
+
+    
+      
+      
+  
+  
+  
+  
+    <li class="md-nav__item">
+      <a href="../development/" class="md-nav__link">
+        
+  
+  
+  <span class="md-ellipsis">
+    
+  
+    Development
+  
+
+    
+  </span>
+  
+  
+
+      </a>
+    </li>
+  
+
+    
+      
+      
+  
+  
+  
+  
+    <li class="md-nav__item">
+      <a href="../deployment/" class="md-nav__link">
+        
+  
+  
+  <span class="md-ellipsis">
+    
+  
+    Deployment
+  
+
+    
+  </span>
+  
+  
+
+      </a>
+    </li>
+  
+
+    
+      
+      
+  
+  
+  
+  
+    <li class="md-nav__item">
+      <a href="../api/" class="md-nav__link">
+        
+  
+  
+  <span class="md-ellipsis">
+    
+  
+    API Reference
+  
+
+    
+  </span>
+  
+  
+
+      </a>
+    </li>
+  
+
+    
+  </ul>
+</nav>
+                  </div>
+                </div>
+              </div>
+            
+            
+              
+              <div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" >
+                <div class="md-sidebar__scrollwrap">
+                  <div class="md-sidebar__inner">
+                    
+
+<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
+  
+  
+  
+    
+  
+  
+    <label class="md-nav__title" for="__toc">
+      <span class="md-nav__icon md-icon"></span>
+      Table of contents
+    </label>
+    <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
+      
+        <li class="md-nav__item">
+  <a href="#background" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Background
+      
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#checking-for-upstream-changes" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Checking for Upstream Changes
+      
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#categorizing-commits" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Categorizing Commits
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Categorizing Commits">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#safe-to-cherry-pick" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Safe to cherry-pick
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#requires-review" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Requires review
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#cannot-cherry-pick" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Cannot cherry-pick
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#cherry-pick-workflow" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Cherry-Pick Workflow
+      
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#common-conflicts" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Common Conflicts
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Common Conflicts">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#package-lockjson" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        package-lock.json
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#file-renames-fava-rustfava" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        File renames (fava -&gt; rustfava)
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#deleted-core-files" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Deleted core files
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#after-syncing" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        After Syncing
+      
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#sync-history" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Sync History
+      
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#upstream-monitoring" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Upstream Monitoring
+      
+    </span>
+  </a>
+  
+</li>
+      
+    </ul>
+  
+</nav>
+                  </div>
+                </div>
+              </div>
+            
+          
+          
+            <div class="md-content" data-md-component="content">
+              
+              <article class="md-content__inner md-typeset">
+                
+                  
+
+
+  
+  
+
+
+<h1 id="syncing-with-upstream-fava">Syncing with Upstream Fava<a class="headerlink" href="#syncing-with-upstream-fava" title="Permanent link">&para;</a></h1>
+<p>rustfava is a fork of <a href="https://github.com/beancount/fava">Fava</a> that replaces the beancount parser with <a href="https://github.com/rustledger/rustledger">rustledger</a>. This document describes how to sync relevant changes from upstream.</p>
+<h2 id="background">Background<a class="headerlink" href="#background" title="Permanent link">&para;</a></h2>
+<p>The fork diverges significantly from upstream in the backend:</p>
+<table>
+<thead>
+<tr>
+<th>Component</th>
+<th>Fava</th>
+<th>rustfava</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Parser</td>
+<td>Python beancount</td>
+<td>rustledger (WASM)</td>
+</tr>
+<tr>
+<td>Core modules</td>
+<td><code>fava/core/</code>, <code>fava/beans/</code></td>
+<td><code>rustfava/rustledger/</code></td>
+</tr>
+<tr>
+<td>Package manager</td>
+<td>npm</td>
+<td>bun</td>
+</tr>
+</tbody>
+</table>
+<p>The frontend is largely unchanged and can usually accept upstream patches.</p>
+<h2 id="checking-for-upstream-changes">Checking for Upstream Changes<a class="headerlink" href="#checking-for-upstream-changes" title="Permanent link">&para;</a></h2>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="c1"># Fetch upstream</span>
+<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a>git<span class="w"> </span>fetch<span class="w"> </span>upstream
+<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a>
+<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a><span class="c1"># Find the common ancestor (fork point)</span>
+<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a>git<span class="w"> </span>merge-base<span class="w"> </span>main<span class="w"> </span>upstream/main
+<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a>
+<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a><span class="c1"># Count commits since fork</span>
+<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a>git<span class="w"> </span>rev-list<span class="w"> </span>--count<span class="w"> </span><span class="k">$(</span>git<span class="w"> </span>merge-base<span class="w"> </span>main<span class="w"> </span>upstream/main<span class="k">)</span>..upstream/main
+<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a>
+<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a><span class="c1"># List upstream commits since fork</span>
+<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a>git<span class="w"> </span>log<span class="w"> </span>--oneline<span class="w"> </span><span class="k">$(</span>git<span class="w"> </span>merge-base<span class="w"> </span>main<span class="w"> </span>upstream/main<span class="k">)</span>..upstream/main
+</code></pre></div>
+<h2 id="categorizing-commits">Categorizing Commits<a class="headerlink" href="#categorizing-commits" title="Permanent link">&para;</a></h2>
+<p>Review each upstream commit and categorize:</p>
+<h3 id="safe-to-cherry-pick">Safe to cherry-pick<a class="headerlink" href="#safe-to-cherry-pick" title="Permanent link">&para;</a></h3>
+<ul>
+<li><strong>Frontend changes</strong> (<code>frontend/src/</code>) - UI, routing, components</li>
+<li><strong>Documentation</strong> (<code>docs/</code>, <code>*.md</code>)</li>
+<li><strong>Templates</strong> (<code>src/fava/templates/</code>)</li>
+<li><strong>Static assets</strong> (<code>src/fava/static/</code>)</li>
+<li><strong>Extension API</strong> (if not touching core)</li>
+</ul>
+<h3 id="requires-review">Requires review<a class="headerlink" href="#requires-review" title="Permanent link">&para;</a></h3>
+<ul>
+<li><strong>Tests</strong> - may reference beancount-specific behavior</li>
+<li><strong>API endpoints</strong> - check if they depend on beancount types</li>
+</ul>
+<h3 id="cannot-cherry-pick">Cannot cherry-pick<a class="headerlink" href="#cannot-cherry-pick" title="Permanent link">&para;</a></h3>
+<ul>
+<li><strong>Core modules</strong> - <code>src/fava/core/</code>, <code>src/fava/beans/</code></li>
+<li><strong>Beancount imports</strong> - anything importing from <code>beancount.*</code></li>
+<li><strong>Inventory/position logic</strong> - replaced by rustledger</li>
+</ul>
+<h2 id="cherry-pick-workflow">Cherry-Pick Workflow<a class="headerlink" href="#cherry-pick-workflow" title="Permanent link">&para;</a></h2>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a><span class="c1"># 1. Create a sync branch</span>
+<a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a>git<span class="w"> </span>checkout<span class="w"> </span>main
+<a id="__codelineno-1-3" name="__codelineno-1-3" href="#__codelineno-1-3"></a>git<span class="w"> </span>pull<span class="w"> </span>origin<span class="w"> </span>main
+<a id="__codelineno-1-4" name="__codelineno-1-4" href="#__codelineno-1-4"></a>git<span class="w"> </span>checkout<span class="w"> </span>-b<span class="w"> </span>sync/upstream-YYYY-MM
+<a id="__codelineno-1-5" name="__codelineno-1-5" href="#__codelineno-1-5"></a>
+<a id="__codelineno-1-6" name="__codelineno-1-6" href="#__codelineno-1-6"></a><span class="c1"># 2. Cherry-pick safe commits (oldest first)</span>
+<a id="__codelineno-1-7" name="__codelineno-1-7" href="#__codelineno-1-7"></a>git<span class="w"> </span>cherry-pick<span class="w"> </span>&lt;commit-hash&gt;
+<a id="__codelineno-1-8" name="__codelineno-1-8" href="#__codelineno-1-8"></a>
+<a id="__codelineno-1-9" name="__codelineno-1-9" href="#__codelineno-1-9"></a><span class="c1"># 3. If conflicts occur, resolve them:</span>
+<a id="__codelineno-1-10" name="__codelineno-1-10" href="#__codelineno-1-10"></a><span class="c1">#    - For package-lock.json conflicts: git rm frontend/package-lock.json</span>
+<a id="__codelineno-1-11" name="__codelineno-1-11" href="#__codelineno-1-11"></a><span class="c1">#    - For renamed files (fava -&gt; rustfava): update paths</span>
+<a id="__codelineno-1-12" name="__codelineno-1-12" href="#__codelineno-1-12"></a><span class="c1">#    - For deleted files: skip the commit with git cherry-pick --skip</span>
+<a id="__codelineno-1-13" name="__codelineno-1-13" href="#__codelineno-1-13"></a>
+<a id="__codelineno-1-14" name="__codelineno-1-14" href="#__codelineno-1-14"></a><span class="c1"># 4. Update lockfile if package.json changed</span>
+<a id="__codelineno-1-15" name="__codelineno-1-15" href="#__codelineno-1-15"></a>nix<span class="w"> </span>develop<span class="w"> </span>--command<span class="w"> </span>bash<span class="w"> </span>-c<span class="w"> </span><span class="s2">&quot;cd frontend &amp;&amp; bun install&quot;</span>
+<a id="__codelineno-1-16" name="__codelineno-1-16" href="#__codelineno-1-16"></a>git<span class="w"> </span>add<span class="w"> </span>frontend/bun.lock
+<a id="__codelineno-1-17" name="__codelineno-1-17" href="#__codelineno-1-17"></a>git<span class="w"> </span>commit<span class="w"> </span>-m<span class="w"> </span><span class="s2">&quot;chore: update bun.lock for upstream sync&quot;</span>
+<a id="__codelineno-1-18" name="__codelineno-1-18" href="#__codelineno-1-18"></a>
+<a id="__codelineno-1-19" name="__codelineno-1-19" href="#__codelineno-1-19"></a><span class="c1"># 5. Test the build</span>
+<a id="__codelineno-1-20" name="__codelineno-1-20" href="#__codelineno-1-20"></a>nix<span class="w"> </span>develop<span class="w"> </span>--command<span class="w"> </span>bash<span class="w"> </span>-c<span class="w"> </span><span class="s2">&quot;cd frontend &amp;&amp; bun run build&quot;</span>
+<a id="__codelineno-1-21" name="__codelineno-1-21" href="#__codelineno-1-21"></a>nix<span class="w"> </span>develop<span class="w"> </span>--command<span class="w"> </span>bash<span class="w"> </span>-c<span class="w"> </span><span class="s2">&quot;just test&quot;</span>
+<a id="__codelineno-1-22" name="__codelineno-1-22" href="#__codelineno-1-22"></a>
+<a id="__codelineno-1-23" name="__codelineno-1-23" href="#__codelineno-1-23"></a><span class="c1"># 6. Push and create PR</span>
+<a id="__codelineno-1-24" name="__codelineno-1-24" href="#__codelineno-1-24"></a>git<span class="w"> </span>push<span class="w"> </span>-u<span class="w"> </span>origin<span class="w"> </span>sync/upstream-YYYY-MM
+<a id="__codelineno-1-25" name="__codelineno-1-25" href="#__codelineno-1-25"></a>gh<span class="w"> </span>pr<span class="w"> </span>create<span class="w"> </span>--title<span class="w"> </span><span class="s2">&quot;chore: sync upstream fava changes (Month YYYY)&quot;</span>
+</code></pre></div>
+<h2 id="common-conflicts">Common Conflicts<a class="headerlink" href="#common-conflicts" title="Permanent link">&para;</a></h2>
+<h3 id="package-lockjson">package-lock.json<a class="headerlink" href="#package-lockjson" title="Permanent link">&para;</a></h3>
+<p>rustfava uses bun instead of npm. Remove the conflicting file:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a>git<span class="w"> </span>rm<span class="w"> </span>frontend/package-lock.json
+<a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a>git<span class="w"> </span>cherry-pick<span class="w"> </span>--continue
+</code></pre></div>
+<h3 id="file-renames-fava-rustfava">File renames (fava -&gt; rustfava)<a class="headerlink" href="#file-renames-fava-rustfava" title="Permanent link">&para;</a></h3>
+<p>Upstream references <code>src/fava/</code> but rustfava uses <code>src/rustfava/</code>. The cherry-pick usually handles this via directory mapping, but manual fixes may be needed.</p>
+<h3 id="deleted-core-files">Deleted core files<a class="headerlink" href="#deleted-core-files" title="Permanent link">&para;</a></h3>
+<p>If upstream modifies files that rustfava deleted (like <code>core/inventory.py</code>), skip the commit:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a>git<span class="w"> </span>cherry-pick<span class="w"> </span>--skip
+</code></pre></div>
+<h2 id="after-syncing">After Syncing<a class="headerlink" href="#after-syncing" title="Permanent link">&para;</a></h2>
+<ol>
+<li><strong>Run the test suite</strong>: <code>just test</code></li>
+<li><strong>Build the frontend</strong>: <code>just frontend</code></li>
+<li><strong>Manual testing</strong>: Start the app and verify functionality</li>
+<li><strong>Update this doc</strong>: Note the last sync date and any new patterns</li>
+</ol>
+<h2 id="sync-history">Sync History<a class="headerlink" href="#sync-history" title="Permanent link">&para;</a></h2>
+<table>
+<thead>
+<tr>
+<th>Date</th>
+<th>PR</th>
+<th>Commits</th>
+<th>Notes</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>2026-01-25</td>
+<td>#22</td>
+<td>2</td>
+<td>Extension types, router improvements</td>
+</tr>
+</tbody>
+</table>
+<h2 id="upstream-monitoring">Upstream Monitoring<a class="headerlink" href="#upstream-monitoring" title="Permanent link">&para;</a></h2>
+<p>Consider setting up notifications for upstream releases:</p>
+<ol>
+<li>Watch the <a href="https://github.com/beancount/fava">beancount/fava</a> repository</li>
+<li>Review the <a href="https://github.com/beancount/fava/blob/main/CHANGELOG.md">Fava changelog</a> periodically</li>
+<li>Sync quarterly or when significant features are added</li>
+</ol>
+
+
+
+
+
+
+
+
+
+
+
+
+                
+              </article>
+            </div>
+          
+          
+<script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script>
+        </div>
+        
+      </main>
+      
+        <footer class="md-footer">
+  
+  <div class="md-footer-meta md-typeset">
+    <div class="md-footer-meta__inner md-grid">
+      <div class="md-copyright">
+  
+  
+    Made with
+    <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
+      Material for MkDocs
+    </a>
+  
+</div>
+      
+    </div>
+  </div>
+</footer>
+      
+    </div>
+    <div class="md-dialog" data-md-component="dialog">
+      <div class="md-dialog__inner md-typeset"></div>
+    </div>
+    
+    
+    
+      
+      
+      <script id="__config" type="application/json">{"annotate": null, "base": "..", "features": ["navigation.sections", "navigation.expand", "content.code.copy"], "search": "../assets/javascripts/workers/search.2c215733.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": null}</script>
+    
+    
+      <script src="../assets/javascripts/bundle.79ae519e.min.js"></script>
+      
+    
+  </body>
+</html>
\ No newline at end of file
diff --git a/public/rustfava/docs/usage/index.html b/public/rustfava/docs/usage/index.html
index 1cd0ec6..df929e1 100644
--- a/public/rustfava/docs/usage/index.html
+++ b/public/rustfava/docs/usage/index.html
@@ -355,13 +355,91 @@
     </span>
   </a>
   
+    <nav class="md-nav" aria-label="Installation">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#option-1-desktop-app-recommended" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Option 1: Desktop App (Recommended)
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#option-2-command-line-pypi" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Option 2: Command Line (PyPI)
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#option-3-docker" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Option 3: Docker
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
       
         <li class="md-nav__item">
   <a href="#starting-rustfava" class="md-nav__link">
     <span class="md-ellipsis">
       
-        Starting Rustfava
+        Starting rustfava
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Starting rustfava">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#desktop-app" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Desktop App
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#command-line" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Command Line
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#using-rustfava" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Using rustfava
       
     </span>
   </a>
@@ -519,13 +597,91 @@
     </span>
   </a>
   
+    <nav class="md-nav" aria-label="Installation">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#option-1-desktop-app-recommended" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Option 1: Desktop App (Recommended)
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#option-2-command-line-pypi" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Option 2: Command Line (PyPI)
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#option-3-docker" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Option 3: Docker
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
       
         <li class="md-nav__item">
   <a href="#starting-rustfava" class="md-nav__link">
     <span class="md-ellipsis">
       
-        Starting Rustfava
+        Starting rustfava
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Starting rustfava">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#desktop-app" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Desktop App
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#command-line" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Command Line
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#using-rustfava" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Using rustfava
       
     </span>
   </a>
@@ -563,30 +719,66 @@ <h1 id="getting-started">Getting Started<a class="headerlink" href="#getting-sta
 <a href="https://docs.google.com/document/d/1RaondTJCS_IUPBHFNdT8oqFKJjVJDsfsn6JEjBG04eA">Beancount Documentation</a>
 page.</p>
 <h2 id="installation">Installation<a class="headerlink" href="#installation" title="Permanent link">&para;</a></h2>
-<p>Rustfava runs on macOS, Linux, and Windows. You will need
-<a href="https://www.python.org/downloads/">Python 3</a> and
+<h3 id="option-1-desktop-app-recommended">Option 1: Desktop App (Recommended)<a class="headerlink" href="#option-1-desktop-app-recommended" title="Permanent link">&para;</a></h3>
+<p>Download the desktop app from <a href="https://github.com/rustledger/rustfava/releases">GitHub Releases</a>:</p>
+<table>
+<thead>
+<tr>
+<th>Platform</th>
+<th>Download</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><strong>macOS</strong></td>
+<td><code>rustfava_x.x.x_aarch64.dmg</code></td>
+</tr>
+<tr>
+<td><strong>Windows</strong></td>
+<td><code>rustfava_x.x.x_x64-setup.exe</code></td>
+</tr>
+<tr>
+<td><strong>Linux</strong></td>
+<td><code>rustfava_x.x.x_amd64.AppImage</code></td>
+</tr>
+</tbody>
+</table>
+<p>Double-click to launch, then open your <code>.beancount</code> file. No Python or other dependencies required.</p>
+<h3 id="option-2-command-line-pypi">Option 2: Command Line (PyPI)<a class="headerlink" href="#option-2-command-line-pypi" title="Permanent link">&para;</a></h3>
+<p>rustfava runs on macOS, Linux, and Windows. You will need
+<a href="https://www.python.org/downloads/">Python 3.13+</a> and
 <a href="https://docs.astral.sh/uv/">uv</a>.</p>
-<p>Then you can install rustfava or update your existing installation by running:</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>uv<span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span>--upgrade<span class="w"> </span>rustfava
+<div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>uv<span class="w"> </span>tool<span class="w"> </span>install<span class="w"> </span>rustfava
+</code></pre></div>
+<p>Or to install into a virtual environment:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>uv<span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span>rustfava
 </code></pre></div>
-<p>Rustfava uses <a href="https://github.com/rustledger/rustledger">rustledger</a>, a
+<p>rustfava uses <a href="https://github.com/rustledger/rustledger">rustledger</a>, a
 Rust-based parser compiled to WebAssembly, to parse your Beancount files. No
 separate Beancount installation is required.</p>
-<p>If you want to export query results to Microsoft Excel or LibreOffice Calc, use
-the following command to install the optional dependencies for this feature:</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>uv<span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span>--upgrade<span class="w"> </span>rustfava<span class="o">[</span>excel<span class="o">]</span>
+<p>To export query results to Microsoft Excel or LibreOffice Calc:</p>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a>uv<span class="w"> </span>tool<span class="w"> </span>install<span class="w"> </span>rustfava<span class="o">[</span>excel<span class="o">]</span>
+</code></pre></div>
+<h3 id="option-3-docker">Option 3: Docker<a class="headerlink" href="#option-3-docker" title="Permanent link">&para;</a></h3>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a>docker<span class="w"> </span>run<span class="w"> </span>-p<span class="w"> </span><span class="m">5000</span>:5000<span class="w"> </span>-v<span class="w"> </span>/path/to/ledger:/data<span class="w"> </span>ghcr.io/rustledger/rustfava<span class="w"> </span>/data/main.beancount
 </code></pre></div>
-<h2 id="starting-rustfava">Starting Rustfava<a class="headerlink" href="#starting-rustfava" title="Permanent link">&para;</a></h2>
-<p>After installing rustfava, you can start it by running:</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a>rustfava<span class="w"> </span>ledger.beancount
+<p>See <a href="../contrib/docker/README.md">Docker deployment</a> for advanced options.</p>
+<h2 id="starting-rustfava">Starting rustfava<a class="headerlink" href="#starting-rustfava" title="Permanent link">&para;</a></h2>
+<h3 id="desktop-app">Desktop App<a class="headerlink" href="#desktop-app" title="Permanent link">&para;</a></h3>
+<ol>
+<li>Launch the app</li>
+<li>Click "Open File" or use File → Open</li>
+<li>Select your <code>.beancount</code> file</li>
+</ol>
+<h3 id="command-line">Command Line<a class="headerlink" href="#command-line" title="Permanent link">&para;</a></h3>
+<div class="highlight"><pre><span></span><code><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a>rustfava<span class="w"> </span>ledger.beancount
 </code></pre></div>
-<p>pointing it to your Beancount file -- and visit the web interface at
-<a href="http://localhost:5000">http://localhost:5000</a>.</p>
-<p>There are some command-line options available, run <code>rustfava --help</code> for an
-overview.</p>
-<p>For more information on rustfava's features, refer to the help pages that are
-available through rustfava's web-interface. Rustfava comes with Gmail-style
-keyboard shortcuts; press <code>?</code> to show an overview.</p>
+<p>Then visit <a href="http://localhost:5000">http://localhost:5000</a>.</p>
+<p>Run <code>rustfava --help</code> for available options.</p>
+<h2 id="using-rustfava">Using rustfava<a class="headerlink" href="#using-rustfava" title="Permanent link">&para;</a></h2>
+<p>For more information on rustfava's features, refer to the help pages available
+through rustfava's web interface. rustfava comes with Gmail-style keyboard
+shortcuts; press <code>?</code> to show an overview.</p>