wbcore 1.59.9__py2.py3-none-any.whl

wbcore/dispatch.py

@@ -0,0 +1,56 @@
+from django.apps import apps
+
+from wbcore.utils.itertools import get_inheriting_subclasses
+
+
+def receiver_all_subclasses(signal, sender, *args, **kwargs):
+    def _decorator(func):
+        signal.connect(func, *args, sender=sender, dispatch_uid=func.__name__ + "_" + sender.__name__, **kwargs)
+        for subclass in sender.__subclasses__():
+            signal.connect(
+                func, *args, sender=subclass, dispatch_uid=func.__name__ + "_" + subclass.__name__, **kwargs
+            )
+
+        return func
+
+    return _decorator
+
+
+def receiver_subclasses(signal, sender, *args, only_leaf=True, **kwargs):
+    """
+    A decorator for connecting receivers and all receiver's subclasses to signals. Used by passing in the
+    signal and keyword arguments to connect::
+    The signal needs to be registered after all child models are registered (e.g. by placing the signal in a dedicated
+    signal file)
+        @receiver_subclasses(post_save, sender=MyModel)
+        def signal_receiver(sender, **kwargs):
+            ...
+    """
+
+    def _decorator(func):
+        if isinstance(sender, str):
+            sender_class = apps.get_model(sender)
+        else:
+            sender_class = sender
+        for snd in get_inheriting_subclasses(sender_class, only_leaf=only_leaf):
+            signal.connect(func, *args, sender=snd, dispatch_uid=func.__name__ + "_" + snd.__name__, **kwargs)
+        return func
+
+    return _decorator
+
+
+def receiver_inherited_through_models(signal, sender, through_field_name, **kwargs):
+    """
+    A decorator for connecting receivers and all subclasses's through model'.
+    """
+
+    def _decorator(func):
+        for sub_class in sender.__subclasses__():
+            if (through_field := getattr(sub_class, through_field_name, None)) and (
+                through_class := getattr(through_field, "through", None)
+            ):
+                signal.connect(
+                    func, sender=through_class, dispatch_uid=func.__name__ + "_" + through_class.__name__, **kwargs
+                )
+
+    return _decorator

wbcore/docs/__init__.py

@@ -0,0 +1,23 @@
+import markdown
+from django.conf import settings
+from rest_framework.response import Response
+
+
+def get_markdown_docs(docs):
+    try:
+        with open(docs, "r") as f:
+            return Response(
+                markdown.markdown(
+                    f.read(),
+                    extensions=settings.WBCORE_DEFAULT_MARKDOWN_EXTENSIONS,
+                )
+            )
+    except FileNotFoundError:
+        return Response(
+            markdown.markdown(
+                docs,
+                extensions=settings.WBCORE_DEFAULT_MARKDOWN_EXTENSIONS,
+            )
+        )
+    except AttributeError:
+        return Response({"errors": "No documentation available."})

wbcore/docs/orderable.md

@@ -0,0 +1,29 @@
+# Orderable View
+
+An orderable view enables the user to freely reorder rows inside AG Grid by drag-and-drop.
+
+**NOTE**: As these changes are saved in a model field, this will change the order globally for each user! Reordering on a per-user basis requires a way more sophisticated approach that is currently out of scope. Please also keep in mind that this also means that different orders for different views of the same model are not possible.
+
+## Implementation Steps
+
+### Simple Reordering
+
+Reorder rows inside a basic list view. Also includes the first level of tree views (level 0).
+
+1. Add the `OrderableModel` from `wbcore.models.orderable` to your model and migrate. Set initial values for existing instances by either `Model.orderable_objects.reset_order()` or calling `save()` on every object.
+2. Add the `order` field to your serializer.
+3. Add the `OrderableMixin` from `wbcore.viewsets.mixins` to your viewset. If you have defined a viewset ordering, make sure to first order by `order`.
+4. Add both `reorderable_column="order"` and `reorderable_endpoint=reverse(f"{endpoint.basename}-reorder", args=["{{id}}"], request=self.request)` to your list display.
+
+### Tree Child Reordering
+
+We currently only support reordering the first child row (i.e. level 1).
+
+1. Add the `OrderableModel` from `wbcore.models.orderable` to your model and migrate. Also add the class variable `PARTITION_BY` to your class and set it to the name of the foreign key field to the child's parent to partition the order values based on the parent. In this case the order number is unique only for the parent and not over the entire model anymore. Set initial values for existing instances by either `Model.orderable_objects.reset_order()` or calling `save()` on every object.
+2. Add the `order` field to your serializer.
+3. Add the `OrderableMixin` from `wbcore.viewsets.mixins` to your viewset. If you have defined a viewset ordering, make sure to first order by `order`.
+4. Add both `tree_reorderable_column="order"` and `tree_reorderable_endpoint=reverse(f"{endpoint.basename}-reorder", args=["{{id}}"], request=self.request)` to **the parent's** list display.
+
+## Example
+
+For an example please take a look at _example_app/team_. In this case we wanted both level 0 (Team) and level 1 (Player) to be reorderable so this example incorporates both a simple reordering for the parent level and a tree child reordering for the child level.

