docs(collections): Cleaned up documentation in response to building docs and running lint, plus other minor clean-up.

Author: rbeyer

HISTORY.rst

@@ -3,11 +3,21 @@
 History
 -------
 
-???
-~~~
-* Worked to switch out the custom OrderedMultiDict with the 3rd party
-  multidict.MultiDict.  Still in-process, have identified issues in
-  the docstring for pvl._collections.PVLMultiDict, not all tests passing.
+1.0.0-alpha.9 (2020-08-18)
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+* Minor addition to pvl.collections.MutableMappingSequence.
+* Implemented PVLMultiDict which is based on the 3rd Party
+  `multidict.MultiDict` object as an option to use instead
+  of the default OrderedMultiDict.  The new PVLMultiDict
+  is better aligned with the Python 3 way that Mapping
+  objects behave.
+* Enhanced the existing OrderedMultiDict with some functionality
+  that extends its behavior closer to the Python 3 ideal, and
+  inserted warnings about how the retained non-Python-3
+  behaviors might be removed at the next major patch.
+* Implemented pvl.new that can be included for those that wish
+  to try out what getting the new PVLMultiDict returned from
+  the loaders might be like by just changing an import statement.
 
 1.0.0-alpha.8 (2020-08-01)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~

environment.yml

@@ -19,3 +19,4 @@ dependencies:
   - python-dateutil
   - astropy
   - pint
+  - multidict

pvl/__init__.py

@@ -24,7 +24,7 @@
 
 __author__ = 'The pvl Developers'
 __email__ = '[email protected]'
-__version__ = '1.0.0-alpha.8'
+__version__ = '1.0.0-alpha.9'
 __all__ = [
     'load',
     'loads',

pvl/collections.py

@@ -489,7 +489,8 @@ def _insert_arg_helper(args):
 
     return kvlist
 
-try:
+
+try:  # noqa: C901
     # In order to access super class attributes for our derived class, we must
     # import the native Python version, instead of the default Cython version.
     from multidict._multidict_py import MultiDict
@@ -500,30 +501,31 @@ class PVLMultiDict(MultiDict, MutableMappingSequence):
         OrderedMultiDict).
 
         Here is a summary of the differences:
