Update docs

2026-07-15 04:54:56 +00:00 · 2026-07-13 10:15:57 -04:00
parent 9a5f2d90da
commit 759ea2b815
33 changed files with 546 additions and 561 deletions
@@ -5,16 +5,16 @@
 <head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Overview: module code &mdash; parsedmarc 10.2.0 documentation</title>
+  <title>Overview: module code &mdash; parsedmarc 10.2.2 documentation</title>
      <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
-      <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=e59714d7" />
+      <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=9edc463e" />

  
      <script src="../_static/jquery.js?v=5d32c60e"></script>
      <script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-      <script src="../_static/documentation_options.js?v=d0f31c56"></script>
-      <script src="../_static/doctools.js?v=9bcbadda"></script>
-      <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
+      <script src="../_static/documentation_options.js?v=43731225"></script>
+      <script src="../_static/doctools.js?v=fd6eb6e6"></script>
+      <script src="../_static/sphinx_highlight.js?v=6ffebe34"></script>
    <script src="../_static/js/theme.js"></script>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" /> 
@@ -5,16 +5,16 @@
 <head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>parsedmarc &mdash; parsedmarc 10.2.0 documentation</title>
+  <title>parsedmarc &mdash; parsedmarc 10.2.2 documentation</title>
      <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
-      <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=e59714d7" />
+      <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=9edc463e" />

  
      <script src="../_static/jquery.js?v=5d32c60e"></script>
      <script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-      <script src="../_static/documentation_options.js?v=d0f31c56"></script>
-      <script src="../_static/doctools.js?v=9bcbadda"></script>
-      <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
+      <script src="../_static/documentation_options.js?v=43731225"></script>
+      <script src="../_static/doctools.js?v=fd6eb6e6"></script>
+      <script src="../_static/sphinx_highlight.js?v=6ffebe34"></script>
    <script src="../_static/js/theme.js"></script>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" /> 
@@ -864,7 +864,7 @@
 <div class="viewcode-block" id="parse_aggregate_report_xml">
 <a class="viewcode-back" href="../api.html#parsedmarc.parse_aggregate_report_xml">[docs]</a>
 <span class="k">def</span><span class="w"> </span><span class="nf">parse_aggregate_report_xml</span><span class="p">(</span>
-    <span class="n">xml</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
+    <span class="n">xml</span><span class="p">:</span> <span class="nb">str</span> <span class="o">|</span> <span class="nb">bytes</span><span class="p">,</span>
    <span class="o">*</span><span class="p">,</span>
    <span class="n">ip_db_path</span><span class="p">:</span> <span class="nb">str</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
    <span class="n">always_use_local_files</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
@@ -880,7 +880,8 @@
 <span class="w">    </span><span class="sd">&quot;&quot;&quot;Parses a DMARC XML report string and returns a consistent dict</span>

 <span class="sd">    Args:</span>
-<span class="sd">        xml (str): A string of DMARC aggregate report XML</span>
+<span class="sd">        xml (str | bytes): DMARC aggregate report XML (bytes are decoded</span>
+<span class="sd">            with errors ignored)</span>
 <span class="sd">        ip_db_path (str): Path to a MMDB file from IPinfo, MaxMind, or DBIP</span>
 <span class="sd">        always_use_local_files (bool): Do not download files</span>
 <span class="sd">        reverse_dns_map_path (str): Path to a reverse DNS map file</span>
@@ -1223,9 +1224,6 @@
                <span class="n">remainder</span> <span class="o">=</span> <span class="n">stream</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>
                <span class="n">file_object</span> <span class="o">=</span> <span class="n">BytesIO</span><span class="p">(</span><span class="n">header</span> <span class="o">+</span> <span class="nb">bytes</span><span class="p">(</span><span class="n">remainder</span><span class="p">))</span>

-        <span class="k">if</span> <span class="n">file_object</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
-            <span class="k">raise</span> <span class="n">ParserError</span><span class="p">(</span><span class="s2">&quot;Invalid report content&quot;</span><span class="p">)</span>
-
        <span class="k">if</span> <span class="n">header</span><span class="p">[:</span> <span class="nb">len</span><span class="p">(</span><span class="n">MAGIC_ZIP</span><span class="p">)]</span> <span class="o">==</span> <span class="n">MAGIC_ZIP</span><span class="p">:</span>
            <span class="n">_zip</span> <span class="o">=</span> <span class="n">zipfile</span><span class="o">.</span><span class="n">ZipFile</span><span class="p">(</span><span class="n">file_object</span><span class="p">)</span>
            <span class="n">report</span> <span class="o">=</span> <span class="n">_zip</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="n">_zip</span><span class="o">.</span><span class="n">namelist</span><span class="p">()[</span><span class="mi">0</span><span class="p">])</span><span class="o">.</span><span class="n">read</span><span class="p">()</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="n">errors</span><span class="o">=</span><span class="s2">&quot;ignore&quot;</span><span class="p">)</span>
@@ -5,16 +5,16 @@
 <head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>parsedmarc.elastic &mdash; parsedmarc 10.2.0 documentation</title>
+  <title>parsedmarc.elastic &mdash; parsedmarc 10.2.2 documentation</title>
      <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=b86133f3" />
-      <link rel="stylesheet" type="text/css" href="../../_static/css/theme.css?v=e59714d7" />
+      <link rel="stylesheet" type="text/css" href="../../_static/css/theme.css?v=9edc463e" />

  
      <script src="../../_static/jquery.js?v=5d32c60e"></script>
      <script src="../../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-      <script src="../../_static/documentation_options.js?v=d0f31c56"></script>
-      <script src="../../_static/doctools.js?v=9bcbadda"></script>
-      <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
+      <script src="../../_static/documentation_options.js?v=43731225"></script>
+      <script src="../../_static/doctools.js?v=fd6eb6e6"></script>
+      <script src="../../_static/sphinx_highlight.js?v=6ffebe34"></script>
    <script src="../../_static/js/theme.js"></script>
    <link rel="index" title="Index" href="../../genindex.html" />
    <link rel="search" title="Search" href="../../search.html" /> 
@@ -375,27 +375,6 @@
    <span class="n">report_id</span> <span class="o">=</span> <span class="n">Text</span><span class="p">()</span>
    <span class="n">policies</span> <span class="o">=</span> <span class="n">Nested</span><span class="p">(</span><span class="n">_SMTPTLSPolicyDoc</span><span class="p">)</span>

-    <span class="k">def</span><span class="w"> </span><span class="nf">add_policy</span><span class="p">(</span>
-        <span class="bp">self</span><span class="p">,</span>
-        <span class="n">policy_type</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
-        <span class="n">policy_domain</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
-        <span class="n">successful_session_count</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span>
-        <span class="n">failed_session_count</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span>
-        <span class="o">*</span><span class="p">,</span>
-        <span class="n">policy_string</span><span class="p">:</span> <span class="nb">str</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
-        <span class="n">mx_host_patterns</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
-        <span class="n">failure_details</span><span class="p">:</span> <span class="nb">str</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
-    <span class="p">):</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">policies</span><span class="o">.</span><span class="n">append</span><span class="p">(</span>
-            <span class="n">policy_type</span><span class="o">=</span><span class="n">policy_type</span><span class="p">,</span>
-            <span class="n">policy_domain</span><span class="o">=</span><span class="n">policy_domain</span><span class="p">,</span>
-            <span class="n">successful_session_count</span><span class="o">=</span><span class="n">successful_session_count</span><span class="p">,</span>
-            <span class="n">failed_session_count</span><span class="o">=</span><span class="n">failed_session_count</span><span class="p">,</span>
-            <span class="n">policy_string</span><span class="o">=</span><span class="n">policy_string</span><span class="p">,</span>
-            <span class="n">mx_host_patterns</span><span class="o">=</span><span class="n">mx_host_patterns</span><span class="p">,</span>
-            <span class="n">failure_details</span><span class="o">=</span><span class="n">failure_details</span><span class="p">,</span>
-        <span class="p">)</span>  <span class="c1"># pyright: ignore[reportCallIssue]</span>
-

 <div class="viewcode-block" id="AlreadySaved">
 <a class="viewcode-back" href="../../api.html#parsedmarc.elastic.AlreadySaved">[docs]</a>
@@ -505,12 +484,12 @@
 <span class="sd">    Args:</span>
 <span class="sd">        aggregate_indexes (list): A list of aggregate index names</span>
 <span class="sd">        failure_indexes (list): A list of failure index names</span>
+<span class="sd">            (accepted for API compatibility; no migrations are</span>
+<span class="sd">            currently needed for failure indexes)</span>
 <span class="sd">    &quot;&quot;&quot;</span>
    <span class="n">version</span> <span class="o">=</span> <span class="mi">2</span>
    <span class="k">if</span> <span class="n">aggregate_indexes</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
        <span class="n">aggregate_indexes</span> <span class="o">=</span> <span class="p">[]</span>
-    <span class="k">if</span> <span class="n">failure_indexes</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
-        <span class="n">failure_indexes</span> <span class="o">=</span> <span class="p">[]</span>
    <span class="k">for</span> <span class="n">aggregate_index_name</span> <span class="ow">in</span> <span class="n">aggregate_indexes</span><span class="p">:</span>
        <span class="k">if</span> <span class="ow">not</span> <span class="n">Index</span><span class="p">(</span><span class="n">aggregate_index_name</span><span class="p">)</span><span class="o">.</span><span class="n">exists</span><span class="p">():</span>
            <span class="k">continue</span>
@@ -538,10 +517,7 @@
            <span class="n">Index</span><span class="p">(</span><span class="n">new_index_name</span><span class="p">)</span><span class="o">.</span><span class="n">create</span><span class="p">()</span>
            <span class="n">Index</span><span class="p">(</span><span class="n">new_index_name</span><span class="p">)</span><span class="o">.</span><span class="n">put_mapping</span><span class="p">(</span><span class="n">doc_type</span><span class="o">=</span><span class="n">doc</span><span class="p">,</span> <span class="n">body</span><span class="o">=</span><span class="n">body</span><span class="p">)</span>
            <span class="n">reindex</span><span class="p">(</span><span class="n">connections</span><span class="o">.</span><span class="n">get_connection</span><span class="p">(),</span> <span class="n">aggregate_index_name</span><span class="p">,</span> <span class="n">new_index_name</span><span class="p">)</span>  <span class="c1"># pyright: ignore[reportArgumentType]</span>
-            <span class="n">Index</span><span class="p">(</span><span class="n">aggregate_index_name</span><span class="p">)</span><span class="o">.</span><span class="n">delete</span><span class="p">()</span>
-
-    <span class="k">for</span> <span class="n">failure_index</span> <span class="ow">in</span> <span class="n">failure_indexes</span><span class="p">:</span>
-        <span class="k">pass</span></div>
+            <span class="n">Index</span><span class="p">(</span><span class="n">aggregate_index_name</span><span class="p">)</span><span class="o">.</span><span class="n">delete</span><span class="p">()</span></div>



@@ -633,8 +609,12 @@
    <span class="p">)</span>

    <span class="k">for</span> <span class="n">record</span> <span class="ow">in</span> <span class="n">aggregate_report</span><span class="p">[</span><span class="s2">&quot;records&quot;</span><span class="p">]:</span>
