42api 0.1.1__tar.gz → 0.1.3__tar.gz

{42api-0.1.1 → 42api-0.1.3}/.gitignore

@@ -218,4 +218,7 @@ __marimo__/
 # Streamlit
 .streamlit/secrets.toml
 
-assets/
+assets/
+
+# agent
+.claude

{42api-0.1.1 → 42api-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: 42api
-Version: 0.1.1
+Version: 0.1.3
 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>
@@ -55,7 +55,7 @@ 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"):
+    for user in client.users.filter(primary_campus_id=1).sort("-pool_year"):
         print(user.login)
 ```
 
@@ -69,7 +69,7 @@ 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"):
+        async for user in client.users.filter(primary_campus_id=1).sort("-pool_year"):
             print(user.login)
 
 
@@ -108,10 +108,12 @@ and `NetworkError` (connection/timeout failures).
 
 ## Status
 
-Early-stage: currently covers `users`, `campuses`, `campus_users`,
-`cursus`, `events`, and `locations` (including its `graph` analytics
-endpoint). More resources are added incrementally on top of the same
-client/model/query-builder pattern.
+Early-stage: currently covers `users`, `accreditations`, `campuses`,
+`campus_users`, `cursus`, `events`, `exams`, `locations`, `projects`, and
+`projects_users` (`exams`, `locations`, and `projects_users` each include
+their `graph` analytics endpoint). More resources are added incrementally
+on top of the same client/model/query-builder pattern.
+The api with restricted access are not implemented currently.
 
 ## Development
 

{42api-0.1.1 → 42api-0.1.3}/README.md

@@ -29,7 +29,7 @@ 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"):
+    for user in client.users.filter(primary_campus_id=1).sort("-pool_year"):
         print(user.login)
 ```
 
@@ -43,7 +43,7 @@ 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"):
+        async for user in client.users.filter(primary_campus_id=1).sort("-pool_year"):
             print(user.login)
 
 
@@ -82,10 +82,12 @@ and `NetworkError` (connection/timeout failures).
 
 ## Status
 
-Early-stage: currently covers `users`, `campuses`, `campus_users`,
-`cursus`, `events`, and `locations` (including its `graph` analytics
-endpoint). More resources are added incrementally on top of the same
-client/model/query-builder pattern.
+Early-stage: currently covers `users`, `accreditations`, `campuses`,
+`campus_users`, `cursus`, `events`, `exams`, `locations`, `projects`, and
+`projects_users` (`exams`, `locations`, and `projects_users` each include
+their `graph` analytics endpoint). More resources are added incrementally
+on top of the same client/model/query-builder pattern.
+The api with restricted access are not implemented currently.
 
 ## Development
 

{42api-0.1.1 → 42api-0.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "42api"
-version = "0.1.1"
+version = "0.1.3"
 description = "Object-oriented Python client for the 42 School API (api.intra.42.fr)"
 readme = "README.md"
 license = { text = "MIT" }

{42api-0.1.1 → 42api-0.1.3}/src/intra42/__init__.py

@@ -4,7 +4,7 @@
 
     with Client(client_id, client_secret) as client:
         user = client.users.get("jdoe")
-        for user in client.users.filter(campus_id=1).sort("-level"):
+        for user in client.users.filter(primary_campus_id=1).sort("-pool_year"):
             ...
 
 An async client with the same interface is available as ``AsyncClient``.
@@ -25,11 +25,15 @@ from .exceptions import (
     ServerError,
     ValidationError,
 )
+from .models.accreditation import Accreditation
 from .models.campus import Campus
 from .models.campus_user import CampusUser
 from .models.cursus import Cursus
 from .models.event import Event
+from .models.exam import Exam
 from .models.location import Location
+from .models.project import Project
+from .models.project_user import ProjectUser
 from .models.user import User
 
 __all__ = [
@@ -37,11 +41,15 @@ __all__ = [
     "Client",
     "ClientConfig",
     "User",
+    "Accreditation",
     "Campus",
     "CampusUser",
     "Cursus",
     "Event",
+    "Exam",
     "Location",
+    "Project",
+    "ProjectUser",
     "FortyTwoAPIError",
     "AuthenticationError",
     "PermissionDeniedError",
@@ -52,4 +60,4 @@ __all__ = [
     "NetworkError",
 ]
 
-__version__ = "0.1.1"
+__version__ = "0.1.3"

{42api-0.1.1 → 42api-0.1.3}/src/intra42/_async/client.py

@@ -12,11 +12,15 @@ 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.accreditations import AsyncAccreditationsResource
 from .resources.campus_users import AsyncCampusUsersResource
 from .resources.campuses import AsyncCampusesResource
 from .resources.cursus import AsyncCursusResource
 from .resources.events import AsyncEventsResource
+from .resources.exams import AsyncExamsResource
 from .resources.locations import AsyncLocationsResource
+from .resources.projects import AsyncProjectsResource
+from .resources.projects_users import AsyncProjectUsersResource
 from .resources.users import AsyncUsersResource
 
 
@@ -58,11 +62,15 @@ class AsyncClient:
         )
 
         self.users = AsyncUsersResource(self)
+        self.accreditations = AsyncAccreditationsResource(self)
         self.campuses = AsyncCampusesResource(self)
         self.campus_users = AsyncCampusUsersResource(self)
         self.cursus = AsyncCursusResource(self)
         self.events = AsyncEventsResource(self)
+        self.exams = AsyncExamsResource(self)
         self.locations = AsyncLocationsResource(self)
+        self.projects = AsyncProjectsResource(self)
+        self.projects_users = AsyncProjectUsersResource(self)
 
     @property
     def base_url(self) -> str:

{42api-0.1.1 → 42api-0.1.3}/src/intra42/_async/query.py

@@ -7,6 +7,7 @@ from __future__ import annotations
 
 from collections.abc import AsyncIterator, Callable
 from typing import TYPE_CHECKING, Any, Generic, TypeVar
+from urllib.parse import parse_qsl, urlsplit
 
 from .._pagination import parse_link_header
 from .._query_params import build_query_params
@@ -78,8 +79,20 @@ class AsyncQuerySet(Generic[ModelT]):
         )
 
     async def __aiter__(self) -> AsyncIterator[ModelT]:
+        # `base_params` (filter/sort/page_size/range) is re-applied on every
+        # page, not just the first. Confirmed against the live API: the
+        # `next` link's own query string always uses a *bare* `page=N`
+        # cursor — a different, incompatible pagination scheme from the
+        # bracketed `page[size]`/`page[number]` this library sends, and the
+        # server returns 400 if both appear on the same request. So rather
+        # than forwarding the link's query string as-is (which either loses
+        # page_size or actively errors once you try to keep it), we extract
+        # just the page *number* from the link and reissue it as
+        # `page[number]`, combined with our own persisted page_size/filter/
+        # sort/range.
+        base_params = self._initial_params()
         url: str | None = self._path
-        params: dict[str, str] | None = self._initial_params()
+        params: dict[str, str] | None = base_params
         while url is not None:
             response = await self._client.request("GET", url, params=params)
             for item in response.json():
@@ -87,8 +100,18 @@ class AsyncQuerySet(Generic[ModelT]):
                 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
+
+            next_url = parse_link_header(response.headers.get("Link")).get("next")
+            if next_url is None:
+                break
+
+            split = urlsplit(next_url)
+            url = f"{split.scheme}://{split.netloc}{split.path}" if split.scheme else split.path
+            next_query = dict(parse_qsl(split.query))
+            page_number = next_query.pop("page[number]", None) or next_query.pop("page", None)
+            params = {**next_query, **base_params}
+            if page_number is not None:
+                params["page[number]"] = page_number
 
     async def all(self) -> list[ModelT]:
         return [item async for item in self]

42api-0.1.3/src/intra42/_async/resources/accreditations.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from ...models.accreditation import Accreditation
+from .base import AsyncResource
+
+
+class AsyncAccreditationsResource(AsyncResource[Accreditation]):
+    path = "/accreditations"
+    model = Accreditation
+
+    def _bind_relations(self, instance: Accreditation) -> None:
+        # Referenced in the users apidoc page: GET /accreditations/:id/users.
+        instance._bind_relation(
+            "users",
+            lambda: self._client.users._queryset(f"/accreditations/{instance.id}/users"),
+        )

{42api-0.1.1 → 42api-0.1.3}/src/intra42/_async/resources/cursus.py

@@ -17,3 +17,7 @@ class AsyncCursusResource(AsyncResource[Cursus]):
             "events",
             lambda: self._client.events._queryset(f"/cursus/{instance.id}/events"),
         )
+        instance._bind_relation(
+            "projects",
+            lambda: self._client.projects._queryset(f"/cursus/{instance.id}/projects"),
+        )

42api-0.1.3/src/intra42/_async/resources/exams.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from ...models.exam import Exam
+from .base import AsyncResource
+
+
+class AsyncExamsResource(AsyncResource[Exam]):
+    path = "/exams"
+    model = Exam
+
+    async def graph(
+        self, *, field: str | None = None, interval: str | None = None
+    ) -> dict[str, int]:
+        """Grouped temporal counts (``GET /exams/graph...``)."""
+        path = "/exams/graph"
+        if interval is not None and field is None:
+            field = "created_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()

42api-0.1.3/src/intra42/_async/resources/projects.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from ...models.project import Project
+from .base import AsyncResource
+
+
+class AsyncProjectsResource(AsyncResource[Project]):
+    path = "/projects"
+    model = Project
+
+    def _bind_relations(self, instance: Project) -> None:
+        # Referenced in the projects_users apidoc page:
+        # GET /projects/:id/projects_users.
+        instance._bind_relation(
+            "projects_users",
+            lambda: self._client.projects_users._queryset(
+                f"/projects/{instance.id}/projects_users"
+            ),
+        )

42api-0.1.3/src/intra42/_async/resources/projects_users.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from ...models.project_user import ProjectUser
+from .base import AsyncResource
+
+
+class AsyncProjectUsersResource(AsyncResource[ProjectUser]):
+    path = "/projects_users"
+    model = ProjectUser
+
+    async def graph(
+        self, *, field: str | None = None, interval: str | None = None
+    ) -> dict[str, int]:
+        path = "/projects_users/graph"
+        if interval is not None and field is None:
+            field = "created_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()

{42api-0.1.1 → 42api-0.1.3}/src/intra42/_async/resources/users.py

@@ -21,3 +21,7 @@ class AsyncUsersResource(AsyncResource[User]):
             "locations",
             lambda: self._client.locations._queryset(f"/users/{instance.id}/locations"),
         )
