python-gitea 0.0.1__py3-none-any.whl

gitea/__init__.py

@@ -0,0 +1,9 @@
+"""
+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/main.py

@@ -0,0 +1,89 @@
+# ruff: noqa PLC0415
+"""Main entry point for the python-gitea CLI application."""
+
+from __future__ import annotations
+
+import enum
+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
+
+    from rich.console import Console
+    from rich.logging import RichHandler
+
+    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(
+    verbose: Annotated[
+        LoggingLevel,
+        typer.Option("--verbose", "-v", help="Set verbosity level."),
+    ] = LoggingLevel.INFO,
+) -> None:
+    """Main entry point for the CLI application.
+
+    Args:
+        verbose: Verbosity level for logging.
+    """
+    setup_logging(verbose)
+
+
+def register_commands() -> None:
+    """Register CLI commands."""
+
+
+register_commands()

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,88 @@
+"""Asynchronous Gitea API client implementation."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from aiohttp import 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, 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
+
+    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) -> 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
+    ) -> dict[str, Any]:
+        """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 JSON response as a dictionary.
+        """
+        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)
+        async with self.session.request(
+            method=method, url=url, headers=request_headers, timeout=timeout_obj, **kwargs
+        ) as response:
+            response.raise_for_status()
+            return await response.json()

gitea/client/base.py

@@ -0,0 +1,40 @@
+"""Base client class for Gitea API interactions."""
+
+from __future__ import annotations
+
+
+class Client:  # pylint: disable=too-few-public-methods
+    """Abstract base class for Gitea clients."""
+
+    def __init__(self, token: str, 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 = {
+            "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('/')}"

gitea/client/gitea.py

@@ -0,0 +1,68 @@
+"""Gitea API client implementation."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import requests
+
+from gitea.client.base import Client
+
+
+class Gitea(Client):  # pylint: disable=too-few-public-methods
+    """Synchronous Gitea API client."""
+
+    def __init__(self, token: str, 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
+
+    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
+    ) -> dict[str, Any]:
+        """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 JSON response from the API.
+        """
+        url = self._build_url(endpoint=endpoint)
+        response = self.session.request(
+            method, url, headers={**self.headers, **(headers or {})}, timeout=timeout, **kwargs
+        )
+        response.raise_for_status()
+        return response.json()

gitea/utils/__init__.py

@@ -0,0 +1,7 @@
+"""Utility functions for the python-gitea package."""
+
+from __future__ import annotations
+
+from gitea.utils.log import get_version_information, setup_logger
+
+__all__ = ["get_version_information", "setup_logger"]

gitea/utils/log.py

@@ -0,0 +1,69 @@
+"""Utility functions for logging."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from gitea.version import __version__
+
+
+def get_version_information() -> str:
+    """Get the version information.
+
+    Returns:
+        str: Version information.
+    """
+    return __version__
+
+
+def setup_logger(
+    outdir: str = ".", label: str | None = None, log_level: str | int = "INFO", print_version: bool = False
+) -> None:
+    """Setup logging output: call at the start of the script to use
+
+    Args:
+        outdir: Output directory for log file.
+        label: Label for log file name. If None, no log file is created.
+        log_level: Logging level as string or integer.
+        print_version: Whether to print version information to the log.
+    """
+
+    if isinstance(log_level, str):
+        try:
+            level = getattr(logging, log_level.upper())
+        except AttributeError as e:
+            raise ValueError(f"log_level {log_level} not understood") from e
+    else:
+        level = int(log_level)
+
+    logger = logging.getLogger("python-gitea")
+    logger.propagate = False
+    logger.setLevel(level)
+
+    if not any(
+        isinstance(h, logging.StreamHandler) and not isinstance(h, logging.FileHandler) for h in logger.handlers
+    ):
+        stream_handler = logging.StreamHandler()
+        stream_handler.setFormatter(
+            logging.Formatter("%(asctime)s %(name)s %(levelname)-8s: %(message)s", datefmt="%H:%M")
+        )
+        stream_handler.setLevel(level)
+        logger.addHandler(stream_handler)
+
+    if not any(isinstance(h, logging.FileHandler) for h in logger.handlers) and label:
+        outdir_path = Path(outdir)
+        outdir_path.mkdir(parents=True, exist_ok=True)
+        log_file = outdir_path / f"{label}.log"
+        file_handler = logging.FileHandler(log_file)
+        file_handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)-8s: %(message)s", datefmt="%H:%M"))
+
+        file_handler.setLevel(level)
+        logger.addHandler(file_handler)
+
+    for handler in logger.handlers:
+        handler.setLevel(level)
+
+    if print_version:
+        version = get_version_information()
+        logger.info("Running python-gitea version: %s", version)

gitea/version.py

@@ -0,0 +1,13 @@
+"""
+A script to infer the version number from the metadata.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("python-gitea")
+except PackageNotFoundError:
+    # Fallback for source checkouts or environments without installed metadata.
+    __version__ = "0+unknown"

python_gitea-0.0.1.dist-info/METADATA

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: python-gitea
+Version: 0.0.1
+Summary: A Python package for interacting with the Gitea API, offering a simple interface to access repositories, users, organizations, issues, and more for automation and data management.
+Project-URL: Documentation, https://isaac-cf-wong.github.io/python-gitea
+Project-URL: Source, https://github.com/isaac-cf-wong/python-gitea
+Project-URL: Tracker, https://github.com/isaac-cf-wong/python-gitea/issues
+Project-URL: Home, https://github.com/isaac-cf-wong/python-gitea
+Project-URL: Release Notes, https://github.com/isaac-cf-wong/python-gitea/releases
+Author-email: "Isaac C. F. Wong" <isaac.cf.wong@gmail.com>
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: aiohttp<4.0.0,>=3.8.0
+Requires-Dist: requests<3.0.0,>=2.32.0
+Requires-Dist: typer<1.0.0,>=0.21.0
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: flake8; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mike; extra == 'docs'
+Requires-Dist: mkdocs; extra == 'docs'
+Requires-Dist: mkdocs-gen-files; extra == 'docs'
+Requires-Dist: mkdocs-literate-nav; extra == 'docs'
+Requires-Dist: mkdocs-material; extra == 'docs'
+Requires-Dist: mkdocs-section-index; extra == 'docs'
+Requires-Dist: mkdocstrings[python]; extra == 'docs'
+Provides-Extra: test
+Requires-Dist: bandit[toml]==1.9.2; extra == 'test'
+Requires-Dist: black==25.12.0; extra == 'test'
+Requires-Dist: check-manifest==0.51; extra == 'test'
+Requires-Dist: flake8; extra == 'test'
+Requires-Dist: flake8-bugbear==25.11.29; extra == 'test'
+Requires-Dist: flake8-docstrings; extra == 'test'
+Requires-Dist: flake8-formatter-junit-xml; extra == 'test'
+Requires-Dist: flake8-pyproject; extra == 'test'
+Requires-Dist: pre-commit==4.5.1; extra == 'test'
+Requires-Dist: pytest-asyncio; extra == 'test'
+Requires-Dist: pytest-cov==7.0.0; extra == 'test'
+Requires-Dist: pytest-github-actions-annotate-failures; extra == 'test'
+Requires-Dist: pytest-mock<3.15.2; extra == 'test'
+Requires-Dist: pytest-runner; extra == 'test'
+Requires-Dist: pytest==9.0.2; extra == 'test'
+Requires-Dist: shellcheck-py==0.11.0.1; extra == 'test'
+Description-Content-Type: text/markdown
+
+# python-gitea
+
+[![Python CI](https://github.com/isaac-cf-wong/python-gitea/actions/workflows/CI.yml/badge.svg)](https://github.com/isaac-cf-wong/python-gitea/actions/workflows/CI.yml)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/isaac-cf-wong/python-gitea/main.svg)](https://results.pre-commit.ci/latest/github/isaac-cf-wong/python-gitea/main)
+[![Documentation Status](https://github.com/isaac-cf-wong/python-gitea/actions/workflows/documentation.yml/badge.svg)](https://isaac-cf-wong.github.io/python-gitea/)
+[![codecov](https://codecov.io/gh/isaac-cf-wong/python-gitea/graph/badge.svg?token=COF8341N60)](https://codecov.io/gh/isaac-cf-wong/python-gitea)
+[![PyPI Version](https://img.shields.io/pypi/v/python-gitea)](https://pypi.org/project/python-gitea/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/package-name-placeholder)](https://pypi.org/project/package-name-placeholder/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
+[![DOI](https://zenodo.org/badge/924023559.svg)](https://doi.org/10.5281/zenodo.18017404)
+
+**Note:** This project is still in progress. The promised features are not fully ready yet, and APIs are subject to change.
+
+A Python package for interacting with the Gitea API.
+This package provides a simple and intuitive interface to access Gitea repositories, users, organizations, issues, and more,
+enabling seamless integration with Gitea instances for automation, data retrieval, and management tasks.
+
+## Features
+
+Full API Coverage: Access to repositories, users, organizations, issues, pull requests, and more.
+
+- Easy Authentication: Support for token-based authentication.
+- Asynchronous Support: Built with async/await for non-blocking operations.
+- Type Hints: Full type annotations for better IDE support and code reliability.
+- Comprehensive Documentation: Detailed guides and API reference.
+- Command-Line Interface: Interact with the Gitea API directly from the terminal for
+  quick, scriptable operations without writing code.
+
+## Installation
+
+We recommend using `uv` to manage virtual environments for installing `python-gitea`.
+
+If you don't have `uv` installed, you can install it with pip. See the project pages for more details:
+
+- Install via pip: `pip install --upgrade pip && pip install uv`
+- Project pages: [uv on PyPI](https://pypi.org/project/uv/) | [uv on GitHub](https://github.com/astral-sh/uv)
+- Full documentation and usage guide: [uv docs](https://docs.astral.sh/uv/)
+
+### Requirements
+
+- Python 3.10 or higher
+- Operating System: Linux, macOS, or Windows
+
+### Install from PyPI
+
+The recommended way to install `python-gitea` is from PyPI:
+
+```bash
+# Create a virtual environment (recommended with uv)
+uv venv --python 3.10
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+uv pip install python-gitea
+```
+
+#### Optional Dependencies
+
+For development or specific features:
+
+```bash
+# Development dependencies (testing, linting, etc.)
+uv pip install python-gitea[dev]
+
+# Documentation dependencies
+uv pip install python-gitea[docs]
+
+# All dependencies
+uv pip install python-gitea[dev,docs]
+```
+
+### Install from Source
+
+For the latest development version:
+
+```bash
+git clone git@github.com:isaac-cf-wong/python-gitea.git
+cd python-gitea
+# Create a virtual environment (recommended with uv)
+uv venv --python 3.10
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+uv pip install .
+```
+
+#### Development Installation
+
+To set up for development:
+
+```bash
+git clone git@github.com:isaac-cf-wong/python-gitea.git
+cd python-gitea
+
+# Create a virtual environment (recommended with uv)
+uv venv --python 3.10
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+uv pip install ".[dev]"
+
+# Install the commitlint dependencies
+npm install
+
+# Install pre-commit hooks
+pre-commit install
+pre-commit install --hook-type commit-msg
+```
+
+### Verify Installation
+
+Check that `python-gitea` is installed correctly:
+
+```bash
+gitea-cli --help
+```
+
+```bash
+python -c "import gitea; print(gitea.__version__)"
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Support
+
+For questions, issues, or contributions, please:
+
+- Check the [documentation](https://isaac-cf-wong.github.io/python-gitea/)
+- Open an issue on [GitHub](https://github.com/isaac-cf-wong/python-gitea/issues)
+- Join our [discussions](https://github.com/isaac-cf-wong/python-gitea/discussions)
+
+## Changelog
+
+See [Release Notes](https://github.com/isaac-cf-wong/python-gitea/releases) for version history.

python_gitea-0.0.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+gitea/__init__.py,sha256=A-KqBpsyLaneujE2QSqtD-xI3HKM5VUMTBZg1m8Cjqo,146
+gitea/__main__.py,sha256=VxrPtOzhGWtiYFtbMf9HZfBOq69f1-6wiZKUgChCi9k,200
+gitea/version.py,sha256=SBY7nWdooBkN0BKqo3R6jRH252I2teqmSdQSZpoCK3Y,349
+gitea/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gitea/cli/main.py,sha256=3mFRBVcGZnezGoweEiKMtaew5_8ksYMQS8N0GbwTGAk,2062
+gitea/client/__init__.py,sha256=tWyILBf_tdTP1F6tf0NrNtgeEOYDRkc2QlHaga7GIo8,185
+gitea/client/async_gitea.py,sha256=zsL_9oxdK1TLnU4AgVDm5Mnpm-XK65OLE0eASFAXKYU,3101
+gitea/client/base.py,sha256=rmZJOS2fmp4t0Z_9wBv63T2zDJLBWOxEr3wxxsd8YRA,1060
+gitea/client/gitea.py,sha256=Ad4YGnZrBkffjfG-VwGsejsKR19M6SDobqOcCA5Bl_Y,2112
+gitea/utils/__init__.py,sha256=aP0FsAkvhZAoKrlaEWWvx_F7KU0HPqWhKElyBdEyTyk,212
+gitea/utils/log.py,sha256=L11Fx66hPKS7Zvol5iiFSMw-GoDYcJMBlGYW2LqjjWI,2230
+python_gitea-0.0.1.dist-info/METADATA,sha256=zNJDUVdBG5lnVMoCLo0gZDAuchAV5kXCHYDAJFIlQCg,7275
+python_gitea-0.0.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+python_gitea-0.0.1.dist-info/entry_points.txt,sha256=m5yt-1RMRZRFMj_M-Un5E4eOkM113S9EppAHp0aCzEY,49
+python_gitea-0.0.1.dist-info/licenses/LICENSE,sha256=4dW9zcCxiQKAu4CyNKJTRmvzdJCCHDxbPGuQ-YALpsY,1137
+python_gitea-0.0.1.dist-info/RECORD,,

python_gitea-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

python_gitea-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gitea-cli = gitea.cli.main:app

python_gitea-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) 2025 isaac-cf-wong
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE