Return to index

Module rstdoc.rstlib.astwriter


Module astwriter

Generate Python source from AbstractSyntaxTrees generated by the compiler.

Imports:
cStringIO, compiler, types, unittest
Classes:
SourceWriter(object): Walk with me to generate source:
Methods:
fileToString(name): I convert a source file to a source string by creating an ast tree and then applying nodeToString.
getSignature(node): I return the argument signature for node which must be a Function or Lambda node.
nodeToString(ast): I convert an ast tree to source.
sourceToString(source): I convert a source string to a source string by creating an ast tree and then applying nodeToString.
testSuite():

Class astwriter.SourceWriter

Back to astwriter

Bases:
object

Walk with me to generate source:

>>> source = "1+2"
>>> ast = parse(source)
>>> print walk(ast, SourceWriter())
1 + 2
<BLANKLINE>

Normally this class is not used directly, use the fileToString, nodeToString, or sourceToString methods instead.

Methods:
__getattr__(self, attr): Called if a node handler is not found.
__init__(self): Creates a SourceWriter instance.
__str__(self): Converts the node to a string. Doing this to a Module node will write all of the source code for a module.
dedent(self): Decrease the indentation level.
indent(self): Increase the indentation level.
joinNodes(self, join, nodeSeq, nodeWriter=None): I act like string.join(seq) except seq is a list of nodes, and the results are written to the internal buffer and not returned by this function.
nl(self): Write a newline to the internal buffer and then indent to the current indentation level.
visitAdd(self, node): Binary addition, i.e. "+".
visitAnd(self, node): Called for logical and operations. Note that a series of and's will result in only one to this method.
visitAssAttr(self, node): Assign expression to an attribute.
visitAssList(self, node): Assign expression to a list.
visitAssName(self, node): Assign expression to a variable.
visitAssTuple(self, node): Assign expression to a tuple.
visitAssert(self, node): The assert statement.
visitAssign(self, node): Called for each assignment. Note that a statement like a = b = None will result in one call to this method.
visitAugAssign(self, node): Called for operations like x += 5 and x -= 1.
visitBackquote(self, node): Called when the backquote character is used.
visitBitand(self, node): Called for bitwise 'and' operations. Note that a series of "&"'s will result in only one call to this method.
visitBitor(self, node): Called for bitwise 'or' operations. Note that a series of "|"'s will result in only one call to this method.
visitBitxor(self, node): Called for bitwise 'xor' operations. Note that a series of "^"'s will result in only one call to this method.
visitBreak(self, node): Called for a break statement.
visitCallFunc(self, node): Called for a function call.
visitClass(self, node): Called for a class definition.
visitCompare(self, node): Called for each comparison operation.
visitConst(self, node): Called for constants.
visitContinue(self, node): Called for the continue statement.
visitDecorators(self, node): Called for function decorators. Note if multiple decorators are applied to a function, this method is called only once.
visitDict(self, node): Called for a literal dictionary definition (i.e. { a : b, c : d })
visitDiscard(self, node): This is called when the results of an expression are discarded.
visitDiv(self, node): Called for each division operation.
visitEllipsis(self, node): I don't know why I would want it but...
visitExec(self, node): Called for the exec statement.
visitFloorDiv(self, node): Called for floor division.
visitFor(self, node): Called for a for statement.
visitFrom(self, node): Called for a from (import) statement.
visitFunction(self, node): Called for each function definition.
visitGetattr(self, node): Called for attribute access.
visitGlobal(self, node): Called for the global statement.
visitIf(self, node): Called for the if statement. Also handles the elif and else clauses.
visitImport(self, node): Called for the import statement.
visitInvert(self, node): Called for bitwise inversion.
visitKeyword(self, node): Called for a keyword argument.
visitLambda(self, node): Called for a lambda statement.
visitLeftShift(self, node): Called for bitwise shift-left.
visitList(self, node): Called for a literal list.
visitListComp(self, node): Called for a list comprehension.
visitListCompFor(self, node): Hmmm, if expr1 if expr2 is valid syntax (at least in 2.4.2.)
visitListCompIf(self, node): Used for the if part of a list comprehension.
visitMod(self, node): Called for modulus division.
visitModule(self, node): This allways gets visited first.
visitMul(self, node): Called for the multiplication operation.
visitName(self, node): Called for variable access.
visitNot(self, node): Called for logical not.
visitOr(self, node): Called for logical or. Note that multiple or's result in one call to this method.
visitPass(self, node): Called for the pass statement.
visitPower(self, node): Called for exponation oerations.
visitPrint(self, node): Called for a print statement without a trailing linefeed.
visitPrintnl(self, node): Called for a print statement with a trailing linefeed.
visitRaise(self, node): Called for the raise statement.
visitReturn(self, node): Called for the return statement.
visitRightShift(self, node): Called for bitwise shift right.
visitSliceobj(self, node): Called for sequence slice operations.
visitStmt(self, node): Called for each statement.
visitSub(self, node): Called for each subtraction operation.
visitSubscript(self, node): Called for a subscript (not a slice).
visitTryExcept(self, node): Called for a try/except block.
visitTryFinally(self, node): Called for a try/finally block.
visitTuple(self, node): Called for each tuple.
visitUnaryAdd(self, node): Called for unary "+".
visitUnarySub(self, node): Called for unary "-".
visitWhile(self, node): Called for the while statement.
visitYield(self, node): Called for a yield statement.
w(self, s): Write to internal buffer.
writeDoc(self, docString): I write the source for a docstring to the internal buffer.
Attributes:
_i = 0

