# requests: HTTP client library for making web requests.
# pandas: Data manipulation and analysis library, used for tabular reporting.
!pip install requests pandas

import warnings
warnings.filterwarnings("ignore")

# Standard library imports for core functionalities
import time
import random
import logging
import sys
import json
from collections import deque
from functools import wraps
from datetime import datetime, timezone

# Third-party library for data manipulation
import pandas as pd

# Configure application logger for consistent output
logging.basicConfig(
    level=logging.INFO, # Keep basicConfig for root logger, but set specific logger level explicitly
    format="%(asctime)s | %(levelname)-8s | %(message)s",
    datefmt="%H:%M:%S",
    stream=sys.stdout,
)

# Initialize a logger specific to rate limiting operations
logger = logging.getLogger("rate_limiter")
logger.setLevel(logging.DEBUG) # Explicitly set the level for the 'rate_limiter' logger

def create_token_bucket(
    max_tokens: float,
    refill_rate: float,
) -> dict:
    """
    Initializes a new token bucket state.

    Parameters
    ----------
    max_tokens : float
        Maximum token capacity of the bucket.
    refill_rate : float
        Rate at which tokens are added to the bucket per second.

    Returns
    -------
    dict
        A dictionary representing the token bucket's current state, including:
        - 'max_tokens': The maximum capacity of the bucket.
        - 'refill_rate': The token replenishment rate.
        - 'tokens': The current number of tokens in the bucket (initially max_tokens).
        - 'last_refill': The monotonic timestamp of the last refill operation.
    """
    return {
        "max_tokens": max_tokens,
        "refill_rate": refill_rate,
        "tokens": max_tokens,  # Bucket starts full.
        "last_refill": time.monotonic(), # Record initial time.
    }

def token_bucket_acquire(
    bucket: dict,
    tokens_needed: float = 1.0,
) -> float:
    """
    Acquires the specified number of tokens from the bucket. If insufficient tokens are available,
    execution blocks until enough tokens have accumulated.

    Parameters
    ----------
    bucket : dict
        The mutable state of the token bucket.
    tokens_needed : float, optional
        The number of tokens required for the current operation (default is 1.0).

    Returns
    -------
    float
        The duration (in seconds) the process waited to acquire tokens.
    """

    now = time.monotonic() # Current monotonic timestamp.

    # Calculate elapsed time since the last token refill.
    elapsed = now - bucket["last_refill"]

    # Determine the number of new tokens generated during the elapsed time.
    new_tokens = elapsed * bucket["refill_rate"]

    # Replenish the bucket, ensuring not to exceed its maximum capacity.
    bucket["tokens"] = min(
        bucket["max_tokens"],
        bucket["tokens"] + new_tokens,
    )

    # Update the timestamp of the last refill operation.
    bucket["last_refill"] = now

    # If sufficient tokens are available, consume them immediately and return no wait time.
    if bucket["tokens"] >= tokens_needed:
        bucket["tokens"] -= tokens_needed
        return 0.0

    # Calculate the token deficit and the required wait time to generate sufficient tokens.
    deficit = tokens_needed - bucket["tokens"]
    wait_time = deficit / bucket["refill_rate"]

    logger.debug(
        "Token bucket wait: %.3fs for %.2f tokens",
        wait_time,
        tokens_needed,
    )

    # Pause execution for the calculated wait time.
    time.sleep(wait_time)

    # After waiting, the bucket is effectively emptied for the requested tokens, as they are now available.
    bucket["tokens"] = 0.0
    # Update the refill timestamp to reflect the end of the wait period.
    bucket["last_refill"] = time.monotonic()

    return wait_time

logger.info("--- Token Bucket Demonstration ---")

# Initialize a token bucket with a capacity of 5 tokens and a refill rate of 5 tokens/second.
bucket = create_token_bucket(
    max_tokens=5,
    refill_rate=5,
)

# Simulate 8 requests to demonstrate token acquisition and waiting.
for i in range(8):
    # Attempt to acquire a token; execution will pause if insufficient tokens are available.
    wait = token_bucket_acquire(bucket)

    # Log the status of each request, including wait time and remaining tokens.
    logger.info(
        "Request %d | waited=%.3fs | remaining_tokens=%.2f",
        i + 1,
        wait,
        bucket["tokens"],
    )

