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
|
# Instantiation
There are several different methods available to create a new `DateTime` instance.
First there is the main `datetime()` helper.
```python
>>> import pendulum
>>> dt = pendulum.datetime(2015, 2, 5)
>>> isinstance(dt, datetime)
True
>>> dt.timezone.name
'UTC'
```
`datetime()` sets the time to `00:00:00` if it's not specified,
and the timezone (the `tz` keyword argument) to `UTC`.
Otherwise it can be a `Timezone` instance or simply a string timezone value.
```python
>>> import pendulum
>>> pendulum.datetime(2015, 2, 5, tz='Europe/Paris')
>>> tz = pendulum.timezone('Europe/Paris')
>>> pendulum.datetime(2015, 2, 5, tz=tz)
```
!!!note
Supported strings for timezones are the one provided
by the [IANA time zone database](https://www.iana.org/time-zones).
The special `local` string is also supported and will return your current timezone.
!!!warning
The `tz` argument is keyword-only, unlike in version `1.x`
The `local()` helper is similar to `datetime()` but automatically sets the
timezone to the local timezone.
```python
>>> import pendulum
>>> dt = pendulum.local(2015, 2, 5)
>>> print(dt.timezone.name)
'America/Toronto'
```
!!!note
`local()` is just an alias for `datetime(..., tz='local')`.
There is also the `now()` method.
```python
>>> import pendulum
>>> now = pendulum.now()
>>> now_in_london_tz = pendulum.now('Europe/London')
>>> now_in_london_tz.timezone_name
'Europe/London'
```
To accompany `now()`, a few other static instantiation helpers exist to create known instances.
The only thing to really notice here is that `today()`, `tomorrow()` and `yesterday()`,
besides behaving as expected, all accept a timezone parameter
and each has their time value set to `00:00:00`.
```python
>>> now = pendulum.now()
>>> print(now)
'2016-06-28T16:51:45.978473-05:00'
>>> today = pendulum.today()
>>> print(today)
'2016-06-28T00:00:00-05:00'
>>> tomorrow = pendulum.tomorrow('Europe/London')
>>> print(tomorrow)
'2016-06-29T00:00:00+01:00'
>>> yesterday = pendulum.yesterday()
>>> print(yesterday)
'2016-06-27T00:00:00-05:00'
```
Pendulum enforces timezone aware datetimes, and using them is the preferred and recommended way
of using the library. However, if you really need a **naive** `DateTime` object, the `naive()` helper
is there for you.
```python
>>> import pendulum
>>> naive = pendulum.naive(2015, 2, 5)
>>> naive.timezone
None
```
The next helper, `from_format()`, is similar to the native `datetime.strptime()` function
but uses custom tokens to create a `DateTime` instance.
```python
>>> dt = pendulum.from_format('1975-05-21 22', 'YYYY-MM-DD HH')
>>> print(dt)
'1975-05-21T22:00:00+00:00'
```
!!!note
To see all the available tokens, you can check the [Formatter](#formatter) section.
It also accepts a `tz` keyword argument to specify the timezone:
```python
>>> dt = pendulum.from_format('1975-05-21 22', 'YYYY-MM-DD HH', tz='Europe/London')
'1975-05-21T22:00:00+01:00'
```
The final helper is for working with unix timestamps.
`from_timestamp()` will create a `DateTime` instance equal to the given timestamp
and will set the timezone as well or default it to `UTC`.
```python
>>> dt = pendulum.from_timestamp(-1)
>>> print(dt)
'1969-12-31T23:59:59+00:00'
>>> dt = pendulum.from_timestamp(-1, tz='Europe/London')
>>> print(dt)
'1970-01-01T00:59:59+01:00'
```
Finally, if you find yourself inheriting a `datetime.datetime` instance,
you can create a `DateTime` instance via the `instance()` function.
```python
>>> dt = datetime(2008, 1, 1)
>>> p = pendulum.instance(dt)
>>> print(p)
'2008-01-01T00:00:00+00:00'
```
|
