tracktolib 0.68.0__py3-none-any.whl → 0.69.0__py3-none-any.whl

tracktolib/api.py

@@ -11,7 +11,6 @@ from typing import (
     Literal,
     Mapping,
     Sequence,
-    Type,
     TypeAlias,
     TypedDict,
     get_args,
@@ -19,14 +18,14 @@ from typing import (
     get_type_hints,
 )
 
-from .utils import json_serial, get_first_line
+from .utils import get_first_line, json_serial
 
 try:
-    from fastapi import params, APIRouter
+    import starlette.status
+    from fastapi import APIRouter, params
     from fastapi.responses import JSONResponse
-    from pydantic.alias_generators import to_camel
     from pydantic import BaseModel, ConfigDict
-    import starlette.status
+    from pydantic.alias_generators import to_camel
 except ImportError:
     raise ImportError('Please install fastapi, pydantic or tracktolib with "api" to use this module')
 
@@ -61,7 +60,7 @@ class MethodMeta(TypedDict):
     status_code: StatusCode
     dependencies: Dependencies
     path: str | None
-    response_model: Type[BaseModel | None | Sequence[BaseModel]] | None
+    response_model: type[BaseModel | None | Sequence[BaseModel]] | None
     openapi_extra: dict[str, Any] | None
     name: str | None
     summary: str | None
@@ -82,7 +81,7 @@ class Endpoint:
         status_code: StatusCode = None,
         dependencies: Dependencies = None,
         path: str | None = None,
-        model: Type[B] | None = None,
+        model: type[B] | None = None,
         openapi_extra: dict[str, Any] | None = None,
         name: str | None = None,
         summary: str | None = None,
@@ -109,7 +108,7 @@ class Endpoint:
         status_code: StatusCode = None,
         dependencies: Dependencies = None,
         path: str | None = None,
-        model: Type[B] | None = None,
+        model: type[B] | None = None,
         openapi_extra: dict[str, Any] | None = None,
         name: str | None = None,
         summary: str | None = None,
@@ -135,7 +134,7 @@ class Endpoint:
         status_code: StatusCode = None,
         dependencies: Dependencies = None,
         path: str | None = None,
-        model: Type[B] | None = None,
+        model: type[B] | None = None,
         openapi_extra: dict[str, Any] | None = None,
         name: str | None = None,
         summary: str | None = None,
@@ -161,7 +160,7 @@ class Endpoint:
         status_code: StatusCode = None,
         dependencies: Dependencies = None,
         path: str | None = None,
-        model: Type[B] | None = None,
+        model: type[B] | None = None,
         openapi_extra: dict[str, Any] | None = None,
         name: str | None = None,
         summary: str | None = None,
@@ -187,7 +186,7 @@ class Endpoint:
         status_code: StatusCode = None,
         dependencies: Dependencies = None,
         path: str | None = None,
-        model: Type[B] | None = None,
+        model: type[B] | None = None,
         openapi_extra: dict[str, Any] | None = None,
         name: str | None = None,
         summary: str | None = None,
@@ -216,7 +215,7 @@ def _get_method_wrapper[B: _BaseModelBound](
     status_code: StatusCode = None,
     dependencies: Dependencies = None,
     path: str | None = None,
-    model: Type[B] | None = None,
+    model: type[B] | None = None,
     openapi_extra: dict[str, Any] | None = None,
     name: str | None = None,
     summary: str | None = None,
@@ -335,7 +334,7 @@ def check_status(resp, status: int = starlette.status.HTTP_200_OK):
         raise AssertionError(json.dumps(resp.json(), indent=4))
 
 
-def generate_list_name_model[B: _BaseModelBound](model: Type[B], status: int | None = None) -> dict:
+def generate_list_name_model[B: _BaseModelBound](model: type[B], status: int | None = None) -> dict:
     _status = "200" if status is None else str(status)
     if get_origin(model) and get_origin(model) is list:
         _title = f"Array[{get_args(model)[0].__name__}]"

tracktolib/cf/__init__.py

@@ -0,0 +1,8 @@
+from .client import CloudflareDNSClient, CloudflareError
+from .types import DnsRecord
+
+__all__ = [
+    "CloudflareDNSClient",
+    "CloudflareError",
+    "DnsRecord",
+]

tracktolib/cf/client.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, cast
+
+try:
+    import niquests
+except ImportError:
+    raise ImportError('Please install niquests or tracktolib with "cf" to use this module')
+
+if TYPE_CHECKING:
+    from urllib3.util.retry import Retry
+
+    from tracktolib.cf.types import DnsRecord
+
+
+class CloudflareError(Exception):
+    """Error raised when a Cloudflare API call fails."""
+
+    def __init__(self, message: str, status_code: int | None = None, errors: list | None = None):
+        self.status_code = status_code
+        self.errors = errors or []
+        super().__init__(message)
+
+
+@dataclass
+class CloudflareDNSClient:
+    """
+    Async Cloudflare DNS API client for managing DNS records.
+
+    Requires CLOUDFLARE_API_TOKEN and CLOUDFLARE_ZONE_ID environment variables,
+    or pass them directly to the constructor.
+    """
+
+    zone_id: str | None = field(default_factory=lambda: os.environ.get("CLOUDFLARE_ZONE_ID"))
+    token: str | None = field(default_factory=lambda: os.environ.get("CLOUDFLARE_API_TOKEN"))
+    base_url: str = "https://api.cloudflare.com/client/v4"
+    retries: int | Retry = 0
+    hooks: Any = None
+    session: niquests.AsyncSession = field(init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        if not self.token:
+            raise ValueError("CLOUDFLARE_API_TOKEN environment variable is required")
+        if not self.zone_id:
+            raise ValueError("CLOUDFLARE_ZONE_ID environment variable is required")
+
+        self.session = niquests.AsyncSession(
+            base_url=self.base_url,
+            retries=self.retries,
+            hooks=self.hooks,
+            headers={
+                "Authorization": f"Bearer {self.token}",
+                "Content-Type": "application/json",
+            },
+        )
+
+    async def __aenter__(self) -> "CloudflareDNSClient":
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Close the underlying session."""
+        await self.session.close()
+
+    def _handle_response(self, response: niquests.Response) -> dict:
+        """Handle Cloudflare API response and raise on errors."""
+        data = response.json()
+        if not data.get("success", False):
+            errors = data.get("errors", [])
+            error_messages = [e.get("message", str(e)) for e in errors]
+            raise CloudflareError(
+                f"Cloudflare API error: {', '.join(error_messages)}",
+                status_code=response.status_code,
+                errors=errors,
+            )
+        return data
+
+    # DNS Records
+
+    async def get_dns_record(self, name: str, record_type: str = "CNAME") -> DnsRecord | None:
+        """
+        Get a DNS record by name and type.
+
+        Returns None if the record doesn't exist.
+        """
+        params = {"type": record_type, "name": name}
+        response = await self.session.get(f"/zones/{self.zone_id}/dns_records", params=params)
+        data = self._handle_response(response)
+
+        results = data.get("result", [])
+        if not results:
+            return None
+
+        return cast("DnsRecord", results[0])
+
+    async def create_dns_record(
+        self,
+        name: str,
+        content: str,
+        record_type: str = "CNAME",
+        *,
+        ttl: int = 1,
+        proxied: bool = False,
+        comment: str | None = None,
+    ) -> DnsRecord:
+        """
+        Create a DNS record.
+
+        The ttl parameter defaults to 1 (automatic). Set to a value between 60-86400 for manual TTL.
+        """
+        payload: dict = {
+            "type": record_type,
+            "name": name,
+            "content": content,
+            "ttl": ttl,
+            "proxied": proxied,
+        }
+        if comment:
+            payload["comment"] = comment
+
+        response = await self.session.post(f"/zones/{self.zone_id}/dns_records", json=payload)
+        data = self._handle_response(response)
+        return cast("DnsRecord", data["result"])
+
+    async def delete_dns_record(self, record_id: str) -> None:
+        """Delete a DNS record by ID."""
+        response = await self.session.delete(f"/zones/{self.zone_id}/dns_records/{record_id}")
+        self._handle_response(response)
+
+    async def delete_dns_record_by_name(self, name: str, record_type: str = "CNAME") -> bool:
+        """
+        Delete a DNS record by name and type.
+
+        Returns True if deleted, False if the record didn't exist.
+        """
+        record = await self.get_dns_record(name, record_type)
+        if record is None:
+            return False
+
+        await self.delete_dns_record(record["id"])
+        return True
+
+    async def dns_record_exists(self, name: str, record_type: str = "CNAME") -> bool:
+        """Check if a DNS record exists."""
+        return await self.get_dns_record(name, record_type) is not None

tracktolib/cf/types.py

@@ -0,0 +1,17 @@
+from typing import NotRequired, TypedDict
+
+
+class DnsRecord(TypedDict):
+    """Cloudflare DNS record response."""
+
+    id: str
+    name: str
+    type: str
+    content: str
+    ttl: int
+    proxied: bool
+    proxiable: NotRequired[bool]
+    created_on: NotRequired[str]
+    modified_on: NotRequired[str]
+    comment: NotRequired[str]
+    tags: NotRequired[list[str]]

tracktolib/gh/__init__.py

@@ -0,0 +1,11 @@
+from .client import GitHubClient, ProgressCallback
+from .types import Deployment, DeploymentStatus, IssueComment, Label
+
+__all__ = [
+    "Deployment",
+    "DeploymentStatus",
+    "GitHubClient",
+    "IssueComment",
+    "Label",
+    "ProgressCallback",
+]

tracktolib/gh/client.py

@@ -0,0 +1,206 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Callable, cast
+from urllib.parse import quote
+
+try:
+    import niquests
+except ImportError:
+    raise ImportError('Please install niquests or tracktolib with "gh" to use this module')
+
+if TYPE_CHECKING:
+    from urllib3.util.retry import Retry
+
+    from tracktolib.gh.types import Deployment, DeploymentStatus, IssueComment, Label
+
+
+ProgressCallback = Callable[[int, int], None]
+
+
+@dataclass
+class GitHubClient:
+    """
+    Async GitHub API client for issues, labels, and deployments.
+    """
+
+    token: str | None = field(default_factory=lambda: os.environ.get("GITHUB_TOKEN"))
+    base_url: str = "https://api.github.com"
+    retries: int | Retry = 0
+    hooks: Any = None
+    session: niquests.AsyncSession = field(init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        if not self.token:
+            raise ValueError("GITHUB_TOKEN environment variable is required")
+
+        self.session = niquests.AsyncSession(
+            base_url=self.base_url,
+            retries=self.retries,
+            hooks=self.hooks,
+            headers={
+                "Authorization": f"Bearer {self.token}",
+                "Accept": "application/vnd.github+json",
+                "X-GitHub-Api-Version": "2022-11-28",
+            },
+        )
+
+    async def __aenter__(self) -> GitHubClient:
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Close the underlying session."""
+        await self.session.close()
+
+    # Issue Comments
+
+    async def get_issue_comments(self, repository: str, issue_number: int) -> list[IssueComment]:
+        """Get all comments on an issue or PR."""
+        response = await self.session.get(f"/repos/{repository}/issues/{issue_number}/comments")
+        response.raise_for_status()
+        return cast("list[IssueComment]", response.json())
+
+    async def create_issue_comment(self, repository: str, issue_number: int, body: str) -> IssueComment:
+        """Create a comment on an issue or PR."""
+        response = await self.session.post(f"/repos/{repository}/issues/{issue_number}/comments", json={"body": body})
+        response.raise_for_status()
+        return cast("IssueComment", response.json())
+
+    async def delete_issue_comment(self, repository: str, comment_id: int) -> None:
+        """Delete a comment by ID."""
+        response = await self.session.delete(f"/repos/{repository}/issues/comments/{comment_id}")
+        response.raise_for_status()
+
+    async def find_comments_with_marker(self, repository: str, issue_number: int, marker: str) -> list[int]:
+        """Find comment IDs containing a specific marker string."""
+        comments = await self.get_issue_comments(repository, issue_number)
+        return [c["id"] for c in comments if marker in c.get("body", "")]
+
+    async def delete_comments_with_marker(
+        self,
+        repository: str,
+        issue_number: int,
+        marker: str,
+        *,
+        on_progress: ProgressCallback | None = None,
+    ) -> int:
+        """Delete all comments containing a specific marker. Returns count deleted."""
+        comment_ids = await self.find_comments_with_marker(repository, issue_number, marker)
+        total = len(comment_ids)
+        for i, comment_id in enumerate(comment_ids):
+            await self.delete_issue_comment(repository, comment_id)
+            if on_progress:
+                on_progress(i + 1, total)
+        return total
+
+    async def create_idempotent_comment(
+        self, repository: str, issue_number: int, body: str, marker: str
+    ) -> IssueComment | None:
+        """
+        Create a comment only if one with the marker doesn't already exist.
+
+        The marker should be included in the body (e.g., an HTML comment like
+        '<!-- my-marker -->'). Returns the created comment, or None if skipped.
+        """
+        if await self.find_comments_with_marker(repository, issue_number, marker):
+            return None
+        return await self.create_issue_comment(repository, issue_number, body)
+
+    # Labels
+
+    async def get_issue_labels(self, repository: str, issue_number: int) -> list[Label]:
+        """Get all labels on an issue or PR."""
+        response = await self.session.get(f"/repos/{repository}/issues/{issue_number}/labels")
+        response.raise_for_status()
+        return cast("list[Label]", response.json())
+
+    async def add_labels(self, repository: str, issue_number: int, labels: list[str]) -> list[Label]:
+        """Add labels to an issue or PR."""
+        response = await self.session.post(f"/repos/{repository}/issues/{issue_number}/labels", json={"labels": labels})
+        response.raise_for_status()
+        return cast("list[Label]", response.json())
+
+    async def remove_label(self, repository: str, issue_number: int, label: str) -> bool:
+        """Remove a label from an issue/PR. Returns True if removed, False if not found."""
+        response = await self.session.delete(
+            f"/repos/{repository}/issues/{issue_number}/labels/{quote(label, safe='')}"
+        )
+        if response.status_code == 404:
+            return False
+        response.raise_for_status()
+        return True
+
+    # Deployments
+
+    async def get_deployments(self, repository: str, *, environment: str | None = None) -> list[Deployment]:
+        """Get deployments, optionally filtered by environment."""
+        params = {"environment": environment} if environment else {}
+        response = await self.session.get(f"/repos/{repository}/deployments", params=params)
+        response.raise_for_status()
+        return cast("list[Deployment]", response.json())
+
+    async def create_deployment_status(
+        self,
+        repository: str,
+        deployment_id: int,
+        state: str,
+        *,
+        description: str | None = None,
+        environment_url: str | None = None,
+    ) -> DeploymentStatus:
+        """
+        Create a deployment status.
+
+        State can be: error, failure, inactive, in_progress, queued, pending, success.
+        """
+        payload: dict = {"state": state}
+        if description:
+            payload["description"] = description
+        if environment_url:
+            payload["environment_url"] = environment_url
+        response = await self.session.post(f"/repos/{repository}/deployments/{deployment_id}/statuses", json=payload)
+        response.raise_for_status()
+        return cast("DeploymentStatus", response.json())
+
+    async def get_deployment_statuses(
+        self,
+        repository: str,
+        deployment_id: int,
+    ) -> list[DeploymentStatus]:
+        """Get all statuses for a deployment, most recent first."""
+        response = await self.session.get(f"/repos/{repository}/deployments/{deployment_id}/statuses")
+        response.raise_for_status()
+        return cast("list[DeploymentStatus]", response.json())
+
+    async def get_latest_deployment_status(
+        self,
+        repository: str,
+        environment: str,
+    ) -> DeploymentStatus | None:
+        """Get the latest deployment status for an environment."""
+        deployments = await self.get_deployments(repository, environment=environment)
+        if not deployments:
+            return None
+        statuses = await self.get_deployment_statuses(repository, deployments[0]["id"])
+        return statuses[0] if statuses else None
+
+    async def mark_deployment_inactive(
+        self,
+        repository: str,
+        environment: str,
+        *,
+        description: str = "Environment removed",
+        on_progress: ProgressCallback | None = None,
+    ) -> int:
+        """Mark all deployments for an environment as inactive. Returns count updated."""
+        deployments = await self.get_deployments(repository, environment=environment)
+        total = len(deployments)
+        for i, deployment in enumerate(deployments):
+            await self.create_deployment_status(repository, deployment["id"], "inactive", description=description)
+            if on_progress:
+                on_progress(i + 1, total)
+        return total

tracktolib/gh/types.py

@@ -0,0 +1,203 @@
+# generated by datamodel-codegen:
+#   timestamp: 2026-02-02T13:26:29+00:00
+
+from typing import Any, Literal, NotRequired, TypedDict
+
+
+class SimpleUser(TypedDict):
+    """
+    A GitHub user.
+    """
+
+    name: NotRequired[str]
+    email: NotRequired[str]
+    login: str
+    id: int
+    node_id: str
+    avatar_url: str
+    gravatar_id: str
+    url: str
+    html_url: str
+    followers_url: str
+    following_url: str
+    gists_url: str
+    starred_url: str
+    subscriptions_url: str
+    organizations_url: str
+    repos_url: str
+    events_url: str
+    received_events_url: str
+    type: str
+    site_admin: bool
+    starred_at: NotRequired[str]
+    user_view_type: NotRequired[str]
+
+
+class NullableSimpleUser(TypedDict):
+    """
+    A GitHub user.
+    """
+
+    name: NotRequired[str]
+    email: NotRequired[str]
+    login: str
+    id: int
+    node_id: str
+    avatar_url: str
+    gravatar_id: str
+    url: str
+    html_url: str
+    followers_url: str
+    following_url: str
+    gists_url: str
+    starred_url: str
+    subscriptions_url: str
+    organizations_url: str
+    repos_url: str
+    events_url: str
+    received_events_url: str
+    type: str
+    site_admin: bool
+    starred_at: NotRequired[str]
+    user_view_type: NotRequired[str]
+
+
+class Label(TypedDict):
+    """
+    Color-coded labels help you categorize and filter your issues (just like labels in Gmail).
+    """
+
+    id: int
+    node_id: str
+    url: str
+    name: str
+    description: str
+    color: str
+    default: bool
+
+
+class Permissions(TypedDict, total=False):
+    """
+    The set of permissions for the GitHub app.
+
+    Note: GitHub returns many dynamic permission fields; only common ones are typed.
+    """
+
+    issues: str
+    checks: str
+    metadata: str
+    contents: str
+    deployments: str
+    pull_requests: str
+    statuses: str
+    actions: str
+    administration: str
+    pages: str
+    packages: str
+    security_events: str
+
+
+ReactionRollup = TypedDict(
+    "ReactionRollup",
+    {
+        "url": str,
+        "total_count": int,
+        "+1": int,
+        "-1": int,
+        "laugh": int,
+        "confused": int,
+        "heart": int,
+        "hooray": int,
+        "eyes": int,
+        "rocket": int,
+    },
+)
+
+
+class NullableIntegration(TypedDict):
+    """
+    GitHub apps are a new way to extend GitHub. They can be installed directly on organizations and user accounts and granted access to specific repositories. They come with granular permissions and built-in webhooks. GitHub apps are first class actors within GitHub.
+    """
+
+    id: int
+    slug: NotRequired[str]
+    node_id: str
+    client_id: NotRequired[str]
+    owner: SimpleUser | Any
+    name: str
+    description: str
+    external_url: str
+    html_url: str
+    created_at: str
+    updated_at: str
+    permissions: Permissions
+    events: list[str]
+    installations_count: NotRequired[int]
+
+
+class IssueComment(TypedDict):
+    """
+    Comments provide a way for people to collaborate on an issue.
+    """
+
+    id: int
+    node_id: str
+    url: str
+    body: NotRequired[str]
+    body_text: NotRequired[str]
+    body_html: NotRequired[str]
+    html_url: str
+    user: NullableSimpleUser
+    created_at: str
+    updated_at: str
+    issue_url: str
+    author_association: NotRequired[Any]
+    performed_via_github_app: NotRequired[NullableIntegration]
+    reactions: NotRequired[ReactionRollup]
+
+
+class Deployment(TypedDict):
+    """
+    A request for a specific ref(branch,sha,tag) to be deployed
+    """
+
+    url: str
+    id: int
+    node_id: str
+    sha: str
+    ref: str
+    task: str
+    payload: dict[str, Any] | str
+    original_environment: NotRequired[str]
+    environment: str
+    description: str
+    creator: NullableSimpleUser
+    created_at: str
+    updated_at: str
+    statuses_url: str
+    repository_url: str
+    transient_environment: NotRequired[bool]
+    production_environment: NotRequired[bool]
+    performed_via_github_app: NotRequired[NullableIntegration]
+
+
+class DeploymentStatus(TypedDict):
+    """
+    The status of a deployment.
+    """
+
+    url: str
+    id: int
+    node_id: str
+    state: Literal["error", "failure", "inactive", "pending", "success", "queued", "in_progress"]
+    creator: NullableSimpleUser
+    description: str
+    environment: NotRequired[str]
+    target_url: str
+    created_at: str
+    updated_at: str
+    deployment_url: str
+    repository_url: str
+    environment_url: NotRequired[str]
+    log_url: NotRequired[str]
+    performed_via_github_app: NotRequired[NullableIntegration]