Skip to content

Commit 0116c5e

Browse files
sdispatersdispater
committed
Updates documentation
1 parent 5980284 commit 0116c5e

File tree

12 files changed

+322
-55
lines changed

12 files changed

+322
-55
lines changed

‎docs/_docs/date.rst‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
Date
2+
====
3+
4+
The ``Date`` class is a drop-in replacement for the native ``date``
5+
class (it is inherited from it).
6+
7+
It shares a lot of methods and attributes with the ``Pendulum`` class.
8+
9+
10+
Instantiation
11+
-------------
12+
13+
There are several different methods available to create a new ``Date`` object.
14+
First there is a constructor. It accepts the same parameters as the standard class.
15+
16+
.. code-block:: python
17+
18+
from pendulum import Date
19+
20+
dt = Date(2016, 11, 26)
21+
isinstance(dt, date)
22+
True
23+
24+
You can also create known instances by using the corresponding methods:
25+
26+
.. code-block:: python
27+
28+
today = Date.today()
29+
print(today)
30+
'2016-11-26'
31+
32+
tomorrow = Date.tomorrow()
33+
print(tomorrow)
34+
'2016-11-27'
35+
36+
yesterday = Date.yesterday()
37+
print(yesterday)
38+
'2016-11-25'
39+
40+
Next there is the ``create()`` helper.
41+
42+
You can provide as many or as few arguments as you want and the helper will provide default values for all others.
43+
Generally default values are the current date.
44+
45+
.. code-block:: python
46+
47+
Date.create()
48+
'2016-11-26'
49+
50+
Date.create(2015)
51+
'2015-11-26'
52+
53+
Date.create(2015, 10, 11)
54+
'2015-10-11'
55+
56+
Finally, if you find yourself inheriting a ``date`` instance,
57+
you can create a ``Date`` instance via the ``instance()`` method.
58+
59+
.. code-block:: python
60+
61+
dt = date(2016, 11, 26)
62+
d = Date.instance(dt)
63+
print(d)
64+
'2016-11-26'
65+
66+
67+
Localization
68+
------------
69+
70+
Localization occurs when using the ``format()`` method which accepts a ``locale`` keyword.
71+
72+
.. code-block:: python
73+
74+
from pendulum import Date
75+
76+
dt = Date(1975, 5, 21)
77+
78+
dt.format('%A %d %B %Y', locale='de')
79+
'Mittwoch 21 Mai 1975'
80+
81+
dt.format('%A %d %B %Y')
82+
'Wednesday 21 May 1975'
83+
84+
``diff_for_humans()`` is also localized, you can set the locale globally
85+
by using the ``pendulum.set_locale()``.
86+
87+
.. code-block:: python
88+
89+
import pendulum
90+
from pendulum import Date
91+
92+
pendulum.set_locale('de')
93+
print(Date.today().add(years=1).diff_for_humans())
94+
'in 1 Jahr'
95+
96+
pendulum.set_locale('en')
97+
98+
However, you might not want to set the locale globally.
99+
The ``diff_for_humans()`` method accept a ``locale`` keyword argument to use a locale for a specific call.
100+
101+
.. code-block:: python
102+
103+
pendulum.set_locale('de')
104+
print(Date.today().add(years=1).diff_for_humans(locale='fr'))
105+
'dans 1 an'
106+
107+
108+
Attributes and Properties
109+
-------------------------
110+
111+
Pendulum gives access to more attributes and properties than the default ``date`` class.
112+
113+
.. code-block:: python
114+
115+
from pendulum import Date
116+
117+
dt = Date(2012, 9, 5)
118+
119+
# These properties specifically return integers
120+
dt.year
121+
2012
122+
dt.month
123+
9
124+
dt.day
125+
5
126+
dt.day_of_week
127+
3
128+
dt.day_of_year
129+
248
130+
dt.week_of_month
131+
1
132+
dt.week_of_year
133+
36
134+
dt.days_in_month
135+
30
136+
dt.quarter
137+
3
138+
139+
140+
Comparison
141+
----------
142+
143+
You can refer to the corresponding `section <#comparison>`_ of the documentation.
144+
145+
146+
Addition and Subtraction
147+
------------------------
148+
149+
You can refer to the corresponding `section <#addition-and-subtraction>`_ of the documentation.
150+
151+
152+
Difference
153+
----------
154+
155+
You can refer to the corresponding `section <#difference>`_ of the documentation.
156+
157+
158+
Modifiers
159+
---------
160+
161+
You can refer to the corresponding `section <#modifiers>`_ of the documentation.

