doc/tutorials/advanced/part02_security.rst
author Nicolas Chauvat <nicolas.chauvat@logilab.fr>
Sun, 02 Feb 2020 22:15:38 +0100
changeset 12881 38fcf5707295
parent 12879 7347715bf0ee
child 12900 2cc3f481ecd0
permissions -rw-r--r--
[doc] replace python with python3 in shell commands
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
     1
.. _TutosPhotoWebSiteSecurity:
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
     2
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
     3
Security, testing and migration
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
     4
-------------------------------
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
     5
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
     6
This part will cover various topics:
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
     7
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
     8
* configuring security
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
     9
* migrating existing instance
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    10
* writing some unit tests
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    11
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    12
Here is the ``read`` security model I want:
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    13
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    14
* folders, files, images and comments should have one of the following visibility:
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    15
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    16
  - ``public``, everyone can see it
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    17
  - ``authenticated``, only authenticated users can see it
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    18
  - ``restricted``, only a subset of authenticated users can see it
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    19
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    20
* managers (e.g. me) can see everything
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    21
* only authenticated users can see people
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    22
* everyone can see classifier entities, such as tag and zone
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    23
12397
c5eb647b7046 [doc] style, switch to bullet points list to make things easier to read
Laurent Peuch <cortex@worlddomination.be>
parents: 12396
diff changeset
    24
Also:
c5eb647b7046 [doc] style, switch to bullet points list to make things easier to read
Laurent Peuch <cortex@worlddomination.be>
parents: 12396
diff changeset
    25
c5eb647b7046 [doc] style, switch to bullet points list to make things easier to read
Laurent Peuch <cortex@worlddomination.be>
parents: 12396
diff changeset
    26
* unless explicitly specified, the visibility of an image should be the same as
c5eb647b7046 [doc] style, switch to bullet points list to make things easier to read
Laurent Peuch <cortex@worlddomination.be>
parents: 12396
diff changeset
    27
its parent folder
c5eb647b7046 [doc] style, switch to bullet points list to make things easier to read
Laurent Peuch <cortex@worlddomination.be>
parents: 12396
diff changeset
    28
* the visibility of a comment should be the same as the commented entity
c5eb647b7046 [doc] style, switch to bullet points list to make things easier to read
Laurent Peuch <cortex@worlddomination.be>
parents: 12396
diff changeset
    29
* If there is no parent entity, the default visibility is ``authenticated``.
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    30
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    31
Regarding write security, that's much easier:
12381
a383091bdea8 [doc] rst syntax bug, blank line needed before item list
Laurent Peuch <cortex@worlddomination.be>
parents: 12209
diff changeset
    32
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    33
* anonymous can't write anything
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    34
* authenticated users can only add comment
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    35
* managers will add the remaining stuff
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    36
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    37
Now, let's implement that!
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    38
12398
ef798288884a [doc] bold to make reading more obvious
Laurent Peuch <cortex@worlddomination.be>
parents: 12397
diff changeset
    39
Proper security in CubicWeb is done **at the schema level**, so you don't have to
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    40
bother with it in views: users will only see what they can see automatically.
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    41
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    42
.. _adv_tuto_security:
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    43
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    44
Step 1: configuring security into the schema
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    45
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    46
12397
c5eb647b7046 [doc] style, switch to bullet points list to make things easier to read
Laurent Peuch <cortex@worlddomination.be>
parents: 12396
diff changeset
    47
In the schema, you can grant access according to:
c5eb647b7046 [doc] style, switch to bullet points list to make things easier to read
Laurent Peuch <cortex@worlddomination.be>
parents: 12396
diff changeset
    48
c5eb647b7046 [doc] style, switch to bullet points list to make things easier to read
Laurent Peuch <cortex@worlddomination.be>
parents: 12396
diff changeset
    49
* groups
c5eb647b7046 [doc] style, switch to bullet points list to make things easier to read
Laurent Peuch <cortex@worlddomination.be>
parents: 12396
diff changeset
    50
* to some RQL expressions: users get access if the expression returns some results
c5eb647b7046 [doc] style, switch to bullet points list to make things easier to read
Laurent Peuch <cortex@worlddomination.be>
parents: 12396
diff changeset
    51
c5eb647b7046 [doc] style, switch to bullet points list to make things easier to read
Laurent Peuch <cortex@worlddomination.be>
parents: 12396
diff changeset
    52
To implement the read security defined earlier, groups are not enough, we'll
c5eb647b7046 [doc] style, switch to bullet points list to make things easier to read
Laurent Peuch <cortex@worlddomination.be>
parents: 12396
diff changeset
    53
need some RQL expression. Here is the idea:
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    54
12399
c0ad7aa36e4a [doc] misc, put every reference to something in the code between backquotes
Laurent Peuch <cortex@worlddomination.be>
parents: 12398
diff changeset
    55
* add a `visibility` attribute on `Folder`, `File` and `Comment`, which may be one of
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    56
  the value explained above
12399
c0ad7aa36e4a [doc] misc, put every reference to something in the code between backquotes
Laurent Peuch <cortex@worlddomination.be>
parents: 12398
diff changeset
    57
* add a `may_be_read_by` relation from `Folder`, `File` and `Comment` to `users`,
12400
a9f15d3d65f9 [doc] plural
Laurent Peuch <cortex@worlddomination.be>
parents: 12399
diff changeset
    58
  which will define who can see the entity
a9f15d3d65f9 [doc] plural
Laurent Peuch <cortex@worlddomination.be>
parents: 12399
diff changeset
    59
* security propagation will be done in hooks
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    60
12401
66d98cfdd914 [doc] explain the difference between a relation and an attribute
Laurent Peuch <cortex@worlddomination.be>
parents: 12400
diff changeset
    61
.. Note::
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    62
12401
66d98cfdd914 [doc] explain the difference between a relation and an attribute
Laurent Peuch <cortex@worlddomination.be>
parents: 12400
diff changeset
    63
   What makes `visibility` an attribute and not a relation is that its object
66d98cfdd914 [doc] explain the difference between a relation and an attribute
Laurent Peuch <cortex@worlddomination.be>
parents: 12400
diff changeset
    64
   is a primitive type, here `String`.
66d98cfdd914 [doc] explain the difference between a relation and an attribute
Laurent Peuch <cortex@worlddomination.be>
parents: 12400
diff changeset
    65
66d98cfdd914 [doc] explain the difference between a relation and an attribute
Laurent Peuch <cortex@worlddomination.be>
parents: 12400
diff changeset
    66
   Other builtin primitives are String, Int, BigInt, Float, Decimal, Boolean,
66d98cfdd914 [doc] explain the difference between a relation and an attribute
Laurent Peuch <cortex@worlddomination.be>
parents: 12400
diff changeset
    67
   Date, Datetime, Time, Interval, Byte and Password and for more information
66d98cfdd914 [doc] explain the difference between a relation and an attribute
Laurent Peuch <cortex@worlddomination.be>
parents: 12400
diff changeset
    68
   read :ref:`EntityType`
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    69
12394
e847b5d1ffff [doc] always put file name for code example and uses :file:`path` syntax everywhere
Laurent Peuch <cortex@worlddomination.be>
parents: 12385
diff changeset
    70
So the first thing to do is to modify my cube's :file:`schema.py` to define those
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    71
relations:
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    72
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    73
.. sourcecode:: python
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    74
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    75
    from yams.constraints import StaticVocabularyConstraint
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    76
12403
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
    77
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    78
    class visibility(RelationDefinition):
12403
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
    79
        subject = ('Folder', 'File', 'Comment')
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
    80
        object = 'String'
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
    81
        constraints = [StaticVocabularyConstraint(('public', 'authenticated',
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
    82
                                                   'restricted', 'parent'))]
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
    83
        default = 'parent'
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
    84
        cardinality = '11'  # required
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
    85
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    86
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    87
    class may_be_read_by(RelationDefinition):
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    88
        __permissions__ = {
12403
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
    89
            'read': ('managers', 'users'),
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
    90
            'add': ('managers',),
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
    91
            'delete': ('managers',),
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
    92
        }
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    93
12403
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
    94
        subject = ('Folder', 'File', 'Comment',)
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
    95
        object = 'CWUser'
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    96
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    97
We can note the following points:
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
    98
12399
c0ad7aa36e4a [doc] misc, put every reference to something in the code between backquotes
Laurent Peuch <cortex@worlddomination.be>
parents: 12398
diff changeset
    99
* we've added a new `visibility` attribute to `Folder`, `File`, `Image` and `Comment`
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   100
  using a `RelationDefinition`
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   101
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   102
* `cardinality = '11'` means this attribute is required. This is usually hidden
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   103
  under the `required` argument given to the `String` constructor, but we can
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   104
  rely on this here (same thing for StaticVocabularyConstraint, which is usually
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   105
  hidden by the `vocabulary` argument)
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   106
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   107
* the `parent` possible value will be used for visibility propagation
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   108
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   109
* think to secure the `may_be_read_by` permissions, else any user can add/delete it
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   110
  by default, which somewhat breaks our security model...
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   111
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   112
Now, we should be able to define security rules in the schema, based on these new
12394
e847b5d1ffff [doc] always put file name for code example and uses :file:`path` syntax everywhere
Laurent Peuch <cortex@worlddomination.be>
parents: 12385
diff changeset
   113
attribute and relation. Here is the code to add to :file:`schema.py`:
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   114
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   115
.. sourcecode:: python
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   116
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   117
    from cubicweb.schema import ERQLExpression
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   118
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   119
    VISIBILITY_PERMISSIONS = {
12879
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 12556
diff changeset
   120
        'read':   ('managers',
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 12556
diff changeset
   121
                   ERQLExpression('X visibility "public"'),
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 12556
diff changeset
   122
                   ERQLExpression('X may_be_read_by U')),
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 12556
diff changeset
   123
        'add':    ('managers',),
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 12556
diff changeset
   124
        'update': ('managers', 'owners',),
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 12556
diff changeset
   125
        'delete': ('managers', 'owners'),
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 12556
diff changeset
   126
        }
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   127
    AUTH_ONLY_PERMISSIONS = {
12879
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 12556
diff changeset
   128
            'read':   ('managers', 'users'),
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 12556
diff changeset
   129
            'add':    ('managers',),
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 12556
diff changeset
   130
            'update': ('managers', 'owners',),
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 12556
diff changeset
   131
            'delete': ('managers', 'owners'),
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 12556
diff changeset
   132
            }
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   133
    CLASSIFIERS_PERMISSIONS = {
12879
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 12556
diff changeset
   134
            'read':   ('managers', 'users', 'guests'),
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 12556
diff changeset
   135
            'add':    ('managers',),
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 12556
diff changeset
   136
            'update': ('managers', 'owners',),
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 12556
diff changeset
   137
            'delete': ('managers', 'owners'),
7347715bf0ee [doc] replace tabs with spaces (and make linter happy)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 12556
diff changeset
   138
            }
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   139
12556
d1c659d70368 [doc] replace legacy import to new style cube import in various places
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12403
diff changeset
   140
    from cubicweb_folder.schema import Folder
d1c659d70368 [doc] replace legacy import to new style cube import in various places
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12403
diff changeset
   141
    from cubicweb_file.schema import File
d1c659d70368 [doc] replace legacy import to new style cube import in various places
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12403
diff changeset
   142
    from cubicweb_comment.schema import Comment
d1c659d70368 [doc] replace legacy import to new style cube import in various places
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12403
diff changeset
   143
    from cubicweb_person.schema import Person
d1c659d70368 [doc] replace legacy import to new style cube import in various places
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12403
diff changeset
   144
    from cubicweb_zone.schema import Zone
d1c659d70368 [doc] replace legacy import to new style cube import in various places
Philippe Pepiot <philippe.pepiot@logilab.fr>
parents: 12403
diff changeset
   145
    from cubicweb_tag.schema import Tag
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   146
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   147
    Folder.__permissions__ = VISIBILITY_PERMISSIONS
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   148
    File.__permissions__ = VISIBILITY_PERMISSIONS
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   149
    Comment.__permissions__ = VISIBILITY_PERMISSIONS.copy()
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   150
    Comment.__permissions__['add'] = ('managers', 'users',)
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   151
    Person.__permissions__ = AUTH_ONLY_PERMISSIONS
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   152
    Zone.__permissions__ = CLASSIFIERS_PERMISSIONS
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   153
    Tag.__permissions__ = CLASSIFIERS_PERMISSIONS
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   154
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   155
What's important in there:
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   156
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   157
* `VISIBILITY_PERMISSIONS` provides read access to managers group, if
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   158
  `visibility` attribute's value is 'public', or if user (designed by the 'U'
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   159
  variable in the expression) is linked to the entity (the 'X' variable) through
9881
3c2202e7bd31 [doc/book] spelling fixes in security tutorial
Julien Cristau <julien.cristau@logilab.fr>
parents: 9878
diff changeset
   160
  the `may_be_read_by` permission
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   161
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   162
* we modify permissions of the entity types we use by importing them and
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   163
  modifying their `__permissions__` attribute
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   164
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   165
* notice the `.copy()`: we only want to modify 'add' permission for `Comment`,
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   166
  not for all entity types using `VISIBILITY_PERMISSIONS`!
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   167
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   168
* the remaining part of the security model is done using regular groups:
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   169
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   170
  - `users` is the group to which all authenticated users will belong
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   171
  - `guests` is the group of anonymous users
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   172
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   173
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   174
.. _adv_tuto_security_propagation:
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   175
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   176
Step 2: security propagation in hooks
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   177
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   178
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   179
To fullfill the requirements, we have to implement::
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   180
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   181
  Also, unless explicity specified, visibility of an image should be the same as
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   182
  its parent folder, as well as visibility of a comment should be the same as the
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   183
  commented entity.
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   184
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   185
This kind of `active` rule will be done using CubicWeb's hook
9881
3c2202e7bd31 [doc/book] spelling fixes in security tutorial
Julien Cristau <julien.cristau@logilab.fr>
parents: 9878
diff changeset
   186
system. Hooks are triggered on database events such as addition of a new
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   187
entity or relation.
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   188
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   189
The tricky part of the requirement is in *unless explicitly specified*, notably
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   190
because when the entity is added, we don't know yet its 'parent'
6923
327443ec7120 [doc] update photo web site tutorial: we're starting from cw 3.10/file 1.9+
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6876
diff changeset
   191
