Python runtime

Parsers generated for Python require the same version of the runtime as the ANTLR tool used. Right now the Python target is only functional up to v3.1.3, so you'll have to use that version of ANTLR and the runtime.

The python-antlr packages available with distributions like Ubuntu are not current. Install the appropriate runtime for your version of ANTLR using the instructions below.

Python runtime package

The runtime package for Python is called antlr3. The package is pure Python and does not have any dependencies to non-standard modules.

Installation

Download the "Complete ANTLR 3.x Java binaries jar" from the ANTLR download page, extract it, and run the Python installer.

On a Linux shell:

wget http://www.antlr.org/download/antlr-3.1.3.tar.gz
tar xzf antlr-3.1.3.tar.gz
cd antlr-3.1.3/runtime/Python
sudo python setup.py install

Check your installation by using the Python shell:

$ python
Python 2.6.5 (r265:79063, Apr 16 2010, 13:57:41)
[GCC 4.4.3] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import antlr3
>>>

Differences from Java runtime

The package structure tries to mimic the Java runtime as close as possible. Translating import statements from Java to Python should be straight forward:

Java	Python
import org.antlr.runtime.*; import org.antlr.runtime.tree.CommonTree;	from antlr3 import * from antlr3.tree import CommonTree

The only difference is that a number of static names, which are members of various Java classes, are defined in the module namespace:

Java	Python
`org.antlr.runtime.CharStream.EOF`	`antlr3.EOF`
`org.antlr.runtime.Token.EOF`	`antlr3.EOF`
`org.antlr.runtime.Token.EOF_TOKEN`	`antlr3.EOF_TOKEN`
`org.antlr.runtime.Token.INVALID_TOKEN_TYPE`	`antlr3.INVALID_TOKEN_TYPE`
`org.antlr.runtime.Token.INVALID_TOKEN`	`antlr3.INVALID_TOKEN`
`org.antlr.runtime.Token.SKIP_TOKEN`	`antlr3.SKIP_TOKEN`
`org.antlr.runtime.Token.DEFAULT_CHANNEL`	`antlr3.DEFAULT_CHANNEL`
`org.antlr.runtime.Token.HIDDEN_CHANNEL`	`antlr3.HIDDEN_CHANNEL`
`org.antlr.runtime.Token.EOR_TOKEN_TYPE`	`antlr3.EOR_TOKEN_TYPE`
`org.antlr.runtime.Token.DOWN`	`antlr3.DOWN`
`org.antlr.runtime.Token.UP`	`antlr3.UP`
`org.antlr.runtime.Token.MIN_TOKEN_TYPE`	`antlr3.MIN_TOKEN_TYPE`
`org.antlr.runtime.tree.Tree.INVALID_NODE`	`antlr3.tree.INVALID_NODE`

The API should be mostly identical to Java, with a few exceptions:

The CommonToken constructor has a different signature than the (overloaded) Java version. It is advised to call it always with keyword arguments to avoid confusion:
- CommonToken(type=None, channel=DEFAULT_CHANNEL, text=None, input=None, start=None, stop=None, oldToken=None)
The overloaded TreeAdaptor.create() is available, but should not be used directly. Instead you should use
- TreeAdaptor.createWithPayload(token)
- TreeAdaptor.createFromToken(typeType, fromToken, text=None)
- TreeAdaptor.createFromType(typeType, text)

There is also full API documentation available for the Python runtime.