"""informix-db — pure-Python driver for IBM Informix IDS over the SQLI wire protocol.

PEP 249 (DB-API 2.0) module surface. Phase 1 implements the connection
lifecycle (open + login + close) only; cursor/execute/fetch land in Phase 2.

Quick start::

    import informix_db

    conn = informix_db.connect(
        host="127.0.0.1", port=9088,
        user="informix", password="in4mix",
        database="sysmaster", server="informix",
    )
    conn.close()

For the full design, see ``docs/PROTOCOL_NOTES.md`` and
``docs/DECISION_LOG.md``.
"""

from __future__ import annotations

from importlib.metadata import PackageNotFoundError, version

from .connections import Connection
from .converters import (
    BlobLocator,
    ClobLocator,
    CollectionValue,
    IntervalYM,
    RowValue,
)
from .exceptions import (
    DatabaseError,
    DataError,
    Error,
    IntegrityError,
    InterfaceError,
    InternalError,
    NotSupportedError,
    OperationalError,
    ProgrammingError,
    Warning,
)

# PEP 249 module-level globals
apilevel = "2.0"
threadsafety = 1  # threads may share the module but not connections
paramstyle = "numeric"  # locked in DECISION_LOG.md — matches Informix ESQL/C

try:
    __version__ = version("informix-db")
except PackageNotFoundError:
    # Editable install or running uninstalled; fall back to a sentinel.
    __version__ = "0.0.0+local"

__all__ = [
    "BlobLocator",
    "ClobLocator",
    "CollectionValue",
    "Connection",
    "DataError",
    "DatabaseError",
    "Error",
    "IntegrityError",
    "InterfaceError",
    "InternalError",
    "IntervalYM",
    "NotSupportedError",
    "OperationalError",
    "ProgrammingError",
    "RowValue",
    "Warning",
    "__version__",
    "apilevel",
    "connect",
    "paramstyle",
    "threadsafety",
]


def connect(
    host: str,
    port: int = 9088,
    *,
    user: str,
    password: str | None,
    database: str | None = None,
    server: str = "informix",
    connect_timeout: float | None = None,
    read_timeout: float | None = None,
    keepalive: bool = False,
    client_locale: str = "en_US.8859-1",
    env: dict[str, str] | None = None,
    autocommit: bool = False,
) -> Connection:
    """Open a connection to an Informix server.

    The ``server`` argument is the Informix DBSERVERNAME the listener
    identifies itself as (default ``"informix"`` matches the IBM
    Developer Edition Docker image). It's distinct from ``host`` (which
    is the network address) and from ``database`` (which is the
    database name to open after login).

    ``database`` may be ``None`` to log in without selecting a database;
    the server still requires a successful login for this to work.
    """
    return Connection(
        host=host,
        port=port,
        user=user,
        password=password,
        database=database,
        server=server,
        connect_timeout=connect_timeout,
        read_timeout=read_timeout,
        keepalive=keepalive,
        client_locale=client_locale,
        env=env,
        autocommit=autocommit,
    )