Metadata-Version: 2.1
Name: send-the-raven
Version: 0.1.0
Summary: A collection of toolkit and algorithms for handling US addresses
Author: Bang Koboi
Author-email: TheManHimself@jimmyganteng.com
Requires-Python: >=3.10,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Dist: aiohttp (>=3.8.5,<4.0.0)
Requires-Dist: asyncio (>=3.4.3,<4.0.0)
Requires-Dist: geopy (>=2.4.0,<3.0.0)
Requires-Dist: h3 (>=3.7.6,<4.0.0)
Requires-Dist: pydantic (>=2.3.0,<3.0.0)
Requires-Dist: usaddress-scourgify (>=0.5.1,<0.6.0)
Requires-Dist: xmltodict (>=0.13.0,<0.14.0)
Description-Content-Type: text/markdown



<!DOCTYPE html>


<html lang="en" >

  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
    <link rel="icon" href="_static/favicon.ico" type="image/x-icon">
    <link rel="icon" sizes="16x16" href="_static/favicon-16x16.png" type="image/png">
    <link rel="icon" sizes="32x32" href="_static/favicon-32x32.png" type="image/png">
    <link rel="icon" sizes="192x192" href="_static/favicon-192x192.png" type="image/png">
    <link rel="icon" sizes="512x512" href="_static/favicon-512x512.png" type="image/png">
    <link rel="apple-touch-icon" href="_static/apple-touch-icon.png" type="image/png" sizes="180x180">
    <title>Send The Raven &#8212; Send The Raven</title>
  
  
  
  <script data-cfasync="false">
    document.documentElement.dataset.mode = localStorage.getItem("mode") || "";
    document.documentElement.dataset.theme = localStorage.getItem("theme") || "light";
  </script>
  
  <!-- Loaded before other Sphinx assets -->
  <link href="_static/styles/theme.css?digest=927b94d3fcb96560df09" rel="stylesheet" />
<link href="_static/styles/bootstrap.css?digest=927b94d3fcb96560df09" rel="stylesheet" />
<link href="_static/styles/pydata-sphinx-theme.css?digest=927b94d3fcb96560df09" rel="stylesheet" />

  
  <link href="_static/vendor/fontawesome/6.1.2/css/all.min.css?digest=927b94d3fcb96560df09" rel="stylesheet" />
  <link rel="preload" as="font" type="font/woff2" crossorigin href="_static/vendor/fontawesome/6.1.2/webfonts/fa-solid-900.woff2" />
<link rel="preload" as="font" type="font/woff2" crossorigin href="_static/vendor/fontawesome/6.1.2/webfonts/fa-brands-400.woff2" />
<link rel="preload" as="font" type="font/woff2" crossorigin href="_static/vendor/fontawesome/6.1.2/webfonts/fa-regular-400.woff2" />

    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
    <link rel="stylesheet" href="_static/styles/sphinx-book-theme.css?digest=14f4ca6b54d191a8c7657f6c759bf11a5fb86285" type="text/css" />
  
  <!-- Pre-loaded scripts that we'll load fully later -->
  <link rel="preload" as="script" href="_static/scripts/bootstrap.js?digest=927b94d3fcb96560df09" />
