Skip to content

Commit 3ce2133

Browse files
author
cloudboat
committed
REF: Replace @substitution with hardcoded docstring in strftime
1 parent 88c276a commit 3ce2133

File tree

1 file changed

+288
-0
lines changed

1 file changed

+288
-0
lines changed

‎pandas/core/arrays/datetimelike.py‎

Lines changed: 288 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2265,6 +2265,102 @@ def round(
22652265
ambiguous: TimeAmbiguous = "raise",
22662266
nonexistent: TimeNonexistent = "raise",
22672267
) -> Self:
2268+
"""
2269+
Perform round operation on the data to the specified `freq`.
2270+
2271+
Parameters
2272+
----------
2273+
freq : str or Offset
2274+
The frequency level to round the index to. Must be a fixed
2275+
frequency like 's' (second) not 'ME' (month end). See
2276+
:ref:`frequency aliases <timeseries.offset_aliases>` for
2277+
a list of possible `freq` values.
2278+
ambiguous : 'infer', bool-ndarray, 'NaT', default 'raise'
2279+
Only relevant for DatetimeIndex:
2280+
2281+
- 'infer' will attempt to infer fall dst-transition hours based on
2282+
order
2283+
- bool-ndarray where True signifies a DST time, False designates
2284+
a non-DST time (note that this flag is only applicable for
2285+
ambiguous times)
2286+
- 'NaT' will return NaT where there are ambiguous times
2287+
- 'raise' will raise a ValueError if there are ambiguous
2288+
times.
2289+
2290+
nonexistent : 'shift_forward', 'shift_backward', 'NaT', timedelta, \
2291+
default 'raise'
2292+
A nonexistent time does not exist in a particular timezone
2293+
where clocks moved forward due to DST.
2294+
2295+
- 'shift_forward' will shift the nonexistent time forward to the
2296+
closest existing time
2297+
- 'shift_backward' will shift the nonexistent time backward to the
2298+
closest existing time
2299+
- 'NaT' will return NaT where there are nonexistent times
2300+
- timedelta objects will shift nonexistent times by the timedelta
2301+
- 'raise' will raise a ValueError if there are
2302+
nonexistent times.
2303+
2304+
Returns
2305+
-------
2306+
DatetimeIndex, TimedeltaIndex, or Series
2307+
Index of the same type for a DatetimeIndex or TimedeltaIndex,
2308+
or a Series with the same index for a Series.
2309+
2310+
Raises
2311+
------
2312+
ValueError if the `freq` cannot be converted.
2313+
2314+
See Also
2315+
--------
2316+
DatetimeIndex.floor :
2317+
Perform floor operation on the data to the specified `freq`.
2318+
DatetimeIndex.snap :
2319+
Snap time stamps to nearest occurring frequency.
2320+
2321+
Notes
2322+
-----
2323+
If the timestamps have a timezone, rounding will take place relative to the
2324+
local ("wall") time and re-localized to the same timezone. When rounding
2325+
near daylight savings time, use ``nonexistent`` and ``ambiguous`` to
2326+
control the re-localization behavior.
2327+
2328+
Examples
2329+
--------
2330+
**DatetimeIndex**
2331+
2332+
>>> rng = pd.date_range("1/1/2018 11:59:00", periods=3, freq="min")
2333+
>>> rng
2334+
DatetimeIndex(['2018-01-01 11:59:00', '2018-01-01 12:00:00',
2335+
'2018-01-01 12:01:00'],
2336+
dtype='datetime64[ns]', freq='min')
2337+
2338+
>>> rng.round("h")
2339+
DatetimeIndex(['2018-01-01 12:00:00', '2018-01-01 12:00:00',
2340+
'2018-01-01 12:00:00'],
2341+
dtype='datetime64[ns]', freq=None)
2342+
2343+
**Series**
2344+
2345+
>>> pd.Series(rng).dt.round("h")
2346+
0 2018-01-01 12:00:00
2347+
1 2018-01-01 12:00:00
2348+
2 2018-01-01 12:00:00
2349+
dtype: datetime64[ns]
2350+
2351+
When rounding near a daylight savings time transition, use ``ambiguous`` or
2352+
``nonexistent`` to control how the timestamp should be re-localized.
2353+
2354+
>>> rng_tz = pd.DatetimeIndex(["2021-10-31 03:30:00"], tz="Europe/Amsterdam")
2355+
2356+
>>> rng_tz.floor("2h", ambiguous=False)
2357+
DatetimeIndex(['2021-10-31 02:00:00+01:00'],
2358+
dtype='datetime64[s, Europe/Amsterdam]', freq=None)
2359+
2360+
>>> rng_tz.floor("2h", ambiguous=True)
2361+
DatetimeIndex(['2021-10-31 02:00:00+02:00'],
2362+
dtype='datetime64[s, Europe/Amsterdam]', freq=None)
2363+
"""
22682364
return self._round(freq, RoundTo.NEAREST_HALF_EVEN, ambiguous, nonexistent)
22692365

