doc/book/en/devrepo/datamodel/definition.rst
author Pierre-Yves David <pierre-yves.david@logilab.fr>
Fri, 09 Dec 2011 12:14:11 +0100
changeset 8125 7070250bf50d
parent 7797 a71618a75b53
child 9255 46f41c3e1443
permissions -rw-r--r--
[schema] React to yams improvement of metadata attribute handling. * Change the way RichString is deprecated. * Add documentation about metadata attribute
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
4452
5d6dec2c4650 [doc] small fixes on security part
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 3811
diff changeset
     1
 .. -*- coding: utf-8 -*-
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     2
5953
af48c527aea7 [doc/book] fix & enhance rql intro chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5400
diff changeset
     3
.. _datamodel_definition:
af48c527aea7 [doc/book] fix & enhance rql intro chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5400
diff changeset
     4
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     5
Yams *schema*
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     6
-------------
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     7
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
     8
The **schema** is the core piece of a *CubicWeb* instance as it
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
     9
defines and handles the data model. It is based on entity types that
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    10
are either already defined in `Yams`_ and the *CubicWeb* standard
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    11
library; or more specific types defined in cubes. The schema for a
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    12
cube is defined in a `schema` python module or package.
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    13
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    14
.. _`Yams`: http://www.logilab.org/project/yams
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    15
5953
af48c527aea7 [doc/book] fix & enhance rql intro chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5400
diff changeset
    16