<link rel="preload" as="script" href="_static/scripts/pydata-sphinx-theme.js?digest=927b94d3fcb96560df09" />
  <script src="_static/vendor/fontawesome/6.1.2/js/all.min.js?digest=927b94d3fcb96560df09"></script>

    <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
    <script src="_static/doctools.js"></script>
    <script src="_static/sphinx_highlight.js"></script>
    <script src="_static/scripts/sphinx-book-theme.js?digest=5a5c038af52cf7bc1a1ec88eea08e6366ee68824"></script>
    <script>DOCUMENTATION_OPTIONS.pagename = 'index';</script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Examples" href="example.html" />
  <meta name="viewport" content="width=device-width, initial-scale=1"/>
  <meta name="docsearch:language" content="en"/>
  </head>
  
  
  <body data-bs-spy="scroll" data-bs-target=".bd-toc-nav" data-offset="180" data-bs-root-margin="0px 0px -60%" data-default-mode="">

  
  
  <a class="skip-link" href="#main-content">Skip to main content</a>
  
  <div id="pst-scroll-pixel-helper"></div>

  
  <button type="button" class="btn rounded-pill" id="pst-back-to-top">
    <i class="fa-solid fa-arrow-up"></i>
    Back to top
  </button>

  
  <input type="checkbox"
          class="sidebar-toggle"
          name="__primary"
          id="__primary"/>
  <label class="overlay overlay-primary" for="__primary"></label>
  
  <input type="checkbox"
          class="sidebar-toggle"
          name="__secondary"
          id="__secondary"/>
  <label class="overlay overlay-secondary" for="__secondary"></label>
  
  <div class="search-button__wrapper">
    <div class="search-button__overlay"></div>
    <div class="search-button__search-container">
<form class="bd-search d-flex align-items-center"
      action="search.html"
      method="get">
  <i class="fa-solid fa-magnifying-glass"></i>
  <input type="search"
         class="form-control"
         name="q"
         id="search-input"
         placeholder="Search..."
         aria-label="Search..."
         autocomplete="off"
         autocorrect="off"
         autocapitalize="off"
         spellcheck="false"/>
  <span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd>K</kbd></span>
</form></div>
  </div>
  
    <nav class="bd-header navbar navbar-expand-lg bd-navbar">
    </nav>
  
  <div class="bd-container">
    <div class="bd-container__inner bd-page-width">
      
      <div class="bd-sidebar-primary bd-sidebar">
        

  
  <div class="sidebar-header-items sidebar-primary__section">
    
    
    
    
  </div>
  
    <div class="sidebar-primary-items__start sidebar-primary__section">
        <div class="sidebar-primary-item">
  

<a class="navbar-brand logo" href="#">
  
  
  
  
    
    
      
    
    
    <img src="_static/android-chrome-512x512.png" class="logo__image only-light" alt="Logo image"/>
    <script>document.write(`<img src="_static/android-chrome-512x512.png" class="logo__image only-dark" alt="Logo image"/>`);</script>
  
  
</a></div>
        <div class="sidebar-primary-item"><nav class="bd-links" id="bd-docs-nav" aria-label="Main">
    <div class="bd-toc-item navbar-nav active">
        <ul class="current nav bd-sidenav">
<li class="toctree-l1 current active"><a class="current reference internal" href="#">Get Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="example.html">Examples</a></li>
<li class="toctree-l1 has-children"><a class="reference internal" href="api.html">API Reference</a><input class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-1"><i class="fa-solid fa-chevron-down"></i></label><ul>
<li class="toctree-l2 has-children"><a class="reference internal" href="_autosummary/send_the_raven.address.html">send_the_raven.address</a><input class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-2"><i class="fa-solid fa-chevron-down"></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="_autosummary/send_the_raven.address.compare.html">send_the_raven.address.compare</a></li>
<li class="toctree-l3"><a class="reference internal" href="_autosummary/send_the_raven.address.Address.html">send_the_raven.address.Address</a></li>
<li class="toctree-l3"><a class="reference internal" href="_autosummary/send_the_raven.address.Addresses.html">send_the_raven.address.Addresses</a></li>
<li class="toctree-l3"><a class="reference internal" href="_autosummary/send_the_raven.address.Placemapper.html">send_the_raven.address.Placemapper</a></li>
</ul>
</li>
<li class="toctree-l2 has-children"><a class="reference internal" href="_autosummary/send_the_raven.geoaddress.html">send_the_raven.geoaddress</a><input class="toctree-checkbox" id="toctree-checkbox-3" name="toctree-checkbox-3" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-3"><i class="fa-solid fa-chevron-down"></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="_autosummary/send_the_raven.geoaddress.GeoAddress.html">send_the_raven.geoaddress.GeoAddress</a></li>
<li class="toctree-l3"><a class="reference internal" href="_autosummary/send_the_raven.geoaddress.Geocoder.html">send_the_raven.geoaddress.Geocoder</a></li>
</ul>
</li>
<li class="toctree-l2 has-children"><a class="reference internal" href="_autosummary/send_the_raven.validator.html">send_the_raven.validator</a><input class="toctree-checkbox" id="toctree-checkbox-4" name="toctree-checkbox-4" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-4"><i class="fa-solid fa-chevron-down"></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="_autosummary/send_the_raven.validator.Validator.html">send_the_raven.validator.Validator</a></li>
</ul>
</li>
<li class="toctree-l2 has-children"><a class="reference internal" href="_autosummary/send_the_raven.utils.html">send_the_raven.utils</a><input class="toctree-checkbox" id="toctree-checkbox-5" name="toctree-checkbox-5" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-5"><i class="fa-solid fa-chevron-down"></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="_autosummary/send_the_raven.utils.generate_id.html">send_the_raven.utils.generate_id</a></li>
<li class="toctree-l3"><a class="reference internal" href="_autosummary/send_the_raven.utils.split_into_n_elements.html">send_the_raven.utils.split_into_n_elements</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="contribute.html">Contributing</a></li>
</ul>

    </div>
