penman

Penman graph library.

For basic usage, common functionality is available from the top-level penman module. For more advanced usage, please use the full API available via the submodules.

Users wanting to interact with graphs might find the decode() and encode() functions a good place to start:

>>> import penman
>>> g = penman.decode('(w / want-01 :ARG0 (b / boy) :ARG1 (g / go :ARG0 b))')
>>> g.top
'w'
>>> len(g.triples)
6
>>> [concept for _, _, concept in g.instances()]
['want-01', 'boy', 'go']
>>> print(penman.encode(g, top='b'))
(b / boy
   :ARG0-of (w / want-01
               :ARG1 (g / go
                        :ARG0 b)))

The decode() and encode() functions work with one PENMAN graph. The load() and dump() functions work with collections of graphs.

Users who want to work with trees would use parse() and format() instead:

>>> import penman
>>> t =  penman.parse('(w / want-01 :ARG0 (b / boy) :ARG1 (g / go :ARG0 b))')
>>> var, branches = t.node
>>> var
'w'
>>> len(branches)
3
>>> role, target = branches[2]
>>> role
':ARG1'
>>> print(penman.format(target))
(g / go
   :ARG0 b)

Module Constants

penman.__version__

The software version string.

penman.__version_info__

The software version as a tuple.

Classes

class penman.Tree[source]

Alias of penman.tree.Tree.

class penman.Triple[source]

Alias of penman.graph.Triple.

class penman.Graph[source]

Alias of penman.graph.Graph.

class penman.PENMANCodec[source]

Alias of penman.codec.PENMANCodec.

Module Functions

Trees

penman.parse(s)[source]

Parse PENMAN-notation string s into its tree structure.

Parameters

s – a string containing a single PENMAN-serialized graph

Returns

The tree structure described by s.

Example

>>> import penman
>>> penman.parse('(b / bark-01 :ARG0 (d / dog))')  # noqa
Tree(('b', [('/', 'bark-01'), (':ARG0', ('d', [('/', 'dog')]))]))
penman.iterparse(lines)[source]

Yield trees parsed from lines.

Parameters

lines – a string or open file with PENMAN-serialized graphs

Returns

The Tree object described in lines.

Example

>>> import penman
>>> for t in penman.iterparse('(a / alpha) (b / beta)'):
...     print(repr(t))
...
Tree(('a', [('/', 'alpha')]))
Tree(('b', [('/', 'beta')]))
penman.format(tree, indent=- 1, compact=False)[source]

Format tree into a PENMAN string.

Parameters

  • tree – a Tree object

  • indent – how to indent formatted strings

  • compact – if True, put initial attributes on the first line

Returns

the PENMAN-serialized string of the Tree t

Example

>>> import penman
>>> print(penman.format(
...     ('b', [('/', 'bark-01'),
...            (':ARG0', ('d', [('/', 'dog')]))])))
(b / bark-01
   :ARG0 (d / dog))
penman.interpret(t, model=None)[source]

Interpret a graph from the Tree t.

Alias of penman.layout.interpret()

Graphs

penman.decode(s, model=None)

Deserialize PENMAN-serialized s into its Graph object

Parameters

  • s – a string containing a single PENMAN-serialized graph

  • model – the model used for interpreting the graph

Returns

the Graph object described by s

Example

>>> import penman
>>> penman.decode('(b / bark-01 :ARG0 (d / dog))')
<Graph object (top=b) at ...>
penman.iterdecode(lines, model=None)

Yield graphs parsed from lines.

Parameters

  • lines – a string or open file with PENMAN-serialized graphs

  • model – the model used for interpreting the graph

Returns

The Graph objects described in lines.

Example

>>> import penman
>>> for g in penman.iterdecode('(a / alpha) (b / beta)'):
...     print(repr(g))
<Graph object (top=a) at ...>
<Graph object (top=b) at ...>
penman.encode(g, top=None, model=None, indent=- 1, compact=False)

Serialize the graph g from top to PENMAN notation.

Parameters

  • g – the Graph object

  • top – if given, the node to use as the top in serialization

  • model – the model used for interpreting the graph

  • indent – how to indent formatted strings

  • compact – if True, put initial attributes on the first line

Returns

the PENMAN-serialized string of the Graph g

Example

>>> import penman
>>> from penman.graph import Graph
>>> penman.encode(Graph([('h', 'instance', 'hi')]))
'(h / hi)'
penman.configure(g, top=None, model=None)[source]

Configure a tree from the Graph g.

Alias of penman.layout.configure()

Corpus Files

penman.loads(string, model=None)

Deserialize a list of PENMAN-encoded graphs from string.

Parameters

  • string – a string containing graph data

  • model – the model used for interpreting the graph

Returns

a list of Graph objects

penman.load(source, model=None, encoding=None)

Deserialize a list of PENMAN-encoded graphs from source.

Parameters

  • source – a filename or file-like object to read from

  • model – the model used for interpreting the graph

Returns

a list of Graph objects

penman.dumps(graphs, model=None, indent=- 1, compact=False)

Serialize each graph in graphs to the PENMAN format.

Parameters

  • graphs – an iterable of Graph objects

  • model – the model used for interpreting the graph

  • indent – how to indent formatted strings

  • compact – if True, put initial attributes on the first line

Returns

the string of serialized graphs

penman.dump(graphs, file, model=None, indent=- 1, compact=False, encoding=None)

Serialize each graph in graphs to PENMAN and write to file.

Parameters

  • graphs – an iterable of Graph objects

  • file – a filename or file-like object to write to

  • model – the model used for interpreting the graph

  • indent – how to indent formatted strings

  • compact – if True, put initial attributes on the first line

Triple Conjunctions

penman.parse_triples(s)[source]

Parse a triple conjunction from s.

Example

>>> import penman
>>> for triple in penman.parse_triples('''
...         instance(b, bark) ^
...         ARG0(b, d) ^
...         instance(d, dog)'''):
...     print(triple)
('b', ':instance', 'bark')
('b', ':ARG0', 'd')
('d', ':instance', 'dog')
penman.format_triples(triples, indent=True)[source]

Return the formatted triple conjunction of triples.

Parameters

  • triples – an iterable of triples

  • indent – how to indent formatted strings

Returns

the serialized triple conjunction of triples

Example

>>> import penman
>>> g = penman.decode('(b / bark-01 :ARG0 (d / dog))')
>>> print(penman.format_triples(g.triples))
instance(b, bark-01) ^
ARG0(b, d) ^
instance(d, dog)

Exceptions

exception penman.PenmanError[source]

Alias of penman.exceptions.PenmanError.

exception penman.DecodeError[source]

Alias of penman.exceptions.DecodeError.

Submodules