wbcore 1.59.9__py2.py3-none-any.whl

wbcore/contrib/geography/import_export/resources/geography.py

@@ -0,0 +1,11 @@
+from import_export.widgets import ForeignKeyWidget
+
+from wbcore.contrib.geography.models import Geography
+
+
+class CountryForeignKeyWidget(ForeignKeyWidget):
+    def __init__(self, field="code_3", use_natural_foreign_keys=False, **kwargs):
+        super().__init__(Geography, field=field)
+
+    def get_queryset(self, value, row, *args, **kwargs):
+        return Geography.countries.all()

wbcore/contrib/geography/migrations/0001_initial.py

@@ -0,0 +1,110 @@
+# Generated by Django 4.1.8 on 2023-04-06 06:43
+
+import django.contrib.postgres.fields
+import django.contrib.postgres.indexes
+import django.contrib.postgres.search
+import django.db.models.deletion
+import mptt.fields
+import timezone_field.fields
+from django.contrib.postgres.operations import BtreeGinExtension, TrigramExtension
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies = []
+
+    operations = [
+        TrigramExtension(),
+        BtreeGinExtension(),
+        migrations.CreateModel(
+            name="Geography",
+            fields=[
+                (
+                    "id",
+                    models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name="ID"),
+                ),
+                ("name", models.CharField(max_length=255)),
+                ("short_name", models.CharField(max_length=255)),
+                (
+                    "alternative_names",
+                    django.contrib.postgres.fields.ArrayField(
+                        base_field=models.CharField(max_length=255),
+                        blank=True,
+                        default=list,
+                        help_text="Alternative Names",
+                        size=None,
+                        verbose_name="Alternative Names",
+                    ),
+                ),
+                ("representation", models.CharField(blank=True, default="", max_length=255)),
+                ("search_vector", django.contrib.postgres.search.SearchVectorField(null=True)),
+                ("trigram_search_vector", models.CharField(blank=True, max_length=1024, null=True)),
+                (
+                    "code_2",
+                    models.CharField(
+                        blank=True, max_length=2, null=True, verbose_name="2 Character Alphanumeric Code"
+                    ),
+                ),
+                (
+                    "code_3",
+                    models.CharField(
+                        blank=True, max_length=3, null=True, verbose_name="3 Character Alphanumeric Code"
+                    ),
+                ),
+                ("code", models.CharField(blank=True, max_length=16, null=True, verbose_name="Code")),
+                ("population", models.PositiveIntegerField(blank=True, null=True)),
+                ("ranking", models.PositiveIntegerField(default=1)),
+                (
+                    "time_zone",
+                    timezone_field.fields.TimeZoneField(blank=True, choices_display="WITH_GMT_OFFSET", null=True),
+                ),
+                ("lft", models.PositiveIntegerField(editable=False)),
+                ("rght", models.PositiveIntegerField(editable=False)),
+                ("tree_id", models.PositiveIntegerField(db_index=True, editable=False)),
+                ("level", models.PositiveIntegerField(editable=False)),
+                (
+                    "parent",
+                    mptt.fields.TreeForeignKey(
+                        blank=True,
+                        null=True,
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="children",
+                        to="geography.geography",
+                    ),
+                ),
+            ],
+            options={
+                "verbose_name_plural": "Geographies",
+            },
+        ),
+        migrations.AddIndex(
+            model_name="geography",
+            index=django.contrib.postgres.indexes.GinIndex(fields=["search_vector"], name="geography_sv_gin_idx"),
+        ),
+        migrations.AddIndex(
+            model_name="geography",
+            index=django.contrib.postgres.indexes.GinIndex(
+                fields=["trigram_search_vector"],
+                name="geography_trigram_sv_gin_idx",
+                opclasses=["gin_trgm_ops"],
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="geography",
+            constraint=models.UniqueConstraint(
+                condition=models.Q(("level", 1)),
+                fields=("level", "code_2"),
+                name="geography_geography_level_code2__uniq",
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="geography",
+            constraint=models.UniqueConstraint(
+                condition=models.Q(("level", 1)),
+                fields=("level", "code_3"),
+                name="geography_geography_level_code3__uniq",
+            ),
+        ),
+    ]

wbcore/contrib/geography/migrations/0002_geography_geography_geography_tree_i739a.py

@@ -0,0 +1,17 @@
+# Generated by Django 5.2.9 on 2025-12-09 08:50
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('geography', '0001_initial'),
+    ]
+
+    operations = [
+        migrations.AddIndex(
+            model_name='geography',
+            index=models.Index(fields=['tree_id', 'lft'], name='geography_geography_tree_i739a'),
+        ),
+    ]

