ohlc-toolkit 0.1.0__tar.gz

ohlc_toolkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) [2025] [Mourits de Beer]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ohlc_toolkit-0.1.0/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.3
+Name: ohlc-toolkit
+Version: 0.1.0
+Summary: A flexible toolkit for working with OHLC data and generating custom time frames from minute data.
+License: MIT
+Keywords: ohlc,price,candlestick,financial,market-data,time-series
+Author: Mourits de Beer
+Author-email: ff137@proton.me
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Provides-Extra: ipyparallel
+Requires-Dist: ipyparallel (>=9.0.0,<10.0.0) ; extra == "ipyparallel"
+Requires-Dist: loguru (>=0.7.3)
+Requires-Dist: numpy (>=2.2.2,<3.0.0)
+Requires-Dist: orjson (>=3.10.15,<4.0.0)
+Requires-Dist: pandas (>=2.2.2,<3.0.0)
+Requires-Dist: pyarrow (>=19.0.0,<20.0.0)
+Requires-Dist: tqdm (>=4.66.4,<5.0.0)
+Project-URL: Repository, https://github.com/ff137/ohlc-toolkit
+Description-Content-Type: text/markdown
+
+# OHLC Toolkit
+
+A flexible toolkit for working with OHLC (Open, High, Low, Close) data and generating custom time frames from minute data.
+
+## Features
+
+- Read OHLC data from CSV files
+- Process high resolution data (e.g. 1-minute interval data) into any greater time frame
+- Calculate future returns from OHLC data
+- Compute technical indicators
+

ohlc_toolkit-0.1.0/README.md

@@ -0,0 +1,10 @@
+# OHLC Toolkit
+
+A flexible toolkit for working with OHLC (Open, High, Low, Close) data and generating custom time frames from minute data.
+
+## Features
+
+- Read OHLC data from CSV files
+- Process high resolution data (e.g. 1-minute interval data) into any greater time frame
+- Calculate future returns from OHLC data
+- Compute technical indicators

ohlc_toolkit-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[tool.poetry]
+name = "ohlc-toolkit"
+version = "0.1.0"
+description = "A flexible toolkit for working with OHLC data and generating custom time frames from minute data."
+authors = ["Mourits de Beer <ff137@proton.me>"]
+license = "MIT"
+readme = "README.md"
+keywords = [
+    "ohlc",
+    "price",
+    "candlestick",
+    "financial",
+    "market-data",
+    "time-series",
+]
+repository = "https://github.com/ff137/ohlc-toolkit"
+
+[tool.poetry.dependencies]
+python = "^3.10"
+loguru = ">=0.7.3"
+numpy = "^2.2.2"
+orjson = "^3.10.15"
+pandas = "^2.2.2"
+pyarrow = "^19.0.0"
+tqdm = "^4.66.4"
+# pyspark = { version = ">=3.2.0", optional = true }
+ipyparallel = { version = "^9.0.0", optional = true }
+
+[tool.poetry.extras]
+# spark = ["pyspark"]
+ipyparallel = ["ipyparallel"]
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.3.4"
+pytest-cov = "^6.0.0"
+pytest-ruff = "^0.4.1"
+ruff = "^0.9.4"
+
+[tool.ruff]
+lint.select = ["B006", "C", "D", "E", "F"]
+lint.ignore = [
+    "D203",
+    "D204",
+    "D213",
+    "D215",
+    "D400",
+    "D401",
+    "D404",
+    "D406",
+    "D407",
+    "D408",
+    "D409",
+    "D413",
+]
+include = ["src/*.py"]
+line-length = 88
+
+[tool.pytest.ini_options]
+testpaths = "tests"
+addopts = "--cov=src --cov-report term --ruff --ruff-format"
+
+[tool.coverage.run]
+omit = ["tests/*", "examples/*"]
+
+[tool.coverage.report]
+skip_covered = false
+show_missing = true
+
+[build-system]
+requires = ["poetry-core>=2.0.0"]
+build-backend = "poetry.core.masonry.api"

ohlc_toolkit-0.1.0/src/ohlc_toolkit/__init__.py

@@ -0,0 +1 @@
+"""OHLC Toolkit."""

ohlc_toolkit-0.1.0/src/ohlc_toolkit/config/__init__.py

@@ -0,0 +1,3 @@
+"""Configuration for the ohlc_toolkit package."""
+
+EXPECTED_COLUMNS = ["timestamp", "open", "high", "low", "close", "volume"]

ohlc_toolkit-0.1.0/src/ohlc_toolkit/config/log_config.py

@@ -0,0 +1,189 @@
+"""Configuration for the ohlc_toolkit package."""
+
+import os
+import sys
+from datetime import datetime
+
+import orjson
+from loguru._logger import Core as _Core
+from loguru._logger import Logger as _Logger
+
+STDOUT_LOG_LEVEL = os.getenv("LOG_LEVEL", "DEBUG").upper()
+FILE_LOG_LEVEL = os.getenv("FILE_LOG_LEVEL", "DEBUG").upper()
+ENABLE_FILE_LOGGING = os.getenv("ENABLE_FILE_LOGGING", "").upper() == "TRUE"
+DISABLE_COLORIZE_LOGS = os.getenv("DISABLE_COLORIZE_LOGS", "").upper() == "TRUE"
+ENABLE_SERIALIZE_LOGS = os.getenv("ENABLE_SERIALIZE_LOGS", "").upper() == "TRUE"
+LOGURU_DIAGNOSE = os.getenv("LOGURU_DIAGNOSE", "").upper() == "TRUE"
+
+colorize = not DISABLE_COLORIZE_LOGS
+serialize = ENABLE_SERIALIZE_LOGS
+
+# Create a mapping of module name to color
+color_map = {
+    "ohlc_toolkit": "blue",
+}
+
+
+def formatter_builder(color: str):
+    """Build a formatter for the logger."""
+    return (
+        "<green>{time:YYYY-MM-DD HH:mm:ss.SSS}</green> | "
+        "<level>{level: <8}</level> | "
+        f"<{color}>{{name}}</{color}>"
+        f":<{color}>"
+        f"{{function}}</{color}>"
+        f":<{color}>"
+        f"{{line}}</{color}>"
+        " | "
+        "<level>{message}</level> | "
+        "{extra[body]}"
+    )
+
+
+# Define custom formatter for serialized logs
+def _serialize_record(record):
+    record_time: datetime = record["time"]
+
+    # format the time field to ISO8601 format
+    iso_date = record_time.isoformat()
+
+    # Handle exceptions as default
+    exception = record["exception"]
+
+    if exception is not None:
+        exception = {
+            "type": None if exception.type is None else exception.type.__name__,
+            "value": exception.value,
+            "traceback": bool(exception.traceback),
+        }
+
+    # Define subset of serialized record - combining message + extra into the text field
+    message = record["message"]
+    extra = record["extra"].get("body")
+    message_with_body = f"{message} | {extra}"
+
+    # we keep fields commented out to compare with loguru's default serialisation
+    subset = {
+        "message": message_with_body,
+        "levelname": record["level"].name,  # log level
+        "date": iso_date,
+        "name": record["name"],
+        "record": {
+            # "elapsed": {
+            #     "repr": record["elapsed"],
+            #     "seconds": record["elapsed"].total_seconds(),
+            # },
+            "exception": exception,
+            # "extra": record["extra"],
+            # "file": {"name": record["file"].name, "path": record["file"].path},
+            "file": record["file"].path,
+            "function": record["function"],
+            # "level": {
+            #     "icon": record["level"].icon,
+            #     "name": record["level"].name,
+            #     "no": record["level"].no,
+            # },
+            "line": record["line"],
+            # "message": record["message"],
+            # "module": record["module"],
+            "process": {"id": record["process"].id, "name": record["process"].name},
+            "thread": {"id": record["thread"].id, "name": record["thread"].name},
+            "time": {
+                "repr": int(1000 * record_time.timestamp()),  # to milliseconds
+                "uptime_h:m:s": record["elapsed"],
+            },
+        },
+    }
+    record["extra"]["serialized"] = orjson.dumps(subset, default=str).decode("utf-8")
+    return "{extra[serialized]}\n"
+
+
+# This will hold our logger instances
+loggers = {}
+
+
+def get_log_file_path(main_module_name) -> str:
+    """Get the log file path for the given module name."""
+    # The absolute path of this file's directory
+    config_dir = os.path.dirname(os.path.abspath(__file__))
+
+    # Move up one level to get to the project root directory
+    base_dir = os.path.dirname(config_dir)
+
+    # Define the logging dir with
+    log_dir = os.path.join(base_dir, f"logs/{main_module_name}")
+    return os.path.join(log_dir, "{time:YYYY-MM-DD}.log")
+
+
+def get_logger(name: str):
+    """Get a logger instance for the given module name."""
+    # Get the main module name
+    main_module_name = name.split(".")[0]
+
+    # Check if a logger for this name already exists
+    if main_module_name in loggers:
+        return loggers[main_module_name].bind(name=name)
+
+    # Create a new logger instance
+    logger_ = _Logger(
+        core=_Core(),
+        exception=None,
+        depth=0,
+        record=False,
+        lazy=False,
+        colors=False,
+        raw=False,
+        capture=True,
+        patchers=[],
+        extra={},
+    )
+
+    logger_.configure(extra={"body": ""})  # Default values for extra args
+
+    if not serialize:
+        # Get the color for this module and build formatter
+        color = color_map.get(main_module_name, "blue")  # Default to blue if no mapping
+        formatter = formatter_builder(color)
+
+        # Log to stdout
+        logger_.add(
+            sys.stdout,
+            level=STDOUT_LOG_LEVEL,
+            diagnose=True,  # for local dev
+            format=formatter,
+            colorize=colorize,
+        )
+    else:  # serialization is enabled:
+        logger_.add(
+            sys.stdout,
+            level=STDOUT_LOG_LEVEL,
+            diagnose=LOGURU_DIAGNOSE,  # default = disabled for serialized logs
+            format=_serialize_record,  # Use our custom serialization formatter
+        )
+
+    # Log to a file
+    if ENABLE_FILE_LOGGING:
+        try:
+            logger_.add(
+                get_log_file_path(main_module_name),
+                rotation="00:00",  # new file is created at midnight
+                retention="7 days",  # keep logs for up to 7 days
+                enqueue=True,  # asynchronous
+                level=FILE_LOG_LEVEL,
+                diagnose=True,
+                format=formatter_builder("blue"),
+                serialize=serialize,
+            )
+        except PermissionError:
+            logger_.warning(
+                "Permission error caught when trying to create log file. "
+                "Continuing without file logging for `{}` in `{}`",
+                name,
+                main_module_name,
+            )
+
+    # Store the logger in the dictionary
+    loggers[main_module_name] = logger_
+
+    # Return a logger bound with the full name including the submodule
+    return logger_.bind(name=name)

