import requests
from django.conf import settings

_BASE = 'https://perenual.com/api'


class PerenualError(Exception):
    pass


def search_species(query):
    """Query Perenual species-list endpoint.

    Returns list of result dicts on success.
    Raises PerenualError if the API is unreachable or rate-limited.
    Returns [] if no API key is configured.
    """
    if not settings.PERENUAL_API_KEY:
        return []
    try:
        resp = requests.get(
            f'{_BASE}/species-list',
            params={'q': query, 'key': settings.PERENUAL_API_KEY},
            timeout=10,
        )
        resp.raise_for_status()
        return resp.json().get('data', [])
    except requests.Timeout:
        raise PerenualError('Perenual API timed out — try again in a moment.')
    except requests.HTTPError as e:
        if e.response is not None and e.response.status_code == 429:
            raise PerenualError('Perenual API rate limit reached — try again later.')
        raise PerenualError(f'Perenual API error ({e.response.status_code if e.response else "?"}).')
    except Exception:
        raise PerenualError('Could not reach Perenual API.')