pharox-sdk 0.2.0__tar.gz

pharox_sdk-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zacarias
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pharox_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: pharox-sdk
+Version: 0.2.0
+Summary: Typed Python SDK for pharox — remote mode (HTTP) and local mode (direct toolkit)
+License: MIT
+License-File: LICENSE
+Author: fzaca
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: httpx (>=0.28,<0.29)
+Requires-Dist: pharox (>=0.8.1,<0.9.0)
+Description-Content-Type: text/markdown
+
+# pharox-sdk
+
+Python SDK for the [Pharox](https://github.com/fzaca/pharox) proxy lifecycle management ecosystem.
+
+Works in two interchangeable modes:
+
+- **Remote mode** — HTTP client for a running `pharox-service`
+- **Local mode** — direct access to `pharox-toolkit` via `IAsyncStorage` (no service required)
+
+## Installation
+
+```bash
+pip install pharox-sdk
+```
+
+## Quick start
+
+```python
+from pharox_sdk import PharoxSDK
+
+# Remote mode
+sdk = PharoxSDK.remote("http://localhost:8000", api_key="my-key")
+
+# Local mode (no service needed)
+from pharox import AsyncInMemoryStorage
+sdk = PharoxSDK.local(AsyncInMemoryStorage())
+
+# Same interface in both modes
+async with sdk.with_lease("my-pool") as lease:
+    if lease:
+        print(lease.proxy_id)
+```
+
+## Links
+
+- [pharox-toolkit](https://github.com/fzaca/pharox) — core library
+- [pharox-service](https://github.com/fzaca/pharox-service) — FastAPI service
+

pharox_sdk-0.2.0/README.md

@@ -0,0 +1,37 @@
+# pharox-sdk
+
+Python SDK for the [Pharox](https://github.com/fzaca/pharox) proxy lifecycle management ecosystem.
+
+Works in two interchangeable modes:
+
+- **Remote mode** — HTTP client for a running `pharox-service`
+- **Local mode** — direct access to `pharox-toolkit` via `IAsyncStorage` (no service required)
+
+## Installation
+
+```bash
+pip install pharox-sdk
+```
+
+## Quick start
+
+```python
+from pharox_sdk import PharoxSDK
+
+# Remote mode
+sdk = PharoxSDK.remote("http://localhost:8000", api_key="my-key")
+
+# Local mode (no service needed)
+from pharox import AsyncInMemoryStorage
+sdk = PharoxSDK.local(AsyncInMemoryStorage())
+
+# Same interface in both modes
+async with sdk.with_lease("my-pool") as lease:
+    if lease:
+        print(lease.proxy_id)
+```
+
+## Links
+
+- [pharox-toolkit](https://github.com/fzaca/pharox) — core library
+- [pharox-service](https://github.com/fzaca/pharox-service) — FastAPI service

pharox_sdk-0.2.0/pyproject.toml

@@ -0,0 +1,47 @@
+[tool.poetry]
+name = "pharox-sdk"
+version = "0.2.0"
+description = "Typed Python SDK for pharox — remote mode (HTTP) and local mode (direct toolkit)"
+authors = ["fzaca"]
+license = "MIT"
+readme = "README.md"
+packages = [{ include = "pharox_sdk", from = "src" }]
+
+[tool.poetry.dependencies]
+python = "^3.10"
+pharox = "^0.8.1"
+httpx = "^0.28"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0"
+pytest-asyncio = "^0.23"
+respx = "^0.21"
+mypy = "^1.10"
+ruff = "^0.4"
+commitizen = "^3.27"
+
+[tool.commitizen]
+name = "cz_conventional_commits"
+tag_format = "v$version"
+version_provider = "poetry"
+update_changelog_on_bump = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+ignore_missing_imports = true
+
+[tool.ruff]
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

pharox_sdk-0.2.0/src/pharox_sdk/__init__.py

@@ -0,0 +1,12 @@
+"""pharox-sdk — typed Python SDK for the Pharox proxy ecosystem."""
+
+from .client import PharoxClient
+from .exceptions import RemoteError, SDKError
+from .sdk import PharoxSDK
+
+__all__ = [
+    "PharoxClient",
+    "PharoxSDK",
+    "RemoteError",
+    "SDKError",
+]

pharox_sdk-0.2.0/src/pharox_sdk/client.py

@@ -0,0 +1,232 @@
+"""Async HTTP client for pharox-service (remote mode low-level API)."""
+from datetime import datetime
+from typing import Any, Optional
+from uuid import UUID
+
+import httpx
+from pharox import (
+    Lease,
+    LeaseStatus,
+    ProxyFilters,
+    ProxyPool,
+    ProxyProtocol,
+    ProxyStatus,
+    SelectorStrategy,
+)
+
+from .exceptions import RemoteError
+
+
+def _parse_pool(data: dict[str, Any]) -> ProxyPool:
+    return ProxyPool(
+        id=UUID(data["id"]),
+        name=data["name"],
+        description=data.get("description", ""),
+    )
+
+
+def _parse_lease(data: dict[str, Any]) -> Lease:
+    pool_id_str = data.get("pool_id") or ""
+    return Lease(
+        id=UUID(data["id"]),
+        proxy_id=UUID(data["proxy_id"]),
+        consumer_id=UUID(data["consumer_id"]),
+        pool_id=UUID(pool_id_str) if pool_id_str else None,
+        status=LeaseStatus(data["status"]),
+        acquired_at=datetime.fromisoformat(data["acquired_at"]),
+        expires_at=datetime.fromisoformat(data["expires_at"]),
+    )
+
+
+class PharoxClient:
+    """
+    Low-level async HTTP client for pharox-service.
+
+    Use as an async context manager or call ``aclose()`` when done.
+
+    Parameters
+    ----------
+    base_url:
+        Base URL of pharox-service (e.g. ``"http://localhost:8000"``).
+    api_key:
+        API key for authentication.
+    timeout:
+        Request timeout in seconds. Defaults to 30.
+    """
+
+    def __init__(
+        self, base_url: str, api_key: str, timeout: float = 30.0
+    ) -> None:
+        self._http = httpx.AsyncClient(
+            base_url=base_url.rstrip("/"),
+            headers={"X-API-Key": api_key},
+            timeout=timeout,
+        )
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "PharoxClient":
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.aclose()
+
+    def _raise_for_status(self, response: httpx.Response) -> None:
+        if response.is_error:
+            try:
+                detail = response.json().get("detail", response.text)
+            except Exception:
+                detail = response.text
+            raise RemoteError(response.status_code, str(detail))
+
+    async def _request(
+        self,
+        method: str,
+        url: str,
+        **kwargs: Any,
+    ) -> httpx.Response:
+        """Execute an HTTP request, wrapping network errors as RemoteError."""
+        try:
+            return await self._http.request(method, url, **kwargs)
+        except httpx.TimeoutException as exc:
+            raise RemoteError(0, f"Request timed out: {exc}") from exc
+        except httpx.NetworkError as exc:
+            raise RemoteError(0, f"Network error: {exc}") from exc
+
+    # ------------------------------------------------------------------
+    # Pools
+    # ------------------------------------------------------------------
+
+    async def create_pool(
+        self, name: str, description: str = ""
+    ) -> ProxyPool:
+        r = await self._request(
+            "POST", "/v1/pools/", json={"name": name, "description": description}
+        )
+        self._raise_for_status(r)
+        return _parse_pool(r.json())
+
+    async def list_pools(self) -> list[ProxyPool]:
+        r = await self._request("GET", "/v1/pools/")
+        self._raise_for_status(r)
+        return [_parse_pool(p) for p in r.json()]
+
+    async def get_pool(self, pool_id: str) -> ProxyPool:
+        r = await self._request("GET", f"/v1/pools/{pool_id}")
+        self._raise_for_status(r)
+        return _parse_pool(r.json())
+
+    async def delete_pool(self, pool_id: str) -> None:
+        r = await self._request("DELETE", f"/v1/pools/{pool_id}")
+        self._raise_for_status(r)
+
+    # ------------------------------------------------------------------
+    # Proxies
+    # ------------------------------------------------------------------
+
+    async def add_proxy(
+        self,
+        pool_id: str,
+        host: str,
+        port: int,
+        protocol: ProxyProtocol = ProxyProtocol.HTTP,
+        username: Optional[str] = None,
+        password: Optional[str] = None,
+        country: Optional[str] = None,
+        city: Optional[str] = None,
+        latitude: Optional[float] = None,
+        longitude: Optional[float] = None,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "host": host,
+            "port": port,
+            "protocol": protocol.value,
+        }
+        if username:
+            payload["username"] = username
+        if password:
+            payload["password"] = password
+        if country:
+            payload["country"] = country
+        if city:
+            payload["city"] = city
+        if latitude is not None:
+            payload["latitude"] = latitude
+        if longitude is not None:
+            payload["longitude"] = longitude
+
+        r = await self._request(
+            "POST", f"/v1/pools/{pool_id}/proxies/", json=payload
+        )
+        self._raise_for_status(r)
+        return r.json()  # type: ignore[no-any-return]
+
+    async def list_proxies(self, pool_id: str) -> list[dict[str, Any]]:
+        r = await self._request("GET", f"/v1/pools/{pool_id}/proxies/")
+        self._raise_for_status(r)
+        return r.json()  # type: ignore[no-any-return]
+
+    async def update_proxy_status(
+        self, pool_id: str, proxy_id: str, status: ProxyStatus
+    ) -> dict[str, Any]:
+        r = await self._request(
+            "PATCH",
+            f"/v1/pools/{pool_id}/proxies/{proxy_id}",
+            json={"status": status.value},
+        )
+        self._raise_for_status(r)
+        return r.json()  # type: ignore[no-any-return]
+
+    async def delete_proxy(self, pool_id: str, proxy_id: str) -> None:
+        r = await self._request(
+            "DELETE", f"/v1/pools/{pool_id}/proxies/{proxy_id}"
+        )
+        self._raise_for_status(r)
+
+    # ------------------------------------------------------------------
+    # Leases
+    # ------------------------------------------------------------------
+
+    async def acquire_lease(
+        self,
+        pool_id: str,
+        consumer_id: str,
+        ttl_seconds: int = 300,
+        filters: Optional[ProxyFilters] = None,
+        selector: Optional[SelectorStrategy] = None,
+    ) -> Optional[Lease]:
+        """
+        Returns the acquired Lease or None if no proxy is available (HTTP 409).
+        Raises RemoteError for any other non-2xx response.
+        """
+        payload: dict[str, Any] = {
+            "pool_id": pool_id,
+            "consumer_id": consumer_id,
+            "ttl_seconds": ttl_seconds,
+            "strategy": (
+                selector.value
+                if selector
+                else SelectorStrategy.FIRST_AVAILABLE.value
+            ),
+        }
+        if filters:
+            payload["filters"] = filters.model_dump(exclude_none=True)
+
+        r = await self._request("POST", "/v1/leases/", json=payload)
+        if r.status_code == 409:
+            return None
+        self._raise_for_status(r)
+        return _parse_lease(r.json())
+
+    async def get_lease(self, lease_id: str) -> Optional[Lease]:
+        r = await self._request("GET", f"/v1/leases/{lease_id}")
+        if r.status_code == 404:
+            return None
+        self._raise_for_status(r)
+        return _parse_lease(r.json())
+
+    async def release_lease(self, lease_id: str) -> Lease:
+        r = await self._request("POST", f"/v1/leases/{lease_id}/release", json={})
+        self._raise_for_status(r)
+        return _parse_lease(r.json())

pharox_sdk-0.2.0/src/pharox_sdk/exceptions.py

@@ -0,0 +1,11 @@
+class SDKError(Exception):
+    """Base error for pharox-sdk."""
+
+
+class RemoteError(SDKError):
+    """Raised when the pharox-service returns an unexpected HTTP error."""
+
+    def __init__(self, status_code: int, detail: str) -> None:
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"HTTP {status_code}: {detail}")

pharox_sdk-0.2.0/src/pharox_sdk/sdk.py

@@ -0,0 +1,241 @@
+"""Unified dual-mode PharoxSDK — remote (HTTP) or local (direct toolkit)."""
+from contextlib import asynccontextmanager
+from typing import AsyncIterator, Optional
+
+from pharox import (
+    IAsyncStorage,
+    Lease,
+    ProxyFilters,
+    ProxyPool,
+    SelectorStrategy,
+)
+
+from .client import PharoxClient
+from .exceptions import RemoteError
+
+
+class PharoxSDK:
+    """
+    Dual-mode SDK that mirrors the async ProxyManager semantics.
+
+    Use the class methods to create an instance:
+
+    .. code-block:: python
+
+        # Remote mode — talks to a running pharox-service
+        sdk = PharoxSDK.remote("http://localhost:8000", api_key="secret")
+
+        # Local mode — uses an IAsyncStorage directly (no HTTP overhead)
+        sdk = PharoxSDK.local(storage)
+
+    Both modes expose the same interface:
+    ``acquire_proxy``, ``release_proxy``, ``with_lease``.
+    """
+
+    def __init__(
+        self,
+        *,
+        client: Optional[PharoxClient] = None,
+        storage: Optional[IAsyncStorage] = None,
+    ) -> None:
+        if (client is None) == (storage is None):
+            raise ValueError(
+                "Provide exactly one of client= (remote) or storage= (local)."
+            )
+        self._client = client
+        self._storage = storage
+        # name → id cache used only in remote mode
+        self._pool_cache: dict[str, str] = {}
+
+    # ------------------------------------------------------------------
+    # Constructors
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def remote(
+        cls, base_url: str, api_key: str, timeout: float = 30.0
+    ) -> "PharoxSDK":
+        """Create an SDK instance that calls a remote pharox-service."""
+        return cls(client=PharoxClient(base_url, api_key, timeout=timeout))
+
+    @classmethod
+    def local(cls, storage: IAsyncStorage) -> "PharoxSDK":
+        """Create an SDK instance that uses a local storage backend directly."""
+        return cls(storage=storage)
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def aclose(self) -> None:
+        if self._client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> "PharoxSDK":
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+    # ------------------------------------------------------------------
+    # Pool helpers (remote mode)
+    # ------------------------------------------------------------------
+
+    async def _resolve_pool_id(self, pool_name: str) -> Optional[str]:
+        """Look up pool_id by name, using a local name cache."""
+        if pool_name in self._pool_cache:
+            return self._pool_cache[pool_name]
+        if self._client is None:  # pragma: no cover
+            raise RuntimeError("_resolve_pool_id called in local mode")
+        pools = await self._client.list_pools()
+        self._pool_cache = {p.name: str(p.id) for p in pools}
+        return self._pool_cache.get(pool_name)
+
+    # ------------------------------------------------------------------
+    # Public API — mirrors ProxyManager async semantics
+    # ------------------------------------------------------------------
+
+    async def acquire_proxy(
+        self,
+        pool_name: str,
+        consumer_id: str = "default",
+        ttl_seconds: int = 300,
+        filters: Optional[ProxyFilters] = None,
+        selector: Optional[SelectorStrategy] = None,
+    ) -> Optional[Lease]:
+        """
+        Acquire a proxy lease from the named pool.
+
+        Returns the Lease on success, or None if no proxy is available.
+        """
+        if self._client is not None:
+            return await self._acquire_remote(
+                pool_name, consumer_id, ttl_seconds, filters, selector
+            )
+        return await self._acquire_local(
+            pool_name, consumer_id, ttl_seconds, filters, selector
+        )
+
+    async def release_proxy(self, lease: Lease) -> None:
+        """Release a previously acquired lease."""
+        if self._client is not None:
+            await self._client.release_lease(str(lease.id))
+        elif self._storage is not None:
+            await self._storage.release_lease(lease)
+        else:  # pragma: no cover
+            raise RuntimeError("SDK has neither client nor storage")
+
+    @asynccontextmanager
+    async def with_lease(
+        self,
+        pool_name: str,
+        consumer_id: str = "default",
+        ttl_seconds: int = 300,
+        filters: Optional[ProxyFilters] = None,
+        selector: Optional[SelectorStrategy] = None,
+    ) -> AsyncIterator[Optional[Lease]]:
+        """
+        Async context manager that acquires a lease and releases it on exit.
+
+        .. code-block:: python
+
+            async with sdk.with_lease("my-pool") as lease:
+                if lease:
+                    print(lease.proxy_id)
+        """
+        lease = await self.acquire_proxy(
+            pool_name,
+            consumer_id=consumer_id,
+            ttl_seconds=ttl_seconds,
+            filters=filters,
+            selector=selector,
+        )
+        try:
+            yield lease
+        finally:
+            if lease is not None:
+                await self.release_proxy(lease)
+
+    # ------------------------------------------------------------------
+    # Admin helpers (remote mode only)
+    # ------------------------------------------------------------------
+
+    async def create_pool(
+        self, name: str, description: str = ""
+    ) -> ProxyPool:
+        """Create a pool in the remote service."""
+        self._require_remote()
+        assert self._client is not None
+        pool = await self._client.create_pool(name, description)
+        self._pool_cache[pool.name] = str(pool.id)
+        return pool
+
+    async def list_pools(self) -> list[ProxyPool]:
+        """List all pools from the remote service."""
+        self._require_remote()
+        assert self._client is not None
+        pools = await self._client.list_pools()
+        self._pool_cache = {p.name: str(p.id) for p in pools}
+        return pools
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _require_remote(self) -> None:
+        if self._client is None:
+            raise RuntimeError(
+                "This method is only available in remote mode."
+            )
+
+    async def _acquire_remote(
+        self,
+        pool_name: str,
+        consumer_id: str,
+        ttl_seconds: int,
+        filters: Optional[ProxyFilters],
+        selector: Optional[SelectorStrategy],
+    ) -> Optional[Lease]:
+        if self._client is None:  # pragma: no cover
+            raise RuntimeError("_acquire_remote called in local mode")
+        pool_id = await self._resolve_pool_id(pool_name)
+        if pool_id is None:
+            from pharox import PoolNotFoundError
+            raise PoolNotFoundError(pool_name)
+        try:
+            return await self._client.acquire_lease(
+                pool_id=pool_id,
+                consumer_id=consumer_id,
+                ttl_seconds=ttl_seconds,
+                filters=filters,
+                selector=selector,
+            )
+        except RemoteError as exc:
+            if exc.status_code == 404:
+                # Pool was in cache but no longer exists — evict and raise
+                self._pool_cache.pop(pool_name, None)
+                from pharox import PoolNotFoundError
+                raise PoolNotFoundError(pool_name) from exc
+            raise
+
+    async def _acquire_local(
+        self,
+        pool_name: str,
+        consumer_id: str,
+        ttl_seconds: int,
+        filters: Optional[ProxyFilters],
+        selector: Optional[SelectorStrategy],
+    ) -> Optional[Lease]:
+        if self._storage is None:  # pragma: no cover
+            raise RuntimeError("_acquire_local called in remote mode")
+        await self._storage.ensure_consumer(consumer_id)
+        await self._storage.cleanup_expired_leases()
+        strategy = selector or SelectorStrategy.FIRST_AVAILABLE
+        proxy = await self._storage.find_available_proxy(
+            pool_name, filters, strategy
+        )
+        if proxy is None:
+            return None
+        return await self._storage.create_lease(
+            proxy, consumer_id, ttl_seconds
+        )