Merge pull request #172 from bas-amop/tz/tagging

Add tag field route model, serialiser and route request view

Author: davidwyld

CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - added ensure_adminuser command to add subtly more sophisticated behaviour to Django's createsuperuser - i.e. don't raise non-zero exit code if superuser already exists, add more useful output.
 - Use uv in the docker image.
 - Empty arrays to empty responses for a consistent response structure.
+- Adding a "tags" field to the Route model. As an optional parameter, tags can be assigned to routes using a POST api/route request. This is implemented using [django-taggit](https://django-taggit.readthedocs.io/en/latest).
 
 ### Changed
 - Inappropriate use of 204 code: RecentRoutesView changed from 204 to 200 OK with an empty array and the original message ("No recent routes found for today.").

docs/apischema.yml

@@ -763,6 +763,14 @@ components:
           default: false
           description: If true, forces recalculation even if an existing route is
             found.
+        tags:
+          type: array
+          items:
+            type: string
+            maxLength: 50
+          nullable: true
+          description: Optional tags for route (e.g., ['archive', 'SD056']). Can also
+            accept a single string or comma-separated string.
       required:
       - end_lat
       - end_lon

polarrouteserver/route_api/admin.py

@@ -16,6 +16,7 @@ class RouteAdmin(admin.ModelAdmin):
         "id",
         "display_start",
         "display_end",
+        "display_tags",
         "requested",
         "calculated",
         "job_id",
@@ -24,28 +25,35 @@ class RouteAdmin(admin.ModelAdmin):
         "polar_route_version",
     ]
     ordering = ("-requested",)
+    list_filter = ("tags", "calculated", "requested")
+    search_fields = ("start_name", "end_name", "tags__name")
 
     list_select_related = ("mesh",)
 
     def get_queryset(self, request):
         # Load only the fields necessary for the changelist view
         queryset = super().get_queryset(request)
-        return queryset.defer("json", "json_unsmoothed", "mesh__json")
+        return queryset.defer("json", "json_unsmoothed", "mesh__json").prefetch_related(
+            "tags"
+        )
 
     def get_fieldsets(self, request, obj=None):
-        # contain the json fields in a collapsed section of the page
+        # Contain the json fields in a collapsed section of the page
         collapsed_fields = ("json", "json_unsmoothed")
         if obj:
+            # Get regular model fields excluding collapsed ones and id
+            regular_fields = [
+                f.name
+                for f in self.model._meta.fields
+                if f.name not in collapsed_fields + ("id",)
+            ]
+            # Add tags field (it is a TaggableManager, not a regular field)
+            regular_fields.append("tags")
+
             return [
                 (
                     None,
-                    {
-                        "fields": [
-                            f.name
-                            for f in self.model._meta.fields
-                            if f.name not in collapsed_fields + ("id",)
-                        ]
-                    },
+                    {"fields": regular_fields},
                 ),
                 (
                     "Click to expand JSON fields",
@@ -67,16 +75,24 @@ def display_end(self, obj):
         else:
             return f"({obj.end_lat},{obj.end_lon})"
 
+    def display_tags(self, obj):
+        """Display tags as a comma-separated string."""
+        tags = obj.tags.all()
+        if tags:
+            return ", ".join([tag.name for tag in tags])
+        return "-"
+
     def job_id(self, obj):
         job = obj.job_set.latest("datetime")
         return f"{job.id}"
 
     display_start.short_description = "Start (lat,lon)"
     display_end.short_description = "End (lat,lon)"
+    display_tags.short_description = "Tags"
     job_id.short_description = "Job ID (latest)"
 
     def get_readonly_fields(self, request, obj=None):
-        editable_fields = ("requested", "calculated", "start_name", "end_name")
+        editable_fields = ("requested", "calculated", "start_name", "end_name", "tags")
 
         if obj:
             # Return a list of all field names on the model

polarrouteserver/route_api/migrations/0017_route_tags.py

@@ -0,0 +1,28 @@
+# Generated by Django 5.2.8 on 2025-12-09 16:23
+
+import taggit.managers
+from django.db import migrations
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("route_api", "0016_alter_location_name"),
+        (
+            "taggit",
+            "0006_rename_taggeditem_content_type_object_id_taggit_tagg_content_8fc721_idx",
+        ),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="route",
+            name="tags",
+            field=taggit.managers.TaggableManager(
+                blank=True,
+                help_text="Tags for route categorization",
+                through="taggit.TaggedItem",
+                to="taggit.Tag",
+                verbose_name="Tags",
+            ),
+        ),
+    ]

