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

Définition d'un type d'entité
-----------------------------

Un type d'entité est définit par une classe python héritant de `EntityType`. Le
nom de la classe correspond au nom du type. Ensuite le corps de la classe
contient la description des attributs et des relations pour ce type d'entité,
par exemple ::

  class Personne(EntityType):
    """une personne avec les propriétés et relations nécessaires à mon
    application"""

    nom = String(required=True, fulltextindexed=True)
    prenom = String(required=True, fulltextindexed=True)
    civilite = String(vocabulary=('M', 'Mme', 'Mlle'))
    date_naiss = Date()
    travaille_pour = SubjectRelation('Company', cardinality='?*')

* le nom de l'attribut python correspond au nom de l'attribut ou de la relation
  dans cubicweb.

* tout les types de bases sont disponibles nativement : `String`, `Int`, `Float`,
  `Boolean`, `Date`, `Datetime`, `Time`, `Byte`.

* Chaque type d'entité a au moins les méta-relations suivantes :

  - `eid` (`Int`)
  
  - `creation_date` (`Datetime`)
  
  - `modification_date` (`Datetime`)
  
  - `created_by` (`CWUser`) (quel utilisateur a créé l'entité)
  
  - `owned_by` (`CWUser`) (à qui appartient l'entité, par défaut le
     créateur mais pas forcément et il peut exister plusieurs propriétaires)
     
  - `is` (`CWEType`)

  
* il est également possible de définir des relations dont le type d'entité est
  l'objet en utilisant `ObjectRelation` plutôt que `SubjectRelation`

* le premier argument de `SubjectRelation` et `ObjectRelation` donne
  respectivement le type d'entité objet /sujet de la relation. Cela
  peut être : 

  * une chaine de caractères correspondant à un type d'entité

  * un tuple de chaines de caractères correspondant à plusieurs types d'entité

  * les chaînes de caractères spéciales suivantes :

    - "**" : tout les types d'entité
    - "*" : tout les types d'entité non méta
    - "@" : tout les types d'entité méta mais non "système" (i.e. servant à la
      description du schema en base)

* il est possible d'utiliser l'attribut possible `meta` pour marquer un type
  d'entité comme étant "méta" (i.e. servant à décrire / classifier d'autre
  entités) 

* propriétés optionnelles des attributs et relations : 

  - `description` : chaine de caractères décrivant un attribut ou une
    relation. Par défaut cette chaine sera utilisée dans le formulaire de saisie
    de l'entité, elle est donc destinée à aider l'utilisateur final et doit être
    marquée par la fonction `_` pour être correctement internationalisée.

  - `constraints` : liste de contraintes devant être respecté par la relation
    (c.f. `Contraintes`_)

  - `cardinality` : chaine de 2 caractères spécifiant la cardinalité de la
    relation. Le premier caractère donne la cardinalité de la relation sur le
    sujet, le 2eme sur l'objet. Quand une relation possède plusieurs sujets ou
    objets possibles, la cardinalité s'applique sur l'ensemble et non un à un (et
    doit donc à priori être cohérente...). Les valeurs possibles sont inspirées
    des expressions régulières :

    * `1`: 1..1
    * `?`: 0..1
    * `+`: 1..n
    * `*`: 0..n

  - `meta` : booléen indiquant que la relation est une méta relation (faux par
    défaut)

* propriétés optionnelles des attributs : 

  - `required` : booléen indiquant si l'attribut est obligatoire (faux par
    défaut)

  - `unique` : booléen indiquant si la valeur de l'attribut doit être unique
    parmi toutes les entités de ce type (faux par défaut)

  - `indexed` : booléen indiquant si un index doit être créé dans la base de
    données sur cette attribut (faux par défaut). C'est utile uniquement si vous
    savez que vous allez faire de nombreuses recherche sur la valeur de cet
    attribut. 

  - `default` : valeur par défaut de l'attribut. A noter que dans le cas des
    types date, les chaines de caractères correspondant aux mots-clés RQL
    `TODAY` et `NOW` sont utilisables.

  - `vocabulary` : spécifie statiquement les valeurs possibles d'un attribut

* propriétés optionnelles des attributs de type `String` : 

  - `fulltextindexed` : booléen indiquant si l'attribut participe à l'index plein
    texte (faux par défaut) (*valable également sur le type `Byte`*)

  - `internationalizable` : booléen indiquant si la valeur de cet attribut est
    internationalisable (faux par défaut) 

  - `maxsize` : entier donnant la taille maximum de la chaine (pas de limite par
    défaut)  

* propriétés optionnelles des relations : 

  - `composite` : chaîne indiquant que le sujet (composite == 'subject') est
    composé de ou des objets de la relation. Pour le cas opposé (l'objet est
    composé de ou des sujets de la relation, il suffit de mettre 'object' comme
    valeur. La composition implique que quand la relation est supprimé (et donc
    aussi quand le composite est supprimé), le ou les composés le sont
    également. 

Contraintes
```````````
Par défaut les types de contraintes suivant sont disponibles :

* `SizeConstraint` : permet de spécifier une taille minimale et/ou maximale sur
  les chaines de caractères (cas générique de `maxsize`)

* `BoundConstraint` : permet de spécifier une valeur minimale et/ou maximale sur
  les types numériques

* `UniqueConstraint` : identique à "unique=True"

* `StaticVocabularyConstraint` : identique à "vocabulary=(...)"

* `RQLConstraint` : permet de spécifier une requête RQL devant être satisfaite
  par le sujet et/ou l'objet de la relation. Dans cette requête les variables `S`
  et `O` sont préféfinies respectivement comme l'entité sujet et objet de la
  relation

* `RQLVocabularyConstraint` : similaire à la précédente, mais exprimant une
  contrainte "faible", i.e. servant uniquement à limiter les valeurs apparaissant
  dans la liste déroulantes du formulaire d'édition, mais n'empêchant pas une
  autre entité d'être séléctionnée


Définition d'un type de relation
--------------------------------

Un type de relation est définit par une classe python héritant de `RelationType`. Le
nom de la classe correspond au nom du type. Ensuite le corps de la classe
contient la description des propriétés de ce type de relation, ainsi
qu'éventuellement une chaine pour le sujet et une autre pour l'objet permettant
de créer des définitions de relations associées (auquel cas il est possibles de
donner sur la classe les propriétés de définition de relation explicitées
ci-dessus), par exemple ::

  class verrouille_par(RelationType):
    """relation sur toutes les entités applicatives indiquant que celles-ci sont vérouillées
    inlined = True
    cardinality = '?*'
    subject = '*'
    object = 'CWUser'

En plus des permissions, les propriétés propres aux types de relation (et donc
partagés par toutes les définitions de relation de ce type) sont :

* `inlined` : booléen contrôlant l'optimisation physique consistant à stocker la
  relation dans la table de l'entité sujet au lieu de créer une table spécifique
  à la relation. Cela se limite donc aux relations dont la cardinalité
  sujet->relation->objet vaut 0..1 ('?') ou 1..1 ('1')

* `symmetric` : booléen indiquant que la relation est symétrique. i.e.
  `X relation Y` implique `Y relation X`

Dans le cas de définitions de relations simultanée, `sujet` et `object` peuvent
tout deux valoir la même chose que décrite pour le 1er argument de
`SubjectRelation` et `ObjectRelation`.

A partir du moment où une relation n'est ni mise en ligne, ni symétrique, et
ne nécessite pas de permissions particulières, sa définition (en utilisant
`SubjectRelation` ou `ObjectRelation`) est suffisante.


Définition des permissions
--------------------------

La définition des permissions se fait à l'aide de l'attribut `permissions` des
types d'entité ou de relation. Celui-ci est un dictionnaire dont les clés sont
les types d'accès (action), et les valeurs les groupes ou expressions autorisées. 

Pour un type d'entité, les actions possibles sont `read`, `add`, `update` et
`delete`.

Pour un type de relation, les actions possibles sont `read`, `add`, et `delete`.

Pour chaque type d'accès, un tuple indique le nom des groupes autorisés et/ou
une ou plusieurs expressions RQL devant être vérifiées pour obtenir
l'accès. L'accès est donné à partir du moment où l'utilisateur fait parti d'un
des groupes requis ou dès qu'une expression RQL est vérifiée.

Les groupes standards sont :

* `guests`

* `users`

* `managers`

* `owners` : groupe virtuel correspondant au propriétaire d'une entité. Celui-ci
  ne peut être utilisé que pour les actions `update` et `delete` d'un type
  d'entité. 

Il est également possible d'utiliser des groupes spécifiques devant être pour
cela créés dans le precreate de l'application (`migration/precreate.py`).

Utilisation d'expression RQL sur les droits en écriture
```````````````````````````````````````````````````````
Il est possible de définir des expressions RQL donnant des droits de
modification (`add`, `delete`, `update`) sur les types d'entité et de relation.

Expression RQL pour les permissions sur un type d'entité :

* il faut utiliser la classe `ERQLExpression`

* l'expression utilisée correspond à la clause WHERE d'une requête RQL

* dans cette expression, les variables X et U sont des références prédéfinies
  respectivement sur l'entité courante (sur laquelle l'action est vérifiée) et
  sur l'utilisateur ayant effectué la requête

