Metadata-Version: 2.4
Name: Alilnvest-Codal
Version: 1.5.4
Summary: Alilnvest-Codal — a resilient, typed Python client for Iranian Codal disclosures
License-Expression: MIT
Keywords: alilnvest,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: codal13_fixed_1.5.4-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

# Alilnvest-Codal

**A resilient Python client for Iranian Codal disclosures, financial statements, caching, reporting, and rate-limit-aware automation.**

نام انتشار این پروژه **Alilnvest-Codal** است و برند رسمی خروجی‌ها **Alilnvest** است.

این کتابخانه برای ربات‌های تحلیل بازار ایران، سرویس‌های backfill، اسکریپت‌های بنیادی و کانال‌های اطلاع‌رسانی طراحی شده و مستقل از پروژه‌های c5/c6 است.

## API و بازهٔ تاریخ

این نسخه کاملاً مستقل است و فقط با namespace `alilnvest_codal` منتشر می‌شود. نام و import قدیمی `namespace قدیمی` داخل این بسته وجود ندارد.

```python
import alilnvest_codal as cp

reports = cp.income_statement("فولاد", max_reports=5)
print(reports[0].period_end_to_date)
```

تاریخ‌ها hard-code نشده‌اند. در صورت‌های مالی، جست‌وجوی اطلاعیه و عملیات اتوماسیون می‌توان بازهٔ دلخواه جلالی را تعیین کرد:

```python
reports = cp.income_statement(
    "فولاد",
    from_date="1403/01/01",
    to_date="1403/12/30",
    max_reports=20,
)
```

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

## نصب

```bash
python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install .
```

برای قابلیت‌های async:

```bash
python -m pip install '.[async]'
```

## استفادهٔ سریع

```python
import alilnvest_codal as cp

income = cp.income_statement("توسن")
balance = cp.balance_sheet("توسن")
cashflow = cp.cash_flow_statement("توسن")
letters = cp.search_letters("توسن", max_pages=1)
snapshot = cp.financial_snapshot("توسن")
```

## خطاهای ساختاریافته

```python
try:
    reports = cp.income_statement("نماد_نامعتبر")
except cp.SymbolNotFoundError as exc:
    print(exc.symbol)
except cp.RateLimitError as exc:
    print(exc.retry_after)
except cp.NetworkError as exc:
    print(exc.status_code)
```

## نرخ درخواست، retry و circuit breaker

```python
import alilnvest_codal as cp

cp.configure(
    min_delay=2.0,
    max_delay=3.5,
    max_retries=2,
    symbol_min_delay=15,
    symbol_max_delay=20,
)
```

کتابخانه پاسخ `Retry-After` را رعایت می‌کند، خطاهای موقت را با backoff کنترل می‌کند و در شرایط شکست پیاپی circuit breaker دارد. هیچ نرخ ثابتی مسدودنشدن IP را تضمین نمی‌کند؛ برای چند پردازه یا چند سرویس روی یک IP از صف مرکزی استفاده کنید.

## کش و تنظیمات پیشنهادی

```env
CODAL_CACHE_DIR=~/bourse_reports/codal_cache
CODAL_FROM_JDATE=1403/01/01
CODAL_TO_JDATE=1405/12/29
CODAL_TIMEOUT=45
CODAL_MAX_RETRIES=3
CODAL_LOG_LEVEL=INFO
```

کتابخانه قبل از شبکه cache را بررسی می‌کند و در صورت شکست، تاریخچهٔ سالم را با دادهٔ ناقص جایگزین نمی‌کند.

## اتصال به کانال‌های Alilnvest

کتابخانه توکن پیام‌رسان را داخل کد قرار نمی‌دهد. ارسال پیام باید در adapter برنامه انجام شود و secrets فقط در `.env` خصوصی باشند.

### کانال بله

```env
ALILNVEST_CHANNEL_NAME=Alilnvest
BALE_BOT_TOKEN=توکن_ربات_بله
BALE_CHANNEL_ID=@شناسه_کانال_بله
```

ربات باید در کانال بلهٔ **Alilnvest** عضو و دارای مجوز ارسال باشد.

### کانال تلگرام

```env
ALILNVEST_CHANNEL_NAME=Alilnvest
TELEGRAM_BOT_TOKEN=توکن_ربات_تلگرام
TELEGRAM_CHANNEL_ID=@شناسه_کانال_تلگرام
```

ربات باید در کانال تلگرام **Alilnvest** ادمین باشد. نام رسمی برند و کانال‌ها در کپشن‌ها، گزارش‌ها و watermarkها نیز باید `Alilnvest` باشد.

## ساختار انتشار

- `src/alilnvest_codal/`: implementation سازگار با پروژه‌های قبلی
- `src/alilnvest_codal/`: namespace جدید برندشده
- `README.md`: راهنمای اصلی
- `MIGRATION.md`: راهنمای سازگاری
- `CHANGELOG.md`: تاریخچهٔ نسخه
- `NOTICE.md`: مالکیت و قواعد برند
- `LICENSE`: مجوز استفاده

فایل‌های تست، fixture، probe، diagnose و اسکریپت‌های توسعه از بستهٔ انتشار حذف شده‌اند. تست‌ها باید در مخزن توسعهٔ خصوصی نگهداری شوند، نه در archive تولیدی.

## دربارهٔ کپی‌برداری

کدی که در GitHub عمومی قرار می‌گیرد از نظر فنی قابل مشاهده و قابل کپی است. هیچ obfuscation واقعی این موضوع را حل نمی‌کند و obfuscation دیباگ، امنیت و نگهداری را ضعیف می‌کند. این بسته به‌جای آن versioning، metadata، `NOTICE.md` و برند مشخص دارد. اگر مالکیت انحصاری لازم است، repository را private نگه دارید و قبل از تغییر MIT به مجوز source-available محدودکننده، بررسی حقوقی انجام دهید.

## هشدار استفاده

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

## برند رسمی

- نام محصول: **Alilnvest-Codal**
- نام کانال‌ها: **Alilnvest**
- نام خروجی: **Alilnvest Codal Report**
- نام پیشنهادی کپشن: **Alilnvest Market Intelligence**
