0
# Time Series and Date Handling
1

2
Comprehensive time series functionality including date/time parsing, time zone handling, frequency conversion, resampling, and specialized time-based operations.
3

4
## Core Imports
5

6
```python
7
import pandas as pd
8
from pandas import date_range, to_datetime, Timestamp, Timedelta
9
```
10

11
## Capabilities
12

13
### Date and Time Creation
14

15
Functions to create and manipulate date/time objects and ranges.
16

17
```python { .api }
18
def date_range(start=None, end=None, periods=None, freq=None, tz=None, normalize=False, name=None, inclusive='both', **kwargs):
19
    """
20
    Return a fixed frequency DatetimeIndex.
21
    
22
    Parameters:
23
    - start: str or datetime-like, left bound for generating dates
24
    - end: str or datetime-like, right bound for generating dates
25
    - periods: int, number of periods to generate
26
    - freq: str or DateOffset, frequency string ('D', 'B', 'H', 'T', 'S', 'MS', etc.)
27
    - tz: str or tzinfo, time zone name for localized DatetimeIndex
28
    - normalize: bool, normalize start/end dates to midnight
29
    - name: str, name of the resulting DatetimeIndex
30
    - inclusive: str, whether to include both endpoints ('both', 'neither', 'left', 'right')
31
    
32
    Returns:
33
    DatetimeIndex
34
    """
35

36
def bdate_range(start=None, end=None, periods=None, freq='B', tz=None, normalize=True, name=None, weekmask=None, holidays=None, inclusive='both', **kwargs):
37
    """
38
    Return a fixed frequency DatetimeIndex with business day default.
39
    
40
    Parameters:
41
    - start: str or datetime-like, left bound for generating dates
42
    - end: str or datetime-like, right bound for generating dates
43
    - periods: int, number of periods to generate
44
    - freq: str or DateOffset, frequency string (default 'B' for business day)
45
    - weekmask: str or None, weekmask of valid business days
46
    - holidays: list-like or None, dates to exclude from valid business days
47
    
48
    Returns:
49
    DatetimeIndex
50
    """
51

52
def period_range(start=None, end=None, periods=None, freq=None, name=None):
53
    """
54
    Return a fixed frequency PeriodIndex.
55
    
56
    Parameters:
57
    - start: str or Period, left bound for generating periods
58
    - end: str or Period, right bound for generating periods
59
    - periods: int, number of periods to generate
60
    - freq: str or DateOffset, frequency string
61
    - name: str, name of the resulting PeriodIndex
62
    
63
    Returns:
64
    PeriodIndex
65
    """
66

67
def timedelta_range(start=None, end=None, periods=None, freq=None, name=None, closed=None):
68
    """
69
    Return a fixed frequency TimedeltaIndex.
70
    
71
    Parameters:
72
    - start: str or timedelta, left bound for generating timedeltas
73
    - end: str or timedelta, right bound for generating timedeltas
74
    - periods: int, number of periods to generate
75
    - freq: str or DateOffset, frequency string
76
    - name: str, name of the resulting TimedeltaIndex
77
    - closed: str, make interval closed on 'left', 'right' or 'both' sides
78
    
79
    Returns:
80
    TimedeltaIndex
81
    """
82

83
def interval_range(start=0, end=None, periods=None, freq=None, name=None, closed='right'):
84
    """
85
    Return a fixed frequency IntervalIndex.
86
    
87
    Parameters:
88
    - start: numeric or datetime-like, left bound for generating intervals
89
    - end: numeric or datetime-like, right bound for generating intervals
90
    - periods: int, number of periods to generate
91
    - freq: numeric, datetime-like, or offset string, length of each interval
92
    - name: str, name of the resulting IntervalIndex
93
    - closed: str, whether intervals are closed on left, right, both, or neither
94
    
95
    Returns:
96
    IntervalIndex
97
    """
98
```
99

100
### Date and Time Conversion
101

102
Functions to parse and convert various date/time formats.
103

