from bojstat.db_catalog import is_known_db as is_known_db
from bojstat.enums import DB as DB, Format as Format, Frequency as Frequency, Lang as Lang
from bojstat.errors import BojValidationError as BojValidationError
from collections.abc import Sequence
from typing import Any

def normalize_lang(value: Lang | str | None) -> Lang:
    """言語入力を正規化する。

    Args:
        value: 入力言語。

    Returns:
        正規化後の言語。

    Raises:
        BojValidationError: 値が不正な場合。
    """
def normalize_format(value: Format | str | None) -> Format:
    """出力形式入力を正規化する。"""
def normalize_frequency(value: Frequency | str | None, *, required: bool) -> Frequency | None:
    """期種入力を正規化する。

    Args:
        value: 期種入力。
        required: 必須項目か。

    Returns:
        正規化済み期種。任意項目未指定時はNone。

    Raises:
        BojValidationError: 必須未指定または不正値。
    """
def normalize_db(value: DB | str) -> str:
    """DB名を正規化する。"""
def validate_outbound_text(value: str, *, param_name: str) -> None:
    """外部送信する文字列を検証する。

    Args:
        value: 送信値。
        param_name: パラメータ名。

    Raises:
        BojValidationError: 禁止文字または全角文字を含む場合。
    """
def normalize_codes(code: str | Sequence[str]) -> list[str]:
    """系列コード入力を正規化する。"""
def normalize_layer(layer: str | Sequence[str | int]) -> list[str]:
    """階層指定を正規化する。"""
def normalize_periods(*, start: str | None, end: str | None, frequency: Frequency) -> tuple[str | None, str | None]:
    """開始期と終了期を正規化する。"""
def normalize_code_periods(*, start: str | None, end: str | None) -> tuple[str | None, str | None]:
    """Code API の開始期・終了期を正規化する。

    Code API は系列期種に依存して時期形式が変わるため、クライアント側では
    `YYYY` または `YYYYMM` の軽量検証と順序検証のみを行い、期種整合は API 応答へ委譲する。

    Args:
        start: 開始期。
        end: 終了期。

    Returns:
        正規化後の開始期・終了期。

    Raises:
        BojValidationError: 入力形式または順序が不正な場合。
    """
def normalize_start_position(value: int | str | None) -> int | None:
    """検索開始位置を正規化する。"""
def validate_strict_auto_split(*, strict_api: bool, auto_split_codes: bool) -> None:
    """strict_api と auto_split_codes の契約を検証する。"""
def normalize_raw_params(raw_params: dict[str, str] | None, *, allow_raw_override: bool) -> dict[str, str]:
    """raw_params の衝突検証を行う。"""
def guess_frequency_from_code(code: str) -> str:
    """系列コードから期種を推定する。

    Args:
        code: 系列コード。

    Returns:
        推定期種コード。推定不能時はUNKNOWN。
    """
def split_codes_by_frequency_and_size(codes: Sequence[str], *, chunk_size: int = 250) -> list[list[str]]:
    """系列コードを期種推定と件数で分割する。

    Args:
        codes: 系列コード列。
        chunk_size: チャンク上限。

    Returns:
        分割済みチャンク。
    """
def canonical_params(params: dict[str, Any]) -> list[tuple[str, str]]:
    """要求指紋生成向けにパラメータを正規化する。"""
