Merge lp:~leonardr/lazr.restful/entry-introduced-in-version into lp:lazr.restful

[Leonard Richardson]

For the first time ever, this branch makes it possible to publish an entry only in certain versions of the web service. Previously when you called export_as_webservice_entry(), the entry was created (in slightly varying forms) for every single version. Now you can make IFoo show up starting in '1.0' instead of 'beta', or have IBar show up in 'beta' but not in '1.0'. You can also give the entry different names in different versions (to fix a typo, or because the terminology changed). So IFoo might be called "foo/foos" in beta, and "foo/fooes" in 1.0.

To see how this works, look at the test classes defined in test_declarations.py. Here are some simpler ones:

class INotInitiallyExported(Interface):
    # An entry that's not exported in the first version of the web
    # service.
    export_as_webservice_entry(as_of="2.0")

class INotPresentInLaterVersion(Interface):
    # An entry that's only exported in the first version of the web
    # service.
    export_as_webservice_entry(
        versioned_annotations=[('2.0', dict(exported=False))])

This work is unfinished, but what I have doesn't break anything, and it's almost exactly 800 lines, so let's review it. Notable unfinished bits:

1. I have not tested the multiversion code in conjunction with contributes_to, and I don't know whether it works.

2. A Reference field can be a link to an entry that isn't even exposed in the current version. The return value of a named operation can also be an entry that isn't exposed in the current version. I need to add checks for this when the web service is being built, or it will cause huge problems at runtime. (This is why I didn't implement the entry code this way in the first place.)

Features I considered but rejected:

1. You can say that IFoo.myfield is published in 2.0, even if IFoo itself is not published in 2.0. Enforcing this would stop some mistakes, but it would require you to un-publish every one of IFoo's fields as a prerequisite for un-publishing IFoo itself.

How it works:

export_as_webservice_entry now takes an 'as_of' argument, just like the exported() function used on fields. If require_explicit_versions is True, then as_of is *required*, just like it is for fields.

The tags describing a webservice entry across versions (eg. the plural name is "foos" in beta and "fooes" in 1.0) are now stored in a VersionedDict, just like they are for fields. Once the tags are gathered, the VersionDict is normalized, so that it includes a dictionary for every single web service version. Then I iterate over the versions as before, creating an entry interface for each version *except* the ones for which this entry is not published.

Figuring out the complete definition of an entry is now the same kind of thing as figuring out the definition of one of its fields. As such, I've refactored some code and started using it for both fields and entries. Notably, the helper function _enforce_explicit_version(), which makes sure you specified as_of if it's required, and the method VersionedDict.normalize_for_versions(), which makes sure the user didn't define versions out of order, and "fills in the blanks" so that the dictionary includes a set of annotations for every single version.

I had a bad cold while I wrote this, but I think it's not too crazy.

[Ian Booth (wallyworld)]

Hi Leonard,

This looks good to me. I have some small fixme's:

diff line 36: param should be "versioned_annotations" not "annotations"
diff line 122: you define stack = entry_tags.stack presumably to make less typing below but then forget to use stack
Perhaps you could tidy up the zope.security.management imports as a drive by in test_utils? The ones in test_declarations also need some lovin' if you are so inclined - there's unused ones as well as formatting issues.

A concern/question:

>> def normalize_for_versions(self, versions, default_dictionary={}, error_prefix=''):

The default_dictionary argument defaults to {} but this is mutable. This can lead to unintended side effects since default args are only evaluated once when the function is defined. It doesn't look like anything bad happens in this case but my preference is to use default_dictionary=dict() just to be safe and explicitly correct in all cases.

A question:

In normalize_for_versions(self, versions, ...), do the later, more recent versions appear towards the front of the versions list? Perhaps the docstring could mention this just to clarify since being unfamiliar with the implementation, it was unclear to me without trying to figure it out.

A suggestion:

In places, instead of using 2-tuple's, eg versioned_annotations parameter to export_as_webservice_entry(), you could consider using a namedtuple. This will make code like:

    if entry_tags.stack[0][0] is None:
        entry_tags.stack[0] = (earliest_version, entry_tags.stack[0][1])

much easier to read, especially for people not previously 100% familiar with the code. It would become something like:

    if entry_tags.stack[0].version is None:
        entry_tags.stack[0] = (earliest_version, entry_tags.stack[0].annotations)

Also the return value of generate_entry_interfaces. So

interfaces = generate_entry_interfaces(...)
... interfaces[0][0]
... interfaces[0][1]

becomes

interfaces = generate_entry_interfaces(...)
... interfaces[0].version
... interfaces[0].interface

review: Needs Fixing

[Tim Penhey (thumper)]

Does lazr.restful use testtools for the TestCase?

If it does, assertRaises returns the exception, so
test_non_existent_annotation_fails could be somewhat
simplified.

It seems that normalize_for_versions is only passed
no dict through in tests. I believe the more used
approach is to have the default value to be None, and
have something like:

  if default_dictionary is None:
    default_dictionary = {}

I wish we had a way to have contracts on the params.
In C++ it would be a "const" dict. Here though we are
doing a deep copy. My preference, even though you don't
mutate the dict now, would be to use None as the param.

review: Needs Fixing (code)

[Leonard Richardson (leonardr)]

> Does lazr.restful use testtools for the TestCase?
>
> If it does, assertRaises returns the exception, so
> test_non_existent_annotation_fails could be somewhat
> simplified.

I tried this; the problem is that the exception is raised *during a class definition*. I decided that the try/catch was more readable than calling assertRaises on the 'type' function.

[lp:~leonardr/lazr.restful/entry-introduced-in-version]

198. By Leonard Richardson on 2011-03-17

Cleaned up imports.

199. By Leonard Richardson on 2011-03-17

Don't set a mutable defalt for default_dictionary.

200. By Leonard Richardson on 2011-03-17

VersionedDict is now a stack of namedtuples, for easier comprehension.

201. By Leonard Richardson on 2011-03-17

Use the namedtuple for everything, and hide the details of namedtuples from declarations.py by giving it rename_version to use instead.

[Leonard Richardson (leonardr)]

Here's my incremental diff:

http://pastebin.ubuntu.com/581586/

The namedtuple idea is a good one. It forced me to improve the encapsulation of VersionedDict by writing the rename_version() method. I'm a little worried about code that violates encapsulation by sticking non-namedtuples into a VersionedDict, since this branch will cause such code to break. But lazr.restful itself no longer contains any such code, so I'm not _too_ worried about it.

[lp:~leonardr/lazr.restful/entry-introduced-in-version]

202. By Leonard Richardson on 2011-03-17

generate_entry_interfaces and generate_entry_adapters now return VersionedObject namedtuples.

203. By Leonard Richardson on 2011-03-17

Consistently use VersionedObject instead of VersionedDict.

[Leonard Richardson (leonardr)]

Here's a better diff. I use one VersionedObject namedtuple class for all purposes: interfaces, adapters, and annotation dictionaries.

http://pastebin.ubuntu.com/581602/

[Ian Booth (wallyworld)]

Thanks for incorporating the suggested changes. The use of namedtuple does make the code more readable.

review: Approve (*code)

=== modified file 'src/lazr/restful/declarations.py'
--- src/lazr/restful/declarations.py	2011-03-10 13:53:18 +0000
+++ src/lazr/restful/declarations.py	2011-03-17 14:24:12 +0000
@@ -57,7 +57,10 @@
 
 from lazr.delegates import Passthrough
 
-from lazr.restful.fields import CollectionField, Reference
+from lazr.restful.fields import (
+    CollectionField,
+    Reference,
+    )
 from lazr.restful.interface import copy_field
 from lazr.restful.interfaces import (
     ICollection,
@@ -72,11 +75,21 @@
     LAZR_WEBSERVICE_NS,
     )
 from lazr.restful import (
-    Collection, Entry, EntryAdapterUtility, ResourceOperation, ObjectLink)
+    Collection,
+    Entry,
+    EntryAdapterUtility,
+    ResourceOperation,
+    ObjectLink,
+    )
 from lazr.restful.security import protect_schema
 from lazr.restful.utils import (
-    camelcase_to_underscore_separated, get_current_web_service_request,
-    make_identifier_safe, VersionedDict, is_total_size_link_active)
+    camelcase_to_underscore_separated,
+    get_current_web_service_request,
+    make_identifier_safe,
+    VersionedDict,
+    VersionedObject,
+    is_total_size_link_active,
+    )
 
 LAZR_WEBSERVICE_EXPORTED = '%s.exported' % LAZR_WEBSERVICE_NS
 LAZR_WEBSERVICE_MUTATORS = '%s.exported.mutators' % LAZR_WEBSERVICE_NS
