Alilnvest-Codal 1.5.4__py3-none-any.whl

alilnvest_codal/__init__.py

@@ -0,0 +1,167 @@
+"""
+Alilnvest-Codal
+=========
+کتابخانهٔ مستقل Alilnvest برای کدال -- زنده، بدون لیست ثابت نماد.
+
+اصولِ طراحی (حاصلِ یه بررسیِ چندمرحله‌ای رویِ منابع پژوهشی قبلی و کتابخانه‌های مشابه):
+  - نماد همیشه زنده روی search.codal.ir چک می‌شه -> نمادهای تازه (توسن) از روز اول کار می‌کنن.
+  - صورت‌هایِ مالیِ اصلی از متغیرِ جاواسکریپتِ `datasource` توی صفحه‌ی گزارش خونده می‌شن، نه از دانلودِ اکسل.
+  - چندتا sheet (شرکت‌هایِ فرعی/وابسته، اعضایِ هیئت‌مدیره) اصلاً تویِ اون
+    datasource نیستن -- برایِ اون‌ها ضمیمه‌ی اکسلِ خودِ اطلاعیه با تطابقِ
+    دقیقِ اسمِ شیت خونده می‌شه (fetch_excel_sheet؛ نگاه کن به CHANGELOG ۰.۸.۹).
+  - سرفصل‌ها با row_code ایندکس می‌شن (پایدارتر از تطبیقِ متنی).
+  - ردیف‌های توضیحیِ بی‌مقدار (زیرِ جدول) به‌صورتِ پیش‌فرض حذف می‌شن.
+  - قبل از گرفتنِ datasource، عنوانِ اطلاعیه چک می‌شه تا وقتِ اطلاعیه‌های غیرمالی هدر نره.
+"""
+
+from ._version import __version__
+
+BRAND = "Alilnvest"
+DISTRIBUTION_NAME = "Alilnvest-Codal"
+from .exceptions import CodalError, SymbolNotFoundError, DataSourceError, NetworkError, ExcelParseError, RateLimitError
+from .http import reset_circuit_breaker, configure, clear_cache, safe_mode, fast_mode, symbol_pause, reset_symbol_pacing
+from .letter_codes import LETTER_CODES, describe_letter_code
+from .utils import validate_jdate
+from .progress import ConsoleProgress, SearchProgress
+from .models import Letter, DataSourceResult, FinancialReport, PortfolioReport, ReportQuality, SubsidiaryCompany, BoardMember, FinancialSnapshot
+from .search import search_letters, get_letter, latest_letter
+from .datasource import get_datasource, get_datasource_result, fetch_report_html
+from .sheets import SheetOption, SheetContent, parse_sheet_menu, list_sheets, read_sheet
+from .frames import cells_to_dataframe, cells_to_grid, apply_row_code_map
+from .reports import (
+    fetch_financial_reports,
+    fetch_structured_sheet,
+    fetch_excel_sheet,
+    fetch_company_snapshot,
+    FULL_STATEMENT_SHEET_IDS,
+    income_statement,
+    balance_sheet,
+    monthly_activity,
+    cash_flow_statement,
+    equity_changes_statement,
+    comprehensive_income_statement,
+    subsidiary_companies,
+    affiliated_companies,
+    board_members,
+    latest_income,
+    latest_balance_sheet,
+    latest_cash_flow,
+    list_subsidiaries,
+    list_affiliates,
+    list_board_members,
+    financial_snapshot,
+    compare_report_data,
+    auditor_opinion_text,
+    fund_portfolio,
+    looks_like_financial_report,
+    looks_like_portfolio_report,
+)
+
+from .checks import CheckResult, analyze_statement, analyze_set, analyze_portfolio, statement_kind, cash_flow_method
+from .audit import SymbolAudit, audit_symbol, audit_symbols, write_reports, detect_kind
+__all__ = [
+    "CheckResult", "analyze_statement", "analyze_set", "analyze_portfolio",
+    "statement_kind", "cash_flow_method", "SymbolAudit", "audit_symbol", "audit_symbols",
+    "write_reports", "detect_kind",
+    "CodalError",
+    "SymbolNotFoundError",
+    "DataSourceError",
+    "NetworkError",
+    "ExcelParseError",
+    "RateLimitError",
+    "reset_circuit_breaker",
+    "configure",
+    "clear_cache",
+    "safe_mode",
+    "fast_mode",
+    "symbol_pause",
+    "reset_symbol_pacing",
+    "LETTER_CODES",
+    "describe_letter_code",
+    "validate_jdate",
+    "SearchProgress",
+    "ConsoleProgress",
+    "Letter",
+    "DataSourceResult",
+    "FinancialReport",
+    "PortfolioReport",
+    "ReportQuality",
+    "SubsidiaryCompany",
+    "BoardMember",
+    "FinancialSnapshot",
+    "search_letters",
+    "get_letter",
+    "latest_letter",
+    "get_datasource",
+    "get_datasource_result",
+    "fetch_report_html",
+    "SheetOption",
+    "SheetContent",
+    "parse_sheet_menu",
+    "list_sheets",
+    "read_sheet",
+    "cells_to_dataframe",
+    "cells_to_grid",
+    "apply_row_code_map",
+    "fetch_financial_reports",
+    "fetch_structured_sheet",
+    "fetch_excel_sheet",
+    "fetch_company_snapshot",
+    "FULL_STATEMENT_SHEET_IDS",
+    "income_statement",
+    "balance_sheet",
+    "monthly_activity",
+    "cash_flow_statement",
+    "equity_changes_statement",
+    "comprehensive_income_statement",
+    "subsidiary_companies",
+    "affiliated_companies",
+    "board_members",
+    "latest_income",
+    "latest_balance_sheet",
+    "latest_cash_flow",
+    "list_subsidiaries",
+    "list_affiliates",
+    "list_board_members",
+    "financial_snapshot",
+    "compare_report_data",
+    "auditor_opinion_text",
+    "fund_portfolio",
+    "looks_like_financial_report",
+    "looks_like_portfolio_report",
+    "__version__",
+    "BRAND",
+    "DISTRIBUTION_NAME",
+]
+
+
+# 1.0 additions; the imports above intentionally remain for 0.9 compatibility.
+from .api import (
+    async_balance_sheet,
+    async_income_statement,
+    balance_sheet as modern_balance_sheet,
+    income_statement as modern_income_statement,
+)
+from .cache import Cache
+from .config import CodalConfig, DEFAULT_CONFIG
+from .endpoints import BROWSER_HEADERS, CodalEndpoint
+from .http import CodalHTTPClient
+from .exceptions import CodalNetworkError, CodalNotFoundError, CodalParsingError
+from .codal import Codal
+from .health import health_check
+from .automation import CodalRun, CodalBot, OperationResult, fetch_since
+from .store import SQLiteStore, StoredDatasource
+
+# New names are aliases at the package boundary; the legacy names above retain
+# their richer optional arguments and historical report types.
+__all__ += [
+    "CodalConfig", "DEFAULT_CONFIG", "Cache", "CodalEndpoint", "BROWSER_HEADERS",
+    "CodalHTTPClient", "CodalNetworkError", "CodalNotFoundError", "CodalParsingError",
+    "async_income_statement", "async_balance_sheet", "modern_income_statement", "modern_balance_sheet", "Codal", "health_check", "CodalRun", "CodalBot", "OperationResult", "fetch_since",
+    "SQLiteStore", "StoredDatasource",
+]
+# The stable 1.0 API must win at the package boundary.  The underlying legacy
+# implementation is still available as reports.income_statement and retains
+# its historical optional arguments.
+income_statement = modern_income_statement  # noqa: F811 — legacy name intentionally replaced at package boundary
+balance_sheet = modern_balance_sheet  # noqa: F811 — legacy name intentionally replaced at package boundary