Method astwriter.SourceWriter.__getattr__

Back to astwriter.SourceWriter

Arguments:
self, attr

Called if a node handler is not found.

Methods:
w(node, attr):

Method astwriter.SourceWriter.joinNodes

Back to astwriter.SourceWriter

Arguments:
self, join, nodeSeq, nodeWriter=None

I act like string.join(seq) except seq is a list of nodes, and the results are written to the internal buffer and not returned by this function.

Methods:
nodeWriter(node):

Method astwriter.SourceWriter.visitAdd

Back to astwriter.SourceWriter

Arguments:
self, node

Binary addition, i.e. "+".

>>> print sourceToString("1+2")
1 + 2
<BLANKLINE>

Method astwriter.SourceWriter.visitAnd

Back to astwriter.SourceWriter

Arguments:
self, node

Called for logical and operations. Note that a series of and's will result in only one to this method.

>>> print sourceToString("1 and 2 and 3")
1 and 2 and 3
<BLANKLINE>

Method astwriter.SourceWriter.visitAssAttr

Back to astwriter.SourceWriter

Arguments:
self, node

Assign expression to an attribute.

>>> print sourceToString("test.a=5")
test.a = 5
<BLANKLINE>

Method astwriter.SourceWriter.visitAssList

Back to astwriter.SourceWriter

Arguments:
self, node

Assign expression to a list.

>>> print sourceToString("[a,b,c] = [1,2,3]")
[a, b, c] = [1, 2, 3]
<BLANKLINE>

Method astwriter.SourceWriter.visitAssName

Back to astwriter.SourceWriter

Arguments:
self, node

Assign expression to a variable.

>>> print sourceToString("x,y,z = 1, str(2), False")
(x, y, z) = (1, str(2), False)
<BLANKLINE>

Method astwriter.SourceWriter.visitAssTuple

Back to astwriter.SourceWriter

Arguments:
self, node

Assign expression to a tuple.

>>> print sourceToString("x, (a,b) ,z = 1, (str(2),str(3)), False")
(x, (a, b), z) = (1, (str(2), str(3)), False)
<BLANKLINE>

Method astwriter.SourceWriter.visitAssert

Back to astwriter.SourceWriter

Arguments:
self, node

The assert statement.

>>> print sourceToString("assert True == False, 'Oops'")
assert (True == False, 'Oops')
<BLANKLINE>

Method astwriter.SourceWriter.visitAssign

Back to astwriter.SourceWriter

Arguments:
self, node