ohlc_toolkit-0.1.0/src/ohlc_toolkit/csv_reader.py

@@ -0,0 +1,86 @@
+"""Module for loading OHLC data from a CSV file."""
+
+from typing import Optional
+
+import pandas as pd
+
+from ohlc_toolkit.config import EXPECTED_COLUMNS
+from ohlc_toolkit.config.log_config import get_logger
+from ohlc_toolkit.timeframes import (
+    parse_timeframe,
+    validate_timeframe,
+    validate_timeframe_format,
+)
+from ohlc_toolkit.utils import check_data_integrity, infer_time_step
+
+logger = get_logger(__name__)
+
+
+def read_ohlc_csv(
+    filepath: str,
+    timeframe: Optional[str] = None,
+    expected_columns: Optional[list[str]] = None,
+    header_row: Optional[int] = None,
+    dtype: Optional[dict[str, str]] = None,
+) -> pd.DataFrame:
+    """Read OHLC data from a CSV file.
+
+    Arguments:
+        filepath (str): Path to the CSV file.
+        timeframe (Optional[str]): User-defined timeframe (e.g., '1m', '5m', '1h').
+        expected_columns (Optional[list[str]]): The expected columns in the CSV file.
+        header_row (Optional[int]): The row number to use as the header.
+        dtype (Optional[dict[str, str]]): The data type for the columns.
+
+    Returns:
+        pd.DataFrame: Processed OHLC dataset.
+    """
+    bound_logger = logger.bind(body=filepath)
+    bound_logger.info("Reading OHLC data")
+
+    if expected_columns is None:
+        expected_columns = EXPECTED_COLUMNS
+    if dtype is None:
+        dtype = {"timestamp": "int32"}
+
+    read_csv_params = {
+        "filepath_or_buffer": filepath,
+        "names": expected_columns,
+        "dtype": dtype,
+    }
+
+    # If header_row is provided, use it directly
+    if header_row is not None:
+        df = pd.read_csv(**read_csv_params, header=header_row)
+    else:
+        # User doesn't specify header - let's try reading without header first
+        try:
+            df = pd.read_csv(**read_csv_params, header=None)
+        except FileNotFoundError:
+            raise FileNotFoundError(f"File not found: {filepath}")
+        except ValueError:
+            # If that fails, try with header
+            df = pd.read_csv(**read_csv_params, header=0)
+
+    bound_logger.debug(
+        f"Read {df.shape[0]} rows and {df.shape[1]} columns: {df.columns.tolist()}"
+    )
+
+    # Infer time step from data
+    time_step = infer_time_step(df)
+
+    # Convert user-defined timeframe to seconds
+    timeframe_seconds = None
+    if timeframe:
+        if not validate_timeframe_format(timeframe):
+            raise ValueError(f"Invalid timeframe format: {timeframe}")
+
+        timeframe_seconds = parse_timeframe(timeframe)
+
+        validate_timeframe(time_step, timeframe_seconds, bound_logger)
+
+    # Perform integrity checks
+    check_data_integrity(df, time_step)
+
+    bound_logger.info("OHLC data successfully loaded.")
+    return df