.. _datamodel_overview:
af48c527aea7 [doc/book] fix & enhance rql intro chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5400
diff changeset
    17
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    18
Overview
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    19
~~~~~~~~
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    20
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    21
The core idea of the yams schema is not far from the classical
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    22
`Entity-relationship`_ model. But while an E/R model (or `logical
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    23
model`) traditionally has to be manually translated to a lower-level
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    24
data description language (such as the SQL `create table`
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    25
sublanguage), also often described as the `physical model`, no such
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    26
step is required with |yams| and |cubicweb|.
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    27
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    28
.. _`Entity-relationship`: http://en.wikipedia.org/wiki/Entity-relationship_model
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    29
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    30
This is because in addition to high-level, logical |yams| models, one
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    31
uses the |rql| data manipulation language to query, insert, update and
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    32
delete data. |rql| abstracts as much of the underlying SQL database as
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    33
a |yams| schema abstracts from the physical layout. The vagaries of
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    34
SQL are avoided.
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    35
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    36
As a bonus point, such abstraction make it quite comfortable to build
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    37
or use different backends to which |rql| queries apply.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    38
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    39
So, as in the E/R formalism, the building blocks are ``entities``
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    40
(:ref:`EntityType`), ``relationships`` (:ref:`RelationType`,
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    41
:ref:`RelationDefinition`) and ``attributes`` (handled like relation
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    42
with |yams|).
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    43
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    44
Let us detail a little the divergences between E/R and |yams|:
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    45
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    46
* all relationship are binary which means that to represent a
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    47
  non-binary relationship, one has to use an entity,
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    48
* relationships do not support attributes (yet, see:
5349
023dbeb84cc2 [doc/book] fix wrong (https) url
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5319
diff changeset
    49
  http://www.cubicweb.org/ticket/341318), hence the need to reify it
023dbeb84cc2 [doc/book] fix wrong (https) url
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5319
diff changeset
    50
  as an entity if need arises,
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    51
* all entities have an `eid` attribute (an integer) that is its
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    52
  primary key (but it is possible to declare uniqueness on other
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    53
  attributes)
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    54
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    55
Also |yams| supports the notions of:
4437
21f2e01fdd6a update exemples using the 3.6 api and add/fix some sections (schema, vreg, talk about CW_MODE in concepts...). So much to do :'(
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4430
diff changeset
    56
5400
b7ab099b128a [doc/book] various content fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
    57
* entity inheritance (quite experimental yet, and completely
b7ab099b128a [doc/book] various content fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5394
diff changeset
    58
  undocumented),
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    59
* relation type: that is, relationships can be established over a set
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    60
  of couple of entity types (henre the distinction made between
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    61
  `RelationType` and `RelationDefinition` below)
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    62
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    63
Finally |yams| has a few concepts of its own:
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    64
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    65
* relationships being oriented and binary, we call the left hand
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    66
  entity type the `subject` and the right hand entity type the
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    67
  `object`
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    68
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    69
.. note::
4437
21f2e01fdd6a update exemples using the 3.6 api and add/fix some sections (schema, vreg, talk about CW_MODE in concepts...). So much to do :'(
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4430
diff changeset
    70
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    71
   The |yams| schema is available at run time through the .schema
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    72
   attribute of the `vregistry`.  It's an instance of
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    73
   :class:`cubicweb.schema.Schema`, which extends
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    74
   :class:`yams.schema.Schema`.
4437
21f2e01fdd6a update exemples using the 3.6 api and add/fix some sections (schema, vreg, talk about CW_MODE in concepts...). So much to do :'(
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4430
diff changeset
    75
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    76
.. _EntityType:
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    77
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    78
Entity type
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    79
~~~~~~~~~~~
5220
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5145
diff changeset
    80
5145
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
    81
An entity type is an instance of :class:`yams.schema.EntitySchema`. Each entity type has
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
    82
a set of attributes and relations, and some permissions which define who can add, read,
4437
21f2e01fdd6a update exemples using the 3.6 api and add/fix some sections (schema, vreg, talk about CW_MODE in concepts...). So much to do :'(
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4430
diff changeset
    83
update or delete entities of this type.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    84
6342
efd5ba519263 [book] Talk about RichString in 'Yams schema' section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6150
diff changeset
    85
The following built-in types are available: ``String``,
efd5ba519263 [book] Talk about RichString in 'Yams schema' section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6150
diff changeset
    86
``Int``, ``Float``, ``Decimal``, ``Boolean``,
efd5ba519263 [book] Talk about RichString in 'Yams schema' section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6150
diff changeset
    87
``Date``, ``Datetime``, ``Time``, ``Interval``, ``Byte`` and
efd5ba519263 [book] Talk about RichString in 'Yams schema' section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6150
diff changeset
    88
``Password``. They can only be used as attributes of an other entity
efd5ba519263 [book] Talk about RichString in 'Yams schema' section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6150
diff changeset
    89
type.
efd5ba519263 [book] Talk about RichString in 'Yams schema' section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6150
diff changeset
    90
efd5ba519263 [book] Talk about RichString in 'Yams schema' section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6150
diff changeset
    91
There is also a `RichString` kindof type:
efd5ba519263 [book] Talk about RichString in 'Yams schema' section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6150
diff changeset
    92
efd5ba519263 [book] Talk about RichString in 'Yams schema' section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6150
diff changeset
    93
 .. autoclass:: yams.buildobjs.RichString
efd5ba519263 [book] Talk about RichString in 'Yams schema' section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6150
diff changeset
    94
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    95
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    96
You can find more base entity types in
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    97
:ref:`pre_defined_entity_types`.
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    98
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
    99
.. XXX yams inheritance
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   100
5220
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5145
diff changeset
   101
.. _RelationType:
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5145
diff changeset
   102
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   103
Relation type
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   104
~~~~~~~~~~~~~
5220
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5145
diff changeset
   105
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   106
A relation type is an instance of
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   107
:class:`yams.schema.RelationSchema`. A relation type is simply a
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   108
semantic definition of a kind of relationship that may occur in an
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   109
application.
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   110
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   111
It may be referenced by zero, one or more relation definitions.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   112
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   113
It is important to choose a good name, at least to avoid conflicts
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   114
with some semantically different relation defined in other cubes
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   115
(since there's only a shared name space for these names).
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   116
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   117
A relation type holds the following properties (which are hence shared
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   118
between all relation definitions of that type):
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   119
5145
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   120
* `inlined`: boolean handling the physical optimization for archiving
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   121
  the relation in the subject entity table, instead of creating a specific
4437
21f2e01fdd6a update exemples using the 3.6 api and add/fix some sections (schema, vreg, talk about CW_MODE in concepts...). So much to do :'(
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4430
diff changeset
   122
  table for the relation. This applies to relations where cardinality
21f2e01fdd6a update exemples using the 3.6 api and add/fix some sections (schema, vreg, talk about CW_MODE in concepts...). So much to do :'(
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4430
diff changeset
   123
  of subject->relation->object is 0..1 (`?`) or 1..1 (`1`) for *all* its relation
21f2e01fdd6a update exemples using the 3.6 api and add/fix some sections (schema, vreg, talk about CW_MODE in concepts...). So much to do :'(
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4430
diff changeset
   124
  definitions.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   125
5145
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   126
* `symmetric`: boolean indicating that the relation is symmetrical, which
4437
21f2e01fdd6a update exemples using the 3.6 api and add/fix some sections (schema, vreg, talk about CW_MODE in concepts...). So much to do :'(
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4430
diff changeset
   127
  means that `X relation Y` implies `Y relation X`.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   128
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   129
.. _RelationDefinition:
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   130
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   131
Relation definition
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   132
~~~~~~~~~~~~~~~~~~~
5220
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5145
diff changeset
   133
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   134
A relation definition is an instance of
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   135
:class:`yams.schema.RelationDefinition`. It is a complete triplet
4437
21f2e01fdd6a update exemples using the 3.6 api and add/fix some sections (schema, vreg, talk about CW_MODE in concepts...). So much to do :'(
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4430
diff changeset
   136
"<subject entity type> <relation type> <object entity type>".
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   137
5145
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   138
When creating a new instance of that class, the corresponding
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   139
:class:`RelationType` instance is created on the fly if necessary.
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   140
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   141
Properties
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   142
``````````
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   143
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   144
The available properties for relation definitions are enumerated
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   145
here. There are several kind of properties, as some relation
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   146
definitions are actually attribute definitions, and other are not.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   147
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   148
Some properties may be completely optional, other may have a default
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   149
value.
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   150
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   151
Common properties for attributes and relations:
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   152
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   153
* `description`: an unicode string describing an attribute or a
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   154
  relation. By default this string will be used in the editing form of
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   155
  the entity, which means that it is supposed to help the end-user and
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   156
  should be flagged by the function `_` to be properly
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   157
  internationalized.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   158
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   159
* `constraints`: a list of conditions/constraints that the relation has to
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   160
  satisfy (c.f. `Constraints`_)
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   161
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   162
* `cardinality`: a two character string specifying the cardinality of
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   163
  the relation. The first character defines the cardinality of the
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   164
  relation on the subject, and the second on the object. When a
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   165
  relation can have multiple subjects or objects, the cardinality
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   166
  applies to all, not on a one-to-one basis (so it must be
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   167
  consistent...). Default value is '**'. The possible values are
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   168
  inspired from regular expression syntax:
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   169
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   170
    * `1`: 1..1
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   171
    * `?`: 0..1
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   172
    * `+`: 1..n
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   173
    * `*`: 0..n
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   174
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   175
Attributes properties:
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   176
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   177
* `unique`: boolean indicating if the value of the attribute has to be
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   178
  unique or not within all entities of the same type (false by
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   179
  default)
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   180
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   181
* `indexed`: boolean indicating if an index needs to be created for
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   182
  this attribute in the database (false by default). This is useful
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   183
  only if you know that you will have to run numerous searches on the
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   184
  value of this attribute.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   185
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   186
* `default`: default value of the attribute. In case of date types, the values
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   187
  which could be used correspond to the RQL keywords `TODAY` and `NOW`.
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
   188
8125
7070250bf50d [schema] React to yams improvement of metadata attribute handling.
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 7797
diff changeset
   189
* `metadata`: Is also accepted as an argument of the attribute contructor. It is
7070250bf50d [schema] React to yams improvement of metadata attribute handling.
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 7797
diff changeset
   190
  not really an attribute property. see `Metadata`_ for details.
7070250bf50d [schema] React to yams improvement of metadata attribute handling.
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 7797
diff changeset
   191
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   192
Properties for `String` attributes:
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   193
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   194
* `fulltextindexed`: boolean indicating if the attribute is part of
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   195
  the full text index (false by default) (*applicable on the type
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   196
  `Byte` as well*)
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   197
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   198
* `internationalizable`: boolean indicating if the value of the
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   199
  attribute is internationalizable (false by default)
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   200
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   201
Relation properties:
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   202
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   203
* `composite`: string indicating that the subject (composite ==
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   204
  'subject') is composed of the objects of the relations. For the
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   205
  opposite case (when the object is composed of the subjects of the
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   206
  relation), we just set 'object' as value. The composition implies
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   207
  that when the relation is deleted (so when the composite is deleted,
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   208
  at least), the composed are also deleted.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   209
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   210
* `fulltext_container`: string indicating if the value if the full
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   211
  text indexation of the entity on one end of the relation should be
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   212
  used to find the entity on the other end. The possible values are
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   213
  'subject' or 'object'. For instance the use_email relation has that
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   214
  property set to 'subject', since when performing a full text search
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   215
  people want to find the entity using an email address, and not the
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   216
  entity representing the email address.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   217
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   218
Constraints
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   219
```````````
4032
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   220
5145
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   221
By default, the available constraint types are:
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   222
4032
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   223
General Constraints
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   224
......................
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   225
5145
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   226
* `SizeConstraint`: allows to specify a minimum and/or maximum size on
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   227
  string (generic case of `maxsize`)
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   228
5220
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5145
diff changeset
   229
* `BoundConstraint`: allows to specify a minimum and/or maximum value
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5145
diff changeset
   230
  on numeric types and date
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5145
diff changeset
   231
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5145
diff changeset
   232
.. sourcecode:: python
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5145
diff changeset
   233
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5145
diff changeset
   234
   from yams.constraints import BoundConstraint, TODAY
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5145
diff changeset
   235
   BoundConstraint('<=', TODAY())
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5145
diff changeset
   236
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5145
diff changeset
   237
* `IntervalBoundConstraint`: allows to specify an interval with
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5145
diff changeset
   238
  included values
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5145
diff changeset
   239
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5145
diff changeset
   240
.. sourcecode:: python
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5145
diff changeset
   241
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5145
diff changeset
   242
     class Node(EntityType):
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5145
diff changeset
   243
         latitude = Float(constraints=[IntervalBoundConstraint(-90, +90)])
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   244
5145
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   245
* `UniqueConstraint`: identical to "unique=True"
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   246
5145
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   247
* `StaticVocabularyConstraint`: identical to "vocabulary=(...)"
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   248
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   249
.. XXX Attribute, NOW
4437
21f2e01fdd6a update exemples using the 3.6 api and add/fix some sections (schema, vreg, talk about CW_MODE in concepts...). So much to do :'(
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4430
diff changeset
   250
4032
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   251
RQL Based Constraints
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   252
......................
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   253
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   254
RQL based constraints may take three arguments. The first one is the ``WHERE``
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   255
clause of a RQL query used by the constraint. The second argument ``mainvars``
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   256
is the ``Any`` clause of the query. By default this include `S` reserved for the
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   257
subject of the relation and `O` for the object. Additional variables could be
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   258
specified using ``mainvars``. The argument expects a single string with all
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   259
variable's name separated by spaces. The last one, ``msg``, is the error message
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   260
displayed when the constraint fails. As RQLVocabularyConstraint never fails the
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   261
third argument is not available.
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   262
5145
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   263
* `RQLConstraint`: allows to specify a RQL query that has to be satisfied
4032
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   264
  by the subject and/or the object of relation. In this query the variables
5145
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   265
  `S` and `O` are reserved for the relation subject and object entities.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   266
5145
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   267
* `RQLVocabularyConstraint`: similar to the previous type of constraint except
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   268
  that it does not express a "strong" constraint, which means it is only used to
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   269
  restrict the values listed in the drop-down menu of editing form, but it does
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   270
  not prevent another entity to be selected.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   271
5145
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   272
* `RQLUniqueConstraint`: allows to the specify a RQL query that ensure that an
4032
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   273
  attribute is unique in a specific context. The Query must **never** return more
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   274
  than a single result to be satisfied. In this query the variables `S` is
5145
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   275
  reserved for the relation subject entity. The other variables should be
4040
00e2f1ae625d Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 4032
diff changeset
   276
  specified with the second constructor argument (mainvars). This constraints
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   277
  should be used when UniqueConstraint doesn't fit. Here is a simple example.
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   278
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   279
.. sourcecode:: python
4040
00e2f1ae625d Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 4032
diff changeset
   280
00e2f1ae625d Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 4032
diff changeset
   281
    # Check that in the same Workflow each state's name is unique.  Using
00e2f1ae625d Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 4032
diff changeset
   282
    # UniqueConstraint (or unique=True) here would prevent states in different
00e2f1ae625d Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 4032
diff changeset
   283
    # workflows to have the same name.
00e2f1ae625d Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 4032
diff changeset
   284
00e2f1ae625d Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 4032
diff changeset
   285
    # With: State S, Workflow W, String N ; S state_of W, S name N
00e2f1ae625d Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 4032
diff changeset
   286
00e2f1ae625d Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 4032
diff changeset
   287
    RQLUniqueConstraint('S name N, S state_of WF, Y state_of WF, Y name N',
00e2f1ae625d Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 4032
diff changeset
   288
                        mainvars='Y',
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   289
                        msg=_('workflow already has a state of that name'))
4040
00e2f1ae625d Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 4032
diff changeset
   290
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   291
.. XXX note about how to add new constraint
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   292
4936
a4b772a0d801 Fixed some of the documentation warnings when building the book with sphinx.
Adrien Chauve <adrien.chauve@logilab.fr>
parents: 4744
diff changeset
   293
.. _securitymodel:
a4b772a0d801 Fixed some of the documentation warnings when building the book with sphinx.
Adrien Chauve <adrien.chauve@logilab.fr>
parents: 4744
diff changeset
   294
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   295
The security model
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   296
~~~~~~~~~~~~~~~~~~
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   297
5145
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   298
The security model of `CubicWeb` is based on `Access Control List`.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   299
The main principles are:
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   300
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   301
* users and groups of users
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   302
* a user belongs to at least one group of user
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   303
* permissions (read, update, create, delete)
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   304
* permissions are assigned to groups (and not to users)
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   305
2175
16d3c37c5d28 [doc] improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2172
diff changeset
   306
For *CubicWeb* in particular:
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   307
5145
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   308
* we associate rights at the entities/relations schema level
6148
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   309
6591
b5ed84c53b3f [book] complete datamodel definition section with default permissions
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6342
diff changeset
   310
* the default groups are: `managers`, `users` and `guests`
6148
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   311
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   312
* users belong to the `users` group
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   313
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   314
* there is a virtual group called `owners` to which we can associate only
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   315
  `delete` and `update` permissions
5145
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   316
6148
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   317
  * we can not add users to the `owners` group, they are implicitly added to it
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   318
    according to the context of the objects they own
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   319
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   320
  * the permissions of this group are only checked on `update`/`delete` actions
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   321
    if all the other groups the user belongs to do not provide those permissions
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   322
4437
21f2e01fdd6a update exemples using the 3.6 api and add/fix some sections (schema, vreg, talk about CW_MODE in concepts...). So much to do :'(
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4430
diff changeset
   323
Setting permissions is done with the attribute `__permissions__` of entities and
6148
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   324
relation definition. The value of this attribute is a dictionary where the keys
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   325
are the access types (action), and the values are the authorized groups or
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   326
expressions.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   327
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   328
For an entity type, the possible actions are `read`, `add`, `update` and
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   329
`delete`.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   330
6148
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   331
For a relation, the possible actions are `read`, `add`, and `delete`.
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   332
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   333
For an attribute, the possible actions are `read`, and `update`.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   334
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   335
For each access type, a tuple indicates the name of the authorized groups and/or
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   336
one or multiple RQL expressions to satisfy to grant access. The access is
5145
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   337
provided if the user is in one of the listed groups or if one of the RQL condition
4452
5d6dec2c4650 [doc] small fixes on security part
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 3811
diff changeset
   338
is satisfied.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   339
6591
b5ed84c53b3f [book] complete datamodel definition section with default permissions
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6342
diff changeset
   340
Default permissions
b5ed84c53b3f [book] complete datamodel definition section with default permissions
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6342
diff changeset
   341
```````````````````
b5ed84c53b3f [book] complete datamodel definition section with default permissions
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6342
diff changeset
   342
b5ed84c53b3f [book] complete datamodel definition section with default permissions
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6342
diff changeset
   343
The default permissions for ``EntityType`` are:
b5ed84c53b3f [book] complete datamodel definition section with default permissions
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6342
diff changeset
   344
b5ed84c53b3f [book] complete datamodel definition section with default permissions
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6342
diff changeset
   345
.. sourcecode:: python
b5ed84c53b3f [book] complete datamodel definition section with default permissions
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6342
diff changeset
   346
b5ed84c53b3f [book] complete datamodel definition section with default permissions
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6342
diff changeset
   347
   __permissions__ = {
b5ed84c53b3f [book] complete datamodel definition section with default permissions
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6342
diff changeset
   348
        'read': ('managers', 'users', 'guests',),
b5ed84c53b3f [book] complete datamodel definition section with default permissions
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6342
diff changeset
   349
        'update': ('managers', 'owners',),
b5ed84c53b3f [book] complete datamodel definition section with default permissions
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6342
diff changeset
   350
        'delete': ('managers', 'owners'),
b5ed84c53b3f [book] complete datamodel definition section with default permissions
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6342
diff changeset
   351
        'add': ('managers', 'users',)
b5ed84c53b3f [book] complete datamodel definition section with default permissions
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6342
diff changeset
   352
        }
b5ed84c53b3f [book] complete datamodel definition section with default permissions
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6342
diff changeset
   353
b5ed84c53b3f [book] complete datamodel definition section with default permissions
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6342
diff changeset
   354
The default permissions for relations are:
b5ed84c53b3f [book] complete datamodel definition section with default permissions
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6342
diff changeset
   355
b5ed84c53b3f [book] complete datamodel definition section with default permissions
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6342
diff changeset
   356
.. sourcecode:: python
b5ed84c53b3f [book] complete datamodel definition section with default permissions
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6342
diff changeset
   357
b5ed84c53b3f [book] complete datamodel definition section with default permissions
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6342
diff changeset
   358
   __permissions__ = {'read': ('managers', 'users', 'guests',),
b5ed84c53b3f [book] complete datamodel definition section with default permissions
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6342
diff changeset
   359
                    'delete': ('managers', 'users'),
b5ed84c53b3f [book] complete datamodel definition section with default permissions
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6342
diff changeset
   360
                    'add': ('managers', 'users',)}
b5ed84c53b3f [book] complete datamodel definition section with default permissions
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6342
diff changeset
   361
b5ed84c53b3f [book] complete datamodel definition section with default permissions
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6342
diff changeset
   362
The default permissions for attributes are:
b5ed84c53b3f [book] complete datamodel definition section with default permissions
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6342
diff changeset
   363
b5ed84c53b3f [book] complete datamodel definition section with default permissions
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6342
diff changeset
   364
.. sourcecode:: python
b5ed84c53b3f [book] complete datamodel definition section with default permissions
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6342
diff changeset
   365
b5ed84c53b3f [book] complete datamodel definition section with default permissions
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6342
diff changeset
   366
   __permissions__ = {'read': ('managers', 'users', 'guests',),
b5ed84c53b3f [book] complete datamodel definition section with default permissions
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6342
diff changeset
   367
                     'update': ('managers', ERQLExpression('U has_update_permission X')),}
6148
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   368
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   369
The standard user groups
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   370
````````````````````````
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   371
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   372
* `guests`
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   373
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   374
* `users`
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   375
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   376
* `managers`
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   377
5145
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   378
* `owners`: virtual group corresponding to the entity's owner.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   379
  This can only be used for the actions `update` and `delete` of an entity
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   380
  type.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   381
6148
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   382
It is also possible to use specific groups if they are defined in the precreate
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   383
script of the cube (``migration/precreate.py``). Defining groups in postcreate
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   384
script or later makes them unavailable for security purposes (in this case, an
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   385
`sync_schema_props_perms` command has to be issued in a CubicWeb shell).
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   386
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   387
3283
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 3144
diff changeset
   388
Use of RQL expression for write permissions
4464
437cc57f7474 fix rest syntax error
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4459
diff changeset
   389
```````````````````````````````````````````
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   390
6148
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   391
It is possible to define RQL expression to provide update permission (`add`,
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   392
`delete` and `update`) on entity type / relation definitions. An rql expression
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   393
is a piece of query (corresponds to the WHERE statement of an RQL query), and the
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   394
expression will be considered as satisfied if it returns some results. They can
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   395
not be used in `read` permission.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   396
6148
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   397
To use RQL expression in entity type permission:
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   398
6148
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   399
* you have to use the class :class:`~cubicweb.schema.ERQLExpression`
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   400
5145
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   401
* in this expression, the variables `X` and `U` are pre-defined references
6148
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   402
  respectively on the current entity (on which the action is verified) and on the
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   403
  user who send the request
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   404
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   405
For RQL expressions on a relation type, the principles are the same except for
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   406
the following:
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   407
6148
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   408
* you have to use the class :class:`~cubicweb.schema.RRQLExpression` instead of
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   409
  :class:`~cubicweb.schema.ERQLExpression`
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   410
6148
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   411
* in the expression, the variables `S`, `O` and `U` are pre-defined references to
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   412
  respectively the subject and the object of the current relation (on which the
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   413
  action is being verified) and the user who executed the query
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   414
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   415
To define security for attributes of an entity (non-final relation), you have to
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   416
use the class :class:`~cubicweb.schema.ERQLExpression` in which `X` represents
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   417
the entity the attribute belongs to.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   418
6148
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   419
It is possible to use in those expression a special relation
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   420
`has_<ACTION>_permission` where the subject is the user (eg 'U') and the object
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   421
is any variable representing an entity (usually 'X' in
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   422
:class:`~cubicweb.schema.ERQLExpression`, 'S' or 'O' in
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   423
:class:`~cubicweb.schema.RRQLExpression`), meaning that the user needs to have
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   424
permission to execute the action <ACTION> on the entities represented by this
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   425
variable. It's recommanded to use this feature whenever possible since it
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   426
simplify greatly complex security definition and upgrade.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   427
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   428
6148
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   429
.. sourcecode:: python
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   430
6148
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   431
  class my_relation(RelationDefinition):
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   432
    __permissions__ = {'read': ('managers', 'users'),
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   433
                       'add': ('managers', RRQLExpression('U has_update_permission S')),
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   434
                       'delete': ('managers', RRQLExpression('U has_update_permission S'))
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   435
		       }
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   436
6148
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   437
In the above example, user will be allowed to add/delete `my_relation` if he has
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   438
the `update` permission on the subject of the relation.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   439
5351
ecf07370e6db [doc/book] a proper note (style)
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5349
diff changeset
   440
.. note::
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   441
6148
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   442
  Potentially, the `use of an RQL expression to add an entity or a relation` can
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   443
  cause problems for the user interface, because if the expression uses the
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   444
  entity or the relation to create, we are not able to verify the permissions
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   445
  before we actually added the entity (please note that this is not a problem for
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   446
  the RQL server at all, because the permissions checks are done after the
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   447
  creation). In such case, the permission check methods
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   448
  (CubicWebEntitySchema.check_perm and has_perm) can indicate that the user is
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   449
  not allowed to create this entity while it would obtain the permission.  To
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   450
  compensate this problem, it is usually necessary in such case to use an action
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   451
  that reflects the schema permissions but which check properly the permissions
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   452
  so that it would show up only if possible.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   453
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
   454
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   455
Use of RQL expression for reading rights
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   456
````````````````````````````````````````
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   457
5145
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   458
The principles are the same but with the following restrictions:
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   459
6148
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   460
* you can not use rql expression for the `read` permission of relations and
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   461
  attributes,
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   462
6148
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   463
* you can not use special `has_<ACTION>_permission` relation in the rql
59c446a813b5 [book] more about has_<action>_permission and enhance a bit security definition section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6120
diff changeset
   464
  expression.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   465
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   466
6120
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   467
Important notes about write permissions checking
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   468
````````````````````````````````````````````````
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   469
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   470
Write permissions (e.g. 'add', 'update', 'delete') are checked in core hooks.
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   471
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   472
When a permission is checked slightly vary according to if it's an entity or
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   473
relation, and if the relation is an attribute relation or not). It's important to
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   474
understand that since according to when a permission is checked, values returned
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   475
by rql expressions may changes, hence the permission being granted or not.
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   476
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   477
Here are the current rules:
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   478
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   479
1. permission to add/update entity and its attributes are checked:
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   480
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   481
   - on commit if the entity has been added
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   482
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   483
   - in an 'after_update_entity' hook if the entity has been updated. If it fails
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   484
     at this time, it will be retried on commit (hence you get the permission if
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   485
     you have it just after the modification or *at* commit time)
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   486
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   487
2. permission to delete an entity is checked in 'before_delete_entity' hook
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   488
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   489
3. permission to add a relation is checked either:
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   490
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   491
   - in 'before_add_relation' hook if the relation type is in the
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   492
     `BEFORE_ADD_RELATIONS` set
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   493
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   494
   - else at commit time if the relation type is in the `ON_COMMIT_ADD_RELATIONS`
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   495
     set
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   496
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   497
   - else in 'after_add_relation' hook (the default)
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   498
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   499
4. permission to delete a relation is checked in 'before_delete_relation' hook
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   500
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   501
Last but not least, remember queries issued from hooks and operation are by
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   502
default 'unsafe', eg there are no read or write security checks.
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   503
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   504
See :mod:`cubicweb.hooks.security` for more details.
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   505
c000e41316ec [book] some more documentation and cleanups
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5953
diff changeset
   506
5953
af48c527aea7 [doc/book] fix & enhance rql intro chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5400
diff changeset
   507
.. _yams_example:
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   508
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   509
Defining your schema using yams
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   510
-------------------------------
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   511
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   512
Entity type definition
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   513
~~~~~~~~~~~~~~~~~~~~~~
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   514
5145
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   515
An entity type is defined by a Python class which inherits from
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   516
:class:`yams.buildobjs.EntityType`.  The class definition contains the
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   517
description of attributes and relations for the defined entity type.
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   518
The class name corresponds to the entity type name. It is expected to
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   519
be defined in the module ``mycube.schema``.
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   520
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   521
:Note on schema definition:
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   522
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   523
 The code in ``mycube.schema`` is not meant to be executed. The class
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   524
 EntityType mentioned above is different from the EntitySchema class
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   525
 described in the previous chapter. EntityType is a helper class to
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   526
 make Entity definition easier. Yams will process EntityType classes
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   527
 and create EntitySchema instances from these class definitions. Similar
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   528
 manipulation happen for relations.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   529
4437
21f2e01fdd6a update exemples using the 3.6 api and add/fix some sections (schema, vreg, talk about CW_MODE in concepts...). So much to do :'(
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4430
diff changeset
   530
When defining a schema using python files, you may use the following shortcuts:
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   531
5145
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   532
- `required`: boolean indicating if the attribute is required, ed subject cardinality is '1'
4437
21f2e01fdd6a update exemples using the 3.6 api and add/fix some sections (schema, vreg, talk about CW_MODE in concepts...). So much to do :'(
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4430
diff changeset
   533
5145
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   534
- `vocabulary`: specify static possible values of an attribute
4437
21f2e01fdd6a update exemples using the 3.6 api and add/fix some sections (schema, vreg, talk about CW_MODE in concepts...). So much to do :'(
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4430
diff changeset
   535
5145
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   536
- `maxsize`: integer providing the maximum size of a string (no limit by default)
4437
21f2e01fdd6a update exemples using the 3.6 api and add/fix some sections (schema, vreg, talk about CW_MODE in concepts...). So much to do :'(
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4430
diff changeset
   537
21f2e01fdd6a update exemples using the 3.6 api and add/fix some sections (schema, vreg, talk about CW_MODE in concepts...). So much to do :'(
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4430
diff changeset
   538
For example:
21f2e01fdd6a update exemples using the 3.6 api and add/fix some sections (schema, vreg, talk about CW_MODE in concepts...). So much to do :'(
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4430
diff changeset
   539
21f2e01fdd6a update exemples using the 3.6 api and add/fix some sections (schema, vreg, talk about CW_MODE in concepts...). So much to do :'(
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4430
diff changeset
   540
.. sourcecode:: python
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   541
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   542
  class Person(EntityType):
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   543
    """A person with the properties and the relations necessary for my
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   544
    application"""
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   545
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   546
    last_name = String(required=True, fulltextindexed=True)
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   547
    first_name = String(required=True, fulltextindexed=True)
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   548
    title = String(vocabulary=('Mr', 'Mrs', 'Miss'))
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   549
    date_of_birth = Date()
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   550
    works_for = SubjectRelation('Company', cardinality='?*')
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   551
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   552
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   553
The entity described above defines three attributes of type String,
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   554
last_name, first_name and title, an attribute of type Date for the date of
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   555
birth and a relation that connects a `Person` to another entity of type
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   556
`Company` through the semantic `works_for`.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   557
6342
efd5ba519263 [book] Talk about RichString in 'Yams schema' section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6150
diff changeset
   558
efd5ba519263 [book] Talk about RichString in 'Yams schema' section
Stephanie Marcu <stephanie.marcu@logilab.fr>
parents: 6150
diff changeset
   559
5145
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   560
:Naming convention:
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   561
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   562
 Entity class names must start with an uppercase letter. The common
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   563
 usage is to use ``CamelCase`` names.
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   564
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   565
 Attribute and relation names must start with a lowercase letter. The
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   566
 common usage is to use ``underscore_separated_words``. Attribute and
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   567
 relation names starting with a single underscore are permitted, to
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   568
 denote a somewhat "protected" or "private" attribute.
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   569
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   570
 In any case, identifiers starting with "CW" or "cw" are reserved for
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   571
 internal use by the framework.
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   572
8125
7070250bf50d [schema] React to yams improvement of metadata attribute handling.
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 7797
diff changeset
   573
 .. _Metadata:
7070250bf50d [schema] React to yams improvement of metadata attribute handling.
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 7797
diff changeset
   574
7070250bf50d [schema] React to yams improvement of metadata attribute handling.
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 7797
diff changeset
   575
 Some attribute using the name of another attribute as prefix are considered
7070250bf50d [schema] React to yams improvement of metadata attribute handling.
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 7797
diff changeset
   576
 metadata.  For example, if an EntityType have both a ``data`` and
7070250bf50d [schema] React to yams improvement of metadata attribute handling.
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 7797
diff changeset
   577
 ``data_format`` attribute, ``data_format`` is view as the ``format`` metadata
7070250bf50d [schema] React to yams improvement of metadata attribute handling.
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 7797
diff changeset
   578
 of ``data``. Later the :meth:`cw_attr_metadata` method will allow you to fetch
7070250bf50d [schema] React to yams improvement of metadata attribute handling.
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 7797
diff changeset
   579
 metadata related to an attribute. There are only three valid metadata names:
7070250bf50d [schema] React to yams improvement of metadata attribute handling.
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 7797
diff changeset
   580
 ``format``, ``encoding`` and ``name``.
7070250bf50d [schema] React to yams improvement of metadata attribute handling.
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 7797
diff changeset
   581
5145
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   582
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   583
The name of the Python attribute corresponds to the name of the attribute
2175
16d3c37c5d28 [doc] improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2172
diff changeset
   584
or the relation in *CubicWeb* application.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   585
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   586
An attribute is defined in the schema as follows::
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
   587
8125
7070250bf50d [schema] React to yams improvement of metadata attribute handling.
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 7797
diff changeset
   588
    attr_name = AttrType(*properties, metadata={})
7070250bf50d [schema] React to yams improvement of metadata attribute handling.
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 7797
diff changeset
   589
7070250bf50d [schema] React to yams improvement of metadata attribute handling.
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 7797
diff changeset
   590
where
7070250bf50d [schema] React to yams improvement of metadata attribute handling.
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 7797
diff changeset
   591
7070250bf50d [schema] React to yams improvement of metadata attribute handling.
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 7797
diff changeset
   592
* `AttrType`: is one of the type listed in EntityType_,
7070250bf50d [schema] React to yams improvement of metadata attribute handling.
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 7797
diff changeset
   593
7070250bf50d [schema] React to yams improvement of metadata attribute handling.
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 7797
diff changeset
   594
* `properties`: is a list of the attribute needs to satisfy (see `Properties`_
7070250bf50d [schema] React to yams improvement of metadata attribute handling.
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 7797
diff changeset
   595
  for more details),
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   596
8125
7070250bf50d [schema] React to yams improvement of metadata attribute handling.
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 7797
diff changeset
   597
* `metadata`: is a dictionary of meta attributes related to ``attr_name``.
7070250bf50d [schema] React to yams improvement of metadata attribute handling.
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 7797
diff changeset
   598
  Dictionary keys are the name of the meta attribute. Dictionary values
7070250bf50d [schema] React to yams improvement of metadata attribute handling.
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 7797
diff changeset
   599
  attributes objects (like the content of ``AttrType``). For each entry of the
7070250bf50d [schema] React to yams improvement of metadata attribute handling.
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 7797
diff changeset
   600
  metadata dictionary a ``<attr_name>_<key> = <value>`` attribute is
7070250bf50d [schema] React to yams improvement of metadata attribute handling.
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 7797
diff changeset
   601
  automaticaly added to the EntityType.  see `Metadata`_ section for details
7070250bf50d [schema] React to yams improvement of metadata attribute handling.
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 7797
diff changeset
   602
  about valid key.
7070250bf50d [schema] React to yams improvement of metadata attribute handling.
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 7797
diff changeset
   603
7070250bf50d [schema] React to yams improvement of metadata attribute handling.
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 7797
diff changeset
   604
7070250bf50d [schema] React to yams improvement of metadata attribute handling.
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 7797
diff changeset
   605
 ---
7070250bf50d [schema] React to yams improvement of metadata attribute handling.
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 7797
diff changeset
   606
7070250bf50d [schema] React to yams improvement of metadata attribute handling.
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 7797
diff changeset
   607
While building your schema
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   608
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   609
* it is possible to use the attribute `meta` to flag an entity type as a `meta`
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   610
  (e.g. used to describe/categorize other entities)
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   611
5145
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   612
.. XXX the paragraph below needs clarification and / or moving out in
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   613
.. another place
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   614
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   615
*Note*: if you end up with an `if` in the definition of your entity, this probably
4430
0b6a069eb29e le patch added_tips a été importé
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4040
diff changeset
   616
means that you need two separate entities that implement the `ITree` interface and
0b6a069eb29e le patch added_tips a été importé
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4040
diff changeset
   617
get the result from `.children()` which ever entity is concerned.
0b6a069eb29e le patch added_tips a été importé
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4040
diff changeset
   618
5953
af48c527aea7 [doc/book] fix & enhance rql intro chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5400
diff changeset
   619
.. Inheritance
af48c527aea7 [doc/book] fix & enhance rql intro chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5400
diff changeset
   620
.. ```````````
af48c527aea7 [doc/book] fix & enhance rql intro chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5400
diff changeset
   621
.. XXX feed me
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   622
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   623
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   624
Definition of relations
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   625
~~~~~~~~~~~~~~~~~~~~~~~
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   626
5953
af48c527aea7 [doc/book] fix & enhance rql intro chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5400
diff changeset
   627
.. XXX add note about defining relation type / definition
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   628
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   629
A relation is defined by a Python class heriting `RelationType`. The name
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   630
of the class corresponds to the name of the type. The class then contains
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
   631
a description of the properties of this type of relation, and could as well
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   632
contain a string for the subject and a string for the object. This allows to create
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
   633
new definition of associated relations, (so that the class can have the
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   634
definition properties from the relation) for example ::
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   635
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   636
  class locked_by(RelationType):
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   637
    """relation on all entities indicating that they are locked"""
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   638
    inlined = True
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   639
    cardinality = '?*'
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   640
    subject = '*'
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   641
    object = 'CWUser'
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   642
5145
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   643
If provided, the `subject` and `object` attributes denote the subject
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   644
and object of the various relation definitions related to the relation
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   645
type. Allowed values for these attributes are:
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   646
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   647
* a string corresponding to an entity type
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   648
* a tuple of string corresponding to multiple entity types
6150
98642a11aea3 remove some deprecated stuff about relation definition
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6148
diff changeset
   649
* the '*' special string, meaning all types of entities
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   650
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   651
When a relation is not inlined and not symmetrical, and it does not require
5145
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   652
specific permissions, it can be defined using a `SubjectRelation`
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   653
attribute in the EntityType class. The first argument of `SubjectRelation` gives
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   654
the entity type for the object of the relation.
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   655
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   656
:Naming convention:
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   657
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   658
 Although this way of defining relations uses a Python class, the
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   659
 naming convention defined earlier prevails over the PEP8 conventions
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   660
 used in the framework: relation type class names use
5220
42f854b6083d [doc/book] complete chapter on hooks & ops
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5145
diff changeset
   661
 ``underscore_separated_words``.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   662
5145
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   663
:Historical note:
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   664
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   665
   It has been historically possible to use `ObjectRelation` which
5953
af48c527aea7 [doc/book] fix & enhance rql intro chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5400
diff changeset
   666
   defines a relation in the opposite direction. This feature is
5145
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   667
   deprecated and therefore should not be used in newly written code.
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   668
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   669
:Future deprecation note:
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   670
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   671
  In an even more remote future, it is quite possible that the
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   672
  SubjectRelation shortcut will become deprecated, in favor of the
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   673
  RelationType declaration which offers some advantages in the context
bfa4d775219f added information about the naming conventions in schema.py
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 4936
diff changeset
   674
  of reusable cubes.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   675
7797
a71618a75b53 backport stable
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7782
diff changeset
   676
  
5319
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   677
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   678
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   679
Handling schema changes
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   680
~~~~~~~~~~~~~~~~~~~~~~~
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   681
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   682
Also, it should be clear that to properly handle data migration, an
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   683
instance's schema is stored in the database, so the python schema file
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   684
used to defined it is only read when the instance is created or
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   685
upgraded.
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   686
9b1b7020d179 [doc/book] an introduction to yams, layout tweaks
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5220
diff changeset
   687
.. XXX complete me