<h1>Synopsis<aclass="headerlink"href="#synopsis"title="Permalink to this headline">¶</a></h1>
<p><strong>Polyloader</strong> is a python module that extends the Python <cite>import</cite>
statement to enable the discovery and loading of heterogenous source
code packages.</p>
</div>
<divclass="section"id="say-what">
<h1>Say What?<aclass="headerlink"href="#say-what"title="Permalink to this headline">¶</a></h1>
<p>The <ttclass="docutils literal"><spanclass="pre">import</span></tt> statement is how the Python interpreter finds a module
written in Python and loads it, turning it into variables, executable
functions, constructable classes, and other Python objects, and then
exposes those objects to the currently running program.</p>
<p>The <ttclass="docutils literal"><spanclass="pre">import</span></tt> statement has long been extensible so that things other
than Python code could be imported, but this feature has always had two
limitations:</p>
<olclass="arabic simple">
<li>It’s annoyingly hard to write an importer. (Believe me. Polyloader
<em>is</em> one!)</li>
<li>For filesystem-based modules (which is 99% of them) Python’s importer
only understands one loader type per directory. It’s not possible to
store code or data written in something other than Python in the same
directory with Python module code and load it via <ttclass="docutils literal"><spanclass="pre">import</span></tt>.</li>
</ol>
<p>The former requires a certain degree of abstraction and thought. For
the latter, most people ignore the problem and load module configuration
files written in JSON or YAML or whatever directly. This is fine,
except when you want to write in one of Python’s extended languages like
Hy or Coconut in a framework like Django, Flask or Glitch.</p>
<p><strong>Polyloader</strong> eliminates these limitations.</p>
</div>
<divclass="section"id="what-s-the-real-problem">
<h1>What’s the real problem?<aclass="headerlink"href="#what-s-the-real-problem"title="Permalink to this headline">¶</a></h1>
<p>The real problem is that Python’s traditional extensions, <ttclass="docutils literal"><spanclass="pre">.py</span></tt>,
<ttclass="docutils literal"><spanclass="pre">.pyc/.pyo</span></tt>, and <ttclass="docutils literal"><spanclass="pre">.so/.dll</span></tt> files, are hard-coded in Python. In
Python 2, they’re in the <ttclass="docutils literal"><spanclass="pre">imp</span></tt> builtin; In Python 3, they’re defined
in a private section of <cite>importlib</cite>. Either way, they’re not accessible
for modification and extension.</p>
<p>This problem is made harder by the <ttclass="docutils literal"><spanclass="pre">pkglib</span></tt> module, which is part of
Python’s standard library. This module uses <ttclass="docutils literal"><spanclass="pre">inspect.getmoduleinfo</span></tt>,
which again only recognizes the usual extensions. Which means you can’t
list multilingual modules either; this hampers the development of Django
management commands in a syntax other than Python.</p>
</div>
<divclass="section"id="what-the-solution">
<h1>What the solution?<aclass="headerlink"href="#what-the-solution"title="Permalink to this headline">¶</a></h1>
<p>At its heart, the Python import system runs two different internal
mechanisms to figure out what the <em>import string</em> (the dotted terms
after the word “import”) “means.” Each mechanism has one or more
<em>finders</em>, and the first finder to report “I have a <em>loader</em> that knows
what that import string means” wins.</p>
<p>The very last finder is for the filesystem. The solution is to get in
front of that finder with one that can handle all the other syntax
loaders <em>and</em> knows how to fall back on the last one for those files the
last one handles.</p>
<p>That’s what <ttclass="docutils literal"><spanclass="pre">polyloader</span></tt> does.</p>