@@ -88,6 +101,16 @@
     'destructor', 'factory', 'read_operation', 'write_operation',
     REMOVED_OPERATION_TYPE)
 
+# These are the only valid keys to be found in an entry's
+# version-specific annotation dictionary.
+ENTRY_ANNOTATION_KEYS = set([
+    'contributes_to',
+    'exported',
+    'plural_name',
+    'publish_web_link',
+    'singular_name',
+    ])
+
 
 class REQUEST_USER:
     """Marker class standing in for the user of the current request.
@@ -130,7 +153,8 @@
 
 
 def export_as_webservice_entry(singular_name=None, plural_name=None,
-                               contributes_to=None, publish_web_link=True):
+                               contributes_to=None, publish_web_link=True,
+                               as_of=None, versioned_annotations=None):
     """Mark the content interface as exported on the web service as an entry.
 
     If contributes_to is a non-empty sequence of Interfaces, this entry will
@@ -149,11 +173,24 @@
         set to True, the representation of this entry will include a
         web_link pointing to the corresponding page on the website. If
         False, web_link will be omitted.
+    :param as_of: The first version of the web service to feature this entry.
+    :param versioned_annotations: A list of 2-tuples (version,
+        {params}), with more recent web service versions earlier in
+        the list and older versions later in the list.
+
+        A 'params' dictionary may contain the key 'exported', which
+        controls whether or not to publish the entry at all in the
+        given version. It may also contain the keys 'singular_name',
+        'plural_name', 'contributes_to', or 'publish_web_link', which
+        work just like the corresponding arguments to this method.
     """
     _check_called_from_interface_def('export_as_webservice_entry()')
     def mark_entry(interface):
         """Class advisor that tags the interface once it is created."""
         _check_interface('export_as_webservice_entry()', interface)
+
+        annotation_stack = VersionedDict()
+
         if singular_name is None:
             # By convention, interfaces are called IWord1[Word2...]. The
             # default behavior assumes this convention and yields a
@@ -162,17 +199,37 @@
                 interface.__name__[1:])
         else:
             my_singular_name = singular_name
-        if plural_name is None:
-            # Apply default pluralization rule.
-            my_plural_name = my_singular_name + 's'
-        else:
-            my_plural_name = plural_name
-
-        interface.setTaggedValue(
-            LAZR_WEBSERVICE_EXPORTED, dict(
-                type=ENTRY_TYPE, singular_name=my_singular_name,
-                plural_name=my_plural_name, contributes_to=contributes_to,
-                publish_web_link=publish_web_link))
+
+        # Turn the named arguments into a dictionary for the first
+        # exported version.
+        initial_version = dict(
+            type=ENTRY_TYPE, singular_name=my_singular_name,
+            plural_name=plural_name, contributes_to=contributes_to,
+            publish_web_link=publish_web_link, exported=True,
+            _as_of_was_used=(not as_of is None))
+
+        afterwards = versioned_annotations or []
+        for version, annotations in itertools.chain(
+            [(as_of, initial_version)], afterwards):
+            annotation_stack.push(version)
+
+            for key, value in annotations.items():
+                if annotations != initial_version:
+                    # Make sure that the 'annotations' dict
+                    # contains only recognized annotations.
+                    if key not in ENTRY_ANNOTATION_KEYS:
+                        raise ValueError(
+                            'Unrecognized annotation for version "%s": '
+                            '"%s"' % (version, key))
+                annotation_stack[key] = value
+            # If this version provides a singular name but not a
+            # plural name, apply the default pluralization rule.
+            if (annotations.get('singular_name') is not None
+                and annotations.get('plural_name') is None):
+                annotation_stack['plural_name'] = (
+                    annotations['singular_name'] + 's')
+
+        interface.setTaggedValue(LAZR_WEBSERVICE_EXPORTED, annotation_stack)
 
         # Set the name of the fields that didn't specify it using the
         # 'export_as' parameter in exported(). This must be done here,
@@ -908,8 +965,7 @@
     _check_tagged_interface(interface, 'entry')
     versions = list(versions)
 
-    # First off, make sure any given version defines only one
-    # destructor method.
+    # Make sure any given version defines only one destructor method.
     destructor_for_version = {}
     for name, method in interface.namesAndDescriptions(True):
         if not IMethod.providedBy(method):
@@ -929,10 +985,33 @@
                             destructor.__name__))
                 destructor_for_version[version] = method
 
+    # Build a data set describing this entry, as it appears in each
+    # version of the web service in which it appears at all.
+    entry_tags = interface.queryTaggedValue(LAZR_WEBSERVICE_EXPORTED)
+    stack = entry_tags.stack
+
+    earliest_version = versions[0]
+    # Now that we know the name of the earliest version, get rid of
+    # any None at the beginning of the stack.
+    if stack[0].version is None:
+        entry_tags.rename_version(None, earliest_version)
+
+    # If require_explicit_versions is set, make sure the first version
+    # to set 'exported' also sets '_as_of_was_used'.
+    _enforce_explicit_version(
+        entry_tags, 'Entry "%s": ' % interface.__name__)
+
+    # Make sure there's one set of entry tags for every version of the
+    # web service, including versions in which this entry is not
+    # published.
+    entry_tags.normalize_for_versions(
+        versions, {'type': ENTRY_TYPE, 'exported': False},
+        'Interface "%s": ' % interface.__name__)
+
     # Next, we'll normalize each published field. A normalized field
-    # has a set of annotations for every version. We'll make a list of
-    # the published fields, which we'll iterate over once for each
-    # version.
+    # has a set of annotations for every version in which the entry is
+    # published. We'll make a list of the published fields, which
+    # we'll iterate over once for each version.
     tags_for_published_fields = []
     for iface in itertools.chain([interface], contributors):
         for name, field in getFields(iface).items():
@@ -943,15 +1022,18 @@
             error_message_prefix = (
                 'Field "%s" in interface "%s": ' % (name, iface.__name__))
             _normalize_field_annotations(field, versions, error_message_prefix)
-            tags_for_published_fields.append((name, field, tag_stack.stack))
+            tags_for_published_fields.append((name, field, tag_stack))
 
     generated_interfaces = []
+    entry_tags = interface.queryTaggedValue(LAZR_WEBSERVICE_EXPORTED)
     for version in versions:
+        entry_tags_this_version = entry_tags.dict_for_name(version)
+        if entry_tags_this_version.get('exported') is False:
+            # Don't define an entry interface for this version at all.
+            continue
         attrs = {}
         for name, field, tag_stack in tags_for_published_fields:
-            tags = [tags for tag_version, tags in tag_stack
-                    if tag_version == version]
-            tags = tags[0]
+            tags = tag_stack.dict_for_name(version)
             if tags.get('exported') is False:
                 continue
             mutated_by, mutated_by_annotations = tags.get(
@@ -978,12 +1060,12 @@
             class_name, bases=(IEntry, ), attrs=attrs,
             __doc__=interface.__doc__, __module__=interface.__module__)
 
-        tag = interface.queryTaggedValue(LAZR_WEBSERVICE_EXPORTED)
+        versioned_tag = entry_tags.dict_for_name(version)
         entry_interface.setTaggedValue(LAZR_WEBSERVICE_NAME, dict(
-            singular=tag['singular_name'],
-            plural=tag['plural_name'],
-            publish_web_link=tag['publish_web_link']))
-        generated_interfaces.append((version, entry_interface))
+            singular=versioned_tag['singular_name'],
+            plural=versioned_tag['plural_name'],
+            publish_web_link=versioned_tag['publish_web_link']))
+        generated_interfaces.append(VersionedObject(version, entry_interface))
     return generated_interfaces
 
 
@@ -1082,7 +1164,7 @@
         classImplements(factory, webservice_interface)
         protect_schema(
             factory, webservice_interface, write_permission=CheckerPublic)
-        adapters.append((version, factory))
+        adapters.append(VersionedObject(version, factory))
     return adapters
 
 
@@ -1345,14 +1427,14 @@
     earliest_version = versions[0]
     stack = versioned_dict.stack
 
-    if (len(stack) >= 2 and stack[0][0] is None
-        and stack[1][0] == earliest_version):
+    if (len(stack) >= 2 and stack[0].version is None
+        and stack[1].version == earliest_version):
         # The behavior of the earliest version is defined with keyword
         # arguments, but the first explicitly-defined version also
         # refers to the earliest version. We need to consolidate the
         # versions.
-        implicit_earliest_version = stack[0][1]
-        explicit_earliest_version = stack[1][1]
+        implicit_earliest_version = stack[0].object
+        explicit_earliest_version = stack[1].object
         for key, value in explicit_earliest_version.items():
             if key not in implicit_earliest_version:
                 # This key was defined for the earliest version using a
@@ -1373,26 +1455,17 @@
                 'for the earliest version: "%s" (from keyword arguments) '
                 'and "%s" (defined explicitly).' % (
                     key, implicit_value, value))
-        stack[0][1].update(stack[1][1])
+        stack[0].object.update(stack[1].object)
         stack.remove(stack[1])
 
     # Now that we know the name of the earliest version, get rid of
     # any None at the beginning of the stack.
-    if stack[0][0] is None:
-        stack[0] = (earliest_version, stack[0][1])
+    if stack[0].version is None:
+        versioned_dict.rename_version(None, earliest_version)
 
     # If require_explicit_versions is set, make sure the first version
     # to set 'exported' also sets '_as_of_was_used'.
-    if getUtility(IWebServiceConfiguration).require_explicit_versions:
-        for version, annotations in stack:
-            if annotations.get('exported', False):
-                if not annotations.get('_as_of_was_used', False):
-                    raise ValueError(
-                        error_prefix + (
-                            "Field was exported in version %s, but not"
-                            " by using as_of. The service configuration"
-                            " requires that you use as_of." % version))
-                break
+    _enforce_explicit_version(versioned_dict, error_prefix)
 
     # Make sure there is at most one mutator for the earliest version.
     # If there is one, move it from the mutator-specific dictionary to
@@ -1406,61 +1479,53 @@
             "found for earliest version %s." % earliest_version)
     earliest_mutator = implicit_earliest_mutator or explicit_earliest_mutator
     if earliest_mutator is not None:
-        stack[0][1]['mutator_annotations'] = earliest_mutator
-
-    # Do some error checking.
-    max_index = -1
-    for version, tags in versioned_dict.stack:
-        try:
-            version_index = versions.index(version)
-        except ValueError:
-            raise ValueError(
-                error_prefix + 'Unrecognized version "%s".' % version)
-        if version_index == max_index:
-            raise ValueError(
-                error_prefix + 'Duplicate annotations for version '
-                '"%s".' % version)
-        if version_index < max_index:
-            raise ValueError(
-                error_prefix + 'Version "%s" defined after '
-                'the later version "%s".' % (version, versions[max_index]))
-        max_index = version_index
+        stack[0].object['mutator_annotations'] = earliest_mutator
 
     # Fill out the stack so that there is one set of tags for each
     # version.
-    if stack[0][0] == earliest_version:
-        new_stack = [stack[0]]
-    else:
-        # The field is not initially exported.
-        new_stack = [(earliest_version, dict(exported=False))]
-    most_recent_tags = new_stack[0][1]
+    versioned_dict.normalize_for_versions(
+        versions, dict(exported=False), error_prefix)
+
+    # Make sure that a mutator defined in version N is inherited in
+    # version N+1.
     most_recent_mutator_tags = earliest_mutator
     for version in versions[1:]:
         most_recent_mutator_tags = mutator_annotations.get(
             version, most_recent_mutator_tags)
-        match = [(stack_version, stack_tags)
-                 for stack_version, stack_tags in stack
-                 if stack_version == version]
-        if len(match) == 0:
-            # This version has no tags of its own. Use a copy of the
-            # most recent tags.
-            new_stack.append((version, copy.deepcopy(most_recent_tags)))
-        else:
-            # This version has tags of its own. Use them unaltered,
-            # and set them up to be used in the future.
-            new_stack.append(match[0])
-            most_recent_tags = match[0][1]
-
         # Install a (possibly inherited) mutator for this field in
         # this version.
         if most_recent_mutator_tags is not None:
-            new_stack[-1][1]['mutator_annotations'] = copy.deepcopy(
+            tags_for_version = versioned_dict.dict_for_name(version)
+            tags_for_version['mutator_annotations'] = copy.deepcopy(
                 most_recent_mutator_tags)
 
-    versioned_dict.stack = new_stack
     return field
 
 
+def _enforce_explicit_version(versioned_dict, error_prefix):
+    """Raise ValueError if the explicit version requirement is not met.
+
+    If the configuration has `require_explicit_versions` set, then
+    the first version in the given VersionedDict to include a True
+    value for 'exported' must also include a True value for
+    '_as_of_was_used'.
+
+    :param versioned_dict: a VersionedDict.
+    :param error_prefix: a string to be prepended onto any error message.
+    """
+    if not getUtility(IWebServiceConfiguration).require_explicit_versions:
+        return
+
+    for version, annotations in versioned_dict.stack:
+        if annotations.get('exported', False):
+            if not annotations.get('_as_of_was_used', False):
+                raise ValueError(
+                    error_prefix + "Exported in version %s, but not"
+                    " by using as_of. The service configuration"
+                    " requires that you use as_of." % version)
+            break
+
+
 def _version_name(version):
     """Return a human-readable version name.
 

