# Helix Connect Python SDK
# Stream 3: SDKs & Developer Experience - Python SDK (Weeks 1-3)

"""
Helix Connect - Data Marketplace SDK

A Python SDK for interacting with the Helix Connect data marketplace.
Supports both data producers (uploading datasets) and data consumers (downloading datasets).

Example usage:

    # For Consumers
    from helix_connect import HelixConsumer

    consumer = HelixConsumer(
        aws_access_key_id="AKIA...",
        aws_secret_access_key="...",
        customer_id="uuid-here"
    )

    # List available datasets
    datasets = consumer.list_datasets()

    # Download a dataset
    consumer.download_dataset(dataset_id="dataset-123", output_path="./data.zip")

    # Poll for notifications
    consumer.poll_notifications(auto_download=True)


    # For Producers
    from helix_connect import HelixProducer

    producer = HelixProducer(
        aws_access_key_id="AKIA...",
        aws_secret_access_key="...",
        customer_id="uuid-here"
    )

    # Upload a dataset
    producer.upload_dataset(
        file_path="./dataset.zip",
        dataset_name="phone-numbers",
        description="Daily phone number dataset"
    )
"""

from __future__ import annotations

import warnings
from typing import TYPE_CHECKING

__version__ = "1.3.0"
__author__ = "Helix Tools"
__license__ = "MIT"

# Public API - always imported
from .consumer import HelixConsumer
from .producer import HelixProducer
from .exceptions import (
    HelixError,
    AuthenticationError,
    PermissionDeniedError,
    DatasetNotFoundError,
    RateLimitError,
    ConflictError,
    UploadError,
    DownloadError,
)

# Deprecation warning message for Admin functionality
_ADMIN_DEPRECATION_MSG = (
    "HelixAdmin is moving to a separate package 'helix-admin' in v2.0.0. "
    "Install: pip install git+https://github.com/helix-tools/helix-admin-sdk-python.git "
    "See MIGRATION_v2.md for details."
)

_ADMIN_EXCEPTION_DEPRECATION_MSG = (
    "{name} is moving to the 'helix-admin' package in v2.0.0. "
    "It will no longer be available from helix-connect. "
    "See MIGRATION_v2.md for details."
)

# For static type checking and IDE support (no runtime import)
if TYPE_CHECKING:
    from .admin import HelixAdmin
    from .exceptions import TokenGenerationError, ValidationError


# Deprecated names that trigger warnings on access
_DEPRECATED_ADMIN_NAMES = frozenset({"HelixAdmin"})
_DEPRECATED_EXCEPTION_NAMES = frozenset({"TokenGenerationError", "ValidationError"})


def __getattr__(name: str):
    """
    Lazy import with deprecation warnings for Admin-related imports.

    This handles:
    - from helix_connect import HelixAdmin
    - from helix_connect import TokenGenerationError, ValidationError

    Caches results in globals() to prevent duplicate warnings on repeated access.
    """
    if name in _DEPRECATED_ADMIN_NAMES:
        warnings.warn(
            _ADMIN_DEPRECATION_MSG,
            FutureWarning,
            stacklevel=2,
        )
        from .admin import HelixAdmin

        globals()[name] = HelixAdmin  # Cache to prevent duplicate warnings
        return HelixAdmin

    if name in _DEPRECATED_EXCEPTION_NAMES:
        warnings.warn(
            _ADMIN_EXCEPTION_DEPRECATION_MSG.format(name=name),
            FutureWarning,
            stacklevel=2,
        )
        from .exceptions import TokenGenerationError, ValidationError

        result = {
            "TokenGenerationError": TokenGenerationError,
            "ValidationError": ValidationError,
        }[name]
        globals()[name] = result  # Cache to prevent duplicate warnings
        return result

    raise AttributeError(f"module 'helix_connect' has no attribute '{name}'")


# Public API exports
# Note: HelixAdmin, TokenGenerationError, ValidationError are deprecated
# and will be removed in v2.0.0
__all__ = [
    # Core classes (public, stable)
    "HelixConsumer",
    "HelixProducer",
    # Exceptions (public, stable)
    "HelixError",
    "AuthenticationError",
    "PermissionDeniedError",
    "DatasetNotFoundError",
    "RateLimitError",
    "ConflictError",
    "UploadError",
    "DownloadError",
    # Deprecated - will be removed in v2.0.0
    # Access triggers FutureWarning
    "HelixAdmin",
    "TokenGenerationError",
    "ValidationError",
]
