drf-parcel 0.1.0__py3-none-any.whl

drf_parcel/apps.py

@@ -0,0 +1,15 @@
+from django.apps import AppConfig
+from django.core import checks
+from django.utils.translation import gettext_lazy as _
+
+
+class DrfParcelConfig(AppConfig):
+    """Installed so Django finds the library's catalogue and runs its checks."""
+
+    name = 'drf_parcel'
+    verbose_name = _('Response envelope')
+
+    def ready(self) -> None:
+        from drf_parcel.checks import check_settings
+
+        checks.register(check_settings)

drf_parcel/checks.py

@@ -0,0 +1,167 @@
+"""
+What is wrong with the ``DRF_PARCEL`` setting, said when the project starts.
+
+A setting that would only fail on the first request that reads it fails
+instead on ``manage.py check`` and ``runserver`` - before a client finds it.
+"""
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from django.apps import AppConfig
+from django.core.checks import CheckMessage, Error
+from django.core.exceptions import ImproperlyConfigured
+from django.utils.module_loading import import_string
+
+from drf_parcel import conf
+from drf_parcel.handlers import STANDARD_CODES
+
+
+def check_settings(
+    app_configs: Sequence[AppConfig] | None = None, **kwargs: Any
+) -> list[CheckMessage]:
+    """Every problem with the setting, each with what to do about it."""
+    try:
+        conf.raw()
+        conf.messages()
+    except ImproperlyConfigured as refused:
+        return [Error(str(refused), id='drf_parcel.E001')]
+
+    return _page_size_problems() + _error_problems()
+
+
+def _page_size_problems() -> list[CheckMessage]:
+    problems: list[CheckMessage] = []
+    page_size = conf.page_size()
+    ceiling = conf.get('MAX_PAGE_SIZE')
+
+    # The page size may be DRF's own PAGE_SIZE, so it is named by what it is.
+    for name, value in (
+        ('The page size', page_size),
+        ("DRF_PARCEL['MAX_PAGE_SIZE']", ceiling),
+    ):
+        if not _is_positive_whole_number(value):
+            problems.append(
+                Error(
+                    f'{name} must be a whole number above zero, not {value!r}.',
+                    hint="It is DRF_PARCEL['PAGE_SIZE'], else REST_FRAMEWORK['PAGE_SIZE'].",
+                    id='drf_parcel.E002',
+                )
+            )
+
+    if not problems and ceiling < page_size:  # type: ignore[operator]
+        problems.append(
+            Error(
+                f"DRF_PARCEL['MAX_PAGE_SIZE'] ({ceiling}) is below the page size ({page_size}).",
+                hint='The ceiling on a size the client chooses cannot be below the default size.',
+                id='drf_parcel.E003',
+            )
+        )
+
+    if not isinstance(conf.get('CLIENT_PAGE_SIZE'), bool):
+        problems.append(
+            Error("DRF_PARCEL['CLIENT_PAGE_SIZE'] must be True or False.", id='drf_parcel.E004')
+        )
+
+    param = conf.get('PAGE_SIZE_QUERY_PARAM')
+
+    if not isinstance(param, str) or not param:
+        problems.append(
+            Error(
+                "DRF_PARCEL['PAGE_SIZE_QUERY_PARAM'] must be the name of a query parameter.",
+                id='drf_parcel.E005',
+            )
+        )
+
+    return problems
+
+
+def _error_problems() -> list[CheckMessage]:
+    problems: list[CheckMessage] = []
+
+    if conf.get('FIELD_ERRORS') not in ('detailed', 'messages'):
+        problems.append(
+            Error(
+                "DRF_PARCEL['FIELD_ERRORS'] must be 'detailed' or 'messages'.",
+                id='drf_parcel.E006',
+            )
+        )
+
+    separator = conf.get('FIELD_PATH_SEPARATOR')
+
+    if not isinstance(separator, str) or not separator:
+        problems.append(
+            Error(
+                "DRF_PARCEL['FIELD_PATH_SEPARATOR'] must be a character or more.",
+                id='drf_parcel.E007',
+            )
+        )
+
+    problems.extend(_error_code_problems())
+
+    for name in ('HANDLE_INTEGRITY_ERRORS', 'RAISE_UNHANDLED_IN_DEBUG'):
+        if not isinstance(conf.get(name), bool):
+            problems.append(
+                Error(f"DRF_PARCEL['{name}'] must be True or False.", id='drf_parcel.E009')
+            )
+
+    problems.extend(_reporter_problems())
+    return problems
+
+
+def _error_code_problems() -> list[CheckMessage]:
+    renamed = conf.get('ERROR_CODES')
+
+    if not isinstance(renamed, Mapping):
+        return [Error("DRF_PARCEL['ERROR_CODES'] must be a dictionary.", id='drf_parcel.E008')]
+
+    problems: list[CheckMessage] = []
+    unknown = sorted(set(renamed) - set(STANDARD_CODES))
+
+    if unknown:
+        problems.append(
+            Error(
+                f"DRF_PARCEL['ERROR_CODES'] renames codes the library does not send: "
+                f'{", ".join(unknown)}.',
+                hint=f'It sends {", ".join(STANDARD_CODES)}.',
+                id='drf_parcel.E008',
+            )
+        )
+
+    if not all(isinstance(new, str) and new for new in renamed.values()):
+        problems.append(
+            Error(
+                "Every new name in DRF_PARCEL['ERROR_CODES'] must be a word.",
+                id='drf_parcel.E008',
+            )
+        )
+
+    return problems
+
+
+def _reporter_problems() -> list[CheckMessage]:
+    path = conf.get('REPORTER')
+
+    if path is None:
+        return []
+
+    try:
+        reporter = import_string(path) if isinstance(path, str) else None
+    except ImportError:
+        reporter = None
+
+    if not callable(reporter):
+        return [
+            Error(
+                f"DRF_PARCEL['REPORTER'] must be the dotted path to a function, not {path!r}.",
+                hint='It is called with each unexpected exception and its context.',
+                id='drf_parcel.E010',
+            )
+        ]
+
+    return []
+
+
+def _is_positive_whole_number(value: object) -> bool:
+    # True is an int to Python, and is no page size.
+    return isinstance(value, int) and not isinstance(value, bool) and value > 0

