Metadata-Version: 2.4
Name: fima
Version: 0.12.0
Summary: A Python package for retrieving and analyzing data from Iran's financial markets.
Author-email: Hemo Boghosian <HemoBoghosian@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/hemoboghosian/fima
Project-URL: Repository, https://github.com/hemoboghosian/fima
Project-URL: PyPI, https://pypi.org/project/fima/
Keywords: Iran financial markets,TSETMC,Iran Mercantile Exchange,Iran Fara Bourse,options
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: beautifulsoup4>=4.13.4
Requires-Dist: jdatetime>=3.8.2
Requires-Dist: lxml
Requires-Dist: mibian>=0.1.3
Requires-Dist: numpy>=1.26.3
Requires-Dist: pandas>=2.2.3
Requires-Dist: persian>=0.5.0
Requires-Dist: requests>=2.32.3
Requires-Dist: scipy>=1.13.1
Requires-Dist: truststore
Requires-Dist: urllib3
Provides-Extra: test
Requires-Dist: pytest>=8.3.5; extra == "test"
Requires-Dist: pytest-timeout; extra == "test"
Dynamic: license-file

# fima

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

## نصب

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

```shell
pip install fima
```

## شروع سریع

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

```python
from fima import get_ticker_historical_data

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

خروجی یک جدول پانداس با نمایهٔ `JalaliDate` است؛ تاریخ‌های شمسی به‌شکل رشته‌هایی مانند `1405-07-26` برمی‌گردند. قیمت پایانی رسمی در ستون `ClosingPrice` و حجم معاملات در ستون `TradeVolume` قرار دارد.

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

- **سهام و شاخص‌ها:** تاریخچهٔ قیمت، معاملات و سهامداران از ماژول `TSETMC`.
- **طلا، ارز و بازارهای جهانی:** فهرست نمادها، آخرین قیمت‌های موجود و تاریخچهٔ روزانه از ماژول `TGJU`.
- **صندوق‌های سرمایه‌گذاری:** فهرست صندوق‌ها، ارزش خالص دارایی‌ها و ترکیب دارایی‌ها از ماژول `Funds`؛ اطلاعات صندوق‌ها از سامانهٔ بورس نیز در همین ماژول است.
- **بورس کالا:** معاملات بازار فیزیکی، صادراتی، آتی، اختیار و گواهی سپرده از ماژول `IME`.
- **اختیار معامله:** زنجیرهٔ قراردادها، تاریخچه و محاسبات قیمت و حساسیت‌ها از ماژول `Options`.
- **فرابورس:** اوراق بدهی، شاخص‌ها، نرخ بدون ریسک و تأمین مالی از ماژول `IFB`.
- **نهادهای مالی:** فهرست نهادها از ماژول `TSEInstitutions`.
- **بانک مرکزی ایران:** نرخ‌های سیاستی، تورم و نرخ‌های ارز و ETS از ماژول `CBI`؛ [راهنما و محدودیت دسترسی منبع](docs/cbi.md).

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

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

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

```python
from fima import get_ticker_historical_data

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

قیمت خام حفظ می‌شود. تعدیل بر پایهٔ قیمت مرجع بورس و با مبنای آخرین تاریخ برگشتی است؛ این خروجی، سری بازده کل تأییدشده نیست. روش محاسبه و انتخاب تاریخ مبنا در [راهنمای تعدیل](docs/tsetmc-adjustment.md) آمده است.

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

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

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

در این مثال، تاریخ‌های ورودی میلادی‌اند. برای تاریخ شمسی و یافتن نام دقیق ابزارها، [راهنمای طلا و ارز](docs/tgju.md) را ببینید. واحد هر سری در مشخصات خروجی قرار دارد؛ ریال و تومان به هم تبدیل نمی‌شوند.

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

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

```python
from fima import get_all_funds

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

برای دریافت تاریخچهٔ ارزش خالص دارایی‌ها و ترکیب دارایی‌های یک صندوق، نام دقیق آن را از همین فهرست انتخاب کنید؛ نمونه‌ها در [راهنمای صندوق‌ها](docs/funds.md) آمده‌اند.

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

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

نمونهٔ زیر از نام کلیدهای نسخهٔ ۰٫۱۰٫۰ استفاده می‌کند. تفاوت‌های ناسازگار با نسخه‌های پیشین در [راهنمای مهاجرت](docs/data-migration.md#fima-0100-public-structured-keys) آمده‌اند.

```python
from fima import get_tsetmc_funds, get_tsetmc_fund_details

