42api 0.1.0__py3-none-any.whl

42api-0.1.0.dist-info/METADATA

@@ -0,0 +1,137 @@
+Metadata-Version: 2.5
+Name: 42api
+Version: 0.1.0
+Summary: Object-oriented Python client for the 42 School API (api.intra.42.fr)
+Project-URL: Homepage, https://github.com/Shadowaker/42api
+Author-email: Dan <danyridolfo98@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: 42,42school,api,client,intra
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Description-Content-Type: text/markdown
+
+# 42api
+
+An object-oriented Python client for the [42 School API](https://api.intra.42.fr)
+(`api.intra.42.fr`) that handles OAuth2 authentication, request pacing, and
+pagination for you, so you can work with typed resources instead of raw JSON
+and HTTP plumbing.
+
+- **Sync and async** — `Client` and `AsyncClient` share one codebase and the
+  same interface.
+- **Typed models** — resources are [Pydantic v2](https://docs.pydantic.dev/)
+  models with IDE-friendly autocomplete.
+- **Automatic rate limiting** — requests are paced to stay under 42's limits;
+  `429`s are retried with backoff automatically.
+- **Lazy pagination** — iterate a query and it walks every page for you.
+
+## Install
+
+```bash
+uv add 42api
+# or: pip install 42api
+```
+
+## Usage
+
+```python
+from intra42 import Client
+
+with Client(client_id="...", client_secret="...") as client:
+    user = client.users.get("jdoe")
+    print(user.login, user.email)
+
+    for user in client.users.filter(campus_id=1).sort("-level"):
+        print(user.login)
+```
+
+Async is the same shape:
+
+```python
+import asyncio
+from intra42 import AsyncClient
+
+
+async def main() -> None:
+    async with AsyncClient(client_id="...", client_secret="...") as client:
+        user = await client.users.get("jdoe")
+        async for user in client.users.filter(campus_id=1).sort("-level"):
+            print(user.login)
+
+
+asyncio.run(main())
+```
+
+Fetched instances expose their nested resources directly — no need to
+build the scoped path yourself:
+
+```python
+campus = client.campuses.get(1)
+for event in campus.events:  # GET /campus/1/events
+    print(event.name)
+
+user = client.users.get("jdoe")
+for cu in user.campus_users:  # GET /users/jdoe/campus_users
+    print(cu.campus_id, cu.is_primary)
+```
+
+These (`campus.events`, `campus.users`, `user.events`, `user.campus_users`)
+are only available on instances fetched via a client — a manually
+constructed model raises a clear `RuntimeError` if accessed.
+
+Get your `client_id`/`client_secret` by registering an app at
+https://profile.intra.42.fr/oauth/applications. This library uses the
+**client credentials** flow, so it accesses the API as your app rather than
+as a specific logged-in user.
+
+## Errors
+
+All errors subclass `intra42.FortyTwoAPIError`, with subclasses for common
+HTTP statuses: `AuthenticationError` (401), `PermissionDeniedError` (403),
+`NotFoundError` (404), `ValidationError` (422), `RateLimitError` (429, only
+raised once the built-in retry budget is exhausted), `ServerError` (5xx),
+and `NetworkError` (connection/timeout failures).
+
+## Status
+
+Early-stage: currently covers `users`, `campuses`, `campus_users`,
+`events`, and `locations` (including its `graph` analytics endpoint). More
+resources are added incrementally on top of the same client/model/
+query-builder pattern.
+
+## Development
+
+Uses [uv](https://docs.astral.sh/uv/) for dependency management.
+
+```bash
+uv sync                                               # install dependencies
+uv run pytest                                         # run tests
+uv run ruff check . && uv run ruff format --check .   # lint
+uv run mypy                                           # type check
+```
+
+The sync client (`intra42._sync`) is generated from the async client
+(`intra42._async`) via [`unasync`](https://github.com/python-trio/unasync) —
+edit the async source and regenerate:
+
+```bash
+uv run python scripts/unasync_generate.py            # regenerate
+uv run python scripts/unasync_generate.py --check    # verify no drift (CI)
+```
+
+## License
+
+MIT

42api-0.1.0.dist-info/RECORD

@@ -0,0 +1,39 @@
+intra42/__init__.py,sha256=oQUa2-hzW7xSlBHlRd5P8JaIUY1nIPtsaKI9OS6DcRA,1226
+intra42/_auth.py,sha256=N5QS8V7iF-TetN4adu0z7aouFZxwODP0Dmc1aIoflCc,3728
+intra42/_config.py,sha256=aMZnkOoNrV9MNS0SGIgBKDlQ2Suugc0bkeaIIilRvWA,395
+intra42/_pagination.py,sha256=eZkLQ07aHZ28_jRuJEiT3G_z2eVypweYAAoNcPSVxrk,705
+intra42/_query_params.py,sha256=Fhyb43lNVa_YQB1OEYpBZ754IO-4zRbnN-FX-ttKdfQ,1624
+intra42/_rate_limit.py,sha256=EX6dY34dUhmi31dA1gFAL3_1TtaY0Yjjg4Eag_dZUv0,3060
+intra42/exceptions.py,sha256=diScpCHtki2M9RxuLNunnmKgssnojnlBvTbyvXYmPfI,2226
+intra42/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+intra42/_async/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+intra42/_async/client.py,sha256=1HDWstyGvUxuV9i8kzaVN-XuwDiGmTnugjQl0Io-ye4,4194
+intra42/_async/query.py,sha256=Nzeaz0M7hBxb7tpyQXj7Ge-kArXqN35htH0HGz63hFA,3443
+intra42/_async/resources/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+intra42/_async/resources/base.py,sha256=3GerWioCDjtOwNQvSFSmj0SgS_x-GncXdEdjbIkQSQo,2723
+intra42/_async/resources/campus_users.py,sha256=9QtlgU96BqnIlJZwL9A_yNxaas00QisHzonjuPRtrOk,224
+intra42/_async/resources/campuses.py,sha256=4IqeaffPAeHZZxqhV21AJ60Jczb3iQyGXb0xE82NqWg,709
+intra42/_async/resources/events.py,sha256=kX4E1pNj31pfpazQOU6ePldxGSyq0QiGMwRpwcAUWHs,192
+intra42/_async/resources/locations.py,sha256=nsbwH6GO9SdhPMPX_iPz2AcjfNc3RvxzLT7xqDg-54M,1027
+intra42/_async/resources/users.py,sha256=-i3FACKLLAHYuRrkszQKQtPknBJXNpRZkeox3jEEhxE,713
+intra42/_sync/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+intra42/_sync/client.py,sha256=q-cwntxt5NKOt7XgBLBygjP_6Tlua9BDbPZc9jHv0Cs,4294
+intra42/_sync/query.py,sha256=VHm2hW_Rhe-lpA0oLlEVxOS-D4lfsLJlOPj5tJzvfbE,3577
+intra42/_sync/resources/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+intra42/_sync/resources/base.py,sha256=meS7yQ9EglCiUTVFvc1keEdjwk6gFxO0fGu8N9Qd0IU,2851
+intra42/_sync/resources/campus_users.py,sha256=RNflq09LBX6Ldm_Z0vwa_kyPkIsNRJLL55Ju098f8YA,435
+intra42/_sync/resources/campuses.py,sha256=F0_UslCm2ZHZUqFvN9o50navrCOb1z-XBqTLxUQ6Xm8,920
+intra42/_sync/resources/events.py,sha256=ARUhCUAGwjpREXr9TVO7n_3lxQeyu7cM8RxphGUrvOc,403
+intra42/_sync/resources/locations.py,sha256=oCV1CCo4F-p5x27vW07fu2bmZLypUYjBITTt7khhFA0,1212
+intra42/_sync/resources/users.py,sha256=1orQnarQTC8cbOwVZoiEBACnSlrFYQNjoH4XNYxa7s0,924
+intra42/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+intra42/models/base.py,sha256=WWjA_Tqhonop_0oEOg7AM7lON8PMggRX0UCmY_fP1wg,1796
+intra42/models/campus.py,sha256=6rQkLx1AEjUteQZ7qDrXDxY9uIRuCalUtM3rkstik2Q,1918
+intra42/models/campus_user.py,sha256=CGlyUvQMBR0qROne6UYnNfnp69mecfIF2MXZjawz0So,397
+intra42/models/event.py,sha256=2xNWEWnNeP7JzjphbdlKYNHVkVyjhQBSCWLRmNwrRdg,1157
+intra42/models/location.py,sha256=kkgLqQb_5zceWxLL6NP7TXigVXiyaVLzUlcWCBfCgyo,617
+intra42/models/user.py,sha256=eu5vmxWr0M2Esd_WWaGEGmMZwUW5a9Si2QRt_kS_Q-A,2270
+42api-0.1.0.dist-info/METADATA,sha256=jdmielmsT9l4S1HiVKYYcSfzevjNcrX9U8CeC0qv8EE,4448
+42api-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+42api-0.1.0.dist-info/licenses/LICENSE,sha256=x8aMiBy-p92-XG6NJxIs-1FbBp_Rk0i-IzlPdEzoHso,1060
+42api-0.1.0.dist-info/RECORD,,

42api-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

42api-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

intra42/__init__.py

@@ -0,0 +1,53 @@
+"""intra42 — an object-oriented Python client for the 42 School API.
+
+    from intra42 import Client
+
+    with Client(client_id, client_secret) as client:
+        user = client.users.get("jdoe")
+        for user in client.users.filter(campus_id=1).sort("-level"):
+            ...
+
+An async client with the same interface is available as ``AsyncClient``.
+"""
+
+from __future__ import annotations
+
+from ._async.client import AsyncClient
+from ._config import ClientConfig
+from ._sync.client import Client
+from .exceptions import (
+    AuthenticationError,
+    FortyTwoAPIError,
+    NetworkError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from .models.campus import Campus
+from .models.campus_user import CampusUser
+from .models.event import Event
+from .models.location import Location
+from .models.user import User
+
+__all__ = [
+    "AsyncClient",
+    "Client",
+    "ClientConfig",
+    "User",
+    "Campus",
+    "CampusUser",
+    "Event",
+    "Location",
+    "FortyTwoAPIError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ValidationError",
+    "RateLimitError",
+    "ServerError",
+    "NetworkError",
+]
+
+__version__ = "0.1.0"

intra42/_async/client.py

@@ -0,0 +1,126 @@
+"""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 AsyncCampusUsersResource
+from .resources.campuses import AsyncCampusesResource
+from .resources.events import AsyncEventsResource
+from .resources.locations import AsyncLocationsResource
+from .resources.users import AsyncUsersResource
+
+
+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 AsyncClient:
+    """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.AsyncClient(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 = AsyncUsersResource(self)
+        self.campuses = AsyncCampusesResource(self)
+        self.campus_users = AsyncCampusUsersResource(self)
+        self.events = AsyncEventsResource(self)
+        self.locations = AsyncLocationsResource(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}"
+
+    async 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 = await self._token_manager.aensure_token(self._http)
+            await self._rate_limiter.aacquire()
+            try:
+                response = await 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
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncClient:
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.aclose()

intra42/_async/query.py

@@ -0,0 +1,99 @@
+"""Lazy, chainable, auto-paginating query builder.
+
+``AsyncQuerySet`` is returned by a resource's ``.filter()``/``.sort()``/etc.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Callable
+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 AsyncClient
+
+ModelT = TypeVar("ModelT", bound=FortyTwoModel)
+
+
+class AsyncQuerySet(Generic[ModelT]):
+    def __init__(
+        self,
+        client: AsyncClient,
+        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) -> AsyncQuerySet[ModelT]:
+        clone = AsyncQuerySet(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) -> AsyncQuerySet[ModelT]:
+        """Add ``filter[field]=value`` constraints. Chainable, non-mutating."""
+        clone = self._clone()
+        clone._filters.update(kwargs)
+        return clone
+
+    def sort(self, *fields: str) -> AsyncQuerySet[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) -> AsyncQuerySet[ModelT]:
+        clone = self._clone()
+        clone._page_size = n
+        return clone
+
+    def range(self, field: str, start: Any, end: Any) -> AsyncQuerySet[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,
+        )
+
+    async def __aiter__(self) -> AsyncIterator[ModelT]:
+        url: str | None = self._path
+        params: dict[str, str] | None = self._initial_params()
+        while url is not None:
+            response = await 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
+
+    async def all(self) -> list[ModelT]:
+        return [item async for item in self]
+
+    async def first(self) -> ModelT | None:
+        async for item in self:
+            return item
+        return None

intra42/_async/resources/base.py

@@ -0,0 +1,77 @@
+"""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 AsyncIterator
+from typing import TYPE_CHECKING, Any, ClassVar, Generic, TypeVar, cast
+
+from ...models.base import FortyTwoModel
+from ..query import AsyncQuerySet
+
+if TYPE_CHECKING:
+    from ..client import AsyncClient
+
+ModelT = TypeVar("ModelT", bound=FortyTwoModel)
+
+
+class AsyncResource(Generic[ModelT]):
+    path: ClassVar[str]
+    model: ClassVar[type[FortyTwoModel]]
+
+    def __init__(self, client: AsyncClient) -> 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
+
+    async def get(self, id: int | str) -> ModelT:
+        """Fetch a single resource by id: ``GET {path}/{id}``."""
+        response = await 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) -> AsyncQuerySet[ModelT]:
+        return AsyncQuerySet(
+            self._client,
+            path or self.path,
+            cast(type[ModelT], self.model),
+            bind=self._bind_relations,
+        )
+
+    def filter(self, **kwargs: Any) -> AsyncQuerySet[ModelT]:
+        return self._queryset().filter(**kwargs)
+
+    def sort(self, *fields: str) -> AsyncQuerySet[ModelT]:
+        return self._queryset().sort(*fields)
+
+    def page_size(self, n: int) -> AsyncQuerySet[ModelT]:
+        return self._queryset().page_size(n)
+
+    def range(self, field: str, start: Any, end: Any) -> AsyncQuerySet[ModelT]:
+        return self._queryset().range(field, start, end)
+
+    async def all(self) -> list[ModelT]:
+        return await self._queryset().all()
+
+    async def first(self) -> ModelT | None:
+        return await self._queryset().first()
+
+    def __aiter__(self) -> AsyncIterator[ModelT]:
+        return self._queryset().__aiter__()

intra42/_async/resources/campus_users.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from ...models.campus_user import CampusUser
+from .base import AsyncResource
+
+
+class AsyncCampusUsersResource(AsyncResource[CampusUser]):
+    path = "/campus_users"
+    model = CampusUser

intra42/_async/resources/campuses.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from ...models.campus import Campus
+from .base import AsyncResource
+
+
+class AsyncCampusesResource(AsyncResource[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/_async/resources/events.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from ...models.event import Event
+from .base import AsyncResource
+
+
+class AsyncEventsResource(AsyncResource[Event]):
+    path = "/events"
+    model = Event

intra42/_async/resources/locations.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from ...models.location import Location
+from .base import AsyncResource
+
+
+class AsyncLocationsResource(AsyncResource[Location]):
+    path = "/locations"
+    model = Location
+
+    async 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 = await self._client.request("GET", path)
+        return response.json()

intra42/_async/resources/users.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from ...models.user import User
+from .base import AsyncResource
+
+
+class AsyncUsersResource(AsyncResource[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"),
+        )