python-corekit 0.1.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

corekit/exceptions/base.py

@@ -1,26 +1,104 @@
 """
 Base exception types.
+
+Every corekit exception is one of two shapes:
+
+* ``InternalCoreException`` -- backend-only. ``message``/``error`` are for
+  logs and debugging and must never reach an end user; there is no field to
+  put user-facing copy in, so there is nothing to leak by accident.
+* ``PublicCoreException`` -- also carries ``user_message``, pre-written copy
+  that *is* safe to show externally. ``message``/``error`` stay backend-only
+  even here; only ``user_message`` should ever be serialized to a client.
+
+Both carry ``retryable``, so a caller (or whatever eventually surfaces the
+error) can tell whether trying again is worth it without re-deriving that
+from a status code every time.
+
+``CoreException`` itself is abstract -- it exists to hold the shared fields,
+not to be raised. Raise one of the two subclasses above (or a subclass of
+those, like ``CoreHTTPException`` and the typed HTTP errors in ``corekit.http``).
 """
 
+from abc import ABC
 from typing import Any
 
 from fastapi import HTTPException
 
-__all__ = ["CustomException", "CustomHTTPException", "ExponentialBackoffTimeoutException"]
+from corekit.exceptions.enum import Retryability
+
+__all__ = [
+    "CoreException",
+    "CoreHTTPException",
+    "RetryableCoreHTTPException",
+    "NonRetryableCoreHTTPException",
+    "ExponentialBackoffTimeoutException",
+    "InternalCoreException",
+    "PublicCoreException",
+]
 
 
-class CustomException(Exception):
+class CoreException(Exception, ABC):
     """
-    Base for corekit exceptions, carrying optional error context.
+    Abstract base carrying the fields every corekit exception shares.
     """
 
-    def __init__(self, message: str, error: str | None = None) -> None:
+    def __init__(
+        self,
+        message: str,
+        *,
+        retryable: Retryability = Retryability.UNKNOWN,
+        error: str | None = None,
+    ) -> None:
+        if type(self) is CoreException:
+            raise TypeError("CoreException is abstract -- raise InternalCoreException or PublicCoreException")
         super().__init__(message)
         self.message = message
         self.error = error
