0
# Date and Time Utilities
1

2
Comprehensive date/time handling for financial data including timezone management, date range operations, and time series utilities. Provides robust datetime conversion and time-based data filtering capabilities optimized for financial market data across global timezones.
3

4
## Capabilities
5

6
### DateRange Class
7

8
Date/time range specification for queries and temporal operations with support for various boundary types.
9

10
```python { .api }
11
class DateRange:
12
    """
13
    Date/time range specification with configurable boundaries.
14
    
15
    Supports various boundary types (open/closed intervals) and
16
    step specifications for time series operations and queries.
17
    """
18
    
19
    def __init__(self, start=None, end=None, interval=CLOSED_CLOSED):
20
        """
21
        Create date range with configurable boundary types.
22
        
23
        Parameters:
24
        - start: Start datetime or date-like object (default: None for unbounded)
25
        - end: End datetime or date-like object (default: None for unbounded)
26
        - interval: Boundary type (CLOSED_CLOSED, OPEN_CLOSED, etc.)
27
        """
28
```
29

30
### Date Conversion Functions
31

32
Functions for converting between different datetime representations and formats.
33

34
```python { .api }
35
def datetime_to_ms(dt):
36
    """
37
    Convert datetime to milliseconds since Unix epoch.
38
    
39
    Parameters:
40
    - dt: datetime object to convert
41
    
42
    Returns:
43
    int: Milliseconds since epoch (1970-01-01 00:00:00 UTC)
44
    """
45

46
def ms_to_datetime(ms):
47
    """
48
    Convert milliseconds since epoch to datetime object.
49
    
50
    Parameters:
51
    - ms: Milliseconds since Unix epoch
52
    
53
    Returns:
54
    datetime: UTC datetime object
55
    """
56

57
def to_dt(date):
58
    """
59
    Convert various date representations to datetime object.
60
    
61
    Parameters:
62
    - date: Date string, timestamp, or date-like object
63
    
64
    Returns:
65
    datetime: Standardized datetime object
66
    
67
    Raises:
68
    - ValueError: If date format cannot be parsed
69
    """
70
```
71

72
### Timezone Management
73

74
Functions for handling timezone conversions and timezone-aware datetime operations.
75

76
```python { .api }
77
def mktz(timezone):
78
    """
79
    Create timezone object from string specification.
80
    
81
    Parameters:
82
    - timezone: Timezone string (e.g., 'UTC', 'US/Eastern', 'Europe/London')
83
    
84
    Returns:
85
    pytz.timezone: Timezone object for datetime operations
86
    
87
    Raises:
88
    - TimezoneError: If timezone string is invalid
89
    """
90

91
def utc_dt_to_local_dt(dt, local_tz):
92
    """
93
    Convert UTC datetime to local timezone.
94
    
95
    Parameters:
96
    - dt: UTC datetime object
97
    - local_tz: Target timezone object or string
98
    
99
    Returns:
100
    datetime: Datetime converted to local timezone
101
    """
102
```
103

104
### Date Range Parsing
105

106
Functions for parsing and converting date range specifications.
107

108
```python { .api }
109
def string_to_daterange(string):
110
    """
111
    Parse date range from string representation.
112
    
113
    Parameters:
114
    - string: Date range string (various formats supported)
115
    
116
    Returns:
117
    DateRange: Parsed date range object
118
    
119
    Raises:
120
    - ValueError: If string format cannot be parsed
121
    """
122

123
def to_pandas_closed_closed(date_range):
124
    """
125
    Convert DateRange to pandas-compatible closed interval.
126
    
127
    Parameters:
128
    - date_range: DateRange object to convert
129
    
130
    Returns:
131
    pandas-compatible date range with closed boundaries
132
    """
133
```
134

135
### Date Range Boundary Constants
136

137
Constants defining different types of interval boundaries for date ranges.
138

139
```python { .api }
140
OPEN_CLOSED = "open_closed"     # Excludes start, includes end: (start, end]
141
CLOSED_OPEN = "closed_open"     # Includes start, excludes end: [start, end)
142
OPEN_OPEN = "open_open"         # Excludes both boundaries: (start, end)
143
CLOSED_CLOSED = "closed_closed" # Includes both boundaries: [start, end]
144
```
145

146
### Exception Types
147

148
Timezone-related exception for error handling.
149

