RFC: Proposal Dexterity API - two variants

======================
Proposal Dexterity API
======================

We, Robert Niederreiter and Jens Klein, wrote this proposal as an entry 
to a discussion for an future Dexterity API (read: Dexterity 3). We 
followed two different pathes and we are curios which one gets more +1 ;)

Both of them are implementable and also both are in the perspective of 
speed almost the same.


Explicit behaviors proposal: expose behaviors explicitly
========================================================

Basic principles
----------------

* Duplicate attribute names are allowed by different behaviors
* Programmer always addresses effected behavior explicit


Pros
----

* More reliable and readable code
* Explicitness
* Easy migration


Cons
----

* Steeper learning curve (developer needs to learn which behaviors exists)
* More code

Implementation implications
---------------------------

* think of behavior inheritance and how default behaviors can be overwritten


API usage example
-----------------

Read Attribute::
 >>> context.behavior('basic').title

Write Attribute::
 >>> context.behavior('basic').title = u'My Title'

Behavior information::
 >>> context.behaviors
{
     'basic': {
         'title': 'Basic',
         'description': 'Foo',
         'attributes': {
             'title': {
                 'label': 'Title',
                 'description': 'Title of the object',
                 '...'
             },
             ...
         }
     }
     ...
}

 >>> repr(context.behaviors)
- basic
     -title
     -description
...

Unrestricted access::
 >>> context.behavior('basic').unrestricted('title')


Shadowed Behaviors Proposal: Simplified value access
====================================================

Basic principles
----------------

* implemented as one property directly on 
plone.dexterity.content.DexterityContent which acts as a 
zope.interface.mapping.IFullMapping (read: dict-like) to work with all 
values and methods coming from the main schema, behavior schemas and 
behavior factories.
* Programmer does not need to know about behavior names when accessing data
* Set/get of main schema values is same as schemas form behaviors.
* Duplicate attribute names are NOT allowed any more and enforced 
(checked on FTI creation time, i.e. XML import, TTW setting) This is 
important!
* factory methods/properties from behaviors are exposed when a factory 
is given instaed of direct attribute access.


Pros
----

* Simple entry for new developers
* pythonic
* natural dict-like API is first principle
* no accicdential override of attributes stored
* behavior inheritance (i.e.IDublicCoreMetadata is not a problem at all)


Cons
----

* duplicate fieldnames in existing code needs migration (not in core)
* behaviors are kind of hidden to developers, so misunderstandings may 
occur (needs good documentation)


Open for discussion
-------------------

* should validation be enforced?


Important
---------

* lots of caching of schemas and intermeidate results


API usage example
-----------------

 >>> context.values['title']
'My Document'

 >>> context.values['title'] = 'Jensens Document'
 >>> context.values['some_factory_property'] = 'Foo'
 >>> context.values['some_factory_property']
'Foo'

 >>> context.values['some_factory_method'](param1, param2='foo')
...

 >>> context.values.keys()
['title', 'description', ....]

 >>> context.update({'title': 'Jensens Updated Document', 'description': 
'A new easy to understand API for dx'}
 >>> context.values.items()
[('title': 'Jensens Updated Document', 'description': 'A new easy ...', 
....)]

other dict-api methods are implemented too (need to finish this, but you 
can imagine how it looks like, )
active access to restricted values which checks the read/write permission!

 >>> context.restricted_values['title']
Traceback ...
....
Unauthorized(...)


Legacy Proposal
------------------------

* rename dexterity to devilstick
* use wording molecule instead of behavior
* the values are atoms
* ignore this legacy proposal ;D

-------------------------------------------------------------------------

happy commenting

Jens and Robert
-- 
BlueDynamics Alliance


------------------------------------------------------------------------------