xpectral-utils 0.1.0__tar.gz

xpectral_utils-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Build package
+        run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/xpectral-utils/
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

xpectral_utils-0.1.0/.gitignore

@@ -0,0 +1,125 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/build/
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# poetry
+poetry.lock
+
+# PEP 582
+__pypackages__/
+
+# Ruff cache
+.ruff_cache/
+
+# Claude Code
+.claude/worktrees/
+
+# VS Code
+.vscode/
+
+# PyCharm
+.idea/
+
+# Local virtual environments
+venv/
+.env
+.env/
+env/
+.env.*
+!.env.example
+.venv/
+
+# macOS
+.DS_Store
+
+# Windows
+Thumbs.db
+
+# Project-specific data files
+*.parquet
+*.csv
+*.dbn
+*.dbn.zst
+logs/

xpectral_utils-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,25 @@
+repos:
+  - repo: local                         # Hooks defined in this project, not pulled from a remote repo
+    hooks:
+      # ---- Linter: finds issues and auto-fixes them (includes import sorting) ----
+      - id: ruff-check                   # Unique identifier for this hook
+        name: Lint with ruff             # Human-readable label shown in pre-commit's output
+        entry: uv run ruff check --fix --exit-non-zero-on-fix
+                                         # Command pre-commit runs:
+                                         #   uv run          → run inside the project's uv environment
+                                         #   ruff check      → the linter
+                                         #   --fix           → automatically fix what it can
+                                         #   --exit-non-zero-on-fix → fail the hook when a fix is applied,
+                                         #                            so the run also fails in CI, not just locally
+        language: system                 # Use the command as-is from the system/uv env (don't let pre-commit build its own)
+        types_or: [python, pyi, jupyter] # Run on .py files, .pyi stubs, AND .ipynb notebooks
+        require_serial: true             # Don't run this hook in parallel with others (avoids fix/format conflicts)
+        stages: [pre-commit]             # Run at commit time (i.e. when you `git commit`)
+
+      # ---- Formatter: reformats code style (runs after the linter) ----
+      - id: ruff-format                  # Unique identifier for this hook
+        name: Format with ruff           # Human-readable label shown in pre-commit's output
+        entry: uv run ruff format        # Command: run `ruff format` inside the uv environment
+        language: system                 # Use the command as-is from the system/uv env
+        types_or: [python, pyi, jupyter] # Format .py files, .pyi stubs, AND .ipynb notebooks
+        stages: [pre-commit]             # Run at commit time

xpectral_utils-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,10 @@
+# Contributing
+
+## Setup
+
+```bash
+uv sync --group dev
+uv run pre-commit install
+```
+
+`pre-commit install` registers the git hook that applies the repo's formatter locally before you commit.

xpectral_utils-0.1.0/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.

xpectral_utils-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,15 @@
+# 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/examples/caching.ipynb