wbcore/docs/reparent.md

@@ -0,0 +1,13 @@
+# Reparent View
+
+A reparent view enables the user to switch a child's parent object inside a tree view by drag-and-dropping the child inside the new parent. Please note that this is currently only supported with level 1 children inside the tree view.
+
+## Implementation Steps
+
+1. Add a `PARENT_FK` class variable to the child's model and set it to the field name of the foreign key to the parent.
+2. Add the `ReparentMixin` from `wbcore.viewsets.mixins` to your viewset.
+3. Add both `tree_reparent_pk_field=f"{pk_field_name}"` and `tree_reparent_endpoint=reverse(f"{endpoint.basename}-reparent", args=["{{id}}"], request=self.request)` to the parent's list display.
+
+## Example
+
+For an example please take a look at _example_app/team_. Drag-and-dropping a child (Player) inside a new parent (Team) will transfer this player to a new team.

wbcore/dynamic_preferences_registry.py

@@ -0,0 +1,131 @@
+from django.utils.translation import gettext as _
+from dynamic_preferences.preferences import Section
+from dynamic_preferences.registries import global_preferences_registry
+from dynamic_preferences.types import IntegerPreference, StringPreference
+from dynamic_preferences.users.registries import user_preferences_registry
+
+from wbcore.contrib.dynamic_preferences.types import ChoicePreference, LanguageChoicePreference
+from wbcore.utils.date import get_timezone_choices
+
+wbcore = Section("wbcore")
+
+
+@global_preferences_registry.register
+class RetentionPeriod(IntegerPreference):
+    section = wbcore
+    name = "retention_period"
+    default = 365
+
+    verbose_name = _("Retention Period in Days")
+    help_text = _(
+        "When an object cannot be deleted and is disabled instead, it gets hidden from the queryset but not deleted. For compliance reasons we enable the retention for a specific period of days (defaults to a year)"
+    )
+
+
+@global_preferences_registry.register
+class SystemUserEmailPeriod(StringPreference):
+    section = wbcore
+    name = "system_user_email"
+
+    default = "system@stainly-bench.com"
+
+    verbose_name = _("System User Email")
+    help_text = _("System User Email")
+
+
+@user_preferences_registry.register
+class LanguagePreference(LanguageChoicePreference):
+    weight = -1
+    choices = [
+        ("de", "Deutsch"),
+        ("fr", "Français"),
+        ("en", "English"),
+    ]
+
+    section = wbcore
+    name = "language"
+    default = "en"
+
+    verbose_name = _("System Language")
+    help_text = _("Select the language you want the Workbench to display.")
+
+
+@user_preferences_registry.register
+class TimezonePreference(ChoicePreference):
+    weight = 0
+    # Value is a IANA timezone name
+    choices = get_timezone_choices()
+    section = wbcore
+    name = "timezone"
+    default = "Europe/Berlin"
+
+    verbose_name = _("Timezone")
+    help_text = _("Pick the timezone in which you want the workbench's dates to be displayed in.")
+
+
+@user_preferences_registry.register
+class DateFormatPreference(ChoicePreference):
+    weight = 1
+    choices = [
+        ("DD.MM.YYYY", "13.04.2007"),
+        ("DD/MM/YYYY", "13/04/2007"),
+        ("DD-MM-YYYY", "13-04-2007"),
+        ("MM/DD/YYYY", "04/13/2007"),
+        ("MM-DD-YYYY", "04-13-2007"),
+        ("YYYY/MM/DD", "2007/04/13"),
+        ("YYYY-MM-DD", "2007-04-13"),
+        ("MMM DD, YYYY", "April 13, 2007"),
+        ("DD MMM YYYY", "13 April 2007"),
+        ("dddd, DD MMM YYYY", "Friday, 13 April 2007"),
+        ("ddd, DD MMM YYYY", "Fri, 13 April 2007"),
+        ("ddd Do MMMM YYYY", "Fri 13th April 2007"),
+    ]
+
+    section = wbcore
+    name = "date_format"
+    default = "YYYY-MM-DD"
+
+    verbose_name = _("Date Format")
+    help_text = _("Choose how you want dates to appear throughout the Workbench.")
+
+
+@user_preferences_registry.register
+class TimeFormatPreference(ChoicePreference):
+    weight = 2
+    choices = [
+        ("HH:mm", "14:05"),
+        ("hh:mm", "02:05"),
+        ("h:mm", "2:05"),
+        ("HH [h] mm", "14 h 05"),
+        ("HH[h]mm", "14h05"),
+        ("h:mm A", "2:05 PM"),
+        ("h:mm a", "2:05 pm"),
+        ("hh:mm A", "02:05 PM"),
+        ("hh:mm a", "02:05 pm"),
+    ]
+
+    section = wbcore
+    name = "time_format"
+    default = "HH:mm"
+
+    verbose_name = _("Time Format")
+    help_text = _("Choose how you want times to appear throughout the Workbench.")
+
+
+@user_preferences_registry.register
+class NumberFormatPreference(ChoicePreference):
+    weight = 3
+    # Value is a BCP 47 region subtag
+    choices = [
+        ("US", "1,234,567.89"),
+        ("FR", "1\u202f234\u202f567,89"),
+        ("DE", "1.234.567,89"),
+        ("CH", "1’234’567.89"),
+    ]
+
+    section = wbcore
+    name = "number_format"
+    default = "US"
+
+    verbose_name = _("Number Format")
+    help_text = _("Choose how you want numbers to appear throughout the Workbench.")

