Metadata-Version: 2.4
Name: Alinvest-codal
Version: 1.7.1
Summary: Alinvest-codal — a resilient, typed Python client for Iranian Codal disclosures
License-Expression: MIT
Project-URL: Homepage, https://github.com/Alilnvest/Alilnvest-Codal
Project-URL: Repository, https://github.com/Alilnvest/Alilnvest-Codal
Project-URL: Issues, https://github.com/Alilnvest/Alilnvest-Codal/issues
Project-URL: Changelog, https://github.com/Alilnvest/Alilnvest-Codal/blob/main/CHANGELOG.md
Keywords: alinvest,codal,iran,bourse,financial-statements,pandas
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE.md
Requires-Dist: requests>=2.28
Requires-Dist: pandas>=2.0
Requires-Dist: lxml>=5.0
Requires-Dist: beautifulsoup4>=4.11
Requires-Dist: openpyxl>=3.1
Requires-Dist: xlrd>=2.0.1
Requires-Dist: jdatetime>=5.0
Provides-Extra: async
Requires-Dist: httpx>=0.27; extra == "async"
Provides-Extra: quality
Requires-Dist: ruff>=0.6; extra == "quality"
Requires-Dist: mypy>=1.11; extra == "quality"
Requires-Dist: httpx>=0.27; extra == "quality"
Dynamic: license-file

<div align="center">

# Alinvest-Codal

### کتابخانهٔ پایتون برای دریافت و تحلیل داده‌های کدال بورس ایران

**نام نصب:** `Alinvest-codal` · **نام ایمپورت:** `alinvest_codal` · **نسخه:** `1.7.1`