@@ -0,0 +1,247 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "3ae94973",
+   "metadata": {},
+   "source": "# ON-DISK FUNCTION CACHING WITH `DISK_CACHE`\n\n`xpectral_utils.cache.disk_cache` memoizes a function's return values **on disk**,\nkeyed by its arguments. Unlike `functools.lru_cache`, the results persist across\nprocesses and interpreter restarts, which is ideal for slow, repeatable work such\nas API data pulls.\n\nEach decorated function gets its own cache directory (no shared global instance),\nbacked by [`diskcache`](https://grantjenks.com/docs/diskcache/), which handles the\narg-hashing, atomic writes, TTL, size limits, and LRU eviction for us. Values are\npickled, so the function must take picklable/hashable arguments and return\npicklable objects."
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "e3859601",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-07-05T07:59:03.978095Z",
+     "iopub.status.busy": "2026-07-05T07:59:03.977902Z",
+     "iopub.status.idle": "2026-07-05T07:59:03.993653Z",
+     "shell.execute_reply": "2026-07-05T07:59:03.992954Z"
+    }
+   },
+   "outputs": [],
+   "source": "%load_ext autoreload\n%autoreload 2\n\n# Standard library imports\nimport tempfile\nimport time\n\n# First-party imports\nfrom xpectral_utils.cache import disk_cache\n\n# Keep this example self-contained: cache into a throwaway temp directory\n# instead of the default ~/.cache/xpectral.\nCACHE_DIR = tempfile.mkdtemp(prefix=\"xpectral-cache-demo-\")\nCACHE_DIR"
+  },
+  {
+   "cell_type": "markdown",
+   "id": "00e28c86",
+   "metadata": {},
+   "source": [
+    "## A slow function\n",
+    "\n",
+    "We simulate expensive work with `time.sleep` and count how many times the body\n",
+    "actually runs, so we can prove the cache is doing its job."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "57933e19",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-07-05T07:59:03.995397Z",
+     "iopub.status.busy": "2026-07-05T07:59:03.995257Z",
+     "iopub.status.idle": "2026-07-05T07:59:04.003631Z",
+     "shell.execute_reply": "2026-07-05T07:59:04.003144Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "calls = {\"n\": 0}\n",
+    "\n",
+    "\n",
+    "@disk_cache(\"demo\", cache_dir=CACHE_DIR)\n",
+    "def slow_add(a, b):\n",
+    "    calls[\"n\"] += 1\n",
+    "    time.sleep(0.5)  # pretend this is a network / heavy compute call\n",
+    "    return a + b"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "93cf0bd5",
+   "metadata": {},
+   "source": [
+    "## Miss vs. hit\n",
+    "\n",
+    "The first call runs the body (a *miss*); the second call with identical arguments\n",
+    "is served from disk (a *hit*) and skips the work entirely."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "278ccd10",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-07-05T07:59:04.005358Z",
+     "iopub.status.busy": "2026-07-05T07:59:04.005250Z",
+     "iopub.status.idle": "2026-07-05T07:59:04.513898Z",
+     "shell.execute_reply": "2026-07-05T07:59:04.513257Z"
+    }
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "result: 5 -> 5\n",
+      "miss took 0.505s\n",
+      "hit  took 0.0002s\n",
+      "function body ran 1 time(s)\n"
+     ]
+    }
+   ],
+   "source": [
+    "t0 = time.perf_counter()\n",
+    "r1 = slow_add(2, 3)  # miss\n",
+    "t1 = time.perf_counter()\n",
+    "r2 = slow_add(2, 3)  # hit\n",
+    "t2 = time.perf_counter()\n",
+    "\n",
+    "print(f\"result: {r1} -> {r2}\")\n",
+    "print(f\"miss took {t1 - t0:.3f}s\")\n",
+    "print(f\"hit  took {t2 - t1:.4f}s\")\n",
+    "print(f\"function body ran {calls['n']} time(s)\")\n",
+    "\n",
+    "assert r1 == r2\n",
+    "assert calls[\"n\"] == 1  # the body ran only for the miss"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4d443128",
+   "metadata": {},
+   "source": [
+    "## Expiring stale entries (TTL)\n",
+    "\n",
+    "Pass `expire=<seconds>` to invalidate entries after a time-to-live. This matters\n",
+    "for data that goes stale (e.g. recent market bars). Here entries live for 1 second."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "9e86ad92",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-07-05T07:59:04.516530Z",
+     "iopub.status.busy": "2026-07-05T07:59:04.516301Z",
+     "iopub.status.idle": "2026-07-05T07:59:05.635004Z",
+     "shell.execute_reply": "2026-07-05T07:59:05.634097Z"
+    }
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "after two quick calls: body ran 1 time(s)\n"
+     ]
+    },
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "after TTL expiry:      body ran 2 time(s)\n"
+     ]
+    }
+   ],
+   "source": [
+    "ttl_calls = {\"n\": 0}\n",
+    "\n",
+    "\n",
+    "@disk_cache(\"demo_ttl\", expire=1, cache_dir=CACHE_DIR)\n",
+    "def slow_double(x):\n",
+    "    ttl_calls[\"n\"] += 1\n",
+    "    return x * 2\n",
+    "\n",
+    "\n",
+    "slow_double(21)  # miss -> body runs\n",
+    "slow_double(21)  # hit  -> cached\n",
+    "print(f\"after two quick calls: body ran {ttl_calls['n']} time(s)\")\n",
+    "\n",
+    "time.sleep(1.1)  # let the entry expire\n",
+    "slow_double(21)  # miss again -> body re-runs\n",
+    "print(f\"after TTL expiry:      body ran {ttl_calls['n']} time(s)\")\n",
+    "\n",
+    "assert ttl_calls[\"n\"] == 2"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "21afaea3",
+   "metadata": {},
+   "source": [
+    "## Inspecting and clearing\n",
+    "\n",
+    "The wrapped function exposes its backing store as `func.cache` (a\n",
+    "`diskcache.Cache`), so you can check how many entries it holds or clear them."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "id": "573e6c6e",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-07-05T07:59:05.637120Z",
+     "iopub.status.busy": "2026-07-05T07:59:05.636935Z",
+     "iopub.status.idle": "2026-07-05T07:59:06.148140Z",
+     "shell.execute_reply": "2026-07-05T07:59:06.147301Z"
+    }
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "entries before clear: 1\n",
+      "entries after clear:  0\n"
+     ]
+    },
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "body ran again after clear: True\n"
+     ]
+    }
+   ],
+   "source": [
+    "print(f\"entries before clear: {len(slow_add.cache)}\")\n",
+    "\n",
+    "slow_add.cache.clear()\n",
+    "print(f\"entries after clear:  {len(slow_add.cache)}\")\n",
+    "\n",
+    "# With the cache emptied, the next call is a miss again and the body re-runs.\n",
+    "before = calls[\"n\"]\n",
+    "slow_add(2, 3)\n",
+    "print(f\"body ran again after clear: {calls['n'] == before + 1}\")\n",
+    "\n",
+    "assert len(slow_add.cache) == 1\n",
+    "assert calls[\"n\"] == before + 1"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "xpectral-utils",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.11"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

xpectral_utils-0.1.0/examples/rate_limiter.ipynb

@@ -0,0 +1,87 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "a1b2c3d4",
+   "metadata": {},
+   "source": "# RATE LIMITER\n\nThrottle calls to an API with `RateLimiter`: at most `calls` acquisitions per `per_seconds` window."
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "b2c3d4e5",
+   "metadata": {},
+   "outputs": [],
+   "source": "%load_ext autoreload\n%autoreload 2"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "c3d4e5f6",
+   "metadata": {},
+   "outputs": [],
+   "source": "# Standard library imports\nimport time\n\n# First-party imports\nfrom xpectral_utils.rate_limiter import RateLimiter\n\nCALLS = 3\nPER_SECONDS = 1"
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d4e5f6a7",
+   "metadata": {},
+   "source": "## Throttle a loop\n\nCall `acquire()` before each request. The first `CALLS` go through immediately; the next one blocks until the oldest call leaves the window."
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "e5f6a7b8",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": "call 0 at 0.0s\ncall 1 at 0.0s\ncall 2 at 0.0s\ncall 3 at 1.0s\ncall 4 at 1.0s\ncall 5 at 1.0s\ncall 6 at 2.0s\ncall 7 at 2.0s\ncall 8 at 2.0s\n"
+    }
+   ],
+   "source": "limiter = RateLimiter(calls=CALLS, per_seconds=PER_SECONDS)\nstart = time.monotonic()\n\nfor i in range(9):\n    limiter.acquire()\n    print(f\"call {i} at {time.monotonic() - start:.1f}s\")"
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f6a7b8c9",
+   "metadata": {},
+   "source": "## Invalid arguments\n\n`calls` and `per_seconds` must be positive."
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "a7b8c9d0",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": "calls and per_seconds must be positive\n"
+    }
+   ],
+   "source": "try:\n    RateLimiter(calls=0, per_seconds=1)\nexcept ValueError as error:\n    print(error)"
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "xpectral-utils",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.13.7"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

xpectral_utils-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "xpectral-utils"
+version = "0.1.0"
+description = "Shared utility functions for xpectral projects"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { file = "LICENSE" }
+authors = [
+    { name = "BayQuant" }
+]
+keywords = ["utils", "quant"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent"
+]
+
+dependencies = []
+
+[project.optional-dependencies]
+cache = ["diskcache>=5.6.3"]  # xpectral_utils.cache
+s3 = ["boto3>=1.34"]  # xpectral_utils.s3
+
+[project.urls]
+Homepage = "https://github.com/bayquant/xpectral-utils"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "ruff>=0.6", # code formatter and linter
+    "pre-commit>=4.4.0", # git hook manager
+    "pytest>=8.0.0", # test runner
+    "ipykernel>=7.0.1", # jupyter notebook support
+    "boto3>=1.34", # tests for xpectral_utils.s3 (the s3 extra at runtime)
+    "diskcache>=5.6.3", # tests for xpectral_utils.cache (the cache extra at runtime)
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["xpectral_utils"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+ignore = [
+    "E501",  # Line too long: handled by formatter, not linter
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["xpectral_utils"]
+force-single-line = true