Called for each assignment. Note that a statement like a = b = None will result in one call to this method.

>>> print sourceToString("x,y,z = 1, str(2), False")
(x, y, z) = (1, str(2), False)
<BLANKLINE>
>>> print sourceToString("x,y,z = l = 1, str(2), False")
(x, y, z) = l = (1, str(2), False)
<BLANKLINE>

Method astwriter.SourceWriter.visitAugAssign

Back to astwriter.SourceWriter

Arguments:
self, node

Called for operations like x += 5 and x -= 1.

>>> print sourceToString("x += 5")
x += 5
<BLANKLINE>

Method astwriter.SourceWriter.visitBackquote

Back to astwriter.SourceWriter

Arguments:
self, node

Called when the backquote character is used.

>>> print sourceToString("`a`")
:wiki:`a`

Method astwriter.SourceWriter.visitBitand

Back to astwriter.SourceWriter

Arguments:
self, node

Called for bitwise 'and' operations. Note that a series of "&"'s will result in only one call to this method.

>>> print sourceToString("1&2&3")
1 & 2 & 3
<BLANKLINE>

Method astwriter.SourceWriter.visitBitor

Back to astwriter.SourceWriter

Arguments:
self, node

Called for bitwise 'or' operations. Note that a series of "|"'s will result in only one call to this method.

>>> print sourceToString("1|2|3")
1 | 2 | 3
<BLANKLINE>

Method astwriter.SourceWriter.visitBitxor

Back to astwriter.SourceWriter

Arguments:
self, node

Called for bitwise 'xor' operations. Note that a series of "^"'s will result in only one call to this method.

>>> print sourceToString("1^2^3")
1 ^ 2 ^ 3

Method astwriter.SourceWriter.visitBreak

Back to astwriter.SourceWriter

Arguments:
self, node

Called for a break statement.

>>> print sourceToString("if True: break")
if True:
    break
<BLANKLINE>

Method astwriter.SourceWriter.visitCallFunc

Back to astwriter.SourceWriter

Arguments:
self, node

Called for a function call.

>>> print sourceToString("x,y,z = 1, str(2), False")
(x, y, z) = (1, str(2), False)
<BLANKLINE>

Method astwriter.SourceWriter.visitClass

Back to astwriter.SourceWriter

Arguments:
self, node

Called for a class definition.

>>> source = '''
... class Test(Base1, Base2):
...     """ Documentation string
...     This is a test. """
...     pass
... '''
>>>
>>> print sourceToString(source)
class Test(Base1, Base2):
    """ Documentation string
    This is a test.
    """
<BLANKLINE>
    pass
<BLANKLINE>
>>> source = '''
... class Test:
...     """ Documentation string
...     This is a test. """
...     pass
... '''
>>>
>>> print sourceToString(source)
class Test:
    """ Documentation string
    This is a test.
    """
<BLANKLINE>
    pass
<BLANKLINE>

Method astwriter.SourceWriter.visitCompare

Back to astwriter.SourceWriter

Arguments:
self, node

Called for each comparison operation.

>>> print sourceToString("a > b or c <= d")
a > b or c <= d

Method astwriter.SourceWriter.visitConst

Back to astwriter.SourceWriter

Arguments:
self, node

Called for constants.

>>> print sourceToString("1 + 2; 'A string constant'")
1 + 2
'A string constant'
<BLANKLINE>

Method astwriter.SourceWriter.visitContinue

Back to astwriter.SourceWriter

Arguments:
self, node

Called for the continue statement.

>>> print sourceToString("if True: continue")
if True:
    continue

Method astwriter.SourceWriter.visitDecorators

Back to astwriter.SourceWriter

Arguments:
self, node

Called for function decorators. Note if multiple decorators are applied to a function, this method is called only once.

>>> source = '''
... @deco
... @deco(1,2,3)
... def test(): pass
... '''
>>> print sourceToString(source)
@deco
@deco(1, 2, 3)
def test():
    pass
<BLANKLINE>

Method astwriter.SourceWriter.visitDict

Back to astwriter.SourceWriter