[![Python](https://img.shields.io/pypi/pyversions/Alinvest-codal?color=3776AB&logo=python&logoColor=white)](https://pypi.org/project/Alinvest-codal/)
[![Version](https://img.shields.io/pypi/v/Alinvest-codal?color=2563EB)](https://pypi.org/project/Alinvest-codal/)
[![License: MIT](https://img.shields.io/badge/License-MIT-16A085.svg)](LICENSE)
[![Data](https://img.shields.io/badge/Data-Codal-F59E0B)](https://www.codal.ir/)

**ساخته‌شده با برند Alinvest؛ برای کار با داده‌های بازار سرمایه ایران**

</div>

---

## 💚 حمایت از توسعه

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

<p align="center">
  <a href="https://daramet.com/alilnvest">
    <img src="https://img.shields.io/badge/حمایت%20مالی-Daramet-159e89?style=for-the-badge&logo=heart&logoColor=white" alt="حمایت مالی">
  </a>
</p>

<p align="center">
  <a href="https://daramet.com/alilnvest">https://daramet.com/alilnvest</a>
</p>
## معرفی

`Alinvest-Codal` یک کتابخانهٔ پایتون برای کار با داده‌های **کدال بورس ایران** است. با آن می‌توانید اطلاعیه‌های ناشران بورسی را بر اساس نماد و تاریخ جست‌وجو کنید و صورت‌های مالی شرکت‌ها—از جمله صورت سود و زیان، ترازنامه و جریان وجوه نقد—را دریافت و در Python پردازش کنید.

این پکیج کدال برای تحلیل بنیادی و ساخت ابزارهای بازار سرمایه، گزارش‌های فعالیت ماهانه، داده‌های صندوق‌ها، تاریخ شمسی جلالی و خروجی‌های CSV، Excel و JSON را نیز پشتیبانی می‌کند. داده‌های دریافت‌شده در مدل‌های پایتونی و DataFrame در دسترس‌اند. نام نصب از PyPI برابر `Alinvest-codal` و نام import در برنامه `alinvest_codal` است.

کتابخانه خودش به تلگرام یا بله پیام ارسال نمی‌کند؛ ربات و اتصال پیام‌رسان باید در برنامهٔ میزبان ساخته شود.

## امکانات

- جست‌وجوی اطلاعیه‌ها بر اساس نماد، نوع اطلاعیه و بازهٔ تاریخ شمسی
- دریافت صورت سود و زیان، ترازنامه و جریان وجوه نقد
- دریافت صورت‌های تکمیلی، فعالیت ماهانه و پورتفوی صندوق
- دریافت نمای کلی چند صورت مالی و داده‌های اختیاری مالکیت و هیئت‌مدیره
- خروجی‌های ساختاریافته، همراه با متدهای ذخیرهٔ CSV، Excel و JSON
- کش درخواست‌ها، تلاش مجدد برای خطاهای گذرا و کنترل circuit breaker
- ابزارهای تحلیل و ممیزی صورت‌های مالی
- رابط‌های async برای صورت سود و زیان و ترازنامه
- پشتیبانی از Python 3.10 به بالا

## نصب

### نصب از PyPI

```bash
python -m pip install --upgrade Alinvest-codal
```

برای قابلیت‌های اختیاری کلاینت HTTP مبتنی بر `httpx`:

```bash
python -m pip install "Alinvest-codal[async]"
```

### نصب از سورس

```bash
python -m pip install .
```

> نام انتشار روی PyPI، `Alinvest-codal` است؛ در کد پایتون آن را با نام `alinvest_codal` وارد کنید. خط تیره در نام ماژول قابل ایمپورت پایتون استفاده نمی‌شود.

## شروع سریع

```python
import alinvest_codal as codal

reports = codal.income_statement(
    "فولاد",
    from_date="1403/01/01",
    to_date="1403/12/29",
    max_reports=3,
    progress=False,
)

for report in reports:
    print(report.title, report.period_end_to_date)
    print(report.row_code_df.head())
```

تاریخ‌ها در قالب `YYYY/MM/DD` و بر اساس تقویم جلالی هستند. اگر تاریخ شروع را تعیین نکنید، مقدار پیش‌فرض کتابخانه استفاده می‌شود؛ برای دریافت دقیق یک بازه، هر دو تاریخ را صریح مشخص کنید.

## نمونه‌های متداول

### صورت‌های مالی

```python
import alinvest_codal as codal

income = codal.income_statement("فولاد", max_reports=5, progress=False)
balance = codal.balance_sheet("فولاد", max_reports=5, progress=False)
cash_flow = codal.cash_flow_statement("فولاد", max_reports=5, progress=False)

if income:
    latest = income[0]
    print(latest.title)
    print(latest.row_code_df.head())
```

### جست‌وجوی اطلاعیه‌ها

`search_letters` یک iterator برمی‌گرداند؛ در صورت نیاز می‌توانید نتیجه را به فهرست تبدیل کنید:

```python
import alinvest_codal as codal

letters = list(
    codal.search_letters(
        "فولاد",
        from_date="1404/01/01",
        to_date="1404/12/29",
        max_pages=1,
        progress=False,
    )
)

for letter in letters:
    print(letter.tracing_no, letter.title, letter.publish_date_time)
```

### نمای کلی صورت‌های مالی

`financial_snapshot` یک فهرست از `FinancialSnapshot` برمی‌گرداند. با `include_ownership=True` اطلاعات مالکیت و اعضای هیئت‌مدیره نیز درخواست می‌شود.

```python
import alinvest_codal as codal

snapshots = codal.financial_snapshot(
    "فولاد",
    max_reports=1,
    include_ownership=True,
    progress=False,
)

if snapshots:
    snapshot = snapshots[0]
    print(snapshot.period_end_to_date)
    if snapshot.income_statement is not None:
        print(snapshot.income_statement.row_code_df.head())
```

### ذخیرهٔ گزارش

شیء `FinancialReport` متدهای `to_csv`، `to_excel` و `to_json` دارد:

```python
if income:
    report = income[0]
    report.to_csv("income_statement.csv")
    report.to_excel("income_statement.xlsx")
    report.to_json("income_statement.json")
```

## تنظیم سرعت و درخواست‌ها

برای کنترل فاصلهٔ درخواست‌ها، تعداد تلاش مجدد و فاصلهٔ بین نمادها از `configure` استفاده کنید:

```python
import alinvest_codal as codal

codal.configure(
    min_delay=2.0,
    max_delay=3.5,
    max_retries=2,
    symbol_min_delay=15.0,
    symbol_max_delay=20.0,
)
```

برای اجرای محافظه‌کارانه و طولانی‌مدت:

```python
codal.safe_mode()
```

`fast_mode()` پروفایل کوتاه‌تری برای اجراهای تعاملی تنظیم می‌کند؛ هیچ نرخ درخواستی تضمین نمی‌کند که سرویس کدال دسترسی را محدود نکند. در صورت اجرای چند worker یا چند سرویس روی یک IP، نرخ درخواست مشترک را در برنامهٔ خود مدیریت کنید.

کتابخانه برای درخواست‌های GET کش حافظه‌ای دارد. متغیرهای زیر برای ساخت `CodalConfig` و تنظیم `CodalHTTPClient` در دسترس‌اند. کلاینت را به توابع گزارش پاس بدهید تا این تنظیمات در درخواست استفاده شوند:

```bash
export CODAL_TIMEOUT=30
export CODAL_MAX_RETRIES=3
export CODAL_DELAY=1
export CODAL_CACHE_TTL=3600
export CODAL_CACHE_DIR="$HOME/.cache/alinvest-codal"
export CODAL_NO_CACHE=false
export CODAL_MAX_CONCURRENCY=5
export CODAL_LOG_LEVEL=INFO
```

```python
from alinvest_codal import CodalConfig, CodalHTTPClient, income_statement

config = CodalConfig.from_env()
with CodalHTTPClient(config) as client:
    reports = income_statement(
        "فولاد",
        max_reports=3,
        client=client,
        progress=False,
    )
```

همچنین می‌توانید مقدار پیش‌فرض تاریخ شروع جست‌وجو را با `CODAL_DEFAULT_FROM_DATE` تنظیم کنید. این مقادیر اختیاری‌اند؛ در صورت نیاز، پارامترهای هر درخواست را مستقیماً بدهید.

برای نگهداری پایدار داده‌های datasource می‌توان از `SQLiteStore` استفاده کرد:

```python
from alinvest_codal import SQLiteStore, income_statement

with SQLiteStore("codal.sqlite3") as store:
    reports = income_statement(
        "فولاد",
        max_reports=3,
        store=store,
        progress=False,
    )
```

## مدیریت خطاها

همهٔ استثناهای اصلی از `CodalError` مشتق شده‌اند و می‌توان بر اساس نوع خطا واکنش نشان داد:

```python
import alinvest_codal as codal

try:
    reports = codal.income_statement("نماد_نامعتبر", max_reports=1)
except codal.SymbolNotFoundError as exc:
    print("نماد پیدا نشد:", exc.symbol)
except codal.RateLimitError as exc:
    print("محدودیت درخواست؛ زمان انتظار:", exc.retry_after)
except codal.NetworkError as exc:
    print("خطای شبکه:", exc.status_code)
except codal.CodalError as exc:
    print("خطای کدال:", exc)
```

## استفادهٔ async

توابع async برای صورت سود و زیان و ترازنامه از API عمومی قابل دسترسی‌اند:

```python
import asyncio
from alinvest_codal import async_income_statement

async def main():
    reports = await async_income_statement(
        "فولاد",
        max_reports=3,
        progress=False,
    )
    for report in reports:
        print(report.title)

asyncio.run(main())
```

## کانال‌ها و شبکه‌های رسمی Alinvest

- تلگرام: [@Alilnvest](https://t.me/Alilnvest)
- بله: [@Alilnvest](https://ble.ir/Alilnvest)
- اینستاگرام: [@Alilnvest](https://www.instagram.com/Alilnvest/)

## اطلاعات پروژه

| مورد | مقدار |
|---|---|
| نام انتشار | `Alinvest-codal` |
| نام ماژول پایتون | `alinvest_codal` |
| نسخه | `1.5.10` |
| حداقل نسخهٔ پایتون | `3.10` |
| منبع داده | سامانهٔ کدال |
| مجوز | MIT |

## لینک‌های پروژه

- [صفحهٔ PyPI و نصب کتابخانه](https://pypi.org/project/Alinvest-Codal/)
- [مخزن GitHub و کد منبع](https://github.com/Alilnvest/Alilnvest-Codal)
- [گزارش مشکل یا پیشنهاد](https://github.com/Alilnvest/Alilnvest-Codal/issues)
- [تاریخچهٔ تغییرات](CHANGELOG.md) · [مجوز MIT](LICENSE)

## سلب مسئولیت

این کتابخانه ابزاری برای دریافت و پردازش داده است و توصیهٔ سرمایه‌گذاری محسوب نمی‌شود. دسترس‌پذیری سرویس کدال، شکل اطلاعیه‌ها و محتوای منتشرشده ممکن است تغییر کند. پیش از استفادهٔ عملیاتی، خروجی‌ها و محدودیت‌های دسترسی را در محیط خود بررسی کنید.

---

<div align="center">
<strong>Alinvest-Codal</strong><br>
کتابخانهٔ پایتون برای داده‌های مالی و اطلاعیه‌های کدال ایران<br>
با برند <strong>Alinvest</strong>
</div>
