--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/devrepo/entityclasses/data-as-objects.rst	Fri Apr 23 17:31:46 2010 +0200
@@ -0,0 +1,136 @@
+Access to persistent data
+--------------------------
+
+Python-level access to persistent data is provided by the
+:class:`Entity <cubicweb.entity>` class.
+
+An entity class is bound to a schema entity type.  Descriptors are added when
+classes are registered in order to initialize the class according to its schema:
+
+* we can access the defined attributes in the schema thanks to the attributes of
+  the same name on instances (typed value)
+
+* we can access the defined relations in the schema thanks to the relations of
+  the same name on instances (entities instances list)
+
+
+:Formatting and output generation:
+
+  * `view(__vid, __registry='views', **kwargs)`, applies the given view to the entity
+    (and returns an unicode string)
+
+  * `absolute_url(*args, **kwargs)`, returns an absolute URL to access the primary view
+    of an entity
+
+  * `rest_path()`, returns a relative REST URL to get the entity
+
+  * `printable_value(attr, value=_marker, attrtype=None, format='text/html', displaytime=True)`,
+    returns a string enabling the display of an attribute value in a given format
+    (the value is automatically recovered if necessary)
+
+:Data handling:
+
+  * `as_rset()`, converts the entity into an equivalent result set simulating the
+     request `Any X WHERE X eid _eid_`
+
+  * `complete(skip_bytes=True)`, executes a request that recovers at
+    once all the missing attributes of an entity
+
+  * `get_value(name)`, returns the value associated to the attribute name given
+    in parameter
+
+  * `related(rtype, role='subject', limit=None, entities=False)`,
+    returns a list of entities related to the current entity by the
+    relation given in parameter
+
+  * `unrelated(rtype, targettype, role='subject', limit=None)`,
+    returns a result set corresponding to the entities not (yet)
+    related to the current entity by the relation given in parameter
+    and satisfying its constraints
+
+  * `set_attributes(**kwargs)`, updates the attributes list with the corresponding
+    values given named parameters
+
+  * `set_relations(**kwargs)`, add relations to the given object. To
+     set a relation where this entity is the object of the relation,
+     use `reverse_<relation>` as argument name.  Values may be an
+     entity, a list of entities, or None (meaning that all relations of
+     the given type from or to this object should be deleted).
+
+  * `copy_relations(ceid)`, copies the relations of the entities having the eid
+    given in the parameters on the current entity
+
+  * `delete()` allows to delete the entity
+
+
+The :class:`AnyEntity` class
+----------------------------
+
+To provide a specific behavior for each entity, we have to define a class
+inheriting from `cubicweb.entities.AnyEntity`. In general, we define this class
+in `mycube.entities` module (or in a submodule if we want to split code among
+multiple files) so that it will be available on both server and client side.
+
+The class `AnyEntity` is a sub-class of Entity that add methods to it,
+and helps specializing (by further subclassing) the handling of a
+given entity type.
+
+Most methods defined for `AnyEntity`, in addition to `Entity`, add
+support for the `Dublin Core`_ metadata.
+
+.. _`Dublin Core`: http://dublincore.org/
+
+:Standard meta-data (Dublin Core):
+
+  * `dc_title()`, returns a unicode string corresponding to the
+    meta-data `Title` (used by default is the first non-meta attribute
+    of the entity schema)
+
+  * `dc_long_title()`, same as dc_title but can return a more
+    detailed title
+
+  * `dc_description(format='text/plain')`, returns a unicode string
+    corresponding to the meta-data `Description` (looks for a
+    description attribute by default)
+
+  * `dc_authors()`, returns a unicode string corresponding to the meta-data
+    `Authors` (owners by default)
+
+  * `dc_creator()`, returns a unicode string corresponding to the
+    creator of the entity
+
+  * `dc_date(date_format=None)`, returns a unicode string corresponding to
+    the meta-data `Date` (update date by default)
+
+  * `dc_type(form='')`, returns a string to display the entity type by
+    specifying the preferred form (`plural` for a plural form)
+
+  * `dc_language()`, returns the language used by the entity
+
+
+:Misc methods:
+
+  * `after_deletion_path`, return (path, parameters) which should be
+     used as redirect information when this entity is being deleted
+
+  * `pre_web_edit`, callback called by the web editcontroller when an
+    entity will be created/modified, to let a chance to do some entity
+    specific stuff (does nothing by default)
+
+Inheritance
+-----------
+
+When describing a data model, entities can inherit from other entities as is
+common in object-oriented programming.
+
+You have the possibility to adapt some entity attributes, as follow:
+
+.. sourcecode:: python
+
+    from cubes.OTHER_CUBE import entities
+    class EntityExample(entities.EntityExample):
+        def dc_long_title(self):
+            return '%s (%s)' % (self.name, self.description)
+
+Notice this is different than yams schema inheritance.
+