entity (e.g. Folder of an File, File commented by a Comment). To handle such things,
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   192
CubicWeb provides `Operation`, which allow to schedule things to do at commit time.
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   193
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   194
In our case we will:
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   195
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   196
* on entity creation, schedule an operation that will set default visibility
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   197
12399
c0ad7aa36e4a [doc] misc, put every reference to something in the code between backquotes
Laurent Peuch <cortex@worlddomination.be>
parents: 12398
diff changeset
   198
* when a `parent` relation is added, propagate parent's visibility unless the
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   199
  child already has a visibility set
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   200
12394
e847b5d1ffff [doc] always put file name for code example and uses :file:`path` syntax everywhere
Laurent Peuch <cortex@worlddomination.be>
parents: 12385
diff changeset
   201
Here is the code in cube's :file:`hooks.py`:
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   202
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   203
.. sourcecode:: python
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   204
8190
2a3c1b787688 [vreg] move base registry implementation to logilab.common. Closes #1916014
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 7286
diff changeset
   205
    from cubicweb.predicates import is_instance
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   206
    from cubicweb.server import hook
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   207
12403
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   208
7286
a0d3ea01f4bf [doc] fix doc and tutorials about hooks and operations
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 6923
diff changeset
   209
    class SetVisibilityOp(hook.DataOperationMixIn, hook.Operation):
a0d3ea01f4bf [doc] fix doc and tutorials about hooks and operations
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 6923
diff changeset
   210
12403
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   211
        def precommit_event(self):
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   212
            for eid in self.get_data():
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   213
                entity = self.cnx.entity_from_eid(eid)
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   214
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   215
                if entity.visibility == 'parent':
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   216
                    entity.cw_set(visibility=u'authenticated')
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   217
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   218
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   219
    class SetVisibilityHook(hook.Hook):
12403
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   220
        __regid__ = 'sytweb.setvisibility'
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   221
        __select__ = hook.Hook.__select__ & is_instance('Folder', 'File', 'Comment')
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   222
        events = ('after_add_entity',)
7286
a0d3ea01f4bf [doc] fix doc and tutorials about hooks and operations
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 6923
diff changeset
   223
12403
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   224
        def __call__(self):
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   225
            SetVisibilityOp.get_instance(self._cw).add_data(self.entity.eid)
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   226
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   227
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   228
    class SetParentVisibilityHook(hook.Hook):
12403
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   229
        __regid__ = 'sytweb.setparentvisibility'
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   230
        __select__ = hook.Hook.__select__ & hook.match_rtype('filed_under', 'comments')
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   231
        events = ('after_add_relation',)
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   232
12403
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   233
        def __call__(self):
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   234
            parent = self._cw.entity_from_eid(self.eidto)
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   235
            child = self._cw.entity_from_eid(self.eidfrom)
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   236
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   237
            if child.visibility == 'parent':
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   238
                child.cw_set(visibility=parent.visibility)
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   239
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   240
Notice:
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   241
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   242
* hooks are application objects, hence have selectors that should match entity or
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   243
  relation types to which the hook applies. To match a relation type, we use the
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   244
  hook specific `match_rtype` selector.
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   245
9881
3c2202e7bd31 [doc/book] spelling fixes in security tutorial
Julien Cristau <julien.cristau@logilab.fr>
parents: 9878
diff changeset
   246
* usage of `DataOperationMixIn`: instead of adding an operation for each added entity,
12399
c0ad7aa36e4a [doc] misc, put every reference to something in the code between backquotes
Laurent Peuch <cortex@worlddomination.be>
parents: 12398
diff changeset
   247
  `DataOperationMixIn` allows to create a single one and to store entity's eids to be
9881
3c2202e7bd31 [doc/book] spelling fixes in security tutorial
Julien Cristau <julien.cristau@logilab.fr>
parents: 9878
diff changeset
   248
  processed in the transaction data. This is a good pratice to avoid heavy
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   249
  operations manipulation cost when creating a lot of entities in the same
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   250
  transaction.
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   251
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   252
* the `precommit_event` method of the operation will be called at transaction's
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   253
  commit time.
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   254
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   255
* in a hook, `self._cw` is the repository session, not a web request as usually
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   256
  in views
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   257
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   258
* according to hook's event, you have access to different attributes on the hook
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   259
  instance. Here:
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   260
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   261
  - `self.entity` is the newly added entity on 'after_add_entity' events
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   262
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   263
  - `self.eidfrom` / `self.eidto` are the eid of the subject / object entity on
7286
a0d3ea01f4bf [doc] fix doc and tutorials about hooks and operations
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 6923
diff changeset
   264
    'after_add_relation' events (you may also get the relation type using
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   265
    `self.rtype`)
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   266
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   267
The `parent` visibility value is used to tell "propagate using parent security"
12399
c0ad7aa36e4a [doc] misc, put every reference to something in the code between backquotes
Laurent Peuch <cortex@worlddomination.be>
parents: 12398
diff changeset
   268
