xyz17711-proxy-pool 0.1.0__tar.gz

xyz17711_proxy_pool-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+# This is the public repo's OWN .gitignore -- clients/ in the internal monorepo is an
+# exact 1:1 mirror of github.com/17711-services/clients, so this file ships as-is to that
+# repo's own root and applies there too (a contributor cloning the public repo and running the
+# tests below needs this same coverage). Never add anything internal-only here -- that belongs in
+# the platform monorepo's own root .gitignore instead.
+
+python/packages/*/src/**/__pycache__/
+python/packages/*/tests/**/__pycache__/
+python/**/.pytest_cache/
+python/**/*.egg-info/
+python/.venv/
+python/.venv-sync/
+python/packages/*/dist/
+
+node/node_modules/
+node/packages/*/node_modules/
+node/packages/*/dist/
+node/packages/*/*.tsbuildinfo

xyz17711_proxy_pool-0.1.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.5
+Name: xyz17711-proxy-pool
+Version: 0.1.0
+Summary: Generated typed client for the proxy-pool 17711.xyz microservice.
+License: MIT
+Requires-Python: >=3.9
+Requires-Dist: xyz17711>=0.1.0
+Provides-Extra: langchain
+Requires-Dist: langchain-core<2.0,>=1.2; extra == 'langchain'
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# xyz17711-proxy-pool
+
+[![Publish](https://github.com/17711-services/clients/actions/workflows/publish-python.yml/badge.svg)](https://github.com/17711-services/clients/actions/workflows/publish-python.yml)
+[![PyPI](https://img.shields.io/pypi/v/xyz17711-proxy-pool)](https://pypi.org/project/xyz17711-proxy-pool/)
+[![Python versions](https://img.shields.io/pypi/pyversions/xyz17711-proxy-pool)](https://pypi.org/project/xyz17711-proxy-pool/)
+[![License](https://img.shields.io/pypi/l/xyz17711-proxy-pool)](https://github.com/17711-services/clients/blob/main/LICENSE)
+
+Typed Python client for **proxy-pool**, part of the
+[17711.xyz](https://api.17711.xyz) microservice fleet -- pay-per-call APIs settled in USDC via
+[x402](https://x402.org), listed on [x402scan](https://www.x402scan.com/server/f1c7b972-3405-4b75-8b4f-d1bfbd6305ff). See the
+[Python family README](https://github.com/17711-services/clients/blob/main/python/README.md)
+for the full guide (payment configuration, LangChain integration, logging, error handling) -- this
+page only covers what's specific to this one package.
+
+## Install
+
+```bash
+pip install "xyz17711[proxy-pool]"
+```
+
+## Methods
+
+| Method | Description |
+| --- | --- |
+| `get_best_proxy` | Returns one of the fastest verified-alive proxies matching the filter, randomized to spread load ($0.001, x402) |
+
+Every method above has both a sync form and an async form (the `a`-prefixed sibling, e.g.
+`aget_best_proxy` next to `get_best_proxy`), sharing one underlying client.
+
+## Quickstart
+
+```python
+from xyz17711_proxy_pool import Client
+
+client = Client("https://api.17711.xyz/registry/proxy-pool")
+# see the Methods table above for every available call and its request/response model
+```
+
+## LangChain
+
+```bash
+pip install "xyz17711-proxy-pool[langchain]"
+```
+
+```python
+from xyz17711_proxy_pool import Client
+from xyz17711_proxy_pool.langchain_tools import ProxyPoolToolkit
+
+client = Client("https://api.17711.xyz/registry/proxy-pool")
+tools = ProxyPoolToolkit(client=client).get_tools()
+```
+
+## License
+
+MIT -- see the repository's own `LICENSE`.

xyz17711_proxy_pool-0.1.0/README.md

@@ -0,0 +1,55 @@
+# xyz17711-proxy-pool
+
+[![Publish](https://github.com/17711-services/clients/actions/workflows/publish-python.yml/badge.svg)](https://github.com/17711-services/clients/actions/workflows/publish-python.yml)
+[![PyPI](https://img.shields.io/pypi/v/xyz17711-proxy-pool)](https://pypi.org/project/xyz17711-proxy-pool/)
+[![Python versions](https://img.shields.io/pypi/pyversions/xyz17711-proxy-pool)](https://pypi.org/project/xyz17711-proxy-pool/)
+[![License](https://img.shields.io/pypi/l/xyz17711-proxy-pool)](https://github.com/17711-services/clients/blob/main/LICENSE)
+
+Typed Python client for **proxy-pool**, part of the
+[17711.xyz](https://api.17711.xyz) microservice fleet -- pay-per-call APIs settled in USDC via
+[x402](https://x402.org), listed on [x402scan](https://www.x402scan.com/server/f1c7b972-3405-4b75-8b4f-d1bfbd6305ff). See the
+[Python family README](https://github.com/17711-services/clients/blob/main/python/README.md)
+for the full guide (payment configuration, LangChain integration, logging, error handling) -- this
+page only covers what's specific to this one package.
+
+## Install
+
+```bash
+pip install "xyz17711[proxy-pool]"
+```
+
+## Methods
+
+| Method | Description |
+| --- | --- |
+| `get_best_proxy` | Returns one of the fastest verified-alive proxies matching the filter, randomized to spread load ($0.001, x402) |
+
+Every method above has both a sync form and an async form (the `a`-prefixed sibling, e.g.
+`aget_best_proxy` next to `get_best_proxy`), sharing one underlying client.
+
+## Quickstart
+
+```python
+from xyz17711_proxy_pool import Client
+
+client = Client("https://api.17711.xyz/registry/proxy-pool")
+# see the Methods table above for every available call and its request/response model
+```
+
+## LangChain
+
+```bash
+pip install "xyz17711-proxy-pool[langchain]"
+```
+
+```python
+from xyz17711_proxy_pool import Client
+from xyz17711_proxy_pool.langchain_tools import ProxyPoolToolkit
+
+client = Client("https://api.17711.xyz/registry/proxy-pool")
+tools = ProxyPoolToolkit(client=client).get_tools()
+```
+
+## License
+
+MIT -- see the repository's own `LICENSE`.

xyz17711_proxy_pool-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "xyz17711-proxy-pool"
+version = "0.1.0"
+description = "Generated typed client for the proxy-pool 17711.xyz microservice."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+dependencies = ["xyz17711>=0.1.0"]
+
+# Only needed to import `langchain_tools` (never the base `client`/`models` modules) -- see that
+# module's own doc comment for why it's an extra, never a hard dependency.
+[project.optional-dependencies]
+langchain = ["langchain-core>=1.2,<2.0"]
+test = ["pytest>=8"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/xyz17711_proxy_pool"]

xyz17711_proxy_pool-0.1.0/src/xyz17711_proxy_pool/__init__.py

@@ -0,0 +1,4 @@
+from .client import Client
+from .models import *  # noqa: F401,F403
+
+__all__ = ["Client"]

xyz17711_proxy_pool-0.1.0/src/xyz17711_proxy_pool/client.py

@@ -0,0 +1,26 @@
+"""Typed HTTP client for proxy-pool -- one method per operation, each with a sync form and an async (`a`-prefixed) form."""
+
+from __future__ import annotations
+
+import logging
+
+from xyz17711_core import Client as _BaseClient
+
+from .models import *  # noqa: F401,F403 -- re-exported for callers building requests
+
+logger = logging.getLogger(__name__)
+
+
+class Client(_BaseClient):
+    """Typed client for proxy-pool. Every method has a sync form and an async form (the `a`-prefixed sibling, e.g. `aget_best_proxy` next to `get_best_proxy`) sharing the same underlying connection/wallet -- pick whichever fits your own code."""
+
+    def get_best_proxy(self, anonymity: Optional[str] = None, city: Optional[str] = None, country: Optional[str] = None, protocol: Optional[str] = None) -> GetBestProxyResponse:
+        """Returns one of the fastest verified-alive proxies matching the filter, randomized to spread load ($0.001, x402)"""
+        logger.debug("get_best_proxy: calling %s", "/v1/proxy-pool/get_best_proxy")
+        return GetBestProxyResponse.model_validate(self._get("/v1/proxy-pool/get_best_proxy", {"anonymity": anonymity, "city": city, "country": country, "protocol": protocol}))
+
+    async def aget_best_proxy(self, anonymity: Optional[str] = None, city: Optional[str] = None, country: Optional[str] = None, protocol: Optional[str] = None) -> GetBestProxyResponse:
+        """Returns one of the fastest verified-alive proxies matching the filter, randomized to spread load ($0.001, x402) (async)"""
+        logger.debug("aget_best_proxy: calling %s", "/v1/proxy-pool/get_best_proxy")
+        return GetBestProxyResponse.model_validate(await self._aget("/v1/proxy-pool/get_best_proxy", {"anonymity": anonymity, "city": city, "country": country, "protocol": protocol}))
+

xyz17711_proxy_pool-0.1.0/src/xyz17711_proxy_pool/langchain_tools.py

@@ -0,0 +1,39 @@
+"""LangChain `StructuredTool`s for proxy-pool, grouped in one `BaseToolkit` -- one tool per operation, each with both a sync and an async implementation. Requires the `langchain` extra: pip install "xyz17711-proxy-pool[langchain]"."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, List, Optional
+
+from langchain_core.tools import BaseTool, BaseToolkit, StructuredTool
+
+from .client import Client
+from .models import *  # noqa: F401,F403 -- request models reused as tool args_schema
+
+logger = logging.getLogger(__name__)
+
+
+class ProxyPoolToolkit(BaseToolkit):
+    """LangChain toolkit for proxy-pool -- one StructuredTool per operation, reusing this package's own generated client and request models directly. Each tool carries both a sync and an async (`coroutine=`) implementation, so `.invoke()` and `.ainvoke()` both work."""
+
+    client: Client
+    model_config = {"arbitrary_types_allowed": True}
+
+    def get_tools(self) -> List[BaseTool]:
+        logger.debug("ProxyPoolToolkit.get_tools: building 1 tool(s)")
+        def _get_best_proxy(anonymity: Optional[str] = None, city: Optional[str] = None, country: Optional[str] = None, protocol: Optional[str] = None) -> Any:
+            logger.debug("ProxyPoolToolkit.get_tools: calling get_best_proxy")
+            return self.client.get_best_proxy(anonymity=anonymity, city=city, country=country, protocol=protocol).model_dump()
+
+        async def _aget_best_proxy(anonymity: Optional[str] = None, city: Optional[str] = None, country: Optional[str] = None, protocol: Optional[str] = None) -> Any:
+            logger.debug("ProxyPoolToolkit.get_tools: calling get_best_proxy (async)")
+            return (await self.client.aget_best_proxy(anonymity=anonymity, city=city, country=country, protocol=protocol)).model_dump()
+
+        return [
+            StructuredTool.from_function(
+                func=_get_best_proxy,
+                coroutine=_aget_best_proxy,
+                name="get_best_proxy",
+                description="Returns one of the fastest verified-alive proxies matching the filter, randomized to spread load ($0.001, x402)",
+            ),
+        ]

xyz17711_proxy_pool-0.1.0/src/xyz17711_proxy_pool/models.py

@@ -0,0 +1,38 @@
+"""Pydantic request/response models for proxy-pool."""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+from pydantic import BaseModel
+
+
+class ProxyView(BaseModel):
+    """A `SourceProxy` joined with its `CheckedProxy` result, if it has been checked at least once -- what every read tool actually filters/returns."""
+    anonymity: str
+    checked_alive: Optional[bool] = None  # `None` if this service has never checked this proxy yet.
+    checked_at: Optional[int] = None
+    checked_consecutive_successes: int  # See `CheckedProxy::consecutive_successes`'s own doc comment. `0` if never checked.
+    checked_ema_latency_ms: Optional[float] = None  # See `CheckedProxy::ema_latency_ms`'s own doc comment.
+    checked_latency_ms: Optional[int] = None
+    checked_protocol: Optional[str] = None
+    city: str
+    country: str
+    id: str
+    ip: str
+    port: int
+    protocols: List[str]
+
+    @classmethod
+    def _dummy(cls) -> "ProxyView":
+        """A minimal, always-constructible instance -- test fixtures only, never real data."""
+        return cls(anonymity="test", checked_alive=None, checked_at=None, checked_consecutive_successes=0, checked_ema_latency_ms=None, checked_latency_ms=None, checked_protocol=None, city="test", country="test", id="test", ip="test", port=0, protocols=[])
+
+
+class GetBestProxyResponse(BaseModel):
+    proxy: ProxyView
+
+    @classmethod
+    def _dummy(cls) -> "GetBestProxyResponse":
+        """A minimal, always-constructible instance -- test fixtures only, never real data."""
+        return cls(proxy=ProxyView._dummy())

xyz17711_proxy_pool-0.1.0/tests/test_client.py

@@ -0,0 +1,45 @@
+"""Verifies every proxy-pool client method (sync and async) sends a request to the expected path/HTTP verb and parses a well-formed response into the expected type."""
+
+from __future__ import annotations
+
+import asyncio
+
+import httpx
+
+from xyz17711_proxy_pool import Client
+from xyz17711_proxy_pool.models import *  # noqa: F401,F403
+
+
+def _mock_client(handler) -> Client:
+    """A Client wired to a fake transport for BOTH its sync and async HTTP clients -- no real network call ever happens in this test module. Found live: the async client is normally constructed LAZILY on first async use, so a test that only mocks `_http` (sync) silently lets an async test make a REAL network call instead of using the mock."""
+    client = Client("https://example.test")
+    client._http = httpx.Client(base_url="https://example.test", transport=httpx.MockTransport(handler))
+    client._ahttp = httpx.AsyncClient(base_url="https://example.test", transport=httpx.MockTransport(handler))
+    return client
+
+
+def test_get_best_proxy_calls_the_expected_path():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.method == "GET"
+        assert request.url.path == "/v1/proxy-pool/get_best_proxy"
+        return httpx.Response(200, json=GetBestProxyResponse._dummy().model_dump(mode='json'))
+
+    client = _mock_client(handler)
+    result = client.get_best_proxy(anonymity=None, city=None, country=None, protocol=None)
+    assert isinstance(result, GetBestProxyResponse)
+
+
+def test_aget_best_proxy_calls_the_expected_path():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.method == "GET"
+        assert request.url.path == "/v1/proxy-pool/get_best_proxy"
+        return httpx.Response(200, json=GetBestProxyResponse._dummy().model_dump(mode='json'))
+
+    client = _mock_client(handler)
+
+    async def run():
+        return await client.aget_best_proxy(anonymity=None, city=None, country=None, protocol=None)
+
+    result = asyncio.run(run())
+    assert isinstance(result, GetBestProxyResponse)
+

xyz17711_proxy_pool-0.1.0/tests/test_langchain_tools.py

@@ -0,0 +1,43 @@
+"""Verifies every proxy-pool LangChain tool through the real StructuredTool (both `.invoke()` and `.ainvoke()`), not just the underlying client method -- catches schema-shape bugs a plain client-method test would miss. Requires the `langchain` extra."""
+
+from __future__ import annotations
+
+import asyncio
+
+import httpx
+
+from xyz17711_proxy_pool import Client
+from xyz17711_proxy_pool.langchain_tools import ProxyPoolToolkit
+from xyz17711_proxy_pool.models import *  # noqa: F401,F403
+
+
+def _mock_client(handler) -> Client:
+    client = Client("https://example.test")
+    client._http = httpx.Client(base_url="https://example.test", transport=httpx.MockTransport(handler))
+    client._ahttp = httpx.AsyncClient(base_url="https://example.test", transport=httpx.MockTransport(handler))
+    return client
+
+
+def test_get_best_proxy_tool_invoke():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, json=GetBestProxyResponse._dummy().model_dump(mode='json'))
+
+    toolkit = ProxyPoolToolkit(client=_mock_client(handler))
+    tool = next(t for t in toolkit.get_tools() if t.name == "get_best_proxy")
+    result = tool.invoke({"anonymity": None, "city": None, "country": None, "protocol": None})
+    assert result is not None
+
+
+def test_get_best_proxy_tool_ainvoke():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, json=GetBestProxyResponse._dummy().model_dump(mode='json'))
+
+    toolkit = ProxyPoolToolkit(client=_mock_client(handler))
+    tool = next(t for t in toolkit.get_tools() if t.name == "get_best_proxy")
+
+    async def run():
+        return await tool.ainvoke({"anonymity": None, "city": None, "country": None, "protocol": None})
+
+    result = asyncio.run(run())
+    assert result is not None
+