Arguments:
self, node

Called for a literal dictionary definition (i.e. { a : b, c : d })

>>> print sourceToString("{a:5,'t':test}")
{ a : 5, 't' : test }
Methods:
nodeWriter((k,v)):

Method astwriter.SourceWriter.visitDiscard

Back to astwriter.SourceWriter

Arguments:
self, node

This is called when the results of an expression are discarded.

>>> print sourceToString("a")
a

Method astwriter.SourceWriter.visitDiv

Back to astwriter.SourceWriter

Arguments:
self, node

Called for each division operation.

>>> print sourceToString("1/2")
1 / 2

Method astwriter.SourceWriter.visitEllipsis

Back to astwriter.SourceWriter

Arguments:
self, node

I don't know why I would want it but...

>>> print sourceToString("a[...]")
a[...]

Method astwriter.SourceWriter.visitExec

Back to astwriter.SourceWriter

Arguments:
self, node

Called for the exec statement.

>>> print sourceToString("exec 'a=1'in {}, {}")
exec 'a=1' in {  } , {  }
>>> print sourceToString("exec 'a=1'in {}")
exec 'a=1' in {  }

Method astwriter.SourceWriter.visitFloorDiv

Back to astwriter.SourceWriter

Arguments:
self, node

Called for floor division.

>>> print sourceToString("1//2")
1 // 2

Method astwriter.SourceWriter.visitFor

Back to astwriter.SourceWriter

Arguments:
self, node

Called for a for statement.

>>> print sourceToString('''
... for x in :changeset:`1 [1]`:
...     print x
... else:
...     print "else"
... ''')
for x in :changeset:`1 [1]`:
    print x
else:
    print 'else'
<BLANKLINE>

Method astwriter.SourceWriter.visitFrom

Back to astwriter.SourceWriter

Arguments:
self, node

Called for a from (import) statement.

>>> print sourceToString('''
... from module import some as thing, a as b
... ''')
from module import some as thing, a as b
Methods:
nodeWriter((mod,as)):

Method astwriter.SourceWriter.visitFunction

Back to astwriter.SourceWriter

Arguments:
self, node

Called for each function definition.

>>> print sourceToString('''
... def test(a,b=1, *a, **k):
...     """ This is my docstring.
...     Some more documentation."""
...     pass
... ''')
def test(a, b=1, *a, **k):
<BLANKLINE>
    """ This is my docstring.
    Some more documentation.
    """
    pass
<BLANKLINE>

Method astwriter.SourceWriter.visitGetattr

Back to astwriter.SourceWriter

Arguments:
self, node

Called for attribute access.

>>> print sourceToString("a = test.a")
a = test.a

Method astwriter.SourceWriter.visitGlobal

Back to astwriter.SourceWriter

Arguments:
self, node

Called for the global statement.

>>> print sourceToString("global a,b,c")
global a, b, c

Method astwriter.SourceWriter.visitIf

Back to astwriter.SourceWriter

Arguments:
self, node

Called for the if statement. Also handles the elif and else clauses.

>>> source = '''
... if True:
...     print "true"
... elif False:
...     print "false"
... else:
...     print "I am confused"
... '''
>>> print sourceToString(source)
if True:
    print 'true'
<BLANKLINE>
elif False:
    print 'false'
<BLANKLINE>
else:
    print 'I am confused'
<BLANKLINE>
<BLANKLINE>

Method astwriter.SourceWriter.visitImport

Back to astwriter.SourceWriter

Arguments:
self, node

Called for the import statement.

>>> print sourceToString(
...     "import a.b as b, some.thing as some")
import a.b as b, some.thing as some
Methods:
nodeWriter((mod,as)):

Method astwriter.SourceWriter.visitInvert

Back to astwriter.SourceWriter

Arguments:
self, node

Called for bitwise inversion.

>>> print sourceToString("~ 5")
~5

Method astwriter.SourceWriter.visitKeyword

Back to astwriter.SourceWriter

Arguments:
self, node

Called for a keyword argument.

