Skip to content

Commit a43573d

Browse files
junyazhanggcf-owl-bot[bot]
junyazhang
and
gcf-owl-bot[bot]
authored
doc: add examples for DatetimeMethods (#577)
* doc: add examples for DatetimeMethods * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md * fix presubmit failure * fix presubmit failure --------- Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>
1 parent d048aa8 commit a43573d

File tree

3 files changed

+223
-21
lines changed

3 files changed

+223
-21
lines changed

‎third_party/bigframes_vendored/pandas/core/arrays/datetimelike.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,8 @@ def strftime(self, date_format: str):
99
Convert to string Series using specified date_format.
1010
1111
Return a Series of formatted strings specified by date_format. Details
12-
of the string format can be found in `BigQuery format elements doc
13-
<%(https://cloud.google.com/bigquery/docs/reference/standard-sql/format-elements)s>`__.
12+
of the string format can be found in BigQuery format elements doc:
13+
https://cloud.google.com/bigquery/docs/reference/standard-sql/format-elements#format_elements_date_time.
1414
1515
**Examples:**
1616

‎third_party/bigframes_vendored/pandas/core/indexes/accessor.py‎

Lines changed: 220 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,27 @@ class DatetimeProperties:
88

99
@property
1010
def day(self):
11-
"""The day of the datetime."""
11+
"""The day of the datetime.
12+
13+
**Examples:**
14+
15+
>>> import pandas as pd
16+
>>> import bigframes.pandas as bpd
17+
>>> bpd.options.display.progress_bar = None
18+
>>> s = bpd.Series(
19+
... pd.date_range("2000-01-01", periods=3, freq="D")
20+
... )
21+
>>> s
22+
0 2000-01-01 00:00:00
23+
1 2000-01-02 00:00:00
24+
2 2000-01-03 00:00:00
25+
dtype: timestamp[us][pyarrow]
26+
>>> s.dt.day
27+
0 1
28+
1 2
29+
2 3
30+
dtype: Int64
31+
"""
1232

1333
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)
1434

@@ -18,62 +38,187 @@ def dayofweek(self):
1838
1939
Return the day of the week. It is assumed the week starts on
2040
Monday, which is denoted by 0 and ends on Sunday which is denoted
21-
by 6. This method is available on both Series with datetime
22-
values (using the `dt` accessor) or DatetimeIndex.
41+
by 6.
42+
43+
**Examples:**
44+
45+
>>> import pandas as pd
46+
>>> import bigframes.pandas as bpd
47+
>>> bpd.options.display.progress_bar = None
48+
>>> s = bpd.Series(
49+
... pd.date_range('2016-12-31', '2017-01-08', freq='D').to_series()
50+
... )
51+
>>> s.dt.dayofweek
52+
2016-12-31 00:00:00 5
53+
2017-01-01 00:00:00 6
54+
2017-01-02 00:00:00 0
55+
2017-01-03 00:00:00 1
56+
2017-01-04 00:00:00 2
57+
2017-01-05 00:00:00 3
58+
2017-01-06 00:00:00 4
59+
2017-01-07 00:00:00 5
60+
2017-01-08 00:00:00 6
61+
dtype: Int64
2362
2463
Returns:
25-
Series or Index: Containing integers indicating the day number.
64+
Series: Containing integers indicating the day number.
2665
"""
2766

2867
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)
2968

3069
@property
3170
def date(self):
32-
"""Returns numpy array of Python :class:`datetime.date` objects.
33-
34-
Namely, the date part of Timestamps without time and
71+
"""Returns a Series with the date part of Timestamps without time and
3572
timezone information.
3673
3774
.. warning::
3875
This method returns a Series whereas pandas returns
3976
a numpy array.
77+
78+
**Examples:**
79+
80+
>>> import bigframes.pandas as bpd
81+
>>> bpd.options.display.progress_bar = None
82+
>>> s = bpd.Series(["1/1/2020 10:00:00+00:00", "2/1/2020 11:00:00+00:00"])
83+
>>> s = bpd.to_datetime(s, utc=True, format="%d/%m/%Y %H:%M:%S%Ez")
84+
>>> s
85+
0 2020-01-01 10:00:00+00:00
86+
1 2020-01-02 11:00:00+00:00
87+
dtype: timestamp[us, tz=UTC][pyarrow]
88+
>>> s.dt.date
89+
0 2020-01-01
90+
1 2020-01-02
91+
dtype: date32[day][pyarrow]
4092
"""
4193