104
```python { .api }
105
def to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False, utc=None, format=None, exact=True, unit=None, infer_datetime_format=False, origin='unix', cache=True):
106
    """
107
    Convert argument to datetime.
108
    
109
    Parameters:
110
    - arg: int, float, str, datetime, list, tuple, 1-d array, Series, DataFrame/dict-like
111
    - errors: str, error handling behavior ('raise', 'coerce', 'ignore')
112
    - dayfirst: bool, interpret first value as day (DD/MM vs MM/DD)
113
    - yearfirst: bool, interpret first value as year
114
    - utc: bool, return UTC DatetimeIndex if True
115
    - format: str, strftime format to parse time
116
    - exact: bool, control how format is used
117
    - unit: str, unit of numeric arg ('D', 's', 'ms', 'us', 'ns')
118
    - infer_datetime_format: bool, attempt to infer format automatically
119
    - origin: scalar, define reference date ('unix', '1900-01-01')
120
    - cache: bool, use cache of unique, converted dates
121
    
122
    Returns:
123
    datetime, Timestamp, DatetimeIndex
124
    """
125

126
def to_timedelta(arg, unit=None, errors='raise'):
127
    """
128
    Convert argument to timedelta.
129
    
130
    Parameters:
131
    - arg: str, timedelta, list-like, or Series
132
    - unit: str, unit of arg when arg is numeric ('D', 'h', 'm', 's', 'ms', 'us', 'ns')
133
    - errors: str, error handling behavior ('raise', 'coerce', 'ignore')
134
    
135
    Returns:
136
    timedelta, TimedeltaIndex, Series
137
    """
138

139
def infer_freq(index, warn=True):
140
    """
141
    Infer most likely frequency given input index.
142
    
143
    Parameters:
144
    - index: DatetimeIndex or TimedeltaIndex
145
    - warn: bool, warn if frequency cannot be inferred
146
    
147
    Returns:
148
    str or None, inferred frequency
149
    """
150
```
151

152
### Core Time Objects
153

154
Core pandas time-based scalar types for representing dates, times, and intervals.
155

156
```python { .api }
157
class Timestamp:
158
    def __init__(self, ts_input=None, freq=None, tz=None, unit=None, year=None, month=None, day=None, hour=None, minute=None, second=None, microsecond=None, nanosecond=None, tzinfo=None, fold=None):
159
        """
160
        Pandas replacement for datetime.datetime.
161
        
162
        Parameters:
163
        - ts_input: datetime-like, str, int, float
164
        - freq: str or DateOffset, offset which Timestamp will have
165
        - tz: str, pytz.timezone, dateutil.tz.tzfile or None
166
        - unit: str, unit of ts_input if ts_input is int or float
167
        - year, month, day, hour, minute, second, microsecond, nanosecond: int
168
        """
169
    
170
    def normalize(self):
171
        """Return timestamp truncated to midnight."""
172
    
173
    def tz_localize(self, tz, ambiguous='raise', nonexistent='raise'):
174
        """Localize timestamp to given timezone."""
175
    
176
    def tz_convert(self, tz):
177
        """Convert timestamp to given timezone."""
178
    
179
    def strftime(self, format):
180
        """Format timestamp using strftime."""
181
    
182
    def isoformat(self, sep='T', timespec='auto'):
183
        """Return ISO 8601 formatted string."""
184
    
185
    def timestamp(self):
186
        """Return POSIX timestamp."""
187

188
class Timedelta:
189
    def __init__(self, value=None, unit=None, **kwargs):
190
        """
191
        Represents a duration between two dates or times.
192
        
193
        Parameters:
194
        - value: Timedelta, timedelta, np.timedelta64, str, or int
195
        - unit: str, unit for value if value is numeric
196
        """
197
    
198
    def total_seconds(self):
199
        """Total seconds in the timedelta."""
200
    
201
    def to_pytimedelta(self):
202
        """Convert to python datetime.timedelta."""
203
    
204
    def to_timedelta64(self):
205
        """Convert to numpy.timedelta64."""
206

207
class Period:
208
    def __init__(self, value=None, freq=None, ordinal=None, year=None, month=None, day=None, hour=None, minute=None, second=None):
209
        """
210
        Represents a period of time.
211
        
212
        Parameters:
213
        - value: Period, str, datetime, int
214
        - freq: str or DateOffset
215
        - ordinal: int, period ordinal value
216
        """
217
    
218
    def asfreq(self, freq, how='E'):
219
        """Convert Period to desired frequency."""
220
    
221
    def to_timestamp(self, freq=None, how='start'):
222
        """Return Timestamp representation of Period."""
223
    
224
    def strftime(self, format):
225
        """Format Period using strftime."""
226

227
class Interval:
228
    def __init__(self, left, right, closed='right'):
229
        """
230
        An interval of values.
231
        
232
        Parameters:
233
        - left: orderable scalar, left bound of interval
234
        - right: orderable scalar, right bound of interval  
235
        - closed: str, whether interval is closed ('left', 'right', 'both', 'neither')
236
        """
237
    
238
    def overlaps(self, other):
239
        """Check whether two intervals overlap."""
240
    
241
    def contains(self, other):
242
        """Check whether interval contains other."""
243
    
244
    @property
245
    def length(self):
246
        """Return length of interval."""
247
    
248
    @property
249
    def mid(self):
250
        """Return midpoint of interval."""
251

252
class DateOffset:
253
    def __init__(self, n=1, normalize=False):
254
        """
255
        Standard kind of date increment used for a date range.
256
        
257
        Parameters:
258
        - n: int, number of time periods  
259
        - normalize: bool, normalize start/end dates to midnight
260
        """
261
    
262
    def apply(self, other):
263
        """Apply offset to datetime."""
264
    
265
    def rollforward(self, dt):
266
        """Roll date forward to next offset."""
267
    
268
    def rollback(self, dt):
269
        """Roll date backward to previous offset."""
270
```
271