+        instance._bind_relation(
+            "projects_users",
+            lambda: self._client.projects_users._queryset(f"/users/{instance.id}/projects_users"),
+        )

{42api-0.1.1 → 42api-0.1.3}/src/intra42/_sync/client.py

@@ -18,11 +18,15 @@ 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.accreditations import AccreditationsResource
 from .resources.campus_users import CampusUsersResource
 from .resources.campuses import CampusesResource
 from .resources.cursus import CursusResource
 from .resources.events import EventsResource
+from .resources.exams import ExamsResource
 from .resources.locations import LocationsResource
+from .resources.projects import ProjectsResource
+from .resources.projects_users import ProjectUsersResource
 from .resources.users import UsersResource
 
 
@@ -64,11 +68,15 @@ class Client:
         )
 
         self.users = UsersResource(self)
+        self.accreditations = AccreditationsResource(self)
         self.campuses = CampusesResource(self)
         self.campus_users = CampusUsersResource(self)
         self.cursus = CursusResource(self)
         self.events = EventsResource(self)
+        self.exams = ExamsResource(self)
         self.locations = LocationsResource(self)
+        self.projects = ProjectsResource(self)
+        self.projects_users = ProjectUsersResource(self)
 
     @property
     def base_url(self) -> str:

{42api-0.1.1 → 42api-0.1.3}/src/intra42/_sync/query.py