-        <span class="n">begin_date</span> <span class="o">=</span> <span class="n">human_timestamp_to_datetime</span><span class="p">(</span><span class="n">record</span><span class="p">[</span><span class="s2">&quot;interval_begin&quot;</span><span class="p">],</span> <span class="n">to_utc</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
-        <span class="n">end_date</span> <span class="o">=</span> <span class="n">human_timestamp_to_datetime</span><span class="p">(</span><span class="n">record</span><span class="p">[</span><span class="s2">&quot;interval_end&quot;</span><span class="p">],</span> <span class="n">to_utc</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
+        <span class="n">begin_date</span> <span class="o">=</span> <span class="n">human_timestamp_to_datetime</span><span class="p">(</span>
+            <span class="n">record</span><span class="p">[</span><span class="s2">&quot;interval_begin&quot;</span><span class="p">],</span> <span class="n">to_utc</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">assume_utc</span><span class="o">=</span><span class="kc">True</span>
+        <span class="p">)</span>
+        <span class="n">end_date</span> <span class="o">=</span> <span class="n">human_timestamp_to_datetime</span><span class="p">(</span>
+            <span class="n">record</span><span class="p">[</span><span class="s2">&quot;interval_end&quot;</span><span class="p">],</span> <span class="n">to_utc</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">assume_utc</span><span class="o">=</span><span class="kc">True</span>
+        <span class="p">)</span>
        <span class="n">normalized_timespan</span> <span class="o">=</span> <span class="n">record</span><span class="p">[</span><span class="s2">&quot;normalized_timespan&quot;</span><span class="p">]</span>

        <span class="k">if</span> <span class="n">monthly_indexes</span><span class="p">:</span>
@@ -762,7 +742,12 @@
    <span class="k">for</span> <span class="n">original_header</span> <span class="ow">in</span> <span class="n">original_headers</span><span class="p">:</span>
        <span class="n">headers</span><span class="p">[</span><span class="n">original_header</span><span class="o">.</span><span class="n">lower</span><span class="p">()]</span> <span class="o">=</span> <span class="n">original_headers</span><span class="p">[</span><span class="n">original_header</span><span class="p">]</span>

-    <span class="n">arrival_date</span> <span class="o">=</span> <span class="n">human_timestamp_to_datetime</span><span class="p">(</span><span class="n">failure_report</span><span class="p">[</span><span class="s2">&quot;arrival_date_utc&quot;</span><span class="p">])</span>
+    <span class="c1"># arrival_date_utc is a UTC wall-clock string; without assume_utc the</span>
+    <span class="c1"># naive .timestamp() below would interpret it as local time and skew</span>
+    <span class="c1"># the epoch by the host&#39;s UTC offset.</span>
+    <span class="n">arrival_date</span> <span class="o">=</span> <span class="n">human_timestamp_to_datetime</span><span class="p">(</span>
+        <span class="n">failure_report</span><span class="p">[</span><span class="s2">&quot;arrival_date_utc&quot;</span><span class="p">],</span> <span class="n">assume_utc</span><span class="o">=</span><span class="kc">True</span>
+    <span class="p">)</span>
    <span class="n">arrival_date_epoch_milliseconds</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="n">arrival_date</span><span class="o">.</span><span class="n">timestamp</span><span class="p">()</span> <span class="o">*</span> <span class="mi">1000</span><span class="p">)</span>

    <span class="k">if</span> <span class="n">index_suffix</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
@@ -5,16 +5,16 @@
 <head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>parsedmarc.opensearch &mdash; parsedmarc 10.2.0 documentation</title>
+  <title>parsedmarc.opensearch &mdash; parsedmarc 10.2.2 documentation</title>
      <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=b86133f3" />
-      <link rel="stylesheet" type="text/css" href="../../_static/css/theme.css?v=e59714d7" />
+      <link rel="stylesheet" type="text/css" href="../../_static/css/theme.css?v=9edc463e" />

  
      <script src="../../_static/jquery.js?v=5d32c60e"></script>
      <script src="../../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-      <script src="../../_static/documentation_options.js?v=d0f31c56"></script>
-      <script src="../../_static/doctools.js?v=9bcbadda"></script>
-      <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
+      <script src="../../_static/documentation_options.js?v=43731225"></script>
+      <script src="../../_static/doctools.js?v=fd6eb6e6"></script>
+      <script src="../../_static/sphinx_highlight.js?v=6ffebe34"></script>
    <script src="../../_static/js/theme.js"></script>
    <link rel="index" title="Index" href="../../genindex.html" />
    <link rel="search" title="Search" href="../../search.html" /> 
@@ -366,27 +366,6 @@
    <span class="n">report_id</span> <span class="o">=</span> <span class="n">Text</span><span class="p">()</span>
    <span class="n">policies</span> <span class="o">=</span> <span class="n">Nested</span><span class="p">(</span><span class="n">_SMTPTLSPolicyDoc</span><span class="p">)</span>

-    <span class="k">def</span><span class="w"> </span><span class="nf">add_policy</span><span class="p">(</span>
-        <span class="bp">self</span><span class="p">,</span>
-        <span class="n">policy_type</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
-        <span class="n">policy_domain</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
-        <span class="n">successful_session_count</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span>
-        <span class="n">failed_session_count</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span>
-        <span class="o">*</span><span class="p">,</span>
-        <span class="n">policy_string</span><span class="p">:</span> <span class="nb">str</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
-        <span class="n">mx_host_patterns</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
-        <span class="n">failure_details</span><span class="p">:</span> <span class="nb">str</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
-    <span class="p">):</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">policies</span><span class="o">.</span><span class="n">append</span><span class="p">(</span>
-            <span class="n">policy_type</span><span class="o">=</span><span class="n">policy_type</span><span class="p">,</span>
-            <span class="n">policy_domain</span><span class="o">=</span><span class="n">policy_domain</span><span class="p">,</span>
-            <span class="n">successful_session_count</span><span class="o">=</span><span class="n">successful_session_count</span><span class="p">,</span>
-            <span class="n">failed_session_count</span><span class="o">=</span><span class="n">failed_session_count</span><span class="p">,</span>
-            <span class="n">policy_string</span><span class="o">=</span><span class="n">policy_string</span><span class="p">,</span>
-            <span class="n">mx_host_patterns</span><span class="o">=</span><span class="n">mx_host_patterns</span><span class="p">,</span>
-            <span class="n">failure_details</span><span class="o">=</span><span class="n">failure_details</span><span class="p">,</span>
-        <span class="p">)</span>
-

 <div class="viewcode-block" id="AlreadySaved">
 <a class="viewcode-back" href="../../api.html#parsedmarc.opensearch.AlreadySaved">[docs]</a>
@@ -505,12 +484,12 @@
 <span class="sd">    Args:</span>
 <span class="sd">        aggregate_indexes (list): A list of aggregate index names</span>
 <span class="sd">        failure_indexes (list): A list of failure index names</span>
+<span class="sd">            (accepted for API compatibility; no migrations are</span>
+<span class="sd">            currently needed for failure indexes)</span>
 <span class="sd">    &quot;&quot;&quot;</span>
    <span class="n">version</span> <span class="o">=</span> <span class="mi">2</span>
    <span class="k">if</span> <span class="n">aggregate_indexes</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
        <span class="n">aggregate_indexes</span> <span class="o">=</span> <span class="p">[]</span>
-    <span class="k">if</span> <span class="n">failure_indexes</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
-        <span class="n">failure_indexes</span> <span class="o">=</span> <span class="p">[]</span>
    <span class="k">for</span> <span class="n">aggregate_index_name</span> <span class="ow">in</span> <span class="n">aggregate_indexes</span><span class="p">:</span>
        <span class="k">if</span> <span class="ow">not</span> <span class="n">Index</span><span class="p">(</span><span class="n">aggregate_index_name</span><span class="p">)</span><span class="o">.</span><span class="n">exists</span><span class="p">():</span>
            <span class="k">continue</span>
@@ -538,10 +517,7 @@
            <span class="n">Index</span><span class="p">(</span><span class="n">new_index_name</span><span class="p">)</span><span class="o">.</span><span class="n">create</span><span class="p">()</span>
            <span class="n">Index</span><span class="p">(</span><span class="n">new_index_name</span><span class="p">)</span><span class="o">.</span><span class="n">put_mapping</span><span class="p">(</span><span class="n">doc_type</span><span class="o">=</span><span class="n">doc</span><span class="p">,</span> <span class="n">body</span><span class="o">=</span><span class="n">body</span><span class="p">)</span>
            <span class="n">reindex</span><span class="p">(</span><span class="n">connections</span><span class="o">.</span><span class="n">get_connection</span><span class="p">(),</span> <span class="n">aggregate_index_name</span><span class="p">,</span> <span class="n">new_index_name</span><span class="p">)</span>
-            <span class="n">Index</span><span class="p">(</span><span class="n">aggregate_index_name</span><span class="p">)</span><span class="o">.</span><span class="n">delete</span><span class="p">()</span>
-
-    <span class="k">for</span> <span class="n">failure_index</span> <span class="ow">in</span> <span class="n">failure_indexes</span><span class="p">:</span>
-        <span class="k">pass</span></div>
+            <span class="n">Index</span><span class="p">(</span><span class="n">aggregate_index_name</span><span class="p">)</span><span class="o">.</span><span class="n">delete</span><span class="p">()</span></div>



@@ -633,8 +609,12 @@
    <span class="p">)</span>

    <span class="k">for</span> <span class="n">record</span> <span class="ow">in</span> <span class="n">aggregate_report</span><span class="p">[</span><span class="s2">&quot;records&quot;</span><span class="p">]:</span>