‎docs/_docs/introduction.rst‎

Lines changed: 0 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -38,27 +38,3 @@ The default timezone, except when using the ``now()``, method will always be ``U
3838
This doesn't make sense since ``now()`` in tokyo is always today in Tokyo.
3939

4040
Thus the comparison to ``now()`` is done in the same timezone as the current instance.
41-
42-
43-
.. note::
44-
45-
Every class methods that will be covered in this documentation are also accessible at module
46-
level and vice-versa with the following correspondences:
47-
48-
============================= =====================
49-
Class Method Module Function
50-
============================= =====================
51-
``instance()`` ``instance()``
52-
``parse()`` ``parse()``
53-
``now()`` ``now()``
54-
``utcnow()`` ``utcnow()``
55-
``today()`` ``today()``
56-
``tomorrow()`` ``tomorrow()``
57-
``yesterday()`` ``yesterday()``
58-
``create()`` ``create()``
59-
``create_from_date()`` ``from_date()``
60-
``create_from_time()`` ``from_time()``
61-
``create_from_format()`` ``from_time()``
62-
``strptime()`` ``strptime()``
63-
``create_from_timestamp()`` ``from_timestamp()``
64-
============================= =====================

‎docs/_docs/period.rst‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -152,10 +152,6 @@ You can check if a ``Pendulum`` instance is inside a period using the ``in`` key
152152
Intersection
153153
------------
154154

155-
.. versionadded:: 0.6.0
156-
157-
The ``intersect()`` method has been added.
158-
159155
You can get the intersection of the current ``Period`` instance with others by
160156
using the ``intersect()`` method.
161157

‎docs/_docs/string_formatting.rst‎

Lines changed: 0 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,6 @@
11
String Formatting
22
=================
33

4-
.. versionadded:: 0.6
5-
6-
Pendulum now supports an alternative formatter. It can either be set locally
7-
when calling the ``format()`` method or set globally by using ``pendulum.set_formatter()``.
8-
9-
.. code-block:: python
10-
11-
import pendulum
12-
13-
dt = pendulum.Pendulum(1975, 12, 25, 14, 15, 16)
14-
dt.format('YYYY-MM-DD HH:mm:ss', formatter='alternative')
15-
'1975-12-25 14:15:16'
16-
17-
pendulum.set_formatter('alternative')
18-
dt.format('YYYY-MM-DD HH:mm:ss')
19-
'1975-12-25 14:15:16'
20-
21-
# Reset to default formatter
22-
pendulum.set_formatter()
23-
24-
See `Alternative Formatter`_ for more information
25-
264
All the ``to_xxx_string()`` methods rely on the native ``datetime.strftime()`` with additional
275
directives available.
286
The ``__str__`` magic method is defined which allows ``Pendulum`` instances to be printed