@@ -13,6 +13,7 @@ from __future__ import annotations
 
 from collections.abc import Callable, Iterator
 from typing import TYPE_CHECKING, Any, Generic, TypeVar
+from urllib.parse import parse_qsl, urlsplit
 
 from .._pagination import parse_link_header
 from .._query_params import build_query_params
@@ -84,8 +85,20 @@ class QuerySet(Generic[ModelT]):
         )
 
     def __iter__(self) -> Iterator[ModelT]:
+        # `base_params` (filter/sort/page_size/range) is re-applied on every
+        # page, not just the first. Confirmed against the live API: the
+        # `next` link's own query string always uses a *bare* `page=N`
+        # cursor — a different, incompatible pagination scheme from the
+        # bracketed `page[size]`/`page[number]` this library sends, and the
+        # server returns 400 if both appear on the same request. So rather
+        # than forwarding the link's query string as-is (which either loses
+        # page_size or actively errors once you try to keep it), we extract
+        # just the page *number* from the link and reissue it as
+        # `page[number]`, combined with our own persisted page_size/filter/
+        # sort/range.
+        base_params = self._initial_params()
         url: str | None = self._path
-        params: dict[str, str] | None = self._initial_params()
+        params: dict[str, str] | None = base_params
         while url is not None:
             response = self._client.request("GET", url, params=params)
             for item in response.json():
