Generate hooks reference

dev-docs/plugins/hooks/check-see-private-thread-permission-hook.md

@@ -0,0 +1,99 @@
+# `check_see_private_thread_permission_hook`
+
+This hook wraps the standard Misago function used to check if the user has a permission to see a private thread. Raises Django's `Http404` if they can't.
+
+
+## Location
+
+This hook can be imported from `misago.permissions.hooks`:
+
+```python
+from misago.permissions.hooks import check_see_private_thread_permission_hook
+```
+
+
+## Filter
+
+```python
+def custom_check_see_private_thread_permission_filter(
+    action: CheckSeePrivateThreadPermissionHookAction,
+    permissions: 'UserPermissionsProxy',
+    thread: Thread,
+) -> None:
+    ...
+```
+
+A function implemented by a plugin that can be registered in this hook.
+
+
+### Arguments
+
+#### `action: CheckSeePrivateThreadPermissionHookAction`
+
+A standard Misago function used to check if the user has a permission to see a private thread. Raises Django's `Http404` if they can't.
+
+See the [action](#action) section for details.
+
+
+#### `user_permissions: UserPermissionsProxy`
+
+A proxy object with the current user's permissions.
+
+
+#### `thread: Thread`
+
+A thread to check permissions for.
+
+
+## Action
+
+```python
+def check_see_private_thread_permission_action(
+    permissions: 'UserPermissionsProxy', thread: Thread
+) -> None:
+    ...
+```
+
+A standard Misago function used to check if the user has a permission to see a private thread. Raises Django's `Http404` if they can't.
+
+
+### Arguments
+
+#### `user_permissions: UserPermissionsProxy`
+
+A proxy object with the current user's permissions.
+
+
+#### `thread: Thread`
+
+A thread to check permissions for.
+
+
+## Example
+
+The code below implements a custom filter function that blocks a user from seeing a specified thread if there is a custom flag set on their account.
+
+```python
+from django.core.exceptions import PermissionDenied
+from django.utils.translation import pgettext
+from misago.permissions.hooks import check_see_private_thread_permission_hook
+from misago.permissions.proxy import UserPermissionsProxy
+from misago.threads.models import Thread
+
+@check_see_private_thread_permission_hook.append_filter
+def check_user_can_see_thread(
+    action,
+    permissions: UserPermissionsProxy,
+    thread: Thread,
+) -> None:
+    # Run standard permission checks
+    action(permissions, category)
+
+    if thread.id in permissions.user.plugin_data.get("banned_thread", []):
+        raise PermissionDenied(
+            pgettext(
+                "thread permission error",
+                "Site admin has removed your access to this thread."
+            )
+        )
+```

dev-docs/plugins/hooks/check-see-thread-permission-hook.md

@@ -0,0 +1,114 @@
+# `check_see_thread_permission_hook`
+
+This hook wraps the standard Misago function used to check if the user has a permission to see a thread. Raises Django's `Http404` if they can't see it or `PermissionDenied` with an error message if they can't browse it.
+
+
+## Location
+
+This hook can be imported from `misago.permissions.hooks`:
+
+```python
+from misago.permissions.hooks import check_see_thread_permission_hook
+```
+
+
+## Filter
+
+```python
+def custom_check_see_thread_permission_filter(
+    action: CheckSeeThreadPermissionHookAction,
+    permissions: 'UserPermissionsProxy',
+    category: Category,
+    thread: Thread,
+) -> None:
+    ...
+```
+
+A function implemented by a plugin that can be registered in this hook.
+
+
+### Arguments
+
+#### `action: CheckSeeThreadPermissionHookAction`
+
+A standard Misago function used to check if the user has a permission to see a thread. Raises Django's `Http404` if they can't see it or `PermissionDenied` with an error message if they can't browse it.
+
+See the [action](#action) section for details.
+
+
+#### `user_permissions: UserPermissionsProxy`
+
+A proxy object with the current user's permissions.
+
+
+#### `category: Category`
+
+A category to check permissions for.
+
+
+#### `thread: Thread`
+
+A thread to check permissions for.
+
+
+## Action
+
+```python
+def check_see_thread_permission_action(
+    permissions: 'UserPermissionsProxy',
+    category: Category,
+    thread: Thread,
+) -> None:
+    ...
+```
+
+A standard Misago function used to check if the user has a permission to see a thread. Raises Django's `Http404` if they can't see it or `PermissionDenied` with an error message if they can't browse it.
+
+
+### Arguments
+
+#### `user_permissions: UserPermissionsProxy`
+
+A proxy object with the current user's permissions.
+
+
+#### `category: Category`
+
+A category to check permissions for.
+
+
+#### `thread: Thread`
+
+A thread to check permissions for.
+
+
+## Example
+
+The code below implements a custom filter function that blocks a user from seeing a specified thread if there is a custom flag set on their account.
+
+```python
+from django.core.exceptions import PermissionDenied
+from django.utils.translation import pgettext
+from misago.categories.models import Category
+from misago.permissions.hooks import check_see_thread_permission_hook
+from misago.permissions.proxy import UserPermissionsProxy
+from misago.threads.models import Thread
+
+@check_see_thread_permission_hook.append_filter
+def check_user_can_see_thread(
+    action,
+    permissions: UserPermissionsProxy,
+    category: Category,
+    thread: Thread,
+) -> None:
+    # Run standard permission checks
+    action(permissions, category)
+
+    if thread.id in permissions.user.plugin_data.get("banned_thread", []):
+        raise PermissionDenied(
+            pgettext(
+                "thread permission error",
+                "Site admin has removed your access to this thread."
+            )
+        )
+```

dev-docs/plugins/hooks/filter-private-thread-posts-queryset-hook.md

@@ -0,0 +1,116 @@
+# `filter_private_thread_posts_queryset_hook`
+
+This hook wraps the standard function that Misago uses set filters on private thread's posts queryset to limit it only to posts that the user can see.
+
+
+## Location
+
+This hook can be imported from `misago.permissions.hooks`:
+
+```python
+from misago.permissions.hooks import filter_private_thread_posts_queryset_hook
+```
+
+
+## Filter
+
+```python
+def custom_private_thread_posts_queryset_filter(
+    action: FilterPrivateThreadPostsQuerysetHookAction,
+    permissions: 'UserPermissionsProxy',
+    thread: Thread,
+    queryset: QuerySet,
+) -> QuerySet:
+    ...
+```
+
+A function implemented by a plugin that can be registered in this hook.
+
+
+### Arguments
+
+#### `action: FilterPrivateThreadPostsQuerysetHookAction`
+
+A standard Misago function used to set filters on a queryset used to retrieve specified private thread's posts that user can see.
+
+See the [action](#action) section for details.
+
+
+#### `user_permissions: UserPermissionsProxy`
+
+A proxy object with the current user's permissions.
+
+
+#### `thread: Thread`
+
+A private thread instance which's posts are retrieved.
+
+
+#### `queryset: Queryset`
+
+A queryset returning thread's posts.
+
+
+#### Return value
+
+A `queryset` filtered to show only thread posts that the user can see.
+
+
+## Action
+
+```python
+def filter_private_thread_posts_queryset_action(
+    permissions: 'UserPermissionsProxy',
+    thread: Thread,
+    queryset: QuerySet,
+) -> QuerySet:
+    ...
+```
+
+A standard Misago function used to set filters on a queryset used to retrieve specified private thread's posts that user can see.
+
+
+### Arguments
+
+#### `user_permissions: UserPermissionsProxy`
+
+A proxy object with the current user's permissions.
+
+
+#### `thread: Thread`
+
+A private thread instance which's posts are retrieved.
+
+
+#### `queryset: Queryset`
+
+A queryset returning thread's posts.
+
+
+#### Return value
+
+A `queryset` filtered to show only thread posts that the user can see.
+
+
+## Example
+
+The code below implements a custom filter function hides deleted posts from anonymous user.
+
+```python
+from misago.permissions.hooks import filter_private_thread_posts_queryset_hook
+from misago.permissions.proxy import UserPermissionsProxy
+
+@filter_private_thread_posts_queryset_hook.append_filter
+def exclude_old_private_threads_queryset_hook(
+    action,
+    permissions: UserPermissionsProxy,
+    thread,
+    queryset,
+) -> None:
+    queryset = action(permissions, thread, queryset)
+
+    if permissions.user.is_anonymous:
+        return queryset.filter(is_hidden=False)
+
+    return queryset
+```

dev-docs/plugins/hooks/filter-private-threads-queryset-hook.md

@@ -18,8 +18,8 @@ from misago.permissions.hooks import filter_private_threads_queryset_hook
 def custom_private_threads_queryset_filter(
     action: FilterPrivateThreadsQuerysetHookAction,
     permissions: 'UserPermissionsProxy',
-    queryset,
-) -> None:
+    queryset: QuerySet,
+) -> QuerySet:
     ...
 ```
 
@@ -53,7 +53,9 @@ A `queryset` filtered to show only private threads that the user has access to.
 ## Action
 
 ```python
-def filter_private_threads_queryset_action(permissions: 'UserPermissionsProxy', queryset):
+def filter_private_threads_queryset_action(
+    permissions: 'UserPermissionsProxy', queryset: QuerySet
+) -> QuerySet:
     ...
 ```