Metadata-Version: 2.5
Name: oxtapus
Version: 1.0.0
Summary: A typed, Polars-native SDK for Iranian financial market data.
Project-URL: Documentation, https://yghaderi.github.io/oxtapus/
Project-URL: Issues, https://github.com/yghaderi/oxtapus/issues
Project-URL: Repository, https://github.com/yghaderi/oxtapus
Author-email: Yaghoub Ghadri <ghaderi.yaghoub@gmail.com>
License: MIT License
        
        Copyright (c) 2023 Yaghoub Ghaderi
        
        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.txt
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.11
Requires-Dist: httpx2<3,>=2.12
Requires-Dist: polars<2,>=1.37
Requires-Dist: pydantic-settings<3,>=2.10
Requires-Dist: pydantic<3,>=2.11
Provides-Extra: arrow
Requires-Dist: pyarrow<24,>=18; extra == 'arrow'
Provides-Extra: docs
Requires-Dist: mkdocs-material<10,>=9.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]<1,>=0.30; extra == 'docs'
Provides-Extra: duckdb
Requires-Dist: duckdb<2,>=1.3; extra == 'duckdb'
Provides-Extra: http2
Requires-Dist: httpx2[http2]<3,>=2.12; extra == 'http2'
Provides-Extra: pandas
Requires-Dist: pandas<4,>=2.2; extra == 'pandas'
Description-Content-Type: text/markdown

# Oxtapus 1.0

<p align="center">
  <a href="https://github.com/yghaderi/oxtapus/actions/workflows/ci.yml">
    <img src="https://github.com/yghaderi/oxtapus/actions/workflows/ci.yml/badge.svg?branch=master" alt="Test">
  </a>
  <a href="https://pypi.org/project/oxtapus/">
    <img src="https://img.shields.io/pypi/dm/oxtapus?color=%2334D058&amp;label=downloads" alt="PyPI downloads">
  </a>
  <a href="https://pypi.org/project/oxtapus/">
    <img src="https://img.shields.io/pypi/pyversions/oxtapus.svg?color=%2334D058" alt="Supported Python versions">
  </a>
  <a href="https://pypi.org/project/oxtapus/">
    <img src="https://img.shields.io/pypi/v/oxtapus?color=%2334D058&amp;label=pypi%20package" alt="Package version">
  </a>
</p>

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](https://tsetmc.com/) for the Tehran Stock Exchange (TSE) and Iran's capital
market. It is not affiliated with or endorsed by TSETMC.

برای توسعه‌دهندگان فارسی‌زبان: Oxtapus کتابخانه پایتون دریافت و پردازش داده‌های
[TSETMC](https://tsetmc.com/)، بورس اوراق بهادار تهران (بورس تهران) و بازار سرمایه ایران
است.

> 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](DATA_SOURCE_NOTICE.md) before commercial use.

## Install

```bash
python -m pip install oxtapus
```

Python 3.11–3.14 is supported. Optional integrations are installed explicitly:

```bash
python -m pip install 'oxtapus[arrow,pandas,duckdb,http2]'
```

## Five-minute quickstart

```python
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:

```python
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`:

```python
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

```mermaid
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](docs/index.md) for configuration, endpoint evidence, replay,
storage, schema contracts, testing, and provider development.

## Development

```bash
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.

[![Sponsor Oxtapus](https://img.shields.io/badge/%E2%99%A1-Sponsor%20Oxtapus-ff69b4?style=flat-square)](https://daramet.com/yghaderi)

## License

Oxtapus source code is MIT-licensed. Upstream data is governed separately by its source.
