Metadata-Version: 2.4
Name: fima
Version: 0.9.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

**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](https://github.com/hemoboghosian/fima/blob/v0.9.0/docs/data-migration.md)
and [release notes](https://github.com/hemoboghosian/fima/releases/tag/v0.9.0)
before upgrading. Analytical scalar rates/volatility still use decimal units.

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

## نصب

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

```shell
pip install fima
```

## شروع سریع

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

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

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

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

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

```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`، نام گروه و نام کامل صندوق کافی است:

```python
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` انتخاب کنید. اطلاعات این منبع ممکن است با وب‌سایت صندوق از نظر تاریخ و پوشش متفاوت باشد؛ [راهنمای صندوق‌های بورس](docs/tsetmc-funds.md) جزئیات بیشتری دارد.

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

- [راهنمای سهام و شاخص‌ها](docs/tsetmc.md) و [روش تعدیل قیمت](docs/tsetmc-adjustment.md)
- [راهنمای طلا، ارز و بازارهای جهانی](docs/tgju.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) قرار دارد.
