Merge 91ce26b into 0c99ee3

dev-docs/plugins/extending-misago.md

@@ -105,6 +105,7 @@ The following models currently define this field:
 - `misago.threads.models.Poll`
 - `misago.threads.models.Post`
 - `misago.threads.models.Thread`
+- `misago.users.models.Group`
 - `misago.users.models.User`
 
 `plugin_data` is not a replacement for models. Use it for [denormalization](https://en.wikipedia.org/wiki/Denormalization), storing small bits of data that are frequently accessed or used in queries. 

dev-docs/plugins/hooks/build-user-category-permissions-hook.md

@@ -0,0 +1,151 @@
+# `build_user_category_permissions_hook`
+
+This hook wraps the standard function that Misago uses to build user category permissions.
+
+Category permissions are stored as a Python `dict` with permission names as keys and values being category IDs with the associated permission:
+
+```python
+category_permissions = {
+    "see": [1, 2, 3],
+    "browse": [1, 2, 3],
+    "start": [1, 2],
+    "reply": [1, 2, 3],
+    "attachments": [1, 2, 3],
+}
+```
+
+Plugins can add custom permissions to this dict.
+
+
+## Location
+
+This hook can be imported from `misago.permissions.hooks`:
+
+```python
+from misago.permissions.hooks import build_user_category_permissions_hook
+```
+
+
+## Filter
+
+```python
+def custom_build_user_category_permissions_filter(
+    action: BuildUserCategoryPermissionsHookAction,
+    groups: list[Group],
+    categories: dict[int, Category],
+    category_permissions: dict[int, list[str]],
+    user_permissions: dict,
+) -> dict:
+    ...
+```
+
+A function implemented by a plugin that can be registered in this hook.
+
+
+### Arguments
+
+#### `action: BuildUserCategoryPermissionsHookAction`
+
+A standard Misago function used to build user category permissions or the next filter function from another plugin.
+
+See the [action](#action) section for details.
+
+
+#### `groups: list[Group]`
+
+A list of groups user belongs to.
+
+
+#### `categories: dict[int, Category]`
+
+A `dict` of categories.
+
+
+#### `category_permissions: dict[int, list[str]]`
+
+A Python `dict` containing lists of category permissions read from the database, indexed by category IDs.
+
+
+#### `user_permissions: dict`
+
+A Python `dict` with user permissions build so far.
+
+
+### Return value
+
+A Python `dict` with category permissions.
+
+
+## Action
+
+```python
+def build_user_category_permissions_action(
+    groups: list[Group],
+    categories: dict[int, Category],
+    category_permissions: dict[int, list[str]],
+    user_permissions: dict,
+) -> dict:
+    ...
+```
+
+A standard Misago function used to get user category permissions.
+
+
+### Arguments
+
+#### `groups: list[Group]`
+
+A list of groups user belongs to.
+
+
+#### `categories: dict[int, Category]`
+
+A `dict` of categories.
+
+
+#### `category_permissions: dict[int, list[str]]`
+
+A Python `dict` containing lists of category permissions read from the database, indexed by category IDs.
+
+
+#### `user_permissions: dict`
+
+A Python `dict` with user permissions build so far.
+
+
+### Return value
+
+A Python `dict` with category permissions.
+
+
+## Example
+
+The code below implements a custom filter function that includes a custom permission in user's category permissions, if they can browse it:
+
+```python
+from misago.categories.models import Category
+from misago.permissions.enums import CategoryPermission
+from misago.permissions.hooks import build_user_category_permissions_hook
+from misago.users.models import Group
+
+
+@build_user_category_permissions_hook.append_filter
+def include_plugin_permission(
+    action,
+    groups: list[Group],
+    categories: dict[int, Category],
+    category_permissions: dict[int, list[str]],
+    user_permissions: dict,
+) -> dict:
+    permissions = action(group, categories, category_permissions, user_permissions)
+    permissions["plugin"] = []
+
+    for category_id in categories:
+        if (
+            category_id in permissions[CategoryPermission.BROWSE]
+            and "plugin" in category_permissions.get(category_id, [])
+        ):
+            permissions["plugin"].append(category_id)
+
+    return permissions
+```

dev-docs/plugins/hooks/build-user-permissions-hook.md

@@ -0,0 +1,89 @@
+# `build_user_permissions_hook`
+
+This hook wraps the standard function that Misago uses to build user permissions from their groups.
+
+
+## Location
+
+This hook can be imported from `misago.permissions.hooks`:
+
+```python
+from misago.permissions.hooks import build_user_permissions_hook
+```
+
+
+## Filter
+
+```python
+def custom_build_user_permissions_filter(
+    action: BuildUserPermissionsHookAction, groups: list[Group]
+) -> dict:
+    ...
+```
+
+A function implemented by a plugin that can be registered in this hook.
+
+
+### Arguments
+
+#### `action: BuildUserPermissionsHookAction`
+
+A standard Misago function used to build user permissions from their groups or the next filter function from another plugin.
+
+See the [action](#action) section for details.
+
+
+#### `groups: list[Group]`
+
+A list of groups user belongs to.
+
+
+### Return value
+
+A Python `dict` with user permissions build from their groups.
+
+
+## Action
+
+```python
+def build_user_permissions_action(groups: list[Group]) -> dict:
+    ...
+```
+
+A standard Misago function used to build user permissions from their groups.
+
+
+### Arguments
+
+#### `groups: list[Group]`
+
+A list of groups user belongs to.
+
+
+### Return value
+
+A Python `dict` with user permissions build from their groups.
+
+
+## Example
+
+The code below implements a custom filter function that includes a custom permission in user permissions:
+
+```python
+from misago.permissions.hooks import build_user_permissions_hook
+from misago.users.models import Group
+
+
+@build_user_permissions_hook.append_filter
+def include_plugin_permission(
+    action, groups: list[Group]
+) -> dict:
+    permissions = action(groups)
+    permissions["plugin_permission"] = False
+
+    for group in groups:
+        if group.plugin_data.get("plugin_permission"):
+            permissions["plugin_permission"] = True
+
+    return permissions
+```

dev-docs/plugins/hooks/copy-category-permissions-hook.md

@@ -0,0 +1,112 @@
+# `copy_category_permissions_hook`
+
+This hook wraps the standard function that Misago uses to copy category permissions.
+
+
+## Location
+
+This hook can be imported from `misago.permissions.hooks`:
+
+```python
+from misago.permissions.hooks import copy_category_permissions_hook
+```
+
+
+## Filter
+
+```python
+def custom_copy_category_permissions_filter(
+    action: CopyCategoryPermissionsHookAction,
+    src: Category,
+    dst: Category,
+    request: HttpRequest | None=None,
+) -> None:
+    ...
+```
+
+A function implemented by a plugin that can be registered in this hook.
+
+
+### Arguments
+
+#### `action: CopyCategoryPermissionsHookAction`
+
+A standard Misago function used to copy permissions from one category to another or the next filter function from another plugin.
+
+See the [action](#action) section for details.
+
+
+#### `src: Category`
+
+A category to copy permissions from.
+
+
+#### `dst: Category`
+
+A category to copy permissions to.
+
+
+#### `request: Optional[HttpRequest]`
+
+The request object or `None` if it was not provided.
+
+
+## Action
+
+```python
+def copy_category_permissions_action(
+    src: Category, dst: Category, request: HttpRequest | None=None
+) -> None:
+    ...
+```
+
+A standard Misago function used to copy permissions from one category to another or the next filter function from another plugin.
+
+
+### Arguments
+
+#### `src: Category`
+
+A category to copy permissions from.
+
+
+#### `dst: Category`
+
+A category to copy permissions to.
+
+
+#### `request: Optional[HttpRequest]`
+
+The request object or `None` if it was not provided.
+
+
+## Example
+
+The code below implements a custom filter function that copies additional models with the plugin's category permissions:
+
+```python
+from django.http import HttpRequest
+from misago.permissions.hooks import copy_category_permissions_hook
+from misago.users.models import Category
+
+from .models PluginCategoryPermissions
+
+
+@copy_category_permissions_hook.append_filter
+def copy_group_plugin_perms(
+    action, src: Category, dst: Category, request: HttpRequest | None = None,
+) -> None:
+    # Delete old permissions
+    PluginCategoryPermissions.objects.filter(category=dst).delete()
+
+    # Copy permissions
+    for permission in PluginCategoryPermissions.objects.filter(category=src):
+        PluginCategoryPermissions.objects.create(
+            category=dst,
+            group_id=permission.group_id,
+            can_do_something=permission.can_do_something,
+        )
+
+    # Call the next function in chain
+    return action(group, **kwargs)
+```