doc/book/en/development/datamodel/definition.rst
author Sylvain Thénault <sylvain.thenault@logilab.fr>
Wed, 03 Feb 2010 20:33:49 +0100
changeset 4442 7bc0e4ed4109
parent 4437 21f2e01fdd6a
child 4446 a413fac5ff5e
permissions -rw-r--r--
fix stupid sed
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     1
.. -*- coding: utf-8 -*-
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     2
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     3
Yams *schema*
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     4
-------------
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     5
2476
1294a6bdf3bf application -> instance where it makes sense
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 2175
diff changeset
     6
The **schema** is the core piece of a *CubicWeb* instance as it defines
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     7
the handled data model. It is based on entity types that are either already
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
     8
defined in the *CubicWeb* standard library; or more specific types defined
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
     9
in cubes. The schema for a cube is defined in a :file:schema.py file or in
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
    10
one or more Python files under the :file:`schema` directory (python package).
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    11
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    12
At this point, it is important to make clear the difference between
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    13
*relation type* and *relation definition*: a *relation type* is only a relation
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
    14
name with potentially other additionnal properties (see below), whereas a
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
    15
*relation definition* is a complete triplet
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
    16
"<subject entity type> <relation type> <object entity type>".
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
    17
A relation type could have been implied if none is related to a
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    18
relation definition of the schema.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    19
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
    20
Also, it should be clear that to properly handle data migration, an instance'schema
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
    21
is stored in the database, so the python schema file used to defined it are only readen
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
    22
when the instance is created or upgraded.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    23
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
    24
The following built-in types are available : `String`, `Int`, `Float`,
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
    25
`Decimal`, `Boolean`, `Date`, `Datetime`, `Time`, `Interval`, `Byte`
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    26
and `Password`.
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
    27
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
    28
You'll also have access to :ref:`CWBaseEntityTypes_:base cubicweb entitye types`.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    29
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
    30
The instance schema is accessible through the .schema attribute of the
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
    31
`vregistry`.  It's an instance of :class:`cubicweb.schema.Schema`, which
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
    32
extends :class:`yams.schema.Schema`.
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
    33
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
    34
:note:
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
    35
  In previous yams versions, almost all classes where available without
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
    36
  any import, but the should now be explicitely imported.
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
    37
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    38
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    39
Entity type
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    40
~~~~~~~~~~~
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
    41
It's an instance of :class:`yams.schema.EntitySchema`. Each entity types has
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
    42
a set of attributes and relation and some permissions, defining who can add, read,
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
    43
update or delete entities of this type.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    44
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    45
XXX yams inheritance
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    46
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    47
Relation type
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    48
~~~~~~~~~~~~~
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
    49
It's an instance of :class:`yams.schema.RelationSchema`. A relation type is simply
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
    50
a semantic definition of a kind of relationship that may occurs in your application.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    51
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
    52
It's important to choose a good name, at least to avoid conflicts with some semantically
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
    53
