Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Deprecate TimeDelta serialization_type parameter #2654

Open
wants to merge 3 commits into
base: dev
Choose a base branch
from
Open

Deprecate TimeDelta serialization_type parameter #2654

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1dcc544
Avoid silent integer downcast in TimeDelta.deserialize
ddelange Dec 10, 2024
0755fe1
Polish docstring
ddelange Dec 10, 2024
3470680
Deprecate TimeDelta serialization_type parameter
ddelange Dec 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 22 additions & 20 deletions src/marshmallow/fields.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1436,44 +1436,46 @@ def _make_object_from_format(value, data_format):

class TimeDelta(Field):
"""A field that (de)serializes a :class:`datetime.timedelta` object to an
integer or float and vice versa. The integer or float can represent the
number of days, seconds or microseconds.
integer or float. The integer or float can represent any time unit that the
:class:`datetime.timedelta` constructor supports.

:param precision: Influences how the integer or float is interpreted during
(de)serialization. Must be 'days', 'seconds', 'microseconds',
'milliseconds', 'minutes', 'hours' or 'weeks'.
:param serialization_type: Whether to (de)serialize to a `int` or `float`.
:param precision: The time unit used for (de)serialization. Must be one of 'weeks',
'days', 'hours', 'minutes', 'seconds', 'milliseconds' or 'microseconds'.
:param serialization_type: Whether to serialize to an `int` or `float`.
Ignored during deserialization: both `int` and `float` inputs are supported.
:param kwargs: The same keyword arguments that :class:`Field` receives.

Integer Caveats
---------------
Any fractional parts (which depends on the precision used) will be truncated
when serializing using `int`.
When serializing using ``serialization_type=int`` and depending on the ``precision``
used, any fractional parts might be truncated (downcast to integer).

Float Caveats
-------------
Use of `float` when (de)serializing may result in data precision loss due
to the way machines handle floating point values.
Precision loss may occur when serializing a highly precise :class:`datetime.timedelta`
object using ``serialization_type=float`` and a big ``precision`` unit due to floating
point arithmetics.

Regardless of the precision chosen, the fractional part when using `float`
will always be truncated to microseconds.
For example, `1.12345` interpreted as microseconds will result in `timedelta(microseconds=1)`.
When necessary, the :class:`datetime.timedelta` constructor rounds `float` inputs
to whole microseconds during initialization of the object. As a result, deserializing
a `float` might be subject to rounding, regardless of `precision`. For example,
``TimeDelta().deserialize("1.1234567") == timedelta(seconds=1, microseconds=123457)``.

.. versionchanged:: 2.0.0
Always serializes to an integer value to avoid rounding errors.
Add `precision` parameter.
.. versionchanged:: 3.17.0
Allow (de)serialization to `float` through use of a new `serialization_type` parameter.
`int` is the default to retain previous behaviour.
Allow serialization to `float` through use of a new `serialization_type` parameter.
Defaults to `int` for backwards compatibility.
Copy link
Member

Choose a reason for hiding this comment

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

Should we add a new versionchanged line here?

Copy link
Author

Choose a reason for hiding this comment

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

Never truncate a `float` to `int` during deserialization.

too concise?

Copy link
Author

Choose a reason for hiding this comment

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

or maybe

Never truncate a `float` to an `int` before deserializing it into a :class:`datetime.timedelta`.

"""

WEEKS = "weeks"
DAYS = "days"
HOURS = "hours"
MINUTES = "minutes"
SECONDS = "seconds"
MICROSECONDS = "microseconds"
MILLISECONDS = "milliseconds"
MINUTES = "minutes"
HOURS = "hours"
WEEKS = "weeks"
MICROSECONDS = "microseconds"