22702366
@Appender((_round_doc + _floor_example).format(op="floor"))
@@ -2274,6 +2370,102 @@ def floor(
22742370
ambiguous: TimeAmbiguous = "raise",
22752371
nonexistent: TimeNonexistent = "raise",
22762372
) -> Self:
2373+
"""
2374+
Perform floor operation on the data to the specified `freq`.
2375+
2376+
Parameters
2377+
----------
2378+
freq : str or Offset
2379+
The frequency level to floor the index to. Must be a fixed
2380+
frequency like 's' (second) not 'ME' (month end). See
2381+
:ref:`frequency aliases <timeseries.offset_aliases>` for
2382+
a list of possible `freq` values.
2383+
ambiguous : 'infer', bool-ndarray, 'NaT', default 'raise'
2384+
Only relevant for DatetimeIndex:
2385+
2386+
- 'infer' will attempt to infer fall dst-transition hours based on
2387+
order
2388+
- bool-ndarray where True signifies a DST time, False designates
2389+
a non-DST time (note that this flag is only applicable for
2390+
ambiguous times)
2391+
- 'NaT' will return NaT where there are ambiguous times
2392+
- 'raise' will raise a ValueError if there are ambiguous
2393+
times.
2394+
2395+
nonexistent : 'shift_forward', 'shift_backward', 'NaT', timedelta, \
2396+
default 'raise'
2397+
A nonexistent time does not exist in a particular timezone
2398+
where clocks moved forward due to DST.
2399+
2400+
- 'shift_forward' will shift the nonexistent time forward to the
2401+
closest existing time
2402+
- 'shift_backward' will shift the nonexistent time backward to the
2403+
closest existing time
2404+
- 'NaT' will return NaT where there are nonexistent times
2405+
- timedelta objects will shift nonexistent times by the timedelta
2406+
- 'raise' will raise a ValueError if there are
2407+
nonexistent times.
2408+
2409+
Returns
2410+
-------
2411+
DatetimeIndex, TimedeltaIndex, or Series
2412+
Index of the same type for a DatetimeIndex or TimedeltaIndex,
2413+
or a Series with the same index for a Series.
2414+
2415+
Raises
2416+
------
2417+
ValueError if the `freq` cannot be converted.
2418+
2419+
See Also
2420+
--------
2421+
DatetimeIndex.floor :
2422+
Perform floor operation on the data to the specified `freq`.
2423+
DatetimeIndex.snap :
2424+
Snap time stamps to nearest occurring frequency.
2425+
2426+
Notes
2427+
-----
2428+
If the timestamps have a timezone, flooring will take place relative to the
2429+
local ("wall") time and re-localized to the same timezone. When flooring
2430+
near daylight savings time, use ``nonexistent`` and ``ambiguous`` to
2431+
control the re-localization behavior.
2432+
2433+
Examples
2434+
--------
2435+
**DatetimeIndex**
2436+
2437+
>>> rng = pd.date_range("1/1/2018 11:59:00", periods=3, freq="min")
2438+
>>> rng
2439+
DatetimeIndex(['2018-01-01 11:59:00', '2018-01-01 12:00:00',
2440+
'2018-01-01 12:01:00'],
2441+
dtype='datetime64[ns]', freq='min')
2442+
2443+
>>> rng.floor("h")
2444+
DatetimeIndex(['2018-01-01 11:00:00', '2018-01-01 12:00:00',
2445+
'2018-01-01 12:00:00'],
2446+
dtype='datetime64[ns]', freq=None)
2447+
2448+
**Series**
2449+
2450+
>>> pd.Series(rng).dt.floor("h")
2451+
0 2018-01-01 11:00:00
2452+
1 2018-01-01 12:00:00
2453+
2 2018-01-01 12:00:00
2454+
dtype: datetime64[ns]
2455+
2456+
When rounding near a daylight savings time transition, use ``ambiguous`` or
2457+
``nonexistent`` to control how the timestamp should be re-localized.
2458+
2459+
>>> rng_tz = pd.DatetimeIndex(["2021-10-31 03:30:00"], tz="Europe/Amsterdam")
2460+
2461+
>>> rng_tz.floor("2h", ambiguous=False)
2462+
DatetimeIndex(['2021-10-31 02:00:00+01:00'],
2463+
dtype='datetime64[s, Europe/Amsterdam]', freq=None)
2464+
2465+
>>> rng_tz.floor("2h", ambiguous=True)
2466+
DatetimeIndex(['2021-10-31 02:00:00+02:00'],
2467+
dtype='datetime64[s, Europe/Amsterdam]', freq=None)
2468+
"""
22772469
return self._round(freq, RoundTo.MINUS_INFTY, ambiguous, nonexistent)
22782470