+        self.retryable = retryable
+
+    def for_log(self) -> str:
+        """
+        Backend text for logs.
+
+        ``str(self)`` on a public exception is the user-facing copy, so a log
+        line of ``str(exc)`` drops ``message``. This always returns the
+        backend message, and the separate error detail when one was given.
+        """
+        if self.error:
+            return f"{self.message} ({self.error})"
+        return self.message
+
+
+class InternalCoreException(CoreException):
+    """
+    Backend-only exception. Never expose ``message`` or ``error`` to a user.
+    """
+
+
+class PublicCoreException(CoreException):
+    """
+    Exception with pre-written copy that is safe to show an end user.
+
+    ``message``/``error`` remain backend-only, for logs; ``user_message`` is
+    the only field on this exception meant to leave the backend.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        user_message: str,
+        *,
+        retryable: Retryability = Retryability.UNKNOWN,
+        error: str | None = None,
+    ) -> None:
+        super().__init__(message, retryable=retryable, error=error)
+        self.user_message = user_message
+
+    def __str__(self) -> str:
+        return self.user_message
 
 
-class ExponentialBackoffTimeoutException(CustomException):
+class ExponentialBackoffTimeoutException(InternalCoreException):
     """
     Raised when a retry loop exhausts its attempts without succeeding.
     """
@@ -28,18 +106,69 @@ class ExponentialBackoffTimeoutException(CustomException):
     def __init__(self, attempts: int, error: str | None = None) -> None:
         super().__init__(
             message=f"Exponential Backoff timed out after {attempts} attempts",
+            retryable=Retryability.NON_RETRYABLE,
             error=error,
         )
         self.attempts = attempts
 
 
-class CustomHTTPException(HTTPException):
+class CoreHTTPException(HTTPException, PublicCoreException):
+    """
+    FastAPI HTTPException that is also a PublicCoreException.
+
+    ``detail`` (FastAPI's client-facing field) and ``user_message`` are kept
+    in sync -- pass either one. ``message``/``error`` default to ``detail``
+    when omitted, since most call sites raising this directly have nothing
+    more specific to log.
+    """
+
+    def __init__(
+        self,
+        *,
+        status_code: int,
+        detail: str | None = None,
+        message: str | None = None,
+        user_message: str | None = None,
+        retryable: Retryability = Retryability.UNKNOWN,
+        error: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        resolved_user_message = user_message or detail
+        if not resolved_user_message:
+            raise ValueError("CoreHTTPException requires detail= or user_message=")
+
+        resolved_message = message or resolved_user_message
+        HTTPException.__init__(self, status_code=status_code, detail=resolved_user_message, **kwargs)
+        PublicCoreException.__init__(
+            self,
+            resolved_message,
+            resolved_user_message,
+            retryable=retryable,
+            error=error,
+        )
+
+    def __str__(self) -> str:
+        # HTTPException.__str__ is "404: detail" and sits ahead of
+        # PublicCoreException in the MRO. The public contract is that only
+        # user_message leaves the backend.
+        return self.user_message
+
+
+class RetryableCoreHTTPException(CoreHTTPException):
+    """
+    HTTP error where trying the same request again may succeed.
+    """
+
+    def __init__(self, **kwargs: Any) -> None:
+        kwargs.setdefault("retryable", Retryability.RETRYABLE)
+        super().__init__(**kwargs)
+
+
+class NonRetryableCoreHTTPException(CoreHTTPException):
     """
-    FastAPI HTTPException that also accepts ``message=`` as an alias for ``detail=``.
+    HTTP error where the same request will fail again until something else changes.
     """
 
     def __init__(self, **kwargs: Any) -> None:
-        message = kwargs.pop("message", None)
-        if message:
-            kwargs["detail"] = message
+        kwargs.setdefault("retryable", Retryability.NON_RETRYABLE)
         super().__init__(**kwargs)

corekit/exceptions/enum.py

@@ -0,0 +1,17 @@
+"""
+Enums used by corekit exceptions.
+"""
+
+from corekit.schemas.enum import StringEnum
+
+__all__ = ["Retryability"]
+
+
+class Retryability(StringEnum):
+    """
+    Whether retrying the operation that raised an exception can help.
+    """
+
+    RETRYABLE = "retryable"
+    NON_RETRYABLE = "non_retryable"
+    UNKNOWN = "unknown"

corekit/exceptions/types.py

@@ -2,16 +2,16 @@
 Type aliases for exception classes.
 
 These name the *class*, for signatures that accept an exception type rather than
-an instance -- ``def handle(exc: CustomExceptionType) -> None``.
+an instance -- ``def handle(exc: CoreExceptionType) -> None``.
 
 ``type(X)`` returns X's metaclass, which is ``type`` for an ordinary class and
 carries no information about X. ``type[X]`` is the subscript form these need.
 """
 
-from corekit.exceptions.base import CustomException, CustomHTTPException
+from corekit.exceptions.base import CoreException, CoreHTTPException
 
-__all__ = ["ArbitraryCustomExceptionType", "CustomExceptionType", "CustomHTTPExceptionType"]
+__all__ = ["ArbitraryCoreExceptionType", "CoreExceptionType", "CoreHTTPExceptionType"]
 
-CustomExceptionType = type[CustomException]
-CustomHTTPExceptionType = type[CustomHTTPException]
-ArbitraryCustomExceptionType = CustomExceptionType | CustomHTTPExceptionType
+CoreExceptionType = type[CoreException]
+CoreHTTPExceptionType = type[CoreHTTPException]
+ArbitraryCoreExceptionType = CoreExceptionType | CoreHTTPExceptionType

corekit/files/__init__.py

@@ -8,10 +8,9 @@ File reading and writing, with format handled by the manager.
 ``_serialize`` and ``_deserialize`` for its format.
 """
 
-from corekit.files.base import FileContent, FileManager
-from corekit.files.enum import FileError, FileMode
+from corekit.files.base import FileContent, FileError, FileManager
+from corekit.files.enum import FileMode
 from corekit.files.json import JsonFileManager
-from corekit.files.pickle import PickleFileManager
 from corekit.files.toml import TomlFileManager
 
 __all__ = [
@@ -20,6 +19,5 @@ __all__ = [
     "FileManager",
     "FileMode",
     "JsonFileManager",
-    "PickleFileManager",
     "TomlFileManager",
 ]

corekit/files/base.py

@@ -1,10 +1,23 @@
 from typing import Any, BinaryIO, Iterator, TextIO, Union
 
-from corekit.files.enum import FileError, FileMode
+from corekit.exceptions import InternalCoreException, Retryability
+from corekit.files.enum import FileMode
 
 FileContent: type[str | bytes] = Union[str, bytes]
 
 
+class FileError(InternalCoreException):
+    """
+    Raised when a file manager is used in the wrong open/closed state.
+    """
+
+    NOT_OPEN = "File is not open"
+    OPEN = "File is open"
+
+    def __init__(self, message: str, *, error: str | None = None) -> None:
+        super().__init__(message, retryable=Retryability.NON_RETRYABLE, error=error)
+
+
 class FileManager:
     def __init__(
         self,
@@ -36,7 +49,7 @@ class FileManager:
 
     def _verify_file_status(self, should_be_open: bool) -> None:
         if self.is_open != should_be_open:
-            raise ValueError(FileError.NOT_OPEN if should_be_open else FileError.OPEN)  # FIXME: raise custom exception
+            raise FileError(FileError.NOT_OPEN if should_be_open else FileError.OPEN)
 
     # ===== File Opening/Closing Methods =====
     def _open(self) -> None:

corekit/files/enum.py

@@ -23,8 +23,3 @@ class FileMode(StringEnum):
         if self in {FileMode.READ, FileMode.READ_BINARY}:
             return False
         return True
-
-
-class FileError(StringEnum):
-    NOT_OPEN = "File is not open"
-    OPEN = "File is open"

corekit/files/json.py

@@ -1,7 +1,7 @@
 import json as _json
-from typing import Any
+from typing import Any, Iterator
 
-from corekit.files.base import FileContent, FileManager
+from corekit.files.base import FileContent, FileError, FileManager
 
 
 class JsonFileManager(FileManager):
@@ -10,3 +10,17 @@ class JsonFileManager(FileManager):
 
     def _deserialize(self, content: FileContent) -> Any:
         return _json.loads(content)
+
+    def read(self, size: int = -1) -> Any:
+        """
+        Read and parse the whole document. Partial reads are refused.
+        """
+        if size != -1:
+            raise FileError("JsonFileManager refuses partial reads; JSON must be parsed as a whole document.")
+        return super().read(size)
+
+    def readline(self) -> Any:
+        raise FileError("JsonFileManager cannot readline; JSON is not line-oriented.")
+
+    def stream(self) -> Iterator[Any]:
+        raise FileError("JsonFileManager cannot stream; JSON must be parsed as a whole document.")

corekit/http/__init__.py

@@ -0,0 +1,51 @@
+"""
+HTTP client building blocks.
+
+``BaseHttpClient`` is the transport; ``BaseApiClient`` is the strict API
+wrapper. ``ExponentialBackoff`` is the retry policy behind the client and is
+useful on its own for any operation that should back off rather than hammer.
+"""
+
+from corekit.http.api import BaseApiClient
+from corekit.http.client import BaseHttpClient
+from corekit.http.exceptions import (
+    BadGatewayException,
+    BadRequestException,
+    ConflictErrorException,
+    ForbiddenException,
+    GatewayTimeoutException,
+    InternalServerErrorException,
+    NotFoundException,
+    ServiceUnavailableException,
+    TooManyRequestsException,
+    UnauthorizedException,
+    UnprocessableEntityException,
+    UnsupportedMediaTypeException,
+    UnsupportedMethodError,
+    URLMismatchError,
+)
+from corekit.http.exponential_backoff import ExponentialBackoff
+from corekit.http.response import BaseApiResponse
+from corekit.http.status import HTTPStatusCode
+
+__all__ = [
+    "BadGatewayException",
+    "BadRequestException",
+    "BaseApiClient",
+    "BaseApiResponse",
+    "BaseHttpClient",
+    "ConflictErrorException",
+    "ExponentialBackoff",
+    "ForbiddenException",
+    "GatewayTimeoutException",
+    "HTTPStatusCode",
+    "InternalServerErrorException",
+    "NotFoundException",
+    "ServiceUnavailableException",
+    "TooManyRequestsException",
+    "UnauthorizedException",
+    "UnprocessableEntityException",
+    "UnsupportedMediaTypeException",
+    "UnsupportedMethodError",
+    "URLMismatchError",
+]

corekit/http/api.py

@@ -0,0 +1,24 @@
+"""
+API clients: a ``BaseHttpClient`` that always talks to one origin.
+"""
+
+from typing import Any
+
+from corekit.http.client import BaseHttpClient
+
+__all__ = ["BaseApiClient"]
+
+
+class BaseApiClient(BaseHttpClient):
+    """
+    Base for API clients. Override ``base_url`` and, usually, ``headers``.
+
+    Strict by default, so an absolute URL that does not share ``base_url`` is
+    a bug rather than a request to somewhere else. ``base_url`` must be
+    available during ``__init__`` — a property on the subclass is the usual way.
+    """
+
+    def __init__(self, *args: Any, strict: bool = True, **kwargs: Any) -> None:
+        super().__init__(*args, strict=strict, **kwargs)
+        if not self.base_url:
+            raise ValueError("BaseApiClient requires a non-empty base_url")

corekit/http/client.py

@@ -1,7 +1,10 @@
 """
 A small HTTP client with retries.
 
-Subclass and give it a base URL::
+``BaseHttpClient`` is the transport: relative paths, optional strict URL
+checking, and retries for statuses the typed HTTP exceptions mark as
+retryable. Subclass ``BaseApiClient`` when the client always talks to one
+API and a foreign absolute URL should be a bug.
 
     class GithubClient(BaseApiClient):
         '''
@@ -17,46 +20,79 @@ Subclass and give it a base URL::
             return {"Authorization": f"Bearer {self.token}"}
 
     client = GithubClient()
-    response = client.get("/user")          # or await client.async_get("/user")
+    response = client.get("/user")          # or await client.get("/user")
     response.data["login"]
 
 Every response comes back as a ``BaseApiResponse``, so callers see one shape
-regardless of what the endpoint returned. Requests that fail with a retryable
-status are retried with exponential backoff.
+regardless of what the endpoint returned.
 """
 
 from http import HTTPMethod
 from typing import Any
-from urllib.parse import urljoin
+from urllib.parse import urljoin, urlsplit, urlunsplit
 
 import httpx
 
+from corekit.concurrency.decorators import allow_sync
+from corekit.http.exceptions import RETRYABLE_STATUS_CODES, UnsupportedMethodError, URLMismatchError
 from corekit.http.exponential_backoff import ExponentialBackoff
 from corekit.http.response import BaseApiResponse
+from corekit.http.status import HTTPStatusCode
 from corekit.observability.benchmarkable import Benchmarkable
 
-__all__ = ["BaseApiClient", "URLMismatchError"]
+__all__ = ["BaseHttpClient"]
 
-# Statuses worth retrying: the server is busy or briefly unavailable, so the
-# same request may well succeed shortly. A 4xx other than 429 will not.
-RETRYABLE_STATUS_CODES = frozenset({429, 500, 502, 503, 504})
 
-
-class URLMismatchError(Exception):
+def _without_query(url: str) -> str:
     """
-    Raised when an absolute URL is passed that does not share the base URL.
+    Drop the query string before a retry warning is logged.
     """
+    parts = urlsplit(url)
+    return urlunsplit((parts.scheme, parts.netloc, parts.path, "", ""))
+
 
+_DEFAULT_METHODS = frozenset(
+    {
+        HTTPMethod.GET,
+        HTTPMethod.POST,
+        HTTPMethod.PUT,
+        HTTPMethod.PATCH,
+        HTTPMethod.DELETE,
+    }
+)
 
-class BaseApiClient(Benchmarkable):
+
+class BaseHttpClient(Benchmarkable):
     """
-    Base for API clients. Override ``base_url`` and, usually, ``headers``.
+    Base for HTTP clients. Override ``base_url`` and, usually, ``headers``.
+
+    ``strict=False`` accepts a foreign absolute URL as-is. ``BaseApiClient``
+    turns that into an error.
     """
 
-    def __init__(self, retries: int = 3, timeout: float = 30.0) -> None:
+    def __init__(
+        self,
+        retries: int = 3,
+        timeout: float = 30.0,
+        strict: bool = False,
+        base_delay: float = 1,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
         super().__init__()
         self.retries = retries
         self.timeout = timeout
+        self.strict = strict
+        self.base_delay = base_delay
+        # Optional pool. Left unset by default: @allow_sync runs sync calls on a
+        # throwaway loop, and an AsyncClient cannot move between loops.
+        self._http_client = http_client
+
+    @property
+    def supported_methods(self) -> frozenset[HTTPMethod]:
+        """
+        HTTP methods this client will send. Override to narrow or extend the set.
+        """
+        return _DEFAULT_METHODS
 
     @property
     def headers(self) -> dict[str, str]:
@@ -77,16 +113,18 @@ class BaseApiClient(Benchmarkable):
         Resolve a path against the base URL, accepting an absolute URL that
         already matches it.
         """
-        if url.startswith(self.base_url):
+        if self.base_url and url.startswith(self.base_url):
             return url
         if url.startswith("http"):
-            raise URLMismatchError(f"URL {url} does not match base URL {self.base_url}")
+            if self.strict:
+                raise URLMismatchError(url, self.base_url)
+            return url
         return urljoin(self.base_url, url)
 
     @staticmethod
-    def _to_response(raw: Any) -> BaseApiResponse:
+    def _to_response(raw: httpx.Response) -> BaseApiResponse:
         """
-        Normalize an httpx response into a BaseApiResponse.
+        Normalize a httpx response into a BaseApiResponse.
 
         The body is decoded as JSON when it parses, and left as text otherwise,
         so a caller never has to guard against a non-JSON error page.
@@ -99,78 +137,67 @@ class BaseApiClient(Benchmarkable):
             data = {"data": data}
 
         return BaseApiResponse(
-            status_code=raw.status_code,
+            status_code=HTTPStatusCode.coerce(raw.status_code),
             text=raw.text,
             data=data,
             headers=dict(raw.headers),
             cookies=dict(raw.cookies),
         )
 
-    def _new_backoff(self) -> ExponentialBackoff:
-        return ExponentialBackoff(retries=self.retries)
-
-    def request(self, method: HTTPMethod, url: str, **kwargs: Any) -> BaseApiResponse:
-        """
-        Send a request, retrying retryable statuses.
-        """
-
-        target = self._build_url(url)
-        backoff = self._new_backoff()
-
-        while True:
-            with httpx.Client(timeout=self.timeout) as client:
-                raw = client.request(str(method), target, headers=self.headers, **kwargs)
-
-            if raw.status_code not in RETRYABLE_STATUS_CODES or backoff.did_timeout():
-                return self._to_response(raw)
-
-            self.warning(f"{method} {target} returned {raw.status_code}; retrying")
-            backoff.wait()
-
-    async def async_request(self, method: HTTPMethod, url: str, **kwargs: Any) -> BaseApiResponse:
+    async def request(self, method: HTTPMethod, url: str, **kwargs: Any) -> BaseApiResponse:
         """
         Send a request asynchronously, retrying retryable statuses.
         """
+        if method not in self.supported_methods:
+            raise UnsupportedMethodError(method)
 
         target = self._build_url(url)
-        backoff = self._new_backoff()
-
+        headers = dict(self.headers)
+        extra_headers = kwargs.pop("headers", None)
+        if extra_headers:
+            headers.update(extra_headers)
+        # Fresh each request: ExponentialBackoff keeps its own attempt count.
+        backoff = ExponentialBackoff(retries=self.retries, base_delay=self.base_delay)
+
+        if self._http_client is not None:
+            return await self._exchange(self._http_client, method, target, headers, backoff, kwargs)
+
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            return await self._exchange(client, method, target, headers, backoff, kwargs)
+
+    async def _exchange(
+        self,
+        client: httpx.AsyncClient,
+        method: HTTPMethod,
+        target: str,
+        headers: dict[str, str],
+        backoff: ExponentialBackoff,
+        kwargs: dict[str, Any],
+    ) -> BaseApiResponse:
         while True:
-            async with httpx.AsyncClient(timeout=self.timeout) as client:
-                raw = await client.request(str(method), target, headers=self.headers, **kwargs)
-
+            raw = await client.request(str(method), target, headers=headers, **kwargs)
             if raw.status_code not in RETRYABLE_STATUS_CODES or backoff.did_timeout():
                 return self._to_response(raw)
 
-            self.warning(f"{method} {target} returned {raw.status_code}; retrying")
+            self.warning(f"{method} {_without_query(target)} returned {raw.status_code}; retrying")
             await backoff.async_wait()
 
-    def get(self, url: str, **kwargs: Any) -> BaseApiResponse:
-        return self.request(HTTPMethod.GET, url, **kwargs)
-
-    def post(self, url: str, **kwargs: Any) -> BaseApiResponse:
-        return self.request(HTTPMethod.POST, url, **kwargs)
-
-    def put(self, url: str, **kwargs: Any) -> BaseApiResponse:
-        return self.request(HTTPMethod.PUT, url, **kwargs)
-
-    def patch(self, url: str, **kwargs: Any) -> BaseApiResponse:
-        return self.request(HTTPMethod.PATCH, url, **kwargs)
-
-    def delete(self, url: str, **kwargs: Any) -> BaseApiResponse:
-        return self.request(HTTPMethod.DELETE, url, **kwargs)
-
-    async def async_get(self, url: str, **kwargs: Any) -> BaseApiResponse:
-        return await self.async_request(HTTPMethod.GET, url, **kwargs)
+    @allow_sync
+    async def get(self, url: str, **kwargs: Any) -> BaseApiResponse:
+        return await self.request(HTTPMethod.GET, url, **kwargs)
 
-    async def async_post(self, url: str, **kwargs: Any) -> BaseApiResponse:
-        return await self.async_request(HTTPMethod.POST, url, **kwargs)
+    @allow_sync
+    async def post(self, url: str, **kwargs: Any) -> BaseApiResponse:
+        return await self.request(HTTPMethod.POST, url, **kwargs)
 
-    async def async_put(self, url: str, **kwargs: Any) -> BaseApiResponse:
-        return await self.async_request(HTTPMethod.PUT, url, **kwargs)
+    @allow_sync
+    async def put(self, url: str, **kwargs: Any) -> BaseApiResponse:
+        return await self.request(HTTPMethod.PUT, url, **kwargs)
 
-    async def async_patch(self, url: str, **kwargs: Any) -> BaseApiResponse:
-        return await self.async_request(HTTPMethod.PATCH, url, **kwargs)
+    @allow_sync
+    async def patch(self, url: str, **kwargs: Any) -> BaseApiResponse:
+        return await self.request(HTTPMethod.PATCH, url, **kwargs)
 
-    async def async_delete(self, url: str, **kwargs: Any) -> BaseApiResponse:
-        return await self.async_request(HTTPMethod.DELETE, url, **kwargs)
+    @allow_sync
+    async def delete(self, url: str, **kwargs: Any) -> BaseApiResponse:
+        return await self.request(HTTPMethod.DELETE, url, **kwargs)