272
### Time Zone Handling
273

274
Functions and methods for working with time zones.
275

276
```python { .api }
277
# These are methods of DatetimeIndex and Timestamp:
278
# .tz_localize(tz, ambiguous='raise', nonexistent='raise') - attach timezone to naive datetime
279
# .tz_convert(tz) - convert timezone-aware datetime to another timezone
280

281
# Common timezone operations
282
def show_timezones():
283
    """Show list of available time zones."""
284

285
# Time zone constants and utilities (accessed via pandas)
286
import pandas as pd
287
# pd.Timestamp.now() - current timestamp
288
# pd.Timestamp.utcnow() - current UTC timestamp  
289
# pd.Timestamp.today() - current local timestamp
290

291
# Timezone-aware operations
292
# pd.date_range(..., tz='UTC') - create timezone-aware DatetimeIndex
293
# pd.to_datetime(..., utc=True) - parse as UTC
294
```
295

296
### Resampling and Frequency Conversion
297

298
Methods for changing the frequency of time series data.
299

300
```python { .api }
301
# These are methods of DataFrame/Series with DatetimeIndex:
302
# .resample(rule, axis=0, closed=None, label=None, convention='start', kind=None, loffset=None, base=None, on=None, level=None, origin='start_day', offset=None, group_keys=False) 
303
# Returns Resampler object with aggregation methods:
304

305
class Resampler:
306
    """GroupBy-like object for resampling operations."""
307
    
308
    def mean(self, numeric_only=False):
309
        """Compute mean of groups."""
310
    
311
    def sum(self, numeric_only=False, min_count=0):
312
        """Compute sum of groups."""
313
    
314
    def min(self, numeric_only=False):
315
        """Compute min of groups."""
316
    
317
    def max(self, numeric_only=False):
318
        """Compute max of groups."""
319
    
320
    def count(self):
321
        """Compute count of groups."""
322
    
323
    def std(self, ddof=1, numeric_only=False):
324
        """Compute standard deviation of groups."""
325
    
326
    def var(self, ddof=1, numeric_only=False):
327
        """Compute variance of groups."""
328
    
329
    def first(self, numeric_only=False, min_count=0):
330
        """Compute first value of groups."""
331
    
332
    def last(self, numeric_only=False, min_count=0):
333
        """Compute last value of groups."""
334
    
335
    def median(self, numeric_only=False):
336
        """Compute median of groups."""
337
    
338
    def ohlc(self):
339
        """Compute open, high, low, close values."""
340
    
341
    def apply(self, func, *args, **kwargs):
342
        """Apply function to each group."""
343
    
344
    def aggregate(self, func=None, *args, **kwargs):
345
        """Aggregate using one or more operations."""
346
    
347
    def transform(self, arg, *args, **kwargs):
348
        """Transform using one or more operations."""
349
    
350
    def interpolate(self, method='linear', axis=0, limit=None, inplace=False, limit_direction=None, limit_area=None, downcast=None, **kwargs):
351
        """Interpolate values according to different methods."""
352
    
353
    def asfreq(self, fill_value=None):
354
        """Convert to specified frequency."""
355
    
356
    def fillna(self, value=None, method=None, axis=None, inplace=False, limit=None, downcast=None):
357
        """Fill missing values in resampled data."""
358

359
# Frequency conversion without aggregation
360
# .asfreq(freq, method=None, how=None, normalize=False, fill_value=None)
361
```
362

