»Home
»User Guide
»Installation
»FAQ
»asciidoc(1)
»a2x(1)
»API
»Plugins
»Cheatsheet
»Tests
»ChangeLog
»Support
»Page Source
AsciiDoc
Text based document generation

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

  • 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).

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.

You can find asciidocapi.py in the AsciiDoc distribution archives (version 8.4.1 or better).

Once you have asciidocapi.py 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:

$ python
Python 2.5.2 (r252:60911, Jul 31 2008, 17:28:52)
[GCC 4.2.3 (Ubuntu 4.2.3-2ubuntu7)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> 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 Rationale

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

Implemented with a single Python module file (asciidocapi.py) containing the AsciiDocAPI API class. AsciiDocAPI contains just one method plus a few attributes for processing options and result messages. No external setup tools and no non-standard library dependencies are used or required.

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?

  1. 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.

  2. This scheme separates the API from the AsciiDoc application — the API implementation can be extended or replaced independently of 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 passed to AsciiDoc.

  • Setting an attribute value to None (name: None) will undefine (delete) the attribute (this in addition to the name! attribute name format that the asciidoc(1) command uses).

  • To simply define an attribute set the attribute value to a blank string (name: '')

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 command options passed to AsciiDoc.

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.py, asciidoc.pyc and asciidoc (in that order).

  4. Finally repeat the previous search 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. You can use any asciidoc(1) options with the exception of the --doctest and --filter 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: 

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

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

opts = Options()
opts.append('--conf-file', 'blog.conf')

Class AsciiDocError(Exception)

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