because we want that attribute to be required, so we can't use `None` value else
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   269
we'll get an error before we get any chance to propagate...
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   270
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   271
Now, we also want to propagate the `may_be_read_by` relation. Fortunately,
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   272
CubicWeb provides some base hook classes for such things, so we only have to add
12394
e847b5d1ffff [doc] always put file name for code example and uses :file:`path` syntax everywhere
Laurent Peuch <cortex@worlddomination.be>
parents: 12385
diff changeset
   273
the following code to :file:`hooks.py`:
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   274
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   275
.. sourcecode:: python
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   276
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   277
    # relations where the "parent" entity is the subject
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   278
    S_RELS = set()
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   279
    # relations where the "parent" entity is the object
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   280
    O_RELS = set(('filed_under', 'comments',))
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   281
12403
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   282
9391
5537c3b64841 [book] replace PropagateSubjectRelation*Hook references
Samuel Trégouët <samuel.tregouet@logilab.fr>
parents: 8483
diff changeset
   283
    class AddEntitySecurityPropagationHook(hook.PropagateRelationHook):
12403
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   284
        """propagate permissions when new entity are added"""
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   285
        __regid__ = 'sytweb.addentity_security_propagation'
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   286
        __select__ = (hook.PropagateRelationHook.__select__
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   287
                      & hook.match_rtype_sets(S_RELS, O_RELS))
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   288
        main_rtype = 'may_be_read_by'
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   289
        subject_relations = S_RELS
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   290
        object_relations = O_RELS
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   291
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   292
9391
5537c3b64841 [book] replace PropagateSubjectRelation*Hook references
Samuel Trégouët <samuel.tregouet@logilab.fr>
parents: 8483
diff changeset
   293
    class AddPermissionSecurityPropagationHook(hook.PropagateRelationAddHook):
12403
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   294
        """propagate permissions when new entity are added"""
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   295
        __regid__ = 'sytweb.addperm_security_propagation'
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   296
        __select__ = (hook.PropagateRelationAddHook.__select__
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   297
                      & hook.match_rtype('may_be_read_by',))
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   298
        subject_relations = S_RELS
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   299
        object_relations = O_RELS
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   300
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   301
9391
5537c3b64841 [book] replace PropagateSubjectRelation*Hook references
Samuel Trégouët <samuel.tregouet@logilab.fr>
parents: 8483
diff changeset
   302
    class DelPermissionSecurityPropagationHook(hook.PropagateRelationDelHook):
12403
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   303
        __regid__ = 'sytweb.delperm_security_propagation'
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   304
        __select__ = (hook.PropagateRelationDelHook.__select__
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   305
                      & hook.match_rtype('may_be_read_by',))
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   306
        subject_relations = S_RELS
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   307
        object_relations = O_RELS
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   308
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   309
* the `AddEntitySecurityPropagationHook` will propagate the relation
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   310
  when `filed_under` or `comments` relations are added
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   311
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   312
  - the `S_RELS` and `O_RELS` set as well as the `match_rtype_sets` selector are
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   313
    used here so that if my cube is used by another one, it'll be able to
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   314
    configure security propagation by simply adding relation to one of the two
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   315
    sets.
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   316
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   317
* the two others will propagate permissions changes on parent entities to
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   318
  children entities
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   319
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   320
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   321
.. _adv_tuto_tesing_security:
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   322
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   323
Step 3: testing our security
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   324
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   325
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   326
Security is tricky. Writing some tests for it is a very good idea. You should
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   327
even write them first, as Test Driven Development recommends!
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   328
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   329
Here is a small test case that will check the basis of our security
12382
c73da3aa84cc [doc] default generated filename as changed
Laurent Peuch <cortex@worlddomination.be>
parents: 12381
diff changeset
   330
model, in :file:`test/test_sytweb.py`:
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   331
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   332
.. sourcecode:: python
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   333
12383
2dee7a944b3a [doc] default tests template has changed
Laurent Peuch <cortex@worlddomination.be>
parents: 12382
diff changeset
   334
    from cubicweb.devtools import testlib
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   335
    from cubicweb import Binary
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   336
12403
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   337
12383
2dee7a944b3a [doc] default tests template has changed
Laurent Peuch <cortex@worlddomination.be>
parents: 12382
diff changeset
   338
    class SecurityTC(testlib.CubicWebTC):
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   339
10383
53d7cf6f0b84 [doc] fix errors in test_visibility_propagation example
Rabah Meradi <rabah.meradi@logilab.fr>
parents: 10376
diff changeset
   340
        def test_visibility_propagation(self):
9878
f3936f64bd98 [doc/book] update examples, using the new connection api
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 9391
diff changeset
   341
            with self.admin_access.repo_cnx() as cnx:
f3936f64bd98 [doc/book] update examples, using the new connection api
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 9391
diff changeset
   342
                # create a user for later security checks
