On Sat, Jun 20, 2026, at 5:52 AM, Tim Düsterhus wrote: >> My main pushback, I think, is the fromIso8601String() method, which is >> not at all self-descriptive. Presuming it means the format accepted by >> DatePeriod (give or take bugs), that's not self-evident anywhere in the >> RFC, or the method name. > > The doc comment for the method explains “Parse a ISO-8601 period.” and > even the automated AI summary in Google (almost) correctly tells right > away “An ISO-8601 period (or duration) represents an amount of time > using the format P[n]Y[n]M[n]W[n]T[n]H[n]M[n]S.” There is a small > mistake in there in that `T` doesn't have a preceding `[n]`, but it > gives the correct idea of what is being expected there. And of course > all the search results point towards the same thing. > >> I can easily see people who aren't familiar with that period format >> (which is, I suspect, most people) trying to use "5:23:44" or similar >> human time formats instead, which will break. But that format actually >> feels more useful, and is also defined somewhere in ISO8601 (as part of >> the full date/time string if nothing else), so the method name is >> ambiguous. > > “break” is a strong word there. It will be rejected with a `ValueError` > as an invalid input. > >> I think we do need to come up with a better, more self-documenting name >> for that operation, and consider if we also want a >> fromHumanTimeString() that accepts "5:23"44" type strings. > > Without checking with Derick, I would be open to renaming the method to > `fromIso8601PeriodString()`. While that would be quite long, (fuzzy) > auto-completion should handle that. And I suspect that constructor would > also be used comparatively rarely. > > If that name makes sense to you, I'll discuss all the feedback (also > from the other mails) that I didn't outright reject myself with Derick > in bulk in the next days :-)
It's the Iso8601 in there that feels confusing. fromTimePeriod() or fromPeriodString() or something like that seems like it would be more reader-friendly. I know we used RFC names in the Uri component, but in that case there's two competing specifications that we're trying to support so using those technical names in namespaces made sense. However, that's not generally true; including random spec IDs in method names is not helpful, and as far as I am aware there's only one type of "time period string" on the market that we need to worry about so there is no risk of the same type of confusion. (If there are others, please let me know.) > The “from human time” one I would reject outright, because of the > ambiguity with regard to how fractional seconds are represented. In the > wild I've sometime seen `.` as the separator between seconds and > fractional seconds, but also `:`, which means that the format would be > ambiguous. And I'm sure there are also going to be differences between > languages, just like some countries use 24h formats and others use 12h. > And then of course, what even is a “human time”. And with regard to the > flexibility in inputs that `strtotime()` accepts, is `"12 hours and 45 > seconds"` a “human time”? Is `"12.5h"` a “human time”? Is `"500µs"` a > “human time” (notably the µ character is not in 7-bit ASCII)? I can see this being punt-able to future scope, though I think an argument could be made for supporting "12 hours and 45 seconds" as a constructor type. Especially as it is supported in other parts of the current date/time API. --Larry Garfield
