Skip to content

fix(serializer): serialize datetime.time and timedelta values (#20158) - #2131

Open
ShayanMuhammad-CS wants to merge 2 commits into
langfuse:mainfrom
ShayanMuhammad-CS:fix/serializer-time-and-timedelta
Open

ShayanMuhammad-CS wants to merge 2 commits into
langfuse:mainfrom
ShayanMuhammad-CS:fix/serializer-time-and-timedelta

Conversation

@ShayanMuhammad-CS

@ShayanMuhammad-CS ShayanMuhammad-CS commented Nov 15, 2026 •

Copy link
Copy Markdown

Description

Closes langfuse/langfuse#20158

Previously, EventSerializer in langfuse._utils.serializer handled date and datetime objects, but lacked branches for datetime.time and datetime.timedelta. Because standard time and timedelta instances lack __slots__ and __dict__, they fell through to the unhandled type-name fallback, serializing as "<time>" and "<timedelta>".

This also caused Pydantic models containing time or timedelta fields to lose their values, as model_dump() output recurses through EventSerializer.default().

Fix

  1. Added time and timedelta handling to EventSerializer._default_inner.
  2. Serializes datetime.time via obj.isoformat().
  3. Serializes datetime.timedelta via standard ISO 8601 duration format (e.g. "PT5M", "PT1M30S", "-PT45S"), using pydantic_core.to_jsonable_python with a zero-dependency fallback _timedelta_to_iso8601, ensuring 100% schema alignment with Pydantic's model_dump_json().

Testing

Added 6 unit tests to tests/unit/test_serializer.py:

  • test_time: verifies ISO 8601 formatting ("09:30:00").
  • test_time_with_microseconds_and_timezone: verifies fractional seconds and timezone offset.
  • test_timedelta: verifies ISO 8601 duration formatting ("PT1M30S").
  • test_timedelta_fractional_and_negative: verifies milliseconds ("PT0.25S") and negative intervals ("-PT45S").
  • test_pydantic_model_with_time_and_timedelta: verifies nested Pydantic model serialization ("timeout": "PT5M").
  • test_dict_with_time_and_timedelta: verifies dictionary values ("duration": "PT1H30M").

All tests passing:

tests/unit/test_serializer.py::test_datetime PASSED
tests/unit/test_serializer.py::test_time PASSED
tests/unit/test_serializer.py::test_time_with_microseconds_and_timezone PASSED
tests/unit/test_timedelta PASSED
tests/unit/test_timedelta_fractional_and_negative PASSED
tests/unit/test_pydantic_model_with_time_and_timedelta PASSED
tests/unit/test_dict_with_time_and_timedelta PASSED

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.

@CLAassistant

CLAassistant commented Nov 15, 2026 •

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

@chrikrah chrikrah left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ShayanMuhammad-CS The time and timedelta branches are correct, and all six new tests fail against base and pass here.

non-blocking: #20158 already offered an ISO 8601 duration as the other option, and pydantic picks that one. The same model reads differently in langfuse and in pydantic's own JSON, and a bare 300.0 loses its unit. It's cheap to pick now, before traces store floats.

$ python -m pytest tests/unit/test_serializer.py -q -p no:cacheprovider   # Python 3.12.14, langfuse imported from the export
56 passed                  # head 8d7553f
6 failed, 50 passed        # serializer.py from base 077448c
$ python lf_td.py          # pydantic 2.14.3, M(at=time(14, 15), timeout=timedelta(minutes=5))
pydantic model_dump_json: {"at":"14:15:00","timeout":"PT5M"}
EventSerializer:          {"at": "14:15:00", "timeout": 300.0}
# not run: e2e tests against a Langfuse server

Is there a consumer that needs seconds, or would PT5M work?

@ShayanMuhammad-CS

Copy link
Copy Markdown
Author

Thanks for the thorough review and benchmarking, @chrikrah!

Switching timedelta to ISO 8601 duration strings (PT5M) makes complete sense:

  1. Consistency with Pydantic: Eliminates schema divergence between Langfuse's EventSerializer and Pydantic's native model_dump_json().
  2. Unit Preservation: A raw float (300.0) loses the time unit, whereas ISO 8601 is explicit, self-documenting, and standardized across observability backends.
  3. No Legacy Debt: Adopting ISO 8601 now before floats are committed into trace storage avoids backwards-compatibility migration headaches later.

I will update the timedelta serialization branch to format as ISO 8601 durations and update the corresponding unit tests accordingly.

@ShayanMuhammad-CS

Copy link
Copy Markdown
Author

Hi @chrikrah,

Updated in commit 9e42e37:

  • Switched datetime.timedelta serialization to standard ISO 8601 duration strings (e.g. "PT5M", "PT1M30S", "-PT45S"), utilizing pydantic_core.to_jsonable_python with a zero-dependency _timedelta_to_iso8601 fallback.
  • Updated unit tests in tests/unit/test_serializer.py to assert against ISO 8601 formatting for positive, negative, fractional, dictionary, and nested Pydantic model cases.
  • Aligned PR description with the updated format.

Ready for review and merge!

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

bug(sdk-python): datetime.time and timedelta values are recorded as "<time>" and "<timedelta>"

3 participants