wbcore/contrib/geography/models.py

@@ -0,0 +1,150 @@
+from typing import Optional
+
+from django.contrib.postgres.fields import ArrayField
+from django.contrib.postgres.indexes import GinIndex
+from django.contrib.postgres.lookups import Unaccent
+from django.contrib.postgres.search import SearchVector, SearchVectorField
+from django.db import models
+from django.db.models.expressions import Value
+from django.db.models.functions import Lower
+from django.db.models.query import QuerySet
+from mptt.managers import TreeManager
+from mptt.models import MPTTModel, TreeForeignKey
+from text_unidecode import unidecode
+from timezone_field import TimeZoneField
+
+from wbcore.models import WBModel
+
+
+class LeveledGeographyManager(TreeManager):
+    def get_by_natural_key(self, code_2):
+        if self.level == 1:
+            return self.get(code_2=code_2)
+
+    def get_by_name(self, name, **extra_filter_args):
+        qs = self
+        if extra_filter_args:
+            qs = qs.filter(**extra_filter_args)
+        return (
+            qs.annotate(name_unaccent=Unaccent(Lower("name")))
+            .filter(models.Q(name_unaccent=unidecode(name).lower()) | models.Q(alternative_names__contains=[name]))
+            .order_by("ranking")
+            .first()
+        )
+
+    def __init__(self, level: Optional[int] = None, *args, **kwargs):
+        self.level = level
+        super().__init__(*args, **kwargs)
+
+    def get_queryset(self) -> QuerySet:
+        queryset = super().get_queryset()
+        if level := self.level:
+            return queryset.filter(level=level)
+        return queryset
+
+
+class Geography(WBModel, MPTTModel):
+    class Level(models.IntegerChoices):
+        CONTINENT = 0, "Continent"
+        COUNTRY = 1, "Country"
+        STATE = 2, "State"
+        CITY = 3, "City"
+
+    name = models.CharField(max_length=255)
+    short_name = models.CharField(max_length=255)
+    alternative_names = ArrayField(
+        base_field=models.CharField(max_length=255),
+        default=list,
+        blank=True,
+        verbose_name="Alternative Names",
+        help_text="Alternative Names",
+    )
+    parent = TreeForeignKey("self", on_delete=models.CASCADE, null=True, blank=True, related_name="children")
+    representation = models.CharField(max_length=255, default="", blank=True)
+
+    search_vector = SearchVectorField(null=True)
+    trigram_search_vector = models.CharField(max_length=1024, null=True, blank=True)
+
+    code_2 = models.CharField(max_length=2, verbose_name="2 Character Alphanumeric Code", null=True, blank=True)
+    code_3 = models.CharField(max_length=3, verbose_name="3 Character Alphanumeric Code", null=True, blank=True)
+    code = models.CharField(max_length=16, verbose_name="Code", null=True, blank=True)
+
+    population = models.PositiveIntegerField(null=True, blank=True)
+    ranking = models.PositiveIntegerField(default=1)
+    time_zone = TimeZoneField(choices_display="WITH_GMT_OFFSET", null=True, blank=True)
+
+    objects = LeveledGeographyManager()
+    continents = LeveledGeographyManager(level=0)
+    countries = LeveledGeographyManager(level=1)
+    states = LeveledGeographyManager(level=2)
+    cities = LeveledGeographyManager(level=3)
+
+    def lookup_descendants(self, name: str, level: Optional[int] = None) -> models.Model | None:
+        qs = self.get_descendants()
+        if level is not None:
+            qs = qs.filter(level=level)
+
+        qs = qs.annotate(name_unaccent=Unaccent(Lower("name"))).filter(
+            models.Q(name_unaccent=unidecode(name).lower()) | models.Q(alternative_names__contains=[name])
+        )
+        if qs.count() == 1:
+            return qs.first()
+
+    class Meta:
+        verbose_name_plural = "Geographies"
+        indexes = [
+            GinIndex(fields=["search_vector"], name="geography_sv_gin_idx"),  # type: ignore
+            GinIndex(
+                fields=["trigram_search_vector"], opclasses=["gin_trgm_ops"], name="geography_trigram_sv_gin_idx"
+            ),  # type: ignore
+        ]
+        constraints = [
+            models.UniqueConstraint(
+                name="%(app_label)s_%(class)s_level_code2__uniq",
+                fields=("level", "code_2"),
+                condition=models.Q(level=1),
+            ),
+            models.UniqueConstraint(
+                name="%(app_label)s_%(class)s_level_code3__uniq",
+                fields=("level", "code_3"),
+                condition=models.Q(level=1),
+            ),
+        ]
+
+    def update_search_vectors(self):
+        alternative_names = [Value(name) for name in self.alternative_names]
+        self.search_vector = SearchVector(Value(self.name), *alternative_names)
+        self.trigram_search_vector = f"{self.name} {' '.join(self.alternative_names)}".strip()
+
+    def save(self, *args, **kwargs):
+        self.update_search_vectors()
+        super().save(*args, **kwargs)
+
+    def __str__(self) -> str:
+        return f"{self.name}"
+
+    @classmethod
+    def dict_to_model(cls, country_data, level=Level.COUNTRY):
+        qs = Geography.objects.filter(level=level)
+        if isinstance(country_data, int):
+            return qs.filter(id=country_data).first()
+        elif code := country_data.get("code", None):
+            return qs.filter(code_3=code).first()
+        elif code_alpha2 := country_data.get("code_alpha2", None):
+            return qs.filter(code_2=code_alpha2).first()
+
+    @classmethod
+    def get_endpoint_basename(cls):
+        return "wbcore:geography:geography"
+
+    @classmethod
+    def get_representation_endpoint(cls):
+        return "wbcore:geography:geographyrepresentation-list"
+
+    @classmethod
+    def get_representation_value_key(cls):
+        return "id"
+
+    @classmethod
+    def get_representation_label_key(cls):
+        return "{{representation}}"

