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¶
penman.codec – Codec class for reading and writing PENMAN data
penman.constant – For working with constant values
penman.epigraph – Base classes for epigraphical markers
penman.exceptions – Exception classes
penman.graph – Classes for pure graphs
penman.layout – Conversion between trees and graphs
penman.model – Class for defining semantic models
penman.models – Pre-defined models
penman.surface – For working with surface alignments
penman.transform – Graph and tree transformation functions
penman.tree – Classes for trees