polarrouteserver/route_api/models.py

@@ -3,6 +3,7 @@
 from celery.result import AsyncResult
 from django.db import models
 from django.utils import timezone
+from taggit.managers import TaggableManager
 
 from polarrouteserver.celery import app
 
@@ -71,6 +72,7 @@ class Route(models.Model):
     json = models.JSONField(null=True)
     json_unsmoothed = models.JSONField(null=True)
     polar_route_version = models.CharField(max_length=60, null=True)
+    tags = TaggableManager(blank=True, help_text="Tags for route")
 
 
 class Job(models.Model):

polarrouteserver/route_api/serializers.py

@@ -1,6 +1,7 @@
 from rest_framework import serializers
 from rest_framework.reverse import reverse
 from celery.result import AsyncResult
+from taggit.serializers import TaggitSerializer, TagListSerializerField
 
 from .models import Mesh, Vehicle, Route, Job, Location
 from polarrouteserver.celery import app
@@ -100,7 +101,9 @@ class Meta:
         vessel_type = serializers.CharField()
 
 
-class RouteSerializer(serializers.ModelSerializer):
+class RouteSerializer(TaggitSerializer, serializers.ModelSerializer):
+    tags = TagListSerializerField()
+
     class Meta:
         model = Route
         fields = [
@@ -118,6 +121,7 @@ class Meta:
             "mesh",
             "requested",
             "calculated",
+            "tags",
         ]
 
     def _extract_routes_by_type(self, route_data, route_type):
@@ -282,6 +286,7 @@ def to_representation(self, instance):
         result = {
             "routes": available_routes,
             "polarrouteserver-version": polarrouteserver_version,
+            "tags": data.get("tags", []),
         }
 
         # Add error if no routes available

polarrouteserver/route_api/views.py

@@ -2,6 +2,7 @@
 from datetime import datetime
 
 from celery.result import AsyncResult
+from django.contrib.contenttypes.models import ContentType
 from drf_spectacular.utils import (
     extend_schema,
     extend_schema_view,
@@ -13,6 +14,7 @@
 from rest_framework.views import APIView
 from rest_framework.reverse import reverse
 from rest_framework import serializers, viewsets
+from taggit.models import TaggedItem
 
 from polar_route.config_validation.config_validator import validate_vessel_config
 from polarrouteserver.version import __version__ as polarrouteserver_version
@@ -318,6 +320,12 @@ class RouteRequestView(LoggingMixin, ResponseMixin, GenericAPIView):
                     default=False,
                     help_text="If true, forces recalculation even if an existing route is found.",
                 ),
+                "tags": serializers.ListField(
+                    child=serializers.CharField(max_length=50),
+                    required=False,
+                    allow_null=True,
+                    help_text="Optional tags for route (e.g., ['archive', 'SD056']). Can also accept a single string or comma-separated string.",
+                ),
             },
         ),
         responses={
@@ -350,6 +358,7 @@ def post(self, request):
         end_name = data.get("end_name", None)
         custom_mesh_id = data.get("mesh_id", None)
         force_new_route = data.get("force_new_route", False)
+        tags = data.get("tags", None)
 
         if custom_mesh_id:
             try:
@@ -409,6 +418,24 @@ def post(self, request):
             end_name=end_name,
         )
 
+        # Add tags if provided
+        if tags:
+            # Handle both string and list inputs
+            if isinstance(tags, str):
+                # If it's a string, split by comma and strip whitespace
+                tags_list = [t.strip() for t in tags.split(",") if t.strip()]
+            elif isinstance(tags, list):
+                tags_list = [str(t).strip() for t in tags if str(t).strip()]
+            else:
+                tags_list = []
+
+            logger.info(f"Adding tags to route {route.id}: {tags_list}")
+            if tags_list:
+                route.tags.add(*tags_list)
+                logger.info(
+                    f"Route {route.id} now has tags: {[tag.name for tag in route.tags.all()]}"
+                )
+
         # Start the task calculation
         task = optimise_route.delay(
             route.id, backup_mesh_ids=[mesh.id for mesh in meshes[1:]]
@@ -525,10 +552,32 @@ def get(self, request):
                 }
             )
 
