contango 0.1.0__py3-none-any.whl

contango/__init__.py

@@ -0,0 +1,20 @@
+# trading/execution/backtester/market/__init__.py — part of Contango, a parameterized backtesting & execution framework
+# Copyright (C) 2026  Jacob Taylor
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+from __future__ import annotations
+
+
+__all__ = []

contango/broker/__init__.py

@@ -0,0 +1,20 @@
+# broker/__init__.py — part of Contango, a parameterized backtesting & execution framework
+# Copyright (C) 2026  Jacob Taylor
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+from __future__ import annotations
+
+
+__all__ = []

contango/broker/calendar/__init__.py

@@ -0,0 +1,23 @@
+# broker/calendar/__init__.py — part of Contango, a parameterized backtesting & execution framework
+# Copyright (C) 2026  Jacob Taylor
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+from __future__ import annotations
+
+from contango.broker.calendar.calendar import Calendar
+from contango.broker.calendar.nyse_calendar import NYSECalendar
+
+
+__all__ = ['Calendar', 'NYSECalendar']

contango/broker/calendar/calendar.py

@@ -0,0 +1,47 @@
+# broker/calendar/calendar.py — part of Contango, a parameterized backtesting & execution framework
+# Copyright (C) 2026  Jacob Taylor
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from datetime import datetime
+
+from contango.broker.historical_brokers.config_type import Interval
+
+
+class Calendar(ABC):
+    """
+    A delegation of the available trading times for calendar type (i.e. NYSE or Crypto).
+    """
+    @abstractmethod
+    def get_expected_timestamps(
+        self,
+        start_timestamp: int,
+        end_timestamp: int,
+        interval: Interval,
+    ) -> list[datetime]:
+        """
+        Returns the expected available timestamps in a calendar for a specified period.
+        
+        Args:
+            start_timestamp: The start time in unix ms.
+            end_timestamp: The end time in unix ms.
+            interval: The bar interval type.
+        
+        Returns:
+            list[datetime]: The dates & times of the available trading bars for the designated period.
+        """
+        ...

contango/broker/calendar/nyse_calendar.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import cast
+from zoneinfo import ZoneInfo
+
+import exchange_calendars as xcals  # pyright: ignore[reportMissingTypeStubs]
+import pandas as pd
+
+from contango.broker.historical_brokers.config_type import Interval
+from contango.broker.calendar.calendar import Calendar
+
+
+class NYSECalendar(Calendar):
+    """
+    Trading calendar for the New York Stock Exchange (9:00AM-4:00PM on weekdays, holidays taken into account).
+    """
+    def __init__(self) -> None:
+        """
+        Initializes `NYSECalendar.
+        """
+        self._calendar = xcals.get_calendar("XNYS", start="1990-01-01")
+
+    def get_expected_timestamps(
+        self,
+        start_timestamp: int,
+        end_timestamp: int,
+        interval: Interval,
+    ) -> list[datetime]:
+        """
+        Returns the expected available NYSE timestamps for the specified period.
+
+        Args:
+            start_timestamp: The start time in unix ms.
+            end_timestamp: The end time in unix ms.
+            interval: The bar interval type.
+
+        Returns:
+            list[datetime]: The close times of the available NYSE trading bars for the designated period.
+        """
+        start_ny = pd.Timestamp(start_timestamp, unit="ms", tz=ZoneInfo("UTC")).tz_convert(ZoneInfo("America/New_York"))
+        end_ny = pd.Timestamp(end_timestamp, unit="ms", tz=ZoneInfo("UTC")).tz_convert(ZoneInfo("America/New_York"))
+
+        start_date = start_ny.tz_localize(None).normalize()
+        end_date = end_ny.tz_localize(None).normalize()
+
+        frequency = pd.Timedelta(interval.value)
+
+        raw_index = self._calendar.trading_index(
+            start=start_date,
+            end=end_date,
+            period=frequency,
+            intervals=True,
+            force=True,
+        )
+
+        close_timestamps: pd.DatetimeIndex
+        if isinstance(raw_index, pd.IntervalIndex):
+            close_timestamps = cast(pd.DatetimeIndex, raw_index.right)
+        else:
+            close_timestamps = raw_index.tz_localize(timezone.utc)
+
+        start_utc = start_ny.tz_convert(ZoneInfo("UTC"))
+        end_utc = end_ny.tz_convert(ZoneInfo("UTC"))
+
+        close_times: list[datetime] = [
+            ts.to_pydatetime().astimezone(timezone.utc)
+            for ts in close_timestamps
+            if start_utc <= ts <= end_utc
+        ]
+
+        return close_times

contango/broker/historical_brokers/__init__.py

@@ -0,0 +1,23 @@
+# broker/historical_brokers/__init__.py — part of Contango, a parameterized backtesting & execution framework
+# Copyright (C) 2026  Jacob Taylor
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+from __future__ import annotations
+
+from contango.broker.historical_brokers.historical_broker import HistoricalBroker
+from contango.broker.historical_brokers.config_type import Config, Interval
+
+
+__all__ = ['HistoricalBroker', 'Config', 'Interval']

contango/broker/historical_brokers/config_type.py

@@ -0,0 +1,55 @@
+# broker/historical_brokers/config_type.py — part of Contango, a parameterized backtesting & execution framework
+# Copyright (C) 2026  Jacob Taylor
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+from __future__ import annotations
+
+from enum import Enum
+from datetime import timedelta
+from dataclasses import dataclass
+
+
+class Interval(Enum):
+    """
+    The interval type to determine how frequent of bars to derive from a broker.
+    """
+    MINUTE_1 = timedelta(minutes=1)
+    MINUTE_2 = timedelta(minutes=2)
+    MINUTE_5 = timedelta(minutes=5)
+    MINUTE_15 = timedelta(minutes=15)
+    MINUTE_30 = timedelta(minutes=30)
+    MINUTE_60 = timedelta(minutes=60)
+    MINUTE_90 = timedelta(minutes=90)
+    HOUR_1 = timedelta(hours=1)
+    DAY_1 = timedelta(days=1)
+    DAY_5 = timedelta(days=5)
+    WEEK_1 = timedelta(weeks=1)
+
+
+@dataclass
+class Config:
+    """
+    Marks a dataclass as a configurator for a historical broker when deriving data from it.
+
+    Attributes:
+        ticker: The ticker symbol for a broker call.
+        interval: The interval for a broker call.
+        start_timestamp: The start time in unix ms to derive data from.
+        end_timestamp: The end time in unix ms to derive data from.
+    """
+    ticker: str
+    interval: Interval
+    start_timestamp: int
+    end_timestamp: int

contango/broker/historical_brokers/historical_broker.py

@@ -0,0 +1,49 @@
+# broker/historical_brokers/historical_broker.py — part of Contango, a parameterized backtesting & execution framework
+# Copyright (C) 2026  Jacob Taylor
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+from __future__ import annotations
+
+from typing import Generic, TypeVar, Iterable
+from abc import ABC, abstractmethod
+from datetime import datetime
+
+from contango.trading.execution.engine.events import MarketDataEvent
+from contango.broker.historical_brokers.config_type import Config
+
+
+TConfig = TypeVar("TConfig", bound=Config)
+
+
+class HistoricalBroker(ABC, Generic[TConfig]):
+    """
+    A single broker (or data provider) for historical market data.
+    """
+    @abstractmethod
+    def get_bars(self, config: TConfig) -> list[MarketDataEvent]:
+        """
+        Returns a list of market data events for any configuration parameters.
+        """
+        ...
+    
+    @abstractmethod
+    def get_expected_timestamps(
+        self,
+        config: TConfig,
+    ) -> Iterable[datetime]:
+        """
+        Returns an Iterable of the expected timestamps for the start & finishing timestamps of a configuration.
+        """
+        ...

contango/broker/historical_brokers/yfinance/__init__.py

@@ -0,0 +1,23 @@
+# broker/historical_brokers/yfinance/__init__.py — part of Contango, a parameterized backtesting & execution framework
+# Copyright (C) 2026  Jacob Taylor
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+from __future__ import annotations
+
+from contango.broker.historical_brokers.yfinance.yfinance import Yfinance
+from contango.broker.historical_brokers.yfinance.yfinance_config import YfinanceConfig
+
+
+__all__ = ['Yfinance', 'YfinanceConfig']

contango/broker/historical_brokers/yfinance/yfinance.py

@@ -0,0 +1,148 @@
+# broker/historical_brokers/yfinance/yfinance.py — part of Contango, a parameterized backtesting & execution framework
+# Copyright (C) 2026  Jacob Taylor
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+from __future__ import annotations
+
+import pandas as pd
+import yfinance as yf   # type: ignore[missingTypeStubs]
+
+from typing import Iterable
+from datetime import datetime, timezone
+
+from contango.broker.historical_brokers.historical_broker import HistoricalBroker
+from contango.broker.historical_brokers.yfinance.yfinance_config import YfinanceConfig
+from contango.broker.historical_brokers.config_type import Interval
+from contango.broker.calendar.calendar import Calendar
+
+from contango.trading.execution.engine.events import MarketDataEvent
+
+
+USD = float
+time_unix_ms = int
+units = int
+
+# Map interval values from the Enum to the expected str values via yfinance.download.
+INTERVAL_MAP: dict[Interval, str] = {
+    Interval.MINUTE_1: "1m",
+    Interval.MINUTE_2: "2m",
+    Interval.MINUTE_5: "5m",
+    Interval.MINUTE_15: "15m",
+    Interval.MINUTE_30: "30m",
+    Interval.MINUTE_60: "60m",
+    Interval.MINUTE_90: "90m",
+    Interval.HOUR_1: "1h",
+    Interval.DAY_1: "1d",
+    Interval.DAY_5: "5d",
+    Interval.WEEK_1: "1wk"
+}
+
+
+class Yfinance(HistoricalBroker[YfinanceConfig]):
+    """
+    The yfinance data provider (not an official broker).
+    Data is limited in large quantities, some data may be innacurate, and rate limiting may be enforced with usage.
+    """
+    def __init__(self, calendar: Calendar) -> None:
+        """
+        Initializes `Yfinance`.
+        
+        Args:
+            calendar: The calender type to follow (i.e. NYSE).
+        """
+        self._calendar = calendar
+
+    def _load_data(self, config: YfinanceConfig) -> pd.DataFrame:
+        """
+        Loads yfinance data from a `YfinanceConfig`.
+        
+        Args:
+            config: The determiner for the ticker, start, end, and interval when downloading yfinance data.
+        
+        Returns:
+            A normalized pandas dataframe representation of the yfinance data.
+        
+        Raises:
+            RuntimeError: If no data was returned for the given config.
+        """
+        start = datetime.fromtimestamp(config.start_timestamp / 1000, tz=timezone.utc).strftime('%Y-%m-%d')
+        end = datetime.fromtimestamp(config.end_timestamp / 1000, tz=timezone.utc).strftime('%Y-%m-%d')
+        interval = INTERVAL_MAP.get(config.interval, None)
+
+        if interval is None:
+            raise RuntimeError("Interval type provided was not in the interval map for yfinance!")
+
+        data = yf.download( # type: ignore[unknownMemberType]
+            tickers=config.ticker,
+            start=start,
+            end=end,
+            interval=interval,
+        )
+
+        if data is None or data.empty:
+            raise RuntimeError(f"No data returned for {config.ticker}")
+
+        return data
+
+    def get_bars(self, config: YfinanceConfig) -> list[MarketDataEvent]:
+        """
+        Returns a list of the bars for the given period.
+        
+        Args:
+            config: The yfinance config to derive bars from.
+        
+        Raises:
+            RuntimeError: Upon yfinance not returning any data.
+        """
+        data = self._load_data(config)
+
+        if isinstance(data.columns, pd.MultiIndex):
+            data.columns = data.columns.get_level_values(0)
+
+        bars: list[MarketDataEvent] = []
+        for timestamp, row in data.iterrows():
+            bars.append(
+                MarketDataEvent(
+                    timestamp=int(pd.Timestamp(timestamp).timestamp() * 1000),  # type: ignore[argumentType]
+                    symbol=config.ticker,
+                    open=float(row["Open"]),
+                    high=float(row["High"]),
+                    low=float(row["Low"]),
+                    close=float(row["Close"]),
+                    volume=int(row["Volume"]),
+                )
+            )
+
+        return bars
+
+    def get_expected_timestamps(
+        self,
+        config: YfinanceConfig,
+    ) -> Iterable[datetime]:
+        """
+        Returns the expected yfinance timestamps for the given calendar at initialization.
+
+        Args:
+            config: The configuration, in which the start timestamp, end timestamp, & interval will be used to 
+                    derive the valid timestamps from.
+        
+        Returns:
+            Iterable[datetime]: An iterable of valid datetime objects.
+        """
+        return self._calendar.get_expected_timestamps(
+            start_timestamp=config.start_timestamp,
+            end_timestamp=config.end_timestamp,
+            interval=config.interval,
+        )

contango/broker/historical_brokers/yfinance/yfinance_config.py

@@ -0,0 +1,35 @@
+# broker/historical_brokers/yfinance/yfinance_config.py — part of Contango, a parameterized backtesting & execution framework
+# Copyright (C) 2026  Jacob Taylor
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from contango.broker.historical_brokers.config_type import Config
+
+
+@dataclass
+class YfinanceConfig(Config):
+    """
+    Holds the configuration for deriving data from the yfinance broker.
+    
+    Attributes:
+        ticker: The ticker symbol (e.g. AAPL) to derive yfinance data from.
+        start_date: The start date (YYYY-MM-DD) to derive yfinance data from.
+        end_date: The end date (YYYY-MM-DD) to derive yfinance data from.
+        interval: The trading interval to derive yfinance data from.
+    """
+    pass

contango/data/__init__.py

@@ -0,0 +1,22 @@
+# data/__init__.py — part of Contango, a parameterized backtesting & execution framework
+# Copyright (C) 2026  Jacob Taylor
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+from __future__ import annotations
+
+from contango.data.data_repository import DataRepository
+
+
+__all__ = ['DataRepository']

contango/data/data_repository.py

@@ -0,0 +1,79 @@
+# data/data_repository.py — part of Contango, a parameterized backtesting & execution framework
+# Copyright (C) 2026  Jacob Taylor
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+from __future__ import annotations
+
+from dataclasses import replace
+from pathlib import Path
+from typing import Generic, TypeVar, Iterable
+from datetime import datetime
+
+from contango.broker.historical_brokers.config_type import Config
+from contango.broker.historical_brokers.historical_broker import HistoricalBroker
+
+from contango.trading.execution.engine.events.events import MarketDataEvent
+
+from contango.data.storage.store_market_data import DataStorage
+
+
+TConfig = TypeVar("TConfig", bound=Config)
+
+
+class DataRepository(Generic[TConfig]):
+    """
+    Retrieves data from either internal storage, a broker, or both.
+    Data that is not already in storage is automatically added.
+    """
+    @staticmethod
+    def get_data_and_store(
+        broker: HistoricalBroker[TConfig],
+        config: TConfig,
+        expected_timestamps: Iterable[datetime],
+        database_path: str | Path | None = None,
+    ) -> list[MarketDataEvent]:
+        """
+        Retrieves data from either the database, a broker, or both.
+        Any data not in the database that is retrieved from the broker is then put into storage for further use.
+
+        Args:
+            broker: The historical broker to derive data from if necessary.
+            config: The corresponding config to the historical broker.
+            expected_timestamps: An iterable of the expected timestamps.
+            database_path: Where the database should live. If not provided,
+                           DataStorage resolves it via  the OS-standard
+                           user data directory.
+        """
+        with DataStorage(database_path) as storage:
+            ticker = config.ticker
+            interval = config.interval.__str__()
+            start_timestamp = config.start_timestamp
+            end_timestamp = config.end_timestamp
+            missing_timestamps = storage.get_missing_timestamps(ticker, interval, expected_timestamps)
+            if len(missing_timestamps) != 0:
+                min_timestamp = min(missing_timestamps)
+                max_timestamp = max(missing_timestamps)
+                interval_ms = int(config.interval.value.total_seconds() * 1000)
+                new_config = replace(
+                    config,
+                    start_timestamp=min_timestamp,
+                    end_timestamp=max(max_timestamp + interval_ms, min_timestamp + interval_ms),
+                )
+                new_data = broker.get_bars(new_config)
+                storage.add_data_to_storage(interval, new_data)
+
+            data = storage.get_data(ticker, interval, start_timestamp, end_timestamp)
+
+        return data

contango/data/storage/__init__.py

@@ -0,0 +1,20 @@
+# data/storage/__init__.py — part of Contango, a parameterized backtesting & execution framework
+# Copyright (C) 2026  Jacob Taylor
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+from __future__ import annotations
+
+
+__all__ = []