different relation defined in other cubes (since we've no namespace yet).
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    54
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
    55
A relation type hold the following properties (which are hence shared between all
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
relation definitions of that type):
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    57
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    58
* `inlined` : boolean handling the physical optimization for archiving
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    59
  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
    60
  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
    61
  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
    62
  definitions.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    63
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    64
* `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
    65
  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
    66
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    67
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    68
Relation definition
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    69
~~~~~~~~~~~~~~~~~~~
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
It's an instance of :class:`yams.schema.RelationDefinition`. It is a complete triplet
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
    71
"<subject entity type> <relation type> <object entity type>".
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    72
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    73
Properties
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    74
``````````
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    75
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
    76
* Optional properties for attributes and relations :
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
  - `description` : a string describing an attribute or a relation. By default
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    79
    this string will be used in the editing form of the entity, which means
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    80
    that it is supposed to help the end-user and should be flagged by the
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    81
    function `_` to be properly internationalized.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    82
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    83
  - `constraints` : a list of conditions/constraints that the relation has to
3581
669854258b90 [doc] various fixes
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 3283
diff changeset
    84
    satisfy (c.f. `Constraints`_)
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    85
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    86
  - `cardinality` : a two character string which specify the cardinality of the
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    87
    relation. The first character defines the cardinality of the relation on
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
    88
    the subject, and the second on the object. When a relation can have
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    89
    multiple subjects or objects, the cardinality applies to all,
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    90
    not on a one-to-one basis (so it must be consistent...). The possible
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    91
    values are inspired from regular expression syntax :
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    92
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    93
    * `1`: 1..1
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    94
    * `?`: 0..1
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    95
    * `+`: 1..n
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    96
    * `*`: 0..n
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    97
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
    98
* optional properties for attributes :
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    99
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   100
  - `unique` : boolean indicating if the value of the attribute has to be unique
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   101
    or not within all entities of the same type (false by default)
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   102
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
   103
  - `indexed` : boolean indicating if an index needs to be created for this
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   104
    attribute in the database (false by default). This is useful only if
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   105
    you know that you will have to run numerous searches on the value of this
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   106
    attribute.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   107
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   108
  - `default` : default value of the attribute. In case of date types, the values
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   109
    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
   110
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
   111
* optional properties of type `String` :
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   112
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   113
  - `fulltextindexed` : boolean indicating if the attribute is part of
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   114
    the full text index (false by default) (*applicable on the type `Byte`
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   115
    as well*)
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   116
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   117
  - `internationalizable` : boolean indicating if the value of the attribute
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   118
    is internationalizable (false by default)
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   119
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
   120
* optional properties for relations :
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   121
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   122
  - `composite` : string indicating that the subject (composite == 'subject')
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   123
    is composed of the objects of the relations. For the opposite case (when
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
   124
    the object is composed of the subjects of the relation), we just set
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   125
    'object' as value. The composition implies that when the relation
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
   126
    is deleted (so when the composite is deleted, at least), the composed are also deleted.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   127
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   128
  - `fti_container`: XXX feed me
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   129
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   130
Constraints
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   131
```````````
4032
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   132
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   133
By default, the available constraint types are :
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   134
4032
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   135
General Constraints
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   136
......................
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   137
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   138
* `SizeConstraint` : allows to specify a minimum and/or maximum size on
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   139
  string (generic case of `maxsize`)
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   140
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
   141
* `BoundConstraint` : allows to specify a minimum and/or maximum value on
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   142
  numeric types
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   143
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   144
* `UniqueConstraint` : identical to "unique=True"
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   145
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   146
* `StaticVocabularyConstraint` : identical to "vocabulary=(...)"
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   147
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
   148
XXX Attribute, TODAY, NOW
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
   149
4032
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   150
RQL Based Constraints
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   151
......................
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   152
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   153
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
   154
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
   155
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
   156
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
   157
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
   158
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
   159
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
   160
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
   161
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   162
* `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
   163
  by the subject and/or the object of relation. In this query the variables
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
   164
  `S` and `O` are reserved for the entities subject and object of the
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   165
  relation.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   166
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   167
* `RQLVocabularyConstraint` : similar to the previous type of constraint except
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   168
  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
   169
  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
   170
  not prevent another entity to be selected.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   171
4032
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   172
* `RQLUniqueConstraint` : allows to the specify a RQL query that ensure that an
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   173
  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
   174
  than a single result to be satisfied. In this query the variables `S` is
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   175
  reserved for the entity subject of the relation. The other variable should be
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   176
  specified with the second constructor argument (mainvars). This constraints
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   177
  should be used when UniqueConstraint doesn't fit. Here is a simple example ::
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   178
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   179
    # Check that in the same Workflow each state's name is unique.  Using
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   180
    # UniqueConstraint (or unique=True) here would prevent states in different
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   181
    # workflows to have the same name.
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   182
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   183
    # With: State S, Workflow W, String N ; S state_of W, S name N
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   184
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   185
    RQLUniqueConstraint('S name N, S state_of WF, Y state_of WF, Y name N',
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   186
                        mainvars='Y',
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   187
                        msg=_('workflow already have a state of that name'))
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   188
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   189
c3a018efe7c9 Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3811
diff changeset
   190
4040
00e2f1ae625d Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 4032
diff changeset
   191
* `RQLUniqueConstraint` : allows to the specify a RQL query that ensure that an
00e2f1ae625d Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 4032
diff changeset
   192
  attribute is unique in a specific context. The Query must **never** return more
00e2f1ae625d Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 4032
diff changeset
   193
  than a single result to be satisfied. In this query the variables `S` is
00e2f1ae625d Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 4032
diff changeset
   194
  reserved for the entity subject of the relation. The other variable should be
00e2f1ae625d Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 4032
diff changeset
   195
  specified with the second constructor argument (mainvars). This constraints
00e2f1ae625d Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 4032
diff changeset
   196
  should be used when UniqueConstraint doesn't fit. Here is a simple example ::
00e2f1ae625d Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 4032
diff changeset
   197
00e2f1ae625d Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 4032
diff changeset
   198
    # 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
   199
    # 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
   200
    # 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
   201
00e2f1ae625d Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 4032
diff changeset
   202
    # 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
   203
00e2f1ae625d Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 4032
diff changeset
   204
    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
   205
                        mainvars='Y',
00e2f1ae625d Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 4032
diff changeset
   206
                        msg=_('workflow already have a state of that name'))
00e2f1ae625d Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 4032
diff changeset
   207
00e2f1ae625d Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 4032
diff changeset
   208
00e2f1ae625d Update generic RQL Based Constraints and RQLUniqueConstraint doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 4032
diff changeset
   209
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   210
XXX note about how to add new constraint
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   211
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   212
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   213
The security model
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   214
~~~~~~~~~~~~~~~~~~
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   215
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
   216
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
   217
The main principles are:
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   218
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   219
* users and groups of users
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   220
* 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
   221
* permissions (read, update, create, delete)
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   222
* permissions are assigned to groups (and not to users)
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   223
2175
16d3c37c5d28 [doc] improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2172
diff changeset
   224
For *CubicWeb* in particular:
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   225
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   226
* we associate rights at the enttities/relations schema level
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   227
* for each entity, we distinguish four kind of permissions: read,
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   228
  add, update and delete
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   229
* for each relation, we distinguish three king of permissions: read,
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   230
  add and delete (we can not modify a relation)
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   231
* the basic groups are: Administrators, Users and Guests
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   232
* by default, users belongs to the group Users
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   233
* there is a virtual group called `Owners users` to which we
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   234
  can associate only deletion and update permissions
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   235
* we can not add users to the `Owners users` group, they are
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   236
  implicetely added to it according to the context of the objects
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   237
  they own
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   238
* the permissions of this group are only be checked on update/deletion
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   239
  actions if all the other groups the user belongs does not provide
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   240
  those permissions
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   241
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
   242
Setting permissions is done with the attribute `__permissions__` of entities and
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   243
relation types. It defines a dictionary where the keys are the access types
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   244
(action), and the values are the authorized groups or expressions.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   245
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   246
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
   247
`delete`.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   248
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   249
For a relation type, the possible actions are `read`, `add`, and `delete`.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   250
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   251
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
   252
one or multiple RQL expressions to satisfy to grant access. The access is
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   253
provided once the user is in the listed groups or one of the RQL condition is
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   254
satisfied.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   255
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   256
The standard user groups
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   257
````````````````````````
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   258
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   259
* `guests`
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   260
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   261
* `users`
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   262
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   263
* `managers`
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   264
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   265
* `owners` : virtual group corresponding to the entity's owner.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   266
  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
   267
  type.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   268
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
   269
It is also possible to use specific groups if they are defined in the precreate
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   270
of the cube (``migration/precreate.py``).
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   271
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   272
3283
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 3144
diff changeset
   273
Use of RQL expression for write permissions
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 3144
diff changeset
   274
```````````````````````````````````````````
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
   275
It is possible to define RQL expression to provide update permission
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   276
(`add`, `delete` and `update`) on relation and entity types.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   277
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   278
RQL expression for entity type permission :
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   279
3811
3726e921f537 small fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 3581
diff changeset
   280
* you have to use the class `ERQLExpression`
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   281
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   282
* the used expression corresponds to the WHERE statement of an RQL query
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   283
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   284
* in this expression, the variables X and U are pre-defined references
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   285
  respectively on the current entity (on which the action is verified) and
4442
7bc0e4ed4109 fix stupid sed
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4437
diff changeset
   286
  on the user who send the request
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   287
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
   288
* it is possible to use, in this expression, a special relation
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
   289
  "has_<ACTION>_permission" where the subject is the user and the
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   290
  object is a any variable, meaning that the user needs to have
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   291
  permission to execute the action <ACTION> on the entities related
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
   292
  to this variable
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   293
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
   294
For RQL expressions on a relation type, the principles are the same except
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   295
for the following :
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   296
3811
3726e921f537 small fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 3581
diff changeset
   297
* you have to use the class `RRQLExpression` in the case of a non-final relation
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   298
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   299
* in the expression, the variables S, O and U are pre-defined references
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   300
  to respectively the subject and the object of the current relation (on
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   301
  which the action is being verified) and the user who executed the query
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   302
3811
3726e921f537 small fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 3581
diff changeset
   303
* we can also define rights over attributes of an entity (non-final relation),
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
   304
  knowing that :
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   305
3811
3726e921f537 small fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 3581
diff changeset
   306
  - to define RQL expression, we have to use the class `ERQLExpression`
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   307
    in which X represents the entity the attribute belongs to
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   308
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   309
  - the permissions `add` and `delete` are equivalent. Only `add`/`read`
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   310
    are actually taken in consideration.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   311
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   312
:Note on the use of RQL expression for `add` permission:
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   313
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   314
  Potentially, the use of an RQL expression to add an entity or a relation
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   315
  can cause problems for the user interface, because if the expression uses
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
   316
  the entity or the relation to create, then we are not able to verify the
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   317
  permissions before we actually add the entity (please note that this is
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   318
  not a problem for the RQL server at all, because the permissions checks are
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
   319
  done after the creation). In such case, the permission check methods
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
   320
  (check_perm, has_perm) can indicate that the user is not allowed to create
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
   321
  this entity but can obtain the permission.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   322
  To compensate this problem, it is usually necessary, for such case,
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   323
  to use an action that reflects the schema permissions but which enables
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   324
  to check properly the permissions so that it would show up if necessary.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   325
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
   326
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   327
Use of RQL expression for reading rights
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   328
````````````````````````````````````````
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   329
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   330
The principles are the same but with the following restrictions :
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   331
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   332
* we can not use `RRQLExpression` on relation types for reading
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   333
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   334
* special relations "has_<ACTION>_permission" can not be used
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   335
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   336
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   337
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   338
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   339
Defining your schema using yams
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   340
-------------------------------
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   341
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   342
Entity type definition
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   343
~~~~~~~~~~~~~~~~~~~~~~
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   344
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   345
An entity type is defined by a Python class which inherits from `EntityType`.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   346
The class definition contains the description of attributes and relations
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   347
for the defined entity type.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   348
The class name corresponds to the entity type name. It is exepected to be
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   349
defined in the module ``mycube.schema``.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   350
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
   351
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
   352
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
   353
- ._cwuired` : boolean indicating if the attribute is._cwuired, eg subject cardinality is '1'
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
   354
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
   355
- `vocabulary` : specify static possible values of an attribute
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
   356
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
   357
- `maxsize` : integer providing the maximum size of a string (no limit by default)
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
   358
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
   359
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
   360
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
   361
.. sourcecode:: python
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   362
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   363
  class Person(EntityType):
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   364
    """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
   365
    application"""
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   366
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
   367
    last_name = String._cwuired=True, fulltextindexed=True)
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
   368
    first_name = String._cwuired=True, fulltextindexed=True)
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   369
    title = String(vocabulary=('Mr', 'Mrs', 'Miss'))
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   370
    date_of_birth = Date()
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   371
    works_for = SubjectRelation('Company', cardinality='?*')
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   372
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
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
   375
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
   376
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
   377
`Company` through the semantic `works_for`.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   378
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   379
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
   380
or the relation in *CubicWeb* application.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   381
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   382
An attribute is defined in the schema as follows::
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
   383
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   384
    attr_name = attr_type(properties*)
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   385
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   386
where `attr_type` is one of the type listed above and `properties` is
3283
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 3144
diff changeset
   387
a list of the attribute needs to statisfy (see :ref:`properties`
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
   388
for more details).
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   389
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   390
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   391
* relations can be defined by using `ObjectRelation` or `SubjectRelation`.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   392
  The first argument of `SubjectRelation` or `ObjectRelation` gives respectively
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
   393
  the object/subject entity type of the relation. This could be :
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   394
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   395
  * a string corresponding to an entity type
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   396
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   397
  * a tuple of string corresponding to multiple entity types
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   398
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   399
  * special string such as follows :
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   400
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   401
    - "**" : all types of entities
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
   402
    - "*" : all types of non-meta entities
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   403
    - "@" : all types of meta entities but not system entities (e.g. used for
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   404
      the basic schema description)
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   405
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   406
* 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
   407
  (e.g. used to describe/categorize other entities)
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   408
4430
0b6a069eb29e le patch added_tips a été importé
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4040
diff changeset
   409
*Note* : if you end up with an `if` in the definition of your entity, this probably
0b6a069eb29e le patch added_tips a été importé
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4040
diff changeset
   410
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
   411
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
   412
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   413
Inheritance
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   414
```````````
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   415
XXX feed me
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   416
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   417
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   418
Definition of relations
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   419
~~~~~~~~~~~~~~~~~~~~~~~
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   420
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   421
XXX add note about defining relation type / definition
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   422
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   423
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
   424
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
   425
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
   426
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
   427
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
   428
definition properties from the relation) for example ::
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   429
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   430
  class locked_by(RelationType):
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   431
    """relation on all entities indicating that they are locked"""
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   432
    inlined = True
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   433
    cardinality = '?*'
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   434
    subject = '*'
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   435
    object = 'CWUser'
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   436
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   437
In the case of simultaneous relations definitions, `subject` and `object`
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   438
can both be equal to the value of the first argument of `SubjectRelation`
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   439
and `ObjectRelation`.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   440
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
   441
