Endpoint

class RequestMethod(enum.Enum):
    """Describing the different request types primarily for selecting request methods."""

    GET = enum.auto()
    POST = enum.auto()
    PUT = enum.auto()
    DELETE = enum.auto()
    PATCH = enum.auto()

class TogglEndpoint(ABC, Generic[T]):
    """Base class with basic functionality for all API requests.

    Attributes:
        BASE_ENDPOINT: Base URL of the Toggl API.
        HEADERS: Default headers that the API requires for most endpoints.
        client: Httpx client that is used for making requests to the API.

    Params:
        auth: Authentication for the client.
        client: Optional client to be passed to be used for requests. Useful
            when a global client is used and needs to be recycled.
        timeout: How long it takes for the client to timeout. Keyword Only.
            Defaults to 10 seconds.
        re_raise: Whether to raise all HTTPStatusError errors and not handle them
            internally. Keyword Only.
        retries: Max retries to attempt if the server returns a *5xx* status_code.
            Has no effect if re_raise is `True`. Keyword Only.
    """

    BASE_ENDPOINT: ClassVar[str] = "https://api.track.toggl.com/api/v9/"
    HEADERS: Final[Headers] = Headers({"content-type": "application/json"})
    MODEL: type[T] | None = None

    __slots__ = ("client", "re_raise", "retries", "workspace_id")

    def __init__(
        self,
        auth: BasicAuth,
        *,
        client: Client | None = None,
        timeout: Timeout | int = 10,
        re_raise: bool = False,
        retries: int = 3,
    ) -> None:
        self.re_raise = re_raise
        self.retries = max(0, retries)

        # NOTE: USES BASE_ENDPOINT instead of endpoint property for base_url
        # as current httpx concatenation is causing appended slashes.
        self.client = client = client or Client()
        client.auth = auth
        client.base_url = self.BASE_ENDPOINT  # type: ignore[assignment] # NOTE: Setter accepts strings.
        client.timeout = timeout if isinstance(timeout, Timeout) else Timeout(timeout)

        atexit.register(self.client.close)

    def _request_handle_error(
        self,
        response: Response,
        body: dict[str, Any] | list[dict[str, Any]] | None,
        headers: Headers | None,
        method: RequestMethod,
        parameters: str,
        *,
        raw: bool,
        retries: int,
    ) -> T | list[T] | Response | None:
        msg = "Request failed with status code %s: %s"
        log.error(msg, response.status_code, response.text)

        if not self.re_raise and codes.is_server_error(response.status_code) and retries:
            delay = random.randint(1, 5)
            retries -= 1
            log.error(
                ("Status code %s is a server error. Retrying request in %s seconds. There are %s retries left."),
                response.status_code,
                delay,
                retries,
            )
            # NOTE: According to https://engineering.toggl.com/docs/#generic-responses
            time.sleep(delay)
            return TogglEndpoint.request(
                self,
                parameters,
                headers,
                body,
                method,
                raw=raw,
                retries=retries,
            )

        return response.raise_for_status()

    def _process_response(
        self,
        response: Response,
        *,
        raw: bool,
    ) -> T | list[T] | Response | None:
        try:
            data = response if raw else response.json()
        except ValueError:
            return None

        if self.MODEL is None or raw:
            return data

        if isinstance(data, list):
            data = self.process_models(data)
        elif isinstance(data, dict):
            data = self.MODEL.from_kwargs(**data)

        return data

    def _build_request(
        self,
        parameters: str,
        headers: Headers | None,
        body: dict[str, Any] | list[dict[str, Any]] | None,
        method: RequestMethod,
    ) -> Request:
        url = self.BASE_ENDPOINT + parameters
        headers = headers or self.HEADERS

        requires_body = method not in {RequestMethod.DELETE, RequestMethod.GET}
        return self.client.build_request(
            method.name.lower(),
            url,
            headers=headers,
            json=body if requires_body else None,
        )

    def request(
        self,
        parameters: str,
        headers: Headers | None = None,
        body: dict[str, Any] | list[dict[str, Any]] | None = None,
        method: RequestMethod = RequestMethod.GET,
        *,
        raw: bool = False,
        retries: int | None = None,
    ) -> T | list[T] | Response | None:
        """Request & handle data from the Toggl API.

        Args:
            parameters (str): Request parameters with the endpoint excluded.
                Will concate with the endpoint property.
            headers (dict, optional): Custom request headers. Defaults to
                class property if set to None.
            body (dict | list, optional): Request body JSON data for specifying info.
                Defaults to None. Only used with none-GET or DELETE requests.
            method (RequestMethod): Request method to select. Defaults to GET.
            raw (bool): Whether to use the raw data. Defaults to False.
            retries (int): For recursive calls if the server fails multiple times.

        Raises:
            HTTPStatusError: If the request is not a success.

        Returns:
            Response data or None if request does not return any data.
        """
        if retries is None:
            retries = self.retries

        request = self._build_request(parameters, headers, body, method)
        response = self.client.send(request)

        if codes.is_error(response.status_code):
            return self._request_handle_error(
                response,
                body,
                headers,
                method,
                parameters,
                raw=raw,
                retries=retries,
            )

        return self._process_response(response, raw=raw)

    @classmethod
    def process_models(cls, data: list[dict[str, Any]]) -> list[T]:
        from_kwargs = cast("type[T]", cls.MODEL).from_kwargs
        return [from_kwargs(**mdl) for mdl in data]

    @staticmethod
    def api_status() -> bool:
        """Verify that the Toggl API is up.

        Returns:
            True if the API is up.
        """
        try:
            result = httpx.get(
                "https://api.track.toggl.com/api/v9/status",
            ).json()
        except (HTTPStatusError, JSONDecodeError):
            log.critical("Failed to get a response from the Toggl API!")
            log.exception("%s")
            return False

        return bool(result) and result.get("status") == "OK"

class TogglCachedEndpoint(TogglEndpoint[T]):
    """Abstract cached endpoint for requesting toggl API data to disk.

    See parent endpoint for more details.

    Params:
        auth: Authentication for the client.
        cache: Cache object for caching toggl API data to disk. Builtin cache
            types are JSONCache and SqliteCache.
        client: Optional client to be passed to be used for requests. Useful
            when a global client is used and needs to be recycled.
        timeout: How long it takes for the client to timeout. Keyword Only.
            Defaults to 10 seconds.
        re_raise: Whether to raise all HTTPStatusError errors and not handle them
            internally. Keyword Only.
        retries: Max retries to attempt if the server returns a *5xx* status_code.
            Has no effect if re_raise is `True`. Keyword Only.

    Attributes:
        cache: Cache object the endpoint will use for storing models. Assigns
            itself as the parent automatically.

    Methods:
        request: Overriden method that implements the cache into the request chain.
        load_cache: Method for loading cache into memory.
        save_cache: Method for saving cache to disk. Ignored if expiry is set
            to 0 seconds.
        query: Wrapper method for accessing querying capabilities within the
            assigned cache.
    """

    __slots__ = ("_cache",)

    def __init__(
        self,
        auth: BasicAuth,
        cache: TogglCache[T] | None = None,
        *,
        client: Client | None = None,
        timeout: Timeout | int = 10,
        re_raise: bool = False,
        retries: int = 3,
    ) -> None:
        super().__init__(
            auth=auth,
            client=client,
            timeout=timeout,
            re_raise=re_raise,
            retries=retries,
        )
        self.cache = cache

    def request(  # type: ignore[override]
        self,
        parameters: str,
        headers: Headers | None = None,
        body: dict[str, Any] | list[Any] | None = None,
        method: RequestMethod = RequestMethod.GET,
        *,
        refresh: bool = False,
        raw: bool = False,
    ) -> T | list[T] | Response | None:
        """Overridden request method with builtin cache.

        Args:
            parameters: Request parameters with the endpoint excluded.
            headers: Request headers. Custom headers can be added here.
            body: Request body for GET, POST, PUT, PATCH requests.
                Defaults to None.
            method: Request method. Defaults to GET.
            refresh: Whether to refresh the cache or not. Defaults to False.
            raw (bool): Whether to use the raw data. Defaults to False.

        Raises:
            HTTPStatusError: If the request is not a success.

        Returns:
            Toggl API response data processed into TogglClass objects or not
                depending on arguments.
        """
        data = self.load_cache() if self.cache and self.MODEL is not None else None
        if data and not refresh:
            log.info(
                "Loading request %s%s data from cache.",
                self.BASE_ENDPOINT,
                parameters,
                extra={"body": body, "headers": headers, "method": method},
            )
            return cast("list[T]", data)

        response = super().request(
            parameters,
            method=method,
            headers=headers,
            body=body,
            raw=raw,
        )
        if raw:
            return response

        if response is None or method == RequestMethod.DELETE:
            return None

        if self.cache and self.MODEL is not None:
            self.save_cache(response, method)  # type: ignore[arg-type]

        return response

    def load_cache(self) -> Iterable[T]:
        """Direct loading method for retrieving all models from cache.

        Raises:
            NoCacheAssignedError: If no cache is assigned to the endpoint.

        Returns:
            An iterable of models that have been previously saved.
        """
        if self.cache is None:
            raise NoCacheAssignedError

        return self.cache.load()

    def save_cache(
        self,
        response: list[T] | T,
        method: RequestMethod,
    ) -> None:
        """Direct saving method for retrieving all models from cache.

        Args:
            response: A list of values or single value to save.
            method: To method to use when updating the cache.

        Raises:
            NoCacheAssignedError: If no cache is assigned to the endpoint.
        """
        if self.cache is None:
            raise NoCacheAssignedError
        if isinstance(self.cache.expire_after, timedelta) and not self.cache.expire_after.total_seconds():
            log.debug(
                "Cache is set to immediately expire!",
                extra={"expiry": self.cache.expire_after},
            )
            return None
        return self.cache.save(response, method)

    def query(
        self,
        *query: TogglQuery[Any],
        distinct: bool = False,
    ) -> list[T]:
        """Query wrapper for the cache method.

        If the original data structure is required use the query on the
        *.cache* attribute instead.

        Args:
            *query: An arbitary amount of queries to match the models to.
            distinct: A boolean that remove duplicate values if present.

        Raises:
            NoCacheAssignedError: If the current cache is set to None.

        Returns:
            A list objects depending on the endpoint.
        """
        if self.cache is None:
            raise NoCacheAssignedError
        return list(self.cache.query(*query, distinct=distinct))

    @property
    def cache(self) -> TogglCache[T] | None:
        return self._cache

    @cache.setter
    def cache(self, value: TogglCache[T] | None) -> None:
        self._cache = value
        if self.cache and self.cache._parent is not self:  # noqa: SLF001
            self.cache.parent = self