python asciidocapi.py
»Home
»FAQ
»a2x
»API
|
AsciiDoc APITable of Contents
asciidocapi — a Python API module for AsciiDoc. IntroductionThe 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 asciidocapiTo 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 RationaleLeverage 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?
API referenceClass AsciiDocAPI(object)This is the AsciiDoc API class. Instance attributes
Instance methods
Class Options(object)Stores asciidoc(1) command options. Instance attributes
Instance methods
Class AsciiDocError(Exception)Thrown by the AsciiDocAPI class when an AsciiDoc execution error occurs. |