Oxtapus 1.0
Oxtapus is a typed, Polars-native Python SDK for Iranian financial market data. Version 1.0 is a clean architecture and API: a small notebook surface sits over the same typed services, provider contracts, resilient HTTPX2 transport, and replayable data pipeline used by larger applications.
Oxtapus provides an independent Python interface to public market data published through TSETMC for the Tehran Stock Exchange (TSE) and Iran's capital market. It is not affiliated with or endorsed by TSETMC.
برای توسعهدهندگان فارسیزبان: Oxtapus کتابخانه پایتون دریافت و پردازش دادههای TSETMC، بورس اوراق بهادار تهران (بورس تهران) و بازار سرمایه ایران است.
Upstream websites can change without notice. Oxtapus reports source/schema metadata but does not promise source availability or grant redistribution rights. Review DATA_SOURCE_NOTICE.md before commercial use.
Install
python -m pip install oxtapus
Python 3.11–3.14 is supported. Optional integrations are installed explicitly:
python -m pip install 'oxtapus[arrow,pandas,duckdb,http2]'
Five-minute quickstart
import oxtapus as ox
prices = ox.daily_prices(
symbols=["فولاد", "خودرو"],
start="2025-01-01",
end="2026-01-01",
progress=True,
)
print(prices.select("symbol", "trading_date", "close_price"))
The simple functions return polars.DataFrame. Persian/Arabic Unicode variants are
normalized, identifiers are resolved explicitly, null values remain null, retries are scoped
to the failing request, and batch failures are not hidden.
Use a long-lived client when making several calls:
from oxtapus import Client, Settings
settings = Settings(concurrency=4, requests_per_second=2, progress=True)
with Client(settings) as client:
snapshot = client.market.market_watch(["equity", "etf"])
result = client.market.fetch_daily_prices(["فولاد", "خودرو"])
print(result.failures)
print(result.lineage.to_dict())
Native async works directly with Jupyter top-level await:
from oxtapus import AsyncClient
async with AsyncClient() as client:
prices = await client.market.daily_prices(["فولاد", "خودرو"])
Oxtapus never starts, nests, restarts, or patches an event loop.
Public surface
The root package intentionally exports Client, AsyncClient, Settings, FetchResult,
DataLayer, daily_prices, market_watch, instrument_search, and option_chain.
Provider implementation classes are internal.
Architecture
flowchart LR
API[Notebook API / Client / CLI] --> APP[Application services]
APP --> PORT[Provider and storage ports]
PORT --> TS[TSETMC provider]
TS --> HTTP[HTTPX2 transport]
APP --> B[Bronze raw evidence]
B --> S[Silver canonical]
S --> G[Gold curated]
S --> PQ[Parquet / Memory]
G --> PQ
PQ --> DB[Optional DuckDB]
See the documentation for configuration, endpoint evidence, replay, storage, schema contracts, testing, and provider development.
Development
uv sync --all-extras --group dev
uv run ruff format --check .
uv run ruff check .
uv run pyright
uv run pytest -m "not live"
uv run lint-imports
uv run mkdocs build --strict
uv build
Ordinary tests are offline. Live canaries are opt-in with pytest -m live.
Support the project
If Oxtapus makes your work easier, consider supporting its continued open-source development.
License
Oxtapus source code is MIT-licensed. Upstream data is governed separately by its source.
1 maintainer
Release files for oxtapus 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| oxtapus-1.0.0.tar.gz | 73.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| oxtapus-1.0.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 158.0 kB
Release files / oxtapus-1.0.0.tar.gz
| Download URL | oxtapus-1.0.0.tar.gz |
|---|---|
| Size | 73.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8cc9d1a28753e1089ffea1c5e9479f1a6dee54ecdd362d3afc9477238c949f48
|
|
BLAKE2b-256 checksum How to use checksums |
8aab81a0d0968afb6ac52be997a2279d0945b2da8da53f5722907e56a5296952
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.27 {"installer":{"name":"uv","version":"0.9.27","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / oxtapus-1.0.0-py3-none-any.whl
| Download URL | oxtapus-1.0.0-py3-none-any.whl |
|---|---|
| Size | 85.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
21a9aeaf30a84307b4e9ba05c6f2801f3c9e50fd70f5b7b57fc5328c21d9a751
|
|
BLAKE2b-256 checksum How to use checksums |
768a556b0e8eebd888848402ad5659fdd9b103589470d63e14feb31b5c3694c1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.27 {"installer":{"name":"uv","version":"0.9.27","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
