=============
Data Managers
=============

For the longest time the way widgets retrieved and stored their values on the
actual content/model was done by binding the field to a context and then
setting and getting the attribute from it. This has several distinct design
shortcomings:

1. The field has too much responsibility by knowing about its implementations.

2. There is no way of redefining the method used to store and access data
   other than rewriting fields.

3. Finding the right content/model to modify is an implicit policy: Find an
   adapter for the field's schema and then set the value there.

While implementing some real-world projects, we noticed that this approach is
too limiting and we often could not use the form framework when we wanted or
had to jump through many hoops to make it work for us. For example, if we want
to display a form to collect data that does not correspond to a set of content
components, we were forced to not only write a schema for the form, but also
implement that schema as a class. but all we wanted was a dictionary. For
edit-form like tasks we often also had an initial dictionary, which we just
wanted modified.

Data managers abstract the getting and setting of the data. A data manager is
responsible for setting one piece of data in a particular context.

  >>> from z3c.form import datamanager


Attribute Field Manager
-----------------------

The most common case, of course, is the management of class attributes through
fields. In this case, the data manager needs to know about the context and the
field it is managing the data for.

  >>> import zope.interface
  >>> import zope.schema
  >>> class IPerson(zope.interface.Interface):
  ...     name = zope.schema.TextLine(
  ...         title=u'Name',
  ...         default=u'<no name>')
  ...     phone = zope.schema.TextLine(
  ...         title=u'Phone')

  >>> class Person(object):
  ...     zope.interface.implements(IPerson)
  ...     name = u''
  ...     def __init__(self, name):
  ...         self.name = name

  >>> stephan = Person(u'Stephan Richter')

We can now instantiate the data manager for Stephan's name:

  >>> nameDm = datamanager.AttributeField(stephan, IPerson['name'])

The data manager consists of a few simple methods to accomplish its
purpose. Getting the value is done using the ``get()`` or ``query()`` method:

  >>> nameDm.get()
  u'Stephan Richter'

  >>> nameDm.query()
  u'Stephan Richter'

The value can be set using ``set()``:

  >>> nameDm.set(u'Stephan "Caveman" Richter')

  >>> nameDm.get()
  u'Stephan "Caveman" Richter'
  >>> stephan.name
  u'Stephan "Caveman" Richter'

If an attribute is not available, ``get()`` fails and ``query()`` returns a
default value:

  >>> phoneDm = datamanager.AttributeField(stephan, IPerson['phone'])

  >>> phoneDm.get()
  Traceback (most recent call last):
  ...
  AttributeError: 'Person' object has no attribute 'phone'

  >>> phoneDm.query()
  <NO_VALUE>
  >>> phoneDm.query('nothing')
  'nothing'

A final feature that is supported by the data manager is the check whether a
value can be accessed and written. When the context is not security proxied,
both, accessing and writing, is allowed:

  >>> nameDm.canAccess()
  True
  >>> nameDm.canWrite()
  True

To demonstrate the behavior for a security-proxied component, we first have to
provide security declarations for our person:

  >>> from zope.security.management import endInteraction
  >>> from zope.security.management import newInteraction
  >>> from zope.security.management import setSecurityPolicy
  >>> import z3c.form.testing
  >>> endInteraction()
  >>> newPolicy = z3c.form.testing.SimpleSecurityPolicy()
  >>> newPolicy.allowedPermissions = ('View', 'Edit')
  >>> oldpolicy = setSecurityPolicy(newPolicy)
  >>> newInteraction()

  >>> from zope.security.checker import Checker
  >>> from zope.security.checker import defineChecker
  >>> personChecker = Checker({'name':'View', 'name':'Edit'})
  >>> defineChecker(Person, personChecker)

We now need to wrap stephan into a proxy:

  >>> protectedStephan = zope.security.checker.ProxyFactory(stephan)

Since we are not logged in as anyone, we cannot acces or write the value:

  >>> nameDm = datamanager.AttributeField(protectedStephan, IPerson['name'])

  >>> nameDm.canAccess()
  False
  >>> nameDm.canWrite()
  False

Clearly, this also means that ``get()`` and ``set()`` are also shut off:

  >>> nameDm.get()
  Traceback (most recent call last):
  ...
  Unauthorized: (<Person object at ...>, 'name', 'Edit')

  >>> nameDm.set(u'Stephan')
  Traceback (most recent call last):
  ...
  ForbiddenAttribute: ('name', <Person object at ...>)

Now we have to setup the security system and "log in" as a user:

  >>> newPolicy.allowedPermissions = ('View', 'Edit')
  >>> newPolicy.loggedIn = True

The created principal, with which we are logged in now, can only access the
attribute:

  >>> nameDm.canAccess()
  True
  >>> nameDm.canWrite()
  False

Thus only the ``get()`` method is allowed:

  >>> nameDm.get()
  u'Stephan "Caveman" Richter'

  >>> nameDm.set(u'Stephan')
  Traceback (most recent call last):
  ...
  ForbiddenAttribute: ('name', <Person object at ...>)

If field's schema is not directly provided by the context, the datamanager
will attempt to find an adapter. Let's give the person an address for example:

  >>> class IAddress(zope.interface.Interface):
  ...     city = zope.schema.TextLine(title=u'City')

  >>> class Address(object):
  ...     zope.component.adapts(IPerson)
  ...     zope.interface.implements(IAddress)
  ...     def __init__(self, person):
  ...         self.person = person
  ...     @apply
  ...     def city():
  ...         def get(self):
  ...             return getattr(self.person, '_city', None)
  ...         def set(self, value):
  ...             self.person._city = value
  ...         return property(get, set)

  >>> zope.component.provideAdapter(Address)

Now we can create a data manager for the city attribute:

  >>> cityDm = datamanager.AttributeField(stephan, IAddress['city'])

We can access and write to the city attribute:

  >>> cityDm.canAccess()
  True
  >>> cityDm.canWrite()
  True

Initially there is no value, but of course we can create one:

  >>> cityDm.get()

  >>> cityDm.set(u'Maynard')
  >>> cityDm.get()
  u'Maynard'

The value can be accessed through the adapter itself as well:

  >>> IAddress(stephan).city
  u'Maynard'

While we think that implicitly looking up an adapter is not the cleanest
solution, it allows us to mimic the behavior of ``zope.formlib``. We think
that we will eventually provide alternative ways to accomplish the same in a
more explicit way.

If we try to set a value that is read-only, a type error is raised:

  >>> readOnlyName = zope.schema.TextLine(
  ...     __name__='name',
  ...     readonly=True)

  >>> nameDm = datamanager.AttributeField(stephan, readOnlyName)
  >>> nameDm.set(u'Stephan')
  Traceback (most recent call last):
  ...
  TypeError: Can't set values on read-only fields
             (name=name, class=__builtin__.Person)

Finally, we instantiate the data manager with a ``zope.schema``
field. And we can access the different methods like before.

  >>> nameDm = datamanager.AttributeField(
  ...    stephan, zope.schema.TextLine(__name__ = 'name'))
  >>> nameDm.canAccess()
  True
  >>> nameDm.canWrite()
  True

  >>> nameDm.get()
  u'Stephan "Caveman" Richter'
  >>> nameDm.query()
  u'Stephan "Caveman" Richter'

  >>> nameDm.set(u'Stephan Richter')
  >>> nameDm.get()
  u'Stephan Richter'

Dictionary Field Manager
------------------------

Another implementation of the data manager interface is provided by the
dictionary field manager, which does not expect an instance with attributes as
its context, but a dictionary. It still uses a field to determine the key to
modify.

  >>> personDict = {}
  >>> nameDm = datamanager.DictionaryField(personDict, IPerson['name'])

The datamanager can really only deal with dictionaries and mapping types:

  >>> import zope.interface.common.mapping
  >>> import persistent.mapping
  >>> import persistent.dict
  >>> class MyMapping(object):
  ...     zope.interface.implements(zope.interface.common.mapping.IMapping)
  >>> datamanager.DictionaryField(MyMapping(), IPerson['name'])
  <z3c.form.datamanager.DictionaryField object at ...>
  >>> datamanager.DictionaryField(persistent.mapping.PersistentMapping(),
  ...     IPerson['name'])
  <z3c.form.datamanager.DictionaryField object at ...>
  >>> datamanager.DictionaryField(persistent.dict.PersistentDict(),
  ...     IPerson['name'])
  <z3c.form.datamanager.DictionaryField object at ...>

  >>> datamanager.DictionaryField([], IPerson['name'])
  Traceback (most recent call last):
  ...
  ValueError: Data are not a dictionary: <type 'list'>

Let's now access the name:

  >>> nameDm.get()
  Traceback (most recent call last):
  ...
  AttributeError

  >>> nameDm.query()
  <NO_VALUE>

Initially we get the default value (as specified in the field), since the
person dictionariy has no entry. If no default value has been specified in the
field, the missing value is returned.

Now we set a value and it should be available:

  >>> nameDm.set(u'Roger Ineichen')

  >>> nameDm.get()
  u'Roger Ineichen'
  >>> personDict
  {'name': u'Roger Ineichen'}

Since this dictionary is not security proxied, any field can be accessed and
written to:

  >>> nameDm.canAccess()
  True
  >>> nameDm.canWrite()
  True

As with the attribute data manager, readonly fields cannot be set:

  >>> nameDm = datamanager.DictionaryField(personDict, readOnlyName)
  >>> nameDm.set(u'Stephan')
  Traceback (most recent call last):
  ...
  TypeError: Can't set values on read-only fields name=name


Cleanup
-------

We clean up the changes we made in these examples:

  >>> endInteraction()
  >>> ignore = setSecurityPolicy(oldpolicy)