When a relation is not inlined and not symmetrical, and it does not._cwuire
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   442
specific permissions, its definition (by using `SubjectRelation` and
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   443
`ObjectRelation`) is all we need.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   444
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   445
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   446
Definition of permissions
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   447
~~~~~~~~~~~~~~~~~~~~~~~~~~
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   448
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   449
In addition to that the entity type `CWPermission` from the standard library
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   450
allow to build very complex and dynamic security architecture. The schema 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
   451
this entity type is as follow:
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   452
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
   453
.. sourcecode:: python
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
   454
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
   455
    class CWPermission(EntityType):
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   456
	"""entity type that may be used to construct some advanced security configuration
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   457
	"""
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
   458
	name = String._cwuired=True, indexed=True, internationalizable=True, maxsize=100)
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
   459
._cwuire_group = SubjectRelation('CWGroup', cardinality='+*',
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   460
					description=_('groups to which the permission is granted'))
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
   461
._cwuire_state = SubjectRelation('State',
3144
a5deac822a13 Bugfix: message was not written in english
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2476
diff changeset
   462
                                        description=_("entity's state in which the permission is applicable"))
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   463
	# can be used on any entity
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
   464
._cwuire_permission = ObjectRelation('**', cardinality='*1', composite='subject',
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   465
					    description=_("link a permission to the entity. This "
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   466
							  "permission should be used in the security "
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   467
							  "definition of the entity's type to be useful."))
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   468
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   469
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
   470
