"""Single-source SQL identifier contract: the charset rule + the quoter.

Two single-definition primitives for SQL identifiers / db_ids, both previously
hand-inlined across the env, ingestion, data card, demo UI, and eval policies:

- ``is_valid_identifier`` — the ``^[A-Za-z0-9_]+$`` charset contract
  ``SQLEnvironment`` enforces for db_ids and that any table name must satisfy
  before reaching raw SQL (was re-derived at four sites).
- ``quote_ident`` — double-quotes an identifier and escapes any embedded
  double-quote (SQL standard ``"`` -> ``""``) so a hostile name like
  ``a"; DROP TABLE x`` can never break out of the quoted identifier (was inlined
  at five sites).

This is a stdlib-only LEAF module (no project imports, no heavy deps); importing
it never pulls ``gradio``/``torch``/``trl``/``transformers``.
"""

from __future__ import annotations

import re

# A non-empty run of [A-Za-z0-9_] — the db_id / SQL-identifier charset contract.
_IDENTIFIER_RE = re.compile(r"[A-Za-z0-9_]+")


def is_valid_identifier(name: str) -> bool:
    """True iff ``name`` is a non-empty string of only ``[A-Za-z0-9_]``.

    The db_id / SQL-identifier charset contract enforced by ``SQLEnvironment`` and
    required of any table name interpolated into raw SQL. Empty string -> False.
    """
    return bool(_IDENTIFIER_RE.fullmatch(name))


def quote_ident(name: str) -> str:
    """Double-quote a SQL identifier, escaping any embedded double-quote.

    ``a"b`` -> ``"a""b"``. The returned string INCLUDES the surrounding quotes.
    """
    return '"' + name.replace('"', '""') + '"'