oxutils 0.1.8__py3-none-any.whl → 0.1.11__py3-none-any.whl

oxutils/pagination/cursor.py

@@ -0,0 +1,367 @@
+"""
+Cursor pagination for django ninja & ninja extra
+
+forked from django-ninja-cursor-pagination
+https://github.com/kitware-resonant/django-ninja-cursor-pagination
+
+
+adapted for django ninja extra by @prosper-groups-soft for Oxiliere
+https://github.com/prosper-groups-soft
+"""
+
+
+from base64 import b64decode, b64encode
+from dataclasses import dataclass
+from typing import Any
+from urllib import parse
+from django.db.models import QuerySet
+from django.http import HttpRequest
+from django.utils.translation import gettext as _
+from ninja import Field, Schema
+from ninja.pagination import PaginationBase
+from pydantic import field_validator
+
+
+@dataclass
+class Cursor:
+    offset: int = 0
+    reverse: bool = False
+    position: str | None = None
+
+
+def _clamp(val: int, min_: int, max_: int) -> int:
+    return max(min_, min(val, max_))
+
+
+def _reverse_order(order: tuple) -> tuple:
+    # Reverse the ordering specification for a Django ORM query.
+    # Given an order_by tuple such as `('-created_at', 'uuid')` reverse the
+    # ordering and return a new tuple, eg. `('created_at', '-uuid')`.
+    def invert(x: str) -> str:
+        return x[1:] if x.startswith("-") else f"-{x}"
+
+    return tuple(invert(item) for item in order)
+
+
+def _replace_query_param(url: str, key: str, val: str) -> str:
+    scheme, netloc, path, query, fragment = parse.urlsplit(url)
+    query_dict = parse.parse_qs(query, keep_blank_values=True)
+    query_dict[key] = [val]
+    query = parse.urlencode(sorted(query_dict.items()), doseq=True)
+    return parse.urlunsplit((scheme, netloc, path, query, fragment))
+
+
+def _get_http_request(request) -> HttpRequest:
+    """
+    Normalize the incoming request object to a Django HttpRequest.
+
+    Supports both direct HttpRequest instances and ninja-extra ControllerBase
+    wrappers (where the HttpRequest is available as request.context.request).
+    """
+    if isinstance(request, HttpRequest):
+        return request
+
+    if hasattr(request, "context") and hasattr(request.context, "request"):
+        return request.context.request
+
+    raise TypeError(
+        f"Unsupported request type for pagination: {type(request)!r}"
+    )
+    
+
+
+class CursorPagination(PaginationBase):
+    class Input(Schema):
+        limit: int | None = Field(
+            None,
+            description=_("Number of results to return per page."),
+        )
+        cursor: str | None = Field(
+            None,
+            description=_("The pagination cursor value."),
+            validate_default=True,
+        )
+
+        @field_validator("cursor")
+        @classmethod
+        def decode_cursor(cls, encoded_cursor: str | None) -> Cursor:
+            if encoded_cursor is None:
+                return Cursor()
+
+            try:
+                encoded_cursor = parse.unquote(encoded_cursor)
+                querystring = b64decode(encoded_cursor).decode()
+                tokens = parse.parse_qs(querystring, keep_blank_values=True)
+
+                offset = int(tokens.get("o", ["0"])[0])
+                offset = _clamp(offset, 0, CursorPagination._offset_cutoff)
+
+                reverse = tokens.get("r", ["0"])[0]
+                reverse = bool(int(reverse))
+
+                position = tokens.get("p", [None])[0]
+            except (TypeError, ValueError) as e:
+                raise ValueError(_("Invalid cursor.")) from e
+
+            return Cursor(offset=offset, reverse=reverse, position=position)
+
+    class Output(Schema):
+        results: list[Any] = Field(description=_("The page of objects."))
+        count: int = Field(
+            description=_("The total number of results across all pages."),
+        )
+        next: str | None = Field(
+            description=_("URL of next page of results if there is one."),
+        )
+        previous: str | None = Field(
+            description=_("URL of previous page of results if there is one."),
+        )
+
+    items_attribute = "results"
+    default_ordering = ("-id",)
+    max_page_size = 100
+    _offset_cutoff = 100  # limit to protect against possibly malicious queries
+
+    def paginate_queryset(
+        self,
+        queryset: QuerySet,
+        pagination: Input,
+        request: Any,
+        **params,
+    ) -> dict:
+        limit = _clamp(pagination.limit or self.max_page_size, 0, self.max_page_size)
+        request = _get_http_request(request)
+
+        if not queryset.query.order_by:
+            queryset = queryset.order_by(*self.default_ordering)
+
+        order = queryset.query.order_by
+        total_count = queryset.count()
+
+        base_url = request.build_absolute_uri()
+        cursor = pagination.cursor
+
+        if cursor.reverse:
+            queryset = queryset.order_by(*_reverse_order(order))
+
+        if cursor.position is not None:
+            values = cursor.position.split("|")
+            fields = [f.lstrip("-") for f in order]
+
+            filters = {}
+            for i, field in enumerate(fields):
+                if i < len(values) - 1:
+                    filters[field] = values[i]
+                else:
+                    op = "lt" if order[i].startswith("-") ^ cursor.reverse else "gt"
+                    filters[f"{field}__{op}"] = values[i]
+
+            queryset = queryset.filter(**filters)
+
+
+        # If we have an offset cursor then offset the entire page by that amount.
+        # We also always fetch an extra item in order to determine if there is a
+        # page following on from this one.
+        results = list(queryset[cursor.offset : cursor.offset + limit + 1])
+        page = list(results[:limit])
+
+        # Determine the position of the final item following the page.
+        if len(results) > len(page):
+            has_following_position = True
+            following_position = self._get_position_from_instance(results[-1], order)
+        else:
+            has_following_position = False
+            following_position = None
+
+        if cursor.reverse:
+            # If we have a reverse queryset, then the query ordering was in reverse
+            # so we need to reverse the items again before returning them to the user.
+            page.reverse()
+
+            has_next = (cursor.position is not None) or (cursor.offset > 0)
+            has_previous = has_following_position
+            next_position = cursor.position if has_next else None
+            previous_position = following_position if has_previous else None
+        else:
+            has_next = has_following_position
+            has_previous = (cursor.position is not None) or (cursor.offset > 0)
+            next_position = following_position if has_next else None
+            previous_position = cursor.position if has_previous else None
+
+        return {
+            "results": page,
+            "count": total_count,
+            "next": self.next_link(
+                base_url=base_url,
+                page=page,
+                cursor=cursor,
+                order=order,
+                has_previous=has_previous,
+                limit=limit,
+                next_position=next_position,
+                previous_position=previous_position,
+            )
+            if has_next
+            else None,
+            "previous": self.previous_link(
+                base_url=base_url,
+                page=page,
+                cursor=cursor,
+                order=order,
+                has_next=has_next,
+                limit=limit,
+                next_position=next_position,
+                previous_position=previous_position,
+            )
+            if has_previous
+            else None,
+        }
+
+    def _encode_cursor(self, cursor: Cursor, base_url: str) -> str:
+        tokens = {}
+        if cursor.offset != 0:
+            tokens["o"] = str(cursor.offset)
+        if cursor.reverse:
+            tokens["r"] = "1"
+        if cursor.position is not None:
+            tokens["p"] = cursor.position
+
+        querystring = parse.urlencode(tokens, doseq=True)
+        encoded = b64encode(querystring.encode()).decode()
+        return _replace_query_param(base_url, "cursor", encoded)
+
+    def next_link(  # noqa: PLR0913
+        self,
+        *,
+        base_url: str,
+        page: list,
+        cursor: Cursor,
+        order: tuple,
+        has_previous: bool,
+        limit: int,
+        next_position: str,
+        previous_position: str,
+    ) -> str:
+        if page and cursor.reverse and cursor.offset:
+            # If we're reversing direction and we have an offset cursor
+            # then we cannot use the first position we find as a marker.
+            compare = self._get_position_from_instance(page[-1], order)
+        else:
+            compare = next_position
+        offset = 0
+
+        has_item_with_unique_position = False
+        for item in reversed(page):
+            position = self._get_position_from_instance(item, order)
+            if position != compare:
+                # The item in this position and the item following it
+                # have different positions. We can use this position as
+                # our marker.
+                has_item_with_unique_position = True
+                break
+
+            # The item in this position has the same position as the item
+            # following it, we can't use it as a marker position, so increment
+            # the offset and keep seeking to the previous item.
+            compare = position
+            offset += 1  # noqa: SIM113
+
+        if page and not has_item_with_unique_position:
+            # There were no unique positions in the page.
+            if not has_previous:
+                # We are on the first page.
+                # Our cursor will have an offset equal to the page size,
+                # but no position to filter against yet.
+                offset = limit
+                position = None
+            elif cursor.reverse:
+                # The change in direction will introduce a paging artifact,
+                # where we end up skipping forward a few extra items.
+                offset = 0
+                position = previous_position
+            else:
+                # Use the position from the existing cursor and increment
+                # it's offset by the page size.
+                offset = cursor.offset + limit
+                position = previous_position
+
+        if not page:
+            position = next_position
+
+        next_cursor = Cursor(offset=offset, reverse=False, position=position)
+        return self._encode_cursor(next_cursor, base_url)
+
+    def previous_link(  # noqa: PLR0913
+        self,
+        *,
+        base_url: str,
+        page: list,
+        cursor: Cursor,
+        order: tuple,
+        has_next: bool,
+        limit: int,
+        next_position: str,
+        previous_position: str,
+    ):
+        if page and not cursor.reverse and cursor.offset:
+            # If we're reversing direction and we have an offset cursor
+            # then we cannot use the first position we find as a marker.
+            compare = self._get_position_from_instance(page[0], order)
+        else:
+            compare = previous_position
+        offset = 0
+
+        has_item_with_unique_position = False
+        for item in page:
+            position = self._get_position_from_instance(item, order)
+            if position != compare:
+                # The item in this position and the item following it
+                # have different positions. We can use this position as
+                # our marker.
+                has_item_with_unique_position = True
+                break
+
+            # The item in this position has the same position as the item
+            # following it, we can't use it as a marker position, so increment
+            # the offset and keep seeking to the previous item.
+            compare = position
+            offset += 1  # noqa: SIM113
+
+        if page and not has_item_with_unique_position:
+            # There were no unique positions in the page.
+            if not has_next:
+                # We are on the final page.
+                # Our cursor will have an offset equal to the page size,
+                # but no position to filter against yet.
+                offset = limit
+                position = None
+            elif cursor.reverse:
+                # Use the position from the existing cursor and increment
+                # it's offset by the page size.
+                offset = cursor.offset + limit
+                position = next_position
+            else:
+                # The change in direction will introduce a paging artifact,
+                # where we end up skipping back a few extra items.
+                offset = 0
+                position = next_position
+
+        if not page:
+            position = previous_position
+
+        cursor = Cursor(offset=offset, reverse=True, position=position)
+        return self._encode_cursor(cursor, base_url)
+
+    def _get_position_from_instance(self, instance, ordering) -> str:
+        values: list[str] = []
+
+        for field in ordering:
+            name = field.lstrip("-")
+            value = (
+                instance[name]
+                if isinstance(instance, dict)
+                else getattr(instance, name)
+            )
+            values.append(str(value))
+
+        return "|".join(values)