=== modified file 'src/lazr/restful/docs/utils.txt'
--- src/lazr/restful/docs/utils.txt	2010-01-20 15:21:38 +0000
+++ src/lazr/restful/docs/utils.txt	2011-03-17 14:24:12 +0000
@@ -65,11 +65,15 @@
     >>> sorted(stack.items())
     [('key', 'value')]
 
-You can pop a named dict off a stack: you'll get back a tuple
-(name, dict).
+You can pop a named dict off a stack: you'll get back a named tuple
+with 'version' and 'object' attributes. The 'object' is the
+dictionary.
 
-    >>> print stack.pop()
-    ('dict #1', {'key': 'value'})
+    >>> pair = stack.pop()
+    >>> print pair.version
+    dict #1
+    >>> print pair.object
+     {'key': 'value'}
 
     >>> stack.push('dict #1')
     >>> stack['key'] = 'value'
@@ -104,6 +108,19 @@
     >>> sorted(stack.items())
     [('key', 'Second dict value'), ('key2', {'key': 'value'})]
 
+You can find the dict for a given name with dict_for_name():
+
+    >>> for key, value in sorted(stack.dict_for_name('dict #1').items()):
+    ...     print "%s: %s" % (key, value)
+    key: value
+    key2: {'key': 'value'}
+
+You can rename a version with rename_version():
+
+    >>> stack.rename_version('dict #2', 'Renamed dict')
+    >>> stack.dict_names
+    ['dict #1', 'Renamed dict']
+
 Suppressing the copy operation
 ------------------------------
 
@@ -121,7 +138,7 @@
 The dictionary that defines 'key' and 'key2' is still there...
 
     >>> stack.dict_names
-    ['dict #1', 'dict #2', 'An empty dictionary']
+    ['dict #1', 'Renamed dict', 'An empty dictionary']
 
 ...but 'key' and 'key2' are no longer accessible.
 
@@ -141,8 +158,11 @@
 
 If you pop the formerly empty dictionary off the stack...
 
-    >>> print stack.pop()
-    ('An empty dictionary', {'key': 'Brand new value'})
+    >>> pair = stack.pop()
+    >>> print pair.version
+    An empty dictionary
+    >>> print pair.object
+    {'key': 'Brand new value'}
 
 ...'key' and 'key2' are visible again.
 

=== modified file 'src/lazr/restful/docs/webservice-declarations.txt'
--- src/lazr/restful/docs/webservice-declarations.txt	2011-03-08 19:59:46 +0000
+++ src/lazr/restful/docs/webservice-declarations.txt	2011-03-17 14:24:12 +0000
@@ -69,7 +69,9 @@
     ...             "%s: %s" %(key, format_value(value))
     ...             for key, value in sorted(tag.items()))
     >>> print_export_tag(IBook)
+    _as_of_was_used: False
     contributes_to: None
+    exported: True
     plural_name: 'books'
     publish_web_link: True
     singular_name: 'book'
@@ -148,6 +150,7 @@
     ...     export_as_webservice_entry(publish_web_link=False)
     ...     field = exported(TextLine(title=u"A field."))
     >>> print_export_tag(INotOnTheWebsite)
+    _as_of_was_used: False
     contributes_to: None
     ...
     publish_web_link: False
@@ -834,7 +837,9 @@
 into IDeveloper).
 
     >>> print_export_tag(IDeveloper)
+    _as_of_was_used: False
     contributes_to: [<InterfaceClass __builtin__.IUser>]
+    exported: True
     plural_name: 'developers'
     publish_web_link: True
     singular_name: 'developer'
@@ -983,9 +988,10 @@
 Services"). This web service only has one version, so there's only one
 adapter.
 
-    >>> [(version, entry_adapter_factory)] = entry_adapter_factories
-    >>> print version
+    >>> [factory] = entry_adapter_factories
+    >>> print factory.version
     beta
+    >>> entry_adapter_factory = factory.object
 
 The generated adapter provides the webservice interface:
 
@@ -1435,14 +1441,16 @@
 
 Generate the entry interface and adapter...
 
