ghnova 0.3.0__py3-none-any.whl

ghnova/repository/async_repository.py

@@ -0,0 +1,134 @@
+"""Asynchronous GitHub Repository resource."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Literal, cast
+
+from aiohttp import ClientResponse
+
+from ghnova.repository.base import BaseRepository
+from ghnova.resource.async_resource import AsyncResource
+from ghnova.utils.response import process_async_response_with_last_modified
+
+
+class AsyncRepository(BaseRepository, AsyncResource):
+    """GitHub Repository resource."""
+
+    async def _list_repositories(  # noqa: PLR0913
+        self,
+        owner: str | None = None,
+        organization: str | None = None,
+        visibility: Literal["all", "public", "private"] | None = None,
+        affiliation: list[Literal["owner", "collaborator", "organization_member"]] | None = None,
+        repository_type: Literal["all", "owner", "public", "private", "member"] | None = None,
+        sort: Literal["created", "updated", "pushed", "full_name"] | None = None,
+        direction: Literal["asc", "desc"] | None = None,
+        per_page: int = 30,
+        page: int = 1,
+        since: datetime | None = None,
+        before: datetime | None = None,
+        etag: str | None = None,
+        last_modified: str | None = None,
+        **kwargs: Any,
+    ) -> ClientResponse:
+        """List repositories information.
+
+        Args:
+            owner: The owner of the repositories to retrieve. If None, retrieves the authenticated user's repositories.
+            organization: The organization of the repositories to retrieve. If None, retrieves by owner.
+            visibility: The visibility of the repositories. Can be one of "all", "public", or "private".
+            affiliation: A list of affiliations for the repositories. Can include "owner", "collaborator", and/or "organization_member".
+            repository_type: The type of repositories to retrieve. Can be one of "all", "owner", "public", "private", or "member".
+            sort: The field to sort the repositories by. Can be one of "created", "updated", "pushed", or "full_name".
+            direction: The direction to sort the repositories. Can be either "asc" or "desc".
+            per_page: The number of results per page (max 100).
+            page: The page number of the results to fetch.
+            since: Only show repositories updated after this time.
+            before: Only show repositories updated before this time.
+            etag: The ETag header value for conditional requests.
+            last_modified: The Last-Modified header value for conditional requests.
+            **kwargs: Additional arguments for the request.
+
+        Returns:
+            The ClientResponse object containing the list of repositories.
+
+        """
+        endpoint, params, kwargs = self._list_repositories_helper(
+            owner=owner,
+            organization=organization,
+            visibility=visibility,
+            affiliation=affiliation,
+            repository_type=repository_type,
+            sort=sort,
+            direction=direction,
+            per_page=per_page,
+            page=page,
+            since=since,
+            before=before,
+            **kwargs,
+        )
+        return await self._get(endpoint, params=params, etag=etag, last_modified=last_modified, **kwargs)
+
+    async def list_repositories(  # noqa: PLR0913
+        self,
+        owner: str | None = None,
+        organization: str | None = None,
+        visibility: Literal["all", "public", "private"] | None = None,
+        affiliation: list[Literal["owner", "collaborator", "organization_member"]] | None = None,
+        repository_type: Literal["all", "owner", "public", "private", "member"] | None = None,
+        sort: Literal["created", "updated", "pushed", "full_name"] | None = None,
+        direction: Literal["asc", "desc"] | None = None,
+        per_page: int = 30,
+        page: int = 1,
+        since: datetime | None = None,
+        before: datetime | None = None,
+        etag: str | None = None,
+        last_modified: str | None = None,
+        **kwargs: Any,
+    ) -> tuple[list[dict[str, Any]], int, str | None, str | None]:
+        """List repositories information.
+
+        Args:
+            owner: The owner of the repositories to retrieve. If None, retrieves the authenticated user's repositories.
+            organization: The organization of the repositories to retrieve. If None, retrieves by owner.
+            visibility: The visibility of the repositories. Can be one of "all", "public", or "private".
+            affiliation: A list of affiliations for the repositories. Can include "owner", "collaborator", and/or "organization_member".
+            repository_type: The type of repositories to retrieve. Can be one of "all", "owner", "public", "private", or "member".
+            sort: The field to sort the repositories by. Can be one of "created", "updated", "pushed", or "full_name".
+            direction: The direction to sort the repositories. Can be either "asc" or "desc".
+            per_page: The number of results per page (max 100).
+            page: The page number of the results to fetch.
+            since: Only show repositories updated after this time.
+            before: Only show repositories updated before this time.
+            etag: The ETag header value for conditional requests.
+            last_modified: The Last-Modified header value for conditional requests.
+            **kwargs: Additional arguments for the request.
+
+        Returns:
+            A tuple containing:
+
+                - A list of dictionaries representing the repositories.
+                - The HTTP status code of the response.
+                - The ETag header value from the response, if available.
+                - The Last-Modified header value from the response, if available.
+
+        """
+        response = await self._list_repositories(
+            owner=owner,
+            organization=organization,
+            visibility=visibility,
+            affiliation=affiliation,
+            repository_type=repository_type,
+            sort=sort,
+            direction=direction,
+            per_page=per_page,
+            page=page,
+            since=since,
+            before=before,
+            etag=etag,
+            last_modified=last_modified,
+            **kwargs,
+        )
+        data, status_code, etag_value, last_modified_value = await process_async_response_with_last_modified(response)
+        return cast(list[dict[str, Any]], data), status_code, etag_value, last_modified_value

ghnova/repository/base.py

@@ -0,0 +1,124 @@
+"""Base class for GitHub Repository resource."""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+from typing import Any, Literal
+
+logger = logging.getLogger("ghnova")
+
+
+class BaseRepository:
+    """Base class for GitHub Repository resource."""
+
+    def _list_repositories_endpoint(self, owner: str | None = None, organization: str | None = None) -> tuple[str, str]:
+        """Determine the repositories endpoint based on owner or organization.
+
+        If both owner and organization are None, returns the authenticated user's repositories.
+        If owner is provided, returns that user's repositories.
+        If organization is provided, returns that organization's repositories.
+
+        Args:
+            owner: The owner of the repositories.
+            organization: The organization of the repositories.
+
+        Returns:
+            The API endpoint for the repositories and a description.
+
+        """
+        if owner is None and organization is None:
+            return "/user/repos", "authenticated user's repositories"
+        if owner is not None and organization is None:
+            return f"/users/{owner}/repos", "user's repositories"
+        if owner is None and organization is not None:
+            return f"/orgs/{organization}/repos", "organization's repositories"
+        raise ValueError("Specify either owner or organization, not both.")
+
+    def _list_repositories_helper(  # noqa: PLR0912, PLR0913
+        self,
+        owner: str | None = None,
+        organization: str | None = None,
+        visibility: Literal["all", "public", "private"] | None = None,
+        affiliation: list[Literal["owner", "collaborator", "organization_member"]] | None = None,
+        repository_type: Literal["all", "owner", "public", "private", "member"] | None = None,
+        sort: Literal["created", "updated", "pushed", "full_name"] | None = None,
+        direction: Literal["asc", "desc"] | None = None,
+        per_page: int = 30,
+        page: int = 1,
+        since: datetime | None = None,
+        before: datetime | None = None,
+        **kwargs: Any,
+    ) -> tuple[str, dict[str, Any], dict[str, Any]]:
+        """List repositories information.
+
+        Args:
+            owner: The owner of the repositories to retrieve. If None, retrieves the authenticated user's repositories.
+            organization: The organization of the repositories to retrieve. If None, retrieves by owner.
+            visibility: The visibility of the repositories. Can be one of "all", "public", or "private".
+            affiliation: A list of affiliations for the repositories. Can include "owner", "collaborator", and/or "organization_member".
+            repository_type: The type of repositories to retrieve. Can be one of "all", "owner", "public", "private", or "member".
+            sort: The field to sort the repositories by. Can be one of "created", "updated", "pushed", or "full_name".
+            direction: The direction to sort the repositories. Can be either "asc" or "desc".
+            per_page: The number of repositories to return per page.
+            page: The page number to retrieve.
+            since: A datetime to filter repositories updated after this time.
+            before: A datetime to filter repositories updated before this time.
+            **kwargs: Additional arguments for the request.
+
+        Returns:
+            A tuple containing the endpoint and the request arguments.
+
+                - The API endpoint for the repositories.
+                - The query parameters for the request.
+                - A dictionary of request arguments.
+
+        """
+        endpoint, description = self._list_repositories_endpoint(owner=owner, organization=organization)
+        default_headers = {
+            "Accept": "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        }
+        headers = kwargs.get("headers") or {}
+        headers = {**default_headers, **headers}
+        kwargs["headers"] = headers
+
+        params = {}
+        if visibility is not None:
+            if description != "authenticated user's repositories":
+                logger.warning(
+                    "The 'visibility' parameter is not applicable when listing an organization's repositories."
+                )
+            else:
+                params["visibility"] = visibility
+        if affiliation is not None:
+            if description != "authenticated user's repositories":
+                logger.warning(
+                    "The 'affiliation' parameter is only applicable when listing the authenticated user's repositories."
+                )
+            else:
+                params["affiliation"] = ",".join(affiliation)
+        if repository_type is not None:
+            params["type"] = repository_type
+        if sort is not None:
+            params["sort"] = sort
+        if direction is not None:
+            params["direction"] = direction
+        params["per_page"] = per_page
+        params["page"] = page
+
+        extra_params = kwargs.pop("params", {})
+        params = {**params, **extra_params}
+
+        if since is not None:
+            if description != "authenticated user's repositories":
+                logger.warning("The 'since' parameter is not applicable when listing an organization's repositories.")
+            else:
+                params["since"] = since.isoformat()
+        if before is not None:
+            if description != "authenticated user's repositories":
+                logger.warning("The 'before' parameter is not applicable when listing an organization's repositories.")
+            else:
+                params["before"] = before.isoformat()
+
+        return endpoint, params, kwargs

ghnova/repository/repository.py

@@ -0,0 +1,134 @@
+"""GitHub Repository resource."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Literal, cast
+
+from requests import Response
+
+from ghnova.repository.base import BaseRepository
+from ghnova.resource.resource import Resource
+from ghnova.utils.response import process_response_with_last_modified
+
+
+class Repository(BaseRepository, Resource):
+    """GitHub Repository resource."""
+
+    def _list_repositories(  # noqa: PLR0913
+        self,
+        owner: str | None = None,
+        organization: str | None = None,
+        visibility: Literal["all", "public", "private"] | None = None,
+        affiliation: list[Literal["owner", "collaborator", "organization_member"]] | None = None,
+        repository_type: Literal["all", "owner", "public", "private", "member"] | None = None,
+        sort: Literal["created", "updated", "pushed", "full_name"] | None = None,
+        direction: Literal["asc", "desc"] | None = None,
+        per_page: int = 30,
+        page: int = 1,
+        since: datetime | None = None,
+        before: datetime | None = None,
+        etag: str | None = None,
+        last_modified: str | None = None,
+        **kwargs: Any,
+    ) -> Response:
+        """List repositories information.
+
+        Args:
+            owner: The owner of the repositories to retrieve. If None, retrieves the authenticated user's repositories.
+            organization: The organization of the repositories to retrieve. If None, retrieves by owner.
+            visibility: The visibility of the repositories. Can be one of "all", "public", or "private".
+            affiliation: A list of affiliations for the repositories. Can include "owner", "collaborator", and/or "organization_member".
+            repository_type: The type of repositories to retrieve. Can be one of "all", "owner", "public", "private", or "member".
+            sort: The field to sort the repositories by. Can be one of "created", "updated", "pushed", or "full_name".
+            direction: The direction to sort the repositories. Can be either "asc" or "desc".
+            per_page: The number of results per page (max 100).
+            page: The page number of the results to fetch.
+            since: Only show repositories updated after this time.
+            before: Only show repositories updated before this time.
+            etag: The ETag header value for conditional requests.
+            last_modified: The Last-Modified header value for conditional requests.
+            **kwargs: Additional arguments for the request.
+
+        Returns:
+            The Response object containing the list of repositories.
+
+        """
+        endpoint, params, kwargs = self._list_repositories_helper(
+            owner=owner,
+            organization=organization,
+            visibility=visibility,
+            affiliation=affiliation,
+            repository_type=repository_type,
+            sort=sort,
+            direction=direction,
+            per_page=per_page,
+            page=page,
+            since=since,
+            before=before,
+            **kwargs,
+        )
+        return self._get(endpoint, params=params, etag=etag, last_modified=last_modified, **kwargs)
+
+    def list_repositories(  # noqa: PLR0913
+        self,
+        owner: str | None = None,
+        organization: str | None = None,
+        visibility: Literal["all", "public", "private"] | None = None,
+        affiliation: list[Literal["owner", "collaborator", "organization_member"]] | None = None,
+        repository_type: Literal["all", "owner", "public", "private", "member"] | None = None,
+        sort: Literal["created", "updated", "pushed", "full_name"] | None = None,
+        direction: Literal["asc", "desc"] | None = None,
+        per_page: int = 30,
+        page: int = 1,
+        since: datetime | None = None,
+        before: datetime | None = None,
+        etag: str | None = None,
+        last_modified: str | None = None,
+        **kwargs: Any,
+    ) -> tuple[list[dict[str, Any]], int, str | None, str | None]:
+        """List repositories information.
+
+        Args:
+            owner: The owner of the repositories to retrieve. If None, retrieves the authenticated user's repositories.
+            organization: The organization of the repositories to retrieve. If None, retrieves by owner.
+            visibility: The visibility of the repositories. Can be one of "all", "public", or "private".
+            affiliation: A list of affiliations for the repositories. Can include "owner", "collaborator", and/or "organization_member".
+            repository_type: The type of repositories to retrieve. Can be one of "all", "owner", "public", "private", or "member".
+            sort: The field to sort the repositories by. Can be one of "created", "updated", "pushed", or "full_name".
+            direction: The direction to sort the repositories. Can be either "asc" or "desc".
+            per_page: The number of results per page (max 100).
+            page: The page number of the results to fetch.
+            since: Only show repositories updated after this time.
+            before: Only show repositories updated before this time.
+            etag: The ETag header value for conditional requests.
+            last_modified: The Last-Modified header value for conditional requests.
+            **kwargs: Additional arguments for the request.
+
+        Returns:
+            A tuple containing:
+
+                - A list of dictionaries representing the repositories.
+                - The HTTP status code of the response.
+                - The ETag header value from the response, if available.
+                - The Last-Modified header value from the response, if available.
+
+        """
+        response = self._list_repositories(
+            owner=owner,
+            organization=organization,
+            visibility=visibility,
+            affiliation=affiliation,
+            repository_type=repository_type,
+            sort=sort,
+            direction=direction,
+            per_page=per_page,
+            page=page,
+            since=since,
+            before=before,
+            etag=etag,
+            last_modified=last_modified,
+            **kwargs,
+        )
+        data, status_code, etag_value, last_modified_value = process_response_with_last_modified(response)
+        return cast(list[dict[str, Any]], data), status_code, etag_value, last_modified_value

