Merge lp:~wallyworld/lazr.enum/json-serialisation-support into lp:lazr.enum

[Ian Booth]

Add json serialisation support and drive by fix a couple of minor bugs

== Implementation ==

This branch adds json serialisation support to enumerated types.

A enum instance is serialised as a dict containing:
- the enumerated type name as per the enumerated_type_registry
- the enum instance name

This information is sufficient to allow the dict to be deserialised back to an enum.

I had to upgrade bootstrap.py and ez_setup.py since they were way out of date.
(Ignore these in the diff since they are not ours).

I also fixed a couple of minor bugs as a drive by: bugs 524259 and 526484

== Tests ==

Add new doc tests to README.txt

== Lint ==

I didn't bother with:
  ez_setup.py
  _bootstrap/bootstrap.py
since they are not ours.

Linting changed files:
  .bzrignore
  src/lazr/enum/NEWS.txt
  src/lazr/enum/README.txt
  src/lazr/enum/__init__.py
  src/lazr/enum/_enum.py
  src/lazr/enum/_json.py
  src/lazr/enum/version.txt

./src/lazr/enum/README.txt
     302: Line exceeds 80 characters.
     419: Line exceeds 80 characters.
     420: Line exceeds 80 characters.
./src/lazr/enum/__init__.py
      25: 'from lazr.enum._enum import *' used; unable to detect undefined names
      27: 'from lazr.enum._json import *' used; unable to detect undefined names
      28: redefinition of unused '_all' from line 26
      29: 'from lazr.enum.interfaces import *' used; unable to detect undefined names
./src/lazr/enum/_enum.py
      29: redefinition of unused 'removeAllProxies' from line 27
      29: E261 at least two spaces before inline comment
      44: E261 at least two spaces before inline comment

[Curtis Hovey (sinzui)]

Thank you.

review: Approve (code)

=== modified file '.bzrignore'
--- .bzrignore	2009-03-24 14:12:06 +0000
+++ .bzrignore	2012-04-18 04:43:17 +0000
@@ -9,3 +9,5 @@
 build
 *.egg
 dist
+eggs
+MANIFEST

=== modified file '_bootstrap/bootstrap.py'
--- _bootstrap/bootstrap.py	2009-03-24 14:12:06 +0000
+++ _bootstrap/bootstrap.py	2012-04-18 04:43:17 +0000
@@ -1,6 +1,6 @@
 ##############################################################################
 #
-# Copyright (c) 2006 Zope Corporation and Contributors.
+# Copyright (c) 2006 Zope Foundation and Contributors.
 # All Rights Reserved.
 #
 # This software is subject to the provisions of the Zope Public License,
@@ -16,25 +16,10 @@
 Simply run this script in a directory containing a buildout.cfg.
 The script accepts buildout command-line options, so you can
 use the -c option to specify an alternate configuration file.