‎docs/_docs/time.rst‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
Time
2+
====
3+
4+
The ``Time`` class is a drop-in replacement for the native ``time``
5+
class (it is inherited from it).
6+
7+
8+
Instantiation
9+
-------------
10+
11+
There are several different methods available to create a new ``Time`` object.
12+
First there is a constructor. It accepts the same parameters as the standard class.
13+
14+
.. code-block:: python
15+
16+
from pendulum import Time
17+
18+
t = Time(19, 48, 57)
19+
isinstance(t, time)
20+
True
21+
22+
You can also get the current time by using the ``now()`` method:
23+
24+
.. code-block:: python
25+
26+
t = Time.now()
27+
print(t)
28+
'19:48:57.025226'
29+
30+
# To exclude the microseconds, pass False
31+
# as the first argument
32+
t = Time.now(False)
33+
print(t)
34+
'19:48:57'
35+
36+
Finally, if you find yourself inheriting a ``time`` instance,
37+
you can create a ``Time`` instance via the ``instance()`` method.
38+
39+
.. code-block:: python
40+
41+
t1 = time(19, 48, 57)
42+
t = Time.instance(t1)
43+
print(t)
44+
'19:48:57'
45+
46+
47+
Localization
48+
------------
49+
50+
Localization occurs when using the ``format()`` method.
51+
52+
.. code-block:: python
53+
54+
from pendulum import Time
55+
56+
t = Time(19, 48, 57)
57+
58+
t.format('%H:%M:%S')
59+
'19:48:57'
60+
61+
``diff_for_humans()`` is localized, you can set the locale globally
62+
by using the ``pendulum.set_locale()``.
63+
64+
.. code-block:: python
65+
66+
import pendulum
67+
from pendulum import Time
68+
69+
pendulum.set_locale('de')
70+
print(Time.now().add(hours=1).diff_for_humans())
71+
'in 1 Stunde'
72+
73+
pendulum.set_locale('en')
74+
75+
However, you might not want to set the locale globally.
76+
The ``diff_for_humans()`` method accept a ``locale`` keyword argument to use a locale for a specific call.
77+
78+
.. code-block:: python
79+
80+
pendulum.set_locale('de')
81+
print(Time.now().add(years=1).diff_for_humans(locale='fr'))
82+
'dans 1 heure'
83+
84+
85+
Attributes and Properties
86+
-------------------------
87+
88+
Pendulum gives access to more attributes and properties than the default ``time`` class.
89+
90+
.. code-block:: python
91+
92+
from pendulum import Time
93+
94+
t = Time(19, 48, 57, 123456)
95+
96+
# These properties specifically return integers
97+
t.hour
98+
19
99+
t.minute
100+
48
101+
t.second
102+
57
103+
t.microsecond
104+
123456
105+
106+
107+
Comparison
108+
----------
109+
110+
You can refer to the corresponding `section <#comparison>`_ of the documentation.
111+
112+
113+
Addition and Subtraction
114+
------------------------
115+
116+
You can refer to the corresponding `section <#addition-and-subtraction>`_ of the documentation.
117+
118+
119+
Difference
120+
----------
121+
122+
You can refer to the corresponding `section <#difference>`_ of the documentation.
123+
124+
125+
Modifiers
126+
---------
127+
128+
You can refer to the corresponding `section <#modifiers>`_ of the documentation.

‎docs/_docs/timezones.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@ given timezone to properly handle any transition that might have occurred.
7979
8080
dt = Pendulum(2013, 3, 31, 2, 30, 0, 0, 'Europe/Paris', fold=1)
8181
dt.isoformat()
82-
'2013-03-31T02:30:00+01:00'
82+
'2013-03-31T03:30:00+02:00'
8383
8484
dt = Pendulum(2013, 10, 27, 2, 30, 0, 0, 'Europe/Paris', fold=0)
8585
dt.isoformat()

‎docs/api/date.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Date API Reference
2+
==================
3+
4+
.. module:: pendulum.date
5+
6+
.. autoclass:: Date
7+
:members:

‎docs/api/index.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
API Reference
2+
=============
3+
4+
.. toctree::
5+
6+
date.rst

‎docs/api/pendulum.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Pendulum API Reference
2+
======================
3+
4+
.. module:: pendulum.pendulum
5+
6+
.. autoclass:: Pendulum
7+
:members:

‎docs/api/time.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Time API Reference
2+
==================
3+
4+
.. module:: pendulum.time
5+
6+
.. autoclass:: Time
7+
:members:

0 commit comments

Comments
 (0)