1 .. -*- coding: utf-8 -*- |
1 .. -*- coding: utf-8 -*- |
2 |
2 |
3 Définition d'un type d'entité |
3 Entity type definition |
4 ----------------------------- |
4 ---------------------- |
5 |
5 |
6 Un type d'entité est définit par une classe python héritant de `EntityType`. Le |
6 An entity type is defined by a Python class which inherits `EntityType`. The |
7 nom de la classe correspond au nom du type. Ensuite le corps de la classe |
7 class name correponds to the type name. Then the content of the class contains |
8 contient la description des attributs et des relations pour ce type d'entité, |
8 the description of attributes and relations for the defined entity type, |
9 par exemple :: |
9 by example :: |
10 |
10 |
11 class Personne(EntityType): |
11 class Personne(EntityType): |
12 """une personne avec les propriétés et relations nécessaires à mon |
12 """A person with the properties and the relations necessarry for my |
13 application""" |
13 application""" |
14 |
14 |
15 nom = String(required=True, fulltextindexed=True) |
15 last_name = String(required=True, fulltextindexed=True) |
16 prenom = String(required=True, fulltextindexed=True) |
16 first_name = String(required=True, fulltextindexed=True) |
17 civilite = String(vocabulary=('M', 'Mme', 'Mlle')) |
17 title = String(vocabulary=('M', 'Mme', 'Mlle')) |
18 date_naiss = Date() |
18 date_of_birth = Date() |
19 travaille_pour = SubjectRelation('Company', cardinality='?*') |
19 works_for = SubjectRelation('Company', cardinality='?*') |
20 |
20 |
21 * le nom de l'attribut python correspond au nom de l'attribut ou de la relation |
21 * the name of the Python attribute corresponds to the name of the attribute |
22 dans cubicweb. |
22 or the relation in `CubicWeb` application. |
23 |
23 |
24 * tout les types de bases sont disponibles nativement : `String`, `Int`, `Float`, |
24 * all built-in types are available : `String`, `Int`, `Float`, |
25 `Boolean`, `Date`, `Datetime`, `Time`, `Byte`. |
25 `Boolean`, `Date`, `Datetime`, `Time`, `Byte`. |
26 |
26 |
27 * Chaque type d'entité a au moins les méta-relations suivantes : |
27 * each entity type has at least the following meta-relations : |
28 |
28 |
29 - `eid` (`Int`) |
29 - `eid` (`Int`) |
30 |
30 |
31 - `creation_date` (`Datetime`) |
31 - `creation_date` (`Datetime`) |
32 |
32 |
33 - `modification_date` (`Datetime`) |
33 - `modification_date` (`Datetime`) |
34 |
34 |
35 - `created_by` (`EUser`) (quel utilisateur a créé l'entité) |
35 - `created_by` (`EUser`) (which user created the entity) |
36 |
36 |
37 - `owned_by` (`EUser`) (à qui appartient l'entité, par défaut le |
37 - `owned_by` (`EUser`) (who does the entity belongs to, by default the |
38 créateur mais pas forcément et il peut exister plusieurs propriétaires) |
38 creator but not necessarry and it could have multiple owners) |
39 |
39 |
40 - `is` (`EEType`) |
40 - `is` (`EEType`) |
41 |
41 |
42 |
42 |
43 * il est également possible de définir des relations dont le type d'entité est |
43 * it is also possible to define relations of type object by using `ObjectRelation` |
44 l'objet en utilisant `ObjectRelation` plutôt que `SubjectRelation` |
44 instead of `SubjectRelation` |
45 |
45 |
46 * le premier argument de `SubjectRelation` et `ObjectRelation` donne |
46 * the first argument of `SubjectRelation` and `ObjectRelation` gives respectively |
47 respectivement le type d'entité objet /sujet de la relation. Cela |
47 the object/subject entity type of the relation. This could be : |
48 peut être : |
48 |
49 |
49 * a string corresponding to an entity type |
50 * une chaine de caractères correspondant à un type d'entité |
50 |
51 |
51 * a tuple of string correponding to multiple entities types |
52 * un tuple de chaines de caractères correspondant à plusieurs types d'entité |
52 |
53 |
53 * special string such as follows : |
54 * les chaînes de caractères spéciales suivantes : |
54 |
55 |
55 - "**" : all types of entities |
56 - "**" : tout les types d'entité |
56 - "*" : all types of non-meta entities |
57 - "*" : tout les types d'entité non méta |
57 - "@" : all types of meta entities but not system entities (e.g. used for |
58 - "@" : tout les types d'entité méta mais non "système" (i.e. servant à la |
58 the basic schema description) |
59 description du schema en base) |
59 |
60 |
60 * it is possible to use the attribute `meta` to flag an entity type as a `meta` |
61 * il est possible d'utiliser l'attribut possible `meta` pour marquer un type |
61 (e.g. used to describe/categorize other entities) |
62 d'entité comme étant "méta" (i.e. servant à décrire / classifier d'autre |
62 |
63 entités) |
63 * optional properties for attributes and relations : |
64 |
64 |
65 * propriétés optionnelles des attributs et relations : |
65 - `description` : string describing an attribute or a relation. By default |
66 |
66 this string will be used in the editing form of the entity, which means |
67 - `description` : chaine de caractères décrivant un attribut ou une |
67 that it is supposed to help the end-user and should be flagged by the |
68 relation. Par défaut cette chaine sera utilisée dans le formulaire de saisie |
68 function `_` to be properly internationalized. |
69 de l'entité, elle est donc destinée à aider l'utilisateur final et doit être |
69 |
70 marquée par la fonction `_` pour être correctement internationalisée. |
70 - `constraints` : list of conditions/constraints that the relation needs to |
71 |
71 satisfy (c.f. `Contraints`_) |
72 - `constraints` : liste de contraintes devant être respecté par la relation |
72 |
73 (c.f. `Contraintes`_) |
73 - `cardinality` : two characters string which specify the cardinality of the |
74 |
74 relation. The first character defines the cardinality of the relation on |
75 - `cardinality` : chaine de 2 caractères spécifiant la cardinalité de la |
75 the subject, the second on the object of the relation. When a relation |
76 relation. Le premier caractère donne la cardinalité de la relation sur le |
76 has multiple possible subjects or objects, the cardinality applies to all |
77 sujet, le 2eme sur l'objet. Quand une relation possède plusieurs sujets ou |
77 and not on a one to one basis (so it must be consistent...). The possible |
78 objets possibles, la cardinalité s'applique sur l'ensemble et non un à un (et |
78 values are inspired from regular expressions syntax : |
79 doit donc à priori être cohérente...). Les valeurs possibles sont inspirées |
|
80 des expressions régulières : |
|
81 |
79 |
82 * `1`: 1..1 |
80 * `1`: 1..1 |
83 * `?`: 0..1 |
81 * `?`: 0..1 |
84 * `+`: 1..n |
82 * `+`: 1..n |
85 * `*`: 0..n |
83 * `*`: 0..n |
86 |
84 |
87 - `meta` : booléen indiquant que la relation est une méta relation (faux par |
85 - `meta` : boolean indicating that the relation is a meta-relation (false by |
88 défaut) |
86 default) |
89 |
87 |
90 * propriétés optionnelles des attributs : |
88 * optionnal properties for attributes : |
91 |
89 |
92 - `required` : booléen indiquant si l'attribut est obligatoire (faux par |
90 - `required` : boolean indicating if the attribute is required (false by default) |
93 défaut) |
91 |
94 |
92 - `unique` : boolean indicating if the value of the attribute has to be unique |
95 - `unique` : booléen indiquant si la valeur de l'attribut doit être unique |
93 or not within all entities of the same type (false by default) |
96 parmi toutes les entités de ce type (faux par défaut) |
94 |
97 |
95 - `indexed` : boolean indicating if an index needs to be created for this |
98 - `indexed` : booléen indiquant si un index doit être créé dans la base de |
96 attribute in the database (false by default). This is usefull only if |
99 données sur cette attribut (faux par défaut). C'est utile uniquement si vous |
97 you know that you will have to run numerous searches on the value of this |
100 savez que vous allez faire de nombreuses recherche sur la valeur de cet |
98 attribute. |
101 attribut. |
99 |
102 |
100 - `default` : default value of the attribute. In case of date types, the values |
103 - `default` : valeur par défaut de l'attribut. A noter que dans le cas des |
101 which could be used correpond to the RQL keywords `TODAY` and `NOW`. |
104 types date, les chaines de caractères correspondant aux mots-clés RQL |
102 |
105 `TODAY` et `NOW` sont utilisables. |
103 - `vocabulary` : specify static possible values of an attribute |
106 |
104 |
107 - `vocabulary` : spécifie statiquement les valeurs possibles d'un attribut |
105 * optionnal properties of type `String` : |
108 |
106 |
109 * propriétés optionnelles des attributs de type `String` : |
107 - `fulltextindexed` : boolean indicating if the attribute is part of |
110 |
108 the full text index (false by default) (*applicable on the type `Byte` |
111 - `fulltextindexed` : booléen indiquant si l'attribut participe à l'index plein |
109 as well*) |
112 texte (faux par défaut) (*valable également sur le type `Byte`*) |
110 |
113 |
111 - `internationalizable` : boolean indicating if the value of the attribute |
114 - `internationalizable` : booléen indiquant si la valeur de cet attribut est |
112 is internationalizable (false by default) |
115 internationalisable (faux par défaut) |
113 |
116 |
114 - `maxsize` : integer providing the maximum size of the string (no limit by default) |
117 - `maxsize` : entier donnant la taille maximum de la chaine (pas de limite par |
115 |
118 défaut) |
116 * optionnal properties for relations : |
119 |
117 |
120 * propriétés optionnelles des relations : |
118 - `composite` : string indicating that the subject (composite == 'subject') |
121 |
119 is composed of the objects of the relations. For the opposite case (when |
122 - `composite` : chaîne indiquant que le sujet (composite == 'subject') est |
120 the object is composed of the subjects of the relation), we just need |
123 composé de ou des objets de la relation. Pour le cas opposé (l'objet est |
121 to set 'object' as the value. The composition implies that when the relation |
124 composé de ou des sujets de la relation, il suffit de mettre 'object' comme |
122 is deleted (so when the composite is deleted), the composed are also deleted. |
125 valeur. La composition implique que quand la relation est supprimé (et donc |
123 |
126 aussi quand le composite est supprimé), le ou les composés le sont |
124 Contraints |
127 également. |
125 `````````` |
128 |
126 By default, the available constraints types are : |
129 Contraintes |
127 |
130 ``````````` |
128 * `SizeConstraint` : allows to specify a minimum and/or maximum size on |
131 Par défaut les types de contraintes suivant sont disponibles : |
129 string (generic case of `maxsize`) |
132 |
130 |
133 * `SizeConstraint` : permet de spécifier une taille minimale et/ou maximale sur |
131 * `BoundConstraint` : allows to specify a minimum and/or maximum value on |
134 les chaines de caractères (cas générique de `maxsize`) |
132 numeric types |
135 |
133 |
136 * `BoundConstraint` : permet de spécifier une valeur minimale et/ou maximale sur |
134 * `UniqueConstraint` : identical to "unique=True" |
137 les types numériques |
135 |
138 |
136 * `StaticVocabularyConstraint` : identical to "vocabulary=(...)" |
139 * `UniqueConstraint` : identique à "unique=True" |
137 |
140 |
138 * `RQLConstraint` : allows to specify a RQL query that needs to be satisfied |
141 * `StaticVocabularyConstraint` : identique à "vocabulary=(...)" |
139 by the subject and/or the object of the relation. In this query the variables |
142 |
140 `S` and `O` are reserved for the entities subject and object of the |
143 * `RQLConstraint` : permet de spécifier une requête RQL devant être satisfaite |
141 relation. |
144 par le sujet et/ou l'objet de la relation. Dans cette requête les variables `S` |
142 |
145 et `O` sont préféfinies respectivement comme l'entité sujet et objet de la |
143 * `RQLVocabularyConstraint` : similar to the previous type of constraint except |
146 relation |
144 that it does not express a "strong" constraint, which means it is only used to |
147 |
145 restrict the values listed in the drop-down menu of editing form, but it does |
148 * `RQLVocabularyConstraint` : similaire à la précédente, mais exprimant une |
146 not prevent another entity to be selected |
149 contrainte "faible", i.e. servant uniquement à limiter les valeurs apparaissant |
147 |
150 dans la liste déroulantes du formulaire d'édition, mais n'empêchant pas une |
148 |
151 autre entité d'être séléctionnée |
149 Relation type definition |
152 |
150 ------------------------ |
153 |
151 |
154 Définition d'un type de relation |
152 A relation is defined by a Python class heriting `RelationType`. The name |
155 -------------------------------- |
153 of the class corresponds to the name of the type. The class then contains |
156 |
154 a description of the properties of this type of relation, and could as well |
157 Un type de relation est définit par une classe python héritant de `RelationType`. Le |
155 contains a string for the subject and a string for the object. This allows to create |
158 nom de la classe correspond au nom du type. Ensuite le corps de la classe |
156 new definition of associated relations, (so that the class can have the |
159 contient la description des propriétés de ce type de relation, ainsi |
157 definition properties from the relation) by example :: |
160 qu'éventuellement une chaine pour le sujet et une autre pour l'objet permettant |
158 |
161 de créer des définitions de relations associées (auquel cas il est possibles de |
159 class locked_by(RelationType): |
162 donner sur la classe les propriétés de définition de relation explicitées |
160 """relation on all entities indicating that they are locked""" |
163 ci-dessus), par exemple :: |
|
164 |
|
165 class verrouille_par(RelationType): |
|
166 """relation sur toutes les entités applicatives indiquant que celles-ci sont vérouillées |
|
167 inlined = True |
161 inlined = True |
168 cardinality = '?*' |
162 cardinality = '?*' |
169 subject = '*' |
163 subject = '*' |
170 object = 'EUser' |
164 object = 'EUser' |
171 |
165 |
172 En plus des permissions, les propriétés propres aux types de relation (et donc |
166 In addition to the permissions, the properties of the relation types |
173 partagés par toutes les définitions de relation de ce type) sont : |
167 (shared also by all definition of relation of this type) are : |
174 |
168 |
175 * `inlined` : booléen contrôlant l'optimisation physique consistant à stocker la |
169 |
176 relation dans la table de l'entité sujet au lieu de créer une table spécifique |
170 * `inlined` : boolean handling the physical optimization for archiving |
177 à la relation. Cela se limite donc aux relations dont la cardinalité |
171 the relation in the subject entity table, instead of creating a specific |
178 sujet->relation->objet vaut 0..1 ('?') ou 1..1 ('1') |
172 table for the relation. This applies to the relation when the cardinality |
179 |
173 of subject->relation->object is 0..1 (`?`) or 1..1 (`1`) |
180 * `symetric` : booléen indiquant que la relation est symétrique. i.e. |
174 |
181 `X relation Y` implique `Y relation X` |
175 * `symetric` : boolean indication that the relation is symetrical, which |
182 |
176 means `X relation Y` implies `Y relation X` |
183 Dans le cas de définitions de relations simultanée, `sujet` et `object` peuvent |
177 |
184 tout deux valoir la même chose que décrite pour le 1er argument de |
178 In the case of simultaneous relations definitions, `subject` and `object` |
185 `SubjectRelation` et `ObjectRelation`. |
179 can both be equal to the value of the first argument of `SubjectRelation` |
186 |
180 and `ObjectRelation`. |
187 A partir du moment où une relation n'est ni mise en ligne, ni symétrique, et |
181 |
188 ne nécessite pas de permissions particulières, sa définition (en utilisant |
182 When a relation is not inlined and not symetrical, and it does not require |
189 `SubjectRelation` ou `ObjectRelation`) est suffisante. |
183 specific permissions, its definition (by using `SubjectRelation` and |
190 |
184 `ObjectRelation`) is all we need. |
191 |
185 |
192 Définition des permissions |
186 Permissions definition |
193 -------------------------- |
187 ---------------------- |
194 |
188 |
195 La définition des permissions se fait à l'aide de l'attribut `permissions` des |
189 Define permissions is set through to the attribute `permissions` of entities and |
196 types d'entité ou de relation. Celui-ci est un dictionnaire dont les clés sont |
190 relations types. It defines a dictionnary where the keys are the access types |
197 les types d'accès (action), et les valeurs les groupes ou expressions autorisées. |
191 (action), and the values are the authorized groups or expressions. |
198 |
192 |
199 Pour un type d'entité, les actions possibles sont `read`, `add`, `update` et |
193 For an entity type, the possible actions are `read`, `add`, `update` and |
200 `delete`. |
194 `delete`. |
201 |
195 |
202 Pour un type de relation, les actions possibles sont `read`, `add`, et `delete`. |
196 For a relation type, the possible actions are `read`, `add`, and `delete`. |
203 |
197 |
204 Pour chaque type d'accès, un tuple indique le nom des groupes autorisés et/ou |
198 For each access type, a tuple indicates the name of the authorized groups and/or |
205 une ou plusieurs expressions RQL devant être vérifiées pour obtenir |
199 one or multiple RQL expressions to satisfy to grant access. The access is |
206 l'accès. L'accès est donné à partir du moment où l'utilisateur fait parti d'un |
200 provided once the user is in the listed groups or one of the RQL condition is |
207 des groupes requis ou dès qu'une expression RQL est vérifiée. |
201 satisfied. |
208 |
202 |
209 Les groupes standards sont : |
203 The standard groups are : |
210 |
204 |
211 * `guests` |
205 * `guests` |
212 |
206 |
213 * `users` |
207 * `users` |
214 |
208 |
215 * `managers` |
209 * `managers` |
216 |
210 |
217 * `owners` : groupe virtuel correspondant au propriétaire d'une entité. Celui-ci |
211 * `owners` : virtual group corresponding to the entity's owner. |
218 ne peut être utilisé que pour les actions `update` et `delete` d'un type |
212 This can only be used for the actions `update` and `delete` of an entity |
219 d'entité. |
213 type. |
220 |
214 |
221 Il est également possible d'utiliser des groupes spécifiques devant être pour |
215 It is also possible to use specific groups if they are define in the precreate |
222 cela créés dans le precreate de l'application (`migration/precreate.py`). |
216 of the application (``migration/precreate.py``). |
223 |
217 |
224 Utilisation d'expression RQL sur les droits en écriture |
218 Use of RQL expression for writing rights |
225 ``````````````````````````````````````````````````````` |
219 ```````````````````````````````````````` |
226 Il est possible de définir des expressions RQL donnant des droits de |
220 It is possible to define RQL expression to provide update permission |
227 modification (`add`, `delete`, `update`) sur les types d'entité et de relation. |
221 (`add`, `delete` and `update`) on relation and entity types. |
228 |
222 |
229 Expression RQL pour les permissions sur un type d'entité : |
223 RQL expression for entity type permission : |
230 |
224 |
231 * il faut utiliser la classe `ERQLExpression` |
225 * you have to use the class `ERQLExpression` |
232 |
226 |
233 * l'expression utilisée correspond à la clause WHERE d'une requête RQL |
227 * the used expression corresponds to the WHERE statement of an RQL query |
234 |
228 |
235 * dans cette expression, les variables X et U sont des références prédéfinies |
229 * in this expression, the variables X and U are pre-defined references |
236 respectivement sur l'entité courante (sur laquelle l'action est vérifiée) et |
230 respectively on the current entity (on which the action is verified) and |
237 sur l'utilisateur ayant effectué la requête |
231 on the user who send the request |
238 |
232 |
239 * il est possible d'utiliser dans cette expression les relations spéciales |
233 * it is possible to use, in this expression, a special relation |
240 "has_<ACTION>_permission" dont le sujet est l'utilisateur et l'objet une |
234 "has_<ACTION>_permission" where the subject is the user and the |
241 variable quelquonque, signifiant ainsi que l'utilisateur doit avoir la |
235 object is a any variable, meaning that the user needs to have |
242 permission d'effectuer l'action <ACTION> sur la ou les entités liées cette |
236 permission to execute the action <ACTION> on the entities related |
243 variable |
237 to this variable |
244 |
238 |
245 Pour les expressions RQL sur un type de relation, les principes sont les mêmes |
239 For RQL expressions on a relation type, the principles are the same except |
246 avec les différences suivantes : |
240 for the following : |
247 |
241 |
248 * il faut utiliser la classe `RRQLExpression` dans le cas d'une relation non |
242 * you have to use the class `RQLExpression` in the case of a non-final relation |
249 finale |
243 |
250 |
244 * in the expression, the variables S, O and U are pre-defined references |
251 * dans cette expression, les variables S, O et U sont des références |
245 to respectively the subject and the object of the current relation (on |
252 prédéfinies respectivement sur le sujet et l'objet de la relation |
246 which the action is being verified) and the user who executed the query |
253 courante (sur laquelle l'action est vérifiée) et sur l'utilisateur |
247 |
254 ayant effectué la requête |
248 * we can also defined rights on attributes of an entity (non-final relation), |
255 |
249 knowing that : |
256 * On peut aussi définir des droits sur les attributs d'une entité (relation non |
250 |
257 finale), sachant les points suivants : |
251 - to defines RQL expression, we have to use the class `ERQLExpression` |
258 |
252 in which X represents the entity the attribute belongs to |
259 - pour définir des expressions rql, il faut utiliser la classe `ERQLExpression` |
253 |
260 dans laquelle X représentera l'entité auquel appartient l'attribut |
254 - the permissions `add` and `delete` are equivalent. Only `add`/`read` |
261 |
255 are actually taken in consideration. |
262 - les permissions 'add' et 'delete' sont équivalentes. En pratique seul |
256 |
263 'add'/'read' son pris en considération |
257 In addition to that the entity type `EPermission` from the standard library |
264 |
258 allow to build very complex and dynamic security architecture. The schema of |
265 |
259 this entity type is as follow : :: |
266 En plus de cela, le type d'entité `EPermission` de la librairie standard permet |
|
267 de construire des modèles de sécurités très complexes et dynamiques. Le schéma |
|
268 de ce type d'entité est le suivant : :: |
|
269 |
|
270 |
260 |
271 class EPermission(MetaEntityType): |
261 class EPermission(MetaEntityType): |
272 """entity type that may be used to construct some advanced security configuration |
262 """entity type that may be used to construct some advanced security configuration |
273 """ |
263 """ |
274 name = String(required=True, indexed=True, internationalizable=True, maxsize=100) |
264 name = String(required=True, indexed=True, internationalizable=True, maxsize=100) |