150
```python { .api }
151
class TimezoneError(Exception):
152
    """
153
    Exception raised for timezone-related errors.
154
    
155
    Raised when timezone strings cannot be parsed or
156
    timezone conversions fail.
157
    """
158
```
159

160
## Usage Examples
161

162
### Basic Date Range Operations
163

164
```python
165
from arctic.date import DateRange, CLOSED_CLOSED, OPEN_CLOSED, CLOSED_OPEN
166
from datetime import datetime, timedelta
167

168
# Create date ranges
169
start_date = datetime(2020, 1, 1, 9, 30)  # Market open
170
end_date = datetime(2020, 1, 1, 16, 0)    # Market close
171

172
# Trading session range (includes both boundaries)
173
session_range = DateRange(start_date, end_date, CLOSED_CLOSED)
174

175
# Date range excluding end boundary
176
hourly_range = DateRange(
177
    datetime(2020, 1, 1),
178
    datetime(2020, 1, 7),
179
    CLOSED_OPEN
180
)
181

182
# Month range
183
month_range = DateRange(
184
    datetime(2020, 1, 1),
185
    datetime(2020, 2, 1),
186
    CLOSED_CLOSED
187
)
188

189
print(f"Session range: {session_range}")
190
print(f"Monthly range: {month_range}")
191
```
192

193
### DateTime Conversions
194

195
```python
196
from arctic.date import datetime_to_ms, ms_to_datetime, to_dt
197

198
# Convert datetime to milliseconds
199
trade_time = datetime(2020, 1, 15, 14, 30, 45)
200
ms_timestamp = datetime_to_ms(trade_time)
201
print(f"Timestamp in ms: {ms_timestamp}")
202

203
# Convert back to datetime
204
restored_time = ms_to_datetime(ms_timestamp)
205
print(f"Restored datetime: {restored_time}")
206

207
# Convert various date formats
208
date_formats = [
209
    "2020-01-15",
210
    "2020-01-15 14:30:45",
211
    "01/15/2020",
212
    1579097445000,  # milliseconds
213
    datetime(2020, 1, 15)
214
]
215

216
for date_input in date_formats:
217
    try:
218
        converted = to_dt(date_input)
219
        print(f"'{date_input}' -> {converted}")
220
    except ValueError as e:
221
        print(f"Failed to convert '{date_input}': {e}")
222
```
223

224
### Timezone Handling
225

226
```python
227
from arctic.date import mktz, utc_dt_to_local_dt
228
import pytz
229

230
# Create timezone objects
231
utc_tz = mktz('UTC')
232
ny_tz = mktz('US/Eastern')
233
london_tz = mktz('Europe/London')
234
tokyo_tz = mktz('Asia/Tokyo')
235

236
print(f"UTC timezone: {utc_tz}")
237
print(f"New York timezone: {ny_tz}")
238

239
# Convert UTC time to different timezones
240
utc_time = datetime(2020, 1, 15, 19, 30, 0, tzinfo=pytz.UTC)
241

242
ny_time = utc_dt_to_local_dt(utc_time, ny_tz)
243
london_time = utc_dt_to_local_dt(utc_time, london_tz)
244
tokyo_time = utc_dt_to_local_dt(utc_time, tokyo_tz)
245

246
print(f"UTC time: {utc_time}")
247
print(f"New York time: {ny_time}")
248
print(f"London time: {london_time}")
249
print(f"Tokyo time: {tokyo_time}")
250
```
251

252
### Financial Market Date Ranges
253

254
```python
255
# Define market sessions across different timezones
256
market_sessions = {
257
    'NYSE': {
258
        'open': datetime(2020, 1, 15, 14, 30),  # 9:30 AM EST in UTC
259
        'close': datetime(2020, 1, 15, 21, 0)   # 4:00 PM EST in UTC
260
    },
261
    'LSE': {
262
        'open': datetime(2020, 1, 15, 8, 0),   # 8:00 AM GMT in UTC
263
        'close': datetime(2020, 1, 15, 16, 30) # 4:30 PM GMT in UTC
264
    },
265
    'TSE': {
266
        'open': datetime(2020, 1, 15, 0, 0),   # 9:00 AM JST in UTC
267
        'close': datetime(2020, 1, 15, 6, 0)   # 3:00 PM JST in UTC
268
    }
269
}
270

271
# Create date ranges for each market session
272
for market, times in market_sessions.items():
273
    session = DateRange(times['open'], times['close'])
274
    duration = times['close'] - times['open']
275
    print(f"{market} session: {session} (Duration: {duration})")
276

277
# Weekly trading range (Monday to Friday)
278
week_start = datetime(2020, 1, 13)  # Monday
279
week_end = datetime(2020, 1, 17)    # Friday
280
trading_week = DateRange(week_start, week_end)
281

282
# Exclude weekends for continuous trading data
283
weekdays_only = DateRange(week_start, week_end, step=timedelta(days=1))
284
```
285