wbcore/enums.py

@@ -0,0 +1,50 @@
+from enum import Enum
+from typing import Union
+
+
+class RequestType(Enum):
+    GET = "get"
+    POST = "post"
+    DELETE = "delete"
+    PATCH = "patch"
+    PUT = "put"
+    OPTIONS = "options"
+    HEAD = "head"
+
+
+class WidgetType(Enum):
+    LIST = "list"
+    INSTANCE = "instance"
+    CHART = "chart"
+    SELECT = "select"
+    HTML = "html"
+
+
+class Operator(Enum):
+    EQUAL = "=="
+    UNEQUAL = "!="
+    GREATER = ">"
+    GREATER_EQUAL = ">="
+    LESS = "<"
+    LESS_EQUAL = "<="
+    EXISTS = "∃"
+
+
+class Unit(Enum):
+    FRACTION = "fr"
+    REM = "rem"
+    PIXEL = "px"
+
+    def __call__(self, _value):
+        return (float(_value), self.value)
+
+    def unit(self, _value: Union[float, str, int]):
+        if not isinstance(_value, (float, str, int)):
+            raise AssertionError("_value needs to be one of str, float or int")
+
+        return f"{float(_value)}{self.value}"
+
+
+class AuthType(Enum):
+    NONE = "NONE"
+    JWT = "JWT"

wbcore/filters/__init__.py

@@ -0,0 +1,21 @@
+from .backends import DjangoFilterBackend
+from .fields import (
+    BooleanFilter,
+    CharFilter,
+    ChoiceFilter,
+    DateFilter,
+    DateRangeFilter,
+    FinancialPerformanceDateRangeFilter,
+    DateTimeFilter,
+    DateTimeRangeFilter,
+    ModelChoiceFilter,
+    ModelMultipleChoiceFilter,
+    MultipleChoiceContentTypeFilter,
+    MultipleChoiceFilter,
+    NumberFilter,
+    YearFilter,
+    RangeSelectFilter,
+    TimeFilter,
+    MultipleLookupFilter,
+)
+from .filterset import FilterSet