oxutils/permissions/actions.py

@@ -0,0 +1,57 @@
+# actions.py
+
+READ = "r"
+WRITE = "w"
+DELETE = "d"
+UPDATE = "u"
+APPROVE = "a"
+
+ACTIONS = [READ, WRITE, DELETE, UPDATE, APPROVE]
+
+
+ACTION_HIERARCHY = {
+    "r": set(),            # read
+    "w": {"r"},            # write ⇒ read
+    "u": {"r"},            # update ⇒ read
+    "d": {"r", "w"},       # delete ⇒ write ⇒ read
+    "a": {"r"},            # approve ⇒ read
+}
+
+
+def collapse_actions(actions: list[str]) -> set[str]:
+    """
+    ['d','w','r'] -> {'d'}
+    ['w','r']     -> {'w'}
+    ['r']         -> {'r'}
+    """
+    actions = set(actions)
+    roots = set(actions)
+
+    # Remove all implied actions from roots
+    for action in list(roots):
+        if action in ACTION_HIERARCHY:
+            implied = ACTION_HIERARCHY[action]
+            roots -= implied
+
+    return roots
+
+
+def expand_actions(actions: list[str]) -> list[str]:
+    """
+    ['w']        -> ['w', 'r']
+    ['d']        -> ['d', 'w', 'r']
+    ['a', 'w']   -> ['a', 'w', 'r']
+    """
+    expanded = set(actions)
+
+    stack = list(actions)
+    while stack:
+        action = stack.pop()
+        implied = ACTION_HIERARCHY.get(action, set())
+
+        for a in implied:
+            if a not in expanded:
+                expanded.add(a)
+                stack.append(a)
+
+    return sorted(expanded)