4294
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)
4395

4496
@property
4597
def hour(self):
46-
"""The hours of the datetime."""
98+
"""The hours of the datetime.
99+
100+
**Examples:**
101+
102+
>>> import pandas as pd
103+
>>> import bigframes.pandas as bpd
104+
>>> bpd.options.display.progress_bar = None
105+
>>> s = bpd.Series(
106+
... pd.date_range("2000-01-01", periods=3, freq="h")
107+
... )
108+
>>> s
109+
0 2000-01-01 00:00:00
110+
1 2000-01-01 01:00:00
111+
2 2000-01-01 02:00:00
112+
dtype: timestamp[us][pyarrow]
113+
>>> s.dt.hour
114+
0 0
115+
1 1
116+
2 2
117+
dtype: Int64
118+
"""
47119

48120
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)
49121

50122
@property
51123
def minute(self):
52-
"""The minutes of the datetime."""
124+
"""The minutes of the datetime.
125+
126+
**Examples:**
127+
128+
>>> import pandas as pd
129+
>>> import bigframes.pandas as bpd
130+
>>> bpd.options.display.progress_bar = None
131+
>>> s = bpd.Series(
132+
... pd.date_range("2000-01-01", periods=3, freq="min")
133+
... )
134+
>>> s
135+
0 2000-01-01 00:00:00
136+
1 2000-01-01 00:01:00
137+
2 2000-01-01 00:02:00
138+
dtype: timestamp[us][pyarrow]
139+
>>> s.dt.minute
140+
0 0
141+
1 1
142+
2 2
143+
dtype: Int64
144+
"""
53145

54146
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)
55147

56148
@property
57149
def month(self):
58-
"""The month as January=1, December=12."""
150+
"""The month as January=1, December=12.
151+
152+
**Examples:**
153+
154+
>>> import pandas as pd
155+
>>> import bigframes.pandas as bpd
156+
>>> bpd.options.display.progress_bar = None
157+
>>> s = bpd.Series(
158+
... pd.date_range("2000-01-01", periods=3, freq="M")
159+
... )
160+
>>> s
161+
0 2000-01-31 00:00:00
162+
1 2000-02-29 00:00:00
163+
2 2000-03-31 00:00:00
164+
dtype: timestamp[us][pyarrow]
165+
>>> s.dt.month
166+
0 1
167+
1 2
168+
2 3
169+
dtype: Int64
170+
"""
59171

60172
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)
61173

62174
@property
63175
def second(self):
64-
"""The seconds of the datetime."""
176+
"""The seconds of the datetime.
177+
178+
**Examples:**
179+
180+
>>> import pandas as pd
181+
>>> import bigframes.pandas as bpd
182+
>>> bpd.options.display.progress_bar = None
183+
>>> s = bpd.Series(
184+
... pd.date_range("2000-01-01", periods=3, freq="s")
185+
... )
186+
>>> s
187+
0 2000-01-01 00:00:00
188+
1 2000-01-01 00:00:01
189+
2 2000-01-01 00:00:02
190+
dtype: timestamp[us][pyarrow]
191+
>>> s.dt.second
192+
0 0
193+
1 1
194+
2 2
195+
dtype: Int64
196+
"""
65197

66198
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)
67199