@@ -93,8 +106,18 @@ class QuerySet(Generic[ModelT]):
                 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
+
+            next_url = parse_link_header(response.headers.get("Link")).get("next")
+            if next_url is None:
+                break
+
+            split = urlsplit(next_url)
+            url = f"{split.scheme}://{split.netloc}{split.path}" if split.scheme else split.path
+            next_query = dict(parse_qsl(split.query))
+            page_number = next_query.pop("page[number]", None) or next_query.pop("page", None)
+            params = {**next_query, **base_params}
+            if page_number is not None:
+                params["page[number]"] = page_number
 
     def all(self) -> list[ModelT]:
         return [item for item in self]

42api-0.1.3/src/intra42/_sync/resources/accreditations.py

@@ -0,0 +1,22 @@
+# 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.accreditation import Accreditation
+from .base import Resource
+
+
+class AccreditationsResource(Resource[Accreditation]):
+    path = "/accreditations"
+    model = Accreditation
+
+    def _bind_relations(self, instance: Accreditation) -> None:
+        # Referenced in the users apidoc page: GET /accreditations/:id/users.
+        instance._bind_relation(
+            "users",
+            lambda: self._client.users._queryset(f"/accreditations/{instance.id}/users"),
+        )

{42api-0.1.1 → 42api-0.1.3}/src/intra42/_sync/resources/cursus.py

@@ -23,3 +23,7 @@ class CursusResource(Resource[Cursus]):
             "events",
             lambda: self._client.events._queryset(f"/cursus/{instance.id}/events"),
         )
+        instance._bind_relation(
+            "projects",
+            lambda: self._client.projects._queryset(f"/cursus/{instance.id}/projects"),
+        )

42api-0.1.3/src/intra42/_sync/resources/exams.py

@@ -0,0 +1,27 @@
+# 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.exam import Exam
+from .base import Resource
+
+
+class ExamsResource(Resource[Exam]):
+    path = "/exams"
+    model = Exam
+
+    def graph(self, *, field: str | None = None, interval: str | None = None) -> dict[str, int]:
+        """Grouped temporal counts (``GET /exams/graph...``)."""
+        path = "/exams/graph"
+        if interval is not None and field is None:
+            field = "created_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()

