Skip to content

Commit 474f360

Browse files
sdispatersdispater
committed
Reorganizes docs.
1 parent 74726d6 commit 474f360

16 files changed

+1735
-1751
lines changed

‎docs/_docs/addition_subtraction.rst‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
Addition and Subtraction
2+
========================
3+
4+
To easily adding and subtracting time, you can use the ``add()`` and ``subtract()``
5+
methods.
6+
Each method returns a new ``Pendulum`` instance.
7+
8+
.. code-block:: python
9+
10+
import pendulum
11+
12+
dt = pendulum.create(2012, 1, 31, 0)
13+
14+
dt.to_datetime_string()
15+
'2012-01-31 00:00:00'
16+
17+
dt = dt.add(years=5)
18+
'2017-01-31 00:00:00'
19+
dt = dt.add(years=1)
20+
'2018-01-31 00:00:00'
21+
dt = dt.subtract(years=1)
22+
'2017-01-31 00:00:00'
23+
dt = dt.subtract(years=5)
24+
'2012-01-31 00:00:00'
25+
26+
dt = dt.add(months=60)
27+
'2017-01-31 00:00:00'
28+
dt = dt.add(months=1)
29+
'2017-02-28 00:00:00'
30+
dt = dt.subtract(months=1)
31+
'2017-01-28 00:00:00'
32+
dt = dt.subtract(months=60)
33+
'2012-01-28 00:00:00'
34+
35+
dt = dt.add(days=29)
36+
'2012-02-26 00:00:00'
37+
dt = dt.add(days=1)
38+
'2012-02-27 00:00:00'
39+
dt = dt.subtract(days=1)
40+
'2012-02-26 00:00:00'
41+
dt = dt.subtract(days=29)
42+
'2012-01-28 00:00:00'
43+
44+
dt = dt.add(weeks=3)
45+
'2012-02-18 00:00:00'
46+
dt = dt.add(weeks=1)
47+
'2012-02-25 00:00:00'
48+
dt = dt.subtract(weeks=1)
49+
'2012-02-18 00:00:00'
50+
dt = dt.subtract(weeks=3)
51+
'2012-01-28 00:00:00'
52+
53+
dt = dt.add(hours=24)
54+
'2012-01-29 00:00:00'
55+
dt = dt.add(hours=1)
56+
'2012-02-25 01:00:00'
57+
dt = dt.subtract(hours=1)
58+
'2012-02-29 00:00:00'
59+
dt = dt.subtract(hours=24)
60+
'2012-01-28 00:00:00'
61+
62+
dt = dt.add(minutes=61)
63+
'2012-01-28 01:01:00'
64+
dt = dt.add(minutes=1)
65+
'2012-01-28 01:02:00'
66+
dt = dt.subtract(minutes=1)
67+
'2012-01-28 01:01:00'
68+
dt = dt.subtract(minutes=24)
69+
'2012-01-28 00:00:00'
70+
71+
dt = dt.add(seconds=61)
72+
'2012-01-28 00:01:01'
73+
dt = dt.add(seconds=1)
74+
'2012-01-28 00:01:02'
75+
dt = dt.subtract(seconds=1)
76+
'2012-01-28 00:01:01'
77+
dt = dt.subtract(seconds=61)
78+
'2012-01-28 00:00:00'
79+
80+
dt = dt.add(years=3, months=2, days=6, hours=12, minutes=31, seconds=43)
81+
'2015-04-03 12:31:43'
82+
dt = dt.subtract(years=3, months=2, days=6, hours=12, minutes=31, seconds=43)
83+
'2012-01-28 00:00:00'
84+
85+
# You can also add or remove a timedelta
86+
dt.add_timedelta(timedelta(hours=3, minutes=4, seconds=5))
87+
'2012-01-28 03:04:05'
88+
dt.sub_timedelta(timedelta(hours=3, minutes=4, seconds=5))
89+
'2012-01-28 00:00:00'
90+
91+
.. note::
92+
93+
Passing negative values to ``add()`` is also possible and will act exactly
94+
like ``subtract()``

‎docs/_docs/attributes_properties.rst‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
Attributes and Properties
2+
=========================
3+
4+
Pendulum gives access to more attributes and properties than the default ``datetime`` class.
5+
6+
.. code-block:: python
7+
8+
import pendulum
9+
10+
dt = pendulum.parse('2012-9-5 23:26:11.123789')
11+
12+
# These properties specifically return integers
13+
dt.year
14+
2012
15+
dt.month
16+
9
17+
dt.day
18+
5
19+
dt.hour
20+
23
21+
dt.minute
22+
26
23+
dt.second
24+
11
25+
dt.microsecond
26+
123789
27+
dt.day_of_week
28+
3
29+
dt.day_of_year
30+
248
31+
dt.week_of_month
32+
1
33+
dt.week_of_year
34+
36
35+
dt.days_in_month
36+
30
37+
dt.timestamp()
38+
1346887571.123789
39+
dt.float_timestamp
40+
1346887571.123789
41+
dt.int_timestamp
42+
1346887571
43+
44+
pendulum.from_date(1975, 5, 21).age
45+
41 # calculated vs now in the same tz
46+
dt.quarter
47+
3
48+
49+
# Returns an int of seconds difference from UTC (+/- sign included)
50+
pendulum.from_timestamp(0).offset
51+
0
52+
pendulum.from_timestamp(0, 'America/Toronto').offset
53+
-18000
54+
55+
# Returns a float of hours difference from UTC (+/- sign included)
56+
pendulum.from_timestamp(0, 'America/Toronto').offset_hours
57+
-5.0
58+
pendulum.from_timestamp(0, 'Australia/Adelaide').offset_hours
59+
9.5
60+
61+
# Indicates if day light savings time is on
62+
pendulum.from_date(2012, 1, 1, 'America/Toronto').is_dst
63+
False
64+
pendulum.from_date(2012, 9, 1, 'America/Toronto').is_dst
65+
True
66+
67+
# Indicates if the instance is in the same timezone as the local timezone
68+
pendulum.now().local
69+
True
70+
pendulum.now('Europe/London').local
71+
False
72+
73+
# Indicates if the instance is in the UTC timezone
74+
pendulum.now().utc
75+
False
76+
pendulum.now('Europe/London').local
77+
False
78+
pendulum.utcnow().utc
79+
True
80+
81+
# Gets the timezone instance
82+
pendulum.now().timezone
83+
pendulum.now().tz
84+
85+
# Gets the timezone name
86+
pendulum.now().timezone_name