Example of configuration:
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
   471
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
   472
.. sourcecode:: python
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   473
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   474
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   475
    ...
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   476
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   477
    class Version(EntityType):
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   478
	"""a version is defining the content of a particular project's release"""
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   479
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
   480
	__permissions__ = {'read':   ('managers', 'users', 'guests',),
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   481
		       'update': ('managers', 'logilab', 'owners',),
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   482
		       'delete': ('managers', ),
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   483
		       'add':    ('managers', 'logilab',
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   484
				  ERQLExpression('X version_of PROJ, U in_group G,'
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
   485
						 'PROJ._cwuire_permission P, P name "add_version",'
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
   486
						 'P._cwuire_group G'),)}
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   487
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   488
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   489
    class version_of(RelationType):
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   490
	"""link a version to its project. A version is necessarily linked to one and only one project.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   491
	"""
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
   492
	__permissions__ = {'read':   ('managers', 'users', 'guests',),
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   493
		       'delete': ('managers', ),
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   494
		       'add':    ('managers', 'logilab',
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
   495
				  RRQLExpression('O._cwuire_permission P, P name "add_version",'
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
   496
						 'U in_group G, P._cwuire_group G'),)
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   497
		       }
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   498
	inlined = True
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   499
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   500
This configuration indicates that an entity `CWPermission` named
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   501
"add_version" can be associated to a project and provides rights to create
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   502
new versions on this project to specific groups. It is important to notice that :
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   503
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   504
* in such case, we have to protect both the entity type "Version" and the relation
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   505
  associating a version to a project ("version_of")
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   506
3283
4f53eb3f1331 more doc
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 3144
diff changeset
   507
* because of the genericity of the entity type `CWPermission`, we have to execute
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   508
  a unification with the groups and/or the states if necessary in the expression
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
   509
  ("U in_group G, P._cwuire_group G" in the above example)