</nav></div>
    </div>
  
  
  <div class="sidebar-primary-items__end sidebar-primary__section">
  </div>
  
  <div id="rtd-footer-container"></div>


      </div>
      
      <main id="main-content" class="bd-main">
        
        

<div class="sbt-scroll-pixel-helper"></div>

          <div class="bd-content">
            <div class="bd-article-container">
              
              <div class="bd-header-article">
<div class="header-article-items header-article__inner">
  
    <div class="header-article-items__start">
      
        <div class="header-article-item"><label class="sidebar-toggle primary-toggle btn btn-sm" for="__primary" title="Toggle primary sidebar" data-bs-placement="bottom" data-bs-toggle="tooltip">
  <span class="fa-solid fa-bars"></span>
</label></div>
      
    </div>
  
  
    <div class="header-article-items__end">
      
        <div class="header-article-item">

<div class="article-header-buttons">





<div class="dropdown dropdown-download-buttons">
  <button class="btn dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false" aria-label="Download this page">
    <i class="fas fa-download"></i>
  </button>
  <ul class="dropdown-menu">
      
      
      
      <li><a href="_sources/index.rst" target="_blank"
   class="btn btn-sm btn-download-source-button dropdown-item"
   title="Download source file"
   data-bs-placement="left" data-bs-toggle="tooltip"
>
  

<span class="btn__icon-container">
  <i class="fas fa-file"></i>
  </span>
<span class="btn__text-container">.rst</span>
</a>
</li>
      
      
      
      
      <li>
<button onclick="window.print()"
  class="btn btn-sm btn-download-pdf-button dropdown-item"
  title="Print to PDF"
  data-bs-placement="left" data-bs-toggle="tooltip"
>
  

<span class="btn__icon-container">
  <i class="fas fa-file-pdf"></i>
  </span>
<span class="btn__text-container">.pdf</span>
</button>
</li>
      
  </ul>
</div>




<button onclick="toggleFullScreen()"
  class="btn btn-sm btn-fullscreen-button"
  title="Fullscreen mode"
  data-bs-placement="bottom" data-bs-toggle="tooltip"
>
  

<span class="btn__icon-container">
  <i class="fas fa-expand"></i>
  </span>

</button>


<script>
document.write(`
  <button class="btn btn-sm navbar-btn theme-switch-button" title="light/dark" aria-label="light/dark" data-bs-placement="bottom" data-bs-toggle="tooltip">
    <span class="theme-switch nav-link" data-mode="light"><i class="fa-solid fa-sun fa-lg"></i></span>
    <span class="theme-switch nav-link" data-mode="dark"><i class="fa-solid fa-moon fa-lg"></i></span>
    <span class="theme-switch nav-link" data-mode="auto"><i class="fa-solid fa-circle-half-stroke fa-lg"></i></span>
  </button>
`);
</script>