wbcore/contrib/geography/release_notes/1_0_0.md

@@ -0,0 +1,13 @@
+Date: 2023-04-26
+Module: Geography
+Summary: Initial Release Note
+Version: 1.0.0
+
+## New Features
+- Bootstrap module versioning
+
+## Enhancements
+./.
+
+## Bugfixes
+./.

wbcore/contrib/geography/serializers.py

@@ -0,0 +1,29 @@
+from wbcore import serializers as wb_serializers
+
+from .models import Geography
+
+
+class GeographyRepresentationSerializer(wb_serializers.RepresentationSerializer):
+    class Meta:
+        model = Geography
+        fields = ["id", "representation"]
+
+
+class CountryRepresentationSerializer(GeographyRepresentationSerializer):
+    filter_params = {"level": Geography.Level.COUNTRY.value}
+
+
+class GeographyModelSerializer(wb_serializers.ModelSerializer):
+    _parent = GeographyRepresentationSerializer(source="parent")
+
+    class Meta:
+        model = Geography
+        fields = [
+            "id",
+            "name",
+            "representation",
+            "parent",
+            "_parent",
+            "code_2",
+            "code_3",
+        ]

wbcore/contrib/geography/static/geography/markdown/documentation/geography.md

@@ -0,0 +1,16 @@
+# Geographies
+A list of every geography object saved in the database.
+
+## Columns:
+Each column title has three lines on the right if you hover over it. Click on them to show options for that column. The second tab of the options menu will allow you to filter the column, the third to completely hide entire columns. Click on anywhere else on the column to order it, cycling between ascending, descending and no ordering. Hold shift while clicking to order multiple columns with individual weights.
+### Name:
+A representation name for the selected geography. Consists of its geography type (continent, country, state or city), the geography's name (e.g. Hamburg) and in the case of states and cities the alpha 3 code of its parent country in brackets (e.g. DEU).
+### Parent:
+The representation name of the geography's parent. Geography objects are ordered like this: Continent > Country > State > City. As a result, continents have no parent. Hover over the name to display the parent's name, their parent object and alpha 3 country code. Column can be ordered by (non-representation-) name.
+### Alpha 2 Country Code:
+The alpha 2 country code for the geography object's parent country. Thus, continents have no country codes.
+### Alpha 3 Country Code:
+The alpha 3 country code for the geography object's parent country.
+
+## Search Field:
+Typing in the search field allows to filter the geography objects by name.

