# AsciiDoc API

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.

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.