<script>
document.write(`
  <button class="btn btn-sm navbar-btn search-button search-button__button" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip">
    <i class="fa-solid fa-magnifying-glass fa-lg"></i>
  </button>
`);
</script>
<label class="sidebar-toggle secondary-toggle btn btn-sm" for="__secondary"title="Toggle secondary sidebar" data-bs-placement="bottom" data-bs-toggle="tooltip">
    <span class="fa-solid fa-list"></span>
</label>
</div></div>
      
    </div>
  
</div>
</div>
              
              

<div id="jb-print-docs-body" class="onlyprint">
    <h1>Send The Raven</h1>
    <!-- Table of contents -->
    <div id="print-main-content">
        <div id="jb-print-toc">
            
            <div>
                <h2> Contents </h2>
            </div>
            <nav aria-label="Page">
                <ul class="visible nav section-nav flex-column">
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#features">Features</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#installation">Installation</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#usage">Usage</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#acknowledgments">Acknowledgments</a></li>
</ul>
            </nav>
        </div>
    </div>
</div>

              
                
<div id="searchbox"></div>
                <article class="bd-article" role="main">
                  
  <section id="send-the-raven">
<h1>Send The Raven<a class="headerlink" href="#send-the-raven" title="Permalink to this heading">#</a></h1>
<p>Send the Raven is a Python library that provides a comprehensive collection of toolkits and algorithms for handling US addresses. It aims to simplify the process of working with US addresses, offering functionalities such as parsing, validation, formatting, and more.</p>
<img alt="Game of Thrones Send the Ravens GIF" class="align-center" src="_images/d782276f-b708-4c7d-a077-5354d19f06fe.gif" />
<section id="features">
<h2>Features<a class="headerlink" href="#features" title="Permalink to this heading">#</a></h2>
<ul class="simple">
<li><p><strong>Address Parsing</strong>: Extract structured information from US addresses, including street names, house numbers, city, state, and ZIP codes.</p></li>
<li><p><strong>Address Validation</strong>: Validate US addresses to ensure accuracy and compliance with USPS standards.</p></li>
<li><p><strong>Address Formatting</strong>: Format US addresses in a consistent and standardized manner for various purposes.</p></li>
<li><p><strong>Additional Utilities</strong>: Additional utilities to enhance address handling, such as address comparison, address normalization, and more.</p></li>
</ul>
</section>
<section id="installation">
<h2>Installation<a class="headerlink" href="#installation" title="Permalink to this heading">#</a></h2>
<p>send_the_raven can be installed from PyPI:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>pip<span class="w"> </span>install<span class="w"> </span>send_the_raven
</pre></div>
</div>
</section>
<section id="usage">
<h2>Usage<a class="headerlink" href="#usage" title="Permalink to this heading">#</a></h2>
<p>Here is a quick example of using send_the_raven to validate addresses:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">send_the_raven</span> <span class="kn">import</span> <span class="n">Validator</span>

<span class="n">addresses</span> <span class="o">=</span> <span class="p">[</span>
   <span class="p">{</span><span class="s2">&quot;street&quot;</span><span class="p">:</span> <span class="s2">&quot;123 Main St&quot;</span><span class="p">,</span> <span class="s2">&quot;city&quot;</span><span class="p">:</span> <span class="s2">&quot;Anytown&quot;</span><span class="p">,</span> <span class="s2">&quot;state&quot;</span><span class="p">:</span> <span class="s2">&quot;CA&quot;</span><span class="p">,</span> <span class="s2">&quot;zip_code&quot;</span><span class="p">:</span> <span class="s2">&quot;12345&quot;</span><span class="p">},</span>
   <span class="p">{</span><span class="s2">&quot;street&quot;</span><span class="p">:</span> <span class="s2">&quot;456 Oak Rd&quot;</span><span class="p">,</span> <span class="s2">&quot;city&quot;</span><span class="p">:</span> <span class="s2">&quot;Forest&quot;</span><span class="p">,</span> <span class="s2">&quot;state&quot;</span><span class="p">:</span> <span class="s2">&quot;VT&quot;</span><span class="p">,</span> <span class="s2">&quot;zip_code&quot;</span><span class="p">:</span> <span class="s2">&quot;67890&quot;</span><span class="p">}</span>
<span class="p">]</span>