def create_sliding_window(
    max_calls: int,
    window_secs: float,
) -> dict:
    """
    Initializes a new sliding window rate limiter state.

    Parameters
    ----------
    max_calls : int
        The maximum number of calls permitted within the sliding window.
    window_secs : float
        The duration of the sliding window in seconds.

    Returns
    -------
    dict
        A dictionary representing the sliding window's state, including:
        - 'max_calls': The maximum call count.
        - 'window_secs': The window duration.
        - 'call_times': A deque storing the monotonic timestamps of recent calls.
    """
    return {
        "max_calls": max_calls,
        "window_secs": window_secs,
        "call_times": deque(), # Stores timestamps of calls within the window.
    }

def sliding_window_acquire(window: dict) -> float:
    """
    Enforces sliding window rate limiting. If the call limit within the window is reached,
    execution is paused until a slot becomes available.

    Parameters
    ----------
    window : dict
        The mutable state of the sliding window rate limiter.

    Returns
    -------
    float
        The duration (in seconds) the process waited to make the call.
    """
    now = time.monotonic() # Current monotonic timestamp.

    # Remove timestamps of calls that have expired from the window.
    while (
        window["call_times"]
        and (now - window["call_times"][0]) >= window["window_secs"]
    ):
        window["call_times"].popleft() # Remove the oldest call.

    # If the number of calls in the window is below the maximum, record the current call and return no wait time.
    if len(window["call_times"]) < window["max_calls"]:
        window["call_times"].append(now) # Add current call timestamp.
        return 0.0

    # Calculate the wait time required until the oldest call in the window expires.
    oldest_call = window["call_times"][0]
    wait_time = window["window_secs"] - (now - oldest_call)

    logger.debug(
        "Sliding window wait: %.3fs",
        wait_time,
    )

    # Pause execution for the calculated wait time, ensuring it's not negative.
    time.sleep(max(0, wait_time))

    # Record the current call's timestamp after the wait period.
    window["call_times"].append(time.monotonic())

    return wait_time

logger.info("--- Sliding Window Demonstration ---")

# Initialize a sliding window with a maximum of 3 calls within a 2-second window.
sw = create_sliding_window(
    max_calls=3,
    window_secs=2.0,
)

# Simulate 7 requests to demonstrate sliding window enforcement.
for i in range(7):
    # Attempt to acquire a slot in the sliding window; execution will pause if the limit is exceeded.
    wait = sliding_window_acquire(sw)

    # Log the status of each request, including wait time and the number of calls currently in the window.
    logger.info(
        "Request %d | waited=%.3fs | calls_in_window=%d",
        i + 1,
        wait,
        len(sw["call_times"]),
    )

def exponential_backoff_sleep(
    attempt: int,
    base_delay: float = 1.0,
    max_delay: float = 60.0,
    backoff_factor: float = 2.0,
    jitter: bool = True,
) -> float:
    """
    Applies an exponential backoff delay, optionally with jitter, before a retry attempt.

    Parameters
    ----------
    attempt : int
        The current retry attempt number (0-indexed).
    base_delay : float, optional
        The initial delay in seconds for the first retry (default is 1.0).
    max_delay : float, optional
        The maximum allowed delay in seconds (default is 60.0).
    backoff_factor : float, optional
        The multiplier for exponential growth of the delay (default is 2.0).
    jitter : bool, optional
        If True, a random delay between 0 and the calculated delay is used
        to prevent synchronized retries (default is True).

    Returns
    -------
    float
        The actual duration (in seconds) the process slept.
    """
    # Calculate the exponential delay, capping it at max_delay.
    delay = min(
        base_delay * (backoff_factor ** attempt),
        max_delay,
    )

    # Apply jitter if enabled, randomizing the delay within the calculated range.
    if jitter:
        delay = random.uniform(0, delay)

    logger.warning(
        "Backoff delay: %.2fs",
        delay,
    )

    time.sleep(delay) # Pause execution for the calculated delay.

    return delay

logger.info("--- Exponential Backoff Schedule ---")

schedule = []