286
### Date Range Parsing and String Conversion
287

288
```python
289
from arctic.date import string_to_daterange, to_pandas_closed_closed
290

291
# Parse various date range string formats
292
date_strings = [
293
    "2020-01-01 to 2020-01-31",
294
    "Jan 1 2020 - Jan 31 2020",
295
    "2020-01-01/2020-01-31",
296
    "20200101:20200131"
297
]
298

299
for date_str in date_strings:
300
    try:
301
        parsed_range = string_to_daterange(date_str)
302
        print(f"Parsed '{date_str}' -> {parsed_range}")
303
    except ValueError as e:
304
        print(f"Failed to parse '{date_str}': {e}")
305

306
# Convert to pandas-compatible format
307
date_range = DateRange(datetime(2020, 1, 1), datetime(2020, 1, 31))
308
pandas_range = to_pandas_closed_closed(date_range)
309
print(f"Pandas-compatible range: {pandas_range}")
310
```
311

312
### Integration with Arctic Operations
313

314
```python
315
from arctic import Arctic, VERSION_STORE
316
import pandas as pd
317

318
# Setup for date-filtered queries
319
arctic_conn = Arctic('mongodb://localhost:27017')
320
lib = arctic_conn['market_data']
321

322
# Create sample data with timezone-aware timestamps
323
dates = pd.date_range('2020-01-01 09:30:00', 
324
                     '2020-01-01 16:00:00', 
325
                     freq='1min', tz='US/Eastern')
326

327
market_data = pd.DataFrame({
328
    'price': np.random.randn(len(dates)).cumsum() + 100,
329
    'volume': np.random.randint(100, 1000, len(dates))
330
}, index=dates)
331

332
# Write data
333
lib.write('AAPL', market_data)
334

335
# Query using date ranges
336
morning_session = DateRange(
337
    datetime(2020, 1, 1, 9, 30),
338
    datetime(2020, 1, 1, 12, 0)
339
)
340

341
afternoon_session = DateRange(
342
    datetime(2020, 1, 1, 12, 0),
343
    datetime(2020, 1, 1, 16, 0)
344
)
345

346
# Read data for specific sessions
347
morning_data = lib.read('AAPL', date_range=morning_session)
348
afternoon_data = lib.read('AAPL', date_range=afternoon_session)
349

350
print(f"Morning data points: {len(morning_data.data)}")
351
print(f"Afternoon data points: {len(afternoon_data.data)}")
352
```
353

354
### Advanced Date Range Operations
355

356
```python
357
# Working with different boundary types
358
inclusive_range = DateRange(
359
    datetime(2020, 1, 1, 9, 30),
360
    datetime(2020, 1, 1, 16, 0)
361
)  # Default: CLOSED_CLOSED [start, end]
362

363
# Exclude end boundary for non-overlapping ranges
364
exclusive_end = DateRange(
365
    datetime(2020, 1, 1, 9, 30),
366
    datetime(2020, 1, 1, 16, 0)
367
)  # Can be configured as CLOSED_OPEN [start, end)
368

369
# Multiple non-overlapping ranges for batch processing
370
batch_ranges = []
371
start = datetime(2020, 1, 1)
372
for i in range(7):  # One week of daily ranges
373
    day_start = start + timedelta(days=i)
374
    day_end = day_start + timedelta(days=1)
375
    batch_ranges.append(DateRange(day_start, day_end))
376

377
for i, day_range in enumerate(batch_ranges):
378
    print(f"Day {i+1}: {day_range}")
379

380
# Handle timezone-aware operations
381
utc_now = datetime.now(pytz.UTC)
382
local_tz = mktz('US/Pacific')
383
local_now = utc_dt_to_local_dt(utc_now, local_tz)
384

385
print(f"UTC time: {utc_now}")
386
print(f"Pacific time: {local_now}")
387
```