1 Access to persistent data

     2 --------------------------

     3 

     4 Python-level access to persistent data is provided by the

     5 :class:`Entity <cubicweb.entity>` class.

     6 

     7 An entity class is bound to a schema entity type.  Descriptors are added when

     8 classes are registered in order to initialize the class according to its schema:

     9 

    10 * we can access the defined attributes in the schema thanks to the attributes of

    11   the same name on instances (typed value)

    12 

    13 * we can access the defined relations in the schema thanks to the relations of

    14   the same name on instances (entities instances list)

    15 

    16 

    17 :Formatting and output generation:

    18 

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

    20 

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

    22     of an entity

    23 

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

    25 

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

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

    28     (the value is automatically recovered if necessary)

    29 

    30 :Data handling:

    31 

    32   * `as_rset()`, converts the entity into an equivalent result set simulating the

    33      request `Any X WHERE X eid _eid_`

    34 

    35   * `complete(skip_bytes=True)`, executes a request that recovers all at once

    36     all the missing attributes of an entity

    37 

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

    39     in parameter

    40 

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

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

    43 

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

    45     corresponding to the entities not related to the current entity by the

    46     relation given in parameter and satisfying its constraints

    47 

    48   * `set_attributes(**kwargs)`, updates the attributes list with the corresponding

    49     values given named parameters

    50 

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

    52     given in the parameters on the current entity

    53 

    54   * `delete()` allows to delete the entity

    55 

    56 

    57 The :class:`AnyEntity` class

    58 ----------------------------

    59 

    60 To provide a specific behavior for each entity, we have to define a class

    61 inheriting from `cubicweb.entities.AnyEntity`. In general, we define this class

    62 in `mycube.entities` module (or in a submodule if we want to split code among

    63 multiple files) so that it will be available on both server and client side.

    64 

    65 The class `AnyEntity` is a sub-class of Entity that add methods to it,

    66 and helps specializing (by further subclassing) the handling of a

    67 given entity type.

    68 

    69 The methods defined for `AnyEntity`, in addition to `Entity`, are the

    70 following ones:

    71 

    72 :Standard meta-data (Dublin Core):

    73 

    74   * `dc_title()`, returns a unicode string corresponding to the

    75     meta-data `Title` (used by default is the first non-meta attribute

    76     of the entity schema)

    77 

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

    79     detailed title

    80 

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

    82     corresponding to the meta-data `Description` (looks for a

    83     description attribute by default)

    84 

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

    86     `Authors` (owners by default)

    87 

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

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

    90 

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

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

    93 

    94 

    95 Inheritance

    96 -----------

    97 

    98 When describing a data model, entities can inherit from other entities as is

    99 common in object-oriented programming.

   100 

   101 You have the possibility to adapt some entity attributes, as follow:

   102 

   103 .. sourcecode:: python

   104 

   105     from cubes.OTHER_CUBE import entities

   106     class EntityExample(entities.EntityExample):

   107         def dc_long_title(self):

   108             return '%s (%s)' % (self.name, self.description)

   109 

   110 Notice this is different than yams schema inheritance.

   111