+        # Get route IDs for tag lookup
+        route_ids = [route["id"] for route in routes_recent]
+
+        # Get all tags for routes in one query
+        route_tags = {}
+        if route_ids:
+            content_type = ContentType.objects.get_for_model(Route)
+            tagged_items = (
+                TaggedItem.objects.filter(
+                    content_type=content_type, object_id__in=route_ids
+                )
+                .select_related("tag")
+                .values("object_id", "tag__name")
+            )
+
+            for item in tagged_items:
+                route_id = int(item["object_id"])
+                if route_id not in route_tags:
+                    route_tags[route_id] = []
+                route_tags[route_id].append(item["tag__name"])
+
         routes_data = []
         for route in routes_recent:
+            job_id = route.get("job__id")
             status = self._get_celery_task_status(
-                route["job__id"], route["calculated"], route["info"]
+                job_id, route["calculated"], route["info"]
             )
 
             # Build lightweight route data
@@ -551,12 +600,13 @@ def get(self, request):
                 "route_url": reverse(
                     "route_detail", args=[route["id"]], request=request
                 ),
+                "tags": route_tags.get(route["id"], []),
             }
 
-            if route["job__id"]:
-                route_data["job_id"] = route["job__id"]
+            if job_id:
+                route_data["job_id"] = job_id
                 route_data["job_status_url"] = reverse(
-                    "job_detail", args=[route["job__id"]], request=request
+                    "job_detail", args=[job_id], request=request
                 )
 
             # Add minimal mesh info without loading the heavy JSON

polarrouteserver/settings/base.py

@@ -91,6 +91,7 @@
     "rest_framework",
     "drf_spectacular",
     "drf_spectacular_sidecar",
+    "taggit",
     "polarrouteserver.route_api",
     "corsheaders",
 ]
@@ -127,6 +128,8 @@
     "AUTHENTICATION_WHITELIST": [],
 }
 
+TAGGIT_CASE_INSENSITIVE = True
+
 ROOT_URLCONF = "polarrouteserver.urls"
 
 TEMPLATES = [

pyproject.toml

@@ -20,6 +20,7 @@ dependencies = [
     "django-celery-results",
     "django-cors-headers",
     "django-rest-framework",
+    "django-taggit",
     "drf-spectacular[sidecar]",
     "haversine",
     "polar-route==1.0.0",

request_route/request_route.py

@@ -87,6 +87,7 @@ def request_route(
     num_requests: int = 10,
     force_new_route: bool = False,
     mesh_id: int = None,
+    tags: list = None,
 ) -> str:
     """Requests a route from polarRouteServer, monitors job status until complete, then retrieves route data.
 
@@ -98,6 +99,7 @@ def request_route(
         num_requests (int, optional): Max number of status requests before giving up. Defaults to 10.
         force_new_route (bool, optional): Force recalculation of an already existing route. Default: False.
         mesh_id (int, optional): Custom mesh ID to use for route calculation. Default: None.
+        tags (list, optional): Tags to assign to the route. Default: None.
 
     Raises:
         Exception: If no status URL is returned.
@@ -122,6 +124,7 @@ def request_route(
                 "end_name": end.name,
                 "force_new_route": force_new_route,
                 "mesh_id": mesh_id,
+                "tags": tags,
             },
         ).encode("utf-8"),
     )
@@ -275,6 +278,13 @@ def parse_args():
         action="store_true",
         help="Force polarRouteServer to create a new route even if one is already available.",
     )
+    parser.add_argument(
+        "-t",
+        "--tags",
+        type=str,
+        nargs="*",
+        help="Tags to assign to the route (e.g., 'archive' 'SD056'). Can specify multiple tags separated by spaces.",
+    )
     parser.add_argument(
         "-o",
         "--output",
@@ -296,6 +306,7 @@ def main():
         status_update_delay=args.delay,
         force_new_route=args.force,
         mesh_id=args.meshid,
+        tags=args.tags,
     )
 
     if route is None: