python asciidocapi.py
asciidocapi — a Python API module for AsciiDoc.
The asciidocapi module implements a Python API for AsciiDoc. It allows you to set asciidoc(1) program options, compile an AsciiDoc source file and then interrogate the results. The asciidocapi.py module file contains the AsciiDocAPI wrapper class for asciidoc.py.
Stable API Shields the user from the undocumented and possibly volatile asciidoc.py internals.
Easier to use and more flexible than the alternative of running asciidoc(1) as a separate process.
Executes inside your application (better performance than running separate asciidoc(1) command processes).
To use the API just drop the asciidocapi.py file into your application directory, import it and use the AsciiDocAPI class. The only requirement is that a compatible version of AsciiDoc is already installed — simple, no setuptools to run, no Eggs to install, no non-standard library dependencies.
Verify everything is working by running the module doctests:
python asciidocapi.py
If there are no messages then all is well.
The following minimal example compiles mydoc.txt to mydoc.html:
from asciidocapi import AsciiDocAPI asciidoc = AsciiDocAPI() asciidoc.execute('mydoc.txt')
The next interactive example uses file-like objects for input and output:
>>> from asciidocapi import AsciiDocAPI >>> import StringIO >>> infile = StringIO.StringIO('Hello *{author}*') >>> outfile = StringIO.StringIO() >>> asciidoc = AsciiDocAPI() >>> asciidoc.options('--no-header-footer') >>> asciidoc.attributes['author'] = 'Joe Bloggs' >>> asciidoc.execute(infile, outfile, backend='html4') >>> print outfile.getvalue() <p>Hello <strong>Joe Bloggs</strong></p> >>>
The API maps directly onto the asciidoc(1) command — this is deliberate — if you know the asciidoc(1) command learning the API will be trivial. A nice side effect of this goal is that API and command-line modes share the same code — virtually no asciidoc(1) code is specific to API usage.
The AsciiDocAPI class contains just one method plus a few attributes for options and result messages.
The dependency between asciidocapi.py and asciidoc.py is minimal — the current asciidocapi.py module uses only two attributes and one function from the asciidoc.py module.
You can’t just drop asciidoc.py into your application because it requires all the related config files and filters — complex and unnecessary since all this was already done when you installed AsciiDoc.
This is the AsciiDoc API class.
The imported asciidoc.py module.
A dictionary of AsciiDoc attribute values.
The file path of the asciidoc.py script. Set by the __init__ method.
A chronologically ordered list of message strings generated during AsciiDoc execution (last message at the end of the list).
An instance of the Options class. Contains a list of AsciiDoc command options.
Locate and import asciidoc.py module and verify API compatibility. Initialize instance attributes. A search for the asciidoc module is made in the following order:
Use the ASCIIDOC_PY environment variable if it is set.
Use the asciidoc_py argument if it is set.
Search the environment PATH for asciidoc, asciidoc.py and asciidoc.pyc (in that order).
Finally look for asciidoc.py in the current working directory.
Compile infile to outfile using backend format. infile and outfile can be file path strings or file-like objects. backend is name of AsciiDoc backend (takes same values as asciidoc(1) command --backend option). If outfile or backend are None then their respective asciidoc(1) defaults are used.
Stores asciidoc(1) command options.
The list of (name,value) command option tuples.
A shortcut for the append method. Example:
options('--verbose')
Append (name,value) to the options list. Example:
options.append('--conf-file', 'blog.conf')
Thrown by the AsciiDocAPI class when an AsciiDoc execution error occurs.