pjdev-gitlab 5.0.0__py3-none-any.whl

pjdev_gitlab/merge_requests_service.py

@@ -0,0 +1,244 @@
+from typing import Any, Dict, List, Optional
+
+from httpx import AsyncClient
+
+from pjdev_gitlab.api_utilities import (
+    async_retry_http,
+    encode_path_segment,
+    http_client,
+    paginate,
+)
+from pjdev_gitlab.models import (
+    Discussion,
+    MergeRequest,
+    MergeRequestState,
+    Note,
+    ProjectId,
+)
+
+_IGNORE_4XX = [400, 401, 403, 404]
+
+
+def _mr_base(project_id: ProjectId, mr_iid: Optional[int] = None) -> str:
+    base = f"/projects/{encode_path_segment(project_id)}/merge_requests"
+    if mr_iid is None:
+        return base
+    return f"{base}/{mr_iid}"
+
+
+@async_retry_http(status_codes_to_ignore=_IGNORE_4XX)
+async def list_merge_requests(
+    project_id: ProjectId,
+    *,
+    state: Optional[MergeRequestState] = None,
+    target_branch: Optional[str] = None,
+    source_branch: Optional[str] = None,
+    author_id: Optional[int] = None,
+    reviewer_id: Optional[int] = None,
+    labels: Optional[List[str]] = None,
+    search: Optional[str] = None,
+    created_after: Optional[str] = None,
+    created_before: Optional[str] = None,
+    extra_params: Optional[Dict[str, Any]] = None,
+    page_size: int = 100,
+    client: Optional[AsyncClient] = None,
+) -> List[MergeRequest]:
+    params: Dict[str, Any] = {}
+    if state is not None:
+        params["state"] = state.value
+    if target_branch is not None:
+        params["target_branch"] = target_branch
+    if source_branch is not None:
+        params["source_branch"] = source_branch
+    if author_id is not None:
+        params["author_id"] = author_id
+    if reviewer_id is not None:
+        params["reviewer_id"] = reviewer_id
+    if labels:
+        params["labels"] = ",".join(labels)
+    if search is not None:
+        params["search"] = search
+    if created_after is not None:
+        params["created_after"] = created_after
+    if created_before is not None:
+        params["created_before"] = created_before
+    if extra_params:
+        params.update(extra_params)
+
+    url = _mr_base(project_id)
+
+    async def _exec(_client: AsyncClient) -> List[MergeRequest]:
+        rows = await paginate(_client, url, params=params, page_size=page_size)
+        return [MergeRequest.model_validate(row) for row in rows]
+
+    if client is None:
+        async with http_client() as _client:
+            return await _exec(_client)
+    return await _exec(client)
+
+
+@async_retry_http(status_codes_to_ignore=_IGNORE_4XX)
+async def get_merge_request(
+    project_id: ProjectId,
+    mr_iid: int,
+    client: Optional[AsyncClient] = None,
+) -> MergeRequest:
+    url = _mr_base(project_id, mr_iid)
+
+    async def _exec(_client: AsyncClient) -> MergeRequest:
+        r = await _client.get(url)
+        r.raise_for_status()
+        return MergeRequest.model_validate(r.json())
+
+    if client is None:
+        async with http_client() as _client:
+            return await _exec(_client)
+    return await _exec(client)
+
+
+@async_retry_http(status_codes_to_ignore=_IGNORE_4XX)
+async def get_merge_request_changes(
+    project_id: ProjectId,
+    mr_iid: int,
+    client: Optional[AsyncClient] = None,
+) -> Dict[str, Any]:
+    """Fetch the raw diff/changes payload for an MR (used for review automation)."""
+    url = f"{_mr_base(project_id, mr_iid)}/changes"
+
+    async def _exec(_client: AsyncClient) -> Dict[str, Any]:
+        r = await _client.get(url)
+        r.raise_for_status()
+        return r.json()
+
+    if client is None:
+        async with http_client() as _client:
+            return await _exec(_client)
+    return await _exec(client)
+
+
+@async_retry_http(status_codes_to_ignore=_IGNORE_4XX)
+async def comment_on_merge_request(
+    project_id: ProjectId,
+    mr_iid: int,
+    body: str,
+    client: Optional[AsyncClient] = None,
+) -> Note:
+    url = f"{_mr_base(project_id, mr_iid)}/notes"
+
+    async def _exec(_client: AsyncClient) -> Note:
+        r = await _client.post(url, json={"body": body})
+        r.raise_for_status()
+        return Note.model_validate(r.json())
+
+    if client is None:
+        async with http_client() as _client:
+            return await _exec(_client)
+    return await _exec(client)
+
+
+@async_retry_http(status_codes_to_ignore=_IGNORE_4XX)
+async def comment_on_merge_request_diff(
+    project_id: ProjectId,
+    mr_iid: int,
+    body: str,
+    *,
+    base_sha: str,
+    start_sha: str,
+    head_sha: str,
+    new_path: str,
+    new_line: int,
+    old_path: Optional[str] = None,
+    old_line: Optional[int] = None,
+    client: Optional[AsyncClient] = None,
+) -> Discussion:
+    """Add a threaded inline diff comment.
+
+    Position payload follows the GitLab discussions API:
+    https://docs.gitlab.com/api/discussions/#create-a-new-thread-on-the-merge-request-diff
+    """
+    url = f"{_mr_base(project_id, mr_iid)}/discussions"
+    position: Dict[str, Any] = {
+        "base_sha": base_sha,
+        "start_sha": start_sha,
+        "head_sha": head_sha,
+        "position_type": "text",
+        "new_path": new_path,
+        "new_line": new_line,
+    }
+    if old_path is not None:
+        position["old_path"] = old_path
+    if old_line is not None:
+        position["old_line"] = old_line
+
+    async def _exec(_client: AsyncClient) -> Discussion:
+        r = await _client.post(url, json={"body": body, "position": position})
+        r.raise_for_status()
+        return Discussion.model_validate(r.json())
+
+    if client is None:
+        async with http_client() as _client:
+            return await _exec(_client)
+    return await _exec(client)
+
+
+@async_retry_http(status_codes_to_ignore=_IGNORE_4XX)
+async def list_merge_request_notes(
+    project_id: ProjectId,
+    mr_iid: int,
+    *,
+    page_size: int = 100,
+    client: Optional[AsyncClient] = None,
+) -> List[Note]:
+    url = f"{_mr_base(project_id, mr_iid)}/notes"
+
+    async def _exec(_client: AsyncClient) -> List[Note]:
+        rows = await paginate(_client, url, params={}, page_size=page_size)
+        return [Note.model_validate(row) for row in rows]
+
+    if client is None:
+        async with http_client() as _client:
+            return await _exec(_client)
+    return await _exec(client)
+
+
+@async_retry_http(status_codes_to_ignore=_IGNORE_4XX)
+async def approve_merge_request(
+    project_id: ProjectId,
+    mr_iid: int,
+    *,
+    sha: Optional[str] = None,
+    client: Optional[AsyncClient] = None,
+) -> Dict[str, Any]:
+    url = f"{_mr_base(project_id, mr_iid)}/approve"
+    payload: Dict[str, Any] = {}
+    if sha is not None:
+        payload["sha"] = sha
+
+    async def _exec(_client: AsyncClient) -> Dict[str, Any]:
+        r = await _client.post(url, json=payload or None)
+        r.raise_for_status()
+        return r.json()
+
+    if client is None:
+        async with http_client() as _client:
+            return await _exec(_client)
+    return await _exec(client)
+
+
+@async_retry_http(status_codes_to_ignore=_IGNORE_4XX)
+async def unapprove_merge_request(
+    project_id: ProjectId,
+    mr_iid: int,
+    client: Optional[AsyncClient] = None,
+) -> None:
+    url = f"{_mr_base(project_id, mr_iid)}/unapprove"
+
+    async def _exec(_client: AsyncClient) -> None:
+        r = await _client.post(url)
+        r.raise_for_status()
+
+    if client is None:
+        async with http_client() as _client:
+            await _exec(_client)
+            return
+    await _exec(client)

