177 lines
8.3 KiB
HTML
177 lines
8.3 KiB
HTML
<!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 it 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> |