xpectral-utils 0.1.0__py3-none-any.whl

xpectral_utils/__init__.py

@@ -0,0 +1,20 @@
+"""Shared utility functions for xpectral projects."""
+
+# ----------------------------------------------------------------------------
+# Imports
+# ----------------------------------------------------------------------------
+
+# Local imports
+from .logger import setup_logging
+
+# ----------------------------------------------------------------------------
+# Globals and constants
+# ----------------------------------------------------------------------------
+
+# Importing ``logger`` (above) registers the package's NullHandler on import,
+# keeping the library silent until an app opts in. Because importing any
+# ``xpectral_utils.*`` submodule runs this ``__init__`` first, that registration
+# happens automatically for every module that logs -- no per-module wiring needed.
+# ``setup_logging`` is re-exported for convenience:
+# ``from xpectral_utils import setup_logging``.
+__all__ = ["setup_logging"]

xpectral_utils/cache.py

@@ -0,0 +1,107 @@
+"""On-disk function memoization built on diskcache (install ``xpectral-utils[cache]``)."""
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+
+# Standard library imports
+import os
+from collections.abc import Callable
+from pathlib import Path
+from typing import Literal
+
+# Third-party imports
+from diskcache import Cache
+
+# -----------------------------------------------------------------------------
+# Globals and constants
+# -----------------------------------------------------------------------------
+
+__all__ = ["EvictionPolicy", "disk_cache"]
+
+# The eviction policies diskcache accepts once ``size_limit`` is reached.
+EvictionPolicy = Literal[
+    "none",
+    "least-recently-stored",
+    "least-recently-used",
+    "least-frequently-used",
+]
+
+# Root under which every function gets its own cache subdirectory. Overridable
+# per call, or globally via the XPECTRAL_CACHE_DIR environment variable.
+_DEFAULT_CACHE_DIR = Path.home() / ".cache" / "xpectral"
+
+# Default per-function size cap before least-recently-used eviction kicks in.
+_SIZE_LIMIT = 2 * 2**30  # 2 GiB
+
+# -----------------------------------------------------------------------------
+# General API
+# -----------------------------------------------------------------------------
+
+
+def disk_cache(
+    name: str | None = None,
+    *,
+    expire: float | None = None,
+    cache_dir: str | os.PathLike | None = None,
+    size_limit: int = _SIZE_LIMIT,
+    eviction_policy: EvictionPolicy = "least-recently-used",
+    typed: bool = False,
+) -> Callable:
+    """Cache a function's return values on disk, keyed by its arguments.
+
+    Each decorated function gets its own :class:`diskcache.Cache` backed by its
+    own subdirectory -- there is no shared global cache instance. Values are
+    pickled, so the function must return picklable objects and take
+    picklable/hashable arguments.
+
+    Args:
+        name: Subdirectory name for this function's cache. Defaults to the
+            function's qualified name.
+        expire: Time-to-live in seconds. ``None`` caches indefinitely.
+        cache_dir: Root directory for the cache. Defaults to the
+            ``XPECTRAL_CACHE_DIR`` environment variable, else
+            ``~/.cache/xpectral``.
+        size_limit: Byte cap for this function's cache before entries are evicted
+            per ``eviction_policy``.
+        eviction_policy: How entries are chosen for eviction once ``size_limit``
+            is reached. One of ``"least-recently-stored"``,
+            ``"least-recently-used"``, ``"least-frequently-used"``, or ``"none"``
+            (no automatic eviction).
+        typed: When ``True``, arguments of different types are cached separately
+            (e.g. ``1`` and ``1.0``).
+
+    Returns:
+        A decorator that wraps the target function with on-disk memoization.
+        The wrapped function exposes its backing store as ``func.cache`` (a
+        :class:`diskcache.Cache`), so callers can ``func.cache.clear()`` or
+        check ``len(func.cache)``.
+    """
+
+    def decorator(func: Callable) -> Callable:
+        directory = _resolve_dir(cache_dir) / (name or func.__qualname__)
+        cache = Cache(
+            directory=str(directory),
+            size_limit=size_limit,
+            eviction_policy=eviction_policy,
+        )
+        memoized = cache.memoize(expire=expire, typed=typed)(func)
+        # Expose the backing Cache so callers can inspect or clear it, e.g.
+        # ``func.cache.clear()`` or ``len(func.cache)``.
+        memoized.cache = cache
+        return memoized
+
+    return decorator
+
+
+# -----------------------------------------------------------------------------
+# Private API
+# -----------------------------------------------------------------------------
+
+
+def _resolve_dir(cache_dir: str | os.PathLike | None) -> Path:
+    """Resolve the cache root: explicit arg, else env var, else default."""
+    if cache_dir is not None:
+        return Path(cache_dir)
+    env = os.getenv("XPECTRAL_CACHE_DIR")
+    return Path(env) if env else _DEFAULT_CACHE_DIR