wbcore/filters/backends.py

@@ -0,0 +1,19 @@
+from django_filters.rest_framework import DjangoFilterBackend as StandardFilterBackend
+
+from .filterset import FilterSet
+
+
+class DjangoFilterBackend(StandardFilterBackend):
+    filterset_base = FilterSet
+
+    def get_filterset_kwargs(self, request, queryset, view):
+        return {"data": request.query_params, "queryset": queryset, "request": request, "view": view}
+
+    def get_filterset_class(self, view, queryset=None):
+        if method := getattr(view, "get_filterset_class", None):
+            view.filterset_class = method(view.request)
+
+        if method := getattr(view, "get_filterset_fields", None):
+            view.filterset_fields = method(view.request)
+
+        return super().get_filterset_class(view, queryset)

wbcore/filters/defaults.py

@@ -0,0 +1,70 @@
+from calendar import monthrange
+from datetime import date, timedelta
+
+from django.utils.timezone import localdate
+from psycopg.types.range import DateRange
+from rest_framework.exceptions import APIException
+
+from wbcore.utils.date import get_end_date_from_date, get_start_date_from_date
+
+
+def current_quarter_date_start(*args, **kwargs):
+    return get_start_date_from_date(localdate())
+
+
+def current_quarter_date_end(*args, **kwargs):
+    return get_end_date_from_date(localdate())
+
+
+def current_quarter_date_range(*args, **kwargs):
+    return DateRange(current_quarter_date_start(*args, **kwargs), current_quarter_date_end(*args, **kwargs))
+
+
+def current_month_date_start(*args, **kwargs):
+    today = date.today()
+    return date(today.year, today.month, 1)
+
+
+def current_month_date_end(*args, **kwargs):
+    today = date.today()
+    return date(today.year, today.month, monthrange(today.year, today.month)[1])
+
+
+def current_month_date_range(*args, **kwargs):
+    return DateRange(current_month_date_start(*args, **kwargs), current_month_date_end(*args, **kwargs))
+
+
+def current_year_date_range(*args, **kwargs):
+    d = localdate()
+    return DateRange(date(d.year, 1, 1), max((date(d.year + 1, 1, 1), d + timedelta(days=60))))
+
+
+def year_to_date_range(*args, **kwargs):
+    d = localdate()
+    return DateRange(d.replace(day=1, month=1), d.today())
+
+
+def n_year_data_range(n: int, *args, **kwargs):
+    d = localdate()
+    return DateRange(d - timedelta(days=n * 365), d)
+
+
+def one_year_date_range(*args, **kwargs):
+    return n_year_data_range(1)
+
+
+def five_year_data_range(*args, **kwargs):
+    return n_year_data_range(5)
+
+
+def current_quarter_date_interval(*args, **kwargs):
+    return (
+        current_quarter_date_start(),
+        current_quarter_date_end(*args, **kwargs),
+    )
+
+
+class RequiredFilterMissing(APIException):
+    status_code = 400
+    default_detail = "Required filters are not available in the query parameters."
+    default_code = "required_filters_missing"

wbcore/filters/fields/__init__.py

@@ -0,0 +1,15 @@
+from .choices import ChoiceFilter, MultipleChoiceField, MultipleChoiceFilter
+from .datetime import (
+    TimeFilter,
+    DateTimeFilter,
+    DateFilter,
+    DateRangeFilter,
+    DateTimeRangeFilter,
+    FinancialPerformanceDateRangeFilter,
+)
+from .models import ModelChoiceFilter, ModelMultipleChoiceFilter
+from .numbers import NumberFilter, YearFilter, RangeSelectFilter
+from .text import CharFilter
+from .booleans import BooleanFilter
+from .content_type import MultipleChoiceContentTypeFilter
+from .multiple_lookups import MultipleLookupFilter

wbcore/filters/fields/booleans.py

@@ -0,0 +1,7 @@
+import django_filters
+
+from wbcore.filters.mixins import WBCoreFilterMixin
+
+
+class BooleanFilter(WBCoreFilterMixin, django_filters.BooleanFilter):
+    filter_type = "boolean"

