42api 0.1.0__py3-none-any.whl

intra42/_auth.py

@@ -0,0 +1,103 @@
+"""OAuth2 client-credentials token acquisition and caching.
+
+:class:`TokenManager` is shared, mutable state used from both the sync and
+async clients. Both paths guard the same cached-token state with a lock and use
+double-checked locking so concurrent callers queued on the lock don't each
+trigger a redundant refresh.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+import time
+
+import httpx
+
+from .exceptions import AuthenticationError
+
+TOKEN_URL = "https://api.intra.42.fr/oauth/token"
+
+DEFAULT_LEEWAY = 60.0  # Refresh before expire
+
+
+class TokenManager:
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str,
+        *,
+        token_url: str = TOKEN_URL,
+        leeway: float = DEFAULT_LEEWAY,
+    ) -> None:
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._token_url = token_url
+        self._leeway = leeway
+
+        self._access_token: str | None = None
+        self._expires_at: float = 0.0
+
+        self._lock = threading.Lock()
+        self._alock = asyncio.Lock()
+
+    def _is_valid(self) -> bool:
+        return self._access_token is not None and time.time() < self._expires_at - self._leeway
+
+    def _body(self) -> dict[str, str]:
+        return {
+            "grant_type": "client_credentials",
+            "client_id": self._client_id,
+            "client_secret": self._client_secret,
+        }
+
+    def _store(self, payload: dict[str, object]) -> str:
+        token = payload.get("access_token")
+        if not isinstance(token, str):
+            raise AuthenticationError(
+                "Token endpoint response did not include an access_token",
+            )
+        expires_in = payload.get("expires_in", 7200)
+        try:
+            expires_in = float(expires_in)  # type: ignore[arg-type]
+        except (TypeError, ValueError):
+            expires_in = 7200.0
+        self._access_token = token
+        self._expires_at = time.time() + expires_in
+        return token
+
+    def ensure_token(self, http: httpx.Client) -> str:
+        if self._is_valid():
+            return self._access_token  # type: ignore[return-value]
+        with self._lock:
+            if self._is_valid():
+                return self._access_token  # type: ignore[return-value]
+            try:
+                response = http.post(self._token_url, data=self._body())
+            except httpx.TransportError as exc:
+                raise AuthenticationError(f"Failed to reach token endpoint: {exc}") from exc
+            if response.status_code != 200:
+                raise AuthenticationError(
+                    f"Token endpoint rejected credentials (status {response.status_code})",
+                    status_code=response.status_code,
+                    response=response,
+                )
+            return self._store(response.json())
+
+    async def aensure_token(self, http: httpx.AsyncClient) -> str:
+        if self._is_valid():
+            return self._access_token  # type: ignore[return-value]
+        async with self._alock:
+            if self._is_valid():
+                return self._access_token  # type: ignore[return-value]
+            try:
+                response = await http.post(self._token_url, data=self._body())
+            except httpx.TransportError as exc:
+                raise AuthenticationError(f"Failed to reach token endpoint: {exc}") from exc
+            if response.status_code != 200:
+                raise AuthenticationError(
+                    f"Token endpoint rejected credentials (status {response.status_code})",
+                    status_code=response.status_code,
+                    response=response,
+                )
+            return self._store(response.json())

intra42/_config.py

@@ -0,0 +1,17 @@
+"""Client configuration knobs, shared by the sync and async clients."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+DEFAULT_BASE_URL = "https://api.intra.42.fr/v2"
+
+
+@dataclass(slots=True)
+class ClientConfig:
+    base_url: str = DEFAULT_BASE_URL
+    timeout: float = 10.0
+    max_retries: int = 3
+    rate: float = 2.0
+    burst: int = 2
+    hourly_quota: int = 1200

intra42/_pagination.py

@@ -0,0 +1,23 @@
+"""Pure helper for parsing RFC 5988 ``Link`` headers.
+
+42's API paginates list endpoints and advertises the next/first/last/prev
+page URLs via a standard ``Link`` header:
+    <https://api.intra.42.fr/v2/users?page=2>; rel="next",
+    <https://api.intra.42.fr/v2/users?page=42>; rel="last"
+"""
+
+from __future__ import annotations
+
+import re
+
+_LINK_RE = re.compile(r'<([^>]+)>\s*;\s*rel="([^"]+)"')
+
+
+def parse_link_header(header_value: str | None) -> dict[str, str]:
+    """Parse a ``Link`` header into a ``{rel: url}`` dict.
+
+    Returns an empty dict for ``None`` or malformed input.
+    """
+    if not header_value:
+        return {}
+    return {rel: url for url, rel in _LINK_RE.findall(header_value)}