-    >>> hastext_entry_interfaces = generate_entry_interfaces(
+    >>> [hastext_entry_interface] = generate_entry_interfaces(
     ...     IHasText, [], 'beta')
-    >>> [(beta, hastext_entry_interface)] = hastext_entry_interfaces
-    >>> [(beta, hastext_entry_adapter_factory)] = generate_entry_adapters(
-    ...     IHasText, [], hastext_entry_interfaces)
+    >>> [hastext_entry_adapter_factory] = generate_entry_adapters(
+    ...     IHasText, [], [hastext_entry_interface])
 
     >>> obj = HasText()
-    >>> hastext_entry_adapter = hastext_entry_adapter_factory(obj, request)
+    >>> print hastext_entry_adapter_factory.version
+    beta
+    >>> hastext_entry_adapter = hastext_entry_adapter_factory.object(
+    ...     obj, request)
 
 ...and you'll have an object that invokes set_text() when you set the
 'text' attribute.
@@ -1456,7 +1464,7 @@
 The original interface defines 'text' as read-only, but the
 generated interface does not.
 
-    >>> hastext_entry_interface.get('text').readonly
+    >>> hastext_entry_interface.object.get('text').readonly
     False
 
 It's not necessary to expose the mutator method as a write operation.
@@ -1944,15 +1952,15 @@
     >>> foo, bar = generate_entry_interfaces(
     ...     IAmbiguousMultiVersion, [], 'foo', 'bar')
 
-    >>> print foo[0]
+    >>> print foo.version
     foo
-    >>> dump_entry_interface(foo[1])
+    >>> dump_entry_interface(foo.object)
     field2: TextLine
     foo_name: TextLine
 
-    >>> print bar[0]
+    >>> print bar.version
     bar
-    >>> dump_entry_interface(bar[1])
+    >>> dump_entry_interface(bar.object)
     bar_name: TextLine
     foo_name: TextLine
 
@@ -1972,15 +1980,15 @@
     >>> bar, foo = generate_entry_interfaces(
     ...     IAmbiguousMultiVersion, [], 'bar', 'foo')
 
-    >>> print bar[0]
+    >>> print bar.version
     bar
-    >>> dump_entry_interface(bar[1])
+    >>> dump_entry_interface(bar.object)
     bar_name: TextLine
     field1: TextLine
 
-    >>> print foo[0]
+    >>> print foo.version
     foo
-    >>> dump_entry_interface(foo[1])
+    >>> dump_entry_interface(foo.object)
     bar_name: TextLine
     foo_name: TextLine
 
@@ -2039,7 +2047,7 @@
     Traceback (most recent call last):
     ...
     ValueError: Field "field" in interface "IDuplicateEntry":
-    Duplicate annotations for version "beta".
+    Duplicate definitions for version "beta".
 
 Or it can happen because you defined the earliest version implicitly
 using keyword arguments, and then explicitly defined conflicting
@@ -2091,7 +2099,7 @@
     ...         ('3.0', dict(exported_as='30_name')),
     ...         ('beta', dict(exported_as='unchanging_name')))
 
-    >>> [version for version, tags in
+    >>> [interface.version for interface in
     ...      generate_entry_interfaces(IUnchangingEntry, [], *versions)]
     ['beta', '1.0', '2.0', '3.0']
 
@@ -2317,8 +2325,11 @@
 But it's not present in the unnamed pre-1.0 version, since it hadn't
 been defined yet:
 
-    >>> print dictionary.pop()
-    (None, {'type': 'removed_operation'})
+    >>> pre_10 = dictionary.pop()
+    >>> print pre_10.version
+    None
+    >>> print pre_10.object
+    {'type': 'removed_operation'}
 
 The @operation_removed_in_version declaration can also be used to
 reset a named operation's definition if you need to completely re-do

=== modified file 'src/lazr/restful/tests/test_declarations.py'
--- src/lazr/restful/tests/test_declarations.py	2011-03-10 14:07:30 +0000
+++ src/lazr/restful/tests/test_declarations.py	2011-03-17 14:24:12 +0000
@@ -1,11 +1,28 @@
 from zope.component import (
-    adapts, getMultiAdapter, getSiteManager, getUtility, provideUtility)
+    adapts,
+    getMultiAdapter,
+    getSiteManager,
+    getUtility,
+    )
 from zope.component.interfaces import ComponentLookupError
-from zope.interface import alsoProvides, Attribute, implements, Interface
+from zope.interface import (
+    Attribute,
+    implements,
+    Interface,
+    )
 from zope.publisher.interfaces.http import IHTTPRequest
-from zope.schema import Int, Object, TextLine
-from zope.security.checker import MultiChecker, ProxyFactory
-from zope.security.management import endInteraction, newInteraction
+from zope.schema import (
+    Int,
+    TextLine,
+    )
+from zope.security.checker import (
+    MultiChecker,
+    ProxyFactory,
+    )
+from zope.security.management import (
+    endInteraction,
+    newInteraction,
+    )
 
 from lazr.restful.declarations import (
     call_with,
@@ -15,14 +32,17 @@
     export_write_operation,
     generate_entry_interfaces,
     generate_operation_adapter,
+    LAZR_WEBSERVICE_NAME,
     mutator_for,
     operation_for_version,
     operation_parameters,
     )
 from lazr.restful.fields import Reference
 from lazr.restful.interfaces import (
-    IEntry, IResourceGETOperation, IWebServiceConfiguration,
-    IWebServiceVersion)
+    IEntry,
+    IResourceGETOperation,
+    IWebServiceConfiguration,
+    )
 from lazr.restful.marshallers import SimpleFieldMarshaller
 from lazr.restful.metazcml import (
     AttemptToContributeToNonExportedInterface,
@@ -30,13 +50,15 @@
     find_interfaces_and_contributors,
     generate_and_register_webservice_operations,
     )
-from lazr.restful._resource import EntryAdapterUtility, EntryResource
-from lazr.restful.testing.webservice import (
-    FakeRequest,
-    TestCaseWithWebServiceFixtures,
+from lazr.restful._resource import (
+    EntryAdapterUtility,
+    EntryResource,
     )
+from lazr.restful.testing.webservice import TestCaseWithWebServiceFixtures
 from lazr.restful.testing.helpers import (
-    create_test_module, TestWebServiceConfiguration, register_test_module)
+    create_test_module,
+    register_test_module,
+    )
 
 
 class ContributingInterfacesTestCase(TestCaseWithWebServiceFixtures):
@@ -344,48 +366,159 @@
 class DummyFieldMarshaller(SimpleFieldMarshaller):
     adapts(Interface, IHTTPRequest)
 
