fima

0.9.0 — breaking public data contracts: DataFrame columns now use PascalCase; Gregorian dates use pandas datetime and Jalali dates use YYYY-MM-DD strings. Numeric/identifier dtypes and percentage-point scales are normalized. Corrections include TSETMC individual/institutional mappings and index high/low fields; Options/IME transaction counts and trade volumes; Funds per-unit NAV versus total assets; Mibian risk-free-rate scaling, volatility and pricing limits; complete IME timestamps; and TGJU display-date interpretation. Read the exhaustive migration guide and release notes before upgrading. Analytical scalar rates/volatility still use decimal units.

با این کتابخانهٔ پایتون می‌توانید داده‌های بازارهای مالی ایران را برای تحلیل و پژوهش دریافت کنید؛ از تاریخچهٔ سهام و اطلاعات صندوق‌ها تا قیمت طلا و ارز، اختیار معامله و معاملات بورس کالا.

نصب

به پایتون نسخهٔ ۳٫۱۰ یا جدیدتر نیاز دارید:

pip install fima

شروع سریع

برای دریافت تاریخچهٔ قیمت سهام، نام نماد را وارد کنید:

from fima import get_ticker_historical_data

history = get_ticker_historical_data(ticker="فملی")
print(history[["ClosingPrice", "TradeVolume"]].head())

خروجی یک جدول پانداس با نمایهٔ تاریخ شمسی است. ستون ClosingPrice قیمت پایانی رسمی و ستون TradeVolume حجم معاملات را نشان می‌دهد.

چه داده‌هایی در دسترس است؟

• سهام و شاخص‌ها: تاریخچهٔ قیمت، معاملات و سهامداران از ماژول TSETMC.
• طلا، ارز و بازارهای جهانی: فهرست نمادها، آخرین قیمت‌های موجود و تاریخچهٔ روزانه از ماژول TGJU.
• صندوق‌های سرمایه‌گذاری: فهرست صندوق‌ها، ارزش خالص دارایی‌ها و ترکیب دارایی‌ها از ماژول Funds؛ اطلاعات صندوق‌ها از سامانهٔ بورس نیز در همین ماژول است.
• بورس کالا: معاملات بازار فیزیکی، صادراتی، آتی، اختیار و گواهی سپرده از ماژول IME.
• اختیار معامله: زنجیرهٔ قراردادها، تاریخچه و محاسبات قیمت و حساسیت‌ها از ماژول Options.
• فرابورس: اوراق بدهی، شاخص‌ها، نرخ بدون ریسک و تأمین مالی از ماژول IFB.
• نهادهای مالی: فهرست نهادها از ماژول TSEInstitutions.

مثال‌های کاربردی

قیمت تعدیل‌شدهٔ سهام

برای افزودن قیمت‌های تعدیل‌شده، گزینهٔ تعدیل را فعال کنید:

from fima import get_ticker_historical_data

history = get_ticker_historical_data(ticker="فملی", adjust_prices=True)
print(history[["ClosingPrice", "AdjustedClosingPrice"]].head())

قیمت خام حفظ می‌شود. تعدیل بر پایهٔ قیمت مرجع بورس و با مبنای آخرین تاریخ برگشتی است؛ این خروجی، سری بازده کل تأییدشده نیست. روش محاسبه و انتخاب تاریخ مبنا در راهنمای تعدیل آمده است.

تاریخچهٔ قیمت دلار

برای دریافت داده‌های طلا و ارز، نام ابزار و گروه آن را مشخص کنید:

from fima import get_tgju_history

usd = get_tgju_history("دلار", "ارز", start_date="2026-10-01", end_date="2026-10-15")
print(usd[["GregorianDate", "ClosingPrice"]].tail())

در این مثال، تاریخ‌های ورودی میلادی‌اند. برای تاریخ شمسی و یافتن نام دقیق ابزارها، راهنمای طلا و ارز را ببینید. واحد هر سری در مشخصات خروجی قرار دارد؛ ریال و تومان به هم تبدیل نمی‌شوند.

اطلاعات صندوق‌های سرمایه‌گذاری

برای دیدن فهرست صندوق‌ها و اطلاعات فعلی آن‌ها از این تابع استفاده کنید:

from fima import get_all_funds

funds = get_all_funds()
print(funds[["FundName", "FundTypeName", "TotalNAV"]].head())

برای دریافت تاریخچهٔ ارزش خالص دارایی‌ها و ترکیب دارایی‌های یک صندوق، نام دقیق آن را از همین فهرست انتخاب کنید؛ نمونه‌ها در راهنمای صندوق‌ها آمده‌اند.

فهرست و جزئیات صندوق‌ها از سامانهٔ بورس

برای انتخاب صندوق از منبع TSETMC، نام گروه و نام کامل صندوق کافی است:

from fima import get_tsetmc_funds, get_tsetmc_fund_details

funds = get_tsetmc_funds("مختلط")
print(funds[["mfName", "regNo"]].head())
details = get_tsetmc_fund_details("آرمان سپهر آتی", fund_type="مختلط")
print(details["mfName"])

نام صندوق را از ستون mfName انتخاب کنید. اطلاعات این منبع ممکن است با وب‌سایت صندوق از نظر تاریخ و پوشش متفاوت باشد؛ راهنمای صندوق‌های بورس جزئیات بیشتری دارد.

مستندات بیشتر

• راهنمای سهام و شاخص‌ها و روش تعدیل قیمت
• راهنمای طلا، ارز و بازارهای جهانی
• راهنمای صندوق‌ها و تاریخچهٔ دارایی‌ها
• راهنمای صندوق‌های بورس
• مثال‌های اختیار معامله، فرابورس، بورس کالا و نهادهای مالی
• فهرست توابع عمومی

نکات مهم

• دریافت داده به اینترنت و در دسترس بودن منبع وابسته است؛ دادهٔ موجود ممکن است قدیمی یا ناقص باشد.
• این کتابخانه مستقل از ارائه‌دهندگان داده است. شرایط استفادهٔ هر منبع را رعایت کنید.

مشارکت و گزارش مشکل

برای گزارش مشکل، یک مسئله در گیت‌هاب باز کنید. نام تابع، نمونهٔ کوتاه کد و متن خطا را بنویسید. برای توسعه و اجرای آزمون‌ها، راهنمای مشارکت را ببینید.

این پروژه با مجوز ام‌آی‌تی منتشر می‌شود. نسخهٔ قابل نصب در صفحهٔ بسته در پای‌پی‌آی و راه تماس در اطلاعات پروژه قرار دارد.