feat(convert): add datetime, dict/list, and URL type support

Extend convert_value to handle three previously unsupported proto
TypedValue variants:

- datetime via datetime.fromisoformat (handles RFC 3339 Z suffix,
  requires Python 3.11+)
- dict/list via json.loads with type-mismatch guard
- URL as a str alias exported from the top-level package

Add tests for all new types including invalid-input and wrong-type
error paths. Update the unsupported-type test to use bytes instead
of list.

Co-Authored-By: Claude <noreply@anthropic.com>
Closes #50

Author: zeevdr

sdk/src/opendecree/__init__.py

@@ -23,6 +23,7 @@
     TypeMismatchError,
     UnavailableError,
 )
+from opendecree._convert import URL
 from opendecree.types import Change, ConfigValue, FieldUpdate, ServerVersion
 from opendecree.watcher import ConfigWatcher, WatchedField
 
@@ -48,6 +49,7 @@
     "RetryConfig",
     "ServerVersion",
     "TypeMismatchError",
+    "URL",
     "UnavailableError",
     "WatchedField",
     "__version__",

sdk/src/opendecree/_convert.py

@@ -2,15 +2,19 @@
 
 The server stores all values internally as strings. The SDK converts between
 the proto TypedValue representation and Python types (str, int, float, bool,
-timedelta) at the boundary.
+datetime, timedelta, dict, list) at the boundary.
 """
 
 from __future__ import annotations
 
-from datetime import timedelta
+import json
+from datetime import datetime, timedelta
 
 from opendecree.errors import TypeMismatchError
 
+# Type alias for url-typed fields — semantically distinct from plain str.
+URL = str
+
 
 def _parse_timedelta(s: str) -> timedelta:
     """Parse a Go-style duration string (e.g., '24h', '30m', '500ms') to timedelta.
@@ -60,7 +64,8 @@ def _parse_timedelta(s: str) -> timedelta:
 def convert_value(raw: str, target_type: type) -> object:
     """Convert a raw string value to the target Python type.
 
-    Supported types: str, int, float, bool, timedelta.
+    Supported types: str, int, float, bool, datetime, timedelta, dict, list.
+    URL is an alias for str and is handled identically.
 
     Raises:
         TypeMismatchError: If the value cannot be converted to the target type.
@@ -78,8 +83,15 @@ def convert_value(raw: str, target_type: type) -> object:
             if raw.lower() in ("false", "0"):
                 return False
             raise ValueError(f"cannot convert {raw!r} to bool")
+        if target_type is datetime:
+            return datetime.fromisoformat(raw)
         if target_type is timedelta:
             return _parse_timedelta(raw)
+        if target_type is dict or target_type is list:
+            result = json.loads(raw)
+            if not isinstance(result, target_type):
+                raise ValueError(f"expected {target_type.__name__}, got {type(result).__name__}")
+            return result
     except (ValueError, OverflowError) as e:
         raise TypeMismatchError(f"cannot convert {raw!r} to {target_type.__name__}: {e}") from e
 

sdk/tests/test_convert.py

@@ -1,10 +1,10 @@
 """Tests for type conversion."""
 
-from datetime import timedelta
+from datetime import datetime, timedelta, timezone
 
 import pytest
 
-from opendecree._convert import _parse_timedelta, convert_value, typed_value_to_string
+from opendecree._convert import URL, _parse_timedelta, convert_value, typed_value_to_string
 from opendecree.errors import TypeMismatchError
 
 
@@ -78,7 +78,60 @@ def test_convert_timedelta_invalid():
 
 def test_convert_unsupported_type():
     with pytest.raises(TypeMismatchError, match="unsupported type"):
-        convert_value("hello", list)  # type: ignore[arg-type]
+        convert_value("hello", bytes)  # type: ignore[arg-type]
+
+
+def test_convert_datetime_utc():
+    result = convert_value("2023-11-14T22:13:20Z", datetime)
+    assert isinstance(result, datetime)
+    assert result == datetime(2023, 11, 14, 22, 13, 20, tzinfo=timezone.utc)
+
+
+def test_convert_datetime_with_offset():
+    result = convert_value("2023-11-14T22:13:20+00:00", datetime)
+    assert isinstance(result, datetime)
+    assert result.year == 2023
+
+
+def test_convert_datetime_invalid():
+    with pytest.raises(TypeMismatchError, match="cannot convert"):
+        convert_value("not-a-datetime", datetime)
+
+
+def test_convert_dict():
+    result = convert_value('{"key": "val", "n": 1}', dict)
+    assert result == {"key": "val", "n": 1}
+
+
+def test_convert_dict_invalid_json():
+    with pytest.raises(TypeMismatchError, match="cannot convert"):
+        convert_value("not-json", dict)
+
+
+def test_convert_dict_wrong_type():
+    with pytest.raises(TypeMismatchError, match="cannot convert"):
+        convert_value("[1, 2]", dict)
+
+
+def test_convert_list():
+    result = convert_value('[1, "two", true]', list)
+    assert result == [1, "two", True]
+
+
+def test_convert_list_invalid_json():
+    with pytest.raises(TypeMismatchError, match="cannot convert"):
+        convert_value("not-json", list)
+
+
+def test_convert_list_wrong_type():
+    with pytest.raises(TypeMismatchError, match="cannot convert"):
+        convert_value('{"a": 1}', list)
+
+
+def test_convert_url():
+    result = convert_value("https://example.com/path", URL)
+    assert result == "https://example.com/path"
+    assert isinstance(result, str)
 
 
 def test_parse_timedelta_empty():