# Generate a schedule of exponential backoff delays for 8 retry attempts.
for attempt in range(8):
    # Calculate delay with a base of 1.0s and a factor of 2.0, capped at 60.0s.
    delay = min(1.0 * (2.0 ** attempt), 60.0)

    schedule.append({
        "attempt": attempt + 1,
        "delay_seconds": delay,
    })

# Display the generated backoff schedule.
pd.DataFrame(schedule)

def call_with_retry(
    func,
    *args,
    max_retries: int = 5,
    base_delay: float = 1.0,
    max_delay: float = 60.0,
    backoff_factor: float = 2.0,
    retry_on: tuple = (429, 500, 502, 503, 504), # HTTP status codes to trigger a retry.
    **kwargs,
):
    """
    Executes a given function with built-in retry handling, supporting exponential backoff
    and specific handling for HTTP 429 responses.

    Parameters
    ----------
    func : callable
        The function to be executed and retried.
    *args
        Positional arguments passed to `func`.
    max_retries : int, optional
        The maximum number of retry attempts (default is 5).
    base_delay : float, optional
        The base delay in seconds for exponential backoff (default is 1.0).
    max_delay : float, optional
        The maximum delay in seconds for exponential backoff (default is 60.0).
    backoff_factor : float, optional
        The multiplier for exponential backoff (default is 2.0).
    retry_on : tuple, optional
        A tuple of HTTP status codes that should trigger a retry (default is (429, 500, 502, 503, 504)).
    **kwargs
        Keyword arguments passed to `func`.

    Returns
    -------
    Any or None
        The result of the `func` call if successful, or None if all retries fail
        and no exception is raised.

    Raises
    ------
    Exception
        Re-raises the last encountered exception if all retries are exhausted and
        an exception was caught.
    """
    last_exception = None # Stores the last exception encountered.

    for attempt in range(max_retries + 1): # Iterate for initial call + max_retries.
        try:
            result = func(*args, **kwargs)

            # Check if the result object has an HTTP status code attribute.
            if hasattr(result, "status_code"):
                if result.status_code == 200:
                    return result # Success: return result immediately.

                elif result.status_code == 429: # Handle Too Many Requests specifically.
                    retry_after = result.headers.get("Retry-After") # Check for Retry-After header.

                    if retry_after: # If header is present, use its value for delay.
                        wait = float(retry_after)
                        time.sleep(wait)
                    else: # Otherwise, use exponential backoff.
                        exponential_backoff_sleep(
                            attempt,
                            base_delay,
                            max_delay,
                            backoff_factor,
                            jitter=True,
                        )

                elif result.status_code in retry_on: # Handle other retryable errors.
                    if attempt < max_retries: # If retries remaining, apply backoff.
                        exponential_backoff_sleep(
                            attempt,
                            base_delay,
                            max_delay,
                            backoff_factor,
                            jitter=True,
                        )
                    else:
                        return result # No retries left, return the failed result.

                else:
                    return result # Non-retryable status code, return result.

            else:
                return result # Result without status_code, assume success or non-HTTP context.

        except Exception as exc:
            last_exception = exc # Capture the exception.

            logger.error(
                "Retry exception: %s",
                exc,
            )

            if attempt < max_retries: # If retries remaining, apply backoff.
                exponential_backoff_sleep(
                    attempt,
                    base_delay,
                    max_delay,
                    backoff_factor,
                    jitter=True,
                )

    if last_exception: # If an exception occurred and all retries exhausted, re-raise.
        raise last_exception

    return None # All retries exhausted without a successful result or re-raised exception.

_fail_count = [0]

def simulated_api_call(fail_times: int = 3):
    """
    Simulate an API endpoint that returns HTTP 429 Too Many Requests for a specified number of initial calls,
    then returns HTTP 200 OK.
    """
    class FakeResponse:
        """A mock HTTP response object."""
        def __init__(self, status_code):
            self.status_code = status_code
            self.headers = {}

    _fail_count[0] += 1

    # Return 429 if the simulated failure count has not been reached.
    if _fail_count[0] <= fail_times:
        logger.info(f"Simulated API call returning 429 (attempt {_fail_count[0]})")
        return FakeResponse(429)

    # Return 200 after the failure count is exceeded.
    logger.info("Simulated API call returning 200 OK.")
    return FakeResponse(200)

