Skip to content

Commit

Permalink
Polish docstring
Browse files Browse the repository at this point in the history
  • Loading branch information
ddelange committed Dec 10, 2024
1 parent 1dcc544 commit ea0509a
Showing 1 changed file with 18 additions and 17 deletions.
35 changes: 18 additions & 17 deletions src/marshmallow/fields.py
Original file line number Diff line number Diff line change
Expand Up @@ -1436,44 +1436,45 @@ 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``.
Float Caveats
-------------
Use of `float` when (de)serializing may result in data precision loss due
Use of `float` when serializing may result in data precision loss due
to the way machines handle floating point values.
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.
"""

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

0 comments on commit ea0509a

Please sign in to comment.