-        - OrderedMultiDict.getall('k') where k is not in the structure returns
-            an empty list, PVLMultiDict.getall('k') properly returns a KeyError.
-        - The .items(), .keys(), and .values() are proper iterators
-            and don't return sequences like OrderedMultiDict did.
-        - Calling list() on an OrderedMultiDict returns a list of tuples, which
-            is like calling list() on the results of a dict.items() iterator.
-            Calling list() on a PVLMultiDict returns just a list of keys,
-            which is semantically identical to calling list() on a dict.
-        - OrderedMultiDict.pop(k) removed all keys that matched k,
-            PVLMultiDict.pop(k) just removes the first occurrence.
-            PVLMultiDict.popall(k) would pop all.
-        - OrderedMultiDict.popitem() removes the last item from the underlying
-            list, PVLMultiDict.popitem() removes an arbitrary key, value pair,
-            semantically identical to .popitem() on a dict.
-        - OrderedMultiDict.__repr__() and .__str__() return identical strings,
-            PVLMultiDict provides a .__str__() that is pretty-printed similar
-            to OrderedMultiDict, but also a .__repr__() with a more compact
-            representation.
-        - equality is different:  OrderedMultiDict has an isinstance()
-            check in the __eq__() operator, which I don't think was right,
-            since equality is about values, not about type.  PVLMultiDict
-            has a value-based notion of equality.  So an empty PVLGroup and an
-            empty PVLObject derived from PVLMultiDict could test equal,
-            but would fail an isinstance() check.
+
+        * OrderedMultiDict.getall('k') where k is not in the structure returns
+          an empty list, PVLMultiDict.getall('k') properly returns a KeyError.
+        * The .items(), .keys(), and .values() are proper iterators
+          and don't return sequences like OrderedMultiDict did.
+        * Calling list() on an OrderedMultiDict returns a list of tuples, which
+          is like calling list() on the results of a dict.items() iterator.
+          Calling list() on a PVLMultiDict returns just a list of keys,
+          which is semantically identical to calling list() on a dict.
+        * OrderedMultiDict.pop(k) removed all keys that matched k,
+          PVLMultiDict.pop(k) just removes the first occurrence.
+          PVLMultiDict.popall(k) would pop all.
+        * OrderedMultiDict.popitem() removes the last item from the underlying
+          list, PVLMultiDict.popitem() removes an arbitrary key, value pair,
+          semantically identical to .popitem() on a dict.
+        * OrderedMultiDict.__repr__() and .__str__() return identical strings,
+          PVLMultiDict provides a .__str__() that is pretty-printed similar
+          to OrderedMultiDict, but also a .__repr__() with a more compact
+          representation.
+        * Equality is different:  OrderedMultiDict has an isinstance()
+          check in the __eq__() operator, which I don't think was right,
+          since equality is about values, not about type.  PVLMultiDict
+          has a value-based notion of equality.  So an empty PVLGroup and an
+          empty PVLObject derived from PVLMultiDict could test equal,
+          but would fail an isinstance() check.
         """
         # Also evaluated the boltons.OrderedMultiDict, but its semantics were
         # too different #52
@@ -669,15 +671,12 @@ def append(self, key, value):
     class PVLModuleNew(PVLMultiDict):
         pass
 
-
     class PVLAggregationNew(PVLMultiDict):
         pass
 
-
     class PVLGroupNew(PVLAggregationNew):
         pass
 
-
     class PVLObjectNew(PVLAggregationNew):
         pass
 

pvl/new.py

@@ -24,7 +24,7 @@
 import inspect
 import urllib.request
 
-from pvl import *
+from pvl import *  # noqa: F401,F403
 from pvl import get_text_from, decode_by_char
 
 from .parser import PVLParser, OmniParser
@@ -123,4 +123,4 @@ def loads(s: str, parser=None, grammar=None, decoder=None, **kwargs):
     elif not isinstance(parser, PVLParser):
         raise TypeError('The parser must be an instance of pvl.PVLParser.')
 
-    return parser.parse(s)
+    return parser.parse(s)

setup.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 1.0.0-alpha.8
+current_version = 1.0.0-alpha.9
 commit = False
 tag = False
 parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)(\-(?P<prerelease>[a-z]+)\.((?P<serial>\d+)))?

setup.py

@@ -12,7 +12,7 @@
 
 setup(
     name='pvl',
-    version='1.0.0-alpha.8',
+    version='1.0.0-alpha.9',
     description='Python implementation of PVL (Parameter Value Language)',
     long_description=readme + '\n\n' + history,
     author='The PlanetaryPy Developers',

tests/test_collections.py

@@ -278,18 +278,26 @@ def test_copy(self):
                 self.assertNotEqual(module, copy)
 
     def test_equality(self):
-        for modcls, grpcls, objcls in (
+        classes = [
             (
                 pvl.collections.PVLModule,
                 pvl.collections.PVLGroup,
                 pvl.collections.PVLObject
-            ),
-            (
-                pvl.collections.PVLModuleNew,
-                pvl.collections.PVLGroupNew,
-                pvl.collections.PVLObjectNew
             )
-        ):
+        ]
+        try:
+            from pvl.collections import PVLMultiDict
+            classes.append(
+                (
+                    pvl.collections.PVLModuleNew,
+                    pvl.collections.PVLGroupNew,
+                    pvl.collections.PVLObjectNew
+                )
+            )
+        except ImportError:
+            pass
+
+        for modcls, grpcls, objcls in classes:
             module = modcls()
             group = grpcls()
             obj = objcls()

tests/test_pvl.py

@@ -990,7 +990,6 @@ def test_broken_labels(label, expected, expected_errors):
     # But this should compare the 'line numbers' of the EmptyValueAtLine
     # objects.
     assert module.errors == expected_errors
-    # assert not module.valid
 
 
 @pytest.mark.parametrize(