Add GitHub notifications namespace (#477)

* Add GitHub notifications namespace

* Apply review feedback: use consistent type annotations in notifications namespace (#478)

* Initial plan

* Apply review feedback: use consistent type annotations in notifications namespace

Co-authored-by: ludeeus <15093472+ludeeus@users.noreply.github.com>

* Update aiogithubapi/namespaces/notifications.py

* Update aiogithubapi/namespaces/notifications.py

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: ludeeus <15093472+ludeeus@users.noreply.github.com>
Co-authored-by: Joakim Sørensen <joasoe@proton.me>

---------

Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>

Author: ludeeus

aiogithubapi/__init__.py

@@ -45,6 +45,7 @@
 from .models.login_oauth import GitHubLoginOauthModel
 from .models.meta import GitHubMetaModel
 from .models.milestone import GitHubMilestoneModel
+from .models.notification import GitHubNotificationModel
 from .models.organization import GitHubOrganizationMinimalModel, GitHubOrganizationModel
 from .models.owner import GitHubOwnerModel
 from .models.permissions import GitHubPermissionsModel

aiogithubapi/github.py

@@ -14,6 +14,7 @@
 from .models.meta import GitHubMetaModel
 from .models.rate_limit import GitHubRateLimitModel
 from .models.response import GitHubResponseModel
+from .namespaces.notifications import GitHubNotificationsNamespace
 from .namespaces.orgs import GitHubOrgsNamespace
 from .namespaces.projects import GitHubBaseProjectsNamespace
 from .namespaces.repos import GitHubReposNamespace
@@ -73,12 +74,18 @@ def __init__(
         self._client = GitHubClient(token=token, session=session, api_version=api_version, **kwargs)
 
         # Namespaces
+        self._notifications = GitHubNotificationsNamespace(self._client)
         self._repos = GitHubReposNamespace(self._client)
         self._user = GitHubUserNamespace(self._client)
         self._users = GitHubUsersNamespace(self._client)
         self._orgs = GitHubOrgsNamespace(self._client)
         self._projects = GitHubBaseProjectsNamespace(self._client)
 
+    @property
+    def notifications(self) -> GitHubNotificationsNamespace:
+        """Property to access the notifications namespace."""
+        return self._notifications
+
     @property
     def repos(self) -> GitHubReposNamespace:
         """Property to access the repos namespace."""

aiogithubapi/models/notification.py

@@ -0,0 +1,43 @@
+"""GitHub notification models"""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from .base import GitHubDataModelBase
+from .repository import GitHubRepositoryModel
+
+
+class _Subject(GitHubDataModelBase):
+    """Notification subject."""
+
+    title: str | None = None
+    url: str | None = None
+    latest_comment_url: str | None = None
+    type: str | None = None
+
+
+class GitHubNotificationModel(GitHubDataModelBase):
+    """
+    GitHub notification data class.
+
+    https://docs.github.com/en/rest/activity/notifications
+    """
+
+    id: str | None = None
+    repository: GitHubRepositoryModel | None = None
+    subject: _Subject | None = None
+    reason: str | None = None
+    unread: bool | None = None
+    updated_at: str | None = None
+    last_read_at: str | None = None
+    url: str | None = None
+    subscription_url: str | None = None
+
+    def _generate_repository(self, data: Dict[str, Any] | None) -> GitHubRepositoryModel:
+        """Generate repository data."""
+        return GitHubRepositoryModel(data) if data else None
+
+    def _generate_subject(self, data: Dict[str, Any] | None) -> _Subject:
+        """Generate subject data."""
+        return _Subject(data) if data else None

aiogithubapi/namespaces/notifications.py

@@ -0,0 +1,59 @@
+"""
+Methods for the notifications namespace
+
+https://docs.github.com/en/rest/activity/notifications
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..const import GitHubRequestKwarg
+from ..models.notification import GitHubNotificationModel
+from ..models.response import GitHubResponseModel
+from .base import BaseNamespace
+
+
+class GitHubNotificationsNamespace(BaseNamespace):
+    """Methods for the notifications namespace"""
+
+    async def list(
+        self,
+        *,
+        all: bool = False,
+        participating: bool = False,
+        since: str | None = None,
+        before: str | None = None,
+        page: int = 1,
+        per_page: int = 50,
+        params: dict[str, str] | None = None,
+        **kwargs: Any,
+    ) -> GitHubResponseModel[list[GitHubNotificationModel]]:
+        """
+        List notifications for the authenticated user
+
+        https://docs.github.com/en/rest/activity/notifications#list-notifications-for-the-authenticated-user
+        """
+        request_params = {}
+        if all:
+            request_params["all"] = "true"
+        if participating:
+            request_params["participating"] = "true"
+        if since:
+            request_params["since"] = since
+        if before:
+            request_params["before"] = before
+        if page != 1:
+            request_params["page"] = str(page)
+        if per_page != 50:
+            request_params["per_page"] = str(per_page)
+        if params:
+            request_params.update(params)
+
+        response = await self._client.async_call_api(
+            endpoint="/notifications",
+            params=request_params,
+            **kwargs,
+        )
+        response.data = [GitHubNotificationModel(data) for data in response.data]
+        return response

tests/fixtures/notifications.json

@@ -0,0 +1,39 @@
+[
+  {
+    "id": "1",
+    "repository": {
+      "id": 1296269,
+      "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
+      "name": "Hello-World",
+      "full_name": "octocat/Hello-World",
+      "owner": {
+        "login": "octocat",
+        "id": 1,
+        "node_id": "MDQ6VXNlcjE=",
+        "avatar_url": "https://github.com/images/error/octocat_happy.gif",
+        "gravatar_id": "",
+        "url": "https://api.github.com/users/octocat",
+        "html_url": "https://github.com/octocat",
+        "type": "User",
+        "site_admin": false
+      },
+      "private": false,
+      "html_url": "https://github.com/octocat/Hello-World",
+      "description": "This your first repo!",
+      "fork": false,
+      "url": "https://api.github.com/repos/octocat/Hello-World"
+    },
+    "subject": {
+      "title": "Greetings",
+      "url": "https://api.github.com/repos/octokit/octokit.rb/issues/123",
+      "latest_comment_url": "https://api.github.com/repos/octokit/octokit.rb/issues/comments/123",
+      "type": "Issue"
+    },
+    "reason": "subscribed",
+    "unread": true,
+    "updated_at": "2014-11-07T22:01:45Z",
+    "last_read_at": "2014-11-07T22:01:45Z",
+    "url": "https://api.github.com/notifications/threads/1",
+    "subscription_url": "https://api.github.com/notifications/threads/1/subscription"
+  }
+]

tests/namespaces/test_notifications.py

@@ -0,0 +1,25 @@
+"""Test notifications namespace."""
+# pylint: disable=missing-docstring
+import pytest
+
+from aiogithubapi import GitHubAPI
+from aiogithubapi.models.notification import GitHubNotificationModel
+
+from tests.common import (
+    MockedRequests,
+)
+
+
+@pytest.mark.asyncio
+async def test_list_notifications(github_api: GitHubAPI, mock_requests: MockedRequests):
+    response = await github_api.notifications.list()
+    assert response.status == 200
+    assert isinstance(response.data, list)
+    assert len(response.data) == 1
+    assert isinstance(response.data[0], GitHubNotificationModel)
+    assert response.data[0].id == "1"
+    assert response.data[0].subject.title == "Greetings"
+    assert response.data[0].reason == "subscribed"
+    assert response.data[0].unread is True
+    assert mock_requests.called == 1
+    assert mock_requests.last_request["url"] == "https://api.github.com/notifications"