Oxtapus 1.1
Oxtapus یه بسته توسعه نرمافزاری (SDK) پایتون تایپشده و مبتنی بر Polars برای دادههای بازار مالی ایرانه. شاخهٔ 1.x با یه معماری و رابط برنامهنویسی (API) کاملاً تازه ساخته شده؛ یعنی هم برای کارهای سریع داخل نوتبوک جمعوجوره و هم زیرِ همین ظاهر ساده، سرویسهای تایپشده، قراردادهای مشخص برای فراهمکنندهها، انتقال مقاوم HTTPX2 و خط لوله داده قابلبازپخش داره تا توی پروژههای بزرگتر هم بشه روش حساب کرد.
با Oxtapus میتونی به دادههای عمومی منتشرشده در TSETMC برای بورس اوراق بهادار تهران (بورس تهران) و بازار سرمایه ایران دسترسی داشته باشی. این پروژه مستقل و غیررسمیه و هیچ وابستگی یا تأییدی از طرف TSETMC نداره.
تاریخچهٔ قیمت دلار آزاد، دلار نیما، یورو، سکه امامی و نیمسکه هم از TGJU در دسترسه.
به زبان ساده، اگه دنبال یه کتابخونه پایتون برای دریافت و پردازش دادههای TSETMC و بورس تهران هستی، Oxtapus دقیقاً برای همین کار ساخته شده.
حواست باشه سایتهای منبع ممکنه هر لحظه و بدون اطلاع قبلی تغییر کنن. Oxtapus اطلاعات منبع و نسخه طرحواره رو ثبت میکنه، ولی در دسترسبودن همیشگی منبع یا اجازه بازنشر دادهها رو تضمین نمیکنه. اگه استفاده تجاری داری، حتماً اول اطلاعیه منابع داده رو بخون.
نصب
برای نصب معمولی این دستور رو اجرا کن:
python -m pip install oxtapus
نسخههای 3.11 تا 3.14 پایتون پشتیبانی میشن. اگه یکپارچهسازیهای اختیاری رو هم میخوای، باید موقع نصب مشخصشون کنی:
python -m pip install 'oxtapus[arrow,pandas,duckdb,http2]'
import oxtapus as ox
prices = ox.daily_prices(
symbols=["فولاد", "خودرو"],
start="۱۴۰۳/۱۰/۱۲",
end="۱۴۰۴/۱۰/۱۱",
progress=True,
)
print(prices.select("symbol", "trading_date", "close_price"))
برای گرفتن تاریخچهٔ دلار یا سکه هم فقط اسم دارایی رو بده:
usd = ox.asset_history("دلار", start="۱۴۰۲/۱۰/۱۱")
nima = ox.asset_history("دلار نیما")
eur = ox.asset_history("یورو")
emami = ox.asset_history("سکه امامی")
half = ox.asset_history("نیمسکه")
start و end اختیاریان. تاریخ شمسی رو میتونی با رقم فارسی، عربی یا انگلیسی و در قالبهای
YYYY-MM-DD، YYYY/MM/DD، YYYY.MM.DD یا YYYYMMDD بدی. Oxtapus با jdatetime اون رو به
میلادی تبدیل میکنه؛ تاریخ میلادی ISO هم پذیرفته میشه. ورودی نامعتبر، همراه با همون مقدار
واردشده و قالبهای مجاز خطا میده.
تابعهای ساده یه polars.DataFrame برمیگردونن. شکلهای مختلف حروف فارسی و عربی بهصورت
خودکار یکدست میشن، شناسهها شفاف پیدا میشن، مقدارهای خالی واقعاً خالی میمونن، تلاش دوباره
فقط برای همون درخواست ناموفق انجام میشه و خطاهای پردازش گروهی هم قایم نمیشن.
اگه قراره چند بار درخواست بفرستی، بهتره یه کلاینت Client بسازی و همون رو نگه داری:
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"])
quote = client.market.quote("فولاد")
order_book = client.market.market_depth("فولاد")
activity = client.market.investor_activity("فولاد")
identity = client.instruments.identity("فولاد")
board = client.governance.board_members("فولاد")
result = client.market.fetch_daily_prices(["فولاد", "خودرو"])
print(result.failures)
print(result.lineage.to_dict())
نسخه ناهمگام (async) واقعی هم مستقیم با await سطح بالای Jupyter کار میکنه:
from oxtapus import AsyncClient
async with AsyncClient() as client:
prices = await client.market.daily_prices(["فولاد", "خودرو"])
Oxtapus خودش حلقه رویداد (event loop) رو راه نمیاندازه، تودرتو نمیکنه، از نو اجرا
نمیکنه و دستکاریش هم نمیکنه.
رابط عمومی
از پکیج اصلی عمداً فقط کلاینتها، تنظیمات، نتیجهی پیشرفته و میانبرهای دیتاستهای عمومی مثل
daily_prices، market_watch، quote، market_depth، investor_activity،
instrument_search، instrument_info، instrument_identity، board_members و
option_chain و asset_history در دسترس مستقیم هستن. کلاسهای داخلی فراهمکنندهها بخشی از
رابط عمومی نیستن.
معماری
flowchart LR
API[Notebook API / Client / CLI] --> APP[Application services]
APP --> PORT[Provider and storage ports]
PORT --> TS[TSETMC provider]
PORT --> TG[TGJU provider]
TS --> HTTP[HTTPX2 transport]
TG --> HTTP
APP --> B[Bronze raw evidence]
B --> S[Silver canonical]
S --> G[Gold curated]
S --> PQ[Parquet / Memory]
G --> PQ
PQ --> DB[Optional DuckDB]
برای تنظیمات، شواهد نقطههای پایانی، بازپخش داده، ذخیرهسازی، قراردادهای طرحواره، تست و ساخت فراهمکننده جدید، یه سر به مستندات کامل بزن.
توسعه پروژه
برای آمادهکردن محیط توسعه و اجرای همه بررسیها از این دستورها استفاده کن:
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 sphinx-build -W --keep-going -b html docs docs/_build/html
uv build
تستهای معمولی کاملاً آفلاین اجرا میشن. تستهای زنده اختیاریان و با pytest -m live
اجرا میشن.
حمایت از پروژه
اگه Oxtapus کارت رو راحتتر کرده و دوست داری توسعه متنبازش ادامه پیدا کنه، میتونی از پروژه حمایت کنی.
مجوز
کد منبع Oxtapus با مجوز MIT منتشر شده. قوانین استفاده از دادههای دریافتی جداست و به منبع اصلی هر داده بستگی داره.
1 maintainer
Release files for oxtapus 1.1.1
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.1.1.tar.gz | 109.2 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| oxtapus-1.1.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 224.4 kB
Release files / oxtapus-1.1.1.tar.gz
| Download URL | oxtapus-1.1.1.tar.gz |
|---|---|
| Size | 109.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2dc0cfa4a9e96050be6a88af11405251a08ad5f188866153200ae084cb35bec0
|
|
BLAKE2b-256 checksum How to use checksums |
327ca85e88c78f3284011b65982a0e05e915b3a880813e261e0d81f968cbaafb
|
| 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.1.1-py3-none-any.whl
| Download URL | oxtapus-1.1.1-py3-none-any.whl |
|---|---|
| Size | 115.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f7da9ff4ec6f2e3d95653293c3e83004be2e7d9a02cb0c8d5c4d4404b4d20072
|
|
BLAKE2b-256 checksum How to use checksums |
beb332d43402425f520fb3bb0f62116c3f60ec6d632d0413eebf40cd1c5eeb71
|
| 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}
|
