## دستیار
```markdown
# FipiranFunds
[](https://pypi.org/project/fipiranfunds/)
[](https://pypi.org/project/fipiranfunds/)
[](https://pypi.org/project/fipiranfunds/)
[](https://github.com/Kimiaslhd/fipiranfunds/issues)
[](https://github.com/Kimiaslhd/fipiranfunds/stargazers)
کتابخانه‌ی پایتون برای دریافت و ذخیره‌سازی داده‌های معاملات و بازدهی صندوق‌ها از API فپیران (Fipiran) و خروجی گرفتن به CSV. این README شامل توضیحات به فارسی برای کاربران ایرانی و نمونه‌های کدنویسی کاربردی به انگلیسی است.
A Python library for fetching and exporting Iranian fund data from the Fipiran API to CSV. This README includes Persian explanations for Iranian users and practical English code examples.
## پیش‌نیازها / Requirements
- **نسخه‌ی پایتون**: 3.6+ (توصیه‌شده: 3.8+ برای بهترین عملکرد و سازگاری).
- **الزامات اصلی** (به طور خودکار با نصب پکیج نصب می‌شوند):
- requests >= 2.25.0
- pandas >= 1.2.0
- jdatetime >= 3.6.0
- beautifulsoup4 (برای تجزیه HTML اگر نیاز باشد).
- **کتابخانه‌های اختیاری** (برای امکانات بیشتر):
- pyodbc — برای اتصال و نوشتن در SQL Server (نیاز به نصب ODBC driver از مایکروسافت روی ویندوز، مانند “Microsoft ODBC Driver 17 for SQL Server”).
- pytse-client — در صورتی که بخواهید از داده‌های TSETMC استفاده کنید.
- tqdm — برای نوار پیشرفت (progress bar).
- python-dateutil — کمک در پردازش تاریخ‌ها.
**نصب سریع (پیشنهادی برای تمام امکانات)**:
```
pip install fipiranfunds requests pandas jdatetime beautifulsoup4 pyodbc pytse-client tqdm python-dateutil
```
## نصب / Installation
برای استفاده ساده (فقط الزامات اصلی):
```
pip install fipiranfunds
```
برای توسعه یا نصب آخرین نسخه از گیت‌هاب:
```
pip install git+https://github.com/Kimiaslhd/fipiranfunds.git
```
## شروع سریع / Quick Start
این کتابخانه اجازه می‌دهد داده‌های صندوق‌های سرمایه‌گذاری ایرانی را از API فپیران دریافت کنید و به CSV خروجی بگیرید. مثال تعاملی زیر از شما تاریخ شمسی می‌پرسد و فایل CSV را روی Desktop ذخیره می‌کند.
```python
from fipiranfunds import export_fund_data
export_fund_data()
# برنامه از شما تاریخ شروع و پایان به فرمت شمسی YYYY/MM/DD را می‌پرسد.
# سپس فایل CSV خروجی روی Desktop ذخیره می‌شود (مثال: fipiranfunds_export_20240321_123456.csv).
```
## خلاصه‌ی قابلیت‌ها / Usage Overview
این پکیج API عمومی ساده‌ای در سطح بالا ارائه می‌دهد برای دسترسی آسان بدون نیاز به واردات زیرماژول‌ها. قابلیت‌های کلیدی:
- `export_fund_data()`: اجرای تعاملی برای دریافت داده‌ها در بازه تاریخی و ذخیره به CSV (روی Desktop).
- `FundDataFetcher`: کلاس برای استفاده برنامه‌نویسی (برگرداندن pandas.DataFrame).
- `jalali_to_gregorian(date_str)`: تبدیل تاریخ شمسی به میلادی (ISO format).
- توابع داخلی مانند `mapper.*` برای نگاشت فیلدهای API به نام‌های کاربرپسند در CSV.
برای جزئیات بیشتر، به بخش توابع و مثال‌ها مراجعه کنید.
## توابع و مثال‌ها / Functions & Examples
### export_fund_data()
تابع راحت و تعاملی: از کاربر تاریخ‌های شروع و پایان شمسی می‌پرسد، آن‌ها را به میلادی تبدیل کرده، داده‌ها را از API فراخوانی می‌کند و CSV را ذخیره می‌کند.
**رفتار کلیدی**:
- اعتبارسنجی تاریخ ورودی (Jalali format: YYYY/MM/DD).
- تلاش‌های مجدد (retries) در صورت بروز خطاهای موقتی شبکه.
- چاپ وضعیت پیشرفت و مسیر نهایی فایل CSV.
**مثال**:
```python
from fipiranfunds import export_fund_data
export_fund_data()
# نمونه ورودی:
# Enter start date (Jalali YYYY/MM/DD): 1403/01/01
# Enter end date (Jalali YYYY/MM/DD): 1403/01/05
# Data saved to: C:\Users\<YourUsername>\Desktop\fipiranfunds_export_20240321_140501.csv
```
### FundDataFetcher
کلاس برای کنترل برنامه‌نویسی پیشرفته، مانند استفاده در اسکریپت‌های ETL. خروجی: pandas.DataFrame.
**مثال**:
```python
from fipiranfunds import FundDataFetcher, jalali_to_gregorian
fetcher = FundDataFetcher()
start = jalali_to_gregorian("1403/01/01") # خروجی: "2024-03-21"
end = jalali_to_gregorian("1403/01/31")
df = fetcher.fetch_fund_data(start, end)
print(df.head())
df.to_csv("funds_local.csv", index=False)
```
### jalali_to_gregorian(date_str)
تبدیل رشته تاریخ شمسی "YYYY/MM/DD" به رشته میلادی ISO "YYYY-MM-DD".
**مثال**:
```python
from fipiranfunds import jalali_to_gregorian
print(jalali_to_gregorian("1403/01/01")) # خروجی: "2024-03-21"
```
## ساختار CSV خروجی / Output CSV Structure
**الگوی نام فایل**: fipiranfunds_export_<YYYYMMDD_HHMMSS>.csv
**ستون‌های نمونه** (ممکن است بسته به نسخه یا داده‌های API تغییر کنند):
- regNo
- fundTitle
- isCompleted
- calcDate
- licenseTitle
- fundSize
- fundType
- initiationDate
- dailyEfficiency
- weeklyEfficiency
- monthlyEfficiency
- quarterlyEfficiency
- sixMonthEfficiency
- annualEfficiency
- statisticalNav
- efficiency
- cancelNav
- issueNav
- dividendPeriodEfficiency
- netAsset
- unitBalance
- accountsNo
- articlesOfAssociationEfficiency
## اتصال به SQL Server (اختیاری) / SQL Server Connection (Optional)
اگر می‌خواهید داده‌ها را مستقیماً به دیتابیس SQL Server بنویسید (pyodbc را نصب کنید).
**مثال ساده**:
```python
import pyodbc
import pandas as pd
conn_str = "DRIVER={ODBC Driver 17 for SQL Server};SERVER=192.168.1.131;DATABASE=LotusibBI;UID=user;PWD=pass"
conn = pyodbc.connect(conn_str)
cursor = conn.cursor()
# فرض کنید df داده‌های شما است
# روش سریع: ابتدا به CSV ذخیره کنید، سپس از BULK INSERT استفاده کنید
# یا از pandas.to_sql (با نصب SQLAlchemy) برای نوشتن مستقیم:
# df.to_sql("funds_table", conn, if_exists="append", index=False)
```
## نکات خطاها و راهنمایی‌ها / Troubleshooting & Tips
- **خطای تاریخ**: ورودی را بررسی کنید؛ فرمت باید YYYY/MM/DD باشد.
- **خطای API (مانند 500 یا IP-block)**: چند دقیقه صبر کنید و دوباره امتحان کنید — سایت ممکن است درخواست‌ها را موقتاً محدود کند.
- **تداخل نسخه‌ها**: اگر jdatetime با دیگر پکیج‌ها تداخل دارد، نسخه سازگار را پین کنید (مثلاً `pip install jdatetime==3.6.0`).
- **نکته عمومی**: برای تست، از محیط مجازی (virtualenv) استفاده کنید تا وابستگی‌ها ایزوله شوند.
## CLI (در صورت وجود) / CLI (If Available)
اگر پکیج CLI را پشتیبانی کند:
```
python -m fipiranfunds.cli
# یا اگر entry point تعریف شده باشد:
fipiranfunds
```
## توسعه و مشارکت / Contributing
خوشحال می‌شویم از کمک شما!
- مسائل (issues) یا درخواست‌های pull را در [گیت‌هاب](https://github.com/Kimiaslhd/fipiranfunds) باز کنید.
- قبل از ارسال PR: تست‌های محلی را اجرا کنید، کد را با black فرمت کنید، و سبک PEP 8 را رعایت کنید.
- برای شروع: repo را fork کنید، تغییرات را اعمال کنید، و PR ارسال کنید.
## تغییرات / Changelog
- **0.1.14**: بهبود README، رفع مشکلات رندرینگ PyPI، و صادرات API در سطح بالا.
- **0.1.13**: نسخه اولیه با پشتیبانی پایه API و CSV.
برای تغییرات کامل، به [گیت‌هاب commits](https://github.com/Kimiaslhd/fipiranfunds/commits) مراجعه کنید.
## مجوز / License
MIT License. جزئیات در فایل LICENSE.
## نویسنده و تماس / Author & Contact
- **نام**: Kimia Salehi Delarestaghy
- **ایمیل**: kimiaslhd@gmail.com
- **لینکدین**: [https://www.linkedin.com/in/kimia-salehy-delarestaghy/](https://www.linkedin.com/in/kimia-salehy-delarestaghy/)
- **گیت‌هاب**: [https://github.com/Kimiaslhd/fipiranfunds](https://github.com/Kimiaslhd/fipiranfunds)
- **PyPI**: [https://pypi.org/project/fipiranfunds/](https://pypi.org/project/fipiranfunds/)
اگر سؤالی دارید، issue باز کنید یا ایمیل بزنید!
```
---
*Generated by: Grok 4*
Raw data
{
"_id": null,
"home_page": null,
"name": "fipiranfunds",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "fipiran, funds, iran, api, finance, csv, pandas, jalali",
"author": null,
"author_email": "Kimia Salehi Delarestaghy <kimiaslhd@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/5a/f3/263994dab036e3b329d24536b7cfcbf22374d44492bc6f6554356d61ab15/fipiranfunds-0.1.15.tar.gz",
"platform": null,
"description": "## \u062f\u0633\u062a\u06cc\u0627\u0631\r\n\r\n```markdown\r\n# FipiranFunds\r\n\r\n[](https://pypi.org/project/fipiranfunds/)\r\n[](https://pypi.org/project/fipiranfunds/)\r\n[](https://pypi.org/project/fipiranfunds/)\r\n[](https://github.com/Kimiaslhd/fipiranfunds/issues)\r\n[](https://github.com/Kimiaslhd/fipiranfunds/stargazers)\r\n\r\n\u06a9\u062a\u0627\u0628\u062e\u0627\u0646\u0647\u200c\u06cc \u067e\u0627\u06cc\u062a\u0648\u0646 \u0628\u0631\u0627\u06cc \u062f\u0631\u06cc\u0627\u0641\u062a \u0648 \u0630\u062e\u06cc\u0631\u0647\u200c\u0633\u0627\u0632\u06cc \u062f\u0627\u062f\u0647\u200c\u0647\u0627\u06cc \u0645\u0639\u0627\u0645\u0644\u0627\u062a \u0648 \u0628\u0627\u0632\u062f\u0647\u06cc \u0635\u0646\u062f\u0648\u0642\u200c\u0647\u0627 \u0627\u0632 API \u0641\u067e\u06cc\u0631\u0627\u0646 (Fipiran) \u0648 \u062e\u0631\u0648\u062c\u06cc \u06af\u0631\u0641\u062a\u0646 \u0628\u0647 CSV. \u0627\u06cc\u0646 README \u0634\u0627\u0645\u0644 \u062a\u0648\u0636\u06cc\u062d\u0627\u062a \u0628\u0647 \u0641\u0627\u0631\u0633\u06cc \u0628\u0631\u0627\u06cc \u06a9\u0627\u0631\u0628\u0631\u0627\u0646 \u0627\u06cc\u0631\u0627\u0646\u06cc \u0648 \u0646\u0645\u0648\u0646\u0647\u200c\u0647\u0627\u06cc \u06a9\u062f\u0646\u0648\u06cc\u0633\u06cc \u06a9\u0627\u0631\u0628\u0631\u062f\u06cc \u0628\u0647 \u0627\u0646\u06af\u0644\u06cc\u0633\u06cc \u0627\u0633\u062a.\r\n\r\nA Python library for fetching and exporting Iranian fund data from the Fipiran API to CSV. This README includes Persian explanations for Iranian users and practical English code examples.\r\n\r\n## \u067e\u06cc\u0634\u200c\u0646\u06cc\u0627\u0632\u0647\u0627 / Requirements\r\n\r\n- **\u0646\u0633\u062e\u0647\u200c\u06cc \u067e\u0627\u06cc\u062a\u0648\u0646**: 3.6+ (\u062a\u0648\u0635\u06cc\u0647\u200c\u0634\u062f\u0647: 3.8+ \u0628\u0631\u0627\u06cc \u0628\u0647\u062a\u0631\u06cc\u0646 \u0639\u0645\u0644\u06a9\u0631\u062f \u0648 \u0633\u0627\u0632\u06af\u0627\u0631\u06cc).\r\n- **\u0627\u0644\u0632\u0627\u0645\u0627\u062a \u0627\u0635\u0644\u06cc** (\u0628\u0647 \u0637\u0648\u0631 \u062e\u0648\u062f\u06a9\u0627\u0631 \u0628\u0627 \u0646\u0635\u0628 \u067e\u06a9\u06cc\u062c \u0646\u0635\u0628 \u0645\u06cc\u200c\u0634\u0648\u0646\u062f):\r\n - requests >= 2.25.0\r\n - pandas >= 1.2.0\r\n - jdatetime >= 3.6.0\r\n - beautifulsoup4 (\u0628\u0631\u0627\u06cc \u062a\u062c\u0632\u06cc\u0647 HTML \u0627\u06af\u0631 \u0646\u06cc\u0627\u0632 \u0628\u0627\u0634\u062f).\r\n\r\n- **\u06a9\u062a\u0627\u0628\u062e\u0627\u0646\u0647\u200c\u0647\u0627\u06cc \u0627\u062e\u062a\u06cc\u0627\u0631\u06cc** (\u0628\u0631\u0627\u06cc \u0627\u0645\u06a9\u0627\u0646\u0627\u062a \u0628\u06cc\u0634\u062a\u0631):\r\n - pyodbc \u2014 \u0628\u0631\u0627\u06cc \u0627\u062a\u0635\u0627\u0644 \u0648 \u0646\u0648\u0634\u062a\u0646 \u062f\u0631 SQL Server (\u0646\u06cc\u0627\u0632 \u0628\u0647 \u0646\u0635\u0628 ODBC driver \u0627\u0632 \u0645\u0627\u06cc\u06a9\u0631\u0648\u0633\u0627\u0641\u062a \u0631\u0648\u06cc \u0648\u06cc\u0646\u062f\u0648\u0632\u060c \u0645\u0627\u0646\u0646\u062f \u201cMicrosoft ODBC Driver 17 for SQL Server\u201d).\r\n - pytse-client \u2014 \u062f\u0631 \u0635\u0648\u0631\u062a\u06cc \u06a9\u0647 \u0628\u062e\u0648\u0627\u0647\u06cc\u062f \u0627\u0632 \u062f\u0627\u062f\u0647\u200c\u0647\u0627\u06cc TSETMC \u0627\u0633\u062a\u0641\u0627\u062f\u0647 \u06a9\u0646\u06cc\u062f.\r\n - tqdm \u2014 \u0628\u0631\u0627\u06cc \u0646\u0648\u0627\u0631 \u067e\u06cc\u0634\u0631\u0641\u062a (progress bar).\r\n - python-dateutil \u2014 \u06a9\u0645\u06a9 \u062f\u0631 \u067e\u0631\u062f\u0627\u0632\u0634 \u062a\u0627\u0631\u06cc\u062e\u200c\u0647\u0627.\r\n\r\n**\u0646\u0635\u0628 \u0633\u0631\u06cc\u0639 (\u067e\u06cc\u0634\u0646\u0647\u0627\u062f\u06cc \u0628\u0631\u0627\u06cc \u062a\u0645\u0627\u0645 \u0627\u0645\u06a9\u0627\u0646\u0627\u062a)**:\r\n```\r\npip install fipiranfunds requests pandas jdatetime beautifulsoup4 pyodbc pytse-client tqdm python-dateutil\r\n```\r\n\r\n## \u0646\u0635\u0628 / Installation\r\n\r\n\u0628\u0631\u0627\u06cc \u0627\u0633\u062a\u0641\u0627\u062f\u0647 \u0633\u0627\u062f\u0647 (\u0641\u0642\u0637 \u0627\u0644\u0632\u0627\u0645\u0627\u062a \u0627\u0635\u0644\u06cc):\r\n```\r\npip install fipiranfunds\r\n```\r\n\r\n\u0628\u0631\u0627\u06cc \u062a\u0648\u0633\u0639\u0647 \u06cc\u0627 \u0646\u0635\u0628 \u0622\u062e\u0631\u06cc\u0646 \u0646\u0633\u062e\u0647 \u0627\u0632 \u06af\u06cc\u062a\u200c\u0647\u0627\u0628:\r\n```\r\npip install git+https://github.com/Kimiaslhd/fipiranfunds.git\r\n```\r\n\r\n## \u0634\u0631\u0648\u0639 \u0633\u0631\u06cc\u0639 / Quick Start\r\n\r\n\u0627\u06cc\u0646 \u06a9\u062a\u0627\u0628\u062e\u0627\u0646\u0647 \u0627\u062c\u0627\u0632\u0647 \u0645\u06cc\u200c\u062f\u0647\u062f \u062f\u0627\u062f\u0647\u200c\u0647\u0627\u06cc \u0635\u0646\u062f\u0648\u0642\u200c\u0647\u0627\u06cc \u0633\u0631\u0645\u0627\u06cc\u0647\u200c\u06af\u0630\u0627\u0631\u06cc \u0627\u06cc\u0631\u0627\u0646\u06cc \u0631\u0627 \u0627\u0632 API \u0641\u067e\u06cc\u0631\u0627\u0646 \u062f\u0631\u06cc\u0627\u0641\u062a \u06a9\u0646\u06cc\u062f \u0648 \u0628\u0647 CSV \u062e\u0631\u0648\u062c\u06cc \u0628\u06af\u06cc\u0631\u06cc\u062f. \u0645\u062b\u0627\u0644 \u062a\u0639\u0627\u0645\u0644\u06cc \u0632\u06cc\u0631 \u0627\u0632 \u0634\u0645\u0627 \u062a\u0627\u0631\u06cc\u062e \u0634\u0645\u0633\u06cc \u0645\u06cc\u200c\u067e\u0631\u0633\u062f \u0648 \u0641\u0627\u06cc\u0644 CSV \u0631\u0627 \u0631\u0648\u06cc Desktop \u0630\u062e\u06cc\u0631\u0647 \u0645\u06cc\u200c\u06a9\u0646\u062f.\r\n\r\n```python\r\nfrom fipiranfunds import export_fund_data\r\n\r\nexport_fund_data()\r\n# \u0628\u0631\u0646\u0627\u0645\u0647 \u0627\u0632 \u0634\u0645\u0627 \u062a\u0627\u0631\u06cc\u062e \u0634\u0631\u0648\u0639 \u0648 \u067e\u0627\u06cc\u0627\u0646 \u0628\u0647 \u0641\u0631\u0645\u062a \u0634\u0645\u0633\u06cc YYYY/MM/DD \u0631\u0627 \u0645\u06cc\u200c\u067e\u0631\u0633\u062f.\r\n# \u0633\u067e\u0633 \u0641\u0627\u06cc\u0644 CSV \u062e\u0631\u0648\u062c\u06cc \u0631\u0648\u06cc Desktop \u0630\u062e\u06cc\u0631\u0647 \u0645\u06cc\u200c\u0634\u0648\u062f (\u0645\u062b\u0627\u0644: fipiranfunds_export_20240321_123456.csv).\r\n```\r\n\r\n## \u062e\u0644\u0627\u0635\u0647\u200c\u06cc \u0642\u0627\u0628\u0644\u06cc\u062a\u200c\u0647\u0627 / Usage Overview\r\n\r\n\u0627\u06cc\u0646 \u067e\u06a9\u06cc\u062c API \u0639\u0645\u0648\u0645\u06cc \u0633\u0627\u062f\u0647\u200c\u0627\u06cc \u062f\u0631 \u0633\u0637\u062d \u0628\u0627\u0644\u0627 \u0627\u0631\u0627\u0626\u0647 \u0645\u06cc\u200c\u062f\u0647\u062f \u0628\u0631\u0627\u06cc \u062f\u0633\u062a\u0631\u0633\u06cc \u0622\u0633\u0627\u0646 \u0628\u062f\u0648\u0646 \u0646\u06cc\u0627\u0632 \u0628\u0647 \u0648\u0627\u0631\u062f\u0627\u062a \u0632\u06cc\u0631\u0645\u0627\u0698\u0648\u0644\u200c\u0647\u0627. \u0642\u0627\u0628\u0644\u06cc\u062a\u200c\u0647\u0627\u06cc \u06a9\u0644\u06cc\u062f\u06cc:\r\n\r\n- `export_fund_data()`: \u0627\u062c\u0631\u0627\u06cc \u062a\u0639\u0627\u0645\u0644\u06cc \u0628\u0631\u0627\u06cc \u062f\u0631\u06cc\u0627\u0641\u062a \u062f\u0627\u062f\u0647\u200c\u0647\u0627 \u062f\u0631 \u0628\u0627\u0632\u0647 \u062a\u0627\u0631\u06cc\u062e\u06cc \u0648 \u0630\u062e\u06cc\u0631\u0647 \u0628\u0647 CSV (\u0631\u0648\u06cc Desktop).\r\n- `FundDataFetcher`: \u06a9\u0644\u0627\u0633 \u0628\u0631\u0627\u06cc \u0627\u0633\u062a\u0641\u0627\u062f\u0647 \u0628\u0631\u0646\u0627\u0645\u0647\u200c\u0646\u0648\u06cc\u0633\u06cc (\u0628\u0631\u06af\u0631\u062f\u0627\u0646\u062f\u0646 pandas.DataFrame).\r\n- `jalali_to_gregorian(date_str)`: \u062a\u0628\u062f\u06cc\u0644 \u062a\u0627\u0631\u06cc\u062e \u0634\u0645\u0633\u06cc \u0628\u0647 \u0645\u06cc\u0644\u0627\u062f\u06cc (ISO format).\r\n- \u062a\u0648\u0627\u0628\u0639 \u062f\u0627\u062e\u0644\u06cc \u0645\u0627\u0646\u0646\u062f `mapper.*` \u0628\u0631\u0627\u06cc \u0646\u06af\u0627\u0634\u062a \u0641\u06cc\u0644\u062f\u0647\u0627\u06cc API \u0628\u0647 \u0646\u0627\u0645\u200c\u0647\u0627\u06cc \u06a9\u0627\u0631\u0628\u0631\u067e\u0633\u0646\u062f \u062f\u0631 CSV.\r\n\r\n\u0628\u0631\u0627\u06cc \u062c\u0632\u0626\u06cc\u0627\u062a \u0628\u06cc\u0634\u062a\u0631\u060c \u0628\u0647 \u0628\u062e\u0634 \u062a\u0648\u0627\u0628\u0639 \u0648 \u0645\u062b\u0627\u0644\u200c\u0647\u0627 \u0645\u0631\u0627\u062c\u0639\u0647 \u06a9\u0646\u06cc\u062f.\r\n\r\n## \u062a\u0648\u0627\u0628\u0639 \u0648 \u0645\u062b\u0627\u0644\u200c\u0647\u0627 / Functions & Examples\r\n\r\n### export_fund_data()\r\n\r\n\u062a\u0627\u0628\u0639 \u0631\u0627\u062d\u062a \u0648 \u062a\u0639\u0627\u0645\u0644\u06cc: \u0627\u0632 \u06a9\u0627\u0631\u0628\u0631 \u062a\u0627\u0631\u06cc\u062e\u200c\u0647\u0627\u06cc \u0634\u0631\u0648\u0639 \u0648 \u067e\u0627\u06cc\u0627\u0646 \u0634\u0645\u0633\u06cc \u0645\u06cc\u200c\u067e\u0631\u0633\u062f\u060c \u0622\u0646\u200c\u0647\u0627 \u0631\u0627 \u0628\u0647 \u0645\u06cc\u0644\u0627\u062f\u06cc \u062a\u0628\u062f\u06cc\u0644 \u06a9\u0631\u062f\u0647\u060c \u062f\u0627\u062f\u0647\u200c\u0647\u0627 \u0631\u0627 \u0627\u0632 API \u0641\u0631\u0627\u062e\u0648\u0627\u0646\u06cc \u0645\u06cc\u200c\u06a9\u0646\u062f \u0648 CSV \u0631\u0627 \u0630\u062e\u06cc\u0631\u0647 \u0645\u06cc\u200c\u06a9\u0646\u062f.\r\n\r\n**\u0631\u0641\u062a\u0627\u0631 \u06a9\u0644\u06cc\u062f\u06cc**:\r\n- \u0627\u0639\u062a\u0628\u0627\u0631\u0633\u0646\u062c\u06cc \u062a\u0627\u0631\u06cc\u062e \u0648\u0631\u0648\u062f\u06cc (Jalali format: YYYY/MM/DD).\r\n- \u062a\u0644\u0627\u0634\u200c\u0647\u0627\u06cc \u0645\u062c\u062f\u062f (retries) \u062f\u0631 \u0635\u0648\u0631\u062a \u0628\u0631\u0648\u0632 \u062e\u0637\u0627\u0647\u0627\u06cc \u0645\u0648\u0642\u062a\u06cc \u0634\u0628\u06a9\u0647.\r\n- \u0686\u0627\u067e \u0648\u0636\u0639\u06cc\u062a \u067e\u06cc\u0634\u0631\u0641\u062a \u0648 \u0645\u0633\u06cc\u0631 \u0646\u0647\u0627\u06cc\u06cc \u0641\u0627\u06cc\u0644 CSV.\r\n\r\n**\u0645\u062b\u0627\u0644**:\r\n```python\r\nfrom fipiranfunds import export_fund_data\r\n\r\nexport_fund_data()\r\n\r\n# \u0646\u0645\u0648\u0646\u0647 \u0648\u0631\u0648\u062f\u06cc:\r\n# Enter start date (Jalali YYYY/MM/DD): 1403/01/01\r\n# Enter end date (Jalali YYYY/MM/DD): 1403/01/05\r\n# Data saved to: C:\\Users\\<YourUsername>\\Desktop\\fipiranfunds_export_20240321_140501.csv\r\n```\r\n\r\n### FundDataFetcher\r\n\r\n\u06a9\u0644\u0627\u0633 \u0628\u0631\u0627\u06cc \u06a9\u0646\u062a\u0631\u0644 \u0628\u0631\u0646\u0627\u0645\u0647\u200c\u0646\u0648\u06cc\u0633\u06cc \u067e\u06cc\u0634\u0631\u0641\u062a\u0647\u060c \u0645\u0627\u0646\u0646\u062f \u0627\u0633\u062a\u0641\u0627\u062f\u0647 \u062f\u0631 \u0627\u0633\u06a9\u0631\u06cc\u067e\u062a\u200c\u0647\u0627\u06cc ETL. \u062e\u0631\u0648\u062c\u06cc: pandas.DataFrame.\r\n\r\n**\u0645\u062b\u0627\u0644**:\r\n```python\r\nfrom fipiranfunds import FundDataFetcher, jalali_to_gregorian\r\n\r\nfetcher = FundDataFetcher()\r\nstart = jalali_to_gregorian(\"1403/01/01\") # \u062e\u0631\u0648\u062c\u06cc: \"2024-03-21\"\r\nend = jalali_to_gregorian(\"1403/01/31\")\r\ndf = fetcher.fetch_fund_data(start, end)\r\n\r\nprint(df.head())\r\ndf.to_csv(\"funds_local.csv\", index=False)\r\n```\r\n\r\n### jalali_to_gregorian(date_str)\r\n\r\n\u062a\u0628\u062f\u06cc\u0644 \u0631\u0634\u062a\u0647 \u062a\u0627\u0631\u06cc\u062e \u0634\u0645\u0633\u06cc \"YYYY/MM/DD\" \u0628\u0647 \u0631\u0634\u062a\u0647 \u0645\u06cc\u0644\u0627\u062f\u06cc ISO \"YYYY-MM-DD\".\r\n\r\n**\u0645\u062b\u0627\u0644**:\r\n```python\r\nfrom fipiranfunds import jalali_to_gregorian\r\n\r\nprint(jalali_to_gregorian(\"1403/01/01\")) # \u062e\u0631\u0648\u062c\u06cc: \"2024-03-21\"\r\n```\r\n\r\n## \u0633\u0627\u062e\u062a\u0627\u0631 CSV \u062e\u0631\u0648\u062c\u06cc / Output CSV Structure\r\n\r\n**\u0627\u0644\u06af\u0648\u06cc \u0646\u0627\u0645 \u0641\u0627\u06cc\u0644**: fipiranfunds_export_<YYYYMMDD_HHMMSS>.csv\r\n\r\n**\u0633\u062a\u0648\u0646\u200c\u0647\u0627\u06cc \u0646\u0645\u0648\u0646\u0647** (\u0645\u0645\u06a9\u0646 \u0627\u0633\u062a \u0628\u0633\u062a\u0647 \u0628\u0647 \u0646\u0633\u062e\u0647 \u06cc\u0627 \u062f\u0627\u062f\u0647\u200c\u0647\u0627\u06cc API \u062a\u063a\u06cc\u06cc\u0631 \u06a9\u0646\u0646\u062f):\r\n- regNo\r\n- fundTitle\r\n- isCompleted\r\n- calcDate\r\n- licenseTitle\r\n- fundSize\r\n- fundType\r\n- initiationDate\r\n- dailyEfficiency\r\n- weeklyEfficiency\r\n- monthlyEfficiency\r\n- quarterlyEfficiency\r\n- sixMonthEfficiency\r\n- annualEfficiency\r\n- statisticalNav\r\n- efficiency\r\n- cancelNav\r\n- issueNav\r\n- dividendPeriodEfficiency\r\n- netAsset\r\n- unitBalance\r\n- accountsNo\r\n- articlesOfAssociationEfficiency\r\n\r\n## \u0627\u062a\u0635\u0627\u0644 \u0628\u0647 SQL Server (\u0627\u062e\u062a\u06cc\u0627\u0631\u06cc) / SQL Server Connection (Optional)\r\n\r\n\u0627\u06af\u0631 \u0645\u06cc\u200c\u062e\u0648\u0627\u0647\u06cc\u062f \u062f\u0627\u062f\u0647\u200c\u0647\u0627 \u0631\u0627 \u0645\u0633\u062a\u0642\u06cc\u0645\u0627\u064b \u0628\u0647 \u062f\u06cc\u062a\u0627\u0628\u06cc\u0633 SQL Server \u0628\u0646\u0648\u06cc\u0633\u06cc\u062f (pyodbc \u0631\u0627 \u0646\u0635\u0628 \u06a9\u0646\u06cc\u062f).\r\n\r\n**\u0645\u062b\u0627\u0644 \u0633\u0627\u062f\u0647**:\r\n```python\r\nimport pyodbc\r\nimport pandas as pd\r\n\r\nconn_str = \"DRIVER={ODBC Driver 17 for SQL Server};SERVER=192.168.1.131;DATABASE=LotusibBI;UID=user;PWD=pass\"\r\nconn = pyodbc.connect(conn_str)\r\ncursor = conn.cursor()\r\n\r\n# \u0641\u0631\u0636 \u06a9\u0646\u06cc\u062f df \u062f\u0627\u062f\u0647\u200c\u0647\u0627\u06cc \u0634\u0645\u0627 \u0627\u0633\u062a\r\n# \u0631\u0648\u0634 \u0633\u0631\u06cc\u0639: \u0627\u0628\u062a\u062f\u0627 \u0628\u0647 CSV \u0630\u062e\u06cc\u0631\u0647 \u06a9\u0646\u06cc\u062f\u060c \u0633\u067e\u0633 \u0627\u0632 BULK INSERT \u0627\u0633\u062a\u0641\u0627\u062f\u0647 \u06a9\u0646\u06cc\u062f\r\n# \u06cc\u0627 \u0627\u0632 pandas.to_sql (\u0628\u0627 \u0646\u0635\u0628 SQLAlchemy) \u0628\u0631\u0627\u06cc \u0646\u0648\u0634\u062a\u0646 \u0645\u0633\u062a\u0642\u06cc\u0645:\r\n# df.to_sql(\"funds_table\", conn, if_exists=\"append\", index=False)\r\n```\r\n\r\n## \u0646\u06a9\u0627\u062a \u062e\u0637\u0627\u0647\u0627 \u0648 \u0631\u0627\u0647\u0646\u0645\u0627\u06cc\u06cc\u200c\u0647\u0627 / Troubleshooting & Tips\r\n\r\n- **\u062e\u0637\u0627\u06cc \u062a\u0627\u0631\u06cc\u062e**: \u0648\u0631\u0648\u062f\u06cc \u0631\u0627 \u0628\u0631\u0631\u0633\u06cc \u06a9\u0646\u06cc\u062f\u061b \u0641\u0631\u0645\u062a \u0628\u0627\u06cc\u062f YYYY/MM/DD \u0628\u0627\u0634\u062f.\r\n- **\u062e\u0637\u0627\u06cc API (\u0645\u0627\u0646\u0646\u062f 500 \u06cc\u0627 IP-block)**: \u0686\u0646\u062f \u062f\u0642\u06cc\u0642\u0647 \u0635\u0628\u0631 \u06a9\u0646\u06cc\u062f \u0648 \u062f\u0648\u0628\u0627\u0631\u0647 \u0627\u0645\u062a\u062d\u0627\u0646 \u06a9\u0646\u06cc\u062f \u2014 \u0633\u0627\u06cc\u062a \u0645\u0645\u06a9\u0646 \u0627\u0633\u062a \u062f\u0631\u062e\u0648\u0627\u0633\u062a\u200c\u0647\u0627 \u0631\u0627 \u0645\u0648\u0642\u062a\u0627\u064b \u0645\u062d\u062f\u0648\u062f \u06a9\u0646\u062f.\r\n- **\u062a\u062f\u0627\u062e\u0644 \u0646\u0633\u062e\u0647\u200c\u0647\u0627**: \u0627\u06af\u0631 jdatetime \u0628\u0627 \u062f\u06cc\u06af\u0631 \u067e\u06a9\u06cc\u062c\u200c\u0647\u0627 \u062a\u062f\u0627\u062e\u0644 \u062f\u0627\u0631\u062f\u060c \u0646\u0633\u062e\u0647 \u0633\u0627\u0632\u06af\u0627\u0631 \u0631\u0627 \u067e\u06cc\u0646 \u06a9\u0646\u06cc\u062f (\u0645\u062b\u0644\u0627\u064b `pip install jdatetime==3.6.0`).\r\n- **\u0646\u06a9\u062a\u0647 \u0639\u0645\u0648\u0645\u06cc**: \u0628\u0631\u0627\u06cc \u062a\u0633\u062a\u060c \u0627\u0632 \u0645\u062d\u06cc\u0637 \u0645\u062c\u0627\u0632\u06cc (virtualenv) \u0627\u0633\u062a\u0641\u0627\u062f\u0647 \u06a9\u0646\u06cc\u062f \u062a\u0627 \u0648\u0627\u0628\u0633\u062a\u06af\u06cc\u200c\u0647\u0627 \u0627\u06cc\u0632\u0648\u0644\u0647 \u0634\u0648\u0646\u062f.\r\n\r\n## CLI (\u062f\u0631 \u0635\u0648\u0631\u062a \u0648\u062c\u0648\u062f) / CLI (If Available)\r\n\r\n\u0627\u06af\u0631 \u067e\u06a9\u06cc\u062c CLI \u0631\u0627 \u067e\u0634\u062a\u06cc\u0628\u0627\u0646\u06cc \u06a9\u0646\u062f:\r\n```\r\npython -m fipiranfunds.cli\r\n# \u06cc\u0627 \u0627\u06af\u0631 entry point \u062a\u0639\u0631\u06cc\u0641 \u0634\u062f\u0647 \u0628\u0627\u0634\u062f:\r\nfipiranfunds\r\n```\r\n\r\n## \u062a\u0648\u0633\u0639\u0647 \u0648 \u0645\u0634\u0627\u0631\u06a9\u062a / Contributing\r\n\r\n\u062e\u0648\u0634\u062d\u0627\u0644 \u0645\u06cc\u200c\u0634\u0648\u06cc\u0645 \u0627\u0632 \u06a9\u0645\u06a9 \u0634\u0645\u0627! \r\n- \u0645\u0633\u0627\u0626\u0644 (issues) \u06cc\u0627 \u062f\u0631\u062e\u0648\u0627\u0633\u062a\u200c\u0647\u0627\u06cc pull \u0631\u0627 \u062f\u0631 [\u06af\u06cc\u062a\u200c\u0647\u0627\u0628](https://github.com/Kimiaslhd/fipiranfunds) \u0628\u0627\u0632 \u06a9\u0646\u06cc\u062f.\r\n- \u0642\u0628\u0644 \u0627\u0632 \u0627\u0631\u0633\u0627\u0644 PR: \u062a\u0633\u062a\u200c\u0647\u0627\u06cc \u0645\u062d\u0644\u06cc \u0631\u0627 \u0627\u062c\u0631\u0627 \u06a9\u0646\u06cc\u062f\u060c \u06a9\u062f \u0631\u0627 \u0628\u0627 black \u0641\u0631\u0645\u062a \u06a9\u0646\u06cc\u062f\u060c \u0648 \u0633\u0628\u06a9 PEP 8 \u0631\u0627 \u0631\u0639\u0627\u06cc\u062a \u06a9\u0646\u06cc\u062f.\r\n- \u0628\u0631\u0627\u06cc \u0634\u0631\u0648\u0639: repo \u0631\u0627 fork \u06a9\u0646\u06cc\u062f\u060c \u062a\u063a\u06cc\u06cc\u0631\u0627\u062a \u0631\u0627 \u0627\u0639\u0645\u0627\u0644 \u06a9\u0646\u06cc\u062f\u060c \u0648 PR \u0627\u0631\u0633\u0627\u0644 \u06a9\u0646\u06cc\u062f.\r\n\r\n## \u062a\u063a\u06cc\u06cc\u0631\u0627\u062a / Changelog\r\n\r\n- **0.1.14**: \u0628\u0647\u0628\u0648\u062f README\u060c \u0631\u0641\u0639 \u0645\u0634\u06a9\u0644\u0627\u062a \u0631\u0646\u062f\u0631\u06cc\u0646\u06af PyPI\u060c \u0648 \u0635\u0627\u062f\u0631\u0627\u062a API \u062f\u0631 \u0633\u0637\u062d \u0628\u0627\u0644\u0627.\r\n- **0.1.13**: \u0646\u0633\u062e\u0647 \u0627\u0648\u0644\u06cc\u0647 \u0628\u0627 \u067e\u0634\u062a\u06cc\u0628\u0627\u0646\u06cc \u067e\u0627\u06cc\u0647 API \u0648 CSV.\r\n\r\n\u0628\u0631\u0627\u06cc \u062a\u063a\u06cc\u06cc\u0631\u0627\u062a \u06a9\u0627\u0645\u0644\u060c \u0628\u0647 [\u06af\u06cc\u062a\u200c\u0647\u0627\u0628 commits](https://github.com/Kimiaslhd/fipiranfunds/commits) \u0645\u0631\u0627\u062c\u0639\u0647 \u06a9\u0646\u06cc\u062f.\r\n\r\n## \u0645\u062c\u0648\u0632 / License\r\n\r\nMIT License. \u062c\u0632\u0626\u06cc\u0627\u062a \u062f\u0631 \u0641\u0627\u06cc\u0644 LICENSE.\r\n\r\n## \u0646\u0648\u06cc\u0633\u0646\u062f\u0647 \u0648 \u062a\u0645\u0627\u0633 / Author & Contact\r\n\r\n- **\u0646\u0627\u0645**: Kimia Salehi Delarestaghy\r\n- **\u0627\u06cc\u0645\u06cc\u0644**: kimiaslhd@gmail.com\r\n- **\u0644\u06cc\u0646\u06a9\u062f\u06cc\u0646**: [https://www.linkedin.com/in/kimia-salehy-delarestaghy/](https://www.linkedin.com/in/kimia-salehy-delarestaghy/)\r\n- **\u06af\u06cc\u062a\u200c\u0647\u0627\u0628**: [https://github.com/Kimiaslhd/fipiranfunds](https://github.com/Kimiaslhd/fipiranfunds)\r\n- **PyPI**: [https://pypi.org/project/fipiranfunds/](https://pypi.org/project/fipiranfunds/)\r\n\r\n\u0627\u06af\u0631 \u0633\u0624\u0627\u0644\u06cc \u062f\u0627\u0631\u06cc\u062f\u060c issue \u0628\u0627\u0632 \u06a9\u0646\u06cc\u062f \u06cc\u0627 \u0627\u06cc\u0645\u06cc\u0644 \u0628\u0632\u0646\u06cc\u062f!\r\n```\r\n\r\n---\r\n*Generated by: Grok 4*\r\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "A Python library for fetching and exporting Iranian fund data from Fipiran API to CSV",
"version": "0.1.15",
"project_urls": {
"Documentation": "https://github.com/Kimiaslhd/fipiranfunds#readme",
"Homepage": "https://github.com/Kimiaslhd/fipiranfunds",
"Issues": "https://github.com/Kimiaslhd/fipiranfunds/issues",
"Repository": "https://github.com/Kimiaslhd/fipiranfunds"
},
"split_keywords": [
"fipiran",
" funds",
" iran",
" api",
" finance",
" csv",
" pandas",
" jalali"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "15353ebf41b43a70ac07dee83a5e74f2c44248ef5ff83d233456ac486c55378d",
"md5": "4e2b64575ff201a316f784968b50b055",
"sha256": "2c7d507f92569107b0e2e92ae3b843eac4d6d6e28b8e7e8c84b8680c5190b2f3"
},
"downloads": -1,
"filename": "fipiranfunds-0.1.15-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4e2b64575ff201a316f784968b50b055",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 5554,
"upload_time": "2025-08-17T11:05:51",
"upload_time_iso_8601": "2025-08-17T11:05:51.336161Z",
"url": "https://files.pythonhosted.org/packages/15/35/3ebf41b43a70ac07dee83a5e74f2c44248ef5ff83d233456ac486c55378d/fipiranfunds-0.1.15-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5af3263994dab036e3b329d24536b7cfcbf22374d44492bc6f6554356d61ab15",
"md5": "64591f1321e91501ccfbaee083e2af9f",
"sha256": "625c29289e20d06b697e73a9435b4ccda21fa004408137481c98493fe5df7619"
},
"downloads": -1,
"filename": "fipiranfunds-0.1.15.tar.gz",
"has_sig": false,
"md5_digest": "64591f1321e91501ccfbaee083e2af9f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 12626,
"upload_time": "2025-08-17T11:05:52",
"upload_time_iso_8601": "2025-08-17T11:05:52.903044Z",
"url": "https://files.pythonhosted.org/packages/5a/f3/263994dab036e3b329d24536b7cfcbf22374d44492bc6f6554356d61ab15/fipiranfunds-0.1.15.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-17 11:05:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Kimiaslhd",
"github_project": "fipiranfunds#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "fipiranfunds"
}
JSON
