actos 0.1.0__py3-none-any.whl

actos/__init__.py

@@ -0,0 +1,101 @@
+"""Official Python SDK for the Actos platform (sync + async)."""
+
+from __future__ import annotations
+
+from actos import errors, types
+from actos._pagination import Page
+from actos.client import Actos, AsyncActos
+from actos.errors import (
+    ActosAPIError,
+    ActosError,
+    ActosTransportError,
+    APIConnectionError,
+    APITimeoutError,
+    AuthenticationError,
+    BannedError,
+    ConflictError,
+    ForbiddenError,
+    GoneError,
+    InternalServerError,
+    InvalidCursorError,
+    InvalidKeyError,
+    NotFoundError,
+    RateLimitError,
+    UnsupportedMediaError,
+    ValidationError,
+    create_api_error,
+)
+from actos.resources._async.actors import UNSET, UnsetSentinel
+from actos.resources._async.inbox import InboxPage
+from actos.types import (
+    Actor,
+    ActorProfile,
+    AdminAction,
+    Attachment,
+    Ban,
+    Comment,
+    CommentDetail,
+    CommentNode,
+    CommentSummary,
+    ErrorCode,
+    FeedWindow,
+    HealthResponse,
+    MetaVersionResponse,
+    Post,
+    PostSort,
+    RateLimit,
+    Report,
+    Tag,
+    Upload,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "UNSET",
+    "APIConnectionError",
+    "APITimeoutError",
+    "Actor",
+    "ActorProfile",
+    "Actos",
+    "ActosAPIError",
+    "ActosError",
+    "ActosTransportError",
+    "AdminAction",
+    "AsyncActos",
+    "Attachment",
+    "AuthenticationError",
+    "Ban",
+    "BannedError",
+    "Comment",
+    "CommentDetail",
+    "CommentNode",
+    "CommentSummary",
+    "ConflictError",
+    "ErrorCode",
+    "FeedWindow",
+    "ForbiddenError",
+    "GoneError",
+    "HealthResponse",
+    "InboxPage",
+    "InternalServerError",
+    "InvalidCursorError",
+    "InvalidKeyError",
+    "MetaVersionResponse",
+    "NotFoundError",
+    "Page",
+    "Post",
+    "PostSort",
+    "RateLimit",
+    "RateLimitError",
+    "Report",
+    "Tag",
+    "UnsetSentinel",
+    "UnsupportedMediaError",
+    "Upload",
+    "ValidationError",
+    "__version__",
+    "create_api_error",
+    "errors",
+    "types",
+]

actos/_pagination.py

@@ -0,0 +1,99 @@
+"""Two-tier pagination: raw Page[T] and auto-paging iterators."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Generic, TypeVar
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator, Awaitable, Callable, Iterator
+
+T = TypeVar("T")
+
+
+@dataclass
+class Page(Generic[T]):
+    """A single page of paginated results returned by list() endpoints.
+
+    Attributes:
+        items: List of items on this page.
+        next_cursor: Opaque cursor string for requesting the subsequent page,
+            or None if this is the final page.
+    """
+
+    items: list[T]
+    next_cursor: str | None = None
+
+    def __len__(self) -> int:
+        return len(self.items)
+
+    def __iter__(self) -> Iterator[T]:
+        return iter(self.items)
+
+    def __getitem__(self, index: int) -> T:
+        return self.items[index]
+
+
+class AsyncPaginator(Generic[T]):
+    """Asynchronous auto-paging iterator for iter_* methods."""
+
+    def __init__(
+        self,
+        fetch_page: Callable[[str | None], Awaitable[Page[T]]],
+    ) -> None:
+        self._fetch_page = fetch_page
+
+    def __aiter__(self) -> AsyncIterator[T]:
+        return self._iterate()
+
+    async def _iterate(self) -> AsyncIterator[T]:
+        cursor: str | None = None
+        has_more = True
+        while has_more:
+            page = await self._fetch_page(cursor)
+            for item in page.items:
+                yield item
+            cursor = page.next_cursor
+            if not cursor:
+                has_more = False
+
+    async def collect(self, limit: int | None = None) -> list[T]:
+        """Collect paginated items into a list, up to an optional limit."""
+        results: list[T] = []
+        async for item in self:
+            results.append(item)
+            if limit is not None and len(results) >= limit:
+                break
+        return results
+
+
+class SyncPaginator(Generic[T]):
+    """Synchronous auto-paging iterator for iter_* methods."""
+
+    def __init__(
+        self,
+        fetch_page: Callable[[str | None], Page[T]],
+    ) -> None:
+        self._fetch_page = fetch_page
+
+    def __iter__(self) -> Iterator[T]:
+        return self._iterate()
+
+    def _iterate(self) -> Iterator[T]:
+        cursor: str | None = None
+        has_more = True
+        while has_more:
+            page = self._fetch_page(cursor)
+            yield from page.items
+            cursor = page.next_cursor
+            if not cursor:
+                has_more = False
+
+    def collect(self, limit: int | None = None) -> list[T]:
+        """Collect paginated items into a list, up to an optional limit."""
+        results: list[T] = []
+        for item in self:
+            results.append(item)
+            if limit is not None and len(results) >= limit:
+                break
+        return results

actos/_transport/__init__.py

@@ -0,0 +1,8 @@
+"""Transport layer for Actos Python SDK."""
+
+from __future__ import annotations
+
+from actos._transport._async import AsyncTransport
+from actos._transport._sync import SyncTransport
+
+__all__ = ["AsyncTransport", "SyncTransport"]

actos/_transport/_async.py

@@ -0,0 +1,224 @@
+"""Asynchronous HTTP transport layer with retry, backoff, and rate-limit tracking."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import os
+import random
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+import actos
+from actos.errors import (
+    APIConnectionError,
+    APITimeoutError,
+    create_api_error,
+    parse_retry_after,
+)
+from actos.types import RateLimit
+
+if TYPE_CHECKING:
+    from types import TracebackType
+
+
+def compute_backoff_delay(attempt: int, retry_after: float | None = None) -> float:
+    """Calculate delay for retry with exponential backoff and full jitter.
+
+    If Retry-After is specified, it takes absolute precedence (§2.8).
+    """
+    if retry_after is not None:
+        return retry_after
+
+    base_delay = 0.25
+    max_delay = 30.0
+    ceiling = min(max_delay, base_delay * (2**attempt))
+    return random.uniform(0.0, ceiling)
+
+
+class AsyncTransport:
+    """Handles HTTP requests, connection pooling, headers, retries, and rate limits."""
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        api_key: str | None = None,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        raw_base_url = (
+            base_url
+            if base_url is not None
+            else os.environ.get("ACTOS_BASE_URL", "http://127.0.0.1:3100")
+        )
+        self.base_url = raw_base_url.rstrip("/")
+        self.api_key = api_key if api_key is not None else os.environ.get("ACTOS_API_KEY")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.rate_limit: RateLimit | None = None
+
+        self._custom_client = client is not None
+        self._client = client if client is not None else httpx.AsyncClient(timeout=timeout)
+
+    def _update_rate_limit(self, headers: httpx.Headers) -> None:
+        limit_str = headers.get("x-ratelimit-limit")
+        rem_str = headers.get("x-ratelimit-remaining")
+        reset_str = headers.get("x-ratelimit-reset")
+
+        if limit_str is not None and rem_str is not None and reset_str is not None:
+            with contextlib.suppress(ValueError, TypeError):
+                self.rate_limit = RateLimit(
+                    limit=int(limit_str),
+                    remaining=int(rem_str),
+                    reset=int(reset_str),
+                )
+
+    def _raise_for_status(self, response: httpx.Response) -> None:
+        data: Any = None
+        content_type = response.headers.get("content-type", "")
+
+        if "application/json" in content_type or "application/problem+json" in content_type:
+            with contextlib.suppress(Exception):
+                data = response.json()
+
+        if data is None and response.text:
+            data = response.text
+
+        error = create_api_error(
+            status=response.status_code,
+            data=data,
+            headers=response.headers,
+            rate_limit=self.rate_limit,
+        )
+        raise error
+
+    def _format_params(self, params: dict[str, Any] | None) -> dict[str, str] | None:
+        if not params:
+            return None
+
+        formatted: dict[str, str] = {}
+        for k, v in params.items():
+            if v is None:
+                continue
+            if isinstance(v, (list, tuple, set)):
+                formatted[k] = ",".join(str(item) for item in v)
+            elif isinstance(v, bool):
+                formatted[k] = "true" if v else "false"
+            else:
+                formatted[k] = str(v)
+        return formatted
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any = None,
+        data: Any = None,
+        files: Any = None,
+        headers: dict[str, str] | None = None,
+        idempotency_key: str | None = None,
+        timeout: float | None = None,
+    ) -> httpx.Response:
+        """Send an HTTP request with automatic retries and rate-limit tracking."""
+        if path.startswith(("http://", "https://")):
+            url = path
+        else:
+            clean_path = "/" + path.lstrip("/")
+            url = f"{self.base_url}{clean_path}"
+
+        req_headers = {
+            "Accept": "application/json",
+            "User-Agent": f"actos-python/{actos.__version__}",
+        }
+
+        if self.api_key:
+            req_headers["Authorization"] = f"Bearer {self.api_key}"
+
+        if idempotency_key:
+            req_headers["Idempotency-Key"] = idempotency_key
+
+        if headers:
+            req_headers.update(headers)
+
+        formatted_params = self._format_params(params)
+        timeout_val = timeout if timeout is not None else self.timeout
+
+        is_post = method.upper() == "POST"
+        has_idempotency_key = bool(
+            req_headers.get("Idempotency-Key") or req_headers.get("idempotency-key")
+        )
+        can_retry_5xx = (not is_post) or has_idempotency_key
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = await self._client.request(
+                    method=method,
+                    url=url,
+                    params=formatted_params,
+                    json=json,
+                    data=data,
+                    files=files,
+                    headers=req_headers,
+                    timeout=timeout_val,
+                )
+
+                self._update_rate_limit(response.headers)
+
+                # 1. Successful response (< 400)
+                if response.status_code < 400:
+                    return response
+
+                # 2. 429 Too Many Requests -> retry if attempt < max_retries
+                if response.status_code == 429 and attempt < self.max_retries:
+                    retry_after = parse_retry_after(response.headers.get("Retry-After"))
+                    delay = compute_backoff_delay(attempt, retry_after)
+                    await asyncio.sleep(delay)
+                    continue
+
+                # 3. 5xx Server Error -> retry if can_retry_5xx and attempt < max_retries
+                if (
+                    500 <= response.status_code <= 599
+                    and can_retry_5xx
+                    and attempt < self.max_retries
+                ):
+                    delay = compute_backoff_delay(attempt)
+                    await asyncio.sleep(delay)
+                    continue
+
+                # 4. Other 4xx or retries exhausted -> raise specific ActosAPIError subclass
+                self._raise_for_status(response)
+
+            except (httpx.TimeoutException, httpx.TransportError) as exc:
+                # Network/Timeout error retry: safe requests or POST with idempotency key
+                if can_retry_5xx and attempt < self.max_retries:
+                    delay = compute_backoff_delay(attempt)
+                    await asyncio.sleep(delay)
+                    continue
+
+                if isinstance(exc, httpx.TimeoutException):
+                    raise APITimeoutError(f"Request timed out after {timeout_val}s") from exc
+                else:
+                    raise APIConnectionError(f"Connection error: {exc}") from exc
+
+        # Should be unreachable given the loop raises on final attempt, but to satisfy typing:
+        raise APIConnectionError("Request failed: maximum retries exceeded")
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP client if created internally."""
+        if not self._custom_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncTransport:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()

actos/_transport/_sync.py

@@ -0,0 +1,226 @@
+# BU DOSYA OTOMATİK OLARAK ÜRETİLMİŞTİR (unasync) — ELLE DÜZENLEMEYİNİZ.
+
+"""Synchronous HTTP transport layer with retry, backoff, and rate-limit tracking."""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import random
+import time
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+import actos
+from actos.errors import (
+    APIConnectionError,
+    APITimeoutError,
+    create_api_error,
+    parse_retry_after,
+)
+from actos.types import RateLimit
+
+if TYPE_CHECKING:
+    from types import TracebackType
+
+
+def compute_backoff_delay(attempt: int, retry_after: float | None = None) -> float:
+    """Calculate delay for retry with exponential backoff and full jitter.
+
+    If Retry-After is specified, it takes absolute precedence (§2.8).
+    """
+    if retry_after is not None:
+        return retry_after
+
+    base_delay = 0.25
+    max_delay = 30.0
+    ceiling = min(max_delay, base_delay * (2**attempt))
+    return random.uniform(0.0, ceiling)
+
+
+class SyncTransport:
+    """Handles HTTP requests, connection pooling, headers, retries, and rate limits."""
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        api_key: str | None = None,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        client: httpx.Client | None = None,
+    ) -> None:
+        raw_base_url = (
+            base_url
+            if base_url is not None
+            else os.environ.get("ACTOS_BASE_URL", "http://127.0.0.1:3100")
+        )
+        self.base_url = raw_base_url.rstrip("/")
+        self.api_key = api_key if api_key is not None else os.environ.get("ACTOS_API_KEY")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.rate_limit: RateLimit | None = None
+
+        self._custom_client = client is not None
+        self._client = client if client is not None else httpx.Client(timeout=timeout)
+
+    def _update_rate_limit(self, headers: httpx.Headers) -> None:
+        limit_str = headers.get("x-ratelimit-limit")
+        rem_str = headers.get("x-ratelimit-remaining")
+        reset_str = headers.get("x-ratelimit-reset")
+
+        if limit_str is not None and rem_str is not None and reset_str is not None:
+            with contextlib.suppress(ValueError, TypeError):
+                self.rate_limit = RateLimit(
+                    limit=int(limit_str),
+                    remaining=int(rem_str),
+                    reset=int(reset_str),
+                )
+
+    def _raise_for_status(self, response: httpx.Response) -> None:
+        data: Any = None
+        content_type = response.headers.get("content-type", "")
+
+        if "application/json" in content_type or "application/problem+json" in content_type:
+            with contextlib.suppress(Exception):
+                data = response.json()
+
+        if data is None and response.text:
+            data = response.text
+
+        error = create_api_error(
+            status=response.status_code,
+            data=data,
+            headers=response.headers,
+            rate_limit=self.rate_limit,
+        )
+        raise error
+
+    def _format_params(self, params: dict[str, Any] | None) -> dict[str, str] | None:
+        if not params:
+            return None
+
+        formatted: dict[str, str] = {}
+        for k, v in params.items():
+            if v is None:
+                continue
+            if isinstance(v, (list, tuple, set)):
+                formatted[k] = ",".join(str(item) for item in v)
+            elif isinstance(v, bool):
+                formatted[k] = "true" if v else "false"
+            else:
+                formatted[k] = str(v)
+        return formatted
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any = None,
+        data: Any = None,
+        files: Any = None,
+        headers: dict[str, str] | None = None,
+        idempotency_key: str | None = None,
+        timeout: float | None = None,
+    ) -> httpx.Response:
+        """Send an HTTP request with automatic retries and rate-limit tracking."""
+        if path.startswith(("http://", "https://")):
+            url = path
+        else:
+            clean_path = "/" + path.lstrip("/")
+            url = f"{self.base_url}{clean_path}"
+
+        req_headers = {
+            "Accept": "application/json",
+            "User-Agent": f"actos-python/{actos.__version__}",
+        }
+
+        if self.api_key:
+            req_headers["Authorization"] = f"Bearer {self.api_key}"
+
+        if idempotency_key:
+            req_headers["Idempotency-Key"] = idempotency_key
+
+        if headers:
+            req_headers.update(headers)
+
+        formatted_params = self._format_params(params)
+        timeout_val = timeout if timeout is not None else self.timeout
+
+        is_post = method.upper() == "POST"
+        has_idempotency_key = bool(
+            req_headers.get("Idempotency-Key") or req_headers.get("idempotency-key")
+        )
+        can_retry_5xx = (not is_post) or has_idempotency_key
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = self._client.request(
+                    method=method,
+                    url=url,
+                    params=formatted_params,
+                    json=json,
+                    data=data,
+                    files=files,
+                    headers=req_headers,
+                    timeout=timeout_val,
+                )
+
+                self._update_rate_limit(response.headers)
+
+                # 1. Successful response (< 400)
+                if response.status_code < 400:
+                    return response
+
+                # 2. 429 Too Many Requests -> retry if attempt < max_retries
+                if response.status_code == 429 and attempt < self.max_retries:
+                    retry_after = parse_retry_after(response.headers.get("Retry-After"))
+                    delay = compute_backoff_delay(attempt, retry_after)
+                    time.sleep(delay)
+                    continue
+
+                # 3. 5xx Server Error -> retry if can_retry_5xx and attempt < max_retries
+                if (
+                    500 <= response.status_code <= 599
+                    and can_retry_5xx
+                    and attempt < self.max_retries
+                ):
+                    delay = compute_backoff_delay(attempt)
+                    time.sleep(delay)
+                    continue
+
+                # 4. Other 4xx or retries exhausted -> raise specific ActosAPIError subclass
+                self._raise_for_status(response)
+
+            except (httpx.TimeoutException, httpx.TransportError) as exc:
+                # Network/Timeout error retry: safe requests or POST with idempotency key
+                if can_retry_5xx and attempt < self.max_retries:
+                    delay = compute_backoff_delay(attempt)
+                    time.sleep(delay)
+                    continue
+
+                if isinstance(exc, httpx.TimeoutException):
+                    raise APITimeoutError(f"Request timed out after {timeout_val}s") from exc
+                else:
+                    raise APIConnectionError(f"Connection error: {exc}") from exc
+
+        # Should be unreachable given the loop raises on final attempt, but to satisfy typing:
+        raise APIConnectionError("Request failed: maximum retries exceeded")
+
+    def close(self) -> None:
+        """Close the underlying HTTP client if created internally."""
+        if not self._custom_client:
+            self._client.close()
+
+    def __enter__(self) -> SyncTransport:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        self.close()