42api 0.1.0__py3-none-any.whl

intra42/_sync/resources/locations.py

@@ -0,0 +1,34 @@
+# 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.location import Location
+from .base import Resource
+
+
+class LocationsResource(Resource[Location]):
+    path = "/locations"
+    model = Location
+
+    def graph(self, *, field: str | None = None, interval: str | None = None) -> dict[str, int]:
+        """Grouped temporal counts (``GET /locations/graph...``).
+
+        Not a paginated list of ``Location`` objects — returns a raw
+        ``{date_string: count}`` mapping, counting occurrences of `field`
+        (default ``begin_at``) bucketed by `interval` (default
+        ``month_of_year``) from the first occurrence to now.
+        """
+
+        path = "/locations/graph"
+        if interval is not None and field is None:
+            field = "begin_at"
+        if field is not None:
+            path += f"/on/{field}"
+            if interval is not None:
+                path += f"/by/{interval}"
+        response = self._client.request("GET", path)
+        return response.json()

intra42/_sync/resources/users.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.user import User
+from .base import Resource
+
+
+class UsersResource(Resource[User]):
+    path = "/users"
+    model = User
+
+    def _bind_relations(self, instance: User) -> None:
+        instance._bind_relation(
+            "events",
+            lambda: self._client.events._queryset(f"/users/{instance.id}/events"),
+        )
+        instance._bind_relation(
+            "campus_users",
+            lambda: self._client.campus_users._queryset(f"/users/{instance.id}/campus_users"),
+        )
+        instance._bind_relation(
+            "locations",
+            lambda: self._client.locations._queryset(f"/users/{instance.id}/locations"),
+        )

intra42/exceptions.py

@@ -0,0 +1,88 @@
+"""Exception hierarchy for the intra42 client."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import httpx
+
+
+class FortyTwoAPIError(Exception):
+    """Base class for all errors raised by this library."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        response: httpx.Response | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.response = response
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(status_code={self.status_code!r}, message={self.message!r})"
+
+
+class AuthenticationError(FortyTwoAPIError):
+    """Raised on any 401"""
+
+
+class PermissionDeniedError(FortyTwoAPIError):
+    """Raised on any 403"""
+
+
+class NotFoundError(FortyTwoAPIError):
+    """Raised on any 404."""
+
+
+class ValidationError(FortyTwoAPIError):
+    """Raised on any 422"""
+
+
+class RateLimitError(FortyTwoAPIError):
+    """Raised on any 429 after the built-in retry/backoff budget is exhausted."""
+
+
+class ServerError(FortyTwoAPIError):
+    """Raised on any 5xx"""
+
+
+class NetworkError(FortyTwoAPIError):
+    """Wraps a transport-level failure (DNS, connect, timeout) from httpx."""
+
+
+_STATUS_MAP: dict[int, type[FortyTwoAPIError]] = {
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    422: ValidationError,
+    429: RateLimitError,
+}
+
+
+def raise_for_status(response: httpx.Response) -> None:
+    """Raise the mapped :class:`FortyTwoAPIError` subclass for a non-2xx response.
+
+    Does nothing for successful responses.
+    """
+    if response.is_success:
+        return
+
+    status = response.status_code
+    try:
+        payload = response.json()
+        detail = payload.get("error_description") or payload.get("message") or payload.get("error")
+    except Exception:
+        detail = None
+    message = detail or f"Request failed with status {status}"
+
+    if status >= 500:
+        error_cls: type[FortyTwoAPIError] = ServerError
+    else:
+        error_cls = _STATUS_MAP.get(status, FortyTwoAPIError)
+
+    raise error_cls(message, status_code=status, response=response)

intra42/models/base.py

