tracktolib 0.68.0__tar.gz → 0.69.0__tar.gz

{tracktolib-0.68.0 → tracktolib-0.69.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tracktolib
-Version: 0.68.0
+Version: 0.69.0
 Summary: Utility library for python
 Keywords: utility
 Author-email: julien.brayere@tracktor.fr
@@ -12,6 +12,8 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Requires-Dist: fastapi>=0.103.2 ; extra == 'api'
 Requires-Dist: pydantic>=2 ; extra == 'api'
+Requires-Dist: niquests>=3.17.0 ; extra == 'cf'
+Requires-Dist: niquests>=3.17.0 ; extra == 'gh'
 Requires-Dist: httpx>=0.25.0 ; extra == 'http'
 Requires-Dist: python-json-logger>=3.2.1 ; extra == 'logs'
 Requires-Dist: niquests>=3.17.0 ; extra == 'notion'
@@ -26,6 +28,8 @@ Requires-Dist: niquests>=3.17.0 ; extra == 's3-niquests'
 Requires-Dist: deepdiff>=8.1.0 ; extra == 'tests'
 Requires-Python: >=3.12, <4.0
 Provides-Extra: api
+Provides-Extra: cf
+Provides-Extra: gh
 Provides-Extra: http
 Provides-Extra: logs
 Provides-Extra: notion
@@ -126,12 +130,42 @@ uv add tracktolib[s3-minio]
 
 ### s3-niquests
 
-Async S3 helpers using [niquests](https://github.com/jawah/niquests) and [botocore](https://github.com/boto/botocore).
+Async S3 helpers using [niquests](https://github.com/jawah/niquests) and [botocore](https://github.com/boto/botocore) presigned URLs.
 
 ```bash
 uv add tracktolib[s3-niquests]
 ```
 
+```python
+from tracktolib.s3.niquests import S3Session
+
+async with S3Session(
+    endpoint_url='http://localhost:9000',
+    access_key='...',
+    secret_key='...',
+    region='us-east-1',
+) as s3:
+    # Object operations
+    await s3.put_object('bucket', 'path/file.txt', b'content')
+    content = await s3.get_object('bucket', 'path/file.txt')
+    await s3.delete_object('bucket', 'path/file.txt')
+
+    # Streaming upload (multipart for large files)
+    async def data_stream():
+        yield b'chunk1'
+        yield b'chunk2'
+    await s3.file_upload('bucket', 'large-file.bin', data_stream())
+
+    # Bucket policy management
+    policy = {'Version': '2012-10-17', 'Statement': [...]}
+    await s3.put_bucket_policy('bucket', policy)
+    await s3.get_bucket_policy('bucket')
+    await s3.delete_bucket_policy('bucket')
+
+    # Empty a bucket (delete all objects)
+    deleted_count = await s3.empty_bucket('bucket')
+```
+
 ### http (deprecated)
 
 HTTP client helpers using [httpx](https://www.python-httpx.org/).
@@ -176,6 +210,65 @@ async with niquests.AsyncSession() as session:
     cache.get_database("db-id")     # Specific database (id, title, properties, cached_at)
 ```
 
+### gh
+
+GitHub API helpers using [niquests](https://github.com/jawah/niquests).
+
+```bash
+uv add tracktolib[gh]
+```
+
+```python
+from tracktolib.gh import GitHubClient
+
+async with GitHubClient() as gh:  # Uses GITHUB_TOKEN env var
+    # Issue comments
+    comments = await gh.get_issue_comments("owner/repo", 123)
+    await gh.create_issue_comment("owner/repo", 123, "Hello!")
+    await gh.delete_comments_with_marker("owner/repo", 123, "<!-- bot -->")
+
+    # Labels
+    labels = await gh.get_issue_labels("owner/repo", 123)
+    await gh.add_labels("owner/repo", 123, ["bug", "priority"])
+    await gh.remove_label("owner/repo", 123, "wontfix")
+
+    # Deployments
+    deploys = await gh.get_deployments("owner/repo", environment="production")
+    await gh.mark_deployment_inactive("owner/repo", "preview-123")
+```
+
+### cf
+
+Cloudflare DNS API helpers using [niquests](https://github.com/jawah/niquests).
+
+```bash
+uv add tracktolib[cf]
+```
+
+```python
+from tracktolib.cf import CloudflareDNSClient
+
+async with CloudflareDNSClient() as cf:  # Uses CLOUDFLARE_API_TOKEN and CLOUDFLARE_ZONE_ID env vars
+    # Get a DNS record
+    record = await cf.get_dns_record("app.example.com", "CNAME")
+
+    # Create a DNS record
+    record = await cf.create_dns_record(
+        "app.example.com",
+        "target.example.com",
+        record_type="CNAME",
+        ttl=60,
+        proxied=True,
+    )
+
+    # Delete by ID or name
+    await cf.delete_dns_record(record["id"])
+    await cf.delete_dns_record_by_name("app.example.com", "CNAME")
+
+    # Check existence
+    exists = await cf.dns_record_exists("app.example.com")
+```
+
 ### tests
 
 Testing utilities using [deepdiff](https://github.com/seperman/deepdiff).

{tracktolib-0.68.0 → tracktolib-0.69.0}/README.md

@@ -87,12 +87,42 @@ uv add tracktolib[s3-minio]
 
 ### s3-niquests
 
-Async S3 helpers using [niquests](https://github.com/jawah/niquests) and [botocore](https://github.com/boto/botocore).
+Async S3 helpers using [niquests](https://github.com/jawah/niquests) and [botocore](https://github.com/boto/botocore) presigned URLs.
 
 ```bash
 uv add tracktolib[s3-niquests]
 ```
 
+```python
+from tracktolib.s3.niquests import S3Session
+
+async with S3Session(
+    endpoint_url='http://localhost:9000',
+    access_key='...',
+    secret_key='...',
+    region='us-east-1',
+) as s3:
+    # Object operations
+    await s3.put_object('bucket', 'path/file.txt', b'content')
+    content = await s3.get_object('bucket', 'path/file.txt')
+    await s3.delete_object('bucket', 'path/file.txt')
+
+    # Streaming upload (multipart for large files)
+    async def data_stream():
+        yield b'chunk1'
+        yield b'chunk2'
+    await s3.file_upload('bucket', 'large-file.bin', data_stream())
+
+    # Bucket policy management
+    policy = {'Version': '2012-10-17', 'Statement': [...]}
+    await s3.put_bucket_policy('bucket', policy)
+    await s3.get_bucket_policy('bucket')
+    await s3.delete_bucket_policy('bucket')
+
+    # Empty a bucket (delete all objects)
+    deleted_count = await s3.empty_bucket('bucket')
+```
+
 ### http (deprecated)
 
 HTTP client helpers using [httpx](https://www.python-httpx.org/).
@@ -137,6 +167,65 @@ async with niquests.AsyncSession() as session:
     cache.get_database("db-id")     # Specific database (id, title, properties, cached_at)
 ```
 
+### gh
+
+GitHub API helpers using [niquests](https://github.com/jawah/niquests).
+
+```bash
+uv add tracktolib[gh]
+```
+
+```python
+from tracktolib.gh import GitHubClient
+
+async with GitHubClient() as gh:  # Uses GITHUB_TOKEN env var
+    # Issue comments
+    comments = await gh.get_issue_comments("owner/repo", 123)
+    await gh.create_issue_comment("owner/repo", 123, "Hello!")
+    await gh.delete_comments_with_marker("owner/repo", 123, "<!-- bot -->")
+
+    # Labels
+    labels = await gh.get_issue_labels("owner/repo", 123)
+    await gh.add_labels("owner/repo", 123, ["bug", "priority"])
+    await gh.remove_label("owner/repo", 123, "wontfix")
+
+    # Deployments
+    deploys = await gh.get_deployments("owner/repo", environment="production")
+    await gh.mark_deployment_inactive("owner/repo", "preview-123")
+```
+
+### cf
+
+Cloudflare DNS API helpers using [niquests](https://github.com/jawah/niquests).
+
+```bash
+uv add tracktolib[cf]
+```
+
+```python
+from tracktolib.cf import CloudflareDNSClient
+
+async with CloudflareDNSClient() as cf:  # Uses CLOUDFLARE_API_TOKEN and CLOUDFLARE_ZONE_ID env vars
+    # Get a DNS record
+    record = await cf.get_dns_record("app.example.com", "CNAME")
+
+    # Create a DNS record
+    record = await cf.create_dns_record(
+        "app.example.com",
+        "target.example.com",
+        record_type="CNAME",
+        ttl=60,
+        proxied=True,
+    )
+
+    # Delete by ID or name
+    await cf.delete_dns_record(record["id"])
+    await cf.delete_dns_record_by_name("app.example.com", "CNAME")
+
+    # Check existence
+    exists = await cf.dns_record_exists("app.example.com")
+```
+
 ### tests
 
 Testing utilities using [deepdiff](https://github.com/seperman/deepdiff).

{tracktolib-0.68.0 → tracktolib-0.69.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tracktolib"
-version = "0.68.0"
+version = "0.69.0"
 authors = [
     { email = "julien.brayere@tracktor.fr" }
 ]
@@ -46,11 +46,13 @@ pg = [
     "asyncpg>=0.27.0",
     "rich>=13.6.0",
 ]
-notion = [
-    "niquests>=3.17.0"
-]
+notion = ["niquests>=3.17.0"]
+gh = ["niquests>=3.17.0"]
+cf = ["niquests>=3.17.0"]
 
 [dependency-groups]
+niquests = ["niquests>=3.17.0"]
+
 dev = [
     "pytest-cov>=7.0.0,<8",
     "pytest>=9.0.1,<10",
@@ -66,9 +68,11 @@ dev = [
     "pycryptodome>=3.23.0",
     "aiobotocore==2.15.2",
     # niquests for s3-niquests tests (botocore comes from aiobotocore)
-    "niquests>=3.17.0",
+    { include-group = "niquests" },
     "python-json-logger>=3.2.0",
     "prek>=0.2.30",
+    "datamodel-code-generator>=0.53.0",
+    "pytest-asyncio>=1.3.0",
 ]
 
 bump = [
@@ -98,6 +102,8 @@ filterwarnings = [
     "ignore::DeprecationWarning",
     "ignore::PendingDeprecationWarning"
 ]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
 
 [tool.pyright]
 include = ["tracktolib", "tests"]
@@ -108,7 +114,7 @@ pythonPlatform = "Linux"
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "0.68.0"
+version = "0.69.0"
 tag_format = "$version"
 version_files = [
     "pyproject.toml:version"
@@ -122,6 +128,9 @@ changelog_file = "CHANGELOG.md"
 line-length = 120
 target-version = "py314"
 
+[tool.ruff.lint]
+# I: isort - consolidates duplicate imports
+extend-select = ["I"]
 
 [tool.ruff.lint.per-file-ignores]
 "__init__.py" = [

{tracktolib-0.68.0 → tracktolib-0.69.0}/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-0.69.0/tracktolib/cf/__init__.py

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

tracktolib-0.69.0/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-0.69.0/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-0.69.0/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",
+]