>>> print sourceToString("f(a=5)")
f(a = 5)
<BLANKLINE>

Method astwriter.SourceWriter.visitLambda

Back to astwriter.SourceWriter

Arguments:
self, node

Called for a lambda statement.

>>> print sourceToString("lambda a,b=1, *a, **k: a")
lambda a, b=1, *a, **k: a

Method astwriter.SourceWriter.visitLeftShift

Back to astwriter.SourceWriter

Arguments:
self, node

Called for bitwise shift-left.

>>> print sourceToString("1<<2")
1 << 2

Method astwriter.SourceWriter.visitList

Back to astwriter.SourceWriter

Arguments:
self, node

Called for a literal list.

>>> print sourceToString("[a,b,c]")
[a, b, c]

Method astwriter.SourceWriter.visitListComp

Back to astwriter.SourceWriter

Arguments:
self, node

Called for a list comprehension.

>>> source = '[x for x in range(10)]'
>>> print sourceToString(source)
[x for x in range(10)]

Method astwriter.SourceWriter.visitListCompFor

Back to astwriter.SourceWriter

Arguments:
self, node

Hmmm, if expr1 if expr2 is valid syntax (at least in 2.4.2.)

>>> source = '[x for x in range(10) if x if y]'
>>> print sourceToString(source)
[x for x in range(10) if x if y]

Method astwriter.SourceWriter.visitListCompIf

Back to astwriter.SourceWriter

Arguments:
self, node

Used for the if part of a list comprehension.

>>> source = '[x for x in range(10) if x if y]'
>>> print sourceToString(source)
[x for x in range(10) if x if y]

Method astwriter.SourceWriter.visitMod

Back to astwriter.SourceWriter

Arguments:
self, node

Called for modulus division.

>>> print sourceToString("1%2")
1 % 2

Method astwriter.SourceWriter.visitModule

Back to astwriter.SourceWriter

Arguments:
self, node

This allways gets visited first.

>>> print sourceToString("' test'")
""" test
"""
<BLANKLINE>

Method astwriter.SourceWriter.visitMul

Back to astwriter.SourceWriter

Arguments:
self, node

Called for the multiplication operation.

>>> print sourceToString("1*2")
1 * 2

Method astwriter.SourceWriter.visitName

Back to astwriter.SourceWriter

Arguments:
self, node

Called for variable access.

>>> print sourceToString("test")
test

Method astwriter.SourceWriter.visitNot

Back to astwriter.SourceWriter

Arguments:
self, node

Called for logical not.

>>> print sourceToString("not True")
not True

Method astwriter.SourceWriter.visitOr

Back to astwriter.SourceWriter

Arguments:
self, node

Called for logical or. Note that multiple or's result in one call to this method.

>>> print sourceToString("a or b or c")
a or b or c

Method astwriter.SourceWriter.visitPass

Back to astwriter.SourceWriter

Arguments:
self, node

Called for the pass statement.

>>> print sourceToString("def test(): pass")
def test():
    pass

Method astwriter.SourceWriter.visitPower

Back to astwriter.SourceWriter

Arguments:
self, node

Called for exponation oerations.

>>> print sourceToString("1**2")
1 ** 2

Method astwriter.SourceWriter.visitPrint

Back to astwriter.SourceWriter

Arguments:
self, node

Called for a print statement without a trailing linefeed.

>>> print sourceToString("print >>f,a,b,c,")
print >>f, a, b, c,
>>> print sourceToString("print a,b,c,")
print a, b, c,

Method astwriter.SourceWriter.visitPrintnl

Back to astwriter.SourceWriter

Arguments:
self, node

Called for a print statement with a trailing linefeed.

>>> print sourceToString("print >>f,a,b,c")
print >>f, a, b, c
>>> print sourceToString("print a,b,c")
print a, b, c

Method astwriter.SourceWriter.visitRaise

Back to astwriter.SourceWriter

Arguments:
self, node

Called for the raise statement.

>>> print sourceToString(
...     "raise ValueError, value, tb")
raise ValueError, value, tb