wbcore/contrib/geography/tests/conftest.py

@@ -0,0 +1,26 @@
+import pytest
+
+from django.apps import apps
+from django.db import connection
+from django.db.models.signals import pre_migrate
+from pytest_factoryboy import register
+from rest_framework.test import APIRequestFactory, APIClient
+from wbcore.contrib.authentication.factories import UserFactory
+
+from ..factories import ContinentFactory
+from .signals import app_pre_migration
+
+register(ContinentFactory)
+
+
+pre_migrate.connect(app_pre_migration, sender=apps.get_app_config("geography"))
+
+
+@pytest.fixture()
+def request_factory():
+    return APIRequestFactory()
+
+
+@pytest.fixture()
+def super_user():
+    return UserFactory(is_superuser=True)

wbcore/contrib/geography/tests/signals.py

@@ -0,0 +1,7 @@
+from django.db import connection
+
+
+def app_pre_migration(sender, app_config, **kwargs):
+    cur = connection.cursor()
+    cur.execute("CREATE EXTENSION IF NOT EXISTS pg_trgm;")
+    cur.execute("CREATE EXTENSION IF NOT EXISTS btree_gin;")

wbcore/contrib/geography/tests/test_models.py

@@ -0,0 +1,27 @@
+from typing import Callable
+
+import pytest
+
+from wbcore.contrib.geography.models import Geography
+
+
+class TestModels:
+    @pytest.fixture
+    def geography(self):
+        return Geography(name="Test Geography")
+
+    def test_endpoint_basename(self, geography):
+        assert isinstance(geography.get_endpoint_basename, Callable)
+
+    def test_representation_endpoint(self, geography):
+        assert isinstance(geography.get_representation_endpoint, Callable)
+
+    def test_representation_value_key(self, geography):
+        assert geography.get_representation_value_key() == "id"
+
+    def test_representation_label_key(self, geography):
+        assert geography.get_representation_label_key is not None
+
+    def test_str(self, geography):
+        assert isinstance(str(geography), str)
+        assert str(geography) == geography.name

wbcore/contrib/geography/tests/test_viewsets.py

