1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
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'
```
|