ohlc_toolkit-0.1.0/src/ohlc_toolkit/timeframes.py

@@ -0,0 +1,113 @@
+"""This module contains functions for parsing and formatting timeframes."""
+
+import re
+from logging import Logger
+
+# Predefined common timeframes for faster lookup
+COMMON_TIMEFRAMES = {
+    "1m": 60,
+    "3m": 180,
+    "5m": 300,
+    "15m": 900,
+    "30m": 1800,
+    "1h": 3600,
+    "2h": 7200,
+    "4h": 14400,
+    "6h": 21600,
+    "8h": 28800,
+    "12h": 43200,
+    "1d": 86400,
+    "2d": 172800,
+    "3d": 259200,
+    "4d": 345600,
+    "1w": 604800,
+    "2w": 1209600,
+    "3w": 1814400,
+    "4w": 2419200,
+}
+
+# Regex pattern to parse timeframe strings
+TIMEFRAME_PATTERN = re.compile(r"(\d+)([wdhms])", re.IGNORECASE)
+TIMEFRAME_FORMAT_PATTERN = re.compile(r"^(\d+[wdhms])+$", re.IGNORECASE)
+
+# Unit conversion
+TIME_UNITS = {
+    "w": 604800,  # Weeks to seconds
+    "d": 86400,  # Days to seconds
+    "h": 3600,  # Hours to seconds
+    "m": 60,  # Minutes to seconds
+    "s": 1,  # Seconds to seconds
+}
+
+
+def parse_timeframe(timeframe: str) -> int:
+    """Convert a timeframe string (e.g., '1h', '4h30m', '1w3d7h14m') into total seconds.
+
+    Arguments:
+        timeframe (str): Human-readable timeframe.
+
+    Returns:
+        int: Total number of seconds.
+
+    Raises:
+        ValueError: If the format is invalid.
+    """
+    if not validate_timeframe_format(timeframe):
+        raise ValueError(f"Invalid timeframe format: {timeframe}")
+
+    matches = TIMEFRAME_PATTERN.findall(timeframe)
+    total_seconds = sum(
+        int(amount) * TIME_UNITS[unit.lower()] for amount, unit in matches
+    )
+    return total_seconds
+
+
+def format_timeframe(seconds: int) -> str:
+    """Convert a total number of seconds into a human-readable timeframe string.
+
+    Arguments:
+        seconds (int): Total number of seconds.
+
+    Returns:
+        str: Human-readable timeframe string (e.g., '1h', '4h30m').
+    """
+    if seconds in COMMON_TIMEFRAMES.values():
+        # Return predefined common timeframes if found
+        return {v: k for k, v in COMMON_TIMEFRAMES.items()}[seconds]
+
+    units = [("w", 604800), ("d", 86400), ("h", 3600), ("m", 60), ("s", 1)]
+    parts = []
+
+    for unit, unit_seconds in units:
+        value, seconds = divmod(seconds, unit_seconds)
+        if value > 0:
+            parts.append(f"{value}{unit}")
+
+    return "".join(parts)
+
+
+def validate_timeframe_format(timeframe: str) -> bool:
+    """Validate whether a given timeframe string follows the expected format.
+
+    Arguments:
+        timeframe (str): Timeframe string to validate.
+
+    Returns:
+        bool: True if valid, False otherwise.
+    """
+    return bool(TIMEFRAME_FORMAT_PATTERN.fullmatch(timeframe))
+
+
+def validate_timeframe(time_step: int, user_timeframe: int, logger: Logger):
+    """Ensure that the timeframe is valid given the time step."""
+    if user_timeframe < time_step:
+        raise ValueError(
+            f"Provided timeframe ({user_timeframe}s) cannot be smaller "
+            f"than inferred time step ({time_step}s)."
+        )
+
+    if user_timeframe % time_step != 0:
+        logger.warning(
+            f"Provided timeframe ({user_timeframe}s) is not a multiple "
+            f"of the inferred time step ({time_step}s). Data may be incomplete."
+        )