drf_parcel/conf.py

@@ -0,0 +1,106 @@
+"""
+The ``DRF_PARCEL`` setting, read and checked.
+
+Every key lives in one dictionary in the project's settings, and the default
+needs none of them::
+
+    DRF_PARCEL = {
+        'PAGE_SIZE': 20,
+        'MESSAGES': {'created': _('Saved successfully.')},
+    }
+
+A key the library does not know is refused rather than ignored: a misspelt
+``PAGE_SZIE`` that is silently ignored is a page size that never changes, and
+nobody can tell why.
+
+The setting is read on every use rather than once, so a test that overrides
+it - and a project that changes it - is answered by what it says now.
+"""
+
+from collections.abc import Mapping
+from types import MappingProxyType
+from typing import Final
+
+from django.conf import settings
+from django.core.exceptions import ImproperlyConfigured
+from rest_framework.settings import api_settings
+
+#: Every key the setting may hold, and what it is when left out.
+DEFAULTS: Final[Mapping[str, object]] = MappingProxyType(
+    {
+        'PAGE_SIZE': 20,
+        'MAX_PAGE_SIZE': 100,
+        'CLIENT_PAGE_SIZE': False,
+        'PAGE_SIZE_QUERY_PARAM': 'page_size',
+        'FIELD_ERRORS': 'detailed',
+        'FIELD_PATH_SEPARATOR': '.',
+        'ERROR_CODES': MappingProxyType({}),
+        'HANDLE_INTEGRITY_ERRORS': False,
+        'RAISE_UNHANDLED_IN_DEBUG': True,
+        'REPORTER': None,
+        'MESSAGES': MappingProxyType({}),
+    }
+)
+
+#: The default success messages a project may replace, by key.
+MESSAGE_KEYS: Final = ('created', 'saved', 'deleted', 'done')
+
+
+def raw() -> Mapping[str, object]:
+    """The setting as written, refused when it is not a dictionary of known keys."""
+    written = getattr(settings, 'DRF_PARCEL', {})
+
+    if not isinstance(written, Mapping):
+        raise ImproperlyConfigured('DRF_PARCEL must be a dictionary.')
+
+    unknown = sorted(set(written) - set(DEFAULTS))
+
+    if unknown:
+        raise ImproperlyConfigured(
+            f'DRF_PARCEL has keys the library does not know: {", ".join(unknown)}. '
+            f'It knows {", ".join(DEFAULTS)}.'
+        )
+
+    return written
+
+
+def get(key: str) -> object:
+    """One key of the setting, or its default when the project left it out."""
+    return raw().get(key, DEFAULTS[key])
+
+
+def page_size() -> object:
+    """
+    The page size when a view names none.
+
+    ``DRF_PARCEL['PAGE_SIZE']`` when the project wrote it; else DRF's own
+    ``PAGE_SIZE``, so a project that already set it there keeps its size when
+    it adopts the library; else the library's default.
+    """
+    written = raw()
+
+    if 'PAGE_SIZE' in written:
+        return written['PAGE_SIZE']
+
+    if api_settings.PAGE_SIZE is not None:
+        return api_settings.PAGE_SIZE
+
+    return DEFAULTS['PAGE_SIZE']
+
+
+def messages() -> Mapping[str, object]:
+    """The project's replacements for the default success messages, by key."""
+    replaced = get('MESSAGES')
+
+    if not isinstance(replaced, Mapping):
+        raise ImproperlyConfigured("DRF_PARCEL['MESSAGES'] must be a dictionary.")
+
+    unknown = sorted(set(replaced) - set(MESSAGE_KEYS))
+
+    if unknown:
+        raise ImproperlyConfigured(
+            f"DRF_PARCEL['MESSAGES'] has keys the library does not know: {', '.join(unknown)}. "
+            f'It knows {", ".join(MESSAGE_KEYS)}.'
+        )
+
+    return replaced

drf_parcel/envelope.py

@@ -0,0 +1,99 @@
+"""
+The envelope - the one place its shape is assembled.
+
+Every answer has the same top level, success and failure alike::
+
+    {"success": true,  "status_code": 200, "message": "...", "data": {}}
+    {"success": true,  "status_code": 200, "message": "...", "data": [], "pagination": {}}
+    {"success": false, "status_code": 409, "message": "...", "data": {}, "error_code": "..."}
+
+Two places building the envelope become two shapes, so nothing else in the
+library writes these keys.
+"""
+
+from collections.abc import Mapping
+from typing import Any
+
+#: The keys every envelope carries, whatever it answers.
+KEYS = ('success', 'status_code', 'message', 'data')
+
+
+def build_envelope(
+    *,
+    success: bool,
+    status_code: int,
+    message: object,
+    data: Any = None,
+    pagination: Mapping[str, Any] | None = None,
+    error_code: str | None = None,
+) -> dict[str, Any]:
+    """
+    The envelope, from its parts.
+
+    ``message`` may be a lazy translation: it becomes text here, under the
+    language active when the answer is built. ``data`` that says nothing is
+    ``{}``, never ``null``.
+
+    A key is either always there or there for a reason, so a failure must
+    name its ``error_code`` and a success must not, and only a success is a
+    page.
+    """
+    if success and error_code is not None:
+        raise ValueError('A success carries no error_code.')
+
+    if not success and not error_code:
+        raise ValueError('A failure must name its error_code.')
+
+    if not success and pagination is not None:
+        raise ValueError('A failure is not a page.')
+
+    envelope: dict[str, Any] = {
+        'success': success,
+        'status_code': status_code,
+        'message': str(message),
+        'data': {} if data is None else data,
+    }
+
+    if pagination is not None:
+        envelope['pagination'] = dict(pagination)
+
+    if error_code is not None:
+        envelope['error_code'] = error_code
+
+    return envelope
+
+
+def envelope_schema(
+    data: Mapping[str, Any],
+    *,
+    pagination: Mapping[str, Any] | None = None,
+    error: bool = False,
+) -> dict[str, Any]:
+    """
+    The OpenAPI schema of an envelope around ``data`` - the shape above, as a schema.
+
+    Kept beside ``build_envelope`` so that the shape and its description
+    change together.
+    """
+    properties: dict[str, Any] = {
+        # Not an enum: drf-spectacular would lift each into a component of its own.
+        'success': {
+            'type': 'boolean',
+            'example': not error,
+            'description': 'Always false on a failure.' if error else 'Always true on a success.',
+        },
+        'status_code': {'type': 'integer'},
+        'message': {'type': 'string'},
+        'data': dict(data),
+    }
+    required = list(KEYS)
+
+    if pagination is not None:
+        properties['pagination'] = dict(pagination)
+        required.append('pagination')
+
+    if error:
+        properties['error_code'] = {'type': 'string'}
+        required.append('error_code')
+
+    return {'type': 'object', 'properties': properties, 'required': required}

drf_parcel/exceptions.py

@@ -0,0 +1,109 @@
+"""
+A project's own errors, and the common ones the library ships.
+
+A ``DomainError`` is DRF's ``APIException`` with one thing added: ``data``,
+what a client can act on - which record is in the way, how long to wait::
+
+    class ProvinceInUse(DomainError):
+        status_code = 409
+        default_code = 'province_in_use'
+        default_detail = _('This province has branches and cannot be deleted.')
+
+    raise ProvinceInUse(data={'branches': 3})
+
+Its names are DRF's own: ``default_code`` is sent as ``error_code``,
+``default_detail`` as ``message``. Being an ``APIException``, it answers
+sensibly under DRF's own handler too, and a Celery task or a management
+command catches it like any other exception.
+
+Where DRF has an exception of the same meaning, the library's is also that
+exception - ``NotFoundError`` is a ``NotFound`` - so code that catches DRF's,
+and DRF's own handling of it, keep working.
+"""
+
+from collections.abc import Mapping
+from typing import Any
+
+from django.utils.translation import gettext_lazy as _
+from rest_framework import exceptions, status
+
+
+class DomainError(exceptions.APIException):
+    """A rule of the project was broken, said in the envelope with ``data`` beside it."""
+
+    status_code: int = status.HTTP_400_BAD_REQUEST
+    default_code = 'error'
+    default_detail = _('The request could not be completed.')
+
+    def __init__(
+        self,
+        detail: Any = None,
+        code: str | None = None,
+        *,
+        data: Mapping[str, Any] | None = None,
+    ) -> None:
+        super().__init__(detail, code)
+        #: What a client can act on. Never what a person must not read elsewhere.
+        self.data: dict[str, Any] = dict(data or {})
+
+
+class InvalidInputError(DomainError):
+    """What was sent cannot be used - said by a service, where no serializer is."""
+
+    default_code = 'validation_error'
+    default_detail = _('Some of the information provided is not valid.')
+
+
+class InvalidCursorError(DomainError):
+    """A cursor the server cannot read: the client sent back something it was never given."""
+
+    default_code = 'invalid_cursor'
+    default_detail = _('The cursor is not valid.')
+
+
+class AuthenticationFailedError(DomainError, exceptions.AuthenticationFailed):
+    """The credentials sent are wrong, or no longer good."""
+
+    status_code = status.HTTP_401_UNAUTHORIZED
+    default_code = 'authentication_failed'
+    default_detail = _('Sign in again to continue.')
+
+
+class PermissionDeniedError(DomainError, exceptions.PermissionDenied):
+    """The caller is known, and may not do this."""
+
+    status_code = status.HTTP_403_FORBIDDEN
+    default_code = 'permission_denied'
+    default_detail = _('You do not have permission to do this.')
+
+
+class NotFoundError(DomainError, exceptions.NotFound):
+    """The record does not exist - or does not exist for this caller."""
+
+    status_code = status.HTTP_404_NOT_FOUND
+    default_code = 'not_found'
+    default_detail = _('It was not found.')
+
+
+class ConflictError(DomainError):
+    """The request is right, and the state of things refuses it."""
+
+    status_code = status.HTTP_409_CONFLICT
+    default_code = 'conflict'
+    default_detail = _('This conflicts with a change made in the meantime.')
+
+
+class RateLimitedError(DomainError):
+    """Too many attempts, too quickly. Put ``retry_after`` in ``data`` when it is known."""
+
+    status_code = status.HTTP_429_TOO_MANY_REQUESTS
+    default_code = 'rate_limited'
+    default_detail = _('Too many attempts. Please wait and try again.')
+
+
+class ServiceUnavailableError(DomainError):
+    """Something the server depends on is not answering."""
+
+    status_code = status.HTTP_503_SERVICE_UNAVAILABLE
+    default_code = 'service_unavailable'
+    default_detail = _('This service is not available right now. Please try again later.')