+# Classes for TestEntryMultiversion.
+
+class INotInitiallyExported(Interface):
+    # An entry that's not exported in the first version of the web
+    # service.
+    export_as_webservice_entry(as_of="2.0")
+
+
+class INotPresentInLaterVersion(Interface):
+    # An entry that's only exported in the first version of the web
+    # service.
+    export_as_webservice_entry(
+        versioned_annotations=[('2.0', dict(exported=False))])
+
+
+class IHasDifferentNamesInDifferentVersions(Interface):
+    # An entry that has different names in different versions.
+    export_as_webservice_entry(
+        singular_name="octopus", plural_name="octopi",
+        versioned_annotations=[
+            ('2.0', dict(singular_name="fish", plural_name="fishes"))])
+
+
+class IHasDifferentSingularNamesInDifferentVersions(Interface):
+    # An entry that has different names in different versions.
+    export_as_webservice_entry(
+        singular_name="frog",
+        versioned_annotations=[('2.0', dict(singular_name="toad"))])
+
+
+class TestEntryMultiversion(TestCaseWithWebServiceFixtures):
+    """Test the ability to export an entry only in certain versions."""
+
+    def test_not_initially_exported(self):
+        # INotInitiallyExported is published in version 2.0 but not in 1.0.
+        interfaces = generate_entry_interfaces(
+            INotInitiallyExported, [],
+            *getUtility(IWebServiceConfiguration).active_versions)
+        self.assertEquals(len(interfaces), 1)
+        self.assertEquals(interfaces[0].version, '2.0')
+
+    def test_not_exported_in_later_version(self):
+        # INotPresentInLaterVersion is published in version 1.0 but
+        # not in 2.0.
+        interfaces = generate_entry_interfaces(
+            INotPresentInLaterVersion, [],
+            *getUtility(IWebServiceConfiguration).active_versions)
+        self.assertEquals(len(interfaces), 1)
+        tags = interfaces[0][1].getTaggedValue(LAZR_WEBSERVICE_NAME)
+        self.assertEquals(interfaces[0].version, '1.0')
+
+    def test_different_names_in_different_versions(self):
+        # IHasDifferentNamesInDifferentVersions is called
+        # octopus/octopi in 1.0, and fish/fishes in 2.0.
+        interfaces = generate_entry_interfaces(
+            IHasDifferentNamesInDifferentVersions, [],
+            *getUtility(IWebServiceConfiguration).active_versions)
+        interface_10 = interfaces[0].object
+        tags_10 = interface_10.getTaggedValue(LAZR_WEBSERVICE_NAME)
+        self.assertEquals('octopus', tags_10['singular'])
+        self.assertEquals('octopi', tags_10['plural'])
+
+        interface_20 = interfaces[1].object
+        tags_20 = interface_20.getTaggedValue(LAZR_WEBSERVICE_NAME)
+        self.assertEquals('fish', tags_20['singular'])
+        self.assertEquals('fishes', tags_20['plural'])
+
+    def test_nonexistent_annotation_fails(self):
+        # You can't define an entry class that includes an unrecognized
+        # annotation in its versioned_annotations.
+        try:
+            class IUsesNonexistentAnnotation(Interface):
+                export_as_webservice_entry(
+                    versioned_annotations=[
+                        ('2.0', dict(no_such_annotation=True))])
+            self.fail("Expected ValueError.")
+        except ValueError, exception:
+            self.assertEquals(
+                str(exception),
+                'Unrecognized annotation for version "2.0": '
+                '"no_such_annotation"')
+
+    def test_changing_singular_also_changes_plural(self):
+        # IHasDifferentSingularNamesInDifferentVersions defines the
+        # singular name 'frog' in 1.0, and 'toad' in 2.0. This test
+        # makes sure that the plural of 'toad' is not 'frogs'.
+        interfaces = generate_entry_interfaces(
+            IHasDifferentSingularNamesInDifferentVersions, [],
+            *getUtility(IWebServiceConfiguration).active_versions)
+        interface_10 = interfaces[0].object
+        tags_10 = interface_10.getTaggedValue(LAZR_WEBSERVICE_NAME)
+        self.assertEquals('frog', tags_10['singular'])
+        self.assertEquals('frogs', tags_10['plural'])
+
+        interface_20 = interfaces[1].object
+        tags_20 = interface_20.getTaggedValue(LAZR_WEBSERVICE_NAME)
+        self.assertEquals('toad', tags_20['singular'])
+        self.assertEquals('toads', tags_20['plural'])
+
 
 # Classes for TestReqireExplicitVersions
 
+class IEntryExportedWithoutAsOf(Interface):
+    export_as_webservice_entry()
+
+
+class IEntryExportedWithAsOf(Interface):
+    export_as_webservice_entry(as_of="1.0")
+
+
+class IEntryExportedAsOfLaterVersion(Interface):
+    export_as_webservice_entry(as_of="2.0")
+
+
 class IFieldExportedWithoutAsOf(Interface):
-    export_as_webservice_entry()
+    export_as_webservice_entry(as_of="1.0")
 
     field = exported(TextLine(), exported=True)
 
 
 class IFieldExportedToEarliestVersionUsingAsOf(Interface):
-    export_as_webservice_entry()
+    export_as_webservice_entry(as_of="1.0")
 
     field = exported(TextLine(), as_of='1.0')
 
 
 class IFieldExportedToLatestVersionUsingAsOf(Interface):
-    export_as_webservice_entry()
+    export_as_webservice_entry(as_of="1.0")
 
     field = exported(TextLine(), as_of='2.0')
 
 
 class IFieldDefiningAttributesBeforeAsOf(Interface):
-    export_as_webservice_entry()
+    export_as_webservice_entry(as_of="1.0")
 
     field = exported(TextLine(), ('1.0', dict(exported=True)),
                      as_of='2.0')
 
 class IFieldAsOfNonexistentVersion(Interface):
-    export_as_webservice_entry()
+    export_as_webservice_entry(as_of="1.0")
 
     field = exported(TextLine(), as_of='nosuchversion')
 
 
 class IFieldDoubleDefinition(Interface):
-    export_as_webservice_entry()
+    export_as_webservice_entry(as_of="1.0")
 
     field = exported(TextLine(), ('2.0', dict(exported_as='name2')),
                      exported_as='name2', as_of='2.0')
 
 
 class IFieldImplicitOperationDefinition(Interface):
-    export_as_webservice_entry()
+    export_as_webservice_entry(as_of="1.0")
 
     @call_with(value="2.0")
     @operation_for_version('2.0')
@@ -396,7 +529,7 @@
 
 
 class IFieldExplicitOperationDefinition(Interface):
-    export_as_webservice_entry()
+    export_as_webservice_entry(as_of="1.0")
 
     @call_with(value="2.0")
     @operation_for_version('2.0')
@@ -429,14 +562,45 @@
         except Exception, e:
             return e
 
