neptune-sdk 0.0.1.dev580__py3-none-any.whl

neptune_sdk/__init__.py

@@ -0,0 +1,69 @@
+"""Neptune SDK — async Python client for the Neptune BitTorrent JSON-RPC API."""
+
+from .client import NeptuneClient
+from .exceptions import NeptuneConnectionError, NeptuneError, NeptuneRPCError
+from .models import (
+    AddTorrentRequest,
+    AddTorrentResponse,
+    AddTrackerRequest,
+    DelCustomRequest,
+    InfoHashRequest,
+    ListTorrentRequest,
+    MainDataTorrent,
+    MoveTorrentRequest,
+    Peer,
+    RemoveTorrentRequest,
+    RemoveTrackerRequest,
+    ReplaceTrackersRequest,
+    SetCustomRequest,
+    SetFilePriorityRequest,
+    SetGlobalSpeedLimitRequest,
+    SetSpeedLimitRequest,
+    TagsRequest,
+    TorrentFile,
+    TorrentFilesResponse,
+    TorrentInfo,
+    TorrentListResponse,
+    TorrentPeersResponse,
+    TorrentTrackersResponse,
+    Tracker,
+    TransferSummary,
+    UpdateCustomRequest,
+)
+
+__all__ = [
+    # client
+    "NeptuneClient",
+    # exceptions
+    "NeptuneError",
+    "NeptuneRPCError",
+    "NeptuneConnectionError",
+    # request models
+    "AddTorrentRequest",
+    "AddTrackerRequest",
+    "DelCustomRequest",
+    "InfoHashRequest",
+    "ListTorrentRequest",
+    "MoveTorrentRequest",
+    "RemoveTorrentRequest",
+    "RemoveTrackerRequest",
+    "ReplaceTrackersRequest",
+    "SetCustomRequest",
+    "SetFilePriorityRequest",
+    "SetGlobalSpeedLimitRequest",
+    "SetSpeedLimitRequest",
+    "TagsRequest",
+    "UpdateCustomRequest",
+    # response / domain models
+    "AddTorrentResponse",
+    "MainDataTorrent",
+    "Peer",
+    "TorrentFile",
+    "TorrentFilesResponse",
+    "TorrentInfo",
+    "TorrentListResponse",
+    "TorrentPeersResponse",
+    "TorrentTrackersResponse",
+    "Tracker",
+    "TransferSummary",
+]

neptune_sdk/client.py

@@ -0,0 +1,311 @@
+"""Sync Python client for the Neptune BitTorrent JSON-RPC API."""
+
+from __future__ import annotations
+
+import base64
+import json
+import random
+from dataclasses import asdict
+from functools import cache
+from typing import Any, TypeVar
+
+import httpx
+from pydantic import TypeAdapter
+
+from .exceptions import NeptuneConnectionError, NeptuneRPCError
+from .models import (
+    AddTorrentRequest,
+    AddTorrentResponse,
+    AddTrackerRequest,
+    DelCustomRequest,
+    InfoHashRequest,
+    ListTorrentRequest,
+    MoveTorrentRequest,
+    RemoveTorrentRequest,
+    RemoveTrackerRequest,
+    ReplaceTrackersRequest,
+    SetCustomRequest,
+    SetFilePriorityRequest,
+    SetGlobalSpeedLimitRequest,
+    SetSpeedLimitRequest,
+    TagsRequest,
+    TorrentFilesResponse,
+    TorrentInfo,
+    TorrentListResponse,
+    TorrentPeersResponse,
+    TorrentTrackersResponse,
+    TransferSummary,
+    UpdateCustomRequest,
+)
+
+T = TypeVar("T")
+
+
+def _json_default(obj: Any) -> Any:
+    if isinstance(obj, (bytes, bytearray)):
+        return base64.b64encode(obj).decode()
+    raise TypeError(f"Object of type {type(obj).__name__} is not JSON serializable")
+
+
+@cache
+def _adapter(cls: type[T]) -> TypeAdapter[T]:
+    return TypeAdapter(cls)
+
+
+def _validate(cls: type[T], data: Any) -> T:
+    return _adapter(cls).validate_python(data)
+
+
+class NeptuneClient:
+    """Sync JSON-RPC client for Neptune.
+
+    Example::
+
+        with NeptuneClient("http://127.0.0.1:8002", token="secret") as c:
+            torrents = c.torrent_list()
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        token: str,
+        timeout: float = 30.0,
+    ) -> None:
+        self._client = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            headers={"Authorization": token},
+            timeout=timeout,
+        )
+
+    # ── lifecycle ──────────────────────────────────────────────────────
+
+    def __enter__(self) -> NeptuneClient:
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._client.close()
+
+    # ── transport ──────────────────────────────────────────────────────
+
+    def _call(self, method: str, params: Any = None) -> Any:
+        """Send a JSON-RPC request and return the result field."""
+        payload: dict[str, Any] = {
+            "jsonrpc": "2.0",
+            "method": method,
+            "id": random.randint(1, 2**31),
+        }
+        if params is not None:
+            payload["params"] = asdict(params)
+
+        body_bytes = json.dumps(payload, default=_json_default).encode()
+
+        try:
+            resp = self._client.post(
+                "/json_rpc",
+                content=body_bytes,
+                headers={"Content-Type": "application/json"},
+            )
+            resp.raise_for_status()
+        except httpx.HTTPError as exc:
+            raise NeptuneConnectionError(str(exc)) from exc
+
+        body = resp.json()
+
+        if "error" in body and body["error"] is not None:
+            err = body["error"]
+            raise NeptuneRPCError(
+                code=err.get("code", -1),
+                message=err.get("message", ""),
+                data=err.get("data"),
+            )
+
+        return body.get("result")
+
+    # ── system ─────────────────────────────────────────────────────────
+
+    def ping(self) -> None:
+        """system.ping — health check."""
+        self._call("system.ping")
+
+    # ── transfer ───────────────────────────────────────────────────────
+
+    def transfer_summary(self) -> TransferSummary:
+        """Global download/upload rates and totals."""
+        return _validate(TransferSummary, self._call("transfer_summary"))
+
+    # ── torrent — queries ──────────────────────────────────────────────
+
+    def torrent_list(self, keys: list[str] | None = None) -> TorrentListResponse:
+        """List all torrents. Optionally filter custom keys returned."""
+        return _validate(
+            TorrentListResponse,
+            self._call("torrent.list", ListTorrentRequest(keys=keys or None)),
+        )
+
+    def torrent_get(self, info_hash: str) -> TorrentInfo:
+        """Get basic info for a single torrent."""
+        return _validate(
+            TorrentInfo,
+            self._call("torrent.get", InfoHashRequest(info_hash=info_hash)),
+        )
+
+    def torrent_files(self, info_hash: str) -> TorrentFilesResponse:
+        """List files in a torrent."""
+        return _validate(
+            TorrentFilesResponse,
+            self._call("torrent.files", InfoHashRequest(info_hash=info_hash)),
+        )
+
+    def torrent_peers(self, info_hash: str) -> TorrentPeersResponse:
+        """List connected peers for a torrent."""
+        return _validate(
+            TorrentPeersResponse,
+            self._call("torrent.peers", InfoHashRequest(info_hash=info_hash)),
+        )
+
+    def torrent_trackers(self, info_hash: str) -> TorrentTrackersResponse:
+        """List trackers for a torrent."""
+        return _validate(
+            TorrentTrackersResponse,
+            self._call("torrent.trackers", InfoHashRequest(info_hash=info_hash)),
+        )
+
+    def torrent_add_tracker(self, info_hash: str, url: str, *, tier: int = 0) -> None:
+        """Add a tracker to a torrent."""
+        self._call(
+            "torrent.add_tracker",
+            AddTrackerRequest(info_hash=info_hash, url=url, tier=tier),
+        )
+
+    def torrent_remove_tracker(self, info_hash: str, url: str) -> None:
+        """Remove a tracker from a torrent."""
+        self._call(
+            "torrent.remove_tracker",
+            RemoveTrackerRequest(info_hash=info_hash, url=url),
+        )
+
+    def torrent_replace_trackers(
+        self, info_hash: str, replacements: dict[str, str]
+    ) -> None:
+        """Replace tracker URLs. Keys are old URLs, values are new URLs."""
+        self._call(
+            "torrent.replace_trackers",
+            ReplaceTrackersRequest(info_hash=info_hash, replacements=replacements),
+        )
+
+    # ── torrent — mutations ────────────────────────────────────────────
+
+    def torrent_add(self, req: AddTorrentRequest) -> AddTorrentResponse:
+        """Add a torrent from raw .torrent bytes."""
+        return _validate(AddTorrentResponse, self._call("torrent.add", req))
+
+    def torrent_move(self, info_hash: str, target_base_path: str) -> None:
+        """Move torrent data to a new directory."""
+        self._call(
+            "torrent.move",
+            MoveTorrentRequest(info_hash=info_hash, target_base_path=target_base_path),
+        )
+
+    def torrent_remove(
+        self, info_hash: str, *, delete_data: bool = False
+    ) -> TorrentListResponse:
+        """Remove a torrent and return updated list."""
+        return _validate(
+            TorrentListResponse,
+            self._call(
+                "torrent.remove",
+                RemoveTorrentRequest(info_hash=info_hash, delete_data=delete_data),
+            ),
+        )
+
+    def torrent_start(self, info_hash: str) -> None:
+        """Start a torrent."""
+        self._call("torrent.start", InfoHashRequest(info_hash=info_hash))
+
+    def torrent_stop(self, info_hash: str) -> None:
+        """Stop a torrent."""
+        self._call("torrent.stop", InfoHashRequest(info_hash=info_hash))
+
+    def torrent_recheck(self, info_hash: str) -> None:
+        """Recheck torrent data integrity."""
+        self._call("torrent.recheck", InfoHashRequest(info_hash=info_hash))
+
+    # ── torrent — custom ───────────────────────────────────────────────
+
+    def torrent_custom_set(self, info_hash: str, key: str, value: str) -> None:
+        """Set a custom key-value pair on a torrent."""
+        self._call(
+            "torrent.custom.set",
+            SetCustomRequest(info_hash=info_hash, key=key, value=value),
+        )
+
+    def torrent_custom_update(self, info_hash: str, custom: dict[str, str]) -> None:
+        """Update multiple custom key-value pairs on a torrent."""
+        self._call(
+            "torrent.custom.update",
+            UpdateCustomRequest(info_hash=info_hash, custom=custom),
+        )
+
+    def torrent_custom_del(self, info_hash: str, key: str) -> None:
+        """Delete a custom key from a torrent."""
+        self._call(
+            "torrent.custom.del",
+            DelCustomRequest(info_hash=info_hash, key=key),
+        )
+
+    def torrent_add_tags(self, info_hash: str, tags: list[str]) -> None:
+        """Add tags to a torrent."""
+        self._call("torrent.add_tags", TagsRequest(info_hash=info_hash, tags=tags))
+
+    def torrent_remove_tags(self, info_hash: str, tags: list[str]) -> None:
+        """Remove tags from a torrent."""
+        self._call("torrent.remove_tags", TagsRequest(info_hash=info_hash, tags=tags))
+
+    # ── torrent — limits ───────────────────────────────────────────────
+
+    def torrent_set_download_limit(self, info_hash: str, limit: int) -> None:
+        """Set per-torrent download speed limit (bytes/s, <=0 = unlimited)."""
+        self._call(
+            "torrent.set_download_limit",
+            SetSpeedLimitRequest(info_hash=info_hash, limit=limit),
+        )
+
+    def torrent_set_upload_limit(self, info_hash: str, limit: int) -> None:
+        """Set per-torrent upload speed limit (bytes/s, <=0 = unlimited)."""
+        self._call(
+            "torrent.set_upload_limit",
+            SetSpeedLimitRequest(info_hash=info_hash, limit=limit),
+        )
+
+    def client_set_download_limit(self, limit: int) -> None:
+        """Set global download speed limit (bytes/s, <=0 = unlimited)."""
+        self._call(
+            "client.set_download_limit",
+            SetGlobalSpeedLimitRequest(limit=limit),
+        )
+
+    def client_set_upload_limit(self, limit: int) -> None:
+        """Set global upload speed limit (bytes/s, <=0 = unlimited)."""
+        self._call(
+            "client.set_upload_limit",
+            SetGlobalSpeedLimitRequest(limit=limit),
+        )
+
+    # ── torrent — file priority ────────────────────────────────────────
+
+    def torrent_set_file_priority(
+        self, info_hash: str, file_ids: list[int], priority: int
+    ) -> None:
+        """Set file priority (0 = skip, 1 = download)."""
+        self._call(
+            "torrent.set_file_priority",
+            SetFilePriorityRequest(
+                info_hash=info_hash,
+                file_ids=file_ids,
+                priority=priority,
+            ),
+        )

neptune_sdk/exceptions.py

@@ -0,0 +1,16 @@
+class NeptuneError(Exception):
+    """Base exception for Neptune SDK."""
+
+
+class NeptuneRPCError(NeptuneError):
+    """Raised when the JSON-RPC server returns an error response."""
+
+    def __init__(self, code: int, message: str, data: object = None) -> None:
+        self.code = code
+        self.message = message
+        self.data = data
+        super().__init__(f"RPC error {code}: {message}")
+
+
+class NeptuneConnectionError(NeptuneError):
+    """Raised when the HTTP connection to Neptune fails."""

neptune_sdk/models.py

@@ -0,0 +1,250 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# ── Shared domain types ──────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class MainDataTorrent:
+    """A torrent entry returned by torrent.list / torrent.remove."""
+
+    hash: str
+    name: str
+    state: str
+    comment: str
+    directory_base: str
+    message: str
+    tracker_errors: dict[str, str]
+    tags: list[str]
+    custom: dict[str, str]
+    download_rate: int
+    download_total: int
+    upload_rate: int
+    upload_total: int
+    connection_count: int
+    completed: int
+    total_length: int
+    selected_size: int
+    add_at: int
+    private: bool
+    total_seeding: int
+    total_downloading: int
+    connected_seeding: int
+    connected_downloading: int
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class TransferSummary:
+    """Global transfer rates and totals."""
+
+    download_rate: int
+    download_total: int
+    upload_rate: int
+    upload_total: int
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class TorrentFile:
+    """A single file inside a torrent."""
+
+    path: list[str]
+    index: int
+    progress: float
+    size: int
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Peer:
+    """A connected peer."""
+
+    address: str
+    client: str
+    progress: float
+    download_rate: int
+    upload_rate: int
+    is_incoming: bool
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Tracker:
+    """A tracker entry."""
+
+    url: str
+    tier: int
+    message: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class TorrentInfo:
+    """Basic torrent metadata from torrent.get."""
+
+    name: str
+    tags: list[str]
+    custom: dict[str, str]
+
+
+# ── Request types ─────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AddTorrentRequest:
+    """Parameters for torrent.add."""
+
+    torrent_file: bytes
+    download_dir: str | None = None
+    tags: list[str] | None = None
+    custom: dict[str, str] | None = None
+    selected_files: list[int] | None = None
+    is_base_dir: bool = False
+    skip_hash_check: bool = False
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class InfoHashRequest:
+    """Common request that only needs an info_hash."""
+
+    info_hash: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class MoveTorrentRequest:
+    """Parameters for torrent.move."""
+
+    info_hash: str
+    target_base_path: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class RemoveTorrentRequest:
+    """Parameters for torrent.remove."""
+
+    info_hash: str
+    delete_data: bool = False
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class TagsRequest:
+    """Parameters for torrent.add_tags / torrent.remove_tags."""
+
+    info_hash: str
+    tags: list[str]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SetFilePriorityRequest:
+    """Parameters for torrent.set_file_priority."""
+
+    info_hash: str
+    file_ids: list[int]
+    priority: int = 0
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SetSpeedLimitRequest:
+    """Parameters for torrent.set_download_limit / torrent.set_upload_limit."""
+
+    info_hash: str
+    limit: int = 0
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SetGlobalSpeedLimitRequest:
+    """Parameters for client.set_download_limit / client.set_upload_limit."""
+
+    limit: int = 0
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ListTorrentRequest:
+    """Parameters for torrent.list."""
+
+    keys: list[str] | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SetCustomRequest:
+    """Parameters for torrent.custom.set."""
+
+    info_hash: str
+    key: str
+    value: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class UpdateCustomRequest:
+    """Parameters for torrent.custom.update."""
+
+    info_hash: str
+    custom: dict[str, str]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class DelCustomRequest:
+    """Parameters for torrent.custom.del."""
+
+    info_hash: str
+    key: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AddTrackerRequest:
+    """Parameters for torrent.add_tracker."""
+
+    info_hash: str
+    url: str
+    tier: int = 0
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class RemoveTrackerRequest:
+    """Parameters for torrent.remove_tracker."""
+
+    info_hash: str
+    url: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ReplaceTrackersRequest:
+    """Parameters for torrent.replace_trackers."""
+
+    info_hash: str
+    replacements: dict[str, str]
+
+
+# ── Response types ────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class TorrentListResponse:
+    """Response for torrent.list and torrent.remove."""
+
+    torrents: list[MainDataTorrent]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AddTorrentResponse:
+    """Response for torrent.add."""
+
+    info_hash: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class TorrentFilesResponse:
+    """Response for torrent.files."""
+
+    files: list[TorrentFile]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class TorrentPeersResponse:
+    """Response for torrent.peers."""
+
+    peers: list[Peer]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class TorrentTrackersResponse:
+    """Response for torrent.trackers."""
+
+    trackers: list[Tracker]

neptune_sdk-0.0.1.dev580.dist-info/METADATA

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: neptune-sdk
+Version: 0.0.1.dev580
+Summary: Python SDK for Neptune BitTorrent client JSON-RPC API
+License-Expression: GPL-3.0-only
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2
+

neptune_sdk-0.0.1.dev580.dist-info/RECORD

@@ -0,0 +1,8 @@
+neptune_sdk-0.0.1.dev580.dist-info/METADATA,sha256=Z5S1QlqDPFkAurZ1W6iMx99bUHoz8Nh5SxvXppaqZgg,237
+neptune_sdk-0.0.1.dev580.dist-info/WHEEL,sha256=VP-D4TPS230sME9Z3vb3INXvo1yt0924YRm5AOsk_dE,90
+neptune_sdk-0.0.1.dev580.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
+neptune_sdk/__init__.py,sha256=LJ3Ll8OXefHysJ6PZM4s8mjhQFt1hCO-S7BTwa522g4,1655
+neptune_sdk/client.py,sha256=5P6eFWU4q9oLihmb_oAmrGnVJ_u32r7WxdroFVc-rIw,11279
+neptune_sdk/exceptions.py,sha256=7nPIjKEzsODbXrxyeD3d4jkbTiIJOEVa2KEwzCrEBUE,504
+neptune_sdk/models.py,sha256=W7RdwGIQ5uiW-iEpJ0WxlXWHEdjNggU4fFhY3be_R7Q,5706
+neptune_sdk-0.0.1.dev580.dist-info/RECORD,,

neptune_sdk-0.0.1.dev580.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: pdm-backend (2.4.9)
+Root-Is-Purelib: true
+Tag: py3-none-any

neptune_sdk-0.0.1.dev580.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+
+[gui_scripts]
+