asciidocapi — a Python API module for AsciiDoc.

Introduction

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.

Benefits

Using asciidocapi

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>

>>>

Implementation Goals

Leverage existing knowledge

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.

Simplicity

The AsciiDocAPI class contains just one method plus a few attributes for options and result messages.

Loose coupling

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.

Why isn’t the API baked right into the asciidoc.py command script?

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.

API reference

Class AsciiDocAPI(object)

This is the AsciiDoc API class.

Instance attributes

asciidoc

The imported asciidoc.py module.

attributes

A dictionary of AsciiDoc attribute values.

cmd

The file path of the asciidoc.py script. Set by the __init__ method.

messages

A chronologically ordered list of message strings generated during AsciiDoc execution (last message at the end of the list).

options

An instance of the Options class. Contains a list of AsciiDoc command options.

Instance methods

__init__(self, asciidoc_py=None)

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:

  1. Use the ASCIIDOC_PY environment variable if it is set.

  2. Use the asciidoc_py argument if it is set.

  3. Search the environment PATH for asciidoc, asciidoc.py and asciidoc.pyc (in that order).

  4. Finally look for asciidoc.py in the current working directory.

execute(self, infile, outfile=None, backend=None)

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.

Class Options(object)

Stores asciidoc(1) command options.

Instance attributes

values

The list of (name,value) command option tuples.

Instance methods

__call__(self, name, value=None)

A shortcut for the append method. Example:

options('--verbose')
append(self, name, value=None)

Append (name,value) to the options list. Example:

options.append('--conf-file', 'blog.conf')

Class AsciiDocError(Exception)

Thrown by the AsciiDocAPI class when an AsciiDoc execution error occurs.