"""A-Alpha Bio Data Portal client for accessing AlphaSeq data blocks.

Python API:
    from aablocks import list_blocks, get_data, get_details, get_datacard, login, logout

    # List all data blocks (as pandas DataFrame by default)
    df = list_blocks()

    # Get data as pandas DataFrame
    df = get_data("ab1001", format="pandas")

    # Get data block metadata
    details = get_details("ab1001")

    # Get data block datacard
    datacard = get_datacard("ab1001")

CLI:
    aablocks login           Log in to the Data Portal
    aablocks logout         Log out and clear cached credentials
    aablocks list            List all accessible data blocks
    aablocks details <id>    Show data block metadata
    aablocks datacard <id>   Show data block datacard
    aablocks get <id>        Download data block data
    aablocks structures <id> Download structure files as zip
    aablocks config          Get or set configuration options

Configuration:
    Settings stored in ~/.aab/config.json
    Tokens cached in ~/.aab/token.json (per environment)
    Logs written to ~/.aab/logs/<domain>/activity.log
"""

__version__ = "0.1.23"

from .auth import login, logout
from .config import set_config
from .client import (
    DataBlock,
    download_structure,
    download_structures,
    get_data,
    get_datacard,
    get_details,
    get_schema,
    list_blocks,
    pandas_schema_to_polars,
)

__all__ = [
    "DataBlock",
    "download_structure",
    "download_structures",
    "get_data",
    "get_datacard",
    "get_details",
    "get_schema",
    "list_blocks",
    "login",
    "logout",
    "pandas_schema_to_polars",
    "set_config",
]

# Function grouping for generated API documentation.
# Each tuple: (section name, section description, list of function names)
DOC_GROUPS = [
    (
        "Authentication",
        "Uses OAuth2 with PKCE via AWS Cognito. Tokens cached in `~/.aab/token.json`.",
        ["login", "logout"],
    ),
    (
        "Data Block Discovery",
        "",
        ["list_blocks", "get_details", "get_datacard"],
    ),
    (
        "Data Access",
        "",
        [
            "get_data",
            "get_schema",
            "download_structures",
            "download_structure",
            "pandas_schema_to_polars",
        ],
    ),
    (
        "Configuration",
        "Config stored in `~/.aab/config.json`.",
        ["set_config"],
    ),
]
