Move dlis parser to submodule 'dlis'

This commit restructure the python submodules, and most notably, moves
the DLIS reader from  module 'dlisio' to submodule 'dlisio.dlis'. This
is a major break of the API, but a necessary one now that dlisio is
extended to be a multi-fileformat reader.

        Before this commit       ->      After this commit
        --------------------------------------------------

        dlisio (module)                 dlisio (module)
        |-> core (submodule)            |-> core (submodule)
        |-> lis  (submodule)            |-> lis  (submodule)
        |    |-> load                   |    |-> load
        |    |-> file                   |    |-> file
        |    |-> curves                 |    |-> curves
        |                               |
        |-> load                        | -> common (submodule)
        |-> logical,physical_file       | -> dlis   (submodule)
        |                                    |-> load
        |-> plumbing (submodule)             |-> file
            |-> object-types etc..           |-> object-types
                                             |-> utils  (submodule)
                                                 |-> etc ..

The commit is rather large and noisy, but there is really no sensible,
smaller and autonomous commits to be made. To break it down, this commit
mainly does 3 things:

  1) Rename files into the new project tree
  2) Update imports, both internally in the package, and in the test
     directory
  3) Update documentation references

python/dlisio/__init__.py

@@ -1,10 +1,7 @@
 from . import core
-from . import plumbing
-from . import errors
-from .settings import get_encodings, set_encodings
-from .file import physicalfile, logicalfile
-from .load import load
-from .open import open
+from . import common
+from . import lis
+from . import dlis
 
 try:
     import pkg_resources

python/dlisio/common/__init__.py

@@ -0,0 +1,3 @@
+from .errorhandler import ErrorHandler, Actions
+from .open import open
+from .settings import get_encodings, set_encodings

python/dlisio/errors/errorhandler.py → python/dlisio/common/errorhandler.py

@@ -122,7 +122,7 @@ class ErrorHandler(core.error_handler):
     --------
     Define your own rules:
 