-
-$Id$
 """
 
-import os, shutil, sys, tempfile, urllib2
-
-tmpeggs = tempfile.mkdtemp()
-
-is_jython = sys.platform.startswith('java')
-
-try:
-    import pkg_resources
-except ImportError:
-    ez = {}
-    exec urllib2.urlopen('http://peak.telecommunity.com/dist/ez_setup.py'
-                         ).read() in ez
-    ez['use_setuptools'](to_dir=tmpeggs, download_delay=0)
-
-    import pkg_resources
+import os, shutil, sys, tempfile, textwrap, urllib, urllib2, subprocess
+from optparse import OptionParser
 
 if sys.platform == 'win32':
     def quote(c):
@@ -43,35 +28,233 @@
         else:
             return c
 else:
-    def quote (c):
-        return c
-
-cmd = 'from setuptools.command.easy_install import main; main()'
-ws  = pkg_resources.working_set
+    quote = str
+
+# See zc.buildout.easy_install._has_broken_dash_S for motivation and comments.
+stdout, stderr = subprocess.Popen(
+    [sys.executable, '-Sc',
+     'try:\n'
+     '    import ConfigParser\n'
+     'except ImportError:\n'
+     '    print 1\n'
+     'else:\n'
+     '    print 0\n'],
+    stdout=subprocess.PIPE, stderr=subprocess.PIPE).communicate()
+has_broken_dash_S = bool(int(stdout.strip()))
+
+# In order to be more robust in the face of system Pythons, we want to
+# run without site-packages loaded.  This is somewhat tricky, in
+# particular because Python 2.6's distutils imports site, so starting
+# with the -S flag is not sufficient.  However, we'll start with that:
+if not has_broken_dash_S and 'site' in sys.modules:
+    # We will restart with python -S.
+    args = sys.argv[:]
+    args[0:0] = [sys.executable, '-S']
+    args = map(quote, args)
+    os.execv(sys.executable, args)
+# Now we are running with -S.  We'll get the clean sys.path, import site
+# because distutils will do it later, and then reset the path and clean
+# out any namespace packages from site-packages that might have been
+# loaded by .pth files.
+clean_path = sys.path[:]
+import site
+sys.path[:] = clean_path
+for k, v in sys.modules.items():
+    if k in ('setuptools', 'pkg_resources') or (
+        hasattr(v, '__path__') and
+        len(v.__path__)==1 and
+        not os.path.exists(os.path.join(v.__path__[0],'__init__.py'))):
+        # This is a namespace package.  Remove it.
+        sys.modules.pop(k)
+
+is_jython = sys.platform.startswith('java')
+
+setuptools_source = 'http://peak.telecommunity.com/dist/ez_setup.py'
+distribute_source = 'http://python-distribute.org/distribute_setup.py'
+
+# parsing arguments
+def normalize_to_url(option, opt_str, value, parser):
+    if value:
+        if '://' not in value: # It doesn't smell like a URL.
+            value = 'file://%s' % (
+                urllib.pathname2url(
+                    os.path.abspath(os.path.expanduser(value))),)
+        if opt_str == '--download-base' and not value.endswith('/'):
+            # Download base needs a trailing slash to make the world happy.
+            value += '/'
+    else:
+        value = None
+    name = opt_str[2:].replace('-', '_')
+    setattr(parser.values, name, value)
+
+usage = '''\
+[DESIRED PYTHON FOR BUILDOUT] bootstrap.py [options]
+
+Bootstraps a buildout-based project.
+
+Simply run this script in a directory containing a buildout.cfg, using the
+Python that you want bin/buildout to use.
+
+Note that by using --setup-source and --download-base to point to
+local resources, you can keep this script from going over the network.
+'''
+
+parser = OptionParser(usage=usage)
+parser.add_option("-v", "--version", dest="version",
+                          help="use a specific zc.buildout version")
+parser.add_option("-d", "--distribute",
+                   action="store_true", dest="use_distribute", default=False,
+                   help="Use Distribute rather than Setuptools.")
+parser.add_option("--setup-source", action="callback", dest="setup_source",
+                  callback=normalize_to_url, nargs=1, type="string",
+                  help=("Specify a URL or file location for the setup file. "
+                        "If you use Setuptools, this will default to " +
+                        setuptools_source + "; if you use Distribute, this "
+                        "will default to " + distribute_source +"."))
+parser.add_option("--download-base", action="callback", dest="download_base",
+                  callback=normalize_to_url, nargs=1, type="string",
+                  help=("Specify a URL or directory for downloading "
+                        "zc.buildout and either Setuptools or Distribute. "
+                        "Defaults to PyPI."))
+parser.add_option("--eggs",
+                  help=("Specify a directory for storing eggs.  Defaults to "
+                        "a temporary directory that is deleted when the "
+                        "bootstrap script completes."))
+parser.add_option("-t", "--accept-buildout-test-releases",
+                  dest='accept_buildout_test_releases',
+                  action="store_true", default=False,
+                  help=("Normally, if you do not specify a --version, the "
+                        "bootstrap script and buildout gets the newest "
+                        "*final* versions of zc.buildout and its recipes and "
+                        "extensions for you.  If you use this flag, "
+                        "bootstrap and buildout will get the newest releases "
+                        "even if they are alphas or betas."))
+parser.add_option("-c", None, action="store", dest="config_file",
+                   help=("Specify the path to the buildout configuration "
+                         "file to be used."))
+
+options, args = parser.parse_args()
+
+# if -c was provided, we push it back into args for buildout's main function
+if options.config_file is not None:
+    args += ['-c', options.config_file]
+
+if options.eggs:
+    eggs_dir = os.path.abspath(os.path.expanduser(options.eggs))
+else:
+    eggs_dir = tempfile.mkdtemp()
+
+if options.setup_source is None:
+    if options.use_distribute:
+        options.setup_source = distribute_source
+    else:
+        options.setup_source = setuptools_source
+
+if options.accept_buildout_test_releases:
+    args.append('buildout:accept-buildout-test-releases=true')
+args.append('bootstrap')
+
+try:
+    import pkg_resources
+    import setuptools # A flag.  Sometimes pkg_resources is installed alone.
+    if not hasattr(pkg_resources, '_distribute'):
+        raise ImportError
+except ImportError:
+    ez_code = urllib2.urlopen(
+        options.setup_source).read().replace('\r\n', '\n')
+    ez = {}
+    exec ez_code in ez
+    setup_args = dict(to_dir=eggs_dir, download_delay=0)
+    if options.download_base:
+        setup_args['download_base'] = options.download_base
+    if options.use_distribute:
+        setup_args['no_fake'] = True
+    ez['use_setuptools'](**setup_args)
+    if 'pkg_resources' in sys.modules:
+        reload(sys.modules['pkg_resources'])
+    import pkg_resources
+    # This does not (always?) update the default working set.  We will
+    # do it.
+    for path in sys.path:
+        if path not in pkg_resources.working_set.entries:
+            pkg_resources.working_set.add_entry(path)
+
+cmd = [quote(sys.executable),
+       '-c',
+       quote('from setuptools.command.easy_install import main; main()'),
+       '-mqNxd',
+       quote(eggs_dir)]
+
+if not has_broken_dash_S:
+    cmd.insert(1, '-S')
+
+find_links = options.download_base
+if not find_links:
+    find_links = os.environ.get('bootstrap-testing-find-links')
+if find_links:
+    cmd.extend(['-f', quote(find_links)])
+
+if options.use_distribute:
+    setup_requirement = 'distribute'
+else:
+    setup_requirement = 'setuptools'
+ws = pkg_resources.working_set
+setup_requirement_path = ws.find(
+    pkg_resources.Requirement.parse(setup_requirement)).location
+env = dict(
+    os.environ,
+    PYTHONPATH=setup_requirement_path)
+
+requirement = 'zc.buildout'
+version = options.version
+if version is None and not options.accept_buildout_test_releases:
+    # Figure out the most recent final version of zc.buildout.
+    import setuptools.package_index
+    _final_parts = '*final-', '*final'
+    def _final_version(parsed_version):
+        for part in parsed_version:
+            if (part[:1] == '*') and (part not in _final_parts):
+                return False
+        return True
+    index = setuptools.package_index.PackageIndex(
+        search_path=[setup_requirement_path])
+    if find_links:
+        index.add_find_links((find_links,))
+    req = pkg_resources.Requirement.parse(requirement)
+    if index.obtain(req) is not None:
+        best = []
+        bestv = None
+        for dist in index[req.project_name]:
+            distv = dist.parsed_version
+            if _final_version(distv):
+                if bestv is None or distv > bestv:
+                    best = [dist]
+                    bestv = distv
+                elif distv == bestv:
+                    best.append(dist)
+        if best:
+            best.sort()
+            version = best[-1].version
+if version:
+    requirement = '=='.join((requirement, version))
+cmd.append(requirement)
 
 if is_jython:
     import subprocess
-    
-    assert subprocess.Popen([sys.executable] + ['-c', quote(cmd), '-mqNxd', 
-           quote(tmpeggs), 'zc.buildout'], 
-           env=dict(os.environ,
-               PYTHONPATH=
-               ws.find(pkg_resources.Requirement.parse('setuptools')).location
-               ),
-           ).wait() == 0
-
-else:
-    assert os.spawnle(
-        os.P_WAIT, sys.executable, quote (sys.executable),
-        '-c', quote (cmd), '-mqNxd', quote (tmpeggs), 'zc.buildout',
-        dict(os.environ,
-            PYTHONPATH=
-            ws.find(pkg_resources.Requirement.parse('setuptools')).location
-            ),
-        ) == 0
-
-ws.add_entry(tmpeggs)
-ws.require('zc.buildout')
+    exitcode = subprocess.Popen(cmd, env=env).wait()
+else: # Windows prefers this, apparently; otherwise we would prefer subprocess
+    exitcode = os.spawnle(*([os.P_WAIT, sys.executable] + cmd + [env]))
+if exitcode != 0:
+    sys.stdout.flush()
+    sys.stderr.flush()
+    print ("An error occurred when trying to install zc.buildout. "
+           "Look above this message for any errors that "
+           "were output by easy_install.")
+    sys.exit(exitcode)
+
+ws.add_entry(eggs_dir)
+ws.require(requirement)
 import zc.buildout.buildout
-zc.buildout.buildout.main(sys.argv[1:] + ['bootstrap'])
-shutil.rmtree(tmpeggs)
+zc.buildout.buildout.main(args)
+if not options.eggs: # clean up temporary egg directory
+    shutil.rmtree(eggs_dir)

=== modified file 'ez_setup.py'
--- ez_setup.py	2009-03-24 14:12:06 +0000
+++ ez_setup.py	2012-04-18 04:43:17 +0000
@@ -14,7 +14,7 @@
 This file can also be run as a script to install or upgrade setuptools.
 """
 import sys
