From a98b5843cc0ba04875ce3351e3ea70309c24d736 Mon Sep 17 00:00:00 2001 From: stumpylog <797416+stumpylog@users.noreply.github.com> Date: Thu, 6 Aug 2026 09:49:45 -0700 Subject: [PATCH] docs: document legacy status of get_objects_for_user_owner_aware/has_perms_owner_aware Stage 4's PermittedObjectsFilter/permitted_object_ids() covers the queryset-filtering use case, but both functions still have production callers outside this plan's scope (documents/views.py, documents/serialisers.py, documents/signals/handlers.py, paperless_ai/matching.py, paperless_ai/ai_classifier.py). Per Task 20 Step 2, they are kept in place rather than partially deleted, with docstrings updated to note their legacy status and remaining callers. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01UFyrt7FWbRRdTUAcdqBcsc --- src/documents/permissions.py | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/src/documents/permissions.py b/src/documents/permissions.py index 29c850a54..7e07665fe 100644 --- a/src/documents/permissions.py +++ b/src/documents/permissions.py @@ -359,6 +359,14 @@ def get_objects_for_user_owner_aware( """ Returns objects the user owns, are unowned, or has explicit perms. When include_deleted is True, soft-deleted items are also included. + + Legacy slow path (guardian-backed, O(n) style permission resolution). + The Stage 4 unification migrated most call sites onto + ``PermittedObjectsFilter``/``permitted_object_ids()``, but this function + is kept because production callers still remain, e.g. + ``documents/views.py`` (several call sites), ``documents/signals/handlers.py``, + ``paperless_ai/matching.py``, and ``paperless_ai/ai_classifier.py``. + Do not remove until those call sites are migrated in a future task. """ manager = ( Model.global_objects @@ -378,6 +386,15 @@ def get_objects_for_user_owner_aware( def has_perms_owner_aware(user, perms, obj): + """ + Legacy slow path (guardian-backed) single-object permission check. + + Stage 4's ``PermittedObjectsFilter``/``permitted_object_ids()`` covers + queryset-level filtering, but this single-object check still has many + production callers, notably ``documents/views.py`` and + ``documents/serialisers.py``. Kept only for those remaining callers; + do not remove until they are migrated in a future task. + """ checker = ObjectPermissionChecker(user) return obj.owner is None or obj.owner == user or checker.has_perm(perms, obj)