ghnova/resource/__init__.py

@@ -0,0 +1,8 @@
+"""Resource package initialization."""
+
+from __future__ import annotations
+
+from ghnova.resource.async_resource import AsyncResource
+from ghnova.resource.resource import Resource
+
+__all__ = ["AsyncResource", "Resource"]

ghnova/resource/async_resource.py

@@ -0,0 +1,88 @@
+"""Asynchronous Resource Base Class for GitHub API interactions."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from aiohttp import ClientResponse
+
+if TYPE_CHECKING:
+    from ghnova.client.async_github import AsyncGitHub
+
+
+class AsyncResource:
+    """Base class for asynchronous GitHub API resources."""
+
+    def __init__(self, client: AsyncGitHub) -> None:
+        """Initialize the Resource with a AsyncGitHub client.
+
+        Args:
+            client: An instance of the AsyncGitHub client.
+
+        """
+        self.client = client
+
+    async def _get(self, endpoint: str, **kwargs: Any) -> ClientResponse:
+        """Perform a GET request.
+
+        Args:
+            endpoint: The API endpoint.
+            **kwargs: Additional arguments for the request.
+
+        Returns:
+            The ClientResponse object.
+
+        """
+        return await self.client._request(method="GET", endpoint=endpoint, **kwargs)
+
+    async def _post(self, endpoint: str, **kwargs: Any) -> ClientResponse:
+        """Perform a POST request.
+
+        Args:
+            endpoint: The API endpoint.
+            **kwargs: Additional arguments for the request.
+
+        Returns:
+            The ClientResponse object.
+
+        """
+        return await self.client._request(method="POST", endpoint=endpoint, **kwargs)
+
+    async def _put(self, endpoint: str, **kwargs: Any) -> ClientResponse:
+        """Perform a PUT request.
+
+        Args:
+            endpoint: The API endpoint.
+            **kwargs: Additional arguments for the request.
+
+        Returns:
+            The ClientResponse object.
+
+        """
+        return await self.client._request(method="PUT", endpoint=endpoint, **kwargs)
+
+    async def _delete(self, endpoint: str, **kwargs: Any) -> ClientResponse:
+        """Perform a DELETE request.
+
+        Args:
+            endpoint: The API endpoint.
+            **kwargs: Additional arguments for the request.
+
+        Returns:
+            The ClientResponse object.
+
+        """
+        return await self.client._request(method="DELETE", endpoint=endpoint, **kwargs)
+
+    async def _patch(self, endpoint: str, **kwargs: Any) -> ClientResponse:
+        """Perform a PATCH request.
+
+        Args:
+            endpoint: The API endpoint.
+            **kwargs: Additional arguments for the request.
+
+        Returns:
+            The ClientResponse object.
+
+        """
+        return await self.client._request(method="PATCH", endpoint=endpoint, **kwargs)

ghnova/resource/resource.py

@@ -0,0 +1,88 @@
+"""Base class for GitHub API resources."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from requests import Response
+
+if TYPE_CHECKING:
+    from ghnova.client.github import GitHub
+
+
+class Resource:
+    """Base class for GitHub API resources."""
+
+    def __init__(self, client: GitHub) -> None:
+        """Initialize the Resource with a GitHub client.
+
+        Args:
+            client: An instance of the GitHub client.
+
+        """
+        self.client = client
+
+    def _get(self, endpoint: str, **kwargs: Any) -> Response:
+        """Perform a GET request.
+
+        Args:
+            endpoint: The API endpoint.
+            **kwargs: Additional arguments for the request.
+
+        Returns:
+            The response object.
+
+        """
+        return self.client._request(method="GET", endpoint=endpoint, **kwargs)
+
+    def _post(self, endpoint: str, **kwargs: Any) -> Response:
+        """Perform a POST request.
+
+        Args:
+            endpoint: The API endpoint.
+            **kwargs: Additional arguments for the request.
+
+        Returns:
+            The response object.
+
+        """
+        return self.client._request(method="POST", endpoint=endpoint, **kwargs)
+
+    def _put(self, endpoint: str, **kwargs: Any) -> Response:
+        """Perform a PUT request.
+
+        Args:
+            endpoint: The API endpoint.
+            **kwargs: Additional arguments for the request.
+
+        Returns:
+            The response object.
+
+        """
+        return self.client._request(method="PUT", endpoint=endpoint, **kwargs)
+
+    def _delete(self, endpoint: str, **kwargs: Any) -> Response:
+        """Perform a DELETE request.
+
+        Args:
+            endpoint: The API endpoint.
+            **kwargs: Additional arguments for the request.
+
+        Returns:
+            The response object.
+
+        """
+        return self.client._request(method="DELETE", endpoint=endpoint, **kwargs)
+
+    def _patch(self, endpoint: str, **kwargs: Any) -> Response:
+        """Perform a PATCH request.
+
+        Args:
+            endpoint: The API endpoint.
+            **kwargs: Additional arguments for the request.
+
+        Returns:
+            The response object.
+
+        """
+        return self.client._request(method="PATCH", endpoint=endpoint, **kwargs)

ghnova/user/__init__.py

@@ -0,0 +1,8 @@
+"""GitHub user module."""
+
+from __future__ import annotations
+
+from ghnova.user.async_user import AsyncUser
+from ghnova.user.user import User
+
+__all__ = ["AsyncUser", "User"]