funds = get_tsetmc_funds("مختلط")
print(funds[["FundName", "RegistrationNumber"]].head())
details = get_tsetmc_fund_details(funds.iloc[0]["FundName"], fund_type="مختلط")
print(details["FundName"])
```

نام صندوق را از ستون `FundName` انتخاب کنید. جدول فهرست و دیکشنری جزئیات از نام‌های یکسان برای مفهوم‌های مشترک استفاده می‌کنند. فیلدهای نامشخص منبع فقط در بخش صریح `ProviderMetadata` حفظ می‌شوند. اطلاعات این منبع ممکن است با وب‌سایت صندوق از نظر تاریخ و پوشش متفاوت باشد؛ [راهنمای صندوق‌های بورس](docs/tsetmc-funds.md) جزئیات بیشتری دارد.

## قرارداد داده‌ها

خروجی‌های عمومی نسخهٔ ۰٫۹ از یک قرارداد مشترک پیروی می‌کنند:

- نام ستون‌های جدول‌ها و کلیدهای معمول دیکشنری‌ها انگلیسی و به‌شکل `PascalCase` است؛ نام توابع و پارامترهای پایتون به‌شکل `snake_case` باقی می‌ماند. مفهوم‌های مالی یکسان نیز تا جای ممکن نام یکسان دارند.
- تاریخ‌های میلادی در جای مناسب به‌صورت datetime پانداس و تاریخ‌های شمسی به‌شکل رشتهٔ لاتین `YYYY-MM-DD` برمی‌گردند.
- مقدارهای مالی قابل محاسبه عددی‌اند، اما شناسه‌هایی که کاربرد محاسباتی ندارند رشته باقی می‌مانند. مقدارهای ناموجود نیز با رفتار معمول داده‌های گمشده در پانداس نمایش داده می‌شوند.
- درصدهای داخل جدول‌ها بر حسب واحد درصد هستند؛ برای نمونه `2.5` یعنی `2.5%`.
- واحد پول و واحد فیزیکی اعلام‌شدهٔ ارائه‌دهنده بدون تبدیل حفظ می‌شود، مگر آنکه مستندات یک تابع صریحاً خلاف آن را بگویند.

تعریف کامل نام‌ها، نوع داده‌ها و استثناها در [قرارداد داده‌های عمومی](docs/data-conventions.md) آمده است.

## ارتقا به نسخهٔ ۰٫۹٫۰

در نسخهٔ ۰٫۹٫۰ نام برخی ستون‌ها، نوع بعضی داده‌ها، مقیاس درصدهای جدولی و تعدادی محاسبه برای یکپارچگی و اصلاح معنی مالی تغییر کرده‌اند. اگر از نسخه‌ای قدیمی‌تر ارتقا می‌دهید، [راهنمای کامل مهاجرت](docs/data-migration.md) را پیش از به‌روزرسانی کد خود ببینید. نام توابع و پارامترهای عمومی تغییر نکرده است.

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

- [قرارداد داده‌های عمومی](docs/data-conventions.md) و [راهنمای مهاجرت نسخهٔ ۰٫۹٫۰](docs/data-migration.md)
- [راهنمای سهام و شاخص‌ها](docs/tsetmc.md) و [روش تعدیل قیمت](docs/tsetmc-adjustment.md)
- [راهنمای طلا، ارز و بازارهای جهانی](docs/tgju.md)
- [راهنمای بانک مرکزی و تاریخچهٔ نرخ‌های سیاستی](docs/cbi.md)
- [راهنمای صندوق‌ها و تاریخچهٔ دارایی‌ها](docs/funds.md)
- [راهنمای صندوق‌های بورس](docs/tsetmc-funds.md)
- [مثال‌های اختیار معامله، فرابورس، بورس کالا و نهادهای مالی](docs/markets.md)
- [فهرست توابع عمومی](docs/api.md)

## نکات مهم

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

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

برای گزارش مشکل، [یک مسئله در گیت‌هاب باز کنید](https://github.com/hemoboghosian/fima/issues). نام تابع، نمونهٔ کوتاه کد و متن خطا را بنویسید. برای توسعه و اجرای آزمون‌ها، [راهنمای مشارکت](docs/development.md) را ببینید.

این پروژه با [مجوز ام‌آی‌تی](LICENSE) منتشر می‌شود. نسخهٔ قابل نصب در [صفحهٔ بسته در پای‌پی‌آی](https://pypi.org/project/fima/) و راه تماس در [اطلاعات پروژه](pyproject.toml) قرار دارد.
