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#