<span class="n">validator</span> <span class="o">=</span> <span class="n">Validator</span><span class="p">(</span><span class="n">addresses</span><span class="p">,</span> <span class="n">usps_id</span><span class="o">=</span><span class="s2">&quot;MY_ID&quot;</span><span class="p">)</span>
<span class="n">valid_addresses</span> <span class="o">=</span> <span class="n">validator</span><span class="p">()</span>
</pre></div>
</div>
<p>send_the_raven handles parsing the address data, constructing the validation requests, and returning the corrected addresses.</p>
<p>The <a class="reference internal" href="_autosummary/send_the_raven.address.Address.html#send_the_raven.address.Address" title="send_the_raven.address.Address"><code class="xref py py-class docutils literal notranslate"><span class="pre">Address</span></code></a> class also provides methods for normalizing, geocoding, and working with addresses.</p>
</section>
<section id="acknowledgments">
<h2>Acknowledgments<a class="headerlink" href="#acknowledgments" title="Permalink to this heading">#</a></h2>
<p>send_the_raven uses the following open source libraries:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://github.com/GreenBuildingRegistry/usaddress-scourgify">usaddress-scourgify</a> for parsing addresses.</p></li>
<li><p><a class="reference external" href="https://github.com/martinblech/xmltodict">xmltodict</a> for working with XML.</p></li>
<li><p><a class="reference external" href="https://github.com/aio-libs/aiohttp">aiohttp</a> for asynchronous HTTP requests.</p></li>
<li><p><a class="reference external" href="https://github.com/geopy/geopy">geopy</a> for geocoding.</p></li>
<li><p><a class="reference external" href="https://github.com/uber/h3-py">h3-py</a> for geospatial indexing.</p></li>
</ul>
<p>We thank the developers of these libraries for their contributions.</p>
<div class="toctree-wrapper compound">
</div>
</section>
</section>


                </article>
              

              
              
              
              
                <footer class="prev-next-footer">
                  <!-- Previous / next buttons -->
<div class="prev-next-area">
    <a class="right-next"
       href="example.html"
       title="next page">
      <div class="prev-next-info">
        <p class="prev-next-subtitle">next</p>
        <p class="prev-next-title">Examples</p>
      </div>
      <i class="fa-solid fa-angle-right"></i>
    </a>
</div>
                </footer>
              
            </div>
            
            
              
                <div class="bd-sidebar-secondary bd-toc"><div class="sidebar-secondary-items sidebar-secondary__inner">

  <div class="sidebar-secondary-item">
  <div class="page-toc tocsection onthispage">
    <i class="fa-solid fa-list"></i> Contents
  </div>
  <nav class="bd-toc-nav page-toc">
    <ul class="visible nav section-nav flex-column">
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#features">Features</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#installation">Installation</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#usage">Usage</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#acknowledgments">Acknowledgments</a></li>
</ul>
  </nav></div>

</div></div>
              
            
          </div>
          <footer class="bd-footer-content">
            
<div class="bd-footer-content__inner container">
  
  <div class="footer-item">
    
<p class="component-author">
By Jimmy Hikmatullah
</p>

  </div>
  
  <div class="footer-item">
    
  <p class="copyright">
    
      © Copyright 2023, Jimmy Hikmatullah.
      <br/>
    
  </p>

  </div>
  
  <div class="footer-item">
    
  </div>
  
  <div class="footer-item">
    
  </div>
  
</div>
          </footer>
        

      </main>
    </div>
  </div>
  
  <!-- Scripts loaded after <body> so the DOM is not blocked -->
  <script src="_static/scripts/bootstrap.js?digest=927b94d3fcb96560df09"></script>
<script src="_static/scripts/pydata-sphinx-theme.js?digest=927b94d3fcb96560df09"></script>

  <footer class="bd-footer">
  </footer>
  </body>
</html>
