xhtmlhook is an import hook for the Python interpreter.
Version: 1.12xhtmlhook is an import hook for the Python interpreter which enables Python source embedded in XHTML documents to be imported in the same manner as for pure Python modules. Additionally, it is also able to fetch documents from remote locations if URLs are used instead of local paths in the sys.path list of module locations.
Operating System: Linux
The xhtmlhook import hook was written to allow Python source code to be included in XHTML documents using a particular class of preformatted text. The underlying mechanics of this includes modifications to the mechanism that the Python interpreter uses to import modules through the ihooks module and use of the xml.dom.minidom module to obtain the code included within documents. Modules can now be written, with some effort, in a web browser which supports editing, although a method for enabling Python to run such code as scripts is not yet in place.
The authors appreciate good documentation when they encounter it. However, it is often necessary to rely on documentation generated from comments included in source code. Despite claims that, "The source code is the documentation," by proponents of various software engineering methodologies and language evangelists, such generated documentation often only provides cursory descriptions of the interfaces exposed by libraries and other resources. Learning how to use such resources often requires the developer to inspect the source code itself before tentatively trying various approaches to use within an interactive session.
We decided that we would like to see better documented code included within web pages for convenient browsing. The motivation behind this peculiar aim is to be able to include high quality documentation alongside working code, hopefully making it easier for programmers to produce more maintainable, readable programs. With easy-to-use editing facilities included with web browsers such as Amaya this aim is within reach.
There are a number of steps required to enable the Python interpreter to import code embedded within webpages:
1. The file extension used for such documents needs to be registered so that the general methods for determining the types of file which can contain source code will include this type of file. Therefore, ".html" will be included as a recognised suffix for source code rather than any other type of Python code, such as bytecode, for example.
This is achieved by subclassing the Hooks class in the ihooks module.
2. Although the method used to search for modules on a given path will not need to be modified in order to support the importing of source code in XHTML files, the use of Uniform Resource Locators (URLs) in the paths to be searched requires that the need to be modified in some way so that such files are located using the urlopen function from the urllib2 module.
This is achieved by subclassing the ModuleLoader class in the ihooks module and reimplementing the find_module method. If URL support is omitted, the find_module class need not be reimplemented.
3. The XHTML documents need to be intercepted before their contents are compiled to bytecode by the interpreter and the included code converted to a suitable form. The approach taken should not affect the import of existing file types. Support for remote modules must be included where appropriate.
This is achieved by subclassing the load_module method in the ModuleLoader class in the ihooks module. Although attempts are made to minimise disruption to the import process used by the base class, it is necessary to override the import process both for the case of XHTML documents (locally and remotely stored) and for all file types when remotely stored.
4. The subclasses must be instantiated and registered through with a subclass of the ModuleImporter class from the ihooks module. This subclass modifies the behaviour of the import_it method to treat XHTML documents as packages when they contain multiple submodules. This instance itself is registered with the import hooks mechanism through a call to its install method.
The following section presents the source code used to implement the module, including comments and docstrings where appropriate. This code is used by the xhtml2py.py script to generate the module when the setup.py script is run; the functions used to extract the Python source code are taken from methods of the subclassed ModuleLoader class. Hence, the module can import itself in its original form.
What's New in This Release:
· Made changes suggested by Kirby Angell to fix module imports within remote packages.