python-gitea 0.3.0__py3-none-any.whl

gitea/__init__.py

@@ -0,0 +1,7 @@
+"""Top-level package for python-gitea."""
+
+from __future__ import annotations
+
+from gitea.version import __version__
+
+__all__ = ["__version__"]

gitea/__main__.py

@@ -0,0 +1,8 @@
+"""Main entry point for the python-gitea package."""
+
+from __future__ import annotations
+
+if __name__ == "__main__":
+    from gitea.utils.log import setup_logger
+
+    setup_logger(print_version=True)

gitea/cli/__init__.py

@@ -0,0 +1 @@
+"""Command line interface for Gitea."""

gitea/cli/main.py

@@ -0,0 +1,128 @@
+"""Main entry point for the python-gitea CLI application."""
+
+from __future__ import annotations
+
+import enum
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+
+class LoggingLevel(str, enum.Enum):
+    """Logging levels for the CLI."""
+
+    NOTSET = "NOTSET"
+    DEBUG = "DEBUG"
+    INFO = "INFO"
+    WARNING = "WARNING"
+    ERROR = "ERROR"
+    CRITICAL = "CRITICAL"
+
+
+# Create the main Typer app
+app = typer.Typer(
+    name="python-gitea",
+    help="Main CLI for python-gitea.",
+    rich_markup_mode="rich",
+)
+
+
+def setup_logging(level: LoggingLevel = LoggingLevel.INFO) -> None:
+    """Set up logging with Rich handler.
+
+    Args:
+        level: Logging level.
+
+    """
+    import logging  # noqa: PLC0415
+
+    from rich.console import Console  # noqa: PLC0415
+    from rich.logging import RichHandler  # noqa: PLC0415
+
+    logger = logging.getLogger("python-gitea")
+
+    logger.setLevel(level.value)
+
+    console = Console()
+
+    # Remove any existing handlers to ensure RichHandler is used
+    for h in logger.handlers[:]:  # Use slice copy to avoid modification during iteration
+        logger.removeHandler(h)
+    # Add the RichHandler
+
+    handler = RichHandler(
+        console=console,
+        rich_tracebacks=True,
+        show_time=True,
+        show_level=True,  # Keep level (e.g., DEBUG, INFO) for clarity
+        markup=True,  # Enable Rich markup in messages for styling
+        level=level.value,  # Ensure handler respects the level
+        omit_repeated_times=False,
+        log_time_format="%H:%M",
+    )
+    handler.setLevel(level.value)
+    logger.addHandler(handler)
+
+    # Prevent propagation to root logger to avoid duplicate output
+    logger.propagate = False
+
+
+@app.callback()
+def main(  # noqa: PLR0913
+    ctx: typer.Context,
+    output: Annotated[Path | None, typer.Option("--output", "-o", help="Output file name.")] = None,
+    token: Annotated[
+        str | None, typer.Option("--token", "-t", help="Gitea API token.", envvar="GITEA_API_TOKEN")
+    ] = None,
+    base_url: Annotated[
+        str,
+        typer.Option(
+            "--base-url",
+            "-b",
+            help="Base URL of the Gitea instance.",
+            envvar="GITEA_BASE_URL",
+            show_default=True,
+        ),
+    ] = "https://gitea.com",
+    timeout: Annotated[
+        int,
+        typer.Option(
+            "--timeout",
+            help="Timeout for API requests in seconds.",
+            show_default=True,
+        ),
+    ] = 30,
+    verbose: Annotated[
+        LoggingLevel,
+        typer.Option("--verbose", "-v", help="Set verbosity level."),
+    ] = LoggingLevel.INFO,
+) -> None:
+    """Enter the CLI application.
+
+    Args:
+        ctx: Typer context.
+        output: Output file name.
+        token: Gitea API token.
+        base_url: Base URL of the Gitea instance.
+        timeout: Timeout for API requests in seconds.
+        verbose: Verbosity level for logging.
+
+    """
+    setup_logging(verbose)
+    ctx.obj = {
+        "output": output,
+        "token": token,
+        "base_url": base_url,
+        "timeout": timeout,
+    }
+
+
+def register_commands() -> None:
+    """Register CLI commands."""
+    from gitea.cli.user.main import user_app  # noqa: PLC0415
+
+    app.add_typer(user_app, name="user", help="Commands for managing Gitea users.")
+
+
+register_commands()

gitea/cli/user/__init__.py

@@ -0,0 +1 @@
+"""User module for CLI commands."""

gitea/cli/user/delete_user_level_runner.py

@@ -0,0 +1,40 @@
+"""Delete user-level runner command for Gitea CLI."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+
+def delete_user_level_runner_command(
+    ctx: typer.Context,
+    runner_id: Annotated[str, typer.Option("--runner-id", help="The ID of the runner to delete.")],
+) -> None:
+    """Delete a user-level runner for the authenticated user.
+
+    Args:
+        ctx: The Typer context.
+        runner_id: The ID of the runner to delete.
+
+    """
+    from typing import Any  # noqa: PLC0415
+
+    import gitea.cli.utils  # noqa: PLC0415
+    import gitea.client.gitea  # noqa: PLC0415
+
+    token: str | None = ctx.obj.get("token")
+    base_url: str = ctx.obj.get("base_url")
+    timeout: int = ctx.obj.get("timeout")
+
+    def api_call() -> dict[str, Any] | None:
+        """Delete a user-level runner.
+
+        Returns:
+            A dictionary containing the result of the deletion.
+
+        """
+        with gitea.client.gitea.Gitea(token=token, base_url=base_url) as client:
+            return client.user.delete_user_level_runner(runner_id=runner_id, timeout=timeout)
+
+    gitea.cli.utils.execute_api_command(ctx=ctx, api_call=api_call, command_name="delete-user-level-runner")

gitea/cli/user/get_registration_token.py

@@ -0,0 +1,31 @@
+"""Get registration token command for Gitea CLI."""
+
+from __future__ import annotations
+
+import typer
+
+
+def get_registration_token_command(
+    ctx: typer.Context,
+) -> None:
+    """Get registration token for the authenticated user."""
+    from typing import Any  # noqa: PLC0415
+
+    import gitea.cli.utils  # noqa: PLC0415
+    import gitea.client.gitea  # noqa: PLC0415
+
+    token: str | None = ctx.obj.get("token")
+    base_url: str = ctx.obj.get("base_url")
+    timeout: int = ctx.obj.get("timeout")
+
+    def api_call() -> dict[str, Any] | None:
+        """Get registration token.
+
+        Returns:
+            A dictionary containing the registration token.
+
+        """
+        with gitea.client.gitea.Gitea(token=token, base_url=base_url) as client:
+            return client.user.get_registration_token(timeout=timeout)
+
+    gitea.cli.utils.execute_api_command(ctx=ctx, api_call=api_call, command_name="get-registration-token")

gitea/cli/user/get_user.py

@@ -0,0 +1,42 @@
+"""Get user information command for Gitea CLI."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+
+def get_user_command(
+    ctx: typer.Context,
+    username: Annotated[
+        str | None, "The username of the user to retrieve. If None, retrieves the authenticated user."
+    ] = None,
+) -> None:
+    """Get user information.
+
+    Args:
+        ctx: The Typer context.
+        username: The username of the user to retrieve. If None, retrieves the authenticated user.
+
+    """
+    from typing import Any  # noqa: PLC0415
+
+    import gitea.cli.utils  # noqa: PLC0415
+    import gitea.client.gitea  # noqa: PLC0415
+
+    token: str | None = ctx.obj.get("token")
+    base_url: str = ctx.obj.get("base_url")
+    timeout: int = ctx.obj.get("timeout")
+
+    def api_call() -> dict[str, Any] | None:
+        """Get user information.
+
+        Returns:
+            The user information as a dictionary.
+
+        """
+        with gitea.client.gitea.Gitea(token=token, base_url=base_url) as client:
+            return client.user.get_user(username=username, timeout=timeout)
+
+    gitea.cli.utils.execute_api_command(ctx=ctx, api_call=api_call, command_name="get-user")

gitea/cli/user/get_user_level_runners.py

@@ -0,0 +1,34 @@
+"""Get user-level runners command for Gitea CLI."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+
+def get_user_level_runners_command(
+    ctx: typer.Context,
+    runner_id: Annotated[str | None, typer.Option("--runner-id", help="The ID of the runner to retrieve.")] = None,
+) -> None:
+    """Get user-level runners for the authenticated user."""
+    from typing import Any  # noqa: PLC0415
+
+    import gitea.cli.utils  # noqa: PLC0415
+    import gitea.client.gitea  # noqa: PLC0415
+
+    token: str | None = ctx.obj.get("token")
+    base_url: str = ctx.obj.get("base_url")
+    timeout: int = ctx.obj.get("timeout")
+
+    def api_call() -> dict[str, Any] | None:
+        """Get user-level runners.
+
+        Returns:
+            A dictionary containing the user-level runners.
+
+        """
+        with gitea.client.gitea.Gitea(token=token, base_url=base_url) as client:
+            return client.user.get_user_level_runners(runner_id=runner_id, timeout=timeout)
+
+    gitea.cli.utils.execute_api_command(ctx=ctx, api_call=api_call, command_name="get-user-level-runners")

gitea/cli/user/get_workflow_jobs.py

@@ -0,0 +1,50 @@
+"""Get workflow jobs command for Gitea CLI."""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+import typer
+
+
+def get_workflow_jobs_command(
+    ctx: typer.Context,
+    status: Annotated[
+        Literal["pending", "queued", "in_progress", "failure", "success", "skipped"],
+        typer.Option(
+            "--status",
+            help="The status to filter workflow jobs by. Options: pending, queued, in_progress, failure, success, skipped.",
+        ),
+    ],
+    page: Annotated[int | None, typer.Option("--page", help="The page number for pagination.")] = None,
+    limit: Annotated[int | None, typer.Option("--limit", help="The number of items per page for pagination.")] = None,
+) -> None:
+    """Get workflow jobs for the authenticated user filtered by status.
+
+    Args:
+        ctx: The Typer context.
+        status: The status to filter workflow jobs by. Options: pending, queued, in_progress, failure, success, skipped.
+        page: The page number for pagination.
+        limit: The number of items per page for pagination.
+
+    """
+    from typing import Any  # noqa: PLC0415
+
+    import gitea.cli.utils  # noqa: PLC0415
+    import gitea.client.gitea  # noqa: PLC0415
+
+    token: str | None = ctx.obj.get("token")
+    base_url: str = ctx.obj.get("base_url")
+    timeout: int = ctx.obj.get("timeout")
+
+    def api_call() -> dict[str, Any] | None:
+        """Get workflow jobs.
+
+        Returns:
+            A dictionary containing the workflow jobs with the specified status.
+
+        """
+        with gitea.client.gitea.Gitea(token=token, base_url=base_url) as client:
+            return client.user.get_workflow_jobs(status=status, page=page, limit=limit, timeout=timeout)
+
+    gitea.cli.utils.execute_api_command(ctx=ctx, api_call=api_call, command_name="get-workflow-jobs")

gitea/cli/user/get_workflow_runs.py

@@ -0,0 +1,67 @@
+"""Get workflow runs command for Gitea CLI."""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+import typer
+
+
+def get_workflow_runs_command(  # noqa: PLR0913
+    ctx: typer.Context,
+    event: Annotated[str | None, typer.Option("--event", help="Workflow event name.")] = None,
+    branch: Annotated[str | None, typer.Option("--branch", help="Workflow branch.")] = None,
+    status: Annotated[
+        Literal["pending", "queued", "in_progress", "failure", "success", "skipped"] | None,
+        typer.Option(
+            "--status",
+            help="Workflow status.",
+        ),
+    ] = None,
+    actor: Annotated[str | None, typer.Option("--actor", help="Triggered by user.")] = None,
+    head_sha: Annotated[str | None, typer.Option("--head-sha", help="Triggering sha of the workflow run.")] = None,
+    page: Annotated[int | None, typer.Option("--page", help="Page number of results to return.")] = None,
+    limit: Annotated[int | None, typer.Option("--limit", help="Page size of results.")] = None,
+) -> None:
+    """Get workflow runs for the authenticated user filtered by various parameters.
+
+    Args:
+        ctx: The Typer context.
+        event: The event that triggered the workflow run.
+        branch: The branch name to filter workflow runs.
+        status: The status to filter workflow jobs by. Options: pending, queued, in_progress, failure, success, skipped.
+        actor: The actor who triggered the workflow run.
+        head_sha: The head SHA to filter workflow runs.
+        page: The page number for pagination.
+        limit: The number of items per page for pagination.
+
+    """
+    from typing import Any  # noqa: PLC0415
+
+    import gitea.cli.utils  # noqa: PLC0415
+    import gitea.client.gitea  # noqa: PLC0415
+
+    token: str | None = ctx.obj.get("token")
+    base_url: str = ctx.obj.get("base_url")
+    timeout: int = ctx.obj.get("timeout")
+
+    def api_call() -> dict[str, Any] | None:
+        """Get workflow runs.
+
+        Returns:
+            A dictionary containing the workflow runs.
+
+        """
+        with gitea.client.gitea.Gitea(token=token, base_url=base_url) as client:
+            return client.user.get_workflow_runs(
+                event=event,
+                branch=branch,
+                status=status,
+                actor=actor,
+                head_sha=head_sha,
+                page=page,
+                limit=limit,
+                timeout=timeout,
+            )
+
+    gitea.cli.utils.execute_api_command(ctx=ctx, api_call=api_call, command_name="get-workflow-runs")

gitea/cli/user/main.py

@@ -0,0 +1,34 @@
+# ruff: noqa PLC0415
+
+"""CLI commands for managing Gitea users."""
+
+from __future__ import annotations
+
+import typer
+
+user_app = typer.Typer(
+    name="user",
+    help="Commands for managing Gitea users.",
+    rich_markup_mode="rich",
+)
+
+
+def register_commands() -> None:
+    """Register user-related commands to the user_app."""
+
+    from gitea.cli.user.get_user import get_user_command
+    from gitea.cli.user.get_workflow_jobs import get_workflow_jobs_command
+    from gitea.cli.user.get_user_level_runners import get_user_level_runners_command
+    from gitea.cli.user.get_registration_token import get_registration_token_command
+    from gitea.cli.user.delete_user_level_runner import delete_user_level_runner_command
+    from gitea.cli.user.get_workflow_runs import get_workflow_runs_command
+
+    user_app.command("get-user")(get_user_command)
+    user_app.command("get-workflow-jobs")(get_workflow_jobs_command)
+    user_app.command("get-user-level-runners")(get_user_level_runners_command)
+    user_app.command("get-registration-token")(get_registration_token_command)
+    user_app.command("delete-user-level-runner")(delete_user_level_runner_command)
+    user_app.command("get-workflow-runs")(get_workflow_runs_command)
+
+
+register_commands()

gitea/cli/utils.py

@@ -0,0 +1,46 @@
+"""CLI utility functions."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+import typer
+from rich.console import Console
+
+
+def execute_api_command(
+    ctx: typer.Context,
+    api_call: Callable[[], dict[str, Any] | None],
+    command_name: str = "Command",
+) -> None:
+    """Execute an API command and output results.
+
+    Args:
+        ctx: Typer context containing token, base_url, and output.
+        api_call: Callable that executes the API call and returns the result.
+        command_name: Name of the command for error messages.
+
+    """
+    output: Path | None = ctx.obj.get("output")
+    console = Console()
+
+    try:
+        result = api_call()
+
+        if result is None:
+            console.print(f"{command_name} executed successfully. No content returned.")
+            return
+
+        json_output = json.dumps(result, indent=4)
+
+        if output:
+            Path(output).write_text(json_output)
+            console.print(f"Output saved to {output}")
+        else:
+            console.print_json(json_output)
+    except Exception as e:
+        console.print(f"Error executing {command_name}: {e}", style="red")
+        raise typer.Exit(1) from e

gitea/client/__init__.py

@@ -0,0 +1,8 @@
+"""Client for Gitea API."""
+
+from __future__ import annotations
+
+from gitea.client.async_gitea import AsyncGitea
+from gitea.client.gitea import Gitea
+
+__all__ = ["AsyncGitea", "Gitea"]

gitea/client/async_gitea.py

@@ -0,0 +1,106 @@
+"""Asynchronous Gitea API client implementation."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from aiohttp import ClientResponse, ClientSession, ClientTimeout
+
+from gitea.client.base import Client
+
+
+class AsyncGitea(Client):  # pylint: disable=too-few-public-methods
+    """Asynchronous Gitea API client."""
+
+    def __init__(self, token: str | None = None, base_url: str = "https://gitea.com") -> None:
+        """Initialize the asynchronous 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: ClientSession | None = None
+
+    def __str__(self) -> str:
+        """Return a string representation of the AsyncGitea client.
+
+        Returns:
+            A string representing the AsyncGitea client.
+
+        """
+        return f"AsyncGitea Client(base_url={self.base_url})"
+
+    async def __aenter__(self) -> AsyncGitea:
+        """Enter the asynchronous context manager.
+
+        Returns:
+            The AsyncGitea client instance.
+
+        """
+        if self.session is not None and not self.session.closed:
+            raise RuntimeError("AsyncGitea session already open; do not re-enter context manager.")
+        self.session = ClientSession(headers=self.headers)
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Exit the asynchronous context manager.
+
+        Args:
+            exc_type: The exception type.
+            exc_val: The exception value.
+            exc_tb: The traceback.
+
+        """
+        if self.session:
+            await self.session.close()
+            self.session = None
+
+    def _get_session(self, headers: dict | None = None, **kwargs: Any) -> ClientSession:
+        """Get or create the aiohttp ClientSession.
+
+        Args:
+            headers: Optional headers to include in the session.
+            **kwargs: Additional arguments for ClientSession.
+
+        Returns:
+            The aiohttp ClientSession instance.
+
+        """
+        return ClientSession(headers=headers, **kwargs)
+
+    async def _request(
+        self, method: str, endpoint: str, headers: dict | None = None, timeout: int = 30, **kwargs: Any
+    ) -> ClientResponse:
+        """Make an asynchronous HTTP request to the Gitea API.
+
+        Args:
+            method: The HTTP method (GET, POST, etc.).
+            endpoint: The API endpoint.
+            headers: Optional headers to include in the request.
+            timeout: Request timeout in seconds.
+            **kwargs: Additional arguments for the request.
+
+        Returns:
+            The aiohttp ClientResponse object.
+
+        """
+        if self.session is None:
+            raise RuntimeError(
+                "AsyncGitea must be used as an async context manager. "
+                + "Use 'async with AsyncGitea(...) as client:' to ensure proper resource cleanup."
+            )
+
+        url = self._build_url(endpoint=endpoint)
+        request_headers = {**self.headers, **(headers or {})}
+        timeout_obj = ClientTimeout(total=timeout)
+        response = await self.session.request(
+            method=method, url=url, headers=request_headers, timeout=timeout_obj, **kwargs
+        )
+        try:
+            response.raise_for_status()
+        except Exception:
+            response.release()
+            raise
+        return response

gitea/client/base.py

@@ -0,0 +1,45 @@
+"""Base client class for Gitea API interactions."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class Client:  # pylint: disable=too-few-public-methods
+    """Abstract base class for Gitea clients."""
+
+    def __init__(self, token: str | None, base_url: str) -> None:
+        """Construct the base client.
+
+        Args:
+            token: The API token for authentication.
+            base_url: The base URL of the Gitea instance.
+
+        """
+        self.token = token
+        self.base_url = base_url.rstrip("/")
+        self.headers: dict[str, Any] = {}
+        if self.token:
+            self.headers["Authorization"] = f"token {self.token}"
+
+    @property
+    def api_url(self) -> str:
+        """Return the base API URL.
+
+        Returns:
+            str: The base API URL.
+
+        """
+        return f"{self.base_url}/api/v1"
+
+    def _build_url(self, endpoint: str) -> str:
+        """Construct the full URL for a given endpoint.
+
+        Args:
+            endpoint (str): The API endpoint.
+
+        Returns:
+            str: The full URL.
+
+        """
+        return f"{self.api_url}/{endpoint.lstrip('/')}"