22792471
@Appender((_round_doc + _ceil_example).format(op="ceil"))
@@ -2283,6 +2475,102 @@ def ceil(
22832475
ambiguous: TimeAmbiguous = "raise",
22842476
nonexistent: TimeNonexistent = "raise",
22852477
) -> Self:
2478+
"""
2479+
Perform ceil operation on the data to the specified `freq`.
2480+
2481+
Parameters
2482+
----------
2483+
freq : str or Offset
2484+
The frequency level to ceil the index to. Must be a fixed
2485+
frequency like 's' (second) not 'ME' (month end). See
2486+
:ref:`frequency aliases <timeseries.offset_aliases>` for
2487+
a list of possible `freq` values.
2488+
ambiguous : 'infer', bool-ndarray, 'NaT', default 'raise'
2489+
Only relevant for DatetimeIndex:
2490+
2491+
- 'infer' will attempt to infer fall dst-transition hours based on
2492+
order
2493+
- bool-ndarray where True signifies a DST time, False designates
2494+
a non-DST time (note that this flag is only applicable for
2495+
ambiguous times)
2496+
- 'NaT' will return NaT where there are ambiguous times
2497+
- 'raise' will raise a ValueError if there are ambiguous
2498+
times.
2499+
2500+
nonexistent : 'shift_forward', 'shift_backward', 'NaT', timedelta, \
2501+
default 'raise'
2502+
A nonexistent time does not exist in a particular timezone
2503+
where clocks moved forward due to DST.
2504+
2505+
- 'shift_forward' will shift the nonexistent time forward to the
2506+
closest existing time
2507+
- 'shift_backward' will shift the nonexistent time backward to the
2508+
closest existing time
2509+
- 'NaT' will return NaT where there are nonexistent times
2510+
- timedelta objects will shift nonexistent times by the timedelta
2511+
- 'raise' will raise a ValueError if there are
2512+
nonexistent times.
2513+
2514+
Returns
2515+
-------
2516+
DatetimeIndex, TimedeltaIndex, or Series
2517+
Index of the same type for a DatetimeIndex or TimedeltaIndex,
2518+
or a Series with the same index for a Series.
2519+
2520+
Raises
2521+
------
2522+
ValueError if the `freq` cannot be converted.
2523+
2524+
See Also
2525+
--------
2526+
DatetimeIndex.floor :
2527+
Perform floor operation on the data to the specified `freq`.
2528+
DatetimeIndex.snap :
2529+
Snap time stamps to nearest occurring frequency.
2530+
2531+
Notes
2532+
-----
2533+
If the timestamps have a timezone, ceiling will take place relative to the
2534+
local ("wall") time and re-localized to the same timezone. When ceiling
2535+
near daylight savings time, use ``nonexistent`` and ``ambiguous`` to
2536+
control the re-localization behavior.
2537+
2538+
Examples
2539+
--------
2540+
**DatetimeIndex**
2541+
2542+
>>> rng = pd.date_range("1/1/2018 11:59:00", periods=3, freq="min")
2543+
>>> rng
2544+
DatetimeIndex(['2018-01-01 11:59:00', '2018-01-01 12:00:00',
2545+
'2018-01-01 12:01:00'],
2546+
dtype='datetime64[ns]', freq='min')
2547+
2548+
>>> rng.ceil("h")
2549+
DatetimeIndex(['2018-01-01 12:00:00', '2018-01-01 12:00:00',
2550+
'2018-01-01 13:00:00'],
2551+
dtype='datetime64[ns]', freq=None)
2552+
2553+
**Series**
2554+
2555+
>>> pd.Series(rng).dt.ceil("h")
2556+
0 2018-01-01 12:00:00
2557+
1 2018-01-01 12:00:00
2558+
2 2018-01-01 13:00:00
2559+
dtype: datetime64[ns]
2560+
2561+
When rounding near a daylight savings time transition, use ``ambiguous`` or
2562+
``nonexistent`` to control how the timestamp should be re-localized.
2563+
2564+
>>> rng_tz = pd.DatetimeIndex(["2021-10-31 01:30:00"], tz="Europe/Amsterdam")
2565+
2566+
>>> rng_tz.ceil("h", ambiguous=False)
2567+
DatetimeIndex(['2021-10-31 02:00:00+01:00'],
2568+
dtype='datetime64[s, Europe/Amsterdam]', freq=None)
2569+
2570+
>>> rng_tz.ceil("h", ambiguous=True)
2571+
DatetimeIndex(['2021-10-31 02:00:00+02:00'],
2572+
dtype='datetime64[s, Europe/Amsterdam]', freq=None)
2573+
"""
22862574
return self._round(freq, RoundTo.PLUS_INFTY, ambiguous, nonexistent)
22872575

22882576
# --------------------------------------------------------------

0 commit comments

Comments
 (0)