363
### Date Offsets and Business Calendar
364

365
Specialized offset classes for date arithmetic and business calendar operations.
366

367
```python { .api }
368
# Import from pandas.tseries.offsets
369
from pandas.tseries.offsets import (
370
    Day, Hour, Minute, Second, Milli, Micro, Nano,
371
    BusinessDay, BDay,
372
    CustomBusinessDay, CDay,
373
    BusinessHour, CustomBusinessHour,
374
    MonthEnd, BMonthEnd, MonthBegin, BMonthBegin,
375
    SemiMonthEnd, SemiMonthBegin,
376
    QuarterEnd, BQuarterEnd, QuarterBegin, BQuarterBegin,
377
    YearEnd, BYearEnd, YearBegin, BYearBegin,
378
    Week, WeekOfMonth, LastWeekOfMonth,
379
    FY5253, FY5253Quarter,
380
    Easter
381
)
382

383
# Business day offset with custom calendar
384
class CustomBusinessDay(DateOffset):
385
    def __init__(self, n=1, normalize=False, weekmask='Mon Tue Wed Thu Fri', holidays=None, calendar=None, offset=timedelta(0)):
386
        """
387
        Custom business day offset.
388
        
389
        Parameters:
390
        - n: int, number of periods
391
        - weekmask: str or None, weekmask of valid business days  
392
        - holidays: list-like, dates to exclude from valid business days
393
        - calendar: AbstractHolidayCalendar, holiday calendar to use
394
        - offset: timedelta, time offset to apply
395
        """
396

397
# Holiday calendar support
398
class AbstractHolidayCalendar:
399
    """Abstract base class for holiday calendars."""
400
    
401
    def holidays(self, start=None, end=None, return_name=False):
402
        """Return holidays between start and end dates."""
403

404
class USFederalHolidayCalendar(AbstractHolidayCalendar):
405
    """US Federal Holiday Calendar."""
406
    pass
407

408
# Business hour offset
409
class BusinessHour(DateOffset):
410
    def __init__(self, n=1, normalize=False, start='09:00', end='17:00', offset=timedelta(0)):
411
        """
412
        Business hour offset.
413
        
414
        Parameters:
415
        - n: int, number of periods
416
        - start: str, start time of business hours
417
        - end: str, end time of business hours
418
        - offset: timedelta, time offset to apply
419
        """
420
```
421

422
### Rolling Window Operations
423

424
Statistical operations over rolling windows of time series data.
425