68200
@property
69201
def time(self):
70-
"""Returns numpy array of :class:`datetime.time` objects.
71-
72-
The time part of the Timestamps.
202+
"""Returns a Series with the time part of the Timestamps.
73203
74204
.. warning::
75205
This method returns a Series whereas pandas returns
76206
a numpy array.
207+
208+
**Examples:**
209+
210+
>>> import bigframes.pandas as bpd
211+
>>> bpd.options.display.progress_bar = None
212+
>>> s = bpd.Series(["1/1/2020 10:00:00+00:00", "2/1/2020 11:00:00+00:00"])
213+
>>> s = bpd.to_datetime(s, utc=True, format="%m/%d/%Y %H:%M:%S%Ez")
214+
>>> s
215+
0 2020-01-01 10:00:00+00:00
216+
1 2020-02-01 11:00:00+00:00
217+
dtype: timestamp[us, tz=UTC][pyarrow]
218+
>>> s.dt.time
219+
0 10:00:00
220+
1 11:00:00
221+
dtype: time64[us][pyarrow]
77222
"""
78223

79224
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)
@@ -82,23 +227,67 @@ def time(self):
82227
def quarter(self):
83228
"""The quarter of the date.
84229
85-
.. warning::
86-
This method returns a Series whereas pandas returns
87-
a numpy array.
230+
**Examples:**
231+
232+
>>> import bigframes.pandas as bpd
233+
>>> bpd.options.display.progress_bar = None
234+
>>> s = bpd.Series(["1/1/2020 10:00:00+00:00", "4/1/2020 11:00:00+00:00"])
235+
>>> s = bpd.to_datetime(s, utc=True, format="%m/%d/%Y %H:%M:%S%Ez")
236+
>>> s
237+
0 2020-01-01 10:00:00+00:00
238+
1 2020-04-01 11:00:00+00:00
239+
dtype: timestamp[us, tz=UTC][pyarrow]
240+
>>> s.dt.quarter
241+
0 1
242+
1 2
243+
dtype: Int64
88244
"""
89245

90246
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)
91247

92248
@property
93249
def year(self):
94-
"""The year of the datetime."""
250+
"""The year of the datetime.
251+
252+
**Examples:**
253+
254+
>>> import pandas as pd
255+
>>> import bigframes.pandas as bpd
256+
>>> bpd.options.display.progress_bar = None
257+
>>> s = bpd.Series(
258+
... pd.date_range("2000-01-01", periods=3, freq="Y")
259+
... )
260+
>>> s
261+
0 2000-12-31 00:00:00
262+
1 2001-12-31 00:00:00
263+
2 2002-12-31 00:00:00
264+
dtype: timestamp[us][pyarrow]
265+
>>> s.dt.year
266+
0 2000
267+
1 2001
268+
2 2002
269+
dtype: Int64
270+
"""
95271

96272
raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)
97273

98274
@property
99275
def tz(self):
100276
"""Return the timezone.
101277
278+
**Examples:**
279+
280+
>>> import bigframes.pandas as bpd
281+
>>> bpd.options.display.progress_bar = None
282+
>>> s = bpd.Series(["1/1/2020 10:00:00+00:00", "2/1/2020 11:00:00+00:00"])
283+
>>> s = bpd.to_datetime(s, utc=True, format="%m/%d/%Y %H:%M:%S%Ez")
284+
>>> s
285+
0 2020-01-01 10:00:00+00:00
286+
1 2020-02-01 11:00:00+00:00
287+
dtype: timestamp[us, tz=UTC][pyarrow]
288+
>>> s.dt.tz
289+
datetime.timezone.utc
290+
102291
Returns:
103292
datetime.tzinfo, pytz.tzinfo.BaseTZInfo, dateutil.tz.tz.tzfile, or None
104293
"""
@@ -109,6 +298,19 @@ def tz(self):
109298
def unit(self) -> str:
110299
"""Returns the unit of time precision.
111300
301+
**Examples:**
302+
303+
>>> import bigframes.pandas as bpd
304+
>>> bpd.options.display.progress_bar = None
305+
>>> s = bpd.Series(["1/1/2020 10:00:00+00:00", "2/1/2020 11:00:00+00:00"])
306+
>>> s = bpd.to_datetime(s, utc=True, format="%m/%d/%Y %H:%M:%S%Ez")
307+
>>> s
308+
0 2020-01-01 10:00:00+00:00
309+
1 2020-02-01 11:00:00+00:00
310+
dtype: timestamp[us, tz=UTC][pyarrow]
311+
>>> s.dt.unit
312+
'us'
313+
112314
Returns:
113315
Unit as string (eg. "us").
114316
"""

‎third_party/bigframes_vendored/pandas/core/tools/datetimes.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ def to_datetime(
2929
.. note::
3030
The format strings for specifying datetime representations in BigQuery and pandas
3131
are not completely identical. Ensure that the format string provided is compatible
32-
with BigQuery.
32+
with BigQuery (https://cloud.google.com/bigquery/docs/reference/standard-sql/format-elements#format_elements_date_time).
3333
3434
**Examples:**
3535

0 commit comments

Comments
 (0)