TimeMachine Utility

Relevant source files

The following files were used as context for generating this wiki page:

• hyperdrive/TimeMachine.py
• test/test_TimeMachine.py
• hyperdrive/DataSource.py
• hyperdrive/FileOps.py
• scripts/sleep.py

The TimeMachine utility, primarily implemented via the TimeTraveller class, serves as the core temporal management engine for the hyperdrive algorithmic trading library. It provides essential functionality for handling time-based offsets, calculating date ranges for data retrieval, and managing execution scheduling through precision sleep mechanisms.

This utility is integrated throughout the library to support historical data collection from providers like IEXCloud and Polygon, and to gate automated workflows. By standardizing how timeframes (e.g., '1d', '3m', '1y') are interpreted and converted into datetime objects, it ensures consistency across the library's data sourcing and file management operations.
Sources: hyperdrive/TimeMachine.py, hyperdrive/DataSource.py:17-21, README.md

Core Component: TimeTraveller

The TimeTraveller class is the primary interface for temporal logic. It handles the translation of string-based timeframes into actionable Python timedelta and datetime objects.

Temporal Logic and Conversion

The utility supports a specific set of shorthand strings representing various durations. These are converted into datetime.timedelta objects for arithmetic operations.

Unit String	Meaning	Logical Duration
d	Day	1 Day
w	Week	7 Days
m	Month	30 Days
y	Year	365 Days

Sources: hyperdrive/TimeMachine.py:11-20, test/test_TimeMachine.py:14-22

Workflow Integration Diagram

The following diagram illustrates how the TimeTraveller interacts with other system components to facilitate data retrieval and process scheduling.

The diagram shows the flow of time-based data from shorthand strings to library-wide functional applications.
Sources: hyperdrive/DataSource.py:317-320, hyperdrive/FileOps.py:75-79, scripts/sleep.py:5-8

Key Functionality

Date Range Generation

The convert_dates method determines the start and end dates based on a provided timeframe relative to the current UTC time. This is critical for the DataSource module when requesting OHLC or intraday data from external APIs.

• Method: convert_dates(timeframe, fmt='%Y-%m-%d')
• Behavior: Subtracts the converted delta from datetime.utcnow() and returns a tuple of formatted strings.

Sources: hyperdrive/TimeMachine.py:22-26, test/test_TimeMachine.py:24-28

Precision Scheduling

The utility provides sleep_until(scheduled_time), which allows the system to pause execution until a specific UTC timestamp is reached. This is used in production scripts to align task execution with market events or data availability windows.

def sleep_until(self, scheduled_time):
    # scheduled_time: PRECISE_TIME_FMT str
    curr = datetime.utcnow()
    sched = datetime.strptime(scheduled_time, PRECISE_TIME_FMT)
    delta = sched - curr
    num_sec = delta.total_seconds()
    if num_sec > 0:
        sleep(num_sec)

Sources: hyperdrive/TimeMachine.py:34-42, scripts/sleep.py:5-8

Data Filtering in Timeframes

FileOps.FileReader utilizes TimeTraveller to filter local DataFrames based on a timeframe. It converts a timeframe string into a delta, calculates the "today" threshold using the project's default timezone (C.TZ), and returns only the rows falling within that window.
Sources: hyperdrive/FileOps.py:75-84

Technical Specifications

Data Flows in Sourcing

The following sequence diagram shows how TimeTraveller is utilized during a typical intraday data collection process within the IEXCloud provider.

Internal Methods Summary

Method	Inputs	Returns	Description
convert_delta	timeframe (str)	timedelta	Maps 'd', 'w', 'm', 'y' to time durations.
convert_dates	timeframe, fmt	tuple(str, str)	Returns start and end date strings.
dates_in_range	timeframe	list(str)	Generates a list of YYYY-MM-DD dates.
combine_date_time	date, time	datetime	Merges string date and time components.
sleep_until	scheduled_time	None	Blocks execution until target UTC time.

Sources: hyperdrive/TimeMachine.py:11-42, test/test_TimeMachine.py:14-49

Summary

The TimeMachine Utility acts as the temporal backbone for the hyperdrive ecosystem. By abstracting complex datetime manipulations into a simple shorthand interface (e.g., '1m' for 30 days), it facilitates robust data collection ranges, consistent file-based data filtering, and reliable automated script scheduling. Its integration into core modules like DataSource and FileOps ensures that time-series market data is handled with precision and uniformity.