-DEFAULT_VERSION = "0.6c8"
+DEFAULT_VERSION = "0.6c11"
 DEFAULT_URL     = "http://pypi.python.org/packages/%s/s/setuptools/" % sys.version[:3]
 
 md5_data = {

=== modified file 'src/lazr/enum/NEWS.txt'
--- src/lazr/enum/NEWS.txt	2011-04-20 02:05:19 +0000
+++ src/lazr/enum/NEWS.txt	2012-04-18 04:43:17 +0000
@@ -2,6 +2,13 @@
 NEWS for lazr.enum
 ==================
 
+1.1.4 (2012-04-18)
+==================
+
+- Support for serialising enums to/from json (lp:984549)
+- Items which are not in an enumerator always compare as False (lp:524259)
+- Fix the licence statement in _enum.py to be LGPLv3 not LGPLv3+ (lp:526484)
+
 1.1.3 (2011-04-20)
 ==================
 

=== modified file 'src/lazr/enum/README.txt'
--- src/lazr/enum/README.txt	2011-03-01 22:28:23 +0000
+++ src/lazr/enum/README.txt	2012-04-18 04:43:17 +0000
@@ -169,6 +169,11 @@
     >>> apple < orange
     True
 
+Items which are not in an enumerator always compare as False.
+    >>> from lazr.enum import Item
+    >>> Item('a') == Item('b')
+    False
+
 The string representation of an Item is the title, and the representation
 also shows the enumeration that the Item is from.
 
@@ -407,6 +412,35 @@
     Mirrored 1
     Imported 2
 
+============
+JSON Support
+============
+
+Enumerated types instances can be serialised to/from json. This library provides the
+necessary encode and decode classes which can be used directly or as part of the
+lazr.json package where they are registered as default handlers for lazr enums.
+
+A enum instance is serialised as a dict containing:
+- the enumerated type name as per the enumerated_type_registry
+- the enum instance name
+
+    >>> import json
+    >>> from lazr.enum import EnumJSONEncoder
+
+    >>> json_enum = json.dumps(Fruit.APPLE, cls=EnumJSONEncoder)
+    >>> print json_enum
+    {"type": "Fruit", "name": "APPLE"}
+
+To deserialse, we can specify a json object_hook as follows.
+This is done transparently when using the lazr.json package.
+
+    >>> def fruit_enum_decoder(value_dict):
+    ...      return EnumJSONDecoder.from_dict(Fruit, value_dict)
+
+    >>> from lazr.enum import EnumJSONDecoder
+    >>> json.loads(json_enum, object_hook=fruit_enum_decoder)
+    <Item Fruit.APPLE, Apple>
+
 .. pypi description ends here
 
 ===============

=== modified file 'src/lazr/enum/__init__.py'
--- src/lazr/enum/__init__.py	2009-08-31 19:30:41 +0000
+++ src/lazr/enum/__init__.py	2012-04-18 04:43:17 +0000
@@ -24,8 +24,11 @@
 # exported.
 from lazr.enum._enum import *
 from lazr.enum._enum import __all__ as _all
+from lazr.enum._json import *
+from lazr.enum._json import __all__ as _jall
 from lazr.enum.interfaces import *
 from lazr.enum.interfaces import __all__ as _iall
 __all__ = []
 __all__.extend(_all)
 __all__.extend(_iall)
+__all__.extend(_jall)

=== modified file 'src/lazr/enum/_enum.py'
--- src/lazr/enum/_enum.py	2011-03-01 22:28:23 +0000
+++ src/lazr/enum/_enum.py	2012-04-18 04:43:17 +0000
@@ -4,8 +4,7 @@
 #
 # lazr.enum is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or (at your
-# option) any later version.
+# the Free Software Foundation, version 3 of the License.
 #
 # lazr.enum is distributed in the hope that it will be useful, but WITHOUT
 # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
@@ -17,20 +16,6 @@
 
 __metaclass__ = type
 
-import itertools
-import operator
-import sys
-import warnings
-
-from zope.interface import implements
-from zope.schema.interfaces import ITitledTokenizedTerm, IVocabularyTokenized
-try:
-    from zope.proxy import removeAllProxies
-except ImportError:
-    removeAllProxies = lambda obj: obj # no-op
-
-from lazr.enum.interfaces import IEnumeratedType
-
 __all__ = [
     'BaseItem',
     'DBEnumeratedType',
@@ -46,6 +31,21 @@
     'MetaDBEnum', # needed for configure.zcml
     ]
 
+import itertools
+import operator
+import sys
+import warnings
+
+from zope.interface import implements
+from zope.schema.interfaces import ITitledTokenizedTerm, IVocabularyTokenized
+try:
+    from zope.proxy import removeAllProxies
+except ImportError:
+    removeAllProxies = lambda obj: obj # no-op
+
+from lazr.enum.interfaces import IEnumeratedType
+
+
 def proxy_isinstance(obj, cls):
     """Test whether an object is an instance of a type.
 
@@ -54,6 +54,7 @@
     """
     return isinstance(removeAllProxies(obj), cls)
 
+
 def docstring_to_title_descr(string):
     """When given a classically formatted docstring, returns a tuple
     (title, description).
@@ -97,8 +98,8 @@
             break
     else:
         raise ValueError
-    assert not lines[num+1].strip()
-    descrlines = lines[num+2:]
+    assert not lines[num + 1].strip()
+    descrlines = lines[num + 2:]
     descr1 = descrlines[0]
     indent = len(descr1) - len(descr1.lstrip())
     descr = '\n'.join([line[indent:] for line in descrlines])
@@ -163,6 +164,12 @@
                 stacklevel=stacklevel)
             return False
         elif proxy_isinstance(other, BaseItem):
+            if (not getattr(self, 'enum', None)
+                or not getattr(other, 'enum', None)):
+                warnings.warn('comparison of Items which are not '
+                              'enumerated types',
+                    stacklevel=stacklevel)
+                return False
             return (self.name == other.name and
                     self.enum == other.enum)
         else:
@@ -201,7 +208,7 @@
     @staticmethod
     def construct(other_item):
         """Create an Item based on the other_item."""
-        item = DBItem(other_item.value, other_item.title, 
+        item = DBItem(other_item.value, other_item.title,
                       other_item.description, other_item.url)
         item.sortkey = other_item.sortkey
         return item
@@ -253,13 +260,16 @@
     def __init__(self, items, mapping):
         self.items = items
         self.mapping = mapping
+
     def __getitem__(self, key):
         if key in self.mapping:
             return self.mapping[key]
         else:
             raise KeyError(key)
+
     def __iter__(self):
         return self.items.__iter__()
+
     def __len__(self):
         return len(self.items)
 

=== added file 'src/lazr/enum/_json.py'
--- src/lazr/enum/_json.py	1970-01-01 00:00:00 +0000
+++ src/lazr/enum/_json.py	2012-04-18 04:43:17 +0000
@@ -0,0 +1,54 @@
+# Copyright 2012 Canonical Ltd.  All rights reserved.
+#
+# This file is part of lazr.enum
+#
+# lazr.enum is free software: you can redistribute it and/or modify it
+# under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# lazr.enum is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
+# License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with lazr.enum.  If not, see <http://www.gnu.org/licenses/>.
+
+__metaclass__ = type
+
+__all__ = [
+    'EnumJSONDecoder',
+    'EnumJSONEncoder',
+    ]
+
+import json
+from lazr.enum import (
+    BaseItem,
+    enumerated_type_registry,
+    )
+
+
+class EnumJSONEncoder(json.JSONEncoder):
+    """A JSON encoder that understands enum objects.
+
+    Objects are serialized using their type and enum name.
+    """
+    def default(self, obj):
+        if isinstance(obj, BaseItem):
+            return {
+                'type': obj.enum.name,
+                'name': obj.name}
+        return json.JSONEncoder.default(self, obj)
+
+
+class EnumJSONDecoder():
+    """A decoder can reconstruct enums from a JSON dict.
+
+    Objects are reconstructed using their type and enum name.
+    """
+    @classmethod
+    def from_dict(cls, class_, values):
+        type_name = values['type']
+        item_name = values['name']
+        return enumerated_type_registry[type_name].items[item_name]

=== modified file 'src/lazr/enum/version.txt'
--- src/lazr/enum/version.txt	2011-04-20 02:05:19 +0000
+++ src/lazr/enum/version.txt	2012-04-18 04:43:17 +0000
@@ -1,1 +1,1 @@
-1.1.3
+1.1.4