@@ -0,0 +1,100 @@
+import pytest
+from rest_framework import status
+
+from wbcore.contrib.geography.factories import ContinentFactory
+from wbcore.contrib.geography.models import Geography
+from wbcore.contrib.geography.serializers import GeographyModelSerializer
+from wbcore.contrib.geography.viewsets import (
+    GeographyModelViewSet,
+    GeographyRepresentationViewSet,
+)
+
+
+@pytest.mark.django_db
+@pytest.mark.with_db
+class TestViewsets:
+    @pytest.fixture
+    def continents(self):
+        return ContinentFactory.create_batch(3)
+
+    @pytest.fixture
+    def continent(self, continents):
+        return continents[0]
+
+    @pytest.fixture
+    def continent_build(self):
+        instance = ContinentFactory.build()
+        return GeographyModelSerializer(instance).data
+
+    @pytest.mark.parametrize("viewset", [GeographyModelViewSet, GeographyRepresentationViewSet])
+    def test_get(self, viewset, request_factory, super_user, continents):
+        # Arrange
+        request = request_factory.get("")
+        request.user = super_user
+        viewset = viewset.as_view({"get": "list"})
+        # Act
+        response = viewset(request)
+        # Assert
+        assert len(response.data["results"]) == 3
+        assert response.status_code == status.HTTP_200_OK
+
+    @pytest.mark.parametrize("viewset", [GeographyModelViewSet, GeographyRepresentationViewSet])
+    def test_retrieve(self, viewset, request_factory, super_user, continent):
+        # Arrange
+        request = request_factory.get("")
+        request.user = super_user
+        viewset = viewset.as_view({"get": "retrieve"})
+        # Act
+        response = viewset(request, pk=continent.id)
+        instance = response.data.get("instance")
+        # Assert
+        assert instance is not None
+        assert instance["id"] == continent.id
+        assert response.status_code == status.HTTP_200_OK
+
+    def test_create(self, request_factory, super_user, continent_build):
+        # Arrange
+        request = request_factory.post("", data=continent_build, format="json")
+        request.user = super_user
+        viewset = GeographyModelViewSet.as_view({"post": "create"})
+        # Act
+        response = viewset(request)
+        # Assert
+        assert response.status_code == status.HTTP_201_CREATED
+
+    def test_delete(self, request_factory, super_user, continents):
+        # Arrange
+        entry_id = continents[1].id
+        request = request_factory.delete("", args=entry_id)
+        request.user = super_user
+        viewset = GeographyModelViewSet.as_view({"delete": "destroy"})
+        # Act
+        response = viewset(request, pk=entry_id)
+        # Assert
+        assert response.status_code == status.HTTP_204_NO_CONTENT
+        assert Geography.objects.count() == 2
+        assert not Geography.objects.filter(id=entry_id).exists()
+
+    def test_put(self, request_factory, super_user, continent, continent_build):
+        # Arrange
+        continent_build["id"] = continent.id
+        request = request_factory.put("", data=continent_build, format="json")
+        request.user = super_user
+        viewset = GeographyModelViewSet.as_view({"put": "update"})
+        # Act
+        response = viewset(request, pk=continent.id)
+        # Assert
+        assert response.status_code == status.HTTP_200_OK
+
+    def test_patch(self, request_factory, super_user, continent):
+        # Arrange
+        new_field_data = "Foo Bar"
+        request = request_factory.patch("", data={"name": new_field_data})
+        request.user = super_user
+        viewset = GeographyModelViewSet.as_view({"patch": "partial_update"})
+        # Act
+        response = viewset(request, pk=continent.id)
+        continent.refresh_from_db()
+        # Assert
+        assert response.status_code == status.HTTP_200_OK
+        assert continent.name == new_field_data

wbcore/contrib/geography/urls.py

@@ -0,0 +1,13 @@
+from django.urls import include, path
+
+from wbcore.routers import WBCoreRouter
+
+from .viewsets import GeographyModelViewSet, GeographyRepresentationViewSet
+
+router = WBCoreRouter()
+router.register(r"geographyrepresentation", GeographyRepresentationViewSet, basename="geographyrepresentation")
+router.register(r"geography", GeographyModelViewSet, basename="geography")
+
+urlpatterns = [
+    path("", include(router.urls)),
+]

wbcore/contrib/geography/viewsets/__init__.py

@@ -0,0 +1 @@
+from .geography import GeographyModelViewSet, GeographyRepresentationViewSet

wbcore/contrib/geography/viewsets/display/__init__.py

@@ -0,0 +1 @@
+from .geography import GeographyDisplayConfig

wbcore/contrib/geography/viewsets/display/geography.py