alilnvest_codal/_version.py

@@ -0,0 +1,2 @@
+"""Package version."""
+__version__ = "1.5.4"

alilnvest_codal/amendments.py

@@ -0,0 +1,82 @@
+"""اصلاحیه: اطلاعیه‌ی اصلاح‌شده را با اولیه‌اش می‌سنجد و می‌گوید اصلاحیه کدام عددها را عوض کرده است.
+
+کدال گاهی یک اطلاعیه را «اصلاحیه» می‌کند و هر دو نسخه جداگانه منتشر می‌شوند. این ماژول نسخه‌ی اولیه‌ی همان دوره
+را پیدا می‌کند (همان پایان دوره، همان نوع تلفیقی یا غیرتلفیقی، و بدون عبارت «اصلاحیه») و عددهایی را که فرق دارند
+فهرست می‌کند. این ماژول خالص است؛ جست‌وجوی شبکه در audit.py انجام می‌شود.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+from .checks import CheckResult, column_layout, fa_digits, index_rows, period_of, row_key
+
+__all__ = ["AMENDMENT_MARK", "is_amendment", "find_original", "differences", "compare_with_original"]
+
+AMENDMENT_MARK = "اصلاحیه"
+TOLERANCE = 1.0  # ریال
+KIND_NAMES = {"balance": "ترازنامه", "income": "سود و زیان", "cash_flow": "جریان نقد"}
+
+
+def is_amendment(report: Any) -> bool:
+    return AMENDMENT_MARK in row_key(getattr(report, "title", "") or "")
+
+
+def find_original(current: Any, candidates: Iterable[Any]) -> Any | None:
+    """اولین اطلاعیه‌ای که همان پایان دوره و همان نوع (تلفیقی/غیرتلفیقی) را دارد و اصلاحیه نیست."""
+    matches = []
+    for rep in candidates:
+        if rep is None or rep.tracing_no == current.tracing_no or is_amendment(rep):
+            continue
+        if rep.period_end_to_date != current.period_end_to_date:
+            continue
+        if bool(rep.is_consolidated) != bool(current.is_consolidated):
+            continue
+        matches.append(rep)
+    if not matches:
+        return None
+    def sort_key(rep):
+        date = getattr(rep, "publish_date_time", None) or getattr(rep, "sent_date_time", None) or "~"
+        return (date, int(rep.tracing_no) if rep.tracing_no is not None else 2**63 - 1)
+    return min(matches, key=sort_key)
+
+
+def _values(report: Any) -> dict[tuple[str, str], tuple[str, float]]:
+    """(کلید برچسب، تاریخ ستون) -> (برچسب، مقدار). اولین رخداد هر کلید نگه داشته می‌شود."""
+    layout = column_layout(report.raw)
+    out: dict[tuple[str, str], tuple[str, float]] = {}
+    for row in index_rows(report.row_code_df):
+        if not row["key"]:
+            continue
+        for col, value in row["vals"].items():
+            if col <= 1:
+                continue
+            date = period_of(layout, col)
+            if date:
+                out.setdefault((row["key"], date), (row["label"], value))
+    return out
+
+
+def differences(current: Any, original: Any, *, tolerance: float = TOLERANCE) -> list[dict[str, Any]]:
+    """عددهایی که در اصلاحیه (current) با اطلاعیه‌ی اولیه (original) فرق دارند."""
+    new, old = _values(current), _values(original)
+    diffs = []
+    for key in sorted(set(new) & set(old), key=lambda k: (k[1], k[0])):
+        label, before = old[key]
+        _, after = new[key]
+        if abs(before - after) > tolerance:
+            diffs.append({"label": label, "period": key[1], "original": before, "amended": after})
+    return diffs
+
+
+def compare_with_original(kind: str, current: Any, original: Any) -> CheckResult:
+    name = f"{KIND_NAMES.get(kind, kind)}: اصلاحیه در برابر اطلاعیه‌ی اولیه"
+    head = f"TracingNo={current.tracing_no} (اصلاحیه) در برابر TracingNo={original.tracing_no} (اولیه)"
+    diffs = differences(current, original)
+    if not diffs:
+        return CheckResult("ok", "اصلاحیه", name, f"{head}: هیچ عددی تغییر نکرده است")
+    details = [f"{d['label']} | {fa_digits(d['period'])}: {d['original']:,.0f} → {d['amended']:,.0f}"
+               for d in diffs[:15]]
+    if len(diffs) > 15:
+        details.append(f"و {len(diffs) - 15} مورد دیگر")
+    return CheckResult("info", "اصلاحیه", name, f"{head}: {len(diffs)} عدد تغییر کرده است", tuple(details))

alilnvest_codal/analytics.py

@@ -0,0 +1,174 @@
+"""پاک‌سازی، مدل‌سازی، export و مقایسه‌ی خروجی‌ها -- لایه‌یِ کمکیِ اختیاری، بالایِ خروجیِ خامِ reports.py."""
+
+from __future__ import annotations
+
+import json
+import math
+from typing import Any
+
+import pandas as pd
+
+from .models import BoardMember, ReportQuality, SubsidiaryCompany
+from .utils import normalize_fa
+
+# نگاشتِ اسمِ ستون‌هایِ فارسیِ رایج (تویِ شیت‌هایِ «شرکت های فرعی»/«شرکت های
+# وابسته») به اسمِ فیلدِ انگلیسیِ SubsidiaryCompany -- برایِ standardize_columns.
+SUBSIDIARY_COLUMN_ALIASES = {
+    "نماد شرکت": "symbol",
+    "نام شرکت": "name",
+    "نماد ثبت شده نزد سازمان": "registered_symbol",
+    "وضعیت ثبت شده نزد سازمان": "registration_status",
+    "نوع فعالیت": "activity_type",
+    "حسابرس": "auditor",
+    "سال مالی": "fiscal_year",
+    "فعال/غیر فعال": "active_status",
+    "وضعیت": "status",
+}
+
+
+def _unique_columns(columns: list[Any]) -> list[str]:
+    """نام ستون‌ها را پایدار و یکتا می‌کند تا ستون تکراری بی‌صدا ادغام نشود."""
+    seen: dict[str, int] = {}
+    result: list[str] = []
+    for value in columns:
+        base = str(value).strip() or "column"
+        count = seen.get(base, 0)
+        seen[base] = count + 1
+        result.append(base if count == 0 else f"{base}_{count + 1}")
+    return result
+
+
+def clean_table(df: pd.DataFrame, *, drop_header: bool = True) -> tuple[pd.DataFrame, ReportQuality]:
+    """
+    خروجیِ خامِ grid_df (که address-based ـه، نه row_code) رو تمیز می‌کنه:
+    ستون‌هایِ کاملاً خالی و ردیف‌هایِ کاملاً تکراری رو حذف می‌کنه، و اگه
+    drop_header=True بود و ردیفِ اول با حداقل ۲ تا از اسم‌هایِ شناخته‌شده‌ی
+    SUBSIDIARY_COLUMN_ALIASES مطابقت داشت، همون ردیف رو به‌عنوانِ هدرِ
+    واقعی برمی‌داره (نه ستون‌هایِ عددیِ پیش‌فرضِ 0/1/2/...).
+
+    خروجیِ دوم (ReportQuality) شفاف می‌گه چقدر ردیف/ستون حذف شد -- تا کاربر
+    کورکورانه به تمیزکاری اعتماد نکنه.
+    """
+    out = df.copy()
+    original_column_count = len(out.columns)
+    duplicate_rows = int(out.duplicated().sum())
+
+    out = out.dropna(axis=1, how="all").drop_duplicates().reset_index(drop=True)
+
+    if drop_header and not out.empty:
+        first_row_normalized = [normalize_fa(str(x)) for x in out.iloc[0].tolist()]
+        known_headers_normalized = {normalize_fa(k) for k in SUBSIDIARY_COLUMN_ALIASES}
+        if len(set(first_row_normalized) & known_headers_normalized) >= 2:
+            out.columns = _unique_columns(list(out.iloc[0]))
+            out = out.iloc[1:].reset_index(drop=True)
+
+    quality = ReportQuality(
+        "cleaned_table",
+        duplicate_rows_removed=duplicate_rows,
+        empty_columns_removed=original_column_count - len(out.columns),
+    )
+    return out, quality
+
+
+def standardize_columns(df: pd.DataFrame) -> pd.DataFrame:
+    """ستون‌هایی که اسمِ فارسیِ شناخته‌شده دارن (SUBSIDIARY_COLUMN_ALIASES) رو به اسمِ فیلدِ انگلیسی تغییر می‌ده؛ بقیه دست‌نخورده می‌مونن."""
+    out = df.copy()
+    aliases_normalized = {normalize_fa(k): v for k, v in SUBSIDIARY_COLUMN_ALIASES.items()}
+    out.columns = _unique_columns([aliases_normalized.get(normalize_fa(str(c)), str(c)) for c in out.columns])
+    return out
+
+
+def subsidiary_models(df: pd.DataFrame) -> list[SubsidiaryCompany]:
+    """grid_dfِ تمیزشده‌یِ شرکت‌هایِ فرعی/وابسته رو به لیستی از SubsidiaryCompany تبدیل می‌کنه."""
+    out = standardize_columns(df)
+    allowed_fields = set(SubsidiaryCompany.__dataclass_fields__) - {"raw"}
+    result: list[SubsidiaryCompany] = []
+    for _, row in out.iterrows():
+        values = {
+            field_name: (None if field_name not in row or pd.isna(row[field_name]) else str(row[field_name]))
+            for field_name in allowed_fields
+        }
+        result.append(SubsidiaryCompany(**values, raw=row.to_dict()))
+    return result
+
+
+def board_models(df: pd.DataFrame) -> list[BoardMember]:
+    """
+    grid_dfِ تمیزشده‌یِ اعضایِ هیئت‌مدیره رو به لیستی از BoardMember تبدیل
+    می‌کنه. اگه ستونِ "name"/"role" (بعدِ standardize_columns) پیدا نشد،
+    به‌ترتیب اولین/دومین ستون رو به‌عنوانِ fallback به‌کار می‌بره -- چون
+    اسمِ دقیقِ ستون‌هایِ این شیت هنوز تویِ SUBSIDIARY_COLUMN_ALIASES نیستن.
+    """
+    out = standardize_columns(df)
+    columns = list(out.columns)
+    name_column = "name" if "name" in columns else (columns[0] if columns else None)
+    role_column = "role" if "role" in columns else (columns[1] if len(columns) > 1 else None)
+
+    result: list[BoardMember] = []
+    for _, row in out.iterrows():
+        name = None if name_column is None or pd.isna(row.get(name_column)) else str(row.get(name_column))
+        role = None if role_column is None or pd.isna(row.get(role_column)) else str(row.get(role_column))
+        result.append(BoardMember(name, role, row.to_dict()))
+    return result
+
+
+def dataframe_to_json(df: pd.DataFrame, path: str, *, metadata: dict | None = None, **kwargs: Any) -> None:
+    """DataFrame رو به یه فایلِ JSON با ساختارِ {"metadata": ..., "rows": [...]} می‌نویسه (UTF-8، بدونِ escapeِ فارسی)."""
+    def json_safe(value: Any) -> Any:
+        if value is None or isinstance(value, (str, bool, int)):
+            return value
+        if isinstance(value, float):
+            return value if math.isfinite(value) else None
+        if isinstance(value, dict):
+            return {str(k): json_safe(v) for k, v in value.items()}
+        if isinstance(value, (list, tuple)):
+            return [json_safe(v) for v in value]
+        try:
+            if pd.isna(value):
+                return None
+        except (TypeError, ValueError):
+            pass
+        return str(value)
+
+    rows = df.where(pd.notna(df), None).to_dict(orient="records")
+    payload = {"metadata": json_safe(metadata or {}), "rows": json_safe(rows)}
+    kwargs.setdefault("ensure_ascii", False)
+    kwargs.setdefault("indent", 2)
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(payload, f, **kwargs)
+
+
+def compare_reports(old: Any, new: Any, *, key: str | None = None) -> dict[str, Any]:
+    """
+    دو گزارش (یا مستقیم دو DataFrame) رو مقایسه می‌کنه -- `old`/`new` می‌تونن
+    خودِ FinancialReport/PortfolioReport باشن (grid_df/row_code_df ازشون
+    خونده می‌شه) یا مستقیم DataFrame.
+
+    اگه key بدی و تویِ هر دو ستون باشه، بر اساسِ اون ایندکس می‌کنه (مقایسه‌ی
+    دقیق‌تر بر اساسِ شناسه، نه شماره‌ی ردیف). خروجی: کدوم ردیف‌ها اضافه
+    شدن، کدوم حذف شدن، کدوم مقدارشون فرق کرده.
+    """
+    old_df = getattr(old, "grid_df", getattr(old, "row_code_df", old)).copy()
+    new_df = getattr(new, "grid_df", getattr(new, "row_code_df", new)).copy()
+
+    if key and key in old_df.columns and key in new_df.columns:
+        old_df, new_df = old_df.set_index(key), new_df.set_index(key)
+    if not (old_df.index.is_unique and new_df.index.is_unique):
+        # با ایندکسِ تکراری، loc یک DataFrame برمی‌گرداند نه یک سطر؛ مقایسه بی‌معنی می‌شود.
+        raise ValueError("compare_reports: شناسه‌ها باید یکتا باشند (ردیفِ تکراری در یکی از گزارش‌ها).")
+
+    old_keys, new_keys = set(old_df.index), set(new_df.index)
+
+    changed: list[dict[str, Any]] = []
+    for idx in sorted(old_keys & new_keys, key=str):  # ترتیبِ قطعی برای خروجیِ قابل‌مقایسه
+        if not old_df.loc[idx].equals(new_df.loc[idx]):
+            changed.append({"key": idx, "old": old_df.loc[idx].to_dict(), "new": new_df.loc[idx].to_dict()})
+
+    added_keys = sorted(new_keys - old_keys, key=str)
+    removed_keys = sorted(old_keys - new_keys, key=str)
+    return {
+        # reset_index تا کلیدِ ردیف (همان «key» در changed) در خروجی بماند؛ با to_dict("records") خالی گم می‌شد
+        "added": new_df.loc[added_keys].rename_axis("key").reset_index().to_dict("records"),
+        "removed": old_df.loc[removed_keys].rename_axis("key").reset_index().to_dict("records"),
+        "changed": changed,
+    }

alilnvest_codal/api.py

@@ -0,0 +1,69 @@
+"""Stable 1.0 public API.
+
+The legacy report engine remains underneath so existing advanced features keep
+working while callers receive keyword-only, injectable entry points.
+"""
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from .config import CodalConfig
+from .http import CodalHTTPClient
+from .reports import balance_sheet as _balance_sheet
+from .reports import income_statement as _income_statement
+
+
+def income_statement(
+    symbol: str,
+    *,
+    from_date: str | None = None,
+    max_reports: int | None = None,
+    use_cache: bool = True,
+    client: CodalHTTPClient | None = None,
+    **kwargs: Any,
+) -> list[Any]:
+    """Return income statements, preserving the mature Codal parser behavior."""
+    options = dict(kwargs)
+    if from_date is not None:
+        options["from_date"] = from_date
+    if max_reports is not None:
+        options["max_reports"] = max_reports
+    options["use_cache"] = use_cache
+    options["client"] = client
+    options.setdefault("max_concurrency", 5)
+    return _income_statement(symbol, **options)
+
+
+def balance_sheet(
+    symbol: str,
+    *,
+    from_date: str | None = None,
+    max_reports: int | None = None,
+    use_cache: bool = True,
+    client: CodalHTTPClient | None = None,
+    **kwargs: Any,
+) -> list[Any]:
+    """Return balance sheets with the same compatibility guarantees as 0.9."""
+    options = dict(kwargs)
+    if from_date is not None:
+        options["from_date"] = from_date
+    if max_reports is not None:
+        options["max_reports"] = max_reports
+    options["use_cache"] = use_cache
+    options["client"] = client
+    options.setdefault("max_concurrency", 5)
+    return _balance_sheet(symbol, **options)
+
+
+async def async_income_statement(symbol: str, **kwargs: Any) -> list[Any]:
+    """Async facade for applications that need a non-blocking call site."""
+    return await asyncio.to_thread(income_statement, symbol, **kwargs)
+
+
+async def async_balance_sheet(symbol: str, **kwargs: Any) -> list[Any]:
+    """Async facade for applications that need a non-blocking call site."""
+    return await asyncio.to_thread(balance_sheet, symbol, **kwargs)
+
+
+__all__ = ["income_statement", "balance_sheet", "async_income_statement", "async_balance_sheet", "CodalConfig"]