AsciiDoc API

AsciiDoc
Text based document generation

»Home »Man Page »User Guide »a2x »API »Cheatsheet »README »ChangeLog »Installation »Downloads »FAQ »Tests »Support »Page Source | # 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. 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? 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 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: 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.py`, `asciidoc.pyc` and `asciidoc` (in that order). 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. #### 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.