Metadata-Version: 2.4
Name: Alinvest-codal
Version: 1.5.10
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.5.10`

[![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>

---

## معرفی

`Alinvest-codal` یک کتابخانهٔ پایتون برای جست‌وجو و دریافت اطلاعیه‌های منتشرشده در سامانهٔ کدال و پردازش داده‌های ساختاریافتهٔ مالی است. کتابخانه نماد و اطلاعیه‌ها را از کدال جست‌وجو می‌کند و گزارش‌ها را در قالب مدل‌های پایتونی و DataFrame در اختیار برنامه قرار می‌دهد.

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

## امکانات

- جست‌وجوی اطلاعیه‌ها بر اساس نماد، نوع اطلاعیه و بازهٔ تاریخ شمسی
- دریافت صورت سود و زیان، ترازنامه و جریان وجوه نقد
- دریافت صورت‌های تکمیلی، فعالیت ماهانه و پورتفوی صندوق
- دریافت نمای کلی چند صورت مالی و داده‌های اختیاری مالکیت و هیئت‌مدیره
- خروجی‌های ساختاریافته، همراه با متدهای ذخیرهٔ 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/30",
    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

نام برند هر دو کانال **Alinvest** است:

- کانال تلگرام: **Alinvest**
- کانال بله: **Alinvest**

این کتابخانه پیام منتشر نمی‌کند و توکن ربات یا شناسهٔ کانال دریافت نمی‌کند. اگر برنامهٔ میزبان شما پیام می‌فرستد، اتصال و اطلاعات محرمانهٔ ربات را در همان برنامه و خارج از مخزن عمومی نگه دارید. برای نمونه‌های راه‌اندازی و متن پیشنهادی پیام، [راهنمای کانال‌ها](CHANNELS.md) را ببینید.

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

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

برای گزارش خطا و مشارکت، از مخزن [Alilnvest/Alilnvest-Codal](https://github.com/Alilnvest/Alilnvest-Codal) استفاده کنید. پیش از استفاده، [تاریخچهٔ تغییرات](CHANGELOG.md)، [مجوز](LICENSE) و [اطلاعیهٔ پروژه](NOTICE.md) را ببینید.

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

> اگر این کتابخانه در کارتان مفید است، حمایت شما به نگهداری، رفع اشکال و توسعهٔ قابلیت‌های تازهٔ **Alinvest** کمک می‌کند.
>
> **[حمایت مالی از Alinvest در دارمت ←](https://daramet.com/alilnvest)**

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

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

---

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