# Execute the simulated API call with retry logic.
# The system will retry up to 5 times, with exponential backoff.
result = call_with_retry(
    simulated_api_call,
    fail_times=3,  # API will fail 3 times before succeeding.
    max_retries=5, # Allow up to 5 retries.
    base_delay=0.1,
    max_delay=2.0,
)

# Print the final status code of the API call after retries.
if result:
    logger.info(f"Final simulated API call status code: {result.status_code}")
else:
    logger.info("Simulated API call failed after all retries.")

def rate_limited(
    max_calls: int,
    window_secs: float,
):
    """
    A decorator that applies sliding window rate limiting to a function.

    Parameters
    ----------
    max_calls : int
        The maximum number of calls allowed within the specified window.
    window_secs : float
        The duration of the sliding window in seconds.

    Returns
    -------
    callable
        A decorator function that can be applied to other functions.
    """

    def decorator(func): # The actual decorator that takes the function to be wrapped.
        # Initialize a sliding window state for this specific rate-limited function.
        window = create_sliding_window(
            max_calls,
            window_secs,
        )

        @wraps(func) # Preserves metadata of the original function (`func`).
        def wrapper(*args, **kwargs):
            # Acquire a slot in the sliding window before executing the original function.
            # This call will block if the rate limit is exceeded.
            sliding_window_acquire(window)
            return func(*args, **kwargs) # Execute the original function.

        # Attach the window state to the wrapper for potential introspection or resetting.
        wrapper._rate_limit_window = window

        return wrapper # Return the wrapped function.

    return decorator # Return the decorator itself.

@rate_limited(max_calls=3, window_secs=1.0)
def fetch_ticker(symbol: str) -> dict:
    """
    Simulates an API endpoint call to fetch ticker information.
    This function is rate-limited by the `@rate_limited` decorator.
    """
    logger.info(f"Fetching ticker for {symbol}")
    return {
        "symbol": symbol,
        "price": 42000 + random.randint(-100, 100),
    }

# List of cryptocurrency symbols to fetch.
symbols = [
    "BTCUSDT",
    "ETHUSDT",
    "SOLUSDT",
    "BNBUSDT",
    "XRPUSDT",
]

results = []

# Iterate through symbols and call the rate-limited function.
# The decorator will automatically manage delays to adhere to the rate limit.
for symbol in symbols:
    result = fetch_ticker(symbol)
    results.append(result)
    # A short sleep to allow the rate limiter's window to slide, demonstrating its effect.
    time.sleep(0.1)

# Display the results in a DataFrame.
pd.DataFrame(results)

def create_rate_limit_tracker() -> dict:
    """
    Initializes a new monitoring statistics tracker for rate limit performance.

    Returns
    -------
    dict
        A dictionary representing the tracker's state, including:
        - 'total_requests': Cumulative count of all requests.
        - 'total_waits': Count of requests that experienced a delay.
        - 'total_wait_time': Sum of all wait durations.
        - 'rate_limit_hits': Count of times a 429 status code was encountered.
        - 'request_times': A list of tuples containing (timestamp, wait_time) for each request.
    """
    return {
        "total_requests": 0,
        "total_waits": 0,
        "total_wait_time": 0.0,
        "rate_limit_hits": 0,
        "request_times": [],
    }

def track_request(
    tracker: dict,
    wait_time: float,
    rate_limited: bool = False,
) -> None:
    """
    Records statistics for a single API request.

    Parameters
    ----------
    tracker : dict
        The mutable state of the rate limit tracker.
    wait_time : float
        The duration (in seconds) the request was delayed due to rate limiting.
    rate_limited : bool, optional
        True if the request explicitly encountered a rate limit (e.g., HTTP 429),
        False otherwise (default is False).
    """
    tracker["total_requests"] += 1 # Increment total request count.

    # Record the current monotonic timestamp and the associated wait time.
    tracker["request_times"].append(
        (time.monotonic(), wait_time)
    )

    if wait_time > 0: # If a wait occurred, update wait-related metrics.
        tracker["total_waits"] += 1
        tracker["total_wait_time"] += wait_time

    if rate_limited: # If the request was explicitly rate-limited (e.g., by 429).
        tracker["rate_limit_hits"] += 1