oxutils/permissions/admin.py

@@ -0,0 +1,3 @@
+from django.contrib import admin
+
+# Register your models here.

oxutils/permissions/apps.py

@@ -0,0 +1,10 @@
+from django.apps import AppConfig
+
+
+class PermissionsConfig(AppConfig):
+    default_auto_field = 'django.db.models.BigAutoField'
+    name = 'oxutils.permissions'
+    
+    def ready(self):
+        """Import checks when app is ready."""
+        from . import checks  # noqa

oxutils/permissions/caches.py

@@ -0,0 +1,19 @@
+from django.conf import settings
+
+
+
+CACHE_CHECK_PERMISSION = getattr(settings, 'CACHE_CHECK_PERMISSION', False)
+
+if CACHE_CHECK_PERMISSION:
+    from cacheops import cached_as
+    from .models import Grant
+    from .utils import check
+
+    @cached_as(Grant, timeout=60*5)
+    def cache_check(user, scope, actions, group = None, **context):
+        return check(user, scope, actions, group, **context)
+else:
+    from .utils import check
+
+    def cache_check(user, scope, actions, group = None, **context):
+        return check(user, scope, actions, group, **context)

oxutils/permissions/checks.py

@@ -0,0 +1,188 @@
+"""
+Django system checks for permissions configuration.
+
+Example configuration in settings.py:
+
+    ACCESS_MANAGER_SCOPE = "access"
+    ACCESS_MANAGER_GROUP = "manager"  # or None
+    ACCESS_MANAGER_CONTEXT = {}
+
+    CACHE_CHECK_PERMISSION = False
+    
+    ACCESS_SCOPES = [
+        "users",
+        "articles",
+        "comments"
+    ]
+    
+    PERMISSION_PRESET = {
+        "roles": [...],
+        "group": [...],
+        "role_grants": [...]
+    }
+"""
+
+from django.conf import settings
+from django.core.checks import Error, Warning, register, Tags
+
+
+@register(Tags.security)
+def check_permission_settings(app_configs, **kwargs):
+    """
+    Validate permission-related settings.
+    
+    Checks:
+    - ACCESS_MANAGER_SCOPE is defined
+    - ACCESS_MANAGER_GROUP is defined (can be None)
+    - ACCESS_MANAGER_CONTEXT is defined
+    - ACCESS_SCOPES is defined
+    - PERMISSION_PRESET is defined
+    - ACCESS_MANAGER_SCOPE exists in ACCESS_SCOPES
+    - ACCESS_MANAGER_GROUP exists in PERMISSION_PRESET groups (if not None)
+    """
+    errors = []
+    
+    # Check ACCESS_MANAGER_SCOPE
+    if not hasattr(settings, 'ACCESS_MANAGER_SCOPE'):
+        errors.append(
+            Error(
+                'ACCESS_MANAGER_SCOPE is not defined',
+                hint='Add ACCESS_MANAGER_SCOPE = "access" to your settings',
+                id='permissions.E001',
+            )
+        )
+    
+    # Check ACCESS_MANAGER_GROUP
+    if not hasattr(settings, 'ACCESS_MANAGER_GROUP'):
+        errors.append(
+            Error(
+                'ACCESS_MANAGER_GROUP is not defined',
+                hint='Add ACCESS_MANAGER_GROUP = "manager" or None to your settings',
+                id='permissions.E002',
+            )
+        )
+    
+    # Check ACCESS_MANAGER_CONTEXT
+    if not hasattr(settings, 'ACCESS_MANAGER_CONTEXT'):
+        errors.append(
+            Error(
+                'ACCESS_MANAGER_CONTEXT is not defined',
+                hint='Add ACCESS_MANAGER_CONTEXT = {} to your settings',
+                id='permissions.E003',
+            )
+        )
+    
+    # Check ACCESS_SCOPES
+    if not hasattr(settings, 'ACCESS_SCOPES'):
+        errors.append(
+            Error(
+                'ACCESS_SCOPES is not defined',
+                hint='Add ACCESS_SCOPES = ["users", "articles", ...] to your settings',
+                id='permissions.E004',
+            )
+        )
+    else:
+        # Validate ACCESS_SCOPES is a list
+        if not isinstance(settings.ACCESS_SCOPES, list):
+            errors.append(
+                Error(
+                    'ACCESS_SCOPES must be a list',
+                    hint='Set ACCESS_SCOPES = ["users", "articles", ...]',
+                    id='permissions.E005',
+                )
+            )
+    
+    # Check PERMISSION_PRESET
+    if not hasattr(settings, 'PERMISSION_PRESET'):
+        errors.append(
+            Warning(
+                'PERMISSION_PRESET is not defined',
+                hint='Add PERMISSION_PRESET dict to your settings or use load_permission_preset',
+                id='permissions.W001',
+            )
+        )
+    else:
+        # Validate PERMISSION_PRESET structure
+        preset = settings.PERMISSION_PRESET
+        if not isinstance(preset, dict):
+            errors.append(
+                Error(
+                    'PERMISSION_PRESET must be a dictionary',
+                    id='permissions.E006',
+                )
+            )
+        else:
+            # Check required keys
+            required_keys = ['roles', 'group', 'role_grants']
+            for key in required_keys:
+                if key not in preset:
+                    errors.append(
+                        Error(
+                            f'PERMISSION_PRESET is missing required key: {key}',
+                            hint=f'Add "{key}" key to PERMISSION_PRESET',
+                            id=f'permissions.E007',
+                        )
+                    )
+    
+    # Cross-validation: ACCESS_MANAGER_SCOPE in ACCESS_SCOPES
+    if (hasattr(settings, 'ACCESS_MANAGER_SCOPE') and 
+        hasattr(settings, 'ACCESS_SCOPES') and 
+        isinstance(settings.ACCESS_SCOPES, list)):
+        
+        if settings.ACCESS_MANAGER_SCOPE not in settings.ACCESS_SCOPES:
+            errors.append(
+                Error(
+                    f'ACCESS_MANAGER_SCOPE "{settings.ACCESS_MANAGER_SCOPE}" is not in ACCESS_SCOPES',
+                    hint=f'Add "{settings.ACCESS_MANAGER_SCOPE}" to ACCESS_SCOPES list',
+                    id='permissions.E008',
+                )
+            )
+    
+    # Cross-validation: ACCESS_MANAGER_GROUP in PERMISSION_PRESET groups
+    if (hasattr(settings, 'ACCESS_MANAGER_GROUP') and 
+        settings.ACCESS_MANAGER_GROUP is not None and
+        hasattr(settings, 'PERMISSION_PRESET') and
+        isinstance(settings.PERMISSION_PRESET, dict) and
+        'group' in settings.PERMISSION_PRESET):
+        
+        group_slugs = [g.get('slug') for g in settings.PERMISSION_PRESET.get('group', [])]
+        
+        if settings.ACCESS_MANAGER_GROUP not in group_slugs:
+            errors.append(
+                Error(
+                    f'ACCESS_MANAGER_GROUP "{settings.ACCESS_MANAGER_GROUP}" is not in PERMISSION_PRESET groups',
+                    hint=f'Add a group with slug "{settings.ACCESS_MANAGER_GROUP}" to PERMISSION_PRESET["group"]',
+                    id='permissions.E009',
+                )
+            )
+    
+    # Validate ACCESS_MANAGER_CONTEXT is a dict
+    if hasattr(settings, 'ACCESS_MANAGER_CONTEXT'):
+        if not isinstance(settings.ACCESS_MANAGER_CONTEXT, dict):
+            errors.append(
+                Error(
+                    'ACCESS_MANAGER_CONTEXT must be a dictionary',
+                    hint='Set ACCESS_MANAGER_CONTEXT = {}',
+                    id='permissions.E010',
+                )
+            )
+    
+    # Check CACHE_CHECK_PERMISSION and cacheops dependency
+    if hasattr(settings, 'CACHE_CHECK_PERMISSION') and settings.CACHE_CHECK_PERMISSION:
+        if not hasattr(settings, 'INSTALLED_APPS'):
+            errors.append(
+                Error(
+                    'INSTALLED_APPS is not defined',
+                    id='permissions.E011',
+                )
+            )
+        elif 'cacheops' not in settings.INSTALLED_APPS:
+            errors.append(
+                Error(
+                    'CACHE_CHECK_PERMISSION is True but cacheops is not in INSTALLED_APPS',
+                    hint='Add "cacheops" to INSTALLED_APPS or set CACHE_CHECK_PERMISSION = False',
+                    id='permissions.E012',
+                )
+            )
+    
+    return errors