feat: add deployment time zone metadata

Author: wietzesuijker

ami/main/api/serializers.py

@@ -185,6 +185,7 @@ class Meta:
             "updated_at",
             "latitude",
             "longitude",
+            "time_zone",
             "first_date",
             "last_date",
             "device",
@@ -234,6 +235,7 @@ class Meta:
             "id",
             "name",
             "details",
+            "time_zone",
         ]
 
 
@@ -247,6 +249,7 @@ class Meta:
             "details",
             "latitude",
             "longitude",
+            "time_zone",
             "events_count",
             # "captures_count",
             # "detections_count",

ami/main/migrations/0079_deployment_time_zone.py

@@ -0,0 +1,21 @@
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("main", "0078_classification_applied_to"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="deployment",
+            name="time_zone",
+            field=models.CharField(
+                default=settings.TIME_ZONE,
+                help_text="IANA time zone for this deployment. Naive datetimes are interpreted in this zone before being stored as UTC.",
+                max_length=64,
+            ),
+        ),
+    ]

ami/main/models.py

@@ -8,6 +8,7 @@
 import urllib.parse
 from io import BytesIO
 from typing import Final, final  # noqa: F401
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
 
 import PIL.Image
 import pydantic
@@ -606,6 +607,14 @@ class Deployment(BaseModel):
     latitude = models.FloatField(null=True, blank=True)
     longitude = models.FloatField(null=True, blank=True)
     image = models.ImageField(upload_to="deployments", blank=True, null=True)
+    time_zone = models.CharField(
+        max_length=64,
+        default=settings.TIME_ZONE,
+        help_text=(
+            "IANA time zone for this deployment. Naive datetimes are interpreted in this zone "
+            "before being stored as UTC."
+        ),
+    )
 
     project = models.ForeignKey(Project, on_delete=models.SET_NULL, null=True, related_name="deployments")
 
@@ -662,6 +671,14 @@ class Deployment(BaseModel):
     class Meta:
         ordering = ["name"]
 
+    def clean(self):
+        super().clean()
+        if self.time_zone:
+            try:
+                ZoneInfo(self.time_zone)
+            except ZoneInfoNotFoundError as exc:
+                raise ValidationError({"time_zone": f"Invalid IANA time zone '{self.time_zone}': {exc}"}) from exc
+
     def taxa(self) -> models.QuerySet["Taxon"]:
         return Taxon.objects.filter(Q(occurrences__deployment=self)).distinct()
 

ami/main/tests.py

@@ -4,6 +4,7 @@
 from io import BytesIO
 
 from django.contrib.auth.models import AnonymousUser
+from django.core.exceptions import ValidationError
 from django.core.files.uploadedfile import SimpleUploadedFile
 from django.db import connection, models
 from django.test import TestCase, override_settings
@@ -15,6 +16,7 @@
 
 from ami.exports.models import DataExport
 from ami.jobs.models import VALID_JOB_TYPES, Job
+from ami.main.api.serializers import DeploymentSerializer
 from ami.main.models import (
     Classification,
     Deployment,
@@ -46,6 +48,28 @@
 logger = logging.getLogger(__name__)
 
 
+class TestTimeZoneNormalization(TestCase):
+    def test_deployment_invalid_time_zone_raises(self):
+        project = Project.objects.create(name="TZ Project", create_defaults=False)
+        deployment = Deployment(project=project, name="D1", time_zone="Mars/Phobos")
+        with self.assertRaises(ValidationError):
+            deployment.full_clean()
+
+    def test_deployment_serializer_exposes_time_zone(self):
+        project = Project.objects.create(name="TZ Project", create_defaults=False)
+        deployment = Deployment.objects.create(project=project, name="D1", time_zone="UTC")
+
+        class MinimalDeploymentSerializer(DeploymentSerializer):
+            class Meta(DeploymentSerializer.Meta):
+                fields = ("id", "time_zone")
+
+        request = APIRequestFactory().get("/")
+        request.user = AnonymousUser()
+
+        data = MinimalDeploymentSerializer(deployment, context={"request": request}).data
+        self.assertEqual(data["time_zone"], "UTC")
+
+
 class TestProjectSetup(TestCase):
     def test_project_creation(self):
         project = Project.objects.create(name="New Project with Defaults", create_defaults=True)