Deprecate penman.interface module

Resolves #78

CHANGELOG.md

@@ -9,11 +9,15 @@
 ### Removed
 
 * `penman.lexer` is now non-public ([#77])
+* `penman.interface` is removed from the public API but remains
+  temporarily for backward compatibility ([#78])
 
 ### Changed
 
 * Make `parse()`, `format()`, `interpret()`, and `configure()`
   available at the top-level module ([#75])
+* Make `iterparse()`, `iterdecode()`, `parse_triples()`, and
+  `format_triples()` available at the top-level module ([#78])
 * Move the implementations of `parse()` and `format()` to separate
   modules from PENMANCodec ([#76])
 * Make `penman.tree.Tree` available at the top-level module
@@ -692,3 +696,4 @@ First release with very basic functionality.
 [#75]: https://github.com/goodmami/penman/issues/75
 [#76]: https://github.com/goodmami/penman/issues/76
 [#77]: https://github.com/goodmami/penman/issues/77
+[#78]: https://github.com/goodmami/penman/issues/78

docs/api/penman.rst

@@ -35,7 +35,6 @@ Other
 '''''
 
 - :doc:`penman.exceptions` -- Exception classes
-- :doc:`penman.interface` -- Functional interface to a codec
 - :doc:`penman.transform` -- Graph and tree transformation functions
 
 
@@ -74,30 +73,54 @@ Classes
 Module Functions
 ----------------
 
+Trees
+'''''
+
 .. autofunction:: parse
 
+.. autofunction:: iterparse
+
+.. autofunction:: format
+
 .. function:: interpret(t, model=None)
 
+   Interpret a graph from the :class:`Tree` *t*.
+
    Alias of :func:`penman.layout.interpret`
 
+Graphs
+''''''
+
 .. autofunction:: decode
 
-.. autofunction:: loads
+.. autofunction:: iterdecode
 
-.. autofunction:: load
-
-.. autofunction:: format
+.. autofunction:: encode
 
 .. function:: configure(g, top=None, model=None, strict=False)
 
+   Configure a tree from the :class:`Graph` *g*.
+
    Alias of :func:`penman.layout.configure`
 
-.. autofunction:: encode
+Corpus Files
+''''''''''''
+
+.. autofunction:: loads
+
+.. autofunction:: load
 
 .. autofunction:: dumps
 
 .. autofunction:: dump
 
+Triple Conjunctions
+'''''''''''''''''''
+
+.. autofunction:: parse_triples
+
+.. autofunction:: format_triples
+
 
 Exceptions
 ----------

docs/basic.rst

@@ -15,11 +15,10 @@ And here's an example of its library usage:
 
 .. code-block:: python
 
-   >>> from penman import PENMANCodec
-   >>> codec = PENMANCodec()
-   >>> g = codec.decode('(s / sleep-01 :polarity - :ARG0 (i / i))')
+   >>> import penman
+   >>> g = penman.decode('(s / sleep-01 :polarity - :ARG0 (i / i))')
    >>> g.triples.remove(('s', ':polarity', '-'))
-   >>> print(PENMANCodec().encode(g))
+   >>> print(penman.encode(g))
    (s / sleep-01
       :ARG0 (i / i))
 
@@ -97,20 +96,19 @@ For example:
 
 .. code-block:: python
 
-   >>> from penman import PENMANCodec
-   >>> codec = PENMANCodec()
-   >>> g = codec.decode('(b / bark-01 :ARG0 (d / dog))')
+   >>> import penman
+   >>> g = penman.decode('(b / bark-01 :ARG0 (d / dog))')
    >>> g.instances()
    [Instance(source='b', role=':instance', target='bark-01'), Instance(source='d', role=':instance', target='dog')]
    >>> g.edges()
    [Edge(source='b', role=':ARG0', target='d')]
    >>> sorted(g.variables())
    ['b', 'd']
-   >>> print(codec.encode(g, top='d'))
+   >>> print(penman.encode(g, top='d'))
    (d / dog
       :ARG0-of (b / bark-01))
    >>> g.triples.append(('b', ':polarity', '-'))
-   >>> print(codec.encode(g))
+   >>> print(penman.encode(g))
    (b / bark-01
       :ARG0 (d / dog)
       :polarity -)

docs/index.rst

@@ -48,7 +48,6 @@ models if they need more control.
    api/penman.epigraph
    api/penman.exceptions
    api/penman.graph
-   api/penman.interface
    api/penman.layout
    api/penman.model
    api/penman.models

penman/__init__.py

@@ -16,10 +16,14 @@
     'Graph',
     'PENMANCodec',
     'parse',
+    'iterparse',
+    'parse_triples',
     'format',
+    'format_triples',
     'interpret',
     'configure',
     'decode',
+    'iterdecode',
     'encode',
     'load',
     'loads',
@@ -46,16 +50,24 @@
     interpret,
     configure,
 )
-from penman._parse import parse
-from penman._format import format
-from penman.codec import PENMANCodec
-from penman.interface import (
-    decode,
-    encode,
-    load,
-    loads,
-    dump,
-    dumps,
+from penman._parse import (
+    parse,
+    iterparse,
+    parse_triples,
+)
+from penman._format import (
+    format,
+    format_triples,
+)
+from penman.codec import (
+    PENMANCodec,
+    _decode as decode,
+    _iterdecode as iterdecode,
+    _encode as encode,
+    _load as load,
+    _loads as loads,
+    _dump as dump,
+    _dumps as dumps,
 )
 
 logging.basicConfig()

penman/_format.py

@@ -10,6 +10,19 @@ def format(tree: Tree,
            compact: bool = False) -> str:
     """
     Format *tree* into a PENMAN string.
+
+    Args:
+        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
+        >>> penman.format(('b', [('/', 'bark-01'),
+        ...                      (':ARG0', ('d', [('/', 'dog')]))]))
+        (b / bark-01
+           :ARG0 (d / dog))
     """
     if not isinstance(tree, Tree):
         tree = Tree(tree)