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 redefine whatever pleases you, 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)

The most specific entity definition will always the one used by the
ORM. For instance, the new EntityExample above in mycube replaces the
one in OTHER_CUBE. These types are stored in the `etype` section of
the `vregistry`.

Notice this is different than yams schema inheritance.