Support parsing human-friendly deltas?

[Ravencentric]

I have a couple places where I need to parse durations like 2h30m, 7d, 2h 30min, etc.

For some prior art, jiff supports this for its Span and SignedDuration types:

• https://docs.rs/jiff/latest/jiff/struct.Span.html#parsing-and-printing
• https://docs.rs/jiff/latest/jiff/struct.SignedDuration.html#parsing-and-printing

[ariebovenberg]

Hi, thanks for posting. I'm definitely considering this. My only concern at the moment is that this complicates the parse_iso family of methods. Since '30min' is definitely not ISO, would a separate method be needed? Or just support non-ISO in deltas parse_iso? Neither is particularly appealing. Perhaps a better option will present itself.

[Ravencentric]

I personally would prefer a seperate method, say TimeDelta.parse_friendly("2h 30m") so that I can opt-in to more lenient parsing and still have the choice of rejecting non-iso formats by using parse_iso. Alternatively, a more generic method, say from_str(iso_or_friendly) (like FromStr from Rust) or just parse(iso_or_friendly) but the former naming feels a bit out of place because there are no other from_* methods in whenever and the latter might be too generic.

[ariebovenberg]

The parse_friendly makes most sense to me too. I'm moving this to discussions until there is a consensus

[aquarhead]

I think this would be good but as I write it I think maybe the main "problem" would be localization.

We actually used jiff in a simple PyO3 wrapper to convert human readable duration string into ISO format and then parse_iso with whenever. However since jiff has only 1 span type it treats some common characters undesirably in some situations. For example 1m is always 1 minute - which would be the wrong convertion for DateDelta.

So we eventually rolled our own regex based parser with some extra behaviour such as treating pure numbers as days:

# This pattern will match any number followed by at least the first letter of days, weeks, months or years
DATEDELTA_PART_PATTERN = re.compile(r"(\d+)\s*(da?y?s?|we?e?k?s?|mo?n?t?h?s?|ye?a?r?s?)")

def _parse_string_to_datedelta(s: str) -> DateDelta:
    """Parse a human-readable or iso duration into a DateDelta."""
    s = s.strip().lower()

    if s.startswith("p"):
        try:
            return DateDelta.parse_iso(s)
        except ValueError:
            pass  # Try to use the generic parser instead

    matches = DATEDELTA_PART_PATTERN.findall(s)

    if len(matches) == 0:
        raise ValueError(f"No valid date parts found in the provided string '{s}'")

    years = 0
    months = 0
    weeks = 0
    days = 0

    for value, unit in matches:
        value = int(value)

        if unit.startswith("y"):
            years += value
        elif unit.startswith("m"):
            months += value
        elif unit.startswith("w"):
            weeks += value
        elif unit.startswith("d"):
            days += value

    return DateDelta(years=years, months=months, weeks=weeks, days=days)

Some extra sauce for Pydantic (as we currently use it)

def _friendly_datedelta_parser(value: Any) -> DateDelta:
    # The built-in DateDelta parser does not give a good error message.
    # So we create our own to improve the error messages generated by the AI model
    exc = PydanticCustomError(
        "invalid_duration_format",
        "Invalid input for duration parser: '{value}'",
        {"value": value},
    )

    try:
        if isinstance(value, DateDelta):
            return value

        elif isinstance(value, int | float):
            return DateDelta(days=int(value))

        elif isinstance(value, str) and value.isdigit():
            return DateDelta(days=int(value))

        elif isinstance(value, str):
            return _parse_string_to_datedelta(value)

        else:
            raise exc
    except ValueError as e:
        raise exc from e

type FriendlyDateDelta = Annotated[
    DateDelta,
    BeforeValidator(_friendly_datedelta_parser),
    WithJsonSchema(
        {
            "type": "string",
            "examples": ["1d", "2w", "3m", "4y", "1 day", "2 weeks", "3 months", "4 years"],
        }
    ),
]


_friendly_string_adapter = TypeAdapter(str, config=ConfigDict(coerce_numbers_to_str=True))

type FriendlyString = Annotated[str, BeforeValidator(_friendly_string_adapter.validate_python)]
"""Custom type which supports coercing numbers to strings. Use only if a specific field should allow this coercion."""