python-gitea 0.3.0__py3-none-any.whl

gitea/client/gitea.py

@@ -0,0 +1,93 @@
+"""Gitea API client implementation."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import requests
+from requests import Response
+
+from gitea.client.base import Client
+from gitea.user.user import User
+
+
+class Gitea(Client):  # pylint: disable=too-few-public-methods
+    """Synchronous Gitea API client."""
+
+    def __init__(self, token: str | None = None, base_url: str = "https://gitea.com") -> None:
+        """Initialize the Gitea client.
+
+        Args:
+            token: The API token for authentication.
+            base_url: The base URL of the Gitea instance.
+
+        """
+        super().__init__(token=token, base_url=base_url)
+        self.session: requests.Session | None = None
+        self.user = User(client=self)
+
+    def __str__(self) -> str:
+        """Return a string representation of the Gitea client.
+
+        Returns:
+            A string representing the Gitea client.
+
+        """
+        return f"Gitea Client(base_url={self.base_url})"
+
+    def __enter__(self) -> Gitea:
+        """Enter the context manager.
+
+        Returns:
+            The Gitea client instance.
+
+        """
+        if self.session is not None:
+            raise RuntimeError("Gitea session already open; do not re-enter context manager.")
+        self.session = requests.Session()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Exit the context manager.
+
+        Args:
+            exc_type: The exception type.
+            exc_val: The exception value.
+            exc_tb: The traceback.
+
+        """
+        if self.session:
+            self.session.close()
+            self.session = None
+
+    def _request(
+        self, method: str, endpoint: str, headers: dict | None = None, timeout: int = 30, **kwargs: Any
+    ) -> Response:
+        """Make an HTTP request to the Gitea API.
+
+        Args:
+            method: The HTTP method (GET, POST, etc.).
+            endpoint: The API endpoint.
+            headers: Additional headers for the request.
+            timeout: Timeout for the request in seconds.
+            **kwargs: Additional arguments for the request.
+
+        Returns:
+            The HTTP response object.
+
+        """
+        if self.session is None:
+            raise RuntimeError(
+                "Gitea must be used as a context manager. "
+                + "Use 'with Gitea(...) as client:' to ensure proper resource cleanup."
+            )
+        url = self._build_url(endpoint=endpoint)
+        response = self.session.request(
+            method, url, headers={**self.headers, **(headers or {})}, timeout=timeout, **kwargs
+        )
+        try:
+            response.raise_for_status()
+        except Exception:
+            response.close()
+            raise
+        return response

gitea/issue/__init__.py

@@ -0,0 +1,8 @@
+"""Gitea Issue resource."""
+
+from __future__ import annotations
+
+from gitea.issue.async_issue import AsyncIssue
+from gitea.issue.issue import Issue
+
+__all__ = ["AsyncIssue", "Issue"]

gitea/issue/async_issue.py

@@ -0,0 +1,277 @@
+"""Asynchronous Gitea Issue resource."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Literal, cast
+
+from aiohttp import ClientResponse
+
+from gitea.issue.base import BaseIssue
+from gitea.resource.async_resource import AsyncResource
+from gitea.utils.response import process_async_response
+
+
+class AsyncIssue(BaseIssue, AsyncResource):
+    """Asynchronous Gitea Issue resource."""
+
+    async def _list_issues(  # noqa: PLR0913
+        self,
+        owner: str,
+        repository: str,
+        state: Literal["closed", "open", "all"] | None = None,
+        labels: list[str] | None = None,
+        search_string: str | None = None,
+        issue_type: Literal["issues", "pulls"] | None = None,
+        milestones: list[str] | list[int] | None = None,
+        since: datetime | None = None,
+        before: datetime | None = None,
+        created_by: str | None = None,
+        assigned_by: str | None = None,
+        mentioned_by: str | None = None,
+        page: int | None = None,
+        limit: int | None = None,
+        **kwargs: Any,
+    ) -> ClientResponse:
+        """List issues in a repository.
+
+        Args:
+            owner: The owner of the repository.
+            repository: The name of the repository.
+            state: Filter issues by state.
+            labels: Filter issues by labels.
+            search_string: Filter issues by search string.
+            issue_type: Filter by issue type.
+            milestones: Filter issues by milestones.
+            since: Filter issues updated since this time.
+            before: Filter issues updated before this time.
+            created_by: Filter issues created by this user.
+            assigned_by: Filter issues assigned to this user.
+            mentioned_by: Filter issues mentioning this user.
+            page: The page number for pagination.
+            limit: The number of issues per page.
+            **kwargs: Additional arguments for the request.
+
+        Returns:
+            The HTTP response object.
+
+        """
+        endpoint, params = self._list_issues_helper(
+            owner=owner,
+            repository=repository,
+            state=state,
+            labels=labels,
+            search_string=search_string,
+            issue_type=issue_type,
+            milestones=milestones,
+            since=since,
+            before=before,
+            created_by=created_by,
+            assigned_by=assigned_by,
+            mentioned_by=mentioned_by,
+            page=page,
+            limit=limit,
+        )
+        return await self._get(endpoint=endpoint, params=params, **kwargs)
+
+    async def list_issues(  # noqa: PLR0913
+        self,
+        owner: str,
+        repository: str,
+        state: Literal["closed", "open", "all"] | None = None,
+        labels: list[str] | None = None,
+        search_string: str | None = None,
+        issue_type: Literal["issues", "pulls"] | None = None,
+        milestones: list[str] | list[int] | None = None,
+        since: datetime | None = None,
+        before: datetime | None = None,
+        created_by: str | None = None,
+        assigned_by: str | None = None,
+        mentioned_by: str | None = None,
+        page: int | None = None,
+        limit: int | None = None,
+        **kwargs: Any,
+    ) -> tuple[list[dict[str, Any]], int]:
+        """List issues in a repository.
+
+        Args:
+            owner: The owner of the repository.
+            repository: The name of the repository.
+            state: Filter issues by state.
+            labels: Filter issues by labels.
+            search_string: Filter issues by search string.
+            issue_type: Filter by issue type.
+            milestones: Filter issues by milestones.
+            since: Filter issues updated since this time.
+            before: Filter issues updated before this time.
+            created_by: Filter issues created by this user.
+            assigned_by: Filter issues assigned to this user.
+            mentioned_by: Filter issues mentioning this user.
+            page: The page number for pagination.
+            limit: The number of issues per page.
+            **kwargs: Additional arguments for the request.
+
+        Returns:
+            A tuple containing the list of issues as a list of dictionaries and the status code.
+
+        """
+        response = await self._list_issues(
+            owner=owner,
+            repository=repository,
+            state=state,
+            labels=labels,
+            search_string=search_string,
+            issue_type=issue_type,
+            milestones=milestones,
+            since=since,
+            before=before,
+            created_by=created_by,
+            assigned_by=assigned_by,
+            mentioned_by=mentioned_by,
+            page=page,
+            limit=limit,
+            **kwargs,
+        )
+        data, status_code = await process_async_response(response)
+        return cast(list[dict[str, Any]], data), status_code
+
+    async def _get_issue(self, owner: str, repository: str, index: int, **kwargs: Any) -> ClientResponse:
+        """Get a single issue by its index.
+
+        Args:
+            owner: The owner of the repository.
+            repository: The name of the repository.
+            index: The index of the issue.
+            **kwargs: Additional arguments for the request.
+
+        Returns:
+            The HTTP response object.
+
+        """
+        endpoint = self._get_issue_helper(owner=owner, repository=repository, index=index)
+        return await self._get(endpoint=endpoint, **kwargs)
+
+    async def get_issue(self, owner: str, repository: str, index: int, **kwargs: Any) -> tuple[dict[str, Any], int]:
+        """Get a single issue by its index.
+
+        Args:
+            owner: The owner of the repository.
+            repository: The name of the repository.
+            index: The index of the issue.
+            **kwargs: Additional arguments for the request.
+
+        Returns:
+            A tuple containing the issue as a dictionary and the status code.
+
+        """
+        response = await self._get_issue(owner=owner, repository=repository, index=index, **kwargs)
+        data, status_code = await process_async_response(response)
+        return cast(dict[str, Any], data), status_code
+
+    async def _edit_issue(  # noqa: PLR0913
+        self,
+        owner: str,
+        repository: str,
+        index: int,
+        assignee: str | None = None,
+        assignees: list[str] | None = None,
+        body: str | None = None,
+        due_date: datetime | None = None,
+        milestone: int | None = None,
+        ref: str | None = None,
+        state: Literal["closed", "open"] | None = None,
+        title: str | None = None,
+        unset_due_date: bool | None = None,
+        **kwargs: Any,
+    ) -> ClientResponse:
+        """Edit a specific issue in a repository.
+
+        Args:
+            owner: The owner of the repository.
+            repository: The name of the repository.
+            index: The index of the issue.
+            assignee: The new assignee of the issue.
+            assignees: The new assignees of the issue.
+            body: The new body of the issue.
+            due_date: The new due date of the issue.
+            milestone: The new milestone of the issue.
+            ref: The new reference of the issue.
+            state: The new state of the issue.
+            title: The new title of the issue.
+            unset_due_date: Whether to unset the due date of the issue.
+            **kwargs: Additional arguments for the request.
+
+        Returns:
+            The HTTP response object.
+
+        """
+        endpoint, payload = self._edit_issue_helper(
+            owner=owner,
+            repository=repository,
+            index=index,
+            assignee=assignee,
+            assignees=assignees,
+            body=body,
+            due_date=due_date,
+            milestone=milestone,
+            ref=ref,
+            state=state,
+            title=title,
+            unset_due_date=unset_due_date,
+        )
+        return await self._patch(endpoint=endpoint, json=payload, **kwargs)
+
+    async def edit_issue(  # noqa: PLR0913
+        self,
+        owner: str,
+        repository: str,
+        index: int,
+        assignee: str | None = None,
+        assignees: list[str] | None = None,
+        body: str | None = None,
+        due_date: datetime | None = None,
+        milestone: int | None = None,
+        ref: str | None = None,
+        state: Literal["closed", "open"] | None = None,
+        title: str | None = None,
+        unset_due_date: bool | None = None,
+        **kwargs: Any,
+    ) -> tuple[dict[str, Any], int]:
+        """Edit a specific issue in a repository.
+
+        Args:
+            owner: The owner of the repository.
+            repository: The name of the repository.
+            index: The index of the issue.
+            assignee: The new assignee of the issue.
+            assignees: The new assignees of the issue.
+            body: The new body of the issue.
+            due_date: The new due date of the issue.
+            milestone: The new milestone of the issue.
+            ref: The new reference of the issue.
+            state: The new state of the issue.
+            title: The new title of the issue.
+            unset_due_date: Whether to unset the due date of the issue.
+            **kwargs: Additional arguments for the request.
+
+        Returns:
+            A tuple containing the edited issue as a dictionary and the status code.
+
+        """
+        response = await self._edit_issue(
+            owner=owner,
+            repository=repository,
+            index=index,
+            assignee=assignee,
+            assignees=assignees,
+            body=body,
+            due_date=due_date,
+            milestone=milestone,
+            ref=ref,
+            state=state,
+            title=title,
+            unset_due_date=unset_due_date,
+            **kwargs,
+        )
+        data, status_code = await process_async_response(response)
+        return cast(dict[str, Any], data), status_code

gitea/issue/base.py

@@ -0,0 +1,201 @@
+"""Base class for Gitea Issue resource."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Literal
+
+
+class BaseIssue:
+    """Base class for Gitea Issue resource."""
+
+    def _list_issues_endpoint(self, owner: str, repository: str) -> str:
+        """Construct the endpoint URL for listing issues in a repository.
+
+        Args:
+            owner: The owner of the repository.
+            repository: The name of the repository.
+
+        Returns:
+            The endpoint URL for listing issues.
+
+        """
+        return f"/repos/{owner}/{repository}/issues"
+
+    def _list_issues_helper(  # noqa: PLR0913
+        self,
+        owner: str,
+        repository: str,
+        state: Literal["closed", "open", "all"] | None = None,
+        labels: list[str] | None = None,
+        search_string: str | None = None,
+        issue_type: Literal["issues", "pulls"] | None = None,
+        milestones: list[str] | list[int] | None = None,
+        since: datetime | None = None,
+        before: datetime | None = None,
+        created_by: str | None = None,
+        assigned_by: str | None = None,
+        mentioned_by: str | None = None,
+        page: int | None = None,
+        limit: int | None = None,
+    ) -> tuple[str, dict[str, Any]]:
+        """Get the endpoint and parameters for listing issues in a repository.
+
+        Args:
+            owner: The owner of the repository.
+            repository: The name of the repository.
+            state: Filter issues by state.
+            labels: Filter issues by labels.
+            search_string: Filter issues by search string.
+            issue_type: Filter by issue type.
+            milestones: Filter issues by milestones.
+            since: Filter issues updated since this time.
+            before: Filter issues updated before this time.
+            created_by: Filter issues created by this user.
+            assigned_by: Filter issues assigned to this user.
+            mentioned_by: Filter issues mentioning this user.
+            page: The page number for pagination.
+            limit: The number of issues per page.
+
+        Returns:
+            A tuple containing the endpoint and the request arguments.
+
+                - The API endpoint for listing issues.
+                - A dictionary of request arguments.
+
+        """
+        endpoint = self._list_issues_endpoint(owner=owner, repository=repository)
+
+        params = {}
+        if state is not None:
+            params["state"] = state
+        if labels is not None:
+            params["labels"] = ",".join(labels)
+        if search_string is not None:
+            params["q"] = search_string
+        if issue_type is not None:
+            params["type"] = issue_type
+        if milestones is not None:
+            params["milestone"] = ",".join(str(m) for m in milestones)
+        if since is not None:
+            params["since"] = since.isoformat()
+        if before is not None:
+            params["before"] = before.isoformat()
+        if created_by is not None:
+            params["created_by"] = created_by
+        if assigned_by is not None:
+            params["assigned_by"] = assigned_by
+        if mentioned_by is not None:
+            params["mentioned_by"] = mentioned_by
+        if page is not None:
+            params["page"] = page
+        if limit is not None:
+            params["limit"] = limit
+
+        return endpoint, params
+
+    def _get_issue_endpoint(self, owner: str, repository: str, index: int) -> str:
+        """Construct the endpoint URL for a specific issue in a repository.
+
+        Args:
+            owner: The owner of the repository.
+            repository: The name of the repository.
+            index: The index of the issue.
+
+        Returns:
+            The endpoint URL for the specific issue.
+
+        """
+        return f"/repos/{owner}/{repository}/issues/{index}"
+
+    def _get_issue_helper(self, owner: str, repository: str, index: int) -> str:
+        """Get the endpoint and parameters for retrieving a specific issue in a repository.
+
+        Args:
+            owner: The owner of the repository.
+            repository: The name of the repository.
+            index: The index of the issue.
+
+        Returns:
+            The API endpoint for retrieving the specific issue.
+
+        """
+        endpoint = self._get_issue_endpoint(owner=owner, repository=repository, index=index)
+        return endpoint
+
+    def _edit_issue_endpoint(self, owner: str, repository: str, index: int) -> str:
+        """Construct the endpoint URL for editing a specific issue in a repository.
+
+        Args:
+            owner: The owner of the repository.
+            repository: The name of the repository.
+            index: The index of the issue.
+
+        Returns:
+            The endpoint URL for editing the specific issue.
+
+        """
+        return f"/repos/{owner}/{repository}/issues/{index}"
+
+    def _edit_issue_helper(  # noqa: PLR0913
+        self,
+        owner: str,
+        repository: str,
+        index: int,
+        assignee: str | None = None,
+        assignees: list[str] | None = None,
+        body: str | None = None,
+        due_date: datetime | None = None,
+        milestone: int | None = None,
+        ref: str | None = None,
+        state: Literal["closed", "open"] | None = None,
+        title: str | None = None,
+        unset_due_date: bool | None = None,
+    ) -> tuple[str, dict[str, Any]]:
+        """Get the endpoint and parameters for editing a specific issue in a repository.
+
+        Args:
+            owner: The owner of the repository.
+            repository: The name of the repository.
+            index: The index of the issue.
+            assignee: The new assignee of the issue.
+            assignees: The new assignees of the issue.
+            body: The new body of the issue.
+            due_date: The new due date of the issue.
+            milestone: The new milestone of the issue.
+            ref: The new reference of the issue.
+            state: The new state of the issue.
+            title: The new title of the issue.
+            unset_due_date: Whether to unset the due date of the issue.
+
+        Returns:
+            A tuple containing the endpoint and the request arguments.
+
+                - The API endpoint for editing the specific issue.
+                - A dictionary of request arguments.
+
+        """
+        endpoint = self._edit_issue_endpoint(owner=owner, repository=repository, index=index)
+
+        payload = {}
+
+        if assignee is not None:
+            payload["assignee"] = assignee
+        if assignees is not None:
+            payload["assignees"] = assignees
+        if body is not None:
+            payload["body"] = body
+        if due_date is not None:
+            payload["due_date"] = due_date.isoformat()
+        if milestone is not None:
+            payload["milestone"] = milestone
+        if ref is not None:
+            payload["ref"] = ref
+        if state is not None:
+            payload["state"] = state
+        if title is not None:
+            payload["title"] = title
+        if unset_due_date is not None:
+            payload["unset_due_date"] = unset_due_date
+
+        return endpoint, payload