qodev-gitlab-api 0.1.0__tar.gz

qodev_gitlab_api-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv sync --all-extras
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv sync --all-extras
+      - run: uv run pytest -v

qodev_gitlab_api-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,16 @@
+name: Publish to PyPI
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

qodev_gitlab_api-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+dist/
+build/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+uv.lock

qodev_gitlab_api-0.1.0/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.4
+Name: qodev-gitlab-api
+Version: 0.1.0
+Summary: Python client for the GitLab API
+Project-URL: Repository, https://github.com/qodevai/gitlab-api
+Project-URL: Issues, https://github.com/qodevai/gitlab-api/issues
+Author-email: Jan Scheffler <jan.scheffler@qodev.ai>
+License: MIT
+Keywords: api,client,gitlab
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: python-dotenv>=1.1.0
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.12.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# qodev-gitlab-api
+
+Python client for the GitLab API.
+
+## Installation
+
+```bash
+pip install qodev-gitlab-api
+```
+
+## Usage
+
+```python
+from qodev_gitlab_api import GitLabClient
+
+client = GitLabClient()
+```

qodev_gitlab_api-0.1.0/README.md

@@ -0,0 +1,17 @@
+# qodev-gitlab-api
+
+Python client for the GitLab API.
+
+## Installation
+
+```bash
+pip install qodev-gitlab-api
+```
+
+## Usage
+
+```python
+from qodev_gitlab_api import GitLabClient
+
+client = GitLabClient()
+```

qodev_gitlab_api-0.1.0/pyproject.toml

@@ -0,0 +1,84 @@
+[project]
+name = "qodev-gitlab-api"
+version = "0.1.0"
+description = "Python client for the GitLab API"
+readme = "README.md"
+authors = [
+    { name = "Jan Scheffler", email = "jan.scheffler@qodev.ai" }
+]
+license = { text = "MIT" }
+requires-python = ">=3.11"
+keywords = ["gitlab", "api", "client"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.28.1",
+    "python-dotenv>=1.1.0",
+]
+
+[project.urls]
+Repository = "https://github.com/qodevai/gitlab-api"
+Issues = "https://github.com/qodevai/gitlab-api/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.1.0",
+    "pytest-mock>=3.12.0",
+    "ruff>=0.8.0",
+    "pyright>=1.1.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/qodev_gitlab_api"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+
+[tool.ruff.lint]
+select = [
+    "E",      # pycodestyle errors
+    "F",      # pyflakes
+    "I",      # isort
+    "UP",     # pyupgrade
+    "B",      # flake8-bugbear
+    "SIM",    # flake8-simplify
+    "RUF",    # ruff-specific rules
+]
+ignore = [
+    "E501",   # line too long (handled by formatter)
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["qodev_gitlab_api"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.pyright]
+pythonVersion = "3.11"
+typeCheckingMode = "basic"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.typos.default]
+extend-ignore-re = ["[0-9a-zA-Z]{40,}"]
+extend-words = { noteable = "noteable" }
+
+[tool.typos.files]
+extend-exclude = ["uv.lock", "*.log"]

qodev_gitlab_api-0.1.0/src/qodev_gitlab_api/__init__.py

@@ -0,0 +1,18 @@
+"""GitLab API client library."""
+
+from qodev_gitlab_api.client import GitLabClient
+from qodev_gitlab_api.exceptions import APIError, AuthenticationError, ConfigurationError, GitLabError, NotFoundError
+from qodev_gitlab_api.models import DiffPosition, FileFromBase64, FileFromPath, FileSource
+
+__all__ = [
+    "APIError",
+    "AuthenticationError",
+    "ConfigurationError",
+    "DiffPosition",
+    "FileFromBase64",
+    "FileFromPath",
+    "FileSource",
+    "GitLabClient",
+    "GitLabError",
+    "NotFoundError",
+]

qodev_gitlab_api-0.1.0/src/qodev_gitlab_api/_base.py

@@ -0,0 +1,143 @@
+"""Base GitLab client mixin with HTTP primitives."""
+
+import logging
+import os
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+from dotenv import load_dotenv
+
+from qodev_gitlab_api.exceptions import APIError, AuthenticationError, ConfigurationError, NotFoundError
+
+load_dotenv()
+
+logger = logging.getLogger(__name__)
+
+
+def _raise_for_status(e: httpx.HTTPStatusError) -> None:
+    """Convert httpx HTTP errors into typed exceptions."""
+    status = e.response.status_code
+    body = e.response.text[:500] if e.response.text else ""
+    if status == 401:
+        raise AuthenticationError(f"Authentication failed: {body}") from e
+    if status == 404:
+        raise NotFoundError(f"Not found: {body}", status_code=status) from e
+    raise APIError(f"API error {status}: {body}", status_code=status, response_body=body) from e
+
+
+class BaseClientMixin:
+    """Base mixin providing HTTP primitives and initialization."""
+
+    token: str | None
+    base_url: str
+    api_url: str
+    client: httpx.Client
+
+    def __init__(self, token: str | None = None, base_url: str | None = None, validate: bool = True):
+        self.token = token or os.getenv("GITLAB_TOKEN")
+        self.base_url = (
+            base_url or os.getenv("GITLAB_BASE_URL") or os.getenv("GITLAB_URL") or "https://gitlab.com"
+        ).rstrip("/")
+
+        self._validate_configuration()
+
+        self.api_url = f"{self.base_url}/api/v4"
+        headers: dict[str, str] = {"PRIVATE-TOKEN": str(self.token), "Content-Type": "application/json"}
+        self.client = httpx.Client(
+            base_url=self.api_url,
+            headers=headers,
+            timeout=30.0,
+        )
+
+        if validate:
+            self._test_connectivity()
+        else:
+            logger.info(f"GitLab client initialized for {self.base_url} (validation skipped)")
+
+    def _validate_configuration(self) -> None:
+        if not self.token:
+            raise ConfigurationError(
+                "GITLAB_TOKEN environment variable is required. Set it in your .env file or environment."
+            )
+        if not self.base_url.startswith(("http://", "https://")):
+            raise ConfigurationError(f"GITLAB_URL must start with http:// or https://, got: {self.base_url}")
+
+    def _test_connectivity(self) -> None:
+        try:
+            version_info = self.get("/version")
+            logger.info(f"Connected to GitLab {version_info.get('version', 'unknown')} at {self.base_url}")
+        except (AuthenticationError, APIError, NotFoundError):
+            raise
+        except httpx.HTTPStatusError as e:
+            _raise_for_status(e)
+        except httpx.RequestError as e:
+            raise ConfigurationError(f"Cannot connect to GitLab at {self.base_url}. Check your GITLAB_URL.") from e
+
+    @staticmethod
+    def _encode_project_id(project_id: str) -> str:
+        return quote(project_id, safe="")
+
+    def get(self, endpoint: str, params: dict[str, Any] | None = None) -> Any:
+        """GET request to GitLab API."""
+        try:
+            logger.debug(f"GET {endpoint} with params={params}")
+            response = self.client.get(endpoint, params=params)
+            response.raise_for_status()
+            return response.json()
+        except httpx.HTTPStatusError as e:
+            logger.error(f"GitLab API error for GET {endpoint}: {e.response.status_code}")
+            _raise_for_status(e)
+        except httpx.RequestError as e:
+            logger.error(f"Network error for GET {endpoint}: {e}")
+            raise
+
+    def get_paginated(
+        self, endpoint: str, params: dict[str, Any] | None = None, per_page: int = 100, max_pages: int = 100
+    ) -> list[Any]:
+        """GET request with pagination support."""
+        params = params or {}
+        params["per_page"] = min(per_page, 100)
+        params["page"] = 1
+
+        all_results: list[Any] = []
+        pages_fetched = 0
+
+        try:
+            while pages_fetched < max_pages:
+                logger.debug(f"GET {endpoint} page {params['page']} (per_page={params['per_page']})")
+                response = self.client.get(endpoint, params=params)
+                response.raise_for_status()
+                results = response.json()
+
+                if not results:
+                    break
+
+                all_results.extend(results)
+                pages_fetched += 1
+
+                if "x-next-page" not in response.headers or not response.headers["x-next-page"]:
+                    break
+
+                params["page"] += 1
+
+            if pages_fetched >= max_pages:
+                logger.warning(f"Hit max_pages limit ({max_pages}) for {endpoint}. Results may be incomplete.")
+
+            logger.debug(f"Fetched {len(all_results)} results from {pages_fetched} pages for {endpoint}")
+            return all_results
+
+        except httpx.HTTPStatusError as e:
+            logger.error(f"GitLab API error during pagination of {endpoint}: {e.response.status_code}")
+            _raise_for_status(e)
+            return []  # unreachable, for type checker
+
+    def get_projects(self, owned: bool = False, membership: bool = True) -> list[dict[str, Any]]:
+        """Get all projects."""
+        params: dict[str, Any] = {"membership": membership, "owned": owned}
+        return self.get_paginated("/projects", params=params)
+
+    def get_project(self, project_id: str) -> dict[str, Any]:
+        """Get a specific project by ID or path."""
+        encoded_id = self._encode_project_id(project_id)
+        return self.get(f"/projects/{encoded_id}")

qodev_gitlab_api-0.1.0/src/qodev_gitlab_api/_files.py

@@ -0,0 +1,64 @@
+"""File operations client mixin."""
+
+import base64
+import binascii
+import logging
+import os
+from typing import Any, cast
+from urllib.parse import quote
+
+import httpx
+
+from qodev_gitlab_api._base import BaseClientMixin, _raise_for_status
+from qodev_gitlab_api.models import FileFromPath, FileSource
+
+logger = logging.getLogger(__name__)
+
+
+class FilesMixin(BaseClientMixin):
+    """Mixin for file operations."""
+
+    def get_file_content(self, project_id: str, file_path: str, ref: str) -> str:
+        """Get raw file content at a specific ref."""
+        encoded_id = self._encode_project_id(project_id)
+        encoded_path = quote(file_path, safe="")
+        try:
+            response = self.client.get(
+                f"/projects/{encoded_id}/repository/files/{encoded_path}/raw",
+                params={"ref": ref},
+            )
+            response.raise_for_status()
+            return response.text
+        except httpx.HTTPStatusError as e:
+            _raise_for_status(e)
+            return ""
+
+    def upload_file(self, project_id: str, source: FileSource) -> dict[str, Any]:
+        """Upload a file to GitLab for use in markdown."""
+        encoded_id = self._encode_project_id(project_id)
+
+        if "path" in source:
+            file_path = cast(FileFromPath, source)["path"]
+            with open(file_path, "rb") as f:
+                file_content = f.read()
+            filename = os.path.basename(file_path)
+        else:
+            try:
+                file_content = base64.b64decode(source["base64"], validate=True)
+            except binascii.Error as e:
+                raise ValueError(f"Invalid base64 data: {e}") from e
+            filename = source["filename"]
+
+        files = {"file": (filename, file_content)}
+        try:
+            response = httpx.post(
+                f"{self.api_url}/projects/{encoded_id}/uploads",
+                files=files,
+                headers={"PRIVATE-TOKEN": str(self.token)},
+                timeout=30.0,
+            )
+            response.raise_for_status()
+            return response.json()
+        except httpx.HTTPStatusError as e:
+            _raise_for_status(e)
+            return {}

qodev_gitlab_api-0.1.0/src/qodev_gitlab_api/_issues.py