* il est possible d'utiliser dans cette expression les relations spéciales
  "has_<ACTION>_permission" dont le sujet est l'utilisateur et l'objet une
  variable quelquonque, signifiant ainsi que l'utilisateur doit avoir la
  permission d'effectuer l'action <ACTION> sur la ou les entités liées cette
  variable

Pour les expressions RQL sur un type de relation, les principes sont les mêmes
avec les différences suivantes :

* il faut utiliser la classe `RRQLExpression` dans le cas d'une relation non
  finale

* dans cette expression, les variables S, O et U sont des références
  prédéfinies respectivement sur le sujet et l'objet de la relation
  courante (sur laquelle l'action est vérifiée) et sur l'utilisateur
  ayant effectué la requête

* On peut aussi définir des droits sur les attributs d'une entité (relation non
  finale), sachant les points suivants :

  - pour définir des expressions rql, il faut utiliser la classe `ERQLExpression`
    dans laquelle X représentera l'entité auquel appartient l'attribut

  - les permissions 'add' et 'delete' sont équivalentes. En pratique seul
    'add'/'read' son pris en considération


En plus de cela, le type d'entité `CWPermission` de la librairie standard permet
de construire des modèles de sécurités très complexes et dynamiques. Le schéma
de ce type d'entité est le suivant : ::


    class CWPermission(MetaEntityType):
	"""entity type that may be used to construct some advanced security configuration
	"""
	name = String(required=True, indexed=True, internationalizable=True, maxsize=100)
	require_group = SubjectRelation('CWGroup', cardinality='+*',
					description=_('groups to which the permission is granted'))
	require_state = SubjectRelation('State',
				    description=_("entity'state in which the permission is applyable"))
	# can be used on any entity
	require_permission = ObjectRelation('**', cardinality='*1', composite='subject',
					    description=_("link a permission to the entity. This "
							  "permission should be used in the security "
							  "definition of the entity's type to be useful."))


Exemple de configuration extrait de *jpl* ::

    ...

    class Version(EntityType):
	"""a version is defining the content of a particular project's release"""

	permissions = {'read':   ('managers', 'users', 'guests',),
		       'update': ('managers', 'logilab', 'owners',),
		       'delete': ('managers', ),
		       'add':    ('managers', 'logilab',
				  ERQLExpression('X version_of PROJ, U in_group G,'
						 'PROJ require_permission P, P name "add_version",'
						 'P require_group G'),)}

    ...

    class version_of(RelationType):
	"""link a version to its project. A version is necessarily linked to one and only one project.
	"""
	permissions = {'read':   ('managers', 'users', 'guests',),
		       'delete': ('managers', ),
		       'add':    ('managers', 'logilab',
				  RRQLExpression('O require_permission P, P name "add_version",'
						 'U in_group G, P require_group G'),)
		       }
	inlined = True

Cette configuration suppose indique qu'une entité `CWPermission` de nom
"add_version" peut-être associée à un projet et donner le droit de créer des
versions sur ce projet à des groupes spécifiques. Il est important de noter les
points suivants :

* dans ce cas il faut protéger à la fois le type d'entité "Version" et la
  relation liant une version à un projet ("version_of")

* du fait de la généricité du type d'entité `CWPermission`, il faut effectuer
  l'unification avec les groupes et / ou les états le cas échéant dans
  l'expression ("U in_group G, P require_group G" dans l'exemple ci-dessus)


Utilisation d'expression RQL sur les droits en lecture
``````````````````````````````````````````````````````
Les principes sont les mêmes mais avec les restrictions suivantes :

* on ne peut de `RRQLExpression` sur les types de relation en lecture

* les relations spéciales "has_<ACTION>_permission" ne sont pas utilisables


Note sur l'utilisation d'expression RQL sur la permission 'add'
```````````````````````````````````````````````````````````````
L'utilisation d'expression RQL sur l'ajout d'entité ou de relation pose
potentiellement un problème pour l'interface utilisateur car si l'expression
utilise l'entité ou la relation à créer, on est pas capable de vérifier les
droits avant d'avoir effectué l'ajout (noter que cela n'est pas un problème coté
serveur rql car la vérification des droits est effectuée après l'ajout
effectif). Dans ce cas les méthodes de vérification des droits (check_perm,
has_perm) peuvent inidquer qu'un utilisateur n'a pas le droit d'ajout alors
qu'il pourrait effectivement l'obtenir. Pour palier à ce soucis il est en général
nécessaire dans tel cas d'utiliser une action reflétant les droits du schéma
mais permettant de faire la vérification correctement afin qu'elle apparaisse
bien le cas échéant.

Mise à jour du schema
`````````````````````

Il faut ensuite lancer son cubicweb en mode shell ::

   cubicweb-ctl shell moninstance

Et taper ::

   add_entity_type('Personne')

Et on relance l'application!