‎docs/_docs/comparison.rst‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
Comparison
2+
==========
3+
4+
Simple comparison is offered up via the basic operators.
5+
Remember that the comparison is done in the UTC timezone so things aren't always as they seem.
6+
7+
.. code-block:: python
8+
9+
import pendulum
10+
11+
first = pendulum.create(2012, 9, 5, 23, 26, 11, 0, tz='America/Toronto')
12+
second = pendulum.create(2012, 9, 5, 20, 26, 11, 0, tz='America/Vancouver')
13+
14+
first.to_datetime_string()
15+
'2012-09-05 23:26:11'
16+
first.timezone_name
17+
'America/Toronto'
18+
second.to_datetime_string()
19+
'2012-09-05 20:26:11'
20+
second.timezone_name
21+
'America/Vancouver'
22+
23+
first == second
24+
True
25+
first != second
26+
False
27+
first > second
28+
False
29+
first >= second
30+
True
31+
first < second
32+
False
33+
first <= second
34+
True
35+
36+
first = first.with_date_time(2012, 1, 1, 0, 0, 0)
37+
second = second.with_date_time(2012, 1, 1, 0, 0, 0)
38+
# tz is still America/Vancouver for second
39+
40+
first == second
41+
False
42+
first != second
43+
True
44+
first > second
45+
False
46+
first >= second
47+
False
48+
first < second
49+
True
50+
first <= second
51+
True
52+
53+
To determine if the current instance is between two other instances you can use the ``between()`` method.
54+
The third parameter indicates if an equal to comparison should be done.
55+
The default is ``True`` which determines if its between or equal to the boundaries.
56+
57+
.. code-block:: python
58+
59+
import pendulum
60+
61+
first = pendulum.create(2012, 9, 5, 1)
62+
second = pendulum.create(2012, 9, 5, 5)
63+
64+
pendulum.create(2012, 9, 5, 3).between(first, second)
65+
True
66+
pendulum.create(2012, 9, 5, 3).between(first, second)
67+
True
68+
pendulum.create(2012, 9, 5, 5).between(first, second, False)
69+
False
70+
71+
There are also the ``min_()`` and ``max_()`` methods.
72+
As usual the default parameter is ``now`` if ``None`` is specified.
73+
74+
.. code-block:: python
75+
76+
import pendulum
77+
78+
dt1 = pendulum.create(2012, 1, 1, 0, 0, 0, 0)
79+
dt2 = pendulum.create(2014, 1, 30, 0, 0, 0, 0)
80+
81+
print(dt1.min_(dt2))
82+
'2012-01-01T00:00:00+00:00'
83+
84+
print(dt1.max_(dt2))
85+
'2014-01-30T00:00:00+00:00'
86+
87+
# now is the default param
88+
print(dt1.max_())
89+
'2016-06-30T19:09:03.757597+00:00'
90+
91+
.. note::
92+
93+
``min_()`` and ``max_()`` methods are named with an underscore
94+
to not override the default ``min`` and ``max`` attributes of
95+
``datetime`` objects.
96+
97+
To handle the most used cases there are some simple helper functions.
98+
For the methods that compare to ``now()`` (ex. ``is_today()``) in some manner
99+
the ``now()`` is created in the same timezone as the instance.
100+
101+
.. code-block:: python
102+
103+
import pendulum
104+
105+
dt = Pendulum.now()
106+
107+
dt.is_weekday()
108+
dt.is_weekend()
109+
dt.is_yesterday()
110+
dt.is_today()
111+
dt.is_tomorrow()
112+
dt.is_future()
113+
dt.is_past()
114+
dt.is_leap_year()
115+
dt.is_same_day(Pendulum.now())
116+
117+
born = pendulum.from_date(1987, 4, 23)
118+
not_birthday = pendulum.from_date(2014, 9, 26)
119+
birthday = pendulum.from_date(2014, 2, 23)
120+
past_birthday = pendulum.now().subtract(years=50)
121+
122+
born.is_birthday(not_birthday)
123+
False
124+
born.is_birthday(birthday)
125+
True
126+
past_birthday.is_birthday()
127+
# Compares to now by default
128+
True

0 commit comments

Comments
 (0)