diff options
Diffstat (limited to 'docs/docs/string_formatting.md')
| -rw-r--r-- | docs/docs/string_formatting.md | 175 |
1 files changed, 175 insertions, 0 deletions
diff --git a/docs/docs/string_formatting.md b/docs/docs/string_formatting.md new file mode 100644 index 0000000..91b95fc --- /dev/null +++ b/docs/docs/string_formatting.md @@ -0,0 +1,175 @@ +# String formatting + +The `__str__` magic method is defined to allow `DateTime` instances to be printed +as a pretty date string when used in a string context. + +The default string representation is the same as the one returned by the `isoformat()` method. + +```python +>>> import pendulum + +>>> dt = pendulum.datetime(1975, 12, 25, 14, 15, 16) +>>> print(dt) +'1975-12-25T14:15:16+00:00' + +>>> dt.to_date_string() +'1975-12-25' + +>>> dt.to_formatted_date_string() +'Dec 25, 1975' + +>>> dt.to_time_string() +'14:15:16' + +>>> dt.to_datetime_string() +'1975-12-25 14:15:16' + +>>> dt.to_day_datetime_string() +'Thu, Dec 25, 1975 2:15 PM' + +# You can also use the format() method +>>> dt.format('dddd Do [of] MMMM YYYY HH:mm:ss A') +'Thursday 25th of December 1975 02:15:16 PM' + +# Of course, the strftime method is still available +>>> dt.strftime('%A %-d%t of %B %Y %I:%M:%S %p') +'Thursday 25th of December 1975 02:15:16 PM' +``` + +!!!note + + For localization support see the [Localization](#localization) section. + +## Common Formats + + +The following are methods to display a `DateTime` instance as a common format: + +```python +>>> import pendulum + +>>> dt = pendulum.now() + +>>> dt.to_atom_string() +'1975-12-25T14:15:16-05:00' + +>>> dt.to_cookie_string() +'Thursday, 25-Dec-1975 14:15:16 EST' + +>>> dt.to_iso8601_string() +'1975-12-25T14:15:16-0500' + +>>> dt.to_rfc822_string() +'Thu, 25 Dec 75 14:15:16 -0500' + +>>> dt.to_rfc850_string() +'Thursday, 25-Dec-75 14:15:16 EST' + +>>> dt.to_rfc1036_string() +'Thu, 25 Dec 75 14:15:16 -0500' + +>>> dt.to_rfc1123_string() +'Thu, 25 Dec 1975 14:15:16 -0500' + +>>> dt.to_rfc2822_string() +'Thu, 25 Dec 1975 14:15:16 -0500' + +>>> dt.to_rfc3339_string() +'1975-12-25T14:15:16-05:00' + +>>> dt.to_rss_string() +'Thu, 25 Dec 1975 14:15:16 -0500' + +>>> dt.to_w3c_string() +'1975-12-25T14:15:16-05:00' +``` + +## Formatter + +Pendulum uses its own formatter when using the `format()` method. + +This format is more intuitive to use than the one used with `strftime()` +and supports more directives. + +```python +>>> import pendulum + +>>> dt = pendulum.datetime(1975, 12, 25, 14, 15, 16) +>>> dt.format('YYYY-MM-DD HH:mm:ss') +'1975-12-25 14:15:16' +``` + +### Tokens + +The following tokens are currently supported: + + +| | Token | Output | +| ------------------------------ | ------------- | ------------------------------------------ | +| **Year** | YYYY | 2000, 2001, 2002 ... 2012, 2013 | +| | YY | 00, 01, 02 ... 12, 13 | +| | Y | 2000, 2001, 2002 ... 2012, 2013 | +| **Quarter** | Q | 1 2 3 4 | +| | Qo | 1st 2nd 3rd 4th | +| **Month** | MMMM | January, February, March ... | +| | MMM | Jan, Feb, Mar ... | +| | MM | 01, 02, 03 ... 11, 12 | +| | M | 1, 2, 3 ... 11, 12 | +| | Mo | 1st 2nd ... 11th 12th | +| **Day of Year** | DDDD | 001, 002, 003 ... 364, 365 | +| | DDD | 1, 2, 3 ... 4, 5 | +| **Day of Month** | DD | 01, 02, 03 ... 30, 31 | +| | D | 1, 2, 3 ... 30, 31 | +| | Do | 1st, 2nd, 3rd ... 30th, 31st | +| **Day of Week** | dddd | Monday, Tuesday, Wednesday ... | +| | ddd | Mon, Tue, Wed ... | +| | dd | Mo, Tu, We ... | +| | d | 0, 1, 2 ... 6 | +| **Days of ISO Week** | E | 1, 2, 3 ... 7 | +| **Hour** | HH | 00, 01, 02 ... 23 | +| | H | 0, 1, 2 ... 23 | +| | hh | 01, 02, 03 ... 11, 12 | +| | h | 1, 2, 3 ... 11, 12 | +| **Minute** | mm | 00, 01, 02 ... 58, 59 | +| | m | 0, 1, 2 ... 58, 59 | +| **Second** | ss | 00, 01, 02 ... 58, 59 | +| | s | 0, 1, 2 ... 58, 59 | +| **Fractional Second** | S | 0 1 ... 8 9 | +| | SS | 00, 01, 02 ... 98, 99 | +| | SSS | 000 001 ... 998 999 | +| | SSSS ... | 000[0..] 001[0..] ... 998[0..] 999[0..] | +| | SSSSSS | | +| **AM / PM** | A | AM, PM | +| **Timezone** | Z | -07:00, -06:00 ... +06:00, +07:00 | +| | ZZ | -0700, -0600 ... +0600, +0700 | +| | z | Asia/Baku, Europe/Warsaw, GMT ... | +| | zz | EST CST ... MST PST | +| **Seconds timestamp** | X | 1381685817, 1234567890.123 | +| **Milliseconds timestamp** | x | 1234567890123 | + + +### Localized Formats + +Because preferred formatting differs based on locale, +there are a few tokens that can be used to format an instance based on its locale. + +| | | | +| ------------------------------------------------------ | ------------- | ------------------------------------------ | +| **Time** | LT | 8:30 PM | +| **Time with seconds** | LTS | 8:30:25 PM | +| **Month numeral, day of month, year** | L | 09/04/1986 | +| **Month name, day of month, year** | LL | September 4 1986 | +| **Month name, day of month, year, time** | LLL | September 4 1986 8:30 PM | +| **Month name, day of month, day of week, year, time** | LLLL | Thursday, September 4 1986 8:30 PM | + +### Escaping Characters + +To escape characters in format strings, you can wrap the characters in square brackets. + +```python +>>> import pendulum + +>>> dt = pendulum.now() +>>> dt.format('[today] dddd') +'today Sunday' +``` |