@@ -0,0 +1,119 @@
+"""Issue client mixin."""
+
+import logging
+from typing import Any
+
+import httpx
+
+from qodev_gitlab_api._base import BaseClientMixin, _raise_for_status
+
+logger = logging.getLogger(__name__)
+
+
+class IssuesMixin(BaseClientMixin):
+    """Mixin for issue operations."""
+
+    def get_issues(
+        self,
+        project_id: str,
+        state: str = "opened",
+        labels: str | None = None,
+        assignee_id: int | None = None,
+        milestone: str | None = None,
+        per_page: int = 20,
+        max_pages: int = 10,
+    ) -> list[dict[str, Any]]:
+        encoded_id = self._encode_project_id(project_id)
+        params: dict[str, Any] = {"state": state}
+        if labels:
+            params["labels"] = labels
+        if assignee_id is not None:
+            params["assignee_id"] = assignee_id
+        if milestone:
+            params["milestone"] = milestone
+        return self.get_paginated(
+            f"/projects/{encoded_id}/issues", params=params, per_page=per_page, max_pages=max_pages
+        )
+
+    def get_issue(self, project_id: str, issue_iid: int) -> dict[str, Any]:
+        encoded_id = self._encode_project_id(project_id)
+        return self.get(f"/projects/{encoded_id}/issues/{issue_iid}")
+
+    def create_issue(
+        self,
+        project_id: str,
+        title: str,
+        description: str | None = None,
+        labels: str | None = None,
+        assignee_ids: list[int] | None = None,
+        milestone_id: int | None = None,
+    ) -> dict[str, Any]:
+        encoded_id = self._encode_project_id(project_id)
+        data: dict[str, Any] = {"title": title}
+        if description:
+            data["description"] = description
+        if labels:
+            data["labels"] = labels
+        if assignee_ids:
+            data["assignee_ids"] = assignee_ids
+        if milestone_id is not None:
+            data["milestone_id"] = milestone_id
+
+        try:
+            response = self.client.post(f"/projects/{encoded_id}/issues", json=data)
+            response.raise_for_status()
+            return response.json()
+        except httpx.HTTPStatusError as e:
+            _raise_for_status(e)
+            return {}
+
+    def update_issue(
+        self,
+        project_id: str,
+        issue_iid: int,
+        title: str | None = None,
+        description: str | None = None,
+        state_event: str | None = None,
+        labels: str | None = None,
+        assignee_ids: list[int] | None = None,
+        milestone_id: int | None = None,
+    ) -> dict[str, Any]:
+        encoded_id = self._encode_project_id(project_id)
+        data: dict[str, Any] = {}
+        if title:
+            data["title"] = title
+        if description is not None:
+            data["description"] = description
+        if state_event:
+            data["state_event"] = state_event
+        if labels is not None:
+            data["labels"] = labels
+        if assignee_ids is not None:
+            data["assignee_ids"] = assignee_ids
+        if milestone_id is not None:
+            data["milestone_id"] = milestone_id
+
+        try:
+            response = self.client.put(f"/projects/{encoded_id}/issues/{issue_iid}", json=data)
+            response.raise_for_status()
+            return response.json()
+        except httpx.HTTPStatusError as e:
+            _raise_for_status(e)
+            return {}
+
+    def close_issue(self, project_id: str, issue_iid: int) -> dict[str, Any]:
+        return self.update_issue(project_id, issue_iid, state_event="close")
+
+    def get_issue_notes(self, project_id: str, issue_iid: int) -> list[dict[str, Any]]:
+        encoded_id = self._encode_project_id(project_id)
+        return self.get_paginated(f"/projects/{encoded_id}/issues/{issue_iid}/notes")
+
+    def create_issue_note(self, project_id: str, issue_iid: int, body: str) -> dict[str, Any]:
+        encoded_id = self._encode_project_id(project_id)
+        try:
+            response = self.client.post(f"/projects/{encoded_id}/issues/{issue_iid}/notes", json={"body": body})
+            response.raise_for_status()
+            return response.json()
+        except httpx.HTTPStatusError as e:
+            _raise_for_status(e)
+            return {}