+    def test_entry_exported_with_as_of_succeeds(self):
+        # An entry exported using as_of is present in the as_of_version
+        # and in subsequent versions.
+        interfaces = generate_entry_interfaces(
+            IEntryExportedWithAsOf, [],
+            *self.utility.active_versions)
+        self.assertEquals(len(interfaces), 2)
+        self.assertEquals(interfaces[0].version, '1.0')
+        self.assertEquals(interfaces[1].version, '2.0')
+
+    def test_entry_exported_as_of_later_version_succeeds(self):
+        # An entry exported as_of a later version is not present in
+        # earlier versions.
+        interfaces = generate_entry_interfaces(
+            IEntryExportedAsOfLaterVersion, [],
+            *self.utility.active_versions)
+        self.assertEquals(len(interfaces), 1)
+        self.assertEquals(interfaces[0].version, '2.0')
+
+    def test_entry_exported_without_as_of_fails(self):
+        exception = self._assertRaises(
+            ValueError, generate_entry_interfaces,
+            IEntryExportedWithoutAsOf, [],
+            *self.utility.active_versions)
+        self.assertEquals(
+            str(exception),
+            'Entry "IEntryExportedWithoutAsOf": Exported in version 1.0, '
+            'but not by using as_of. The service configuration requires '
+            'that you use as_of.')
+
+
     def test_field_exported_as_of_earlier_version_is_exported_in_subsequent_versions(self):
         # If you export a field as_of version 1.0, it's present in
         # 1.0's version of the entry and in all subsequent versions.
         interfaces = generate_entry_interfaces(
             IFieldExportedToEarliestVersionUsingAsOf, [],
             *self.utility.active_versions)
-        interface_10 = interfaces[0][1]
-        interface_20 = interfaces[1][1]
+        interface_10 = interfaces[0].object
+        interface_20 = interfaces[1].object
         self.assertEquals(interface_10.names(), ['field'])
         self.assertEquals(interface_20.names(), ['field'])
 
@@ -446,8 +610,8 @@
         interfaces = generate_entry_interfaces(
             IFieldExportedToLatestVersionUsingAsOf, [],
             *self.utility.active_versions)
-        interface_10 = interfaces[0][1]
-        interface_20 = interfaces[1][1]
+        interface_10 = interfaces[0].object
+        interface_20 = interfaces[1].object
         self.assertEquals(interface_10.names(), [])
         self.assertEquals(interface_20.names(), ['field'])
 
@@ -460,7 +624,7 @@
         self.assertEquals(
             str(exception),
             ('Field "field" in interface "IFieldExportedWithoutAsOf": '
-             'Field was exported in version 1.0, but not by using as_of. '
+             'Exported in version 1.0, but not by using as_of. '
              'The service configuration requires that you use as_of.')
             )
 
@@ -494,7 +658,7 @@
         self.assertEquals(
             str(exception),
             ('Field "field" in interface "IFieldDoubleDefinition": '
-             'Duplicate annotations for version "2.0".'))
+             'Duplicate definitions for version "2.0".'))
 
     def test_field_with_annotations_that_precede_as_of_fails(self):
         # You can't provide a dictionary of attributes for a version

=== modified file 'src/lazr/restful/tests/test_utils.py'
--- src/lazr/restful/tests/test_utils.py	2011-02-18 00:11:51 +0000
+++ src/lazr/restful/tests/test_utils.py	2011-03-17 14:24:12 +0000
@@ -5,11 +5,15 @@
 __metaclass__ = type
 
 import random
+import testtools
 import unittest
 
 from zope.publisher.browser import TestRequest
 from zope.security.management import (
-    endInteraction, newInteraction, queryInteraction)
+    endInteraction,
+    newInteraction,
+    queryInteraction,
+    )
 
 from lazr.restful.utils import (
     extract_write_portion,
@@ -17,6 +21,7 @@
     is_total_size_link_active,
     parse_accept_style_header,
     sorted_named_things,
+    VersionedDict,
     )
 
 
@@ -93,6 +98,111 @@
     # and tag_request_with_version_name() are tested in test_webservice.py.
 
 
+class TestVersionedDict(testtools.TestCase):
+
+    def setUp(self):
+        super(TestVersionedDict, self).setUp()
+        self.dict = VersionedDict()
+
+    def test_rename_version_works(self):
+        # rename_version works when the given version exists.
+        self.dict.push("original")
+        self.dict.rename_version("original", "renamed")
+        self.assertEquals(self.dict.dict_names, ["renamed"])
+
+    def test_rename_version_fails_given_nonexistent_version(self):
+        # rename_version gives KeyError when the given version does
+        # not exist.
+        self.dict.push("original")
+        self.assertRaises(
+            KeyError, self.dict.rename_version, "not present", "renamed")
+
+    def test_dict_for_name_finds_first_dict(self):
+        # dict_for_name finds a dict with the given name in the stack.
+        self.dict.push("name1")
+        self.dict['key'] = 'value1'
+        self.assertEquals(
+            self.dict.dict_for_name('name1'), dict(key='value1'))
+
+    def test_dict_for_name_finds_first_dict(self):
+        # If there's more than one dict with a given name,
+        # dict_for_name() finds the first one.
+        self.dict.push("name1")
+        self.dict['key'] = 'value1'
+        self.dict.push("name2")
+        self.dict.push("name1")
+        self.dict['key'] = 'value2'
+        self.assertEquals(
+            self.dict.dict_for_name('name1'), dict(key='value1'))
+
+    def test_dict_for_name_returns_None_if_no_such_name(self):
+        # If there's no dict with the given name, dict_for_name
+        # returns None.
+        self.assertEquals(None, self.dict.dict_for_name("name1"))
+
+    def test_dict_for_name_returns_default_if_no_such_name(self):
+        # If there's no dict with the given name, and a default value
+        # is provided, dict_for_name returns the default.
+        obj = object()
+        self.assertEquals(obj, self.dict.dict_for_name("name1", obj))
+
+    def test_normalize_for_versions_fills_in_blanks(self):
+        # `normalize_for_versions` makes sure a VersionedDict has
+        # an entry for every one of the given versions.
+        self.dict.push("name2")
+        self.dict['key'] = 'value'
+        self.dict.normalize_for_versions(['name1', 'name2', 'name3'])
+        self.assertEquals(
+            self.dict.stack,
+            [('name1', dict()),
+             ('name2', dict(key='value')),
+             ('name3', dict(key='value'))])
+
+    def test_normalize_for_versions_uses_default_dict(self):
+        self.dict.push("name2")
+        self.dict['key'] = 'value'
+        self.dict.normalize_for_versions(
+            ['name1', 'name2'], dict(default=True))
+        self.assertEquals(
+            self.dict.stack,
+            [('name1', dict(default=True)),
+             ('name2', dict(key='value'))])
+
+    def test_normalize_for_versions_rejects_nonexistant_versions(self):
+        self.dict.push("nosuchversion")
+        exception = self.assertRaises(
+            ValueError, self.dict.normalize_for_versions, ['name1'])
+        self.assertEquals(
+            str(exception), 'Unrecognized version "nosuchversion".')
+
+    def test_normalize_for_versions_rejects_duplicate_versions(self):
+        self.dict.push("name1")
+        self.dict.push("name1")
+        exception = self.assertRaises(
+            ValueError, self.dict.normalize_for_versions, ['name1', 'name2'])
+        self.assertEquals(
+            str(exception), 'Duplicate definitions for version "name1".')
+
+    def test_normalize_for_versions_rejects_misordered_versions(self):
+        self.dict.push("name2")
+        self.dict.push("name1")
+        exception = self.assertRaises(
+            ValueError, self.dict.normalize_for_versions, ['name1', 'name2'])
+        self.assertEquals(
+            str(exception),
+            'Version "name1" defined after the later version "name2".')
+
+    def test_error_prefix_prepended_to_exception(self):
+        self.dict.push("nosuchversion")
+        exception = self.assertRaises(
+            ValueError, self.dict.normalize_for_versions, ['name1'],
+            error_prefix='Error test: ')
+        self.assertEquals(
+            str(exception),
+            'Error test: Unrecognized version "nosuchversion".')
+
+
+
 class TestParseAcceptStyleHeader(unittest.TestCase):
 
     def test_single_value(self):