Method astwriter.SourceWriter.visitReturn

Back to astwriter.SourceWriter

Arguments:
self, node

Called for the return statement.

>>> print sourceToString("return some,things")
return (some, things)

Method astwriter.SourceWriter.visitRightShift

Back to astwriter.SourceWriter

Arguments:
self, node

Called for bitwise shift right.

>>> print sourceToString("1>>2")
1 >> 2

Method astwriter.SourceWriter.visitSliceobj

Back to astwriter.SourceWriter

Arguments:
self, node

Called for sequence slice operations.

>>> print sourceToString("l[a: b: c ]")
l[a:b:c]
<BLANKLINE>
>>> print sourceToString("l[:b:c ]")
l[:b:c]
>>> print sourceToString("l[a::c ]")
l[a::c]
>>> print sourceToString("l[a:b:]")
l[a:b]

Method astwriter.SourceWriter.visitStmt

Back to astwriter.SourceWriter

Arguments:
self, node

Called for each statement.

>>> print sourceToString("print x")
print x

Method astwriter.SourceWriter.visitSub

Back to astwriter.SourceWriter

Arguments:
self, node

Called for each subtraction operation.

>>> print sourceToString("x-1")
x - 1

Method astwriter.SourceWriter.visitSubscript

Back to astwriter.SourceWriter

Arguments:
self, node

Called for a subscript (not a slice).

>>> print sourceToString("[1,2,3][0]")
[1, 2, 3][0]
>>> print sourceToString("del l[2]")
del l[2]

Method astwriter.SourceWriter.visitTryExcept

Back to astwriter.SourceWriter

Arguments:
self, node

Called for a try/except block.

>>> source = '''
... try:
...     some(thing)
... except ValueError,e:
...     done()
... '''
>>> print sourceToString(source)
try:
    some(thing)
<BLANKLINE>
except ValueError, e:
    done()
<BLANKLINE>
<BLANKLINE>
>>> source = '''
... try:
...     some(thing)
... except (ValueError,CustomError),e:
...     done()
... '''
>>> print sourceToString(source)
try:
    some(thing)
<BLANKLINE>
except (ValueError, CustomError), e:
    done()
<BLANKLINE>
<BLANKLINE>

Method astwriter.SourceWriter.visitTryFinally

Back to astwriter.SourceWriter

Arguments:
self, node

Called for a try/finally block.

>>> source = '''
... try:
...     some(thing)
... finally:
...     done()
... '''
>>> print sourceToString(source)
try:
    some(thing)
<BLANKLINE>
finally:
    done()
<BLANKLINE>
<BLANKLINE>

Method astwriter.SourceWriter.visitTuple

Back to astwriter.SourceWriter

Arguments:
self, node

Called for each tuple.

>>> print sourceToString("(1,2,3)")
(1, 2, 3)
>>> print sourceToString("(1,)")
(1,)

Method astwriter.SourceWriter.visitUnaryAdd

Back to astwriter.SourceWriter

Arguments:
self, node

Called for unary "+".

>>> print sourceToString("+100")
+100

Method astwriter.SourceWriter.visitUnarySub

Back to astwriter.SourceWriter

Arguments:
self, node

Called for unary "-".

>>> print sourceToString("-100")
-100

Method astwriter.SourceWriter.visitWhile

Back to astwriter.SourceWriter

Arguments:
self, node

Called for the while statement.

>>> source = '''
... while True:
...     some(thing)
... else:
...     else_(thing)
... '''
>>> print sourceToString(source)
while True:
    some(thing)
<BLANKLINE>
else:
    else_(thing)
<BLANKLINE>

Method astwriter.SourceWriter.visitYield

Back to astwriter.SourceWriter

Arguments:
self, node

Called for a yield statement.

>>> print sourceToString("yield y")
yield y

Method astwriter.getSignature

Back to astwriter

Arguments:
node

I return the argument signature for node which must be a Function or Lambda node.

Methods:
fix(arg):

Method astwriter.testSuite

Back to astwriter

Arguments:
Imports:
astwriter, doctest