426
```python { .api }
427
# These are methods of DataFrame/Series:
428
# .rolling(window, min_periods=None, center=False, win_type=None, on=None, axis=0, closed=None, step=None, method='single')
429
# Returns Rolling object with statistical methods:
430

431
class Rolling:
432
    """Provides rolling window calculations."""
433
    
434
    def count(self):
435
        """Count of non-null observations."""
436
    
437
    def sum(self, numeric_only=False, engine=None, engine_kwargs=None):
438
        """Sum of values."""
439
    
440
    def mean(self, numeric_only=False, engine=None, engine_kwargs=None):
441
        """Mean of values."""
442
    
443
    def median(self, numeric_only=False, engine=None, engine_kwargs=None):
444
        """Median of values."""
445
    
446
    def var(self, ddof=1, numeric_only=False, engine=None, engine_kwargs=None):
447
        """Variance of values."""
448
    
449
    def std(self, ddof=1, numeric_only=False, engine=None, engine_kwargs=None):
450
        """Standard deviation of values."""
451
    
452
    def min(self, numeric_only=False, engine=None, engine_kwargs=None):
453
        """Min of values."""
454
    
455
    def max(self, numeric_only=False, engine=None, engine_kwargs=None):
456
        """Max of values."""
457
    
458
    def corr(self, other=None, pairwise=None, ddof=1, numeric_only=False):
459
        """Correlation of values."""
460
    
461
    def cov(self, other=None, pairwise=None, ddof=1, numeric_only=False):
462
        """Covariance of values."""
463
    
464
    def skew(self, numeric_only=False):
465
        """Skewness of values."""
466
    
467
    def kurt(self, numeric_only=False):
468
        """Kurtosis of values."""
469
    
470
    def apply(self, func, raw=False, engine=None, engine_kwargs=None, args=None, kwargs=None):
471
        """Apply function to rolling window."""
472
    
473
    def aggregate(self, func, *args, **kwargs):
474
        """Aggregate using one or more operations."""
475
    
476
    def quantile(self, quantile, interpolation='linear', numeric_only=False):
477
        """Quantile of values."""
478

479
# Expanding window operations
480
# .expanding(min_periods=1, center=None, axis=0, method='single')
481
# Returns Expanding object with same methods as Rolling
482

483
class Expanding:
484
    """Provides expanding window calculations."""
485
    # Same methods as Rolling class
486
    pass
487

488
# Exponentially weighted operations  
489
# .ewm(com=None, span=None, halflife=None, alpha=None, min_periods=0, adjust=True, ignore_na=False, axis=0, times=None, method='single')
490
# Returns ExponentialMovingWindow object
491

492
class ExponentialMovingWindow:
493
    """Provides exponentially weighted calculations."""
494
    
495
    def mean(self, numeric_only=False, engine=None, engine_kwargs=None):
496
        """Exponentially weighted moving average."""
497
    
498
    def var(self, bias=False, numeric_only=False, engine=None, engine_kwargs=None):
499
        """Exponentially weighted moving variance."""
500
    
501
    def std(self, bias=False, numeric_only=False, engine=None, engine_kwargs=None):
502
        """Exponentially weighted moving standard deviation."""
503
    
504
    def corr(self, other=None, pairwise=None, numeric_only=False):
505
        """Exponentially weighted moving correlation."""
506
    
507
    def cov(self, other=None, pairwise=None, bias=False, numeric_only=False):
508
        """Exponentially weighted moving covariance."""
509
```
510

511
## Types
512

513
```python { .api }
514
# Frequency strings
515
FrequencyStr = Literal[
516
    'B', 'C', 'D', 'W', 'M', 'SM', 'BM', 'CBM', 'MS', 'SMS', 'BMS', 'CBMS',
517
    'Q', 'BQ', 'QS', 'BQS', 'A', 'Y', 'BA', 'BY', 'AS', 'YS', 'BAS', 'BYS',
518
    'BH', 'H', 'T', 'min', 'S', 'L', 'ms', 'U', 'us', 'N', 'ns'
519
]
520

521
# Time zone types
522
TimeZone = Union[str, datetime.tzinfo, None]
523

524
# Resample rule types
525
ResampleRule = Union[str, DateOffset]
526

527
# Date parse error handling
528
DateParseError = Literal['raise', 'coerce', 'ignore']
529

530
# Timestamp origin types  
531
TimestampOrigin = Union[Literal['unix'], Timestamp, str]
532

533
# Missing value sentinels for datetime
534
NaT: object  # Not-a-Time, pandas equivalent of NaN for datetime
535

536
# Interval closed options
537
IntervalClosed = Literal['left', 'right', 'both', 'neither']
538
```