=== modified file 'src/lazr/restful/utils.py'
--- src/lazr/restful/utils.py	2011-02-18 00:11:51 +0000
+++ src/lazr/restful/utils.py	2011-03-17 14:24:12 +0000
@@ -15,11 +15,13 @@
     'smartquote',
     'simple_popen2',
     'tag_request_with_version_name',
+    'VersionedAnnotations',
     'VersionedDict',
     ]
 
 
 import cgi
+import collections
 import copy
 import operator
 import re
@@ -125,6 +127,10 @@
     return [value for quality, value in filtered_accepts]
 
 
+VersionedObject = collections.namedtuple(
+    'VersionedObject', ['version', 'object'])
+
+
 class VersionedDict(object):
     """A stack of named dictionaries.
 
@@ -156,9 +162,9 @@
         if empty or len(self.stack) == 0:
             dictionary = {}
         else:
-            stack_top = self.stack[-1][1]
+            stack_top = self.stack[-1].object
             dictionary = copy.deepcopy(stack_top)
-        self.stack.append((name, dict(dictionary)))
+        self.stack.append(VersionedObject(name, dict(dictionary)))
 
     def pop(self):
         """Pop a tuple representing a dictionary from the stack.
@@ -169,19 +175,98 @@
         """
         return self.stack.pop()
 
+    def dict_for_name(self, version, default=None):
+        """Find the first dict for the given version."""
+        matches = [item.object for item in self.stack
+                   if item.version == version]
+        if len(matches) == 0:
+            return default
+        return matches[0]
+
+    def normalize_for_versions(self, versions, default_dictionary=None,
+                               error_prefix=''):
+        """Fill out the stack with something for every given version.
+
+        :param versions: A list of names for dictionaries. By the time
+          this method completes, the value of `dict_names` will be the
+          same as this list. 'Earlier' versions are presumed to come
+          before 'later' versions, but this only affects the error
+          message given when annotations are discovered to be out of
+          order.
+
+        :param default_dictionary: A dictionary to use for versions that
+          can't inherit values from some other dictionary.
+
+        :param error_prefix: A string to prepend to errors when
+          raising exceptions.
+
+        :raise ValueError: If the existing dictionary stack includes
+           names not present in `versions`, if the names in the stack
+           are present in an order other than the one given in
+           `versions`, or if any names in the stack are duplicated.
+        """
+        new_stack = []
+
+        # Do some error checking.
+        max_index = -1
+        for version, tags in self.stack:
+            try:
+                version_index = versions.index(version)
+            except ValueError:
+                raise ValueError(
+                    error_prefix + 'Unrecognized version "%s".' % version)
+            if version_index == max_index:
+                raise ValueError(
+                    error_prefix + 'Duplicate definitions for version '
+                    '"%s".' % version)
+            if version_index < max_index:
+                raise ValueError(
+                    error_prefix + 'Version "%s" defined after '
+                    'the later version "%s".' % (version, versions[max_index]))
+            max_index = version_index
+
+        # We now know that the versions present in the dictionary are
+        # an ordered subset of the versions in `versions`. All we have
+        # to do now is fill in the blanks.
+        most_recent_dict = default_dictionary or {}
+        for version in versions:
+            existing_dict = self.dict_for_name(version)
+            if existing_dict is None:
+                # This version has no dictionary of its own. Use a copy of
+                # the most recent dictionary.
+                new_stack.append(
+                    VersionedObject(
+                        version, copy.deepcopy(most_recent_dict)))
+            else:
+                # This version has a dictionary. Use it.
+                new_stack.append(
+                    VersionedObject(version, existing_dict))
+                most_recent_dict = existing_dict
+        self.stack = new_stack
+
     @property
     def dict_names(self):
         """Return the names of dictionaries in the stack."""
-        return [item[0] for item in self.stack if item is not None]
+        return [item.version for item in self.stack if item is not None]
 
     @property
     def is_empty(self):
         """Is the stack empty?"""
         return len(self.stack) == 0
 
+    def rename_version(self, old_name, new_name):
+        """Change the name of a version."""
+        for index, pair in enumerate(self.stack):
+            if pair.version == old_name:
+                self.stack[index] = VersionedObject(
+                    new_name, pair.object)
+                break
+        else:
+            raise KeyError(old_name)
+
     def setdefault(self, key, value):
         """Get a from the top of the stack, setting it if not present."""
-        return self.stack[-1][1].setdefault(key, value)
+        return self.stack[-1].object.setdefault(key, value)
 
     def __contains__(self, key):
         """Check whether a key is visible in the stack."""
@@ -191,31 +276,31 @@
         """Look up an item somewhere in the stack."""
         if self.is_empty:
             raise KeyError(key)
-        return self.stack[-1][1][key]
+        return self.stack[-1].object[key]
 
     def get(self, key, default=None):
         """Look up an item somewhere in the stack, with default fallback."""
         if self.is_empty:
             return default
-        return self.stack[-1][1].get(key, default)
+        return self.stack[-1].object.get(key, default)
 
     def items(self):
         """Return a merged view of the items in the dictionary."""
         if self.is_empty:
             raise IndexError("Stack is empty")
-        return self.stack[-1][1].items()
+        return self.stack[-1].object.items()
 
     def __setitem__(self, key, value):
         """Set a value in the dict at the top of the stack."""
         if self.is_empty:
             raise IndexError("Stack is empty")
-        self.stack[-1][1][key] = value
+        self.stack[-1].object[key] = value
 
     def __delitem__(self, key):
         """Delete a value from the dict at the top of the stack."""
         if self.is_empty:
             raise IndexError("Stack is empty")
-        del self.stack[-1][1][key]
+        del self.stack[-1].object[key]
 
 
 def implement_from_dict(class_name, interface, values, superclass=object):