def summarize_tracker(tracker: dict) -> pd.DataFrame:
    """
    Generates a summary DataFrame of the collected rate limit tracking statistics.

    Parameters
    ----------
    tracker : dict
        The state of the rate limit tracker.

    Returns
    -------
    pd.DataFrame
        A DataFrame presenting key summary statistics, including total requests,
        requests with waits, percentage of waited requests, total wait time,
        and explicit rate limit hits.
    """
    n = tracker["total_requests"]
    waits = tracker["total_waits"]

    summary = {
        "total_requests": n,
        "requests_with_wait": waits,
        "pct_requests_waited": round((waits / n) * 100, 1) if n else 0, # Percentage of requests that experienced a wait.
        "total_wait_time_s": round(tracker["total_wait_time"], 4),
        "rate_limit_hits_429": tracker["rate_limit_hits"],
    }

    return pd.DataFrame([summary]).T.rename(columns={0: "value"})

# Defines a dictionary containing rate limit configurations for various cryptocurrency exchanges.
EXCHANGE_RATE_LIMITS = {
    "bybit": {
        "description": "Bybit Unified Trading API",
        "public_endpoints": {
            "get_kline": {"max_calls": 10, "window_secs": 1},   # 10 calls per second
            "get_orderbook": {"max_calls": 10, "window_secs": 1}, # 10 calls per second
        },
    },

    "binance": {
        "description": "Binance Spot/Futures API",
        "weight_limit_per_minute": 1200, # Overall weight limit for the API key per minute
        "endpoint_weights": {
            "klines": {"weight": 1},     # Low weight endpoint
            "depth": {"weight": 2},      # Medium weight endpoint
            "account": {"weight": 10},   # High weight endpoint
        },
    },

    "okx": {
        "description": "OKX REST API",
        "public_endpoints": {
            "candles": {"max_calls": 20, "window_secs": 2},  # 20 calls per 2 seconds
        },
    },
}

def get_rate_limit_profile(
    exchange: str,
    endpoint: str,
    tier: str = "public",
) -> dict:
    """
    Retrieves the rate limit configuration for a specified exchange endpoint and tier.

    Parameters
    ----------
    exchange : str
        The name of the exchange (e.g., 'bybit', 'binance').
    endpoint : str
        The specific API endpoint (e.g., 'get_kline', 'klines').
    tier : str, optional
        The access tier of the endpoint (e.g., 'public', 'private'), defaults to 'public'.

    Returns
    -------
    dict
        A dictionary containing the rate limit parameters for the endpoint,
        or an empty dictionary if the profile is not found.
    """
    profile = EXCHANGE_RATE_LIMITS.get(exchange.lower(), {}) # Retrieve exchange-specific profile.

    key = f"{tier}_endpoints" # Construct key for tier-specific endpoints.

    # Check for tier-specific endpoint configuration.
    if key in profile and endpoint in profile[key]:
        return profile[key][endpoint]

    # Check for weighted endpoint configuration if not found in tier-specific.
    elif (
        "endpoint_weights" in profile
        and endpoint in profile["endpoint_weights"]
    ):
        return profile["endpoint_weights"][endpoint]

    return {} # Return empty dict if no matching profile is found.

def build_rate_limiter_from_profile(
    exchange: str,
    endpoint: str,
    tier: str = "public",
):
    """
    Constructs a sliding window rate limiter instance based on predefined exchange profiles.

    Parameters
    ----------
    exchange : str
        The name of the exchange.
    endpoint : str
        The specific API endpoint.
    tier : str, optional
        The access tier of the endpoint (default is 'public').

    Returns
    -------
    dict or None
        A sliding window rate limiter dictionary if a profile is found, otherwise None.
    """
    profile = get_rate_limit_profile(
        exchange,
        endpoint,
        tier,
    )

    if not profile: # If no profile is found, no limiter can be built.
        return None

    # Create and return a sliding window limiter using parameters from the profile.
    return create_sliding_window(
        max_calls=profile["max_calls"],
        window_secs=profile["window_secs"],
    )

# Construct a sliding window rate limiter for Bybit's 'get_kline' public endpoint.
bybit_kline_limiter = build_rate_limiter_from_profile(
    "bybit",
    "get_kline",
    "public",
)

# Display the created rate limiter's configuration.
logger.info(f"Bybit KLine Limiter: {bybit_kline_limiter}")