xpectral_utils/dates.py

@@ -0,0 +1,61 @@
+"""Date and datetime normalization helpers."""
+
+# ----------------------------------------------------------------------------
+# Imports
+# ----------------------------------------------------------------------------
+
+# Standard library imports
+from datetime import UTC
+from datetime import date
+from datetime import datetime
+
+# ----------------------------------------------------------------------------
+# Globals and constants
+# ----------------------------------------------------------------------------
+
+__all__ = ["to_date", "to_datetime"]
+
+# ----------------------------------------------------------------------------
+# General API
+# ----------------------------------------------------------------------------
+
+
+def to_date(value: str | date) -> date:
+    """Normalize a calendar day to a ``date``.
+
+    Args:
+        value: ISO 8601 date string (``2024-03-01``) or a ``date``.
+
+    Returns:
+        The calendar day as a ``date``.
+
+    Raises:
+        TypeError: If ``value`` is a ``datetime``.
+        ValueError: If ``value`` is a malformed string.
+    """
+    # datetime is a subclass of date, so reject it before anything else.
+    if isinstance(value, datetime):
+        raise TypeError("expected a date, got a datetime")
+    if isinstance(value, str):
+        return date.fromisoformat(value)
+    return value
+
+
+def to_datetime(value: str | datetime) -> datetime:
+    """Normalize an instant to a timezone-aware ``datetime`` in UTC.
+
+    Args:
+        value: ISO 8601 string with an offset (``2024-03-01T14:30:00Z``) or an
+            aware ``datetime``.
+
+    Returns:
+        The instant as an aware ``datetime`` in UTC.
+
+    Raises:
+        ValueError: If ``value`` is naive or a malformed string.
+    """
+    if isinstance(value, str):
+        value = datetime.fromisoformat(value)
+    if value.tzinfo is None:
+        raise ValueError("datetime must be timezone-aware")
+    return value.astimezone(UTC)

xpectral_utils/logger.py

@@ -0,0 +1,84 @@
+"""Opt-in console logging for the xpectral_utils package logger."""
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+
+# Standard library imports
+import logging
+import sys
+from typing import Literal
+
+# -----------------------------------------------------------------------------
+# Globals and constants
+# -----------------------------------------------------------------------------
+
+__all__ = ["LogLevel", "setup_logging"]
+
+# Package-root logger. Modules log via ``logging.getLogger(__name__)``, which
+# descends from this as ``xpectral_utils.*``.
+_ROOT = "xpectral_utils"
+
+LogLevel = Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+
+# ANSI colors per level for the optional colored console handler.
+_COLORS = {
+    "DEBUG": "\033[94m",
+    "INFO": "\033[92m",
+    "WARNING": "\033[93m",
+    "ERROR": "\033[91m",
+    "CRITICAL": "\033[95m",
+}
+_RESET = "\033[0m"
+
+# Silent by default: a no-op handler on the package root stops Python's
+# last-resort handler from printing until the app opts in (via setup_logging or
+# its own logging config).
+logging.getLogger(_ROOT).addHandler(logging.NullHandler())
+
+# -----------------------------------------------------------------------------
+# General API
+# -----------------------------------------------------------------------------
+
+
+def setup_logging(
+    level: LogLevel = "INFO", *, color: bool = True, force_color: bool = False
+) -> None:
+    """Turn on console logging for xpectral_utils (opt-in, to stderr).
+
+    Apps that manage their own logging can ignore this and configure the
+    standard ``logging`` module directly. Color is applied only on a TTY, so
+    ANSI escapes don't leak into files or pipes; pass ``force_color=True`` to
+    color output regardless (e.g. in a notebook, which renders ANSI but is not
+    a TTY).
+    """
+    logger = logging.getLogger(_ROOT)
+    # Replace a handler a previous call added so repeats don't duplicate output.
+    logger.handlers = [h for h in logger.handlers if isinstance(h, logging.NullHandler)]
+    logger.setLevel(level)
+    logger.propagate = False
+
+    handler = logging.StreamHandler()
+    handler.setFormatter(
+        _ColorFormatter(color and (force_color or sys.stderr.isatty()))
+    )
+    logger.addHandler(handler)
+
+
+# -----------------------------------------------------------------------------
+# Private API
+# -----------------------------------------------------------------------------
+
+
+class _ColorFormatter(logging.Formatter):
+    """Render ``[LEVEL] name: message``, coloring the line when enabled."""
+
+    def __init__(self, color: bool):
+        super().__init__("[%(levelname)s] %(name)s: %(message)s")
+        self._color = color
+
+    def format(self, record: logging.LogRecord) -> str:
+        text = super().format(record)
+        if not self._color:
+            return text
+        return f"{_COLORS.get(record.levelname, '')}{text}{_RESET}"