@@ -0,0 +1,47 @@
+"""Shared base model for all 42 API resource models."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, PrivateAttr
+
+
+class FortyTwoModel(BaseModel):
+    """Base class for every typed resource returned by the API.
+
+    ``extra="allow"`` is deliberate: 42's API has historically added fields
+    over time, so unknown keys are kept (inspectable via ``.model_extra``)
+    rather than raising a ``ValidationError`` or silently discarding them.
+    """
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    # Nested-resource accessors (e.g. User.events) are not
+    # hardcoded, they're bound per-instance by whichever resource
+    # fetched this object, as a lazily invoked factory.
+    _relations: dict[str, Callable[[], Any]] = PrivateAttr(default_factory=dict)
+
+    def _bind_relation(self, name: str, factory: Callable[[], Any]) -> None:
+        """Attach a lazily-invoked nested-resource accessor to this instance.
+
+        Called internally by Client/AsyncClient resources right after
+        parsing a response; not meant to be called directly.
+        """
+        self._relations[name] = factory
+
+    def _relation(self, name: str) -> Any:
+        """Resolve a nested-resource accessor bound via ``_bind_relation``.
+
+        Raises ``RuntimeError`` with a clear message if this instance wasn't
+        fetched through a Client/AsyncClient
+        """
+        try:
+            factory = self._relations[name]
+        except KeyError:
+            raise RuntimeError(
+                f"'{name}' is only available on a {type(self).__name__} instance "
+                "fetched via Client/AsyncClient, not one constructed manually."
+            ) from None
+        return factory()

intra42/models/campus.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .base import FortyTwoModel
+
+if TYPE_CHECKING:
+    from .._async.query import AsyncQuerySet
+    from .._sync.query import QuerySet
+    from .event import Event
+    from .location import Location
+    from .user import User
+
+
+class CampusLanguage(FortyTwoModel):
+    id: int
+    name: str | None = None
+    identifier: str | None = None
+
+
+class CampusEndpoint(FortyTwoModel):
+    id: int
+    url: str | None = None
+    description: str | None = None
+    created_at: str | None = None
+    updated_at: str | None = None
+
+
+class Campus(FortyTwoModel):
+    id: int
+    name: str
+    time_zone: str | None = None
+    language: CampusLanguage | None = None
+    users_count: int | None = None
+    vogsphere_id: int | None = None
+    country: str | None = None
+    address: str | None = None
+    zip: str | None = None
+    city: str | None = None
+    website: str | None = None
+    facebook: str | None = None
+    twitter: str | None = None
+    active: bool | None = None
+    public: bool | None = None
+    email_extension: str | None = None
+    default_hidden_phone: bool | None = None
+    endpoint: CampusEndpoint | None = None
+
+    @property
+    def users(self) -> AsyncQuerySet[User] | QuerySet[User]:
+        """Users of this campus (``GET /campus/{id}/users``).
+
+        Lazily-paginating. Only available on instances fetched via
+        ``Client``/``AsyncClient`` — see ``FortyTwoModel._relation``.
+        """
+        return self._relation("users")
+
+    @property
+    def events(self) -> AsyncQuerySet[Event] | QuerySet[Event]:
+        """Events at this campus (``GET /campus/{id}/events``)."""
+        return self._relation("events")
+
+    @property
+    def locations(self) -> AsyncQuerySet[Location] | QuerySet[Location]:
+        """Login sessions at this campus (``GET /campus/{id}/locations``)."""
+        return self._relation("locations")

intra42/models/campus_user.py

@@ -0,0 +1,16 @@
+"""The ``CampusUser`` resource: the join between a user and a campus."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from .base import FortyTwoModel
+
+
+class CampusUser(FortyTwoModel):
+    id: int
+    user_id: int | None = None
+    campus_id: int | None = None
+    is_primary: bool | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None

intra42/models/event.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+from .base import FortyTwoModel
+
+
+class EventTheme(FortyTwoModel):
+    id: int | None = None
+    name: str | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+
+class EventWaitlist(FortyTwoModel):
+    id: int | None = None
+    waitlistable_id: int | None = None
+    waitlistable_type: str | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+
+class Event(FortyTwoModel):
+    id: int
+    name: str | None = None
+    description: str | None = None
+    location: str | None = None
+    kind: str | None = None
+    max_people: int | None = None
+    nbr_subscribers: int | None = None
+    begin_at: datetime | None = None
+    end_at: datetime | None = None
+    campus_ids: list[int] | None = None
+    cursus_ids: list[int] | None = None
+    themes: list[EventTheme] | None = None
+    waitlist: EventWaitlist | None = None
+    prohibition_of_cancellation: int | None = None
+    difficulty: int | None = None
+    remote: bool | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None

intra42/models/location.py

@@ -0,0 +1,26 @@
+"""The ``Location`` resource: a login session at a workstation."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from .base import FortyTwoModel
+
+
+class LocationUser(FortyTwoModel):
+    id: int | None = None
+    login: str | None = None
+    url: str | None = None
+
+
+class Location(FortyTwoModel):
+    id: int
+    begin_at: datetime | None = None
+    end_at: datetime | None = None
+    primary: bool | None = None
+    floor: str | None = None
+    row: str | None = None
+    post: str | None = None
+    host: str | None = None
+    campus_id: int | None = None
+    user: LocationUser | None = None

intra42/models/user.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from pydantic import Field
+
+from .base import FortyTwoModel
+
+if TYPE_CHECKING:
+    from .._async.query import AsyncQuerySet
+    from .._sync.query import QuerySet
+    from .campus_user import CampusUser
+    from .event import Event
+    from .location import Location
+
+
+class ImageVersions(FortyTwoModel):
+    large: str | None = None
+    medium: str | None = None
+    small: str | None = None
+    micro: str | None = None
+
+
+class Image(FortyTwoModel):
+    link: str | None = None
+    versions: ImageVersions | None = None
+
+
+class User(FortyTwoModel):
+    id: int
+    email: str | None = None
+    login: str | None = None
+    first_name: str | None = None
+    last_name: str | None = None
+    usual_full_name: str | None = None
+    usual_first_name: str | None = None
+    url: str | None = None
+    phone: str | None = None
+    displayname: str | None = None
+    kind: str | None = None
+    image: Image | None = None
+    staff: bool | None = Field(default=None, alias="staff?")
+    correction_point: int | None = None
+    pool_month: str | None = None
+    pool_year: str | None = None
+    location: str | None = None
+    wallet: int | None = None
+    anonymize_date: datetime | None = None
+    data_erasure_date: datetime | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+    alumnized_at: datetime | None = None
+    alumni: bool | None = Field(default=None, alias="alumni?")
+    active: bool | None = Field(default=None, alias="active?")
+
+    @property
+    def events(self) -> AsyncQuerySet[Event] | QuerySet[Event]:
+        """Events scoped to this user (``GET /users/{id}/events``)"""
+        return self._relation("events")
+
+    @property
+    def campus_users(self) -> AsyncQuerySet[CampusUser] | QuerySet[CampusUser]:
+        """This user's campus memberships (``GET /users/{id}/campus_users``)."""
+        return self._relation("campus_users")
+
+    @property
+    def locations(self) -> AsyncQuerySet[Location] | QuerySet[Location]:
+        """This user's login sessions (``GET /users/{id}/locations``).
+
+        Not to be confused with the ``location`` string field.
+        """
+        return self._relation("locations")