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 قدیمی داخل این بسته وجود ندارد.

import alilnvest_codal as cp

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

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

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 همیشه هر دو تاریخ را صریح ارسال کنید.

نصب

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

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

python -m pip install '.[async]'

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

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("توسن")

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

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

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 از صف مرکزی استفاده کنید.

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

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 خصوصی باشند.

کانال بله

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

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

کانال تلگرام

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