    ==============
    Source Widgets
    ==============

    Sources are objects that represent sets of values from which one might choose
    and are used with Choice schema fields. Source widgets currently fall into two
    categories:

    - widgets for iterable sources

    - widgets for queryable sources

    Sources (combined with the available adapters) may support both approaches, but
    no widgets currently support both.

    In both cases, the widgets need views that can be used to get tokens to
    represent source values in forms, as well as textual representations of values.
    We use the `zope.browser.interfaces.ITerms` views for that.

    All of our examples will be using the component architecture::

      >>> import zope.interface
      >>> import zope.component
      >>> import zope.schema

    This `ITerms` implementation can be used for the sources involved in
    our tests::

      >>> from zope.browser.interfaces import ITerms
      >>> import zope.publisher.interfaces.browser
      >>> import zope.app.form.browser.interfaces
      >>> from zope.schema.vocabulary import SimpleTerm
      >>> class ListTerms:
      ...
      ...     zope.interface.implements(ITerms)
      ...
      ...     def __init__(self, source, request):
      ...         pass # We don't actually need the source or the request :)
      ...
      ...     def getTerm(self, value):
      ...         title = unicode(value)
      ...         try:
      ...             token = title.encode('base64').strip()
      ...         except binascii.Error:
      ...             raise LookupError(token)
      ...         return SimpleTerm(value, token=token, title=title)
      ...
      ...     def getValue(self, token):
      ...         return token.decode('base64')

    This view just uses the unicode representations of values as titles and the
    base-64 encoding of the titles as tokens.  This is a very simple strategy
    that's only approriate when the values have short and unique unicode
    representations.

    All of the source widgets are in a single module::

      >>> import zope.app.form.browser.source

    We'll also need request objects::

      >>> from zope.publisher.browser import TestRequest

    Iterable Source Widgets
    =======================

    Iterable sources are expected to be simpler than queriable sources, so they
    represent a good place to start.  The most important aspect of iterable sources
    for widgets is that it's actually possible to enumerate all the values from the
    source.  This allows each possible value to be listed in a