42api-0.1.3/src/intra42/_sync/resources/projects.py

@@ -0,0 +1,25 @@
+# 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.project import Project
+from .base import Resource
+
+
+class ProjectsResource(Resource[Project]):
+    path = "/projects"
+    model = Project
+
+    def _bind_relations(self, instance: Project) -> None:
+        # Referenced in the projects_users apidoc page:
+        # GET /projects/:id/projects_users.
+        instance._bind_relation(
+            "projects_users",
+            lambda: self._client.projects_users._queryset(
+                f"/projects/{instance.id}/projects_users"
+            ),
+        )

42api-0.1.3/src/intra42/_sync/resources/projects_users.py

@@ -0,0 +1,26 @@
+# 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.project_user import ProjectUser
+from .base import Resource
+
+
+class ProjectUsersResource(Resource[ProjectUser]):
+    path = "/projects_users"
+    model = ProjectUser
+
+    def graph(self, *, field: str | None = None, interval: str | None = None) -> dict[str, int]:
+        path = "/projects_users/graph"
+        if interval is not None and field is None:
+            field = "created_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()

{42api-0.1.1 → 42api-0.1.3}/src/intra42/_sync/resources/users.py

@@ -27,3 +27,7 @@ class UsersResource(Resource[User]):
             "locations",
             lambda: self._client.locations._queryset(f"/users/{instance.id}/locations"),
         )
+        instance._bind_relation(
+            "projects_users",
+            lambda: self._client.projects_users._queryset(f"/users/{instance.id}/projects_users"),
+        )

42api-0.1.3/src/intra42/models/accreditation.py

@@ -0,0 +1,29 @@
+"""The ``Accreditation`` resource."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from .base import FortyTwoModel
+
+if TYPE_CHECKING:
+    from .._async.query import AsyncQuerySet
+    from .._sync.query import QuerySet
+    from .user import User
+
+
+class Accreditation(FortyTwoModel):
+    id: int
+    name: str | None = None
+    user_id: int | None = None
+    cursus_id: int | None = None
+    difficulty: int | None = None
+    validated: bool | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+    @property
+    def users(self) -> AsyncQuerySet[User] | QuerySet[User]:
+        """Users holding this accreditation (``GET /accreditations/{id}/users``)."""
+        return self._relation("users")

{42api-0.1.1 → 42api-0.1.3}/src/intra42/models/cursus.py

@@ -11,6 +11,7 @@ if TYPE_CHECKING:
     from .._async.query import AsyncQuerySet
     from .._sync.query import QuerySet
     from .event import Event
+    from .project import Project
     from .user import User
 
 
@@ -33,3 +34,8 @@ class Cursus(FortyTwoModel):
     def events(self) -> AsyncQuerySet[Event] | QuerySet[Event]:
         """Events for this cursus (``GET /cursus/{id}/events``)."""
         return self._relation("events")
+
+    @property
+    def projects(self) -> AsyncQuerySet[Project] | QuerySet[Project]:
+        """Projects belonging to this cursus (``GET /cursus/{id}/projects``)."""
+        return self._relation("projects")

42api-0.1.3/src/intra42/models/exam.py

@@ -0,0 +1,32 @@
+"""The ``Exam`` resource."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from .base import FortyTwoModel
+from .campus import Campus
+from .cursus import Cursus
+from .project import Project
+
+
+class Exam(FortyTwoModel):
+    id: int
+    name: str | None = None
+    ip_range: str | None = None
+    begin_at: datetime | None = None
+    end_at: datetime | None = None
+    location: str | None = None
+    max_people: int | None = None
+    nbr_subscribers: int | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+    campus_id: int | None = None
+    campus: Campus | None = None
+    cursus: list[Cursus] | None = None
+    projects: list[Project] | None = None
+    visible: bool | None = None
+    validated: bool | None = None
+    validated_at: datetime | None = None
+    validator_id: int | None = None
+    prohibition_of_cancellation: int | None = None