ohlc_toolkit-0.1.0/src/ohlc_toolkit/utils.py

@@ -0,0 +1,38 @@
+"""This module contains utility functions for the OHLC toolkit."""
+
+from typing import Optional
+
+import numpy as np
+import pandas as pd
+from loguru import logger
+
+
+def infer_time_step(df: pd.DataFrame) -> int:
+    """Infer the time step by analyzing the timestamp column."""
+    time_diffs = np.diff(df["timestamp"])
+
+    if len(time_diffs) == 0:
+        raise ValueError("Cannot infer time step from a single-row dataset.")
+
+    time_step = int(pd.Series(time_diffs).mode()[0])  # Most frequent difference
+    logger.info(f"Inferred time step: {time_step} seconds")
+    return time_step
+
+
+def check_data_integrity(df: pd.DataFrame, time_step: Optional[int] = None):
+    """Perform basic data integrity checks on the OHLC dataset."""
+    if df.isnull().values.any():
+        logger.warning("Data contains null values.")
+
+    if df["timestamp"].duplicated().any():
+        logger.warning("Duplicate timestamps found in the dataset.")
+
+    if time_step:
+        expected_timestamps = set(
+            range(df["timestamp"].min(), df["timestamp"].max() + time_step, time_step)
+        )
+        actual_timestamps = set(df["timestamp"])
+        missing_timestamps = expected_timestamps - actual_timestamps
+
+        if missing_timestamps:
+            logger.warning(f"Missing {len(missing_timestamps)} timestamps in dataset.")