Merge pull request #110 from lsst-sqre/tickets/DM-51345

DM-51345: Update DayObs parameter formats

Author: jonathansick

.github/workflows/ci.yaml

@@ -4,7 +4,7 @@ env:
   # Current supported uv version. The uv documentation recommends pinning
   # this. The version should match the version used in .pre-commit-config.yaml
   # and frozen in uv.lock.
-  UV_VERSION: "0.7.7"
+  UV_VERSION: "0.7.12"
 
 "on":
   merge_group: {}

.github/workflows/periodic-ci.yaml

@@ -9,7 +9,7 @@ env:
   # Current supported uv version. The uv documentation recommends pinning
   # this. The version should match the version used in .pre-commit-config.yaml
   # and frozen in uv.lock.
-  UV_VERSION: "0.7.7"
+  UV_VERSION: "0.7.12"
 
 "on":
   schedule:

.pre-commit-config.yaml

@@ -7,12 +7,12 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.7.7
+    rev: 0.7.12
     hooks:
       - id: uv-lock
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.11.11
+    rev: v0.11.13
     hooks:
       - id: ruff-check
         args: [--fix, --exit-non-zero-on-fix]

CHANGELOG.md

@@ -8,6 +8,20 @@ Collect fragments into this file with: scriv collect --version X.Y.Z
 
 <!-- scriv-insert-here -->
 
+<a id='changelog-0.23.0'></a>
+
+## 0.23.0 (2025-06-12)
+
+### Backwards-incompatible changes
+
+- The `dayobs` parameter format now creates an int value in the notebook rather than a string. For example, `mydate = 20250115` instead of `mydate = '20250115'`. This is a better match for the DayObs metadata standard described in [SITCOMTN-032](https://sitcomtn-032.lsst.io).
+
+  Any early adopters of the `dayobs` format will need to update their notebooks. Also consider using the new `dayobs-date` format instead.
+
+### New features
+
+- Added a new `dayobs-date` parameter format. This is similar to the original `dayobs` format in the use of the UTC-12 timezone, but expects dates in the `YYYY-MM-DD` format and assigns the parameters as `datetime.date` values in the notebook. Although this is not the standard usage of `dayobs`, it should be useful for many applications because the ISO 8601 string format is more readable and the `datetime.date` type is more convenient to use in Python code. `dayobs-date` works with dynamic defaults like `dayobs` and standard `date` formats.
+
 <a id='changelog-0.22.0'></a>
 
 ## 0.22.0 (2025-06-05)

Dockerfile

@@ -23,7 +23,7 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
 FROM base-image AS install-image
 
 # Install uv.
-COPY --from=ghcr.io/astral-sh/uv:0.7.7 /uv /bin/uv
+COPY --from=ghcr.io/astral-sh/uv:0.7.12 /uv /bin/uv
 
 # Install some additional packages required for building dependencies.
 COPY scripts/install-dependency-packages.sh .

src/timessquare/domain/pageparameters/__init__.py

@@ -6,9 +6,10 @@
 from ._datedynamicdefault import DYNAMIC_DATE_PATTERN, DateDynamicDefault
 from ._dateparameter import DateParameterSchema
 from ._datetimeparameter import DatetimeParameterSchema
+from ._dayobsdateparameter import DayObsDateParameterSchema
+from ._dayobsparameter import DayObsParameterSchema
 from ._integerparameter import IntegerParameterSchema
 from ._numberparameter import NumberParameterSchema
-from ._obsdateparameter import ObsDateParameterSchema
 from ._pageparameters import (
     PageParameters,
     create_and_validate_parameter_schema,
@@ -23,9 +24,10 @@
     "DateDynamicDefault",
     "DateParameterSchema",
     "DatetimeParameterSchema",
+    "DayObsDateParameterSchema",
+    "DayObsParameterSchema",
     "IntegerParameterSchema",
     "NumberParameterSchema",
-    "ObsDateParameterSchema",
     "PageParameterSchema",
     "PageParameters",
     "StringParameterSchema",

src/timessquare/domain/pageparameters/_dayobsdateparameter.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import re
+from datetime import date, datetime, timedelta, timezone
+from typing import Any
+
+from timessquare.exceptions import PageParameterValueCastingError
+
+from ._datedynamicdefault import DateDynamicDefault
+from ._schemabase import PageParameterSchema
+
+__all__ = ["DayObsDateParameterSchema"]
+
+
+class DayObsDateParameterSchema(PageParameterSchema):
+    """A parameter schema for the custom Rubin DayObs date format with dashes.
+
+    DayObsDate is defined as a date in the UTC-12 timezone with the string
+    representation formatted as YYYY-MM-DD. Times Square parameters validate
+    dayobs-date parameters as strings, but the Python assignment returns a
+    datetime.date instance.
+    """
+
+    tz = timezone(-timedelta(hours=12))
+    """The timezone for DayObs parameters, UTC-12."""
+
+    @property
+    def strict_schema(self) -> dict[str, Any]:
+        """Get the JSON schema without the custom format."""
+        schema = super().strict_schema
+        # Add a basic regex pattern to validate the YYYY-MM-DD format
+        schema["pattern"] = r"^\d{4}-\d{2}-\d{2}$"
+        return schema
+
+    def validate_default(self) -> bool:
+        """Validate the default value for the parameter.
+
+        Returns
+        -------
+        bool
+            True if the default is valid, False otherwise.
+        """
+        if "X-Dynamic-Default" in self.schema:
+            try:
+                DateDynamicDefault(self.schema["X-Dynamic-Default"])
+            except ValueError:
+                return False
+            else:
+                return True
+        elif "default" in self.schema:
+            try:
+                self.cast_value(self.schema["default"])
+            except PageParameterValueCastingError:
+                return False
+            else:
+                return True
+        else:
+            return False
+
+    def cast_value(self, v: Any) -> date:
+        """Cast a value to its Python type."""
+        try:
+            # Parse a YYYY-MM-DD string, date object, or datetime object
+            if isinstance(v, str):
+                return self._cast_string(v)
+            elif isinstance(v, datetime):
+                # Check datetime before date because of inheritance
+                return self._cast_datetime(v)
+            elif isinstance(v, date):
+                return self._cast_date(v)
+            else:
+                raise PageParameterValueCastingError.for_value(v, "date")
+        except Exception as e:
+            raise PageParameterValueCastingError.for_value(v, "date") from e
+
+    def _cast_string(self, v: str) -> date:
+        """Cast a string value to the date format."""
+        match = re.match(r"^\d{4}-\d{2}-\d{2}$", v)
+        if not match:
+            raise ValueError(f"Invalid YYYY-MM-DD format: {v}")
+
+        year = int(v[:4])
+        month = int(v[5:7])
+        day = int(v[8:10])
+        return date(year, month, day)
+
+    def _cast_date(self, v: date) -> date:
+        """Cast a date object directly (no conversion needed)."""
+        return v
+
+    def _cast_datetime(self, v: datetime) -> date:
+        """Cast a datetime object to the DayObs date format."""
+        if v.tzinfo is not None:
+            # Convert to UTC-12 timezone
+            v = v.astimezone(self.tz)
+        else:
+            # If no timezone info, assume it's in UTC-12
+            v = v.replace(tzinfo=self.tz)
+        return v.date()
+
+    def create_python_imports(self) -> list[str]:
+        return ["import datetime"]
+
+    def create_python_assignment(self, name: str, value: Any) -> str:
+        date_value = self.cast_value(value)
+        str_value = date_value.isoformat()
+        return f'{name} = datetime.date.fromisoformat("{str_value}")'
+
+    def create_json_value(self, value: Any) -> str:
+        return self.cast_value(value).isoformat()
+
+    def create_qs_value(self, value: Any) -> str:
+        return self.cast_value(value).isoformat()
+
+    @property
+    def default(self) -> date:
+        if "X-Dynamic-Default" in self.schema:
+            dynamic_default = DateDynamicDefault(
+                self.schema["X-Dynamic-Default"]
+            )
+            return dynamic_default(datetime.now(tz=self.tz).date())
+        return self.cast_value(self.schema["default"])

src/timessquare/domain/pageparameters/_obsdateparameter.py renamed to src/timessquare/domain/pageparameters/_dayobsparameter.py

@@ -9,15 +9,16 @@
 from ._datedynamicdefault import DateDynamicDefault
 from ._schemabase import PageParameterSchema
 
-__all__ = ["ObsDateParameterSchema"]
+__all__ = ["DayObsParameterSchema"]
 
 
-class ObsDateParameterSchema(PageParameterSchema):
+class DayObsParameterSchema(PageParameterSchema):
     """A parameter schema for the custom Rubin DayObs format.
 
     DayObs is defined as the date in the UTC-12 timezone. It's string
-    representationformatted is YYYYMMDD. Times Square treats DayObs parameters
-    as strings, although some applicatinos may use them as integers.
+    representation formatted is YYYYMMDD. Times Square parameters validate
+    dayobs parameters as int types in notebook code.
+    integers.
     """
 
     tz = timezone(-timedelta(hours=12))
@@ -56,7 +57,7 @@ def validate_default(self) -> bool:
         else:
             return False
 
-    def cast_value(self, v: Any) -> str:
+    def cast_value(self, v: Any) -> int:
         """Cast a value to its Python type."""
         try:
             # Parse a YYYYMMDD string, integer, date object, or datetime object
@@ -74,7 +75,7 @@ def cast_value(self, v: Any) -> str:
         except Exception as e:
             raise PageParameterValueCastingError.for_value(v, "date") from e
 
-    def _cast_string(self, v: str) -> str:
+    def _cast_string(self, v: str) -> int:
         """Cast a string value to the DayObs format."""
         match = re.match(r"^\d{8}$", v)
         if not match:
@@ -85,15 +86,15 @@ def _cast_string(self, v: str) -> str:
         day = int(v[6:8])
         return self._cast_date(date(year, month, day))
 
-    def _cast_integer(self, v: int) -> str:
+    def _cast_integer(self, v: int) -> int:
         """Cast an integer value to the DayObs format."""
         return self._cast_string(str(v))
 
-    def _cast_date(self, v: date) -> str:
+    def _cast_date(self, v: date) -> int:
         """Cast a date object to the DayObs format."""
-        return v.strftime("%Y%m%d")
+        return int(v.strftime("%Y%m%d"))
 
-    def _cast_datetime(self, v: datetime) -> str:
+    def _cast_datetime(self, v: datetime) -> int:
         """Cast a datetime object to the DayObs format."""
         if v.tzinfo is not None:
             # Convert to UTC-12 timezone
@@ -104,22 +105,24 @@ def _cast_datetime(self, v: datetime) -> str:
         return self._cast_date(v.date())
 
     def create_python_assignment(self, name: str, value: Any) -> str:
-        date_value = self.cast_value(value)
-        return f"{name} = {date_value!r}"
+        int_value = self.cast_value(value)
+        return f"{name} = {int_value}"
 
     def create_json_value(self, value: Any) -> str:
-        return self.cast_value(value)
+        return str(self.cast_value(value))
 
     def create_qs_value(self, value: Any) -> str:
-        return self.cast_value(value)
+        return str(self.cast_value(value))
 
     @property
     def default(self) -> str:
         if "X-Dynamic-Default" in self.schema:
             dynamic_default = DateDynamicDefault(
                 self.schema["X-Dynamic-Default"]
             )
-            return self.cast_value(
-                dynamic_default(datetime.now(tz=self.tz).date())
+            return str(
+                self.cast_value(
+                    dynamic_default(datetime.now(tz=self.tz).date())
+                )
             )
-        return self.cast_value(self.schema["default"])
+        return str(self.cast_value(self.schema["default"]))

src/timessquare/domain/pageparameters/_pageparameters.py

@@ -22,9 +22,10 @@
 from ._booleanparameter import BooleanParameterSchema
 from ._dateparameter import DateParameterSchema
 from ._datetimeparameter import DatetimeParameterSchema
+from ._dayobsdateparameter import DayObsDateParameterSchema
+from ._dayobsparameter import DayObsParameterSchema
 from ._integerparameter import IntegerParameterSchema
 from ._numberparameter import NumberParameterSchema
-from ._obsdateparameter import ObsDateParameterSchema
 from ._schemabase import PageParameterSchema
 from ._stringparameter import StringParameterSchema
 
@@ -60,7 +61,9 @@ def create_page_parameter_schema(
     elif schema_type == "boolean":
         return BooleanParameterSchema(validator=validator)
     elif schema_type == "string" and schema_format == "dayobs":
-        return ObsDateParameterSchema(validator=validator)
+        return DayObsParameterSchema(validator=validator)
+    elif schema_type == "string" and schema_format == "dayobs-date":
+        return DayObsDateParameterSchema(validator=validator)
     elif schema_type == "string" and schema_format == "date":
         return DateParameterSchema(validator=validator)
     elif schema_type == "string" and schema_format == "date-time":

src/timessquare/storage/github/settingsfiles/_parameterschema.py

@@ -46,13 +46,14 @@ class ParameterSchemaModel(BaseModel):
     ]
 
     format: Annotated[
-        Literal["date", "date-time", "dayobs"] | None,
+        Literal["date", "date-time", "dayobs", "dayobs-date"] | None,
         Field(
             title="The JSON schema format",
             description=(
                 "For example, the format of a date or time. Only used for "
                 "the string type. Times Square also supports extensions to "
-                "format: 'dayobs' for Rubin DayObs dates."
+                "format: 'dayobs' for Rubin DayObs dates and 'dayobs-date' "
+                "for Rubin DayObs dates with dashes."
             ),
         ),
     ] = None
@@ -120,6 +121,11 @@ def to_parameter_schema(self, name: str) -> PageParameterSchema:
         if "format" in json_schema and json_schema["format"] == "dayobs":
             del json_schema["format"]
             json_schema["X-TS-Format"] = "dayobs"
+        elif (
+            "format" in json_schema and json_schema["format"] == "dayobs-date"
+        ):
+            del json_schema["format"]
+            json_schema["X-TS-Format"] = "dayobs-date"
         return create_and_validate_parameter_schema(
             name=name, json_schema=json_schema
         )
@@ -133,10 +139,11 @@ def check_dynamic_default(self) -> Self:
             if self.type != JsonSchemaTypeEnum.string or self.format not in {
                 "date",
                 "dayobs",
+                "dayobs-date",
             }:
                 raise ValueError(
                     "dynamic_default can only be set when type is 'string' "
-                    "and format is 'date' or 'dayobs'. "
+                    "and format is 'date', 'dayobs', or 'dayobs-date'. "
                 )
         return self
 
@@ -148,7 +155,7 @@ def check_dynamic_default_pattern(self) -> Self:
         if (
             self.dynamic_default is not None
             and self.type == JsonSchemaTypeEnum.string
-            and self.format in {"date", "dayobs"}
+            and self.format in {"date", "dayobs", "dayobs-date"}
         ):
             if not DYNAMIC_DATE_PATTERN.match(self.dynamic_default):
                 raise ValueError(