<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Synopsis — polyloader 0.1.0 documentation</title>
<link rel="stylesheet" href="default.css" type="text/css" />
<link rel="stylesheet" href="pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '0.1.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="underscore.js"></script>
<script type="text/javascript" src="doctools.js"></script>
<link rel="top" title="polyloader 0.1.0 documentation" href="index.html" />
<link rel="next" title="Installation" href="installation.html" />
<link rel="prev" title="Welcome to polyloader" href="index.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="installation.html" title="Installation"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="index.html" title="Welcome to polyloader"
accesskey="P">previous</a> |</li>
<li><a href="index.html">polyloader 0.1.0 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="synopsis">
<h1>Synopsis<a class="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>
<div class="section" id="say-what-in-english-this-time">
<h1>Say What? In English this time<a class="headerlink" href="#say-what-in-english-this-time" title="Permalink to this headline">¶</a></h1>
<p>The <tt class="docutils literal"><span class="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 <tt class="docutils literal"><span class="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>
<ol class="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 both via <tt class="docutils literal"><span class="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>
<div class="section" id="what-s-the-real-problem">
<h1>What’s the real problem?<a class="headerlink" href="#what-s-the-real-problem" title="Permalink to this headline">¶</a></h1>
<p>The real problem is that Python’s traditional extensions, <tt class="docutils literal"><span class="pre">.py</span></tt>,
<tt class="docutils literal"><span class="pre">.pyc/.pyo</span></tt>, and <tt class="docutils literal"><span class="pre">.so/.dll</span></tt> files, are hard-coded in Python. In
Python 2, they’re in the <tt class="docutils literal"><span class="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 <tt class="docutils literal"><span class="pre">pkglib</span></tt> module, which is part of
Python’s standard library. This module uses <tt class="docutils literal"><span class="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>
<div class="section" id="what-the-solution">
<h1>What the solution?<a class="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 <tt class="docutils literal"><span class="pre">polyloader</span></tt> does.</p>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Synopsis</a></li>
<li><a class="reference internal" href="#say-what-in-english-this-time">Say What? In English this time</a></li>
<li><a class="reference internal" href="#what-s-the-real-problem">What’s the real problem?</a></li>
<li><a class="reference internal" href="#what-the-solution">What the solution?</a></li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="index.html"
title="previous chapter">Welcome to polyloader</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="installation.html"
title="next chapter">Installation</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/readme.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="installation.html" title="Installation"
>next</a> |</li>
<li class="right" >
<a href="index.html" title="Welcome to polyloader"
>previous</a> |</li>
<li><a href="index.html">polyloader 0.1.0 documentation</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2016, Kenneth M. "Elf" Sternberg.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
</div>
</body>
</html>
Elf M. Sternberg
39e93c354f