-        <span class="n">begin_date</span> <span class="o">=</span> <span class="n">human_timestamp_to_datetime</span><span class="p">(</span><span class="n">record</span><span class="p">[</span><span class="s2">&quot;interval_begin&quot;</span><span class="p">],</span> <span class="n">to_utc</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
-        <span class="n">end_date</span> <span class="o">=</span> <span class="n">human_timestamp_to_datetime</span><span class="p">(</span><span class="n">record</span><span class="p">[</span><span class="s2">&quot;interval_end&quot;</span><span class="p">],</span> <span class="n">to_utc</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
+        <span class="n">begin_date</span> <span class="o">=</span> <span class="n">human_timestamp_to_datetime</span><span class="p">(</span>
+            <span class="n">record</span><span class="p">[</span><span class="s2">&quot;interval_begin&quot;</span><span class="p">],</span> <span class="n">to_utc</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">assume_utc</span><span class="o">=</span><span class="kc">True</span>
+        <span class="p">)</span>
+        <span class="n">end_date</span> <span class="o">=</span> <span class="n">human_timestamp_to_datetime</span><span class="p">(</span>
+            <span class="n">record</span><span class="p">[</span><span class="s2">&quot;interval_end&quot;</span><span class="p">],</span> <span class="n">to_utc</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">assume_utc</span><span class="o">=</span><span class="kc">True</span>
+        <span class="p">)</span>
        <span class="n">normalized_timespan</span> <span class="o">=</span> <span class="n">record</span><span class="p">[</span><span class="s2">&quot;normalized_timespan&quot;</span><span class="p">]</span>

        <span class="k">if</span> <span class="n">monthly_indexes</span><span class="p">:</span>
@@ -762,7 +742,12 @@
    <span class="k">for</span> <span class="n">original_header</span> <span class="ow">in</span> <span class="n">original_headers</span><span class="p">:</span>
        <span class="n">headers</span><span class="p">[</span><span class="n">original_header</span><span class="o">.</span><span class="n">lower</span><span class="p">()]</span> <span class="o">=</span> <span class="n">original_headers</span><span class="p">[</span><span class="n">original_header</span><span class="p">]</span>

-    <span class="n">arrival_date</span> <span class="o">=</span> <span class="n">human_timestamp_to_datetime</span><span class="p">(</span><span class="n">failure_report</span><span class="p">[</span><span class="s2">&quot;arrival_date_utc&quot;</span><span class="p">])</span>
+    <span class="c1"># arrival_date_utc is a UTC wall-clock string; without assume_utc the</span>
+    <span class="c1"># naive .timestamp() below would interpret it as local time and skew</span>
+    <span class="c1"># the epoch by the host&#39;s UTC offset.</span>
+    <span class="n">arrival_date</span> <span class="o">=</span> <span class="n">human_timestamp_to_datetime</span><span class="p">(</span>
+        <span class="n">failure_report</span><span class="p">[</span><span class="s2">&quot;arrival_date_utc&quot;</span><span class="p">],</span> <span class="n">assume_utc</span><span class="o">=</span><span class="kc">True</span>
+    <span class="p">)</span>
    <span class="n">arrival_date_epoch_milliseconds</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="n">arrival_date</span><span class="o">.</span><span class="n">timestamp</span><span class="p">()</span> <span class="o">*</span> <span class="mi">1000</span><span class="p">)</span>

    <span class="k">if</span> <span class="n">index_suffix</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
@@ -5,16 +5,16 @@
 <head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>parsedmarc.splunk &mdash; parsedmarc 10.2.0 documentation</title>
+  <title>parsedmarc.splunk &mdash; parsedmarc 10.2.2 documentation</title>
      <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=b86133f3" />
-      <link rel="stylesheet" type="text/css" href="../../_static/css/theme.css?v=e59714d7" />
+      <link rel="stylesheet" type="text/css" href="../../_static/css/theme.css?v=9edc463e" />

  
      <script src="../../_static/jquery.js?v=5d32c60e"></script>
      <script src="../../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-      <script src="../../_static/documentation_options.js?v=d0f31c56"></script>
-      <script src="../../_static/doctools.js?v=9bcbadda"></script>
-      <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
+      <script src="../../_static/documentation_options.js?v=43731225"></script>
+      <script src="../../_static/doctools.js?v=fd6eb6e6"></script>
+      <script src="../../_static/sphinx_highlight.js?v=6ffebe34"></script>
    <script src="../../_static/js/theme.js"></script>
    <link rel="index" title="Index" href="../../genindex.html" />
    <link rel="search" title="Search" href="../../search.html" /> 
@@ -211,8 +211,10 @@
                    <span class="n">new_report</span><span class="p">[</span><span class="s2">&quot;spf_results&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">record</span><span class="p">[</span><span class="s2">&quot;auth_results&quot;</span><span class="p">][</span><span class="s2">&quot;spf&quot;</span><span class="p">]</span>

                <span class="n">data</span><span class="p">[</span><span class="s2">&quot;sourcetype&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&quot;dmarc:aggregate&quot;</span>
+                <span class="c1"># interval_begin is a UTC wall-clock string; assume_utc keeps</span>
+                <span class="c1"># it from being re-interpreted as local time on non-UTC hosts.</span>
                <span class="n">timestamp</span> <span class="o">=</span> <span class="n">human_timestamp_to_unix_timestamp</span><span class="p">(</span>
-                    <span class="n">new_report</span><span class="p">[</span><span class="s2">&quot;interval_begin&quot;</span><span class="p">]</span>
+                    <span class="n">new_report</span><span class="p">[</span><span class="s2">&quot;interval_begin&quot;</span><span class="p">],</span> <span class="n">assume_utc</span><span class="o">=</span><span class="kc">True</span>
                <span class="p">)</span>
                <span class="n">data</span><span class="p">[</span><span class="s2">&quot;time&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">timestamp</span>
                <span class="n">data</span><span class="p">[</span><span class="s2">&quot;event&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">new_report</span><span class="o">.</span><span class="n">copy</span><span class="p">()</span>
@@ -255,7 +257,11 @@
        <span class="k">for</span> <span class="n">report</span> <span class="ow">in</span> <span class="n">failure_reports</span><span class="p">:</span>
            <span class="n">data</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_common_data</span><span class="o">.</span><span class="n">copy</span><span class="p">()</span>
            <span class="n">data</span><span class="p">[</span><span class="s2">&quot;sourcetype&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&quot;dmarc:failure&quot;</span>
-            <span class="n">timestamp</span> <span class="o">=</span> <span class="n">human_timestamp_to_unix_timestamp</span><span class="p">(</span><span class="n">report</span><span class="p">[</span><span class="s2">&quot;arrival_date_utc&quot;</span><span class="p">])</span>
+            <span class="c1"># arrival_date_utc is a UTC wall-clock string; assume_utc keeps</span>
+            <span class="c1"># it from being re-interpreted as local time on non-UTC hosts.</span>
+            <span class="n">timestamp</span> <span class="o">=</span> <span class="n">human_timestamp_to_unix_timestamp</span><span class="p">(</span>
+                <span class="n">report</span><span class="p">[</span><span class="s2">&quot;arrival_date_utc&quot;</span><span class="p">],</span> <span class="n">assume_utc</span><span class="o">=</span><span class="kc">True</span>
+            <span class="p">)</span>
            <span class="n">data</span><span class="p">[</span><span class="s2">&quot;time&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">timestamp</span>
            <span class="n">data</span><span class="p">[</span><span class="s2">&quot;event&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">report</span><span class="o">.</span><span class="n">copy</span><span class="p">()</span>
            <span class="n">json_str</span> <span class="o">+=</span> <span class="s2">&quot;</span><span class="si">{0}</span><span class="se">\n</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">json</span><span class="o">.</span><span class="n">dumps</span><span class="p">(</span><span class="n">data</span><span class="p">))</span>
@@ -5,16 +5,16 @@
 <head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>parsedmarc.types &mdash; parsedmarc 10.2.0 documentation</title>
+  <title>parsedmarc.types &mdash; parsedmarc 10.2.2 documentation</title>
      <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=b86133f3" />
-      <link rel="stylesheet" type="text/css" href="../../_static/css/theme.css?v=e59714d7" />
+      <link rel="stylesheet" type="text/css" href="../../_static/css/theme.css?v=9edc463e" />

  
      <script src="../../_static/jquery.js?v=5d32c60e"></script>
      <script src="../../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-      <script src="../../_static/documentation_options.js?v=d0f31c56"></script>
-      <script src="../../_static/doctools.js?v=9bcbadda"></script>
-      <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
+      <script src="../../_static/documentation_options.js?v=43731225"></script>
+      <script src="../../_static/doctools.js?v=fd6eb6e6"></script>
+      <script src="../../_static/sphinx_highlight.js?v=6ffebe34"></script>
    <script src="../../_static/js/theme.js"></script>
    <link rel="index" title="Index" href="../../genindex.html" />
    <link rel="search" title="Search" href="../../search.html" /> 
@@ -5,16 +5,16 @@
 <head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>parsedmarc.utils &mdash; parsedmarc 10.2.0 documentation</title>
+  <title>parsedmarc.utils &mdash; parsedmarc 10.2.2 documentation</title>
      <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=b86133f3" />
-      <link rel="stylesheet" type="text/css" href="../../_static/css/theme.css?v=e59714d7" />
+      <link rel="stylesheet" type="text/css" href="../../_static/css/theme.css?v=9edc463e" />

  
      <script src="../../_static/jquery.js?v=5d32c60e"></script>
      <script src="../../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-      <script src="../../_static/documentation_options.js?v=d0f31c56"></script>
-      <script src="../../_static/doctools.js?v=9bcbadda"></script>
-      <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
+      <script src="../../_static/documentation_options.js?v=43731225"></script>
+      <script src="../../_static/doctools.js?v=fd6eb6e6"></script>
+      <script src="../../_static/sphinx_highlight.js?v=6ffebe34"></script>
    <script src="../../_static/js/theme.js"></script>
    <link rel="index" title="Index" href="../../genindex.html" />
    <link rel="search" title="Search" href="../../search.html" /> 
@@ -104,11 +104,7 @@
 <span class="kn">import</span><span class="w"> </span><span class="nn">mailparser</span>
 <span class="kn">from</span><span class="w"> </span><span class="nn">expiringdict</span><span class="w"> </span><span class="kn">import</span> <span class="n">ExpiringDict</span>

-<span class="k">try</span><span class="p">:</span>
-    <span class="kn">from</span><span class="w"> </span><span class="nn">importlib.resources</span><span class="w"> </span><span class="kn">import</span> <span class="n">files</span>
-<span class="k">except</span> <span class="ne">ImportError</span><span class="p">:</span>
-    <span class="c1"># Try backported to PY&lt;3 `importlib_resources`</span>
-    <span class="kn">from</span><span class="w"> </span><span class="nn">importlib.resources</span><span class="w"> </span><span class="kn">import</span> <span class="n">files</span>
+<span class="kn">from</span><span class="w"> </span><span class="nn">importlib.resources</span><span class="w"> </span><span class="kn">import</span> <span class="n">files</span>


 <span class="kn">import</span><span class="w"> </span><span class="nn">dns.exception</span>
@@ -476,7 +472,7 @@
 <div class="viewcode-block" id="human_timestamp_to_datetime">
 <a class="viewcode-back" href="../../api.html#parsedmarc.utils.human_timestamp_to_datetime">[docs]</a>
 <span class="k">def</span><span class="w"> </span><span class="nf">human_timestamp_to_datetime</span><span class="p">(</span>
-    <span class="n">human_timestamp</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">to_utc</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span>
+    <span class="n">human_timestamp</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">to_utc</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span> <span class="n">assume_utc</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span>
 <span class="p">)</span> <span class="o">-&gt;</span> <span class="n">datetime</span><span class="p">:</span>
 <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">    Converts a human-readable timestamp into a Python ``datetime`` object</span>
@@ -484,6 +480,11 @@
 <span class="sd">    Args:</span>
 <span class="sd">        human_timestamp (str): A timestamp string</span>
 <span class="sd">        to_utc (bool): Convert the timestamp to UTC</span>
+<span class="sd">        assume_utc (bool): Treat a timestamp that carries no UTC offset as</span>
+<span class="sd">            UTC wall-clock time instead of local time. Pass this when the</span>
+<span class="sd">            string is known to be UTC (e.g. an ``arrival_date_utc`` value);</span>
+<span class="sd">            otherwise naive results are interpreted as local time by</span>
+<span class="sd">            ``datetime.astimezone()`` / ``datetime.timestamp()``.</span>

 <span class="sd">    Returns:</span>
 <span class="sd">        datetime: The converted timestamp</span>
@@ -493,29 +494,41 @@
    <span class="n">human_timestamp</span> <span class="o">=</span> <span class="n">parenthesis_regex</span><span class="o">.</span><span class="n">sub</span><span class="p">(</span><span class="s2">&quot;&quot;</span><span class="p">,</span> <span class="n">human_timestamp</span><span class="p">)</span>

    <span class="n">dt</span> <span class="o">=</span> <span class="n">parse_date</span><span class="p">(</span><span class="n">human_timestamp</span><span class="p">)</span>
+    <span class="k">if</span> <span class="n">assume_utc</span> <span class="ow">and</span> <span class="n">dt</span><span class="o">.</span><span class="n">tzinfo</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
+        <span class="n">dt</span> <span class="o">=</span> <span class="n">dt</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="n">tzinfo</span><span class="o">=</span><span class="n">timezone</span><span class="o">.</span><span class="n">utc</span><span class="p">)</span>
    <span class="k">return</span> <span class="n">dt</span><span class="o">.</span><span class="n">astimezone</span><span class="p">(</span><span class="n">timezone</span><span class="o">.</span><span class="n">utc</span><span class="p">)</span> <span class="k">if</span> <span class="n">to_utc</span> <span class="k">else</span> <span class="n">dt</span></div>



 <div class="viewcode-block" id="human_timestamp_to_unix_timestamp">
 <a class="viewcode-back" href="../../api.html#parsedmarc.utils.human_timestamp_to_unix_timestamp">[docs]</a>
-<span class="k">def</span><span class="w"> </span><span class="nf">human_timestamp_to_unix_timestamp</span><span class="p">(</span><span class="n">human_timestamp</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">int</span><span class="p">:</span>
+<span class="k">def</span><span class="w"> </span><span class="nf">human_timestamp_to_unix_timestamp</span><span class="p">(</span>
+    <span class="n">human_timestamp</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">assume_utc</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span>
+<span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">int</span><span class="p">:</span>
 <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">    Converts a human-readable timestamp into a UNIX timestamp</span>

 <span class="sd">    Args:</span>
 <span class="sd">        human_timestamp (str): A timestamp in `YYYY-MM-DD HH:MM:SS`` format</span>
+<span class="sd">        assume_utc (bool): Treat a timestamp that carries no UTC offset as</span>
+<span class="sd">            UTC wall-clock time instead of local time</span>

 <span class="sd">    Returns:</span>
-<span class="sd">        float: The converted timestamp</span>
+<span class="sd">        int: The converted timestamp</span>
 <span class="sd">    &quot;&quot;&quot;</span>
    <span class="n">human_timestamp</span> <span class="o">=</span> <span class="n">human_timestamp</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="s2">&quot;T&quot;</span><span class="p">,</span> <span class="s2">&quot; &quot;</span><span class="p">)</span>
-    <span class="k">return</span> <span class="nb">int</span><span class="p">(</span><span class="n">human_timestamp_to_datetime</span><span class="p">(</span><span class="n">human_timestamp</span><span class="p">)</span><span class="o">.</span><span class="n">timestamp</span><span class="p">())</span></div>
+    <span class="k">return</span> <span class="nb">int</span><span class="p">(</span>
+        <span class="n">human_timestamp_to_datetime</span><span class="p">(</span><span class="n">human_timestamp</span><span class="p">,</span> <span class="n">assume_utc</span><span class="o">=</span><span class="n">assume_utc</span><span class="p">)</span><span class="o">.</span><span class="n">timestamp</span><span class="p">()</span>
+    <span class="p">)</span></div>



 <span class="n">_IP_DB_PATH</span><span class="p">:</span> <span class="nb">str</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span>

+<span class="c1"># The last database path logged by _get_ip_database_path(), so the</span>
+<span class="c1"># selection is logged when it changes rather than on every lookup.</span>
+<span class="n">_LAST_LOGGED_IP_DB_PATH</span><span class="p">:</span> <span class="nb">str</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span>
+

 <div class="viewcode-block" id="load_ip_db">
 <a class="viewcode-back" href="../../api.html#parsedmarc.utils.load_ip_db">[docs]</a>
@@ -639,12 +652,11 @@
    <span class="k">if</span> <span class="ow">not</span> <span class="n">_IPINFO_API_TOKEN</span> <span class="ow">or</span> <span class="ow">not</span> <span class="n">probe</span><span class="p">:</span>
        <span class="k">return</span>

-    <span class="k">try</span><span class="p">:</span>
-        <span class="n">_ipinfo_api_lookup</span><span class="p">(</span><span class="s2">&quot;1.1.1.1&quot;</span><span class="p">)</span>
-    <span class="k">except</span> <span class="n">InvalidIPinfoAPIKey</span><span class="p">:</span>
-        <span class="k">raise</span>
-    <span class="k">except</span> <span class="ne">Exception</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
-        <span class="n">logger</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;IPinfo API probe failed (will fall back per-request): </span><span class="si">{</span><span class="n">e</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
+    <span class="c1"># _ipinfo_api_lookup() raises InvalidIPinfoAPIKey on 401/403 (which</span>
+    <span class="c1"># must propagate) and returns None on any other failure — network</span>
+    <span class="c1"># errors, non-2xx responses, malformed bodies.</span>
+    <span class="k">if</span> <span class="n">_ipinfo_api_lookup</span><span class="p">(</span><span class="s2">&quot;1.1.1.1&quot;</span><span class="p">)</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
+        <span class="n">logger</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span><span class="s2">&quot;IPinfo API probe failed (will fall back per-request)&quot;</span><span class="p">)</span>
    <span class="k">else</span><span class="p">:</span>
        <span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s2">&quot;IPinfo API configured&quot;</span><span class="p">)</span></div>

@@ -740,6 +752,12 @@


 <span class="k">def</span><span class="w"> </span><span class="nf">_get_ip_database_path</span><span class="p">(</span><span class="n">db_path</span><span class="p">:</span> <span class="nb">str</span> <span class="o">|</span> <span class="kc">None</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">str</span><span class="p">:</span>
+    <span class="c1"># Last-resort fallbacks for unusual installs where the bundled database</span>
+    <span class="c1"># is missing. Country-only databases (GeoLite2 / DBIP) lack the ASN</span>
+    <span class="c1"># fields source attribution depends on, so an incidental system GeoIP</span>
+    <span class="c1"># file must never shadow the parsedmarc-managed database</span>
+    <span class="c1"># (https://github.com/domainaware/parsedmarc/issues/810). To use</span>
+    <span class="c1"># MaxMind or DBIP data deliberately, set the ip_db_path option.</span>
    <span class="n">db_paths</span> <span class="o">=</span> <span class="p">[</span>
        <span class="s2">&quot;ipinfo_lite.mmdb&quot;</span><span class="p">,</span>
        <span class="s2">&quot;GeoLite2-Country.mmdb&quot;</span><span class="p">,</span>
@@ -763,19 +781,35 @@
        <span class="p">)</span>
        <span class="n">db_path</span> <span class="o">=</span> <span class="kc">None</span>

-    <span class="k">if</span> <span class="n">db_path</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
-        <span class="k">for</span> <span class="n">system_path</span> <span class="ow">in</span> <span class="n">db_paths</span><span class="p">:</span>
-            <span class="k">if</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">exists</span><span class="p">(</span><span class="n">system_path</span><span class="p">):</span>
-                <span class="n">db_path</span> <span class="o">=</span> <span class="n">system_path</span>
-                <span class="k">break</span>
+    <span class="c1"># The database parsedmarc manages takes precedence: the one selected by</span>
+    <span class="c1"># load_ip_db() (downloaded, cached, or bundled), or the bundled copy</span>
+    <span class="c1"># directly for library callers that never call load_ip_db().</span>
+    <span class="k">if</span> <span class="n">db_path</span> <span class="ow">is</span> <span class="kc">None</span> <span class="ow">and</span> <span class="n">_IP_DB_PATH</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
+        <span class="n">db_path</span> <span class="o">=</span> <span class="n">_IP_DB_PATH</span>

    <span class="k">if</span> <span class="n">db_path</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
-        <span class="k">if</span> <span class="n">_IP_DB_PATH</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
-            <span class="n">db_path</span> <span class="o">=</span> <span class="n">_IP_DB_PATH</span>
+        <span class="n">bundled_path</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span>
+            <span class="n">files</span><span class="p">(</span><span class="n">parsedmarc</span><span class="o">.</span><span class="n">resources</span><span class="o">.</span><span class="n">ipinfo</span><span class="p">)</span><span class="o">.</span><span class="n">joinpath</span><span class="p">(</span><span class="s2">&quot;ipinfo_lite.mmdb&quot;</span><span class="p">)</span>
+        <span class="p">)</span>
+        <span class="k">if</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">isfile</span><span class="p">(</span><span class="n">bundled_path</span><span class="p">):</span>
+            <span class="n">db_path</span> <span class="o">=</span> <span class="n">bundled_path</span>
        <span class="k">else</span><span class="p">:</span>
-            <span class="n">db_path</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span>
-                <span class="n">files</span><span class="p">(</span><span class="n">parsedmarc</span><span class="o">.</span><span class="n">resources</span><span class="o">.</span><span class="n">ipinfo</span><span class="p">)</span><span class="o">.</span><span class="n">joinpath</span><span class="p">(</span><span class="s2">&quot;ipinfo_lite.mmdb&quot;</span><span class="p">)</span>
-            <span class="p">)</span>
+            <span class="k">for</span> <span class="n">system_path</span> <span class="ow">in</span> <span class="n">db_paths</span><span class="p">:</span>
+                <span class="k">if</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">exists</span><span class="p">(</span><span class="n">system_path</span><span class="p">):</span>
+                    <span class="n">db_path</span> <span class="o">=</span> <span class="n">system_path</span>
+                    <span class="k">break</span>
+            <span class="k">else</span><span class="p">:</span>
+                <span class="c1"># Nothing found anywhere; use the bundled path so the</span>
+                <span class="c1"># os.stat() below raises a FileNotFoundError naming the</span>
+                <span class="c1"># expected install location.</span>
+                <span class="n">db_path</span> <span class="o">=</span> <span class="n">bundled_path</span>
+
+    <span class="k">global</span> <span class="n">_LAST_LOGGED_IP_DB_PATH</span>
+    <span class="k">if</span> <span class="n">db_path</span> <span class="o">!=</span> <span class="n">_LAST_LOGGED_IP_DB_PATH</span><span class="p">:</span>
+        <span class="c1"># Log per selected path, not per lookup — this function runs on</span>
+        <span class="c1"># every uncached IP lookup and would flood --debug output.</span>
+        <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Using IP database at </span><span class="si">{</span><span class="n">db_path</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
+        <span class="n">_LAST_LOGGED_IP_DB_PATH</span> <span class="o">=</span> <span class="n">db_path</span>

    <span class="n">db_age</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">()</span> <span class="o">-</span> <span class="n">datetime</span><span class="o">.</span><span class="n">fromtimestamp</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">stat</span><span class="p">(</span><span class="n">db_path</span><span class="p">)</span><span class="o">.</span><span class="n">st_mtime</span><span class="p">)</span>
    <span class="k">if</span> <span class="n">db_age</span> <span class="o">&gt;</span> <span class="n">timedelta</span><span class="p">(</span><span class="n">days</span><span class="o">=</span><span class="mi">30</span><span class="p">):</span>
@@ -1278,10 +1312,11 @@
                    <span class="n">received</span><span class="p">[</span><span class="s2">&quot;date_utc&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">received</span><span class="p">[</span><span class="s2">&quot;date_utc&quot;</span><span class="p">]</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="s2">&quot;T&quot;</span><span class="p">,</span> <span class="s2">&quot; &quot;</span><span class="p">)</span>

    <span class="k">if</span> <span class="s2">&quot;from&quot;</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">parsed_email</span><span class="p">:</span>
-        <span class="k">if</span> <span class="s2">&quot;From&quot;</span> <span class="ow">in</span> <span class="n">parsed_email</span><span class="p">[</span><span class="s2">&quot;headers&quot;</span><span class="p">]:</span>
-            <span class="n">parsed_email</span><span class="p">[</span><span class="s2">&quot;from&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">parsed_email</span><span class="p">[</span><span class="s2">&quot;Headers&quot;</span><span class="p">][</span><span class="s2">&quot;From&quot;</span><span class="p">]</span>
-        <span class="k">else</span><span class="p">:</span>
-            <span class="n">parsed_email</span><span class="p">[</span><span class="s2">&quot;from&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>
+        <span class="c1"># mailparser omits &quot;from&quot; from mail_json when the From header is</span>
+        <span class="c1"># present but unparseable (e.g. an empty &quot;From:&quot;); headers_json may</span>
+        <span class="c1"># still carry a &quot;From&quot; entry, which can be an empty list — treat</span>
+        <span class="c1"># that the same as a missing header.</span>
+        <span class="n">parsed_email</span><span class="p">[</span><span class="s2">&quot;from&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">parsed_email</span><span class="p">[</span><span class="s2">&quot;headers&quot;</span><span class="p">]</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;From&quot;</span><span class="p">)</span> <span class="ow">or</span> <span class="kc">None</span>

    <span class="k">if</span> <span class="n">parsed_email</span><span class="p">[</span><span class="s2">&quot;from&quot;</span><span class="p">]</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
        <span class="n">parsed_email</span><span class="p">[</span><span class="s2">&quot;from&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">parse_email_address</span><span class="p">(</span><span class="n">parsed_email</span><span class="p">[</span><span class="s2">&quot;from&quot;</span><span class="p">][</span><span class="mi">0</span><span class="p">])</span>
@@ -119,12 +119,28 @@ This installs the `msgconvert` script to `/usr/local/bin/msgconvert`.

 ## Using MaxMind GeoLite2 (optional)

-`parsedmarc` will pick up the [MaxMind GeoLite2 Country database] if
-it is installed at one of the standard system paths (e.g.
-`/usr/share/GeoIP/GeoLite2-Country.mmdb`,
-`/var/lib/GeoIP/GeoLite2-Country.mmdb`, or the equivalent location on
-Windows). **Use this only if you specifically prefer MaxMind data over
-the bundled IPinfo Lite database — most users do not need it.**
+To use the [MaxMind GeoLite2 Country database] instead of the bundled
+IPinfo Lite database, point the `ip_db_path` option at it explicitly:
+
+```ini
+[general]
+ip_db_path = /usr/share/GeoIP/GeoLite2-Country.mmdb
+```
+
+**Use this only if you specifically prefer MaxMind data over the
+bundled IPinfo Lite database — most users do not need it.** Country
+databases like GeoLite2 carry no ASN data, so source attribution for
+IP addresses without reverse DNS is reduced when one is used.
+
+:::{note}
+parsedmarc no longer picks up a GeoLite2/DBIP database from standard
+system paths (e.g. `/usr/share/GeoIP/GeoLite2-Country.mmdb`)
+automatically — a GeoIP file installed by an unrelated distro package
+would silently override the bundled database and disable ASN
+enrichment. System paths are now only consulted as a last resort when
+the bundled database is missing. If you previously relied on the
+automatic pickup, set `ip_db_path` as shown above.
+:::

 Install [geoipupdate] for your platform:

@@ -218,8 +218,8 @@ The full set of configuration options are:
  - `password` - str: The IMAP password
 - `msgraph`
  - `auth_method` - str: Authentication method, valid types are
-      `UsernamePassword`, `DeviceCode`, `ClientSecret`, or `Certificate`
-      (Default: `UsernamePassword`).
+      `UsernamePassword`, `DeviceCode`, `ClientSecret`, `Certificate`, or
+      `ClientAssertion` (Default: `UsernamePassword`).
  - `user` - str: The M365 user, required when the auth method is
      UsernamePassword
  - `password` - str: The user password, required when the auth
@@ -231,6 +231,17 @@ The full set of configuration options are:
      `Certificate`
  - `certificate_password` - str: Optional password for the
      certificate file when using `Certificate` auth
+  - `client_assertion` - str: A signed JWT client assertion, required
+      when the auth method is `ClientAssertion`
+
+    :::{note}
+    `client_assertion` is a static value, so it is only usable for as
+    long as the JWT it contains remains unexpired (assertions are
+    typically short-lived, on the order of minutes). It is best suited
+    to short one-shot runs; for long-running `watch` mode, prefer
+    `Certificate` or `ClientSecret` auth, which can refresh
+    indefinitely.
+    :::
  - `tenant_id` - str: The Azure AD tenant ID. This is required
      for all auth methods except UsernamePassword.
  - `mailbox` - str: The mailbox name. This defaults to the
@@ -252,6 +263,18 @@ The full set of configuration options are:
    username, you must grant the app `Mail.ReadWrite.Shared`.
    :::

+    :::{tip}
+    **Troubleshooting connections.** Run with `--verbose` to log a
+    redacted connection summary (auth method, tenant, client ID,
+    mailbox, Graph URL) before the connection attempt, and with
+    `--debug` to additionally surface the underlying library activity —
+    `azure.identity` token acquisition (including `AADSTS` error codes
+    from Entra ID, which distinguish a local configuration problem from
+    an Exchange Online-side one), Microsoft Graph SDK requests, and
+    `httpx` HTTP request lines. Secret values (passwords, client
+    secrets, certificate passwords) are never written to logs.
+    :::
+
    :::{warning}
    If you are using the `ClientSecret` auth method, you need to
    grant the `Mail.ReadWrite` (application) permission to the
@@ -269,7 +292,7 @@ The full set of configuration options are:
    ```

    The same application permission and mailbox scoping guidance
-    applies to the `Certificate` auth method.
+    applies to the `Certificate` and `ClientAssertion` auth methods.

    :::
 - `elasticsearch`
@@ -59,7 +59,7 @@ const Documentation = {
    Object.assign(Documentation.TRANSLATIONS, catalog.messages);
    Documentation.PLURAL_EXPR = new Function(
      "n",
-      `return (${catalog.plural_expr})`
+      `return (${catalog.plural_expr})`,
    );
    Documentation.LOCALE = catalog.locale;
  },
@@ -89,7 +89,7 @@ const Documentation = {

    const togglerElements = document.querySelectorAll("img.toggler");
    togglerElements.forEach((el) =>
-      el.addEventListener("click", (event) => toggler(event.currentTarget))
+      el.addEventListener("click", (event) => toggler(event.currentTarget)),
    );
    togglerElements.forEach((el) => (el.style.display = ""));
    if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) togglerElements.forEach(toggler);
@@ -98,14 +98,15 @@ const Documentation = {
  initOnKeyListeners: () => {
    // only install a listener if it is really needed
    if (
-      !DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS &&
-      !DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS
+      !DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS
+      && !DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS
    )
      return;

    document.addEventListener("keydown", (event) => {
      // bail for input elements
-      if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return;
+      if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName))
+        return;
      // bail with special keys
      if (event.altKey || event.ctrlKey || event.metaKey) return;

@@ -1,5 +1,5 @@
 const DOCUMENTATION_OPTIONS = {
-    VERSION: '10.2.0',
+    VERSION: '10.2.2',
    LANGUAGE: 'en',
    COLLAPSE_INDEX: false,
    BUILDER: 'html',
@@ -41,11 +41,12 @@ if (typeof Scorer === "undefined") {
 }

 // Global search result kind enum, used by themes to style search results.
+// prettier-ignore
 class SearchResultKind {
-    static get index() { return  "index"; }
-    static get object() { return "object"; }
-    static get text() { return "text"; }
-    static get title() { return "title"; }
+  static get index() { return "index"; }
+  static get object() { return "object"; }
+  static get text() { return "text"; }
+  static get title() { return "title"; }
 }

 const _removeChildren = (element) => {
@@ -58,6 +59,15 @@ const _removeChildren = (element) => {
 const _escapeRegExp = (string) =>
  string.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string

+const _escapeHTML = (text) => {
+  return text
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;");
+};
+
 const _displayItem = (item, searchTerms, highlightTerms) => {
  const docBuilder = DOCUMENTATION_OPTIONS.BUILDER;
  const docFileSuffix = DOCUMENTATION_OPTIONS.FILE_SUFFIX;
@@ -90,25 +100,30 @@ const _displayItem = (item, searchTerms, highlightTerms) => {
  let linkEl = listItem.appendChild(document.createElement("a"));
  linkEl.href = linkUrl + anchor;
  linkEl.dataset.score = score;
-  linkEl.innerHTML = title;
+  linkEl.innerHTML = _escapeHTML(title);
  if (descr) {
    listItem.appendChild(document.createElement("span")).innerHTML =
-      " (" + descr + ")";
+      ` (${_escapeHTML(descr)})`;
    // highlight search terms in the description
-    if (SPHINX_HIGHLIGHT_ENABLED)  // set in sphinx_highlight.js
-      highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted"));
-  }
-  else if (showSearchSummary)
+    if (SPHINX_HIGHLIGHT_ENABLED)
+      // SPHINX_HIGHLIGHT_ENABLED is set in sphinx_highlight.js
+      highlightTerms.forEach((term) =>
+        _highlightText(listItem, term, "highlighted"),
+      );
+  } else if (showSearchSummary)
    fetch(requestUrl)
      .then((responseData) => responseData.text())
      .then((data) => {
        if (data)
          listItem.appendChild(
-            Search.makeSearchSummary(data, searchTerms, anchor)
+            Search.makeSearchSummary(data, searchTerms, anchor),
          );
        // highlight search terms in the summary
-        if (SPHINX_HIGHLIGHT_ENABLED)  // set in sphinx_highlight.js
-          highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted"));
+        if (SPHINX_HIGHLIGHT_ENABLED)
+          // SPHINX_HIGHLIGHT_ENABLED is set in sphinx_highlight.js
+          highlightTerms.forEach((term) =>
+            _highlightText(listItem, term, "highlighted"),
+          );
      });
  Search.output.appendChild(listItem);
 };
@@ -117,14 +132,14 @@ const _finishSearch = (resultCount) => {
  Search.title.innerText = _("Search Results");
  if (!resultCount)
    Search.status.innerText = Documentation.gettext(
-      "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories."
+      "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.",
    );
  else
    Search.status.innerText = Documentation.ngettext(
      "Search finished, found one page matching the search query.",
      "Search finished, found ${resultCount} pages matching the search query.",
      resultCount,
-    ).replace('${resultCount}', resultCount);
+    ).replace("${resultCount}", resultCount);
 };
 const _displayNextItem = (
  results,
@@ -138,7 +153,7 @@ const _displayNextItem = (
    _displayItem(results.pop(), searchTerms, highlightTerms);
    setTimeout(
      () => _displayNextItem(results, resultCount, searchTerms, highlightTerms),
-      5
+      5,
    );
  }
  // search finished, update title and status message
@@ -170,9 +185,10 @@ const _orderResultsByScoreThenName = (a, b) => {
 * This is the same as ``\W+`` in Python, preserving the surrogate pair area.
 */
 if (typeof splitQuery === "undefined") {
-  var splitQuery = (query) => query
+  var splitQuery = (query) =>
+    query
      .split(/[^\p{Letter}\p{Number}_\p{Emoji_Presentation}]+/gu)
-      .filter(term => term)  // remove remaining empty strings
+      .filter((term) => term); // remove remaining empty strings
 }

 /**
@@ -184,16 +200,23 @@ const Search = {
  _pulse_status: -1,

  htmlToText: (htmlString, anchor) => {
-    const htmlElement = new DOMParser().parseFromString(htmlString, 'text/html');
+    const htmlElement = new DOMParser().parseFromString(
+      htmlString,
+      "text/html",
+    );
    for (const removalQuery of [".headerlink", "script", "style"]) {
-      htmlElement.querySelectorAll(removalQuery).forEach((el) => { el.remove() });
+      htmlElement.querySelectorAll(removalQuery).forEach((el) => {
+        el.remove();
+      });
    }
    if (anchor) {
-      const anchorContent = htmlElement.querySelector(`[role="main"] ${anchor}`);
+      const anchorContent = htmlElement.querySelector(
+        `[role="main"] ${anchor}`,
+      );
      if (anchorContent) return anchorContent.textContent;

      console.warn(
-        `Anchored content block not found. Sphinx search tries to obtain it via DOM query '[role=main] ${anchor}'. Check your theme or template.`
+        `Anchored content block not found. Sphinx search tries to obtain it via DOM query '[role=main] ${anchor}'. Check your theme or template.`,
      );
    }

@@ -202,7 +225,7 @@ const Search = {
    if (docContent) return docContent.textContent;

    console.warn(
-      "Content block not found. Sphinx search tries to obtain it via DOM query '[role=main]'. Check your theme or template."
+      "Content block not found. Sphinx search tries to obtain it via DOM query '[role=main]'. Check your theme or template.",
    );
    return "";
  },
@@ -287,12 +310,8 @@ const Search = {
      const queryTermLower = queryTerm.toLowerCase();

      // maybe skip this "word"
-      // stopwords array is from language_data.js
-      if (
-        stopwords.indexOf(queryTermLower) !== -1 ||
-        queryTerm.match(/^\d+$/)
-      )
-        return;
+      // stopwords set is from language_data.js
+      if (stopwords.has(queryTermLower) || queryTerm.match(/^\d+$/)) return;

      // stem the word
      let word = stemmer.stemWord(queryTermLower);
@@ -304,8 +323,12 @@ const Search = {
      }
    });

-    if (SPHINX_HIGHLIGHT_ENABLED) {  // set in sphinx_highlight.js
-      localStorage.setItem("sphinx_highlight_terms", [...highlightTerms].join(" "))
+    if (SPHINX_HIGHLIGHT_ENABLED) {
+      // SPHINX_HIGHLIGHT_ENABLED is set in sphinx_highlight.js
+      localStorage.setItem(
+        "sphinx_highlight_terms",
+        [...highlightTerms].join(" "),
+      );
    }

    // console.debug("SEARCH: searching for:");
@@ -318,7 +341,13 @@ const Search = {
  /**
   * execute search (requires search index to be loaded)
   */
-  _performSearch: (query, searchTerms, excludedTerms, highlightTerms, objectTerms) => {
+  _performSearch: (
+    query,
+    searchTerms,
+    excludedTerms,
+    highlightTerms,
+    objectTerms,
+  ) => {
    const filenames = Search._index.filenames;
    const docNames = Search._index.docnames;
    const titles = Search._index.titles;
@@ -334,10 +363,15 @@ const Search = {

    const queryLower = query.toLowerCase().trim();
    for (const [title, foundTitles] of Object.entries(allTitles)) {
-      if (title.toLowerCase().trim().includes(queryLower) && (queryLower.length >= title.length/2)) {
+      if (
+        title.toLowerCase().trim().includes(queryLower)
+        && queryLower.length >= title.length / 2
+      ) {
        for (const [file, id] of foundTitles) {
-          const score = Math.round(Scorer.title * queryLower.length / title.length);
-          const boost = titles[file] === title ? 1 : 0;  // add a boost for document titles
+          const score = Math.round(
+            (Scorer.title * queryLower.length) / title.length,
+          );
+          const boost = titles[file] === title ? 1 : 0; // add a boost for document titles
          normalResults.push([
            docNames[file],
            titles[file] !== title ? `${titles[file]} > ${title}` : title,
@@ -353,9 +387,9 @@ const Search = {

    // search for explicit entries in index directives
    for (const [entry, foundEntries] of Object.entries(indexEntries)) {
-      if (entry.includes(queryLower) && (queryLower.length >= entry.length/2)) {
+      if (entry.includes(queryLower) && queryLower.length >= entry.length / 2) {
        for (const [file, id, isMain] of foundEntries) {
-          const score = Math.round(100 * queryLower.length / entry.length);
+          const score = Math.round((100 * queryLower.length) / entry.length);
          const result = [
            docNames[file],
            titles[file],
@@ -376,11 +410,13 @@ const Search = {

    // lookup as object
    objectTerms.forEach((term) =>
-      normalResults.push(...Search.performObjectSearch(term, objectTerms))
+      normalResults.push(...Search.performObjectSearch(term, objectTerms)),
    );

    // lookup as search terms in fulltext
-    normalResults.push(...Search.performTermsSearch(searchTerms, excludedTerms));
+    normalResults.push(
+      ...Search.performTermsSearch(searchTerms, excludedTerms),
+    );

    // let the scorer override scores with a custom scoring function
    if (Scorer.score) {
@@ -401,7 +437,11 @@ const Search = {
    // note the reversing of results, so that in the case of duplicates, the highest-scoring entry is kept
    let seen = new Set();
    results = results.reverse().reduce((acc, result) => {
-      let resultStr = result.slice(0, 4).concat([result[5]]).map(v => String(v)).join(',');
+      let resultStr = result
+        .slice(0, 4)
+        .concat([result[5]])
+        .map((v) => String(v))
+        .join(",");
      if (!seen.has(resultStr)) {
        acc.push(result);
        seen.add(resultStr);
@@ -413,8 +453,20 @@ const Search = {
  },

  query: (query) => {
-    const [searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms] = Search._parseQuery(query);
-    const results = Search._performSearch(searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms);
+    const [
+      searchQuery,
+      searchTerms,
+      excludedTerms,
+      highlightTerms,
+      objectTerms,
+    ] = Search._parseQuery(query);
+    const results = Search._performSearch(
+      searchQuery,
+      searchTerms,
+      excludedTerms,
+      highlightTerms,
+      objectTerms,
+    );

    // for debugging
    //Search.lastresults = results.slice();  // a copy
@@ -437,7 +489,7 @@ const Search = {
    const results = [];

    const objectSearchCallback = (prefix, match) => {
-      const name = match[4]
+      const name = match[4];
      const fullname = (prefix ? prefix + "." : "") + name;
      const fullnameLower = fullname.toLowerCase();
      if (fullnameLower.indexOf(object) < 0) return;
@@ -489,9 +541,7 @@ const Search = {
      ]);
    };
    Object.keys(objects).forEach((prefix) =>
-      objects[prefix].forEach((array) =>
-        objectSearchCallback(prefix, array)
-      )
+      objects[prefix].forEach((array) => objectSearchCallback(prefix, array)),
    );
    return results;
  },
@@ -516,8 +566,14 @@ const Search = {
      // find documents, if any, containing the query word in their text/title term indices
      // use Object.hasOwnProperty to avoid mismatching against prototype properties
      const arr = [
-        { files: terms.hasOwnProperty(word) ? terms[word] : undefined, score: Scorer.term },
-        { files: titleTerms.hasOwnProperty(word) ? titleTerms[word] : undefined, score: Scorer.title },
+        {
+          files: terms.hasOwnProperty(word) ? terms[word] : undefined,
+          score: Scorer.term,
+        },
+        {
+          files: titleTerms.hasOwnProperty(word) ? titleTerms[word] : undefined,
+          score: Scorer.title,
+        },
      ];
      // add support for partial matches
      if (word.length > 2) {
@@ -558,7 +614,8 @@ const Search = {
      // create the mapping
      files.forEach((file) => {
        if (!fileMap.has(file)) fileMap.set(file, [word]);
-        else if (fileMap.get(file).indexOf(word) === -1) fileMap.get(file).push(word);
+        else if (fileMap.get(file).indexOf(word) === -1)
+          fileMap.get(file).push(word);
      });
    });

@@ -569,11 +626,11 @@ const Search = {

      // as search terms with length < 3 are discarded
      const filteredTermCount = [...searchTerms].filter(
-        (term) => term.length > 2
+        (term) => term.length > 2,
      ).length;
      if (
-        wordList.length !== searchTerms.size &&
-        wordList.length !== filteredTermCount
+        wordList.length !== searchTerms.size
+        && wordList.length !== filteredTermCount
      )
        continue;

@@ -581,10 +638,10 @@ const Search = {
      if (
        [...excludedTerms].some(
          (term) =>
-            terms[term] === file ||
-            titleTerms[term] === file ||
-            (terms[term] || []).includes(file) ||
-            (titleTerms[term] || []).includes(file)
+            terms[term] === file
+            || titleTerms[term] === file
+            || (terms[term] || []).includes(file)
+            || (titleTerms[term] || []).includes(file),
        )
      )
        break;
@@ -626,7 +683,8 @@ const Search = {

    let summary = document.createElement("p");
    summary.classList.add("context");
-    summary.textContent = top + text.substr(startWithContext, 240).trim() + tail;
+    summary.textContent =
+      top + text.substr(startWithContext, 240).trim() + tail;

    return summary;
  },
@@ -1,7 +1,7 @@
 /* Highlighting utilities for Sphinx HTML documentation. */
 "use strict";

-const SPHINX_HIGHLIGHT_ENABLED = true
+const SPHINX_HIGHLIGHT_ENABLED = true;

 /**
 * highlight a given string on a node by wrapping it in
@@ -13,9 +13,9 @@ const _highlight = (node, addItems, text, className) => {
    const parent = node.parentNode;
    const pos = val.toLowerCase().indexOf(text);
    if (
-      pos >= 0 &&
-      !parent.classList.contains(className) &&
-      !parent.classList.contains("nohighlight")
+      pos >= 0
+      && !parent.classList.contains(className)
+      && !parent.classList.contains("nohighlight")
    ) {
      let span;

@@ -30,13 +30,7 @@ const _highlight = (node, addItems, text, className) => {

      span.appendChild(document.createTextNode(val.substr(pos, text.length)));
      const rest = document.createTextNode(val.substr(pos + text.length));
-      parent.insertBefore(
-        span,
-        parent.insertBefore(
-          rest,
-          node.nextSibling
-        )
-      );
+      parent.insertBefore(span, parent.insertBefore(rest, node.nextSibling));
      node.nodeValue = val.substr(0, pos);
      /* There may be more occurrences of search term in this node. So call this
       * function recursively on the remaining fragment.
@@ -46,7 +40,7 @@ const _highlight = (node, addItems, text, className) => {
      if (isInSVG) {
        const rect = document.createElementNS(
          "http://www.w3.org/2000/svg",
-          "rect"
+          "rect",
        );
        const bbox = parent.getBBox();
        rect.x.baseVal.value = bbox.x;
@@ -65,7 +59,7 @@ const _highlightText = (thisNode, text, className) => {
  let addItems = [];
  _highlight(thisNode, addItems, text, className);
  addItems.forEach((obj) =>
-    obj.parent.insertAdjacentElement("beforebegin", obj.target)
+    obj.parent.insertAdjacentElement("beforebegin", obj.target),
  );
 };

@@ -73,25 +67,31 @@ const _highlightText = (thisNode, text, className) => {
 * Small JavaScript module for the documentation.
 */
 const SphinxHighlight = {
-
  /**
   * highlight the search words provided in localstorage in the text
   */
  highlightSearchWords: () => {
-    if (!SPHINX_HIGHLIGHT_ENABLED) return;  // bail if no highlight
+    if (!SPHINX_HIGHLIGHT_ENABLED) return; // bail if no highlight

    // get and clear terms from localstorage
    const url = new URL(window.location);
    const highlight =
-        localStorage.getItem("sphinx_highlight_terms")
-        || url.searchParams.get("highlight")
-        || "";
-    localStorage.removeItem("sphinx_highlight_terms")
-    url.searchParams.delete("highlight");
-    window.history.replaceState({}, "", url);
+      localStorage.getItem("sphinx_highlight_terms")
+      || url.searchParams.get("highlight")
+      || "";
+    localStorage.removeItem("sphinx_highlight_terms");
+    // Update history only if '?highlight' is present; otherwise it
+    // clears text fragments (not set in window.location by the browser)
+    if (url.searchParams.has("highlight")) {
+      url.searchParams.delete("highlight");
+      window.history.replaceState({}, "", url);
+    }

    // get individual terms from highlight string
-    const terms = highlight.toLowerCase().split(/\s+/).filter(x => x);
+    const terms = highlight
+      .toLowerCase()
+      .split(/\s+/)
+      .filter((x) => x);
    if (terms.length === 0) return; // nothing to do

    // There should never be more than one element matching "div.body"
@@ -107,11 +107,11 @@ const SphinxHighlight = {
      document
        .createRange()
        .createContextualFragment(
-          '<p class="highlight-link">' +
-            '<a href="javascript:SphinxHighlight.hideSearchWords()">' +
-            _("Hide Search Matches") +
-            "</a></p>"
-        )
+          '<p class="highlight-link">'
+            + '<a href="javascript:SphinxHighlight.hideSearchWords()">'
+            + _("Hide Search Matches")
+            + "</a></p>",
+        ),
    );
  },

@@ -125,7 +125,7 @@ const SphinxHighlight = {
    document
      .querySelectorAll("span.highlighted")
      .forEach((el) => el.classList.remove("highlighted"));
-    localStorage.removeItem("sphinx_highlight_terms")
+    localStorage.removeItem("sphinx_highlight_terms");
  },

  initEscapeListener: () => {
@@ -134,10 +134,15 @@ const SphinxHighlight = {

    document.addEventListener("keydown", (event) => {
      // bail for input elements
-      if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return;
+      if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName))
+        return;
      // bail with special keys
-      if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) return;
-      if (DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS && (event.key === "Escape")) {
+      if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey)
+        return;
+      if (
+        DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS
+        && event.key === "Escape"
+      ) {
        SphinxHighlight.hideSearchWords();
        event.preventDefault();
      }
@@ -6,16 +6,16 @@
  <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Contributing to parsedmarc &mdash; parsedmarc 10.2.0 documentation</title>
+  <title>Contributing to parsedmarc &mdash; parsedmarc 10.2.2 documentation</title>
      <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b86133f3" />
-      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=e59714d7" />
+      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=9edc463e" />

  
      <script src="_static/jquery.js?v=5d32c60e"></script>
      <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-      <script src="_static/documentation_options.js?v=d0f31c56"></script>
-      <script src="_static/doctools.js?v=9bcbadda"></script>
-      <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
+      <script src="_static/documentation_options.js?v=43731225"></script>
+      <script src="_static/doctools.js?v=fd6eb6e6"></script>
+      <script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
    <script src="_static/js/theme.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
@@ -6,16 +6,16 @@
  <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Accessing an inbox using OWA/EWS &mdash; parsedmarc 10.2.0 documentation</title>
+  <title>Accessing an inbox using OWA/EWS &mdash; parsedmarc 10.2.2 documentation</title>
      <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b86133f3" />
-      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=e59714d7" />
+      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=9edc463e" />

  
      <script src="_static/jquery.js?v=5d32c60e"></script>
      <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-      <script src="_static/documentation_options.js?v=d0f31c56"></script>
-      <script src="_static/doctools.js?v=9bcbadda"></script>
-      <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
+      <script src="_static/documentation_options.js?v=43731225"></script>
+      <script src="_static/doctools.js?v=fd6eb6e6"></script>
+      <script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
    <script src="_static/js/theme.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
@@ -6,16 +6,16 @@
  <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Understanding DMARC &mdash; parsedmarc 10.2.0 documentation</title>
+  <title>Understanding DMARC &mdash; parsedmarc 10.2.2 documentation</title>
      <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b86133f3" />
-      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=e59714d7" />
+      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=9edc463e" />

  
      <script src="_static/jquery.js?v=5d32c60e"></script>
      <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-      <script src="_static/documentation_options.js?v=d0f31c56"></script>
-      <script src="_static/doctools.js?v=9bcbadda"></script>
-      <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
+      <script src="_static/documentation_options.js?v=43731225"></script>
+      <script src="_static/doctools.js?v=fd6eb6e6"></script>
+      <script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
    <script src="_static/js/theme.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
@@ -6,16 +6,16 @@
  <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Elasticsearch and Kibana &mdash; parsedmarc 10.2.0 documentation</title>
+  <title>Elasticsearch and Kibana &mdash; parsedmarc 10.2.2 documentation</title>
      <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b86133f3" />
-      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=e59714d7" />
+      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=9edc463e" />

  
      <script src="_static/jquery.js?v=5d32c60e"></script>
      <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-      <script src="_static/documentation_options.js?v=d0f31c56"></script>
-      <script src="_static/doctools.js?v=9bcbadda"></script>
-      <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
+      <script src="_static/documentation_options.js?v=43731225"></script>
+      <script src="_static/doctools.js?v=fd6eb6e6"></script>
+      <script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
    <script src="_static/js/theme.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
@@ -5,16 +5,16 @@
 <head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Index &mdash; parsedmarc 10.2.0 documentation</title>
+  <title>Index &mdash; parsedmarc 10.2.2 documentation</title>
      <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b86133f3" />
-      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=e59714d7" />
+      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=9edc463e" />

  
      <script src="_static/jquery.js?v=5d32c60e"></script>
      <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-      <script src="_static/documentation_options.js?v=d0f31c56"></script>
-      <script src="_static/doctools.js?v=9bcbadda"></script>
-      <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
+      <script src="_static/documentation_options.js?v=43731225"></script>
+      <script src="_static/doctools.js?v=fd6eb6e6"></script>
+      <script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
    <script src="_static/js/theme.js"></script>
    <link rel="index" title="Index" href="#" />
    <link rel="search" title="Search" href="search.html" /> 
@@ -6,16 +6,16 @@
  <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>parsedmarc documentation - Open source DMARC report analyzer and visualizer &mdash; parsedmarc 10.2.0 documentation</title>
+  <title>parsedmarc documentation - Open source DMARC report analyzer and visualizer &mdash; parsedmarc 10.2.2 documentation</title>
      <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b86133f3" />
-      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=e59714d7" />
+      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=9edc463e" />

  
      <script src="_static/jquery.js?v=5d32c60e"></script>
      <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-      <script src="_static/documentation_options.js?v=d0f31c56"></script>
-      <script src="_static/doctools.js?v=9bcbadda"></script>
-      <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
+      <script src="_static/documentation_options.js?v=43731225"></script>
+      <script src="_static/doctools.js?v=fd6eb6e6"></script>
+      <script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
    <script src="_static/js/theme.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
@@ -91,7 +91,7 @@
 <p>This project is maintained by one developer.
 Please consider <a class="reference external" href="https://github.com/sponsors/seanthegeek">sponsoring my work</a> if you or your organization benefit from it.</p>
 </div>
-<a class="reference external image-reference" href="_static/screenshots/dmarc-summary-charts.png"><img alt="A screenshot of DMARC summary charts in Kibana" class="align-center" src="_images/dmarc-summary-charts.png" style="width: 754.0px; height: 449.0px;" />
+<a class="reference external image-reference" href="_static/screenshots/dmarc-summary-charts.png"><img alt="A screenshot of DMARC summary charts in Kibana" class="align-center" height="449" src="_images/dmarc-summary-charts.png" width="754" />
 </a>
 <p><code class="docutils literal notranslate"><span class="pre">parsedmarc</span></code> is a Python module and CLI utility for parsing DMARC reports.
 When used with Elasticsearch and Kibana (or Splunk), or with OpenSearch and Grafana, it works as a self-hosted
@@ -6,16 +6,16 @@
  <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Installation &mdash; parsedmarc 10.2.0 documentation</title>
+  <title>Installation &mdash; parsedmarc 10.2.2 documentation</title>
      <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b86133f3" />
-      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=e59714d7" />
+      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=9edc463e" />

  
      <script src="_static/jquery.js?v=5d32c60e"></script>
      <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-      <script src="_static/documentation_options.js?v=d0f31c56"></script>
-      <script src="_static/doctools.js?v=9bcbadda"></script>
-      <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
+      <script src="_static/documentation_options.js?v=43731225"></script>
+      <script src="_static/doctools.js?v=fd6eb6e6"></script>
+      <script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
    <script src="_static/js/theme.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
@@ -195,12 +195,26 @@ sudo<span class="w"> </span>cpan<span class="w"> </span>-i<span class="w"> </spa
 </section>
 <section id="using-maxmind-geolite2-optional">
 <h2>Using MaxMind GeoLite2 (optional)<a class="headerlink" href="#using-maxmind-geolite2-optional" title="Link to this heading"></a></h2>
-<p><code class="docutils literal notranslate"><span class="pre">parsedmarc</span></code> will pick up the <a class="reference external" href="https://dev.maxmind.com/geoip/geolite2-free-geolocation-data">MaxMind GeoLite2 Country database</a> if
-it is installed at one of the standard system paths (e.g.
-<code class="docutils literal notranslate"><span class="pre">/usr/share/GeoIP/GeoLite2-Country.mmdb</span></code>,
-<code class="docutils literal notranslate"><span class="pre">/var/lib/GeoIP/GeoLite2-Country.mmdb</span></code>, or the equivalent location on
-Windows). <strong>Use this only if you specifically prefer MaxMind data over
-the bundled IPinfo Lite database — most users do not need it.</strong></p>
+<p>To use the <a class="reference external" href="https://dev.maxmind.com/geoip/geolite2-free-geolocation-data">MaxMind GeoLite2 Country database</a> instead of the bundled
+IPinfo Lite database, point the <code class="docutils literal notranslate"><span class="pre">ip_db_path</span></code> option at it explicitly:</p>
+<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[general]</span>
+<span class="na">ip_db_path</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">/usr/share/GeoIP/GeoLite2-Country.mmdb</span>
+</pre></div>
+</div>
+<p><strong>Use this only if you specifically prefer MaxMind data over the
+bundled IPinfo Lite database — most users do not need it.</strong> Country
+databases like GeoLite2 carry no ASN data, so source attribution for
+IP addresses without reverse DNS is reduced when one is used.</p>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>parsedmarc no longer picks up a GeoLite2/DBIP database from standard
+system paths (e.g. <code class="docutils literal notranslate"><span class="pre">/usr/share/GeoIP/GeoLite2-Country.mmdb</span></code>)
+automatically — a GeoIP file installed by an unrelated distro package
+would silently override the bundled database and disable ASN
+enrichment. System paths are now only consulted as a last resort when
+the bundled database is missing. If you previously relied on the
+automatic pickup, set <code class="docutils literal notranslate"><span class="pre">ip_db_path</span></code> as shown above.</p>
+</div>
 <p>Install <a class="reference external" href="https://github.com/maxmind/geoipupdate">geoipupdate</a> for your platform:</p>
 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Debian 10+ (requires the contrib component in apt sources)</span>
 sudo<span class="w"> </span>apt-get<span class="w"> </span>install<span class="w"> </span>-y<span class="w"> </span>geoipupdate
@@ -6,16 +6,16 @@
  <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Using the Kibana dashboards &mdash; parsedmarc 10.2.0 documentation</title>
+  <title>Using the Kibana dashboards &mdash; parsedmarc 10.2.2 documentation</title>
      <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b86133f3" />
-      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=e59714d7" />
+      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=9edc463e" />

  
      <script src="_static/jquery.js?v=5d32c60e"></script>
      <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-      <script src="_static/documentation_options.js?v=d0f31c56"></script>
-      <script src="_static/doctools.js?v=9bcbadda"></script>
-      <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
+      <script src="_static/documentation_options.js?v=43731225"></script>
+      <script src="_static/doctools.js?v=fd6eb6e6"></script>
+      <script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
    <script src="_static/js/theme.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
@@ -6,16 +6,16 @@
  <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>What about mailing lists? &mdash; parsedmarc 10.2.0 documentation</title>
+  <title>What about mailing lists? &mdash; parsedmarc 10.2.2 documentation</title>
      <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b86133f3" />
-      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=e59714d7" />
+      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=9edc463e" />

  
      <script src="_static/jquery.js?v=5d32c60e"></script>
      <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-      <script src="_static/documentation_options.js?v=d0f31c56"></script>
-      <script src="_static/doctools.js?v=9bcbadda"></script>
-      <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
+      <script src="_static/documentation_options.js?v=43731225"></script>
+      <script src="_static/doctools.js?v=fd6eb6e6"></script>
+      <script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
    <script src="_static/js/theme.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" /> 
@@ -6,16 +6,16 @@
  <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>OpenSearch and Grafana &mdash; parsedmarc 10.2.0 documentation</title>
+  <title>OpenSearch and Grafana &mdash; parsedmarc 10.2.2 documentation</title>
      <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b86133f3" />
-      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=e59714d7" />
+      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=9edc463e" />

  
      <script src="_static/jquery.js?v=5d32c60e"></script>
      <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-      <script src="_static/documentation_options.js?v=d0f31c56"></script>
-      <script src="_static/doctools.js?v=9bcbadda"></script>
-      <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
+      <script src="_static/documentation_options.js?v=43731225"></script>
+      <script src="_static/doctools.js?v=fd6eb6e6"></script>
+      <script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
    <script src="_static/js/theme.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
@@ -6,16 +6,16 @@
  <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Sample outputs &mdash; parsedmarc 10.2.0 documentation</title>
+  <title>Sample outputs &mdash; parsedmarc 10.2.2 documentation</title>
      <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b86133f3" />
-      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=e59714d7" />
+      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=9edc463e" />

  
      <script src="_static/jquery.js?v=5d32c60e"></script>
      <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-      <script src="_static/documentation_options.js?v=d0f31c56"></script>
-      <script src="_static/doctools.js?v=9bcbadda"></script>
-      <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
+      <script src="_static/documentation_options.js?v=43731225"></script>
+      <script src="_static/doctools.js?v=fd6eb6e6"></script>
+      <script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
    <script src="_static/js/theme.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
@@ -5,16 +5,16 @@
 <head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Python Module Index &mdash; parsedmarc 10.2.0 documentation</title>
+  <title>Python Module Index &mdash; parsedmarc 10.2.2 documentation</title>
      <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b86133f3" />
-      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=e59714d7" />
+      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=9edc463e" />

  
      <script src="_static/jquery.js?v=5d32c60e"></script>
      <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-      <script src="_static/documentation_options.js?v=d0f31c56"></script>
-      <script src="_static/doctools.js?v=9bcbadda"></script>
-      <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
+      <script src="_static/documentation_options.js?v=43731225"></script>
+      <script src="_static/doctools.js?v=fd6eb6e6"></script>
+      <script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
    <script src="_static/js/theme.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
@@ -5,17 +5,17 @@
 <head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Search &mdash; parsedmarc 10.2.0 documentation</title>
+  <title>Search &mdash; parsedmarc 10.2.2 documentation</title>
      <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b86133f3" />
-      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=e59714d7" />
+      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=9edc463e" />

  
    
      <script src="_static/jquery.js?v=5d32c60e"></script>
      <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-      <script src="_static/documentation_options.js?v=d0f31c56"></script>
-      <script src="_static/doctools.js?v=9bcbadda"></script>
-      <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
+      <script src="_static/documentation_options.js?v=43731225"></script>
+      <script src="_static/doctools.js?v=fd6eb6e6"></script>
+      <script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
    <script src="_static/js/theme.js"></script>
    <script src="_static/searchtools.js"></script>
    <script src="_static/language_data.js"></script>
@@ -6,16 +6,16 @@
  <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Splunk &mdash; parsedmarc 10.2.0 documentation</title>
+  <title>Splunk &mdash; parsedmarc 10.2.2 documentation</title>
      <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b86133f3" />
-      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=e59714d7" />
+      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=9edc463e" />

  
      <script src="_static/jquery.js?v=5d32c60e"></script>
      <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-      <script src="_static/documentation_options.js?v=d0f31c56"></script>
-      <script src="_static/doctools.js?v=9bcbadda"></script>
-      <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
+      <script src="_static/documentation_options.js?v=43731225"></script>
+      <script src="_static/doctools.js?v=fd6eb6e6"></script>
+      <script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
    <script src="_static/js/theme.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
@@ -6,16 +6,16 @@
  <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Using parsedmarc &mdash; parsedmarc 10.2.0 documentation</title>
+  <title>Using parsedmarc &mdash; parsedmarc 10.2.2 documentation</title>
      <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b86133f3" />
-      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=e59714d7" />
+      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=9edc463e" />

  
      <script src="_static/jquery.js?v=5d32c60e"></script>
      <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-      <script src="_static/documentation_options.js?v=d0f31c56"></script>
-      <script src="_static/doctools.js?v=9bcbadda"></script>
-      <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
+      <script src="_static/documentation_options.js?v=43731225"></script>
+      <script src="_static/doctools.js?v=fd6eb6e6"></script>
+      <script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
    <script src="_static/js/theme.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
@@ -326,8 +326,8 @@ verification (not recommended)</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">msgraph</span></code></p>
 <ul>
 <li><p><code class="docutils literal notranslate"><span class="pre">auth_method</span></code> - str: Authentication method, valid types are
-<code class="docutils literal notranslate"><span class="pre">UsernamePassword</span></code>, <code class="docutils literal notranslate"><span class="pre">DeviceCode</span></code>, <code class="docutils literal notranslate"><span class="pre">ClientSecret</span></code>, or <code class="docutils literal notranslate"><span class="pre">Certificate</span></code>
-(Default: <code class="docutils literal notranslate"><span class="pre">UsernamePassword</span></code>).</p></li>
+<code class="docutils literal notranslate"><span class="pre">UsernamePassword</span></code>, <code class="docutils literal notranslate"><span class="pre">DeviceCode</span></code>, <code class="docutils literal notranslate"><span class="pre">ClientSecret</span></code>, <code class="docutils literal notranslate"><span class="pre">Certificate</span></code>, or
+<code class="docutils literal notranslate"><span class="pre">ClientAssertion</span></code> (Default: <code class="docutils literal notranslate"><span class="pre">UsernamePassword</span></code>).</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">user</span></code> - str: The M365 user, required when the auth method is
 UsernamePassword</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">password</span></code> - str: The user password, required when the auth
@@ -339,6 +339,18 @@ including the private key. Required when the auth method is
 <code class="docutils literal notranslate"><span class="pre">Certificate</span></code></p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">certificate_password</span></code> - str: Optional password for the
 certificate file when using <code class="docutils literal notranslate"><span class="pre">Certificate</span></code> auth</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">client_assertion</span></code> - str: A signed JWT client assertion, required
+when the auth method is <code class="docutils literal notranslate"><span class="pre">ClientAssertion</span></code></p>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p><code class="docutils literal notranslate"><span class="pre">client_assertion</span></code> is a static value, so it is only usable for as
+long as the JWT it contains remains unexpired (assertions are
+typically short-lived, on the order of minutes). It is best suited
+to short one-shot runs; for long-running <code class="docutils literal notranslate"><span class="pre">watch</span></code> mode, prefer
+<code class="docutils literal notranslate"><span class="pre">Certificate</span></code> or <code class="docutils literal notranslate"><span class="pre">ClientSecret</span></code> auth, which can refresh
+indefinitely.</p>
+</div>
+</li>
 <li><p><code class="docutils literal notranslate"><span class="pre">tenant_id</span></code> - str: The Azure AD tenant ID. This is required
 for all auth methods except UsernamePassword.</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">mailbox</span></code> - str: The mailbox name. This defaults to the
@@ -359,6 +371,18 @@ admin grant the Microsoft Graph <code class="docutils literal notranslate"><span
 <code class="docutils literal notranslate"><span class="pre">UsernamePassword</span></code> auth and the mailbox is different from the
 username, you must grant the app <code class="docutils literal notranslate"><span class="pre">Mail.ReadWrite.Shared</span></code>.</p>
 </div>
+<div class="admonition tip">
+<p class="admonition-title">Tip</p>
+<p><strong>Troubleshooting connections.</strong> Run with <code class="docutils literal notranslate"><span class="pre">--verbose</span></code> to log a
+redacted connection summary (auth method, tenant, client ID,
+mailbox, Graph URL) before the connection attempt, and with
+<code class="docutils literal notranslate"><span class="pre">--debug</span></code> to additionally surface the underlying library activity —
+<code class="docutils literal notranslate"><span class="pre">azure.identity</span></code> token acquisition (including <code class="docutils literal notranslate"><span class="pre">AADSTS</span></code> error codes
+from Entra ID, which distinguish a local configuration problem from
+an Exchange Online-side one), Microsoft Graph SDK requests, and
+<code class="docutils literal notranslate"><span class="pre">httpx</span></code> HTTP request lines. Secret values (passwords, client
+secrets, certificate passwords) are never written to logs.</p>
+</div>
 <div class="admonition warning">
 <p class="admonition-title">Warning</p>
 <p>If you are using the <code class="docutils literal notranslate"><span class="pre">ClientSecret</span></code> auth method, you need to
@@ -375,7 +399,7 @@ group and use that as the group id.</p>
 </pre></div>
 </div>
 <p>The same application permission and mailbox scoping guidance
-applies to the <code class="docutils literal notranslate"><span class="pre">Certificate</span></code> auth method.</p>
+applies to the <code class="docutils literal notranslate"><span class="pre">Certificate</span></code> and <code class="docutils literal notranslate"><span class="pre">ClientAssertion</span></code> auth methods.</p>
 </div>
 </li>
 </ul>