pjdev_gitlab/models.py

@@ -0,0 +1,172 @@
+import enum
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+
+from pydantic import BaseModel, ConfigDict
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+ProjectId = Union[int, str]
+GroupId = Union[int, str]
+
+
+class IssueState(enum.StrEnum):
+    opened = "opened"
+    closed = "closed"
+
+
+class StateEvent(enum.StrEnum):
+    close = "close"
+    reopen = "reopen"
+
+
+class IssueType(enum.StrEnum):
+    issue = "issue"
+    incident = "incident"
+    test_case = "test_case"
+    task = "task"
+
+
+class MergeRequestState(enum.StrEnum):
+    opened = "opened"
+    closed = "closed"
+    merged = "merged"
+    locked = "locked"
+
+
+class Config(BaseSettings):
+    gitlab_url: str = "https://gitlab.com"
+    token: Optional[str] = None
+    default_project_id: Optional[ProjectId] = None
+    output_path: Optional[Path] = None
+    http_retry_max_count: int = 5
+    http_retry_delay_seconds: int = 2
+    request_timeout_seconds: Optional[float] = None
+
+    model_config = SettingsConfigDict(
+        env_prefix="GL_",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    @property
+    def api_base_url(self) -> str:
+        return f"{self.gitlab_url.rstrip('/')}/api/v4"
+
+
+class GitlabBase(BaseModel):
+    model_config = ConfigDict(extra="ignore", populate_by_name=True, strict=False)
+
+
+class Author(GitlabBase):
+    id: int
+    username: str
+    name: Optional[str] = None
+    email: Optional[str] = None
+
+
+class Label(GitlabBase):
+    id: Optional[int] = None
+    name: str
+    color: Optional[str] = None
+    description: Optional[str] = None
+
+
+class Milestone(GitlabBase):
+    id: int
+    iid: Optional[int] = None
+    title: str
+    description: Optional[str] = None
+    state: Optional[str] = None
+    due_date: Optional[str] = None
+    start_date: Optional[str] = None
+
+
+class Iteration(GitlabBase):
+    id: int
+    iid: Optional[int] = None
+    title: Optional[str] = None
+    state: Optional[int] = None
+    start_date: Optional[str] = None
+    due_date: Optional[str] = None
+    web_url: Optional[str] = None
+
+
+class Issue(GitlabBase):
+    id: int
+    iid: int
+    project_id: int
+    title: str
+    description: Optional[str] = None
+    state: IssueState
+    labels: List[str] = []
+    author: Optional[Author] = None
+    assignees: List[Author] = []
+    milestone: Optional[Milestone] = None
+    iteration: Optional[Iteration] = None
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+    closed_at: Optional[datetime] = None
+    web_url: Optional[str] = None
+    issue_type: Optional[str] = None
+
+
+class Note(GitlabBase):
+    id: int
+    body: str
+    author: Optional[Author] = None
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+    system: Optional[bool] = None
+    noteable_id: Optional[int] = None
+    noteable_iid: Optional[int] = None
+    noteable_type: Optional[str] = None
+
+
+class Discussion(GitlabBase):
+    id: str
+    individual_note: Optional[bool] = None
+    notes: List[Note] = []
+
+
+class MergeRequest(GitlabBase):
+    id: int
+    iid: int
+    project_id: int
+    title: str
+    description: Optional[str] = None
+    state: MergeRequestState
+    target_branch: str
+    source_branch: str
+    labels: List[str] = []
+    author: Optional[Author] = None
+    assignees: List[Author] = []
+    reviewers: List[Author] = []
+    milestone: Optional[Milestone] = None
+    draft: Optional[bool] = None
+    work_in_progress: Optional[bool] = None
+    merge_status: Optional[str] = None
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+    merged_at: Optional[datetime] = None
+    web_url: Optional[str] = None
+    sha: Optional[str] = None
+    diff_refs: Optional[Dict[str, Any]] = None
+
+
+class RepoTreeEntry(GitlabBase):
+    id: str
+    name: str
+    type: str
+    path: str
+    mode: Optional[str] = None
+
+
+class Upload(GitlabBase):
+    """Response from POST /projects/:id/uploads"""
+
+    alt: Optional[str] = None
+    url: str
+    full_path: Optional[str] = None
+    markdown: str

pjdev_gitlab/packages_service.py

@@ -0,0 +1,134 @@
+from pathlib import Path
+from typing import Any, Dict, List, Literal, Optional
+
+from httpx import AsyncClient
+from loguru import logger
+
+from pjdev_gitlab.api_utilities import (
+    async_retry_http,
+    encode_path_segment,
+    http_client,
+    paginate,
+)
+from pjdev_gitlab.config_service import get_config
+from pjdev_gitlab.models import ProjectId
+
+_IGNORE_4XX = [400, 401, 403, 404]
+
+
+def _generic_url(
+    project_id: ProjectId, package_name: str, package_version: str, file_name: str
+) -> str:
+    return (
+        f"/projects/{encode_path_segment(project_id)}"
+        f"/packages/generic/{encode_path_segment(package_name)}"
+        f"/{encode_path_segment(package_version)}"
+        f"/{encode_path_segment(file_name)}"
+    )
+
+
+@async_retry_http(status_codes_to_ignore=_IGNORE_4XX)
+async def upload_generic_package(
+    project_id: ProjectId,
+    package_name: str,
+    package_version: str,
+    file_name: str,
+    file_path: Path,
+    *,
+    status: Literal["default", "hidden"] = "default",
+    select: Optional[Literal["package_file"]] = None,
+    client: Optional[AsyncClient] = None,
+) -> Dict[str, Any]:
+    """Upload a file to the GitLab generic package registry.
+
+    PUT /projects/:id/packages/generic/:package_name/:package_version/:file_name
+    Body is the raw file bytes; ``Content-Type: application/octet-stream``.
+    """
+    url = _generic_url(project_id, package_name, package_version, file_name)
+    params: Dict[str, Any] = {"status": status}
+    if select is not None:
+        params["select"] = select
+
+    async def _exec(_client: AsyncClient) -> Dict[str, Any]:
+        with open(file_path, "rb") as fh:
+            r = await _client.put(
+                url,
+                params=params,
+                content=fh.read(),
+                headers={"Content-Type": "application/octet-stream"},
+            )
+        if not r.is_success:
+            logger.warning(r.text)
+        r.raise_for_status()
+        if not r.content:
+            return {}
+        try:
+            return r.json()
+        except ValueError:
+            return {"text": r.text}
+
+    if client is None:
+        async with http_client() as _client:
+            return await _exec(_client)
+    return await _exec(client)
+
+
+@async_retry_http(status_codes_to_ignore=_IGNORE_4XX)
+async def download_generic_package(
+    project_id: ProjectId,
+    package_name: str,
+    package_version: str,
+    file_name: str,
+    *,
+    dest: Optional[Path] = None,
+    client: Optional[AsyncClient] = None,
+) -> Path:
+    url = _generic_url(project_id, package_name, package_version, file_name)
+
+    if dest is None:
+        output_path = get_config().output_path
+        if output_path is None:
+            raise ValueError(
+                "Either pass dest=... or set GL_OUTPUT_PATH / config.output_path"
+            )
+        dest = output_path / file_name
+
+    dest.parent.mkdir(parents=True, exist_ok=True)
+
+    async def _exec(_client: AsyncClient) -> Path:
+        async with _client.stream("GET", url) as r:
+            r.raise_for_status()
+            with open(dest, "wb") as fh:
+                async for chunk in r.aiter_bytes():
+                    fh.write(chunk)
+        return dest
+
+    if client is None:
+        async with http_client() as _client:
+            return await _exec(_client)
+    return await _exec(client)
+
+
+@async_retry_http(status_codes_to_ignore=_IGNORE_4XX)
+async def list_packages(
+    project_id: ProjectId,
+    *,
+    package_type: Optional[str] = None,
+    package_name: Optional[str] = None,
+    page_size: int = 100,
+    client: Optional[AsyncClient] = None,
+) -> List[Dict[str, Any]]:
+    url = f"/projects/{encode_path_segment(project_id)}/packages"
+    params: Dict[str, Any] = {}
+    if package_type is not None:
+        params["package_type"] = package_type
+    if package_name is not None:
+        params["package_name"] = package_name
+
+    async def _exec(_client: AsyncClient) -> List[Dict[str, Any]]:
+        return await paginate(_client, url, params=params, page_size=page_size)
+
+    if client is None:
+        async with http_client() as _client:
+            return await _exec(_client)
+    return await _exec(client)

pjdev_gitlab/repo_files_service.py

@@ -0,0 +1,145 @@
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+
+from httpx import AsyncClient
+from loguru import logger
+
+from pjdev_gitlab.api_utilities import (
+    async_retry_http,
+    encode_path_segment,
+    http_client,
+    paginate,
+)
+from pjdev_gitlab.config_service import get_config
+from pjdev_gitlab.models import ProjectId, RepoTreeEntry
+
+_IGNORE_4XX = [400, 401, 403, 404]
+
+
+def _file_url(project_id: ProjectId, file_path: str) -> str:
+    return (
+        f"/projects/{encode_path_segment(project_id)}"
+        f"/repository/files/{encode_path_segment(file_path)}/raw"
+    )
+
+
+def _tree_url(project_id: ProjectId) -> str:
+    return f"/projects/{encode_path_segment(project_id)}/repository/tree"
+
+
+@async_retry_http(status_codes_to_ignore=_IGNORE_4XX)
+async def get_file(
+    project_id: ProjectId,
+    file_path: str,
+    ref: str = "main",
+    *,
+    decode: bool = True,
+    client: Optional[AsyncClient] = None,
+) -> Union[str, bytes]:
+    url = _file_url(project_id, file_path)
+    params = {"ref": ref}
+
+    async def _exec(_client: AsyncClient) -> Union[str, bytes]:
+        r = await _client.get(url, params=params)
+        r.raise_for_status()
+        return r.text if decode else r.content
+
+    if client is None:
+        async with http_client() as _client:
+            return await _exec(_client)
+    return await _exec(client)
+
+
+@async_retry_http(status_codes_to_ignore=_IGNORE_4XX)
+async def download_file(
+    project_id: ProjectId,
+    file_path: str,
+    ref: str = "main",
+    *,
+    dest: Optional[Path] = None,
+    client: Optional[AsyncClient] = None,
+) -> Path:
+    url = _file_url(project_id, file_path)
+    params = {"ref": ref}
+
+    if dest is None:
+        output_path = get_config().output_path
+        if output_path is None:
+            raise ValueError(
+                "Either pass dest=... or set GL_OUTPUT_PATH / config.output_path"
+            )
+        dest = output_path / Path(file_path).name
+
+    dest.parent.mkdir(parents=True, exist_ok=True)
+
+    async def _exec(_client: AsyncClient) -> Path:
+        async with _client.stream("GET", url, params=params) as r:
+            r.raise_for_status()
+            with open(dest, "wb") as fh:
+                async for chunk in r.aiter_bytes():
+                    fh.write(chunk)
+        return dest
+
+    if client is None:
+        async with http_client() as _client:
+            return await _exec(_client)
+    return await _exec(client)
+
+
+@async_retry_http(status_codes_to_ignore=_IGNORE_4XX)
+async def list_tree(
+    project_id: ProjectId,
+    path: str = "",
+    ref: str = "main",
+    *,
+    recursive: bool = False,
+    page_size: int = 100,
+    client: Optional[AsyncClient] = None,
+) -> List[RepoTreeEntry]:
+    url = _tree_url(project_id)
+    params: Dict[str, Any] = {"ref": ref, "recursive": "true" if recursive else "false"}
+    if path:
+        params["path"] = path
+
+    async def _exec(_client: AsyncClient) -> List[RepoTreeEntry]:
+        rows = await paginate(_client, url, params=params, page_size=page_size)
+        return [RepoTreeEntry.model_validate(row) for row in rows]
+
+    if client is None:
+        async with http_client() as _client:
+            return await _exec(_client)
+    return await _exec(client)
+
+
+async def download_directory(
+    project_id: ProjectId,
+    path: str,
+    ref: str = "main",
+    *,
+    dest: Path,
+    client: Optional[AsyncClient] = None,
+) -> Path:
+    """Recursively download every blob under ``path`` into ``dest``, preserving
+    the relative directory structure.
+    """
+    dest.mkdir(parents=True, exist_ok=True)
+
+    async def _exec(_client: AsyncClient) -> Path:
+        entries = await list_tree(project_id, path=path, ref=ref, recursive=True, client=_client)
+        for entry in entries:
+            if entry.type != "blob":
+                continue
+            relative = (
+                entry.path[len(path):].lstrip("/")
+                if path and entry.path.startswith(path)
+                else entry.path
+            )
+            file_dest = dest / relative
+            await download_file(project_id, entry.path, ref=ref, dest=file_dest, client=_client)
+        logger.info(f"Downloaded {path or '/'}@{ref} from project {project_id} to {dest}")
+        return dest
+
+    if client is None:
+        async with http_client() as _client:
+            return await _exec(_client)
+    return await _exec(client)