Aller au contenu

# Perms

Permission classes to be used within ninja-extra controllers.

Some permissions are global (like `IsInGroup` or `IsRoot`), and some others are per-object (like `CanView` or `CanEdit`).

Example

    # restrict all the routes of this controller
    # to subscribed users
    @api_controller("/foo", permissions=[IsSubscriber])
    class FooController(ControllerBase):
        @route.get("/bar")
        def bar_get(self):
            # This route inherits the permissions of the controller
            # ...

        @route.bar("/bar/{bar_id}", permissions=[CanView])
        def bar_get_one(self, bar_id: int):
            # per-object permission resolution happens
            # when calling either the `get_object_or_exception`
            # or `get_object_or_none` method.
            bar = self.get_object_or_exception(Counter, pk=bar_id)

            # you can also call the `check_object_permission` manually
            other_bar = Counter.objects.first()
            self.check_object_permissions(other_bar)

            # ...

        # This route is restricted to counter admins and root users
        @route.delete(
            "/bar/{bar_id}",
            permissions=[IsRoot | IsInGroup(settings.SITH_GROUP_COUNTER_ADMIN_ID)
        ]
        def bar_delete(self, bar_id: int):
            # ...

### `CanAccessLookup = IsLoggedInCounter | HasPerm('core.access_lookup')` `module-attribute`

### `IsInGroup(group_pk)`

Bases: `BasePermission`

Check that the user is in the group whose primary key is given.

Source code in `api/permissions.py`

    55
    56
    def __init__(self, group_pk: int):
        self._group_pk = group_pk

### `HasPerm(perms, op=operator.and_)`

Bases: `BasePermission`

Check that the user has the required perm.

If multiple perms are given, a comparer function can also be passed, in order to change the way perms are checked.

Example

    @api_controller("/foo")
    class FooController(ControllerBase):
        # this route will require both permissions
        @route.put("/foo", permissions=[HasPerm(["foo.change_foo", "foo.add_foo"])]
        def foo(self): ...

        # This route will require at least one of the perm,
        # but it's not mandatory to have all of them
        @route.put(
            "/bar",
            permissions=[HasPerm(["foo.change_bar", "foo.add_bar"], op=operator.or_)],
        )
        def bar(self): ...

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`perms` | `str | Permission | list[str | Permission]` | a permission or a list of permissions the user must have | required
`op` | `Callable[[bool, bool], bool]` | An operator to combine multiple permissions (in most cases, it will be either `operator.and_` or `operator.or_`) | `and_`

Source code in `api/permissions.py`

     86
     87
     88
     89
     90
     91
     92
     93
     94
     95
     96
     97
     98
     99
    100
    101
    def __init__(
        self,
        perms: str | Permission | list[str | Permission],
        op: Callable[[bool, bool], bool] = operator.and_,
    ):
        """
        Args:
            perms: a permission or a list of permissions the user must have
            op: An operator to combine multiple permissions (in most cases,
                it will be either `operator.and_` or `operator.or_`)
        """
        super().__init__()
        if not isinstance(perms, (list, tuple, set)):
            perms = [perms]
        self._operator = op
        self._perms = perms

### `IsRoot`

Bases: `BasePermission`

Check that the user is root.

### `IsSubscriber`

Bases: `BasePermission`

Check that the user is currently subscribed.

### `IsOldSubscriber`

Bases: `BasePermission`

Check that the user has at least one subscription in its history.

### `CanView`

Bases: `BasePermission`

Check that this user has the permission to view the object of this route.

Wrap the `user.can_view(obj)` method. To see an example, look at the example in the module docstring.

### `CanEdit`

Bases: `BasePermission`

Check that this user has the permission to edit the object of this route.

Wrap the `user.can_edit(obj)` method. To see an example, look at the example in the module docstring.

### `IsOwner`

Bases: `BasePermission`

Check that this user owns the object of this route.

Wrap the `user.is_owner(obj)` method. To see an example, look at the example in the module docstring.

### `IsLoggedInCounter`

Bases: `BasePermission`

Check that a user is logged in a counter.