f3936f64bd98 [doc/book] update examples, using the new connection api
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 9391
diff changeset
   343
                toto = self.create_user(cnx, 'toto')
12384
b2e0b6a8f76c [doc] blanks spaces to allow example to breath and be more lisible
Laurent Peuch <cortex@worlddomination.be>
parents: 12383
diff changeset
   344
9878
f3936f64bd98 [doc/book] update examples, using the new connection api
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 9391
diff changeset
   345
                cnx.commit()
12384
b2e0b6a8f76c [doc] blanks spaces to allow example to breath and be more lisible
Laurent Peuch <cortex@worlddomination.be>
parents: 12383
diff changeset
   346
9878
f3936f64bd98 [doc/book] update examples, using the new connection api
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 9391
diff changeset
   347
                # init some data using the default manager connection
f3936f64bd98 [doc/book] update examples, using the new connection api
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 9391
diff changeset
   348
                folder = cnx.create_entity('Folder',
f3936f64bd98 [doc/book] update examples, using the new connection api
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 9391
diff changeset
   349
                                           name=u'restricted',
10383
53d7cf6f0b84 [doc] fix errors in test_visibility_propagation example
Rabah Meradi <rabah.meradi@logilab.fr>
parents: 10376
diff changeset
   350
                                           visibility=u'restricted')
9878
f3936f64bd98 [doc/book] update examples, using the new connection api
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 9391
diff changeset
   351
                photo1 = cnx.create_entity('File',
10383
53d7cf6f0b84 [doc] fix errors in test_visibility_propagation example
Rabah Meradi <rabah.meradi@logilab.fr>
parents: 10376
diff changeset
   352
                                           data_name=u'photo1.jpg',
9878
f3936f64bd98 [doc/book] update examples, using the new connection api
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 9391
diff changeset
   353
                                           data=Binary('xxx'),
f3936f64bd98 [doc/book] update examples, using the new connection api
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 9391
diff changeset
   354
                                           filed_under=folder)
12384
b2e0b6a8f76c [doc] blanks spaces to allow example to breath and be more lisible
Laurent Peuch <cortex@worlddomination.be>
parents: 12383
diff changeset
   355
9878
f3936f64bd98 [doc/book] update examples, using the new connection api
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 9391
diff changeset
   356
                cnx.commit()
12384
b2e0b6a8f76c [doc] blanks spaces to allow example to breath and be more lisible
Laurent Peuch <cortex@worlddomination.be>
parents: 12383
diff changeset
   357
9878
f3936f64bd98 [doc/book] update examples, using the new connection api
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 9391
diff changeset
   358
                # visibility propagation
f3936f64bd98 [doc/book] update examples, using the new connection api
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 9391
diff changeset
   359
                self.assertEquals(photo1.visibility, 'restricted')
12384
b2e0b6a8f76c [doc] blanks spaces to allow example to breath and be more lisible
Laurent Peuch <cortex@worlddomination.be>
parents: 12383
diff changeset
   360
9878
f3936f64bd98 [doc/book] update examples, using the new connection api
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 9391
diff changeset
   361
                # unless explicitly specified
f3936f64bd98 [doc/book] update examples, using the new connection api
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 9391
diff changeset
   362
                photo2 = cnx.create_entity('File',
f3936f64bd98 [doc/book] update examples, using the new connection api
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 9391
diff changeset
   363
                                           data_name=u'photo2.jpg',
10383
53d7cf6f0b84 [doc] fix errors in test_visibility_propagation example
Rabah Meradi <rabah.meradi@logilab.fr>
parents: 10376
diff changeset
   364
                                           data=Binary('xxx'),
53d7cf6f0b84 [doc] fix errors in test_visibility_propagation example
Rabah Meradi <rabah.meradi@logilab.fr>
parents: 10376
diff changeset
   365
                                           visibility=u'public',
53d7cf6f0b84 [doc] fix errors in test_visibility_propagation example
Rabah Meradi <rabah.meradi@logilab.fr>
parents: 10376
diff changeset
   366
                                           filed_under=folder)
12384
b2e0b6a8f76c [doc] blanks spaces to allow example to breath and be more lisible
Laurent Peuch <cortex@worlddomination.be>
parents: 12383
diff changeset
   367
9878
f3936f64bd98 [doc/book] update examples, using the new connection api
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 9391
diff changeset
   368
                cnx.commit()
12384
b2e0b6a8f76c [doc] blanks spaces to allow example to breath and be more lisible
Laurent Peuch <cortex@worlddomination.be>
parents: 12383
diff changeset
   369
9878
f3936f64bd98 [doc/book] update examples, using the new connection api
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 9391
diff changeset
   370
                self.assertEquals(photo2.visibility, 'public')
12384
b2e0b6a8f76c [doc] blanks spaces to allow example to breath and be more lisible
Laurent Peuch <cortex@worlddomination.be>
parents: 12383
diff changeset
   371
9878
f3936f64bd98 [doc/book] update examples, using the new connection api
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 9391
diff changeset
   372
            with self.new_access('toto').repo_cnx() as cnx:
f3936f64bd98 [doc/book] update examples, using the new connection api
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 9391
diff changeset
   373
                # test security
f3936f64bd98 [doc/book] update examples, using the new connection api
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 9391
diff changeset
   374
                self.assertEqual(1, len(cnx.execute('File X'))) # only the public one
f3936f64bd98 [doc/book] update examples, using the new connection api
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 9391
diff changeset
   375
                self.assertEqual(0, len(cnx.execute('Folder X'))) # restricted...
12384
b2e0b6a8f76c [doc] blanks spaces to allow example to breath and be more lisible
Laurent Peuch <cortex@worlddomination.be>
parents: 12383
diff changeset
   376
10383
53d7cf6f0b84 [doc] fix errors in test_visibility_propagation example
Rabah Meradi <rabah.meradi@logilab.fr>
parents: 10376
diff changeset
   377
            with self.admin_access.repo_cnx() as cnx:
9878
f3936f64bd98 [doc/book] update examples, using the new connection api
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 9391
diff changeset
   378
                # may_be_read_by propagation
f3936f64bd98 [doc/book] update examples, using the new connection api
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 9391
diff changeset
   379
                folder = cnx.entity_from_eid(folder.eid)
f3936f64bd98 [doc/book] update examples, using the new connection api
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 9391
diff changeset
   380
                folder.cw_set(may_be_read_by=toto)
12384
b2e0b6a8f76c [doc] blanks spaces to allow example to breath and be more lisible
Laurent Peuch <cortex@worlddomination.be>
parents: 12383
diff changeset
   381
9878
f3936f64bd98 [doc/book] update examples, using the new connection api
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 9391
diff changeset
   382
                cnx.commit()
12384
b2e0b6a8f76c [doc] blanks spaces to allow example to breath and be more lisible
Laurent Peuch <cortex@worlddomination.be>
parents: 12383
diff changeset
   383
10383
53d7cf6f0b84 [doc] fix errors in test_visibility_propagation example
Rabah Meradi <rabah.meradi@logilab.fr>
parents: 10376
diff changeset
   384
            with self.new_access('toto').repo_cnx() as cnx:
53d7cf6f0b84 [doc] fix errors in test_visibility_propagation example
Rabah Meradi <rabah.meradi@logilab.fr>
parents: 10376
diff changeset
   385
                photo1 = cnx.entity_from_eid(photo1.eid)
12384
b2e0b6a8f76c [doc] blanks spaces to allow example to breath and be more lisible
Laurent Peuch <cortex@worlddomination.be>
parents: 12383
diff changeset
   386
9878
f3936f64bd98 [doc/book] update examples, using the new connection api
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 9391
diff changeset
   387
                self.failUnless(photo1.may_be_read_by)
12384
b2e0b6a8f76c [doc] blanks spaces to allow example to breath and be more lisible
Laurent Peuch <cortex@worlddomination.be>
parents: 12383
diff changeset
   388
9878
f3936f64bd98 [doc/book] update examples, using the new connection api
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 9391
diff changeset
   389
                # test security with permissions
f3936f64bd98 [doc/book] update examples, using the new connection api
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 9391
diff changeset
   390
                self.assertEquals(2, len(cnx.execute('File X'))) # now toto has access to photo2
f3936f64bd98 [doc/book] update examples, using the new connection api
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 9391
diff changeset
   391
                self.assertEquals(1, len(cnx.execute('Folder X'))) # and to restricted folder
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   392
12403
d901fc62eb01 [doc] pep8 and retab in tutorial code example
Laurent Peuch <cortex@worlddomination.be>
parents: 12401
diff changeset
   393
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   394
    if __name__ == '__main__':
12383
2dee7a944b3a [doc] default tests template has changed
Laurent Peuch <cortex@worlddomination.be>
parents: 12382
diff changeset
   395
        from unittest import main
2dee7a944b3a [doc] default tests template has changed
Laurent Peuch <cortex@worlddomination.be>
parents: 12382
diff changeset
   396
        main()
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   397
9881
3c2202e7bd31 [doc/book] spelling fixes in security tutorial
Julien Cristau <julien.cristau@logilab.fr>
parents: 9878
diff changeset
   398
It's not complete, but shows most things you'll want to do in tests: adding some
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   399
content, creating users and connecting as them in the test, etc...
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   400
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   401
To run it type:
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   402
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   403
.. sourcecode:: bash
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   404
12881
38fcf5707295 [doc] replace python with python3 in shell commands
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 12879
diff changeset
   405
    $ python3 test/test_sytweb.py
12385
ec8d3d8a9cf7 [doc] output has changed
Laurent Peuch <cortex@worlddomination.be>
parents: 12384
diff changeset
   406
    ======================================================================
ec8d3d8a9cf7 [doc] output has changed
Laurent Peuch <cortex@worlddomination.be>
parents: 12384
diff changeset
   407
    -> creating tables [====================]
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   408
    -> inserting default user and default groups.
12385
ec8d3d8a9cf7 [doc] output has changed
Laurent Peuch <cortex@worlddomination.be>
parents: 12384
diff changeset
   409
    -> storing the schema in the database [====================]
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   410
    -> database for instance data initialized.
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   411
    .
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   412
    ----------------------------------------------------------------------
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   413
    Ran 1 test in 22.547s
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   414
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   415
    OK
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   416
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   417
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   418
The first execution is taking time, since it creates a sqlite database for the
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   419
test instance. The second one will be much quicker:
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   420
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   421
.. sourcecode:: bash
7286
a0d3ea01f4bf [doc] fix doc and tutorials about hooks and operations
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 6923
diff changeset
   422
12881
38fcf5707295 [doc] replace python with python3 in shell commands
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 12879
diff changeset
   423
    $ python3 test/test_sytweb.py
12385
ec8d3d8a9cf7 [doc] output has changed
Laurent Peuch <cortex@worlddomination.be>
parents: 12384
diff changeset
   424
    ======================================================================
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   425
    .
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   426
    ----------------------------------------------------------------------
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   427
    Ran 1 test in 2.662s
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   428
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   429
    OK
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   430
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   431
If you do some changes in your schema, you'll have to force regeneration of that
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   432
database. You do that by removing the tmpdb files before running the test: ::
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   433
9881
3c2202e7bd31 [doc/book] spelling fixes in security tutorial
Julien Cristau <julien.cristau@logilab.fr>
parents: 9878
diff changeset
   434
    $ rm data/database/tmpdb*
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   435
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   436
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   437
.. _adv_tuto_migration_script:
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   438
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   439
Step 4: writing the migration script and migrating the instance
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   440
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   441
9881
3c2202e7bd31 [doc/book] spelling fixes in security tutorial
Julien Cristau <julien.cristau@logilab.fr>
parents: 9878
diff changeset
   442
Prior to those changes, I created an instance, fed it with some data, so I
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   443
don't want to create a new one, but to migrate the existing one. Let's see how to
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   444
do that.
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   445
12394
e847b5d1ffff [doc] always put file name for code example and uses :file:`path` syntax everywhere
Laurent Peuch <cortex@worlddomination.be>
parents: 12385
diff changeset
   446
Migration commands should be put in the cube's :file:`migration` directory, in a
12396
4a08a2b6e979 [doc] explains what the <X.Y.Z> means
Laurent Peuch <cortex@worlddomination.be>
parents: 12394
diff changeset
   447
file named :file:`<X.Y.Z>_Any.py` ('Any' being there mostly for historical
4a08a2b6e979 [doc] explains what the <X.Y.Z> means
Laurent Peuch <cortex@worlddomination.be>
parents: 12394
diff changeset
   448
reasons and '<X.Y.Z>' being the version number of the cube we are going to release.)
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   449
12394
e847b5d1ffff [doc] always put file name for code example and uses :file:`path` syntax everywhere
Laurent Peuch <cortex@worlddomination.be>
parents: 12385
diff changeset
   450
Here I'll create a :file:`migration/0.2.0_Any.py` file containing the following
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   451
instructions:
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   452
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   453
.. sourcecode:: python
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   454
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   455
  add_relation_type('may_be_read_by')
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   456
  add_relation_type('visibility')
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   457
  sync_schema_props_perms()
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   458
12394
e847b5d1ffff [doc] always put file name for code example and uses :file:`path` syntax everywhere
Laurent Peuch <cortex@worlddomination.be>
parents: 12385
diff changeset
   459
Then I update the version number in the cube's :file:`__pkginfo__.py` to 0.2.0. And
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   460
that's it! Those instructions will:
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   461
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   462
* update the instance's schema by adding our two new relations and update the
9881
3c2202e7bd31 [doc/book] spelling fixes in security tutorial
Julien Cristau <julien.cristau@logilab.fr>
parents: 9878
diff changeset
   463
  underlying database tables accordingly (the first two instructions)
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   464
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   465
* update schema's permissions definition (the last instruction)
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   466
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   467
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   468
To migrate my instance I simply type::
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   469
10376
b566c8081832 [doc] the instance is sytweb_instance and sytweb is the cube
Rabah Meradi <rabah.meradi@logilab.fr>
parents: 9881
diff changeset
   470
   cubicweb-ctl upgrade sytweb_instance
6876
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   471
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   472
You'll then be asked some questions to do the migration step by step. You should say
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   473
YES when it asks if a backup of your database should be done, so you can get back
4b0b9d8207c5 [doc] backport part 3 & 4 of the sytweb's tutorial + to be published part 5
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents:
diff changeset
   474
to initial state if anything goes wrong...