-    >>> from dlisio.errors import ErrorHandler, Actions
+    >>> from dlisio.common import ErrorHandler, Actions
     >>> def myhandler(msg):
     ...     raise RuntimeError("Custom handler: " + msg)
     >>> errorhandler = ErrorHandler(
@@ -133,10 +133,11 @@ class ErrorHandler(core.error_handler):
 
     Parse a file:
 
-    >>> files = dlisio.load(path)
+    >>> from dlisio import dlis
+    >>> files = dlis.load(path)
     RuntimeError: "...."
     >>> handler = ErrorHandler(critical=Actions.LOG_ERROR)
-    >>> files = dlisio.load(path, errorhandler=handler)
+    >>> files = dlis.load(path, errorhandler=handler)
     [ERROR] "...."
     >>> for f in files:
     ...  pass

python/dlisio/open.py → python/dlisio/common/open.py

@@ -1,4 +1,4 @@
-from . import core
+from .. import core
 
 def open(path, offset = 0):
     """ Open a file
@@ -18,6 +18,7 @@ def open(path, offset = 0):
 
     See Also
     --------
-    dlisio.load
+    dlisio.dlis.load
+    dlisio.lis.load
     """
     return core.open(str(path), offset)

python/dlisio/settings.py → python/dlisio/common/settings.py

@@ -1,7 +1,4 @@
-from . import core
-from . import plumbing
-
-import re
+from .. import core
 
 
 def get_encodings():
@@ -82,16 +79,17 @@ def set_encodings(encodings):
     --------
     Decoding of the same string under different encodings
 
-    >>> dlisio.set_encodings([])
-    >>> with dlisio.load('file.dlis') as (f, *_):
+    >>> from dlisio import dlis, common
+    >>> common.set_encodings([])
+    >>> with dlis.load('file.dlis') as (f, *_):
     ...     print(getchannel(f).units)
     b'custom unit\\xb0'
-    >>> dlisio.set_encodings(['latin1'])
-    >>> with dlisio.load('file.dlis') as (f, *_):
+    >>> common.set_encodings(['latin1'])
+    >>> with dlis.load('file.dlis') as (f, *_):
     ...     print(getchannel(f).units)
     'custom unit°'
-    >>> dlisio.set_encodings(['utf-16'])
-    >>> with dlisio.load('file.dlis') as (f, *_):
+    >>> common.set_encodings(['utf-16'])
+    >>> with dlis.load('file.dlis') as (f, *_):
     ...     print(getchannel(f).units)
     '畣瑳浯甠楮끴'
     """

python/dlisio/plumbing/__init__.py → python/dlisio/dlis/__init__.py

@@ -1,3 +1,6 @@
+from .load import load
+from .file import *
+
 from .basicobject import BasicObject
 from .axis import Axis
 from .fileheader import Fileheader
@@ -23,8 +26,4 @@
 from .unknown import Unknown
 from .noformat import Noformat
 
-from .matcher import *
-from .valuetypes import *
-from .linkage import *
-from .describe import *
-from .dimensional import *
+from . import utils

python/dlisio/plumbing/axis.py → python/dlisio/dlis/axis.py

@@ -1,9 +1,8 @@
-from .basicobject import BasicObject
-from .valuetypes import scalar, vector
-from .describe import describe_attributes
-
 from collections import OrderedDict
 
+from .basicobject import BasicObject
+from . import utils
+
 
 class Axis(BasicObject):
     """Axis
@@ -37,9 +36,9 @@ class Axis(BasicObject):
     described in detail in Chapter 5.3.1 - Static and Frame Data, Axis Objects.
     """
     attributes = {
-        'AXIS-ID'     : scalar,
-        'COORDINATES' : vector,
-        'SPACING'     : scalar,
+        'AXIS-ID'     : utils.scalar,
+        'COORDINATES' : utils.vector,
+        'SPACING'     : utils.scalar,
     }
 
     def __init__(self, attic, lf):
@@ -63,4 +62,4 @@ def describe_attr(self, buf, width, indent, exclude):
         d['Spacing']     = 'SPACING'
         d['Coordinates'] = 'COORDINATES'
 
-        describe_attributes(buf, d, self, width, indent, exclude)
+        utils.describe_attributes(buf, d, self, width, indent, exclude)

python/dlisio/plumbing/basicobject.py → python/dlisio/dlis/basicobject.py

@@ -1,16 +1,8 @@
+import logging
+
 from .. import core
-from .valuetypes import *
-from .linkage import *
-from .describe import (
-    describe_header,
-    describe_dict,
-    describe_attributes,
-    parseoptions,
-    headerinfo,
-    Summary
-)
+from . import utils
 
-import logging
 
 class BasicObject():
     """A Basic object that all other object-types derive from
@@ -109,9 +101,9 @@ class BasicObject():
     the attribute-dict before loading the file and dlisio will parse 'UNITS' as
     a list:
 
-    >>> from dlisio.plumbing import vector
+    >>> from dlisio.dlis.utils import vector
     >>> Channel.attributes['UNITS'] = vector
-    >>> with dlisio.load('file.dlis') as (f, *_):
+    >>> with dlisio.dlis.load('file.dlis') as (f, *_):
     ...     ch = f.object('CHANNEL', 'TDEP')
     ...     ch.units
     ['m/s', 'rad/s']
@@ -148,9 +140,9 @@ class BasicObject():
 
     Change how dlisio parses Channel.source:
 
-    >>> from dlisio.plumbing import obname
+    >>> from dlisio.dlis.utils import obname
     >>> Channel.linkage['SOURCE'] = obname('PARAMETER')
-    >>> with dlisio.load('file.dlis') as (f, *_):
+    >>> with dlisio.dlis.load('file.dlis') as (f, *_):
     ...     ch = f.object('channel', 'TDEP')
     ...     ch.source
     Parameter('2000T')
@@ -201,7 +193,7 @@ def __getitem__(self, key):
             parse_as = self.attributes[key]
         except KeyError:
             # No rule for parsing, keep rp66value as is, i.e. vector
-            parse_as = vector
+            parse_as = utils.vector
 
         # report errors before checking for key presence - it might be a symptom
         if len(self.attic.log) > 0:
@@ -217,7 +209,7 @@ def __getitem__(self, key):
         try:
             attribute = self.attic[key]
         except KeyError:
-            return defaultvalue(parse_as)
+            return utils.defaultvalue(parse_as)
 
         rp66value = attribute.value
 
@@ -229,16 +221,16 @@ def __getitem__(self, key):
                     error.severity, context, error.problem,
                     error.specification, error.action, "")
 
-        if rp66value is None: return defaultvalue(parse_as)
-        if rp66value == []  : return defaultvalue(parse_as)
+        if rp66value is None: return utils.defaultvalue(parse_as)
+        if rp66value == []  : return utils.defaultvalue(parse_as)
 
-        if key in self.linkage and isreference(rp66value[0]):
+        if key in self.linkage and utils.isreference(rp66value[0]):
             reftype = self.linkage[key]
-            value = [lookup(self.logicalfile, reftype, v) for v in rp66value]
+            value = [utils.lookup(self.logicalfile, reftype, v) for v in rp66value]
         else:
             value = [v.strip() if isinstance(v, str) else v for v in rp66value]
 
-        return parsevalue(value, parse_as)
+        return utils.parsevalue(value, parse_as)
 
     def __eq__(self, rhs):
         try:
@@ -308,7 +300,7 @@ def describe(self, width=80, indent='', exclude='er'):
         Returns
         -------
 
-        summary : Summary
+        summary : utils.Summary
             A printable summary of the object
 
         Notes
@@ -337,22 +329,22 @@ def describe(self, width=80, indent='', exclude='er'):
         from io import StringIO
 
         buf = StringIO()
-        exclude = parseoptions(exclude)
+        exclude = utils.parseoptions(exclude)
 
         if not exclude['head']:
-            describe_header(buf, self.type.capitalize(), width, indent)
-            describe_dict(buf, headerinfo(self), width, indent, exclude)
+            utils.describe_header(buf, self.type.capitalize(), width, indent)
+            utils.describe_dict(buf, utils.headerinfo(self), width, indent, exclude)
 
         if not exclude['attr']:
             self.describe_attr(buf, indent=indent, width=width, exclude=exclude)
 
         if not exclude['stash']:
             if len(self.stash) > 0:
-                describe_header(buf, 'Unknown attributes', width, indent, lvl=2)
+                utils.describe_header(buf, 'Unknown attributes', width, indent, lvl=2)
                 d = {k : k for k in self.stash.keys()}
-                describe_attributes(buf, d, self, width, indent, exclude)
+                utils.describe_attributes(buf, d, self, width, indent, exclude)
 
-        return Summary(info=buf.getvalue())
+        return utils.Summary(info=buf.getvalue())
 
     def describe_attr(self, buf, width, indent, exclude):
         """Describe the attributes of the object.

python/dlisio/plumbing/calibration.py → python/dlisio/dlis/calibration.py

@@ -1,10 +1,8 @@
-from .basicobject import BasicObject
-from .valuetypes import vector, scalar
-from .linkage import obname
-from .describe import describe_dict, replist
-
 from collections import OrderedDict
 
+from .basicobject import BasicObject
+from . import utils
+
 class Calibration(BasicObject):
     """
     Calibration objects are a collection of measurements and coefficients that
@@ -47,20 +45,20 @@ class Calibration(BasicObject):
     CALIBRATION objects.
     """
     attributes = {
-        'METHOD'               : scalar,
-        'CALIBRATED-CHANNELS'  : vector,
-        'UNCALIBRATED-CHANNELS': vector,
-        'COEFFICIENTS'         : vector,
-        'MEASUREMENTS'         : vector,
-        'PARAMETERS'           : vector,
+        'METHOD'               : utils.scalar,
+        'CALIBRATED-CHANNELS'  : utils.vector,
+        'UNCALIBRATED-CHANNELS': utils.vector,
+        'COEFFICIENTS'         : utils.vector,
+        'MEASUREMENTS'         : utils.vector,
+        'PARAMETERS'           : utils.vector,
     }
 
     linkage = {
-        'CALIBRATED-CHANNELS'   : obname('CHANNEL'),
-        'UNCALIBRATED-CHANNELS' : obname('CHANNEL'),
-        'COEFFICIENTS'          : obname('CALIBRATION-COEFFICIENT'),
-        'MEASUREMENTS'          : obname('CALIBRATION-MEASUREMENT'),
-        'PARAMETERS'            : obname('PARAMETER')
+        'CALIBRATED-CHANNELS'   : utils.obname('CHANNEL'),
+        'UNCALIBRATED-CHANNELS' : utils.obname('CHANNEL'),
+        'COEFFICIENTS'          : utils.obname('CALIBRATION-COEFFICIENT'),
+        'MEASUREMENTS'          : utils.obname('CALIBRATION-MEASUREMENT'),
+        'PARAMETERS'            : utils.obname('PARAMETER')
     }
 
     def __init__(self, attic, lf):
@@ -93,10 +91,10 @@ def parameters(self):
     def describe_attr(self, buf, width, indent, exclude):
         d = OrderedDict()
         d['Computational method']  = self.method
-        d['Calibrated channels']   = replist(self.calibrated  , 'name')
-        d['Uncalibrated channels'] = replist(self.uncalibrated, 'name')
-        d['Coefficients']          = replist(self.coefficients, 'name')
-        d['Measurements']          = replist(self.measurements, 'name')
-        d['Parameters']            = replist(self.parameters  , 'name')
+        d['Calibrated channels']   = utils.replist(self.calibrated  , 'name')
+        d['Uncalibrated channels'] = utils.replist(self.uncalibrated, 'name')
+        d['Coefficients']          = utils.replist(self.coefficients, 'name')
+        d['Measurements']          = utils.replist(self.measurements, 'name')
+        d['Parameters']            = utils.replist(self.parameters  , 'name')
 
-        describe_dict(buf, d, width, indent, exclude)
+        utils.describe_dict(buf, d, width, indent, exclude)