#: Default error messages.
default_error_messages = {
Expand Down Expand Up @@ -1526,7 +1528,7 @@ def _serialize(self, value, attr, obj, **kwargs):

def _deserialize(self, value, attr, data, **kwargs):
try:
value = self.serialization_type(value)
value = float(value)
ddelange marked this conversation as resolved.
Show resolved Hide resolved
except (TypeError, ValueError) as error:
raise self.make_error("invalid") from error

Expand Down
25 changes: 16 additions & 9 deletions tests/test_deserialization.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -709,6 +709,13 @@ def test_timedelta_field_deserialization(self):
assert result.seconds == 42
assert result.microseconds == 0

field = fields.TimeDelta()
result = field.deserialize("42.9")
assert isinstance(result, dt.timedelta)
assert result.days == 0
assert result.seconds == 42
assert result.microseconds == 900000

field = fields.TimeDelta(fields.TimeDelta.SECONDS)
result = field.deserialize(100000)
assert result.days == 1
Expand Down Expand Up @@ -741,7 +748,7 @@ def test_timedelta_field_deserialization(self):
assert isinstance(result, dt.timedelta)
assert result.days == 0
assert result.seconds == 12
assert result.microseconds == 0
assert result.microseconds == 900000
ddelange marked this conversation as resolved.
Show resolved Hide resolved

field = fields.TimeDelta(fields.TimeDelta.WEEKS)
result = field.deserialize(1)
Expand Down Expand Up @@ -772,7 +779,7 @@ def test_timedelta_field_deserialization(self):
assert result.microseconds == 456000

total_microseconds_value = 322.0
field = fields.TimeDelta(fields.TimeDelta.MICROSECONDS, float)
field = fields.TimeDelta(fields.TimeDelta.MICROSECONDS)
result = field.deserialize(total_microseconds_value)
assert isinstance(result, dt.timedelta)
unit_value = dt.timedelta(microseconds=1).total_seconds()
Expand All @@ -781,7 +788,7 @@ def test_timedelta_field_deserialization(self):
)

total_microseconds_value = 322.12345
field = fields.TimeDelta(fields.TimeDelta.MICROSECONDS, float)
field = fields.TimeDelta(fields.TimeDelta.MICROSECONDS)
result = field.deserialize(total_microseconds_value)
assert isinstance(result, dt.timedelta)
unit_value = dt.timedelta(microseconds=1).total_seconds()
Expand All @@ -790,7 +797,7 @@ def test_timedelta_field_deserialization(self):
)

total_milliseconds_value = 322.223
field = fields.TimeDelta(fields.TimeDelta.MILLISECONDS, float)
field = fields.TimeDelta(fields.TimeDelta.MILLISECONDS)
result = field.deserialize(total_milliseconds_value)
assert isinstance(result, dt.timedelta)
unit_value = dt.timedelta(milliseconds=1).total_seconds()
Expand All @@ -799,34 +806,34 @@ def test_timedelta_field_deserialization(self):
)

total_seconds_value = 322.223
field = fields.TimeDelta(fields.TimeDelta.SECONDS, float)
field = fields.TimeDelta(fields.TimeDelta.SECONDS)
result = field.deserialize(total_seconds_value)
assert isinstance(result, dt.timedelta)
assert math.isclose(result.total_seconds(), total_seconds_value)

total_minutes_value = 322.223
field = fields.TimeDelta(fields.TimeDelta.MINUTES, float)
field = fields.TimeDelta(fields.TimeDelta.MINUTES)
result = field.deserialize(total_minutes_value)
assert isinstance(result, dt.timedelta)
unit_value = dt.timedelta(minutes=1).total_seconds()
assert math.isclose(result.total_seconds() / unit_value, total_minutes_value)

total_hours_value = 322.223
field = fields.TimeDelta(fields.TimeDelta.HOURS, float)
field = fields.TimeDelta(fields.TimeDelta.HOURS)
result = field.deserialize(total_hours_value)
assert isinstance(result, dt.timedelta)
unit_value = dt.timedelta(hours=1).total_seconds()
assert math.isclose(result.total_seconds() / unit_value, total_hours_value)

total_days_value = 322.223
field = fields.TimeDelta(fields.TimeDelta.DAYS, float)
field = fields.TimeDelta(fields.TimeDelta.DAYS)
result = field.deserialize(total_days_value)
assert isinstance(result, dt.timedelta)
unit_value = dt.timedelta(days=1).total_seconds()
assert math.isclose(result.total_seconds() / unit_value, total_days_value)

total_weeks_value = 322.223
field = fields.TimeDelta(fields.TimeDelta.WEEKS, float)
field = fields.TimeDelta(fields.TimeDelta.WEEKS)
result = field.deserialize(total_weeks_value)
assert isinstance(result, dt.timedelta)
unit_value = dt.timedelta(weeks=1).total_seconds()
Expand Down
Loading