From ff35070aacb247c5e67ab50dd7b92a2054cc0e26 Mon Sep 17 00:00:00 2001 From: Adii Date: Thu, 4 Jun 2026 17:38:52 +0530 Subject: [PATCH] docs: add ISO 8601 duration parsing examples --- docs/docs/parsing.md | 87 ++++++++++++++++++++++++++++---------------- 1 file changed, 56 insertions(+), 31 deletions(-) diff --git a/docs/docs/parsing.md b/docs/docs/parsing.md index dd78fd45..27cb9c0d 100644 --- a/docs/docs/parsing.md +++ b/docs/docs/parsing.md @@ -37,58 +37,57 @@ ParserError: Unable to parse string [31-01-01] '2031-01-01T00:00:00+00:00' ``` - ## RFC 3339 -| String | Output | -| --------------------------------- | ------------------------------------------| -| 1996-12-19T16:39:57-08:00 | 1996-12-19T16:39:57-08:00 | -| 1990-12-31T23:59:59Z | 1990-12-31T23:59:59+00:00 | +| String | Output | +| ------------------------- | ------------------------- | +| 1996-12-19T16:39:57-08:00 | 1996-12-19T16:39:57-08:00 | +| 1990-12-31T23:59:59Z | 1990-12-31T23:59:59+00:00 | ## ISO 8601 ### Datetime -| String | Output | -| --------------------------------- | ----------------------------------------- | -| 20161001T143028+0530 | 2016-10-01T14:30:28+05:30 | -| 20161001T14 | 2016-10-01T14:00:00+00:00 | +| String | Output | +| -------------------- | ------------------------- | +| 20161001T143028+0530 | 2016-10-01T14:30:28+05:30 | +| 20161001T14 | 2016-10-01T14:00:00+00:00 | ### Date -| String | Output | -| --------------------------------- | ----------------------------------------- | -| 2012 | 2012-01-01T00:00:00+00:00 | -| 2012-05-03 | 2012-05-03T00:00:00+00:00 | -| 20120503 | 2012-05-03T00:00:00+00:00 | -| 2012-05 | 2012-05-01T00:00:00+00:00 | +| String | Output | +| ---------- | ------------------------- | +| 2012 | 2012-01-01T00:00:00+00:00 | +| 2012-05-03 | 2012-05-03T00:00:00+00:00 | +| 20120503 | 2012-05-03T00:00:00+00:00 | +| 2012-05 | 2012-05-01T00:00:00+00:00 | ### Ordinal day -| String | Output | -| ---------------------------------- | ----------------------------------------- | -| 2012-007 | 2012-01-07T00:00:00+00:00 | -| 2012007 | 2012-01-07T00:00:00+00:00 | +| String | Output | +| -------- | ------------------------- | +| 2012-007 | 2012-01-07T00:00:00+00:00 | +| 2012007 | 2012-01-07T00:00:00+00:00 | ### Week number -| String | Output | -| --------------------------------- | ----------------------------------------- | -| 2012-W05 | 2012-01-30T00:00:00+00:00 | -| 2012W05 | 2012-01-30T00:00:00+00:00 | -| 2012-W05-5 | 2012-02-03T00:00:00+00:00 | -| 2012W055 | 2012-02-03T00:00:00+00:00 | +| String | Output | +| ---------- | ------------------------- | +| 2012-W05 | 2012-01-30T00:00:00+00:00 | +| 2012W05 | 2012-01-30T00:00:00+00:00 | +| 2012-W05-5 | 2012-02-03T00:00:00+00:00 | +| 2012W055 | 2012-02-03T00:00:00+00:00 | ### Time When passing only time information the date will default to today. -| String | Output | -| --------------------------------- | ------------------------------------------ | -| 00:00 | 2016-12-17T00:00:00+00:00 | -| 12:04:23 | 2016-12-17T12:04:23+00:00 | -| 120423 | 2016-12-17T12:04:23+00:00 | -| 12:04:23.45 | 2016-12-17T12:04:23.450000+00:00 | +| String | Output | +| ----------- | -------------------------------- | +| 00:00 | 2016-12-17T00:00:00+00:00 | +| 12:04:23 | 2016-12-17T12:04:23+00:00 | +| 120423 | 2016-12-17T12:04:23+00:00 | +| 12:04:23.45 | 2016-12-17T12:04:23.450000+00:00 | ### Intervals @@ -112,3 +111,29 @@ When passing only time information the date will default to today. >>> pendulum.parse('12:04:23', exact=True) Time(12, 04, 23) ``` + +### Durations + +`pendulum.parse()` also supports ISO 8601 duration strings. + +```python +>>> import pendulum + +>>> pendulum.parse("P1D", exact=True) +Duration(days=1) + +>>> pendulum.parse("PT2H30M", exact=True) +Duration(hours=2, minutes=30) + +>>> pendulum.parse("P1DT2H") +Duration(days=1, hours=2) +``` + +Examples of supported duration formats: + +| String | Meaning | +| ------ | ----------------- | +| P1D | 1 day | +| PT2H | 2 hours | +| PT30M | 30 minutes | +| P1DT2H | 1 day and 2 hours |