xpectral_utils/rate_limiter.py

@@ -0,0 +1,63 @@
+"""Sliding-window rate limiter for throttling API calls."""
+
+# ----------------------------------------------------------------------------
+# Imports
+# ----------------------------------------------------------------------------
+
+# Standard library imports
+import logging
+import time
+from collections import deque
+
+# ----------------------------------------------------------------------------
+# Globals and constants
+# ----------------------------------------------------------------------------
+
+__all__ = ["RateLimiter"]
+
+logger = logging.getLogger(__name__)
+
+# ----------------------------------------------------------------------------
+# General API
+# ----------------------------------------------------------------------------
+
+
+class RateLimiter:
+    """Allow at most ``calls`` acquisitions per ``per_seconds`` window.
+
+    Call :meth:`acquire` before each request. It returns immediately while the
+    window has room, and otherwise blocks until the oldest call leaves the
+    window.
+
+    Args:
+        calls: Maximum acquisitions allowed in one window.
+        per_seconds: Window length in seconds.
+
+    Raises:
+        ValueError: If ``calls`` or ``per_seconds`` is not positive.
+    """
+
+    def __init__(self, calls: int, per_seconds: float):
+        if calls <= 0 or per_seconds <= 0:
+            raise ValueError("calls and per_seconds must be positive")
+        self.calls = calls
+        self.per_seconds = per_seconds
+        self._hits: deque[float] = deque()
+
+    def acquire(self) -> None:
+        """Block until a call is allowed, then record it."""
+        now = time.monotonic()
+        window_start = now - self.per_seconds
+
+        while self._hits and self._hits[0] <= window_start:
+            self._hits.popleft()
+
+        if len(self._hits) >= self.calls:
+            sleep_for = self.per_seconds - (now - self._hits[0])
+            if sleep_for > 0:
+                logger.info("sleeping for %.0f seconds", sleep_for)
+                time.sleep(sleep_for)
+            self.acquire()
+            return
+
+        self._hits.append(time.monotonic())

xpectral_utils/s3.py

@@ -0,0 +1,136 @@
+"""Read-only S3 downloader built on boto3 (install ``xpectral-utils[s3]``)."""
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+
+# Standard library imports
+import logging
+import os
+from pathlib import Path
+
+# Third-party imports
+import boto3
+from botocore.config import Config
+from botocore.exceptions import BotoCoreError
+from botocore.exceptions import ClientError
+
+# -----------------------------------------------------------------------------
+# Globals and constants
+# -----------------------------------------------------------------------------
+
+__all__ = ["S3Downloader"]
+
+logger = logging.getLogger(__name__)
+
+# -----------------------------------------------------------------------------
+# General API
+# -----------------------------------------------------------------------------
+
+
+class S3Downloader:
+    """Download objects from an S3-compatible bucket to local disk.
+
+    A thin read-only wrapper over a boto3 S3 client: it lists object keys under
+    a prefix and downloads them to a local root, preserving each key's path,
+    skipping files already on disk, and tolerating missing objects. It knows
+    nothing about the data it moves -- object-key layout, parsing, caching,
+    and whether to attempt the network at all belong to the caller.
+
+    Args:
+        bucket: Name of the S3 bucket to read from.
+        dest_dir: Default local directory downloaded objects are written under,
+            preserving each key's path. Overridable per :meth:`download` call.
+        endpoint_url: S3-compatible endpoint. ``None`` uses the AWS default.
+        access_key: Access key id. ``None`` falls back to boto3's own
+            credential resolution.
+        secret_key: Secret access key. ``None`` falls back to boto3's own
+            credential resolution.
+    """
+
+    def __init__(
+        self,
+        bucket: str,
+        dest_dir: str | os.PathLike,
+        endpoint_url: str | None = None,
+        access_key: str | None = None,
+        secret_key: str | None = None,
+    ):
+        # boto3 resolves credentials lazily -- building the session and client
+        # requires none; they are only needed on an actual API call.
+        session = boto3.Session(
+            aws_access_key_id=access_key,
+            aws_secret_access_key=secret_key,
+        )
+        self._client = session.client(
+            "s3",
+            endpoint_url=endpoint_url,
+            config=Config(signature_version="s3v4"),
+        )
+        self._bucket = bucket
+        self._dest_dir = Path(dest_dir)
+
+    def list_keys(self, prefix: str) -> list[str]:
+        """List every object key under ``prefix`` in the bucket."""
+        keys = []
+        paginator = self._client.get_paginator("list_objects_v2")
+        for page in paginator.paginate(Bucket=self._bucket, Prefix=prefix):
+            keys.extend(obj["Key"] for obj in page.get("Contents", []))
+        return keys
+
+    def download(
+        self,
+        keys: list[str],
+        dest_dir: str | os.PathLike | None = None,
+        overwrite: bool = False,
+    ) -> list[Path]:
+        """Download ``keys`` to ``dest_dir`` and return the local paths present.
+
+        Files already on disk are reused rather than re-downloaded, and keys
+        with no object (a 404/403) are logged and omitted from the result.
+        Whether to attempt the network at all is the caller's decision, not
+        this method's -- e.g. skip calling this entirely when working offline.
+
+        Args:
+            keys: Object keys to download.
+            dest_dir: Destination directory; the key path is preserved beneath
+                it. Defaults to the instance ``dest_dir``.
+            overwrite: When ``True``, re-download and replace files that
+                already exist locally instead of reusing them.
+
+        Returns:
+            Local paths, one per key that exists locally after the call.
+        """
+        root = Path(dest_dir) if dest_dir is not None else self._dest_dir
+        paths = []
+        for key in keys:
+            path = root / key
+            is_cached = path.exists()
+            if is_cached and not overwrite:
+                paths.append(path)
+                continue
+            path.parent.mkdir(parents=True, exist_ok=True)
+            try:
+                self._client.download_file(self._bucket, key, str(path))
+            except ClientError as error:
+                # S3-compatible buckets that withhold ``s3:ListBucket`` from
+                # download-only credentials hide object existence: a missing
+                # key comes back as 403/AccessDenied rather than 404/NoSuchKey.
+                # Treat both as "not there" so gaps (weekends, holidays,
+                # unpublished days) are skipped. Trade-off: genuinely bad
+                # credentials also land here, surfacing as an empty result
+                # instead of a raised auth error.
+                code = error.response.get("Error", {}).get("Code")
+                if code in {"404", "NoSuchKey", "403", "AccessDenied"}:
+                    logger.warning("no object for key, skipping: %s", key)
+                    continue
+                raise
+            except BotoCoreError:
+                # Unlike a missing object, this means the request never
+                # reached S3 at all (DNS/connection/timeout) -- surface it
+                # loudly rather than treating it as "no data available".
+                logger.error("connection failure downloading key: %s", key)
+                raise
+            logger.info("downloaded: %s", key)
+            paths.append(path)
+        return paths

xpectral_utils-0.1.0.dist-info/METADATA

@@ -0,0 +1,55 @@
+Metadata-Version: 2.5
+Name: xpectral-utils
+Version: 0.1.0
+Summary: Shared utility functions for xpectral projects
+Project-URL: Homepage, https://github.com/bayquant/xpectral-utils
+Author: BayQuant
+License: MIT License
+        
+        Copyright (c) 2025 BayQuant
+        
+        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.
+License-File: LICENSE
+Keywords: quant,utils
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Provides-Extra: cache
+Requires-Dist: diskcache>=5.6.3; extra == 'cache'
+Provides-Extra: s3
+Requires-Dist: boto3>=1.34; extra == 's3'
+Description-Content-Type: text/markdown
+
+# xpectral-utils
+
+![Spectral decomposition](https://raw.githubusercontent.com/bayquant/xpectral-utils/main/assets/xpectral_banner.gif)
+
+Shared utility functions used across xpectral projects.
+
+## Install
+
+```bash
+uv pip install xpectral-utils
+```
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).

xpectral_utils-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+xpectral_utils/__init__.py,sha256=INMGXKV3o2eGLy6oE1kOk2BSDskYCV3DnD8Em6WmF2Y,901
+xpectral_utils/cache.py,sha256=WMWfYwmVvA9b5kPBfQRmmmU-PiC-feuJ8KZRvWvSDGI,4134
+xpectral_utils/dates.py,sha256=yepN2TdXQmBUWd3XXdikGQZhldL0xBhXqhs16dkJx2U,1923
+xpectral_utils/logger.py,sha256=xNPSRk2VH9ua8nGRVJIwZpz7U-X07PgVs8qiZWfe7Ok,2999
+xpectral_utils/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+xpectral_utils/rate_limiter.py,sha256=6hfhyfX_KjK-ceGOH3MkkuohP8Ye8pKo5AElULRj-Xg,2081
+xpectral_utils/s3.py,sha256=xptoXM7NiROV-1SQ-iMUx6eQA3hX1D824nvxBqra9zc,5691
+xpectral_utils-0.1.0.dist-info/METADATA,sha256=aGUzMIp3E9f7BlH38AD17OHG0OGEPIfOZnrneLiDLIs,2174
+xpectral_utils-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+xpectral_utils-0.1.0.dist-info/licenses/LICENSE,sha256=oKFaOASRExmxKyg4h4tzD8yffNm1zGNFwubGUOVwq_E,1065
+xpectral_utils-0.1.0.dist-info/RECORD,,

xpectral_utils-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

xpectral_utils-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 BayQuant
+
+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.