.. -*- coding: utf-8 -*-

Stored data handling

====================

Classes `Entity` and `AnyEntity`

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

To provide a specific behavior for each entity, we just need to define

a class inheriting from `cubicweb.entities.EnyEntity`. In genera, we have

to defined those classes in a module of `entites` package of an application

so that it will be available on both server and client side.

The class `AnyEntity` is loaded dynamically from the class `Entity` 

(`cubciweb.common.entity`). We define a sub-class to add methods or to

specialize the handling of a given 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 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)

The methods defined for `AnyEntity` or `Entity` are the following ones:

* `has_eid()`, returns true is the entity has an definitive eid (e.g. not in the

  creation process)

* `check_perm(action)`, checks if the user has the permission to execcute the

  requested action on the entity

:Formatting and output generation:

  * `view(vid, **kwargs)`, apply the given view to the entity

  * `absolute_url(**kwargs)`, returns an absolute URL to access the primary view

    of an entity

  * `rest_path()`, returns a relative REST URL to get the entity

  * `format(attr)`, returns the format (MIME type) of the field given un parameter

  * `printable_value(attr, value=_marker, attrtype=None, format='text/html')`, 

    returns a string enabling the display of an attribute value in a given format

    (the value is automatically recovered if necessarry)

  * `display_name(form='')`, returns a string to display the entity type by 

    specifying the preferred form (`plural` for a plural form)

: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 in one time

    all the missing attributes of an entity

  * `get_value(name)`, returns the value associated to the attribute name given

    in parameter

  * `related(rtype, x='subject', limit=None, entities=False)`, returns a list

    of entities related to the current entity by the relation given in parameter

  * `unrelated(rtype, targettype, x='subject', limit=None)`, returns a result set

    corresponding to the entities not 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

  * `copy_relations(ceid)`, copies the relations of the entities having the eid

    given in the parameters on the current entity

  * `last_modified(view)`, returns the date the object has been modified

    (used by HTTP cache handling)

  * `delete()` allows to delete the entity

:Standard meta-data (Dublin Core):

  * `dc_title()`, returns a unicode string corresponding to the meta-data

    `Title` (used by default the first attribute non-meta of the entity

    schema)

  * `dc_long_title()`, same as dc_title but can return a more

    detailled title

  * `dc_description(format='text/plain')`, returns a unicode string 

    corresponding to the meta-data `Description` (look for a description

    attribute by default)

  * `dc_authors()`, returns a unicode string corresponding to the meta-data 

    `Authors` (owners by default)

  * `dc_date(date_format=None)`, returns a unicode string corresponding to 

    the meta-data `Date` (update date by default)

:Vocabulary control on relations:

  * `vocabulary(rtype, x='subject', limit=None)`, called by the

    editing views, it returns a list of couples (label, eid) of entities

    that could be related to the entity by the relation `rtype`

  * `subject_relation_vocabulary(rtype, limit=None)`, called internally 

    by  `vocabulary` in the case of a subject relation

  * `object_relation_vocabulary(rtype, limit=None)`, called internally 

    by  `vocabulary` in the case of an object relation

  * `relation_vocabulary(rtype, targettype, x, limit=None)`, called

    internally by `subject_relation_vocabulary` and `object_relation_vocabulary`

*rtags*

-------

*rtags* allows to specify certain behaviors of relations relative to a given

entity type (see later). They are defined on the entity class by the attribute

`rtags` which is a dictionnary with as its keys the triplet ::

  <relation type>, <target entity type>, <context position ("subject" ou "object")>

and as the values a `set` or a tuple of markers defining the properties that

apply to this relation.

It is possible to simplify this dictionnary:

* if we want to specifiy a single marker, it is not necessarry to

  use a tuple as the value, the marker by itself (characters string)

  is enough

* if we only care about a single type of relation and not about the target

  and the context position (or when this one is not ambigous), we can simply

  use the name of the relation type as the key

* if we want a marker to apply independently from the target entity type,

  we have to use the string `*` as the target entity type

Please note that this dictionnary is *treated at the time the class is created*.

It is automatically merged with the parent class(es) (no need to copy the

dictionnary from the parent class to modify it). Also, modify it after the 

class is created will not have any effect...