wbcore/filters/fields/choices.py

@@ -0,0 +1,60 @@
+import itertools
+from urllib.parse import quote
+
+import django_filters
+from django_filters.filters import MultipleChoiceField
+
+from wbcore.filters.mixins import WBCoreFilterMixin
+
+
+class WBCoreChoiceFilterMixin(WBCoreFilterMixin):
+    def __init__(self, *args, **kwargs):
+        self.choices = kwargs["choices"]
+        super().__init__(*args, **kwargs)
+
+    def get_representation(self, request, name, view):
+        representation, lookup_expr = super().get_representation(request, name, view)
+        lookup_expr["input_properties"]["choices"] = list()
+        if callable(self.choices):
+            choice_keys = [
+                choice[0] for choice in self.field.choices
+            ]  # we save the choices key for validation in case we narrow down the choices list in get_representation
+            # we get a new choices set but make sure its keys are still valid regarding the initial choices
+            choices = list(filter(lambda x: x[0] in choice_keys, self.choices(request, view)))
+        else:
+            choices = self.choices
+
+        for choice in choices:
+            lookup_expr["input_properties"]["choices"].append(
+                {"value": quote(choice[0]) if isinstance(choice[0], str) else choice[0], "label": choice[1]}
+            )
+        return representation, lookup_expr
+
+
+class ChoiceFilter(WBCoreChoiceFilterMixin, django_filters.ChoiceFilter):
+    filter_type = "select"
+
+
+class WBCoreMultipleChoiceField(MultipleChoiceField):
+    def to_python(self, value):
+        # We do this because DRF wrap a coma seperated list of choices into a one list element
+        if value and isinstance(value, list):
+            value = list(itertools.chain(*[v.split(",") for v in value]))
+        return super().to_python(value)
+
+
+class MultipleChoiceFilter(WBCoreChoiceFilterMixin, django_filters.MultipleChoiceFilter):
+    field_class = WBCoreMultipleChoiceField
+    filter_type = "select"
+
+    def _validate_initial_with_request(self, initial, request, name):
+        if request_initial := request.GET.get(name):
+            return request_initial.split(",")
+        return initial
+
+    def get_representation(self, request, name, view):
+        representation, lookup_expr = super().get_representation(request, name, view)
+        lookup_expr["input_properties"]["multiple"] = True
+        if (initial := lookup_expr["input_properties"].get("initial")) and not isinstance(initial, list):
+            lookup_expr["input_properties"]["initial"] = [initial]
+        return representation, lookup_expr

wbcore/filters/fields/content_type.py

@@ -0,0 +1,45 @@
+import json
+import operator
+from functools import reduce
+
+import django_filters
+from django.contrib.contenttypes.models import ContentType
+from django.db.models import Q
+from django_filters.constants import EMPTY_VALUES
+
+from wbcore.filters.mixins import WBCoreFilterMixin
+from wbcore.forms import ContentTypeMultiValueField
+
+
+class MultipleChoiceContentTypeFilter(WBCoreFilterMixin, django_filters.Filter):
+    field_class = ContentTypeMultiValueField
+    filter_type = "text"
+
+    def _validate_initial_with_request(self, initial, request, name):
+        initial = super()._validate_initial_with_request(initial, request, name)
+        if initial:
+            initial = json.dumps(initial)
+        return initial
+
+    def __init__(self, object_id_label="object_id", content_type_label="content_type", **kwargs):
+        self.object_id_label = object_id_label
+        self.content_type_label = content_type_label
+        super().__init__(**kwargs)
+
+    def filter(self, qs, value):
+        if value in EMPTY_VALUES:
+            return qs
+        conditions = [
+            (
+                Q(**{self.content_type_label: ContentType.objects.get_for_model(val)})
+                & Q(**{self.object_id_label: val.id})
+            )
+            for val in filter(None, value)
+        ]
+        if conditions:
+            qs = qs.filter(reduce(operator.or_, conditions))
+        else:
+            qs = qs.none()
+        if self.distinct:
+            qs = qs.distinct()
+        return qs

wbcore/filters/fields/datetime.py

@@ -0,0 +1,117 @@
+from contextlib import suppress
+
+import django_filters
+from django.contrib.postgres.fields import RangeField
+from django_filters.constants import EMPTY_VALUES
+from django_filters.utils import get_model_field
+
+from wbcore.filters.mixins import WBCoreFilterMixin
+from wbcore.forms import DateRangeField, DateTimeRangeField
+from wbcore.utils.date import financial_performance_shortcuts
+from wbcore.utils.date_builder.components import Component
+
+
+class TimeFilter(WBCoreFilterMixin, django_filters.TimeFilter):
+    filter_type = "time"
+
+
+class DateTimeFilter(WBCoreFilterMixin, django_filters.DateTimeFilter):
+    filter_type = "datetime"
+
+
+class DateFilter(WBCoreFilterMixin, django_filters.DateFilter):
+    filter_type = "date"
+
+
+class ShortcutAndPerformanceMixin(WBCoreFilterMixin):
+    def __init__(self, shortcuts: list | None = None, performance_mode: bool = False, *args, **kwargs):
+        self.shortcuts = shortcuts
+        self.performance_mode = performance_mode
+        super().__init__(*args, **kwargs)
+
+    def get_representation(self, request, name, view):
+        representation, lookup_expr = super().get_representation(request, name, view)
+        lookup_expr["input_properties"]["performance_mode"] = self.performance_mode
+
+        if self.shortcuts:
+            lookup_expr["input_properties"]["shortcuts"] = self.shortcuts
+
+        return representation, lookup_expr
+
+
+class DateRangeFilter(ShortcutAndPerformanceMixin, django_filters.Filter):
+    field_class = DateRangeField
+    filter_type = "daterange"
+    initial_format = "%Y-%m-%d"
+
+    def __init__(self, *args, **kwargs):
+        kwargs.setdefault("lookup_expr", "overlap")
+        super().__init__(*args, **kwargs)
+
+    @property
+    def is_range(self) -> bool:
+        if hasattr(self, "model"):
+            field = get_model_field(self.model, self.field_name)
+            return issubclass(field.__class__, RangeField)
+        return False
+
+    def _get_initial(self, *args):
+        initial = super()._get_initial(*args)
+        if initial is not None:
+            lower = upper = None
+            if isinstance(initial, tuple):
+                lower, upper = initial
+
+                # if the initial is a tuple of components, we need to convert them to string
+                if isinstance(lower, Component) and isinstance(upper, Component):
+                    return f"{lower},{upper}"
+
+            elif hasattr(initial, "lower") and hasattr(initial, "upper"):
+                lower, upper = initial.lower, initial.upper
+            initial = f'{lower.strftime(self.initial_format) if lower else ""},{upper.strftime(self.initial_format) if upper else ""}'
+        return initial
+
+    def get_representation(self, request, name, view):
+        representation, lookup_expr = super().get_representation(request, name, view)
+        representation["lookup_expr"] = {"exact": self.field_name}
+        with suppress(KeyError):  # TODO frontend needs to support both exact and overlaps lookup
+            initial = representation["initial"].pop(self.lookup_expr)
+            lookup_expr["input_properties"]["initial"]["exact"] = initial
+
+        return representation, lookup_expr
+
+    def filter(self, qs, value):
+        if value in EMPTY_VALUES:
+            return qs
+        if value:
+            lower, upper = value.lower, value.upper
+            filters = {}
+            is_field_range = self.is_range
+            if lower:
+                if is_field_range:
+                    filters[f"{self.field_name}__startswith__gte"] = lower
+                else:
+                    filters[f"{self.field_name}__gte"] = lower
+
+            if upper:
+                if is_field_range:
+                    filters[f"{self.field_name}__endswith__lte"] = upper
+                else:
+                    filters[f"{self.field_name}__lte"] = upper
+
+            if self.exclude:
+                qs = qs.exclude(**filters)
+            else:
+                qs = qs.filter(**filters)
+        return qs
+
+
+class FinancialPerformanceDateRangeFilter(DateRangeFilter):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, performance_mode=True, shortcuts=financial_performance_shortcuts, **kwargs)
+
+
+class DateTimeRangeFilter(DateRangeFilter):
+    field_class = DateTimeRangeField
+    initial_format = "%Y-%m-%dT%H:%M:%S%z"
+    filter_type = "datetimerange"