@@ -0,0 +1,32 @@
+from typing import Optional
+
+from wbcore.metadata.configs import display as dp
+from wbcore.metadata.configs.display.instance_display.shortcuts import (
+    Display,
+    create_simple_display,
+)
+from wbcore.metadata.configs.display.view_config import DisplayViewConfig
+
+
+class GeographyDisplayConfig(DisplayViewConfig):
+    def get_list_display(self) -> Optional[dp.ListDisplay]:
+        return dp.ListDisplay(
+            fields=[
+                dp.Field(key="name", label="Name"),
+                dp.Field(key="parent", label="Parent"),
+                dp.Field(key="code_2", label="Alpha 2 Country Code"),
+                dp.Field(key="code_3", label="Alpha 3 Country Code"),
+            ]
+        )
+
+    def get_instance_display(self) -> Display:
+        return create_simple_display(
+            [
+                [
+                    "name",
+                    "parent",
+                    "code_2",
+                    "code_3",
+                ]
+            ]
+        )

wbcore/contrib/geography/viewsets/geography.py

@@ -0,0 +1,58 @@
+from django.contrib.postgres.search import TrigramSimilarity
+from django.db.models.expressions import Value
+from rest_framework.filters import OrderingFilter
+
+from wbcore import viewsets
+from wbcore.contrib.guardian.filters import ObjectPermissionsFilter
+from wbcore.viewsets.mixins import DjangoFilterBackend
+
+from ..models import Geography
+from ..serializers import GeographyModelSerializer, GeographyRepresentationSerializer
+from .display import GeographyDisplayConfig
+from .preview import GeographyPreviewConfig
+from .titles.geography import GeographyTitleConfig
+
+
+class GeographyRepresentationViewSet(viewsets.RepresentationViewSet):
+    filter_backends = (ObjectPermissionsFilter, DjangoFilterBackend, OrderingFilter)
+    ordering = ["-trigram", "ranking", "representation"]
+    filterset_fields = {"level": ["exact"]}
+
+    queryset = Geography.objects.all()
+    serializer_class = GeographyRepresentationSerializer
+
+    def get_queryset(self):
+        queryset = super().get_queryset()
+
+        if search := self.request.GET.get("search", None):
+            if search.startswith("^"):
+                return queryset.annotate(trigram=Value(1)).filter(search_vector=search[1:])
+
+            return queryset.filter(trigram_search_vector__icontains=search).annotate(
+                trigram=TrigramSimilarity("name", search)
+            )
+
+        return queryset.annotate(trigram=Value(1))
+
+
+class GeographyModelViewSet(viewsets.ModelViewSet):
+    LIST_DOCUMENTATION = "geography/markdown/documentation/geography.md"
+    display_config_class = GeographyDisplayConfig
+    preview_config_class = GeographyPreviewConfig
+    title_config_class = GeographyTitleConfig
+    ordering_fields = [
+        "code_2",
+        "code_3",
+        "parent__name",
+    ]
+    ordering = ["name"]
+    search_fields = ["name"]
+    filterset_fields = {
+        "code_2": ["exact", "icontains"],
+        "code_3": ["exact", "icontains"],
+        "parent": ["exact"],
+        "level": ["exact"],
+    }
+
+    queryset = Geography.objects.all()
+    serializer_class = GeographyModelSerializer

wbcore/contrib/geography/viewsets/menu/__init__.py

@@ -0,0 +1 @@
+from .geography import GEOGRAPHY_MENUITEM

wbcore/contrib/geography/viewsets/menu/geography.py

@@ -0,0 +1,8 @@
+from wbcore.menus import ItemPermission, MenuItem
+
+GEOGRAPHY_MENUITEM = MenuItem(
+    label="Geography",
+    endpoint="geography:geography-list",
+    add=MenuItem(label="New Geography", endpoint="geography:geography-list"),
+    permission=ItemPermission(method=lambda request: request.user.is_staff),
+)

wbcore/contrib/geography/viewsets/preview/__init__.py

@@ -0,0 +1 @@
+from .geography import GeographyPreviewConfig