intra42/_query_params.py

@@ -0,0 +1,54 @@
+"""Pure helpers for building 42 API query strings."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+
+def _stringify(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)
+
+
+def _join(value: Any) -> str:
+    if isinstance(value, (list, tuple, set)):
+        return ",".join(_stringify(v) for v in value)
+    return _stringify(value)
+
+
+def build_query_params(
+    *,
+    filters: Mapping[str, Any] | None = None,
+    sort: Sequence[str] | None = None,
+    page_size: int | None = None,
+    page_number: int | None = None,
+    ranges: Mapping[str, tuple[Any, Any]] | None = None,
+) -> dict[str, str]:
+    """Assemble a flat ``{param_name: value}`` dict ready to pass to httpx.
+
+    - ``filters={"campus_id": 1}`` -> ``{"filter[campus_id]": "1"}``
+    - ``filters={"campus_id": [1, 2]}`` -> ``{"filter[campus_id]": "1,2"}``
+    - ``sort=["-level", "login"]`` -> ``{"sort": "-level,login"}``
+    - ``page_size=30`` -> ``{"page[size]": "30"}``
+    - ``ranges={"id": (1, 100)}`` -> ``{"range[id]": "1,100"}``
+    """
+    params: dict[str, str] = {}
+
+    for key, value in (filters or {}).items():
+        params[f"filter[{key}]"] = _join(value)
+
+    if sort:
+        params["sort"] = ",".join(sort)
+
+    if page_size is not None:
+        params["page[size]"] = str(page_size)
+
+    if page_number is not None:
+        params["page[number]"] = str(page_number)
+
+    for key, (start, end) in (ranges or {}).items():
+        params[f"range[{key}]"] = f"{_stringify(start)},{_stringify(end)}"
+
+    return params

intra42/_rate_limit.py

@@ -0,0 +1,102 @@
+"""Automatic request pacing to stay under the 42 API's rate limits.
+
+Combines a token bucket (per-second pacing) with an hourly quota counter and
+a ``Retry-After`` cooldown gate shared by both the sync and async
+acquire paths.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+import time
+from collections.abc import Callable
+
+DEFAULT_RATE = 2.0  # requests per second
+DEFAULT_BURST = 2  # bucket capacity
+DEFAULT_HOURLY_QUOTA = 1200
+HOUR_SECONDS = 3600.0
+
+
+class RateLimiter:
+    def __init__(
+        self,
+        *,
+        rate: float = DEFAULT_RATE,
+        burst: int = DEFAULT_BURST,
+        hourly_quota: int = DEFAULT_HOURLY_QUOTA,
+        monotonic: Callable[[], float] = time.monotonic,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+
+        self._rate = rate
+        self._capacity = float(burst)
+        self._hourly_quota = hourly_quota
+        self._monotonic = monotonic
+        self._sleep = sleep
+
+        now = monotonic()
+        self._tokens = self._capacity
+        self._last_refill = now
+
+        self._hour_window_start = now
+        self._hour_count = 0
+
+        self._retry_after_until = 0.0
+
+        self._lock = threading.Lock()
+        self._alock = asyncio.Lock()
+
+    def _refill(self, now: float) -> None:
+        elapsed = now - self._last_refill
+        if elapsed > 0:
+            self._tokens = min(self._capacity, self._tokens + elapsed * self._rate)
+            self._last_refill = now
+
+        if now - self._hour_window_start >= HOUR_SECONDS:
+            self._hour_window_start = now
+            self._hour_count = 0
+
+    def _compute_wait(self, now: float) -> float:
+        self._refill(now)
+
+        waits = [0.0]
+
+        if self._tokens < 1.0:
+            waits.append((1.0 - self._tokens) / self._rate)
+
+        if self._hour_count >= self._hourly_quota:
+            waits.append(self._hour_window_start + HOUR_SECONDS - now)
+
+        if self._retry_after_until > now:
+            waits.append(self._retry_after_until - now)
+
+        return max(waits)
+
+    def _consume(self) -> None:
+        # Called immediately after the wait, while still holding the lock.
+        now = self._monotonic()
+        self._refill(now)
+        self._tokens = max(0.0, self._tokens - 1.0)
+        self._hour_count += 1
+
+    # No lock needed: monotonically extending a float is safe to race,
+    # and only ever makes the next acquire() wait *more*, never less.
+    def notify_retry_after(self, seconds: float) -> None:
+        until = self._monotonic() + max(0.0, seconds)
+        if until > self._retry_after_until:
+            self._retry_after_until = until
+
+    def acquire(self) -> None:
+        with self._lock:
+            wait = self._compute_wait(self._monotonic())
+            if wait > 0:
+                self._sleep(wait)
+            self._consume()
+
+    async def aacquire(self) -> None:
+        async with self._alock:
+            wait = self._compute_wait(self._monotonic())
+            if wait > 0:
+                await asyncio.sleep(wait)
+            self._consume()

intra42/_sync/client.py

@@ -0,0 +1,132 @@
+# GENERATED FILE — DO NOT EDIT BY HAND.
+#
+# Generated from the corresponding module under intra42._async by
+# scripts/unasync_generate.py (via the `unasync` library). Edit the
+# async source and re-run that script instead.
+
+"""The async client, do not hand-maintain a parallel sync
+implementation of the request logic here.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .._auth import TokenManager
+from .._config import DEFAULT_BASE_URL, ClientConfig
+from .._rate_limit import RateLimiter
+from ..exceptions import NetworkError, raise_for_status
+from .resources.campus_users import CampusUsersResource
+from .resources.campuses import CampusesResource
+from .resources.events import EventsResource
+from .resources.locations import LocationsResource
+from .resources.users import UsersResource
+
+
+def _parse_retry_after(value: str | None) -> float:
+    """Parse a ``Retry-After`` header value as seconds.
+
+    Assumed to be the integer-seconds form.
+    """
+    if value is None:
+        return 1.0
+    try:
+        return max(0.0, float(value))
+    except ValueError:
+        return 1.0
+
+
+class Client:
+    """Async client for the 42 API, authenticated via OAuth2 client credentials."""
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 10.0,
+        max_retries: int = 3,
+        config: ClientConfig | None = None,
+    ) -> None:
+        self._config = config or ClientConfig(
+            base_url=base_url, timeout=timeout, max_retries=max_retries
+        )
+        self._http = httpx.Client(timeout=self._config.timeout)
+        self._token_manager = TokenManager(client_id, client_secret)
+        self._rate_limiter = RateLimiter(
+            rate=self._config.rate,
+            burst=self._config.burst,
+            hourly_quota=self._config.hourly_quota,
+        )
+
+        self.users = UsersResource(self)
+        self.campuses = CampusesResource(self)
+        self.campus_users = CampusUsersResource(self)
+        self.events = EventsResource(self)
+        self.locations = LocationsResource(self)
+
+    @property
+    def base_url(self) -> str:
+        return self._config.base_url
+
+    def _build_url(self, path: str) -> str:
+        if path.startswith("http://") or path.startswith("https://"):
+            return path
+        return f"{self._config.base_url}{path}"
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+    ) -> httpx.Response:
+        """Send one authenticated, rate-limited, error-mapped request.
+
+        Retries on 429 up to ``max_retries`` times, honoring the response's
+        ``Retry-After`` header via the shared rate limiter's cooldown gate,
+        before raising :class:`intra42.exceptions.RateLimitError`.
+        """
+        url = self._build_url(path)
+        response: httpx.Response | None = None
+
+        for attempt in range(self._config.max_retries + 1):
+            token = self._token_manager.ensure_token(self._http)
+            self._rate_limiter.acquire()
+            try:
+                response = self._http.request(
+                    method,
+                    url,
+                    params=params,
+                    json=json,
+                    headers={"Authorization": f"Bearer {token}"},
+                )
+            except httpx.TransportError as exc:
+                raise NetworkError(f"Request to {url} failed: {exc}") from exc
+
+            if response.status_code == 429:
+                self._rate_limiter.notify_retry_after(
+                    _parse_retry_after(response.headers.get("Retry-After"))
+                )
+                if attempt < self._config.max_retries:
+                    continue
+
+            raise_for_status(response)
+            return response
+
+        assert response is not None  # loop always runs at least once
+        raise_for_status(response)
+        return response  # pragma: no cover - raise_for_status always raises on a 429
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()

intra42/_sync/query.py

@@ -0,0 +1,105 @@
+# GENERATED FILE — DO NOT EDIT BY HAND.
+#
+# Generated from the corresponding module under intra42._async by
+# scripts/unasync_generate.py (via the `unasync` library). Edit the
+# async source and re-run that script instead.
+
+"""Lazy, chainable, auto-paginating query builder.
+
+``AsyncQuerySet`` is returned by a resource's ``.filter()``/``.sort()``/etc.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
+
+from .._pagination import parse_link_header
+from .._query_params import build_query_params
+from ..models.base import FortyTwoModel
+
+if TYPE_CHECKING:
+    from .client import Client
+
+ModelT = TypeVar("ModelT", bound=FortyTwoModel)
+
+
+class QuerySet(Generic[ModelT]):
+    def __init__(
+        self,
+        client: Client,
+        path: str,
+        model: type[ModelT],
+        *,
+        bind: Callable[[ModelT], None] | None = None,
+    ) -> None:
+        self._client = client
+        self._path = path
+        self._model = model
+        # Set by the owning resource to attach nested-resource accessors
+        # (e.g. User.events) to each instance as it's parsed. See
+        # AsyncResource._bind_relations / FortyTwoModel._bind_relation.
+        self._bind = bind
+        self._filters: dict[str, Any] = {}
+        self._sort_fields: list[str] = []
+        self._page_size: int | None = None
+        self._ranges: dict[str, tuple[Any, Any]] = {}
+
+    def _clone(self) -> QuerySet[ModelT]:
+        clone = QuerySet(self._client, self._path, self._model, bind=self._bind)
+        clone._filters = dict(self._filters)
+        clone._sort_fields = list(self._sort_fields)
+        clone._page_size = self._page_size
+        clone._ranges = dict(self._ranges)
+        return clone
+
+    def filter(self, **kwargs: Any) -> QuerySet[ModelT]:
+        """Add ``filter[field]=value`` constraints. Chainable, non-mutating."""
+        clone = self._clone()
+        clone._filters.update(kwargs)
+        return clone
+
+    def sort(self, *fields: str) -> QuerySet[ModelT]:
+        """Set the ``sort`` param, e.g. ``.sort('-level', 'login')``."""
+        clone = self._clone()
+        clone._sort_fields = list(fields)
+        return clone
+
+    def page_size(self, n: int) -> QuerySet[ModelT]:
+        clone = self._clone()
+        clone._page_size = n
+        return clone
+
+    def range(self, field: str, start: Any, end: Any) -> QuerySet[ModelT]:
+        clone = self._clone()
+        clone._ranges[field] = (start, end)
+        return clone
+
+    def _initial_params(self) -> dict[str, str]:
+        return build_query_params(
+            filters=self._filters,
+            sort=self._sort_fields,
+            page_size=self._page_size,
+            ranges=self._ranges,
+        )
+
+    def __iter__(self) -> Iterator[ModelT]:
+        url: str | None = self._path
+        params: dict[str, str] | None = self._initial_params()
+        while url is not None:
+            response = self._client.request("GET", url, params=params)
+            for item in response.json():
+                instance = self._model.model_validate(item)
+                if self._bind is not None:
+                    self._bind(instance)
+                yield instance
+            url = parse_link_header(response.headers.get("Link")).get("next")
+            params = None  # the next URL already carries its full query string
+
+    def all(self) -> list[ModelT]:
+        return [item for item in self]
+
+    def first(self) -> ModelT | None:
+        for item in self:
+            return item
+        return None

intra42/_sync/resources/base.py

@@ -0,0 +1,83 @@
+# GENERATED FILE — DO NOT EDIT BY HAND.
+#
+# Generated from the corresponding module under intra42._async by
+# scripts/unasync_generate.py (via the `unasync` library). Edit the
+# async source and re-run that script instead.
+
+"""Generic resource base class shared by all async resource managers.
+
+Concrete resources (``AsyncUsersResource``, ``AsyncCampusesResource``, ...)
+are thin subclasses that just set ``path`` and ``model``. ``.filter()``,
+``.sort()``, ``.all()`` etc. delegate to :class:`AsyncQuerySet`, and the
+resource itself is iterable (``async for x in client.users``) for the
+unfiltered, unsorted case.
+
+Resources whose model exposes nested sub-resources (e.g. ``User.events``,
+``Campus.users``) override ``_bind_relations()`` to attach lazy accessor
+factories to each freshly parsed instance.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import TYPE_CHECKING, Any, ClassVar, Generic, TypeVar, cast
+
+from ...models.base import FortyTwoModel
+from ..query import QuerySet
+
+if TYPE_CHECKING:
+    from ..client import Client
+
+ModelT = TypeVar("ModelT", bound=FortyTwoModel)
+
+
+class Resource(Generic[ModelT]):
+    path: ClassVar[str]
+    model: ClassVar[type[FortyTwoModel]]
+
+    def __init__(self, client: Client) -> None:
+        self._client = client
+
+    def _bind_relations(self, instance: ModelT) -> None:
+        """Attach nested-resource accessors to a freshly parsed instance.
+
+        No-op by default. Applied to instances from both ``.get()`` and
+        queryset iteration, so relations work the same either way.
+        """
+        return
+
+    def get(self, id: int | str) -> ModelT:
+        """Fetch a single resource by id: ``GET {path}/{id}``."""
+        response = self._client.request("GET", f"{self.path}/{id}")
+        instance = cast(ModelT, self.model.model_validate(response.json()))
+        self._bind_relations(instance)
+        return instance
+
+    def _queryset(self, path: str | None = None) -> QuerySet[ModelT]:
+        return QuerySet(
+            self._client,
+            path or self.path,
+            cast(type[ModelT], self.model),
+            bind=self._bind_relations,
+        )
+
+    def filter(self, **kwargs: Any) -> QuerySet[ModelT]:
+        return self._queryset().filter(**kwargs)
+
+    def sort(self, *fields: str) -> QuerySet[ModelT]:
+        return self._queryset().sort(*fields)
+
+    def page_size(self, n: int) -> QuerySet[ModelT]:
+        return self._queryset().page_size(n)
+
+    def range(self, field: str, start: Any, end: Any) -> QuerySet[ModelT]:
+        return self._queryset().range(field, start, end)
+
+    def all(self) -> list[ModelT]:
+        return self._queryset().all()
+
+    def first(self) -> ModelT | None:
+        return self._queryset().first()
+
+    def __iter__(self) -> Iterator[ModelT]:
+        return self._queryset().__iter__()

intra42/_sync/resources/campus_users.py

@@ -0,0 +1,15 @@
+# GENERATED FILE — DO NOT EDIT BY HAND.
+#
+# Generated from the corresponding module under intra42._async by
+# scripts/unasync_generate.py (via the `unasync` library). Edit the
+# async source and re-run that script instead.
+
+from __future__ import annotations
+
+from ...models.campus_user import CampusUser
+from .base import Resource
+
+
+class CampusUsersResource(Resource[CampusUser]):
+    path = "/campus_users"
+    model = CampusUser

intra42/_sync/resources/campuses.py

@@ -0,0 +1,29 @@
+# GENERATED FILE — DO NOT EDIT BY HAND.
+#
+# Generated from the corresponding module under intra42._async by
+# scripts/unasync_generate.py (via the `unasync` library). Edit the
+# async source and re-run that script instead.
+
+from __future__ import annotations
+
+from ...models.campus import Campus
+from .base import Resource
+
+
+class CampusesResource(Resource[Campus]):
+    path = "/campus"
+    model = Campus
+
+    def _bind_relations(self, instance: Campus) -> None:
+        instance._bind_relation(
+            "users",
+            lambda: self._client.users._queryset(f"/campus/{instance.id}/users"),
+        )
+        instance._bind_relation(
+            "events",
+            lambda: self._client.events._queryset(f"/campus/{instance.id}/events"),
+        )
+        instance._bind_relation(
+            "locations",
+            lambda: self._client.locations._queryset(f"/campus/{instance.id}/locations"),
+        )

intra42/_sync/resources/events.py

@@ -0,0 +1,15 @@
+# GENERATED FILE — DO NOT EDIT BY HAND.
+#
+# Generated from the corresponding module under intra42._async by
+# scripts/unasync_generate.py (via the `unasync` library). Edit the
+# async source and re-run that script instead.
+
+from __future__ import annotations
+
+from ...models.event import Event
+from .base import Resource
+
+
+class EventsResource(Resource[Event]):
+    path = "/events"
+    model = Event