asockslib 0.1.0__tar.gz

asockslib-0.1.0/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: asockslib
+Version: 0.1.0
+Summary: Premium Python library and CLI for the ASocks Proxy API
+Keywords: proxy,asocks,socks5,http-proxy,rotating-proxy
+Author: bot4ka
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: Proxy Servers
+Classifier: Typing :: Typed
+Requires-Dist: beartype>=0.22.9
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: questionary>=2.1.1
+Requires-Dist: rich>=14.3.3
+Requires-Dist: socksio>=1.0.0
+Requires-Dist: tenacity>=9.1.4
+Requires-Dist: typer>=0.24.1
+Requires-Python: >=3.12
+Project-URL: Documentation, https://bot4ka.github.io/asockslib
+Project-URL: Homepage, https://github.com/bot4ka/asockslib
+Project-URL: Issues, https://github.com/bot4ka/asockslib/issues
+Project-URL: Repository, https://github.com/bot4ka/asockslib
+Description-Content-Type: text/markdown
+
+# ASocksLib
+
+Premium Python library and CLI for the [ASocks Proxy API](https://docs.asocks.com/en/).
+
+[![CI](https://github.com/bot4ka/asockslib/actions/workflows/ci.yml/badge.svg)](https://github.com/bot4ka/asockslib/actions/workflows/ci.yml)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+---
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **One-liner API** | Get working proxies in a single function call |
+| **Async Client** | Fully typed `httpx` client, Pydantic models, configurable retry/back-off on 429/5xx/network, typed errors |
+| **Smart Proxy** | Health checking, auto-rotation, and self-healing proxy manager |
+| **Proxy Pool** | Zero-traffic pool for 100,000+ accounts — detects dead proxies via API, sticky per-account mapping, pluggable persistence, optional ping-ranked selection |
+| **CLI** | Interactive wizard, bulk generation, clipboard auto-copy |
+| **18 Templates** | Built-in output formats for AdsPower, Dolphin Anty, GoLogin, etc. |
+| **Export** | `.txt`, `.json`, `.csv` |
+| **Type Safe** | Strict `mypy` + `pyright` + `beartype` runtime checks |
+
+## Installation
+
+```bash
+pip install asockslib
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add asockslib
+```
+
+## Quick Start
+
+Set your API key:
+
+```bash
+export ASOCKS_API_KEY="sk-your-api-key"
+```
+
+### One-liner
+
+```python
+import asyncio
+from asockslib import get_proxies
+
+urls = asyncio.run(get_proxies("US", count=10))
+# → ["socks5://user:pass@host:port", ...]
+```
+
+### Full API Client
+
+```python
+import asyncio
+from asockslib import ASocksClient, CreatePortRequest
+
+async def main():
+    async with ASocksClient(api_key="sk-...") as client:
+        balance = await client.get_balance()
+        print(f"Balance: ${balance.balance:.2f}")
+
+        ports = await client.create_ports(
+            CreatePortRequest(country_code="US", count=5)
+        )
+        for p in ports:
+            print(p.proxy_url)
+
+asyncio.run(main())
+```
+
+### Smart Proxy (auto-rotation)
+
+```python
+from asockslib import ASocksClient, SmartProxy
+
+async with ASocksClient(api_key="sk-...") as client:
+    smart = SmartProxy(client, country_code="US")
+    await smart.initialize(pool_size=5)
+
+    proxy = await smart.get_proxy()  # auto-heals on failure
+```
+
+### Proxy Pool (100,000+ accounts)
+
+```python
+from asockslib import ASocksClient, ProxyPool, PoolStrategy
+
+async with ASocksClient(api_key="sk-...") as client:
+    pool = ProxyPool(
+        client,
+        country_code="US",
+        city="New York",              # geo-targeting: country + city
+        pool_size=100,
+        strategy=PoolStrategy.STICKY, # each account pinned to its own proxy
+    )
+    await pool.initialize()
+
+    url = await pool.get_proxy("account_42")  # sticky assignment
+    # On failure — auto-replaces via API (zero traffic waste)
+    await pool.report_failure("account_42")
+    url = await pool.get_proxy("account_42")  # new same-geo proxy!
+
+    await pool.shutdown()
+```
+
+**Persistence across restarts** — supply a `ProxyStore` so `account_id → port_id`
+bindings survive a process restart (mapping is otherwise in-memory only):
+
+```python
+class RedisStore:  # implement against Redis / SQL / file — your backend
+    async def load(self) -> dict[str, int]: ...
+    async def save(self, account_id: str, port_id: int) -> None: ...
+    async def delete(self, account_id: str) -> None: ...
+
+pool = ProxyPool(client, country_code="US", pool_size=100, store=RedisStore())
+await pool.initialize()  # restores bindings from the store
+```
+
+**Ping-ranked selection** — over-provision, benchmark, keep the fastest
+(default off = zero-traffic startup):
+
+```python
+pool = ProxyPool(
+    client, country_code="US", pool_size=100,
+    benchmark_on_init=True, benchmark_oversample=2.0,  # test 200, keep fastest 100
+)
+```
+
+### Reliability & errors
+
+The client retries **429, 5xx and transient network errors** with configurable
+exponential back-off. Non-idempotent `POST` (create-port) is retried only on 429,
+so a timeout can never silently double-create paid ports.
+
+```python
+from asockslib import ASocksClient, APIConnectionError, RateLimitError, ASocksError
+
+client = ASocksClient(
+    api_key="sk-...",
+    max_retries=5,          # attempts per request
+    retry_backoff_base=1.0, # attempt n waits base * 2**(n-1), capped at max
+    retry_backoff_max=30.0,
+)
+
+try:
+    await client.get_balance()
+except APIConnectionError as e:   # network unreachable after all retries
+    ...
+except RateLimitError as e:       # 429 after all retries
+    ...
+except ASocksError as e:          # any library error — has .status_code / .message
+    ...
+```
+
+## CLI
+
+```bash
+# Interactive wizard
+asocks wizard
+
+# Quick proxy generation
+asocks get US -n 10
+
+# Custom template + export
+asocks get US -n 50 -f json -o proxies.json
+
+# Account management
+asocks balance
+asocks list
+asocks info 12345
+asocks delete 12345
+
+# Raw API
+asocks api countries
+asocks api generate 5 --country DE
+asocks api whitelist-add 203.0.113.42
+```
+
+## Documentation
+
+Full docs: **[bot4ka.github.io/asockslib](https://bot4ka.github.io/asockslib)**
+
+## Development
+
+```bash
+uv sync                          # install dependencies
+uv run pytest                    # run tests
+uv run pyright                   # type checking
+uv run ruff check .              # linting
+uv run python generate_docs.py   # generate docs
+cd docs && npm run dev           # start docs dev server
+```
+
+## License
+
+MIT

asockslib-0.1.0/README.md

@@ -0,0 +1,199 @@
+# ASocksLib
+
+Premium Python library and CLI for the [ASocks Proxy API](https://docs.asocks.com/en/).
+
+[![CI](https://github.com/bot4ka/asockslib/actions/workflows/ci.yml/badge.svg)](https://github.com/bot4ka/asockslib/actions/workflows/ci.yml)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+---
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **One-liner API** | Get working proxies in a single function call |
+| **Async Client** | Fully typed `httpx` client, Pydantic models, configurable retry/back-off on 429/5xx/network, typed errors |
+| **Smart Proxy** | Health checking, auto-rotation, and self-healing proxy manager |
+| **Proxy Pool** | Zero-traffic pool for 100,000+ accounts — detects dead proxies via API, sticky per-account mapping, pluggable persistence, optional ping-ranked selection |
+| **CLI** | Interactive wizard, bulk generation, clipboard auto-copy |
+| **18 Templates** | Built-in output formats for AdsPower, Dolphin Anty, GoLogin, etc. |
+| **Export** | `.txt`, `.json`, `.csv` |
+| **Type Safe** | Strict `mypy` + `pyright` + `beartype` runtime checks |
+
+## Installation
+
+```bash
+pip install asockslib
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add asockslib
+```
+
+## Quick Start
+
+Set your API key:
+
+```bash
+export ASOCKS_API_KEY="sk-your-api-key"
+```
+
+### One-liner
+
+```python
+import asyncio
+from asockslib import get_proxies
+
+urls = asyncio.run(get_proxies("US", count=10))
+# → ["socks5://user:pass@host:port", ...]
+```
+
+### Full API Client
+
+```python
+import asyncio
+from asockslib import ASocksClient, CreatePortRequest
+
+async def main():
+    async with ASocksClient(api_key="sk-...") as client:
+        balance = await client.get_balance()
+        print(f"Balance: ${balance.balance:.2f}")
+
+        ports = await client.create_ports(
+            CreatePortRequest(country_code="US", count=5)
+        )
+        for p in ports:
+            print(p.proxy_url)
+
+asyncio.run(main())
+```
+
+### Smart Proxy (auto-rotation)
+
+```python
+from asockslib import ASocksClient, SmartProxy
+
+async with ASocksClient(api_key="sk-...") as client:
+    smart = SmartProxy(client, country_code="US")
+    await smart.initialize(pool_size=5)
+
+    proxy = await smart.get_proxy()  # auto-heals on failure
+```
+
+### Proxy Pool (100,000+ accounts)
+
+```python
+from asockslib import ASocksClient, ProxyPool, PoolStrategy
+
+async with ASocksClient(api_key="sk-...") as client:
+    pool = ProxyPool(
+        client,
+        country_code="US",
+        city="New York",              # geo-targeting: country + city
+        pool_size=100,
+        strategy=PoolStrategy.STICKY, # each account pinned to its own proxy
+    )
+    await pool.initialize()
+
+    url = await pool.get_proxy("account_42")  # sticky assignment
+    # On failure — auto-replaces via API (zero traffic waste)
+    await pool.report_failure("account_42")
+    url = await pool.get_proxy("account_42")  # new same-geo proxy!
+
+    await pool.shutdown()
+```
+
+**Persistence across restarts** — supply a `ProxyStore` so `account_id → port_id`
+bindings survive a process restart (mapping is otherwise in-memory only):
+
+```python
+class RedisStore:  # implement against Redis / SQL / file — your backend
+    async def load(self) -> dict[str, int]: ...
+    async def save(self, account_id: str, port_id: int) -> None: ...
+    async def delete(self, account_id: str) -> None: ...
+
+pool = ProxyPool(client, country_code="US", pool_size=100, store=RedisStore())
+await pool.initialize()  # restores bindings from the store
+```
+
+**Ping-ranked selection** — over-provision, benchmark, keep the fastest
+(default off = zero-traffic startup):
+
+```python
+pool = ProxyPool(
+    client, country_code="US", pool_size=100,
+    benchmark_on_init=True, benchmark_oversample=2.0,  # test 200, keep fastest 100
+)
+```
+
+### Reliability & errors
+
+The client retries **429, 5xx and transient network errors** with configurable
+exponential back-off. Non-idempotent `POST` (create-port) is retried only on 429,
+so a timeout can never silently double-create paid ports.
+
+```python
+from asockslib import ASocksClient, APIConnectionError, RateLimitError, ASocksError
+
+client = ASocksClient(
+    api_key="sk-...",
+    max_retries=5,          # attempts per request
+    retry_backoff_base=1.0, # attempt n waits base * 2**(n-1), capped at max
+    retry_backoff_max=30.0,
+)
+
+try:
+    await client.get_balance()
+except APIConnectionError as e:   # network unreachable after all retries
+    ...
+except RateLimitError as e:       # 429 after all retries
+    ...
+except ASocksError as e:          # any library error — has .status_code / .message
+    ...
+```
+
+## CLI
+
+```bash
+# Interactive wizard
+asocks wizard
+
+# Quick proxy generation
+asocks get US -n 10
+
+# Custom template + export
+asocks get US -n 50 -f json -o proxies.json
+
+# Account management
+asocks balance
+asocks list
+asocks info 12345
+asocks delete 12345
+
+# Raw API
+asocks api countries
+asocks api generate 5 --country DE
+asocks api whitelist-add 203.0.113.42
+```
+
+## Documentation
+
+Full docs: **[bot4ka.github.io/asockslib](https://bot4ka.github.io/asockslib)**
+
+## Development
+
+```bash
+uv sync                          # install dependencies
+uv run pytest                    # run tests
+uv run pyright                   # type checking
+uv run ruff check .              # linting
+uv run python generate_docs.py   # generate docs
+cd docs && npm run dev           # start docs dev server
+```
+
+## License
+
+MIT

asockslib-0.1.0/pyproject.toml

@@ -0,0 +1,92 @@
+[project]
+name = "asockslib"
+version = "0.1.0"
+description = "Premium Python library and CLI for the ASocks Proxy API"
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "bot4ka" }]
+requires-python = ">=3.12"
+keywords = ["proxy", "asocks", "socks5", "http-proxy", "rotating-proxy"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: Proxy Servers",
+    "Typing :: Typed",
+]
+dependencies = [
+    "beartype>=0.22.9",
+    "httpx>=0.28.1",
+    "pydantic>=2.12.5",
+    "questionary>=2.1.1",
+    "rich>=14.3.3",
+    "socksio>=1.0.0",
+    "tenacity>=9.1.4",
+    "typer>=0.24.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/bot4ka/asockslib"
+Documentation = "https://bot4ka.github.io/asockslib"
+Repository = "https://github.com/bot4ka/asockslib"
+Issues = "https://github.com/bot4ka/asockslib/issues"
+
+[project.scripts]
+asocks = "asockslib.cli:app"
+
+[build-system]
+requires = ["uv_build>=0.8.4,<0.9.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.19.1",
+    "pyright>=1.1.408",
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+    "pytest-httpx>=0.36.0",
+    "ruff>=0.15.4",
+]
+
+[tool.mypy]
+strict = true
+python_version = "3.12"
+
+[tool.pyright]
+typeCheckingMode = "strict"
+pythonVersion = "3.12"
+
+[[tool.pyright.executionEnvironments]]
+# White-box unit tests deliberately reach into private attributes/methods
+# (_slots, _is_healthy, _fetch_matching_ports, ...) to test internal state
+# directly — that is the intended test design, not a leak of encapsulation.
+root = "tests"
+reportPrivateUsage = false
+
+[[tool.pyright.executionEnvironments]]
+# Typer registers these functions as CLI commands via the `@app.command()`
+# decorator at runtime; pyright's static analysis doesn't see that use and
+# flags every command as dead code.
+root = "src/asockslib/cli"
+reportUnusedFunction = false
+
+[[tool.pyright.executionEnvironments]]
+root = "."
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "ANN", "B", "SIM", "TCH"]
+
+[tool.ruff.lint.per-file-ignores]
+# Embedded Markdown/MDX template strings (prose, tables) — wrapping mid-content
+# would corrupt rendered docs; the 100-col limit doesn't apply to prose.
+"generate_docs.py" = ["E501"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

asockslib-0.1.0/src/asockslib/__init__.py

@@ -0,0 +1,117 @@
+"""ASocksLib — Python library and CLI for the ASocks Proxy API."""
+
+from __future__ import annotations
+
+from asockslib.benchmark import (
+    CountryPingResult,
+    FindBestResult,
+    ProxyBenchmarkResult,
+    benchmark_proxies,
+    find_best_proxies,
+    ping_proxy,
+    select_best_proxies,
+)
+from asockslib.client import ASocksClient
+from asockslib.exceptions import (
+    APIConnectionError,
+    ASocksError,
+    AuthenticationError,
+    InsufficientBalanceError,
+    NoAvailableProxyError,
+    PortNotFoundError,
+    ProxyHealthError,
+    RateLimitError,
+)
+from asockslib.geo_picker import (
+    GeoPicker,
+    PickedASN,
+    PickedCity,
+    PickedConnectionType,
+    PickedCountry,
+    PickedProxyType,
+    PickedServerPortType,
+    PickedState,
+)
+from asockslib.models import (
+    ASNInfo,
+    ASNListResponse,
+    AuthType,
+    BalanceResponse,
+    CityInfo,
+    ConnectionType,
+    ConnectionTypeId,
+    CountryInfo,
+    CreatePortRequest,
+    CreateTemplateRequest,
+    PortFilterParams,
+    PortInfo,
+    PortListResponse,
+    PortStatus,
+    ProxyType,
+    ProxyTypeId,
+    ServerPortType,
+    StateInfo,
+    UpdatePortRequest,
+    UpdateTemplateRequest,
+    WhitelistAddRequest,
+)
+from asockslib.proxy_pool import PoolStrategy, ProxyPool, ProxyPoolStats, ProxyStore
+from asockslib.quick import get_proxies, get_proxies_sync
+from asockslib.smart_proxy import SmartProxy
+
+__all__ = [
+    "APIConnectionError",
+    "ASNInfo",
+    "ASNListResponse",
+    "ASocksClient",
+    "ASocksError",
+    "AuthType",
+    "AuthenticationError",
+    "BalanceResponse",
+    "CityInfo",
+    "ConnectionType",
+    "ConnectionTypeId",
+    "CountryInfo",
+    "CountryPingResult",
+    "CreatePortRequest",
+    "CreateTemplateRequest",
+    "FindBestResult",
+    "GeoPicker",
+    "InsufficientBalanceError",
+    "NoAvailableProxyError",
+    "PickedASN",
+    "PickedCity",
+    "PickedConnectionType",
+    "PickedCountry",
+    "PickedProxyType",
+    "PickedServerPortType",
+    "PickedState",
+    "PoolStrategy",
+    "PortFilterParams",
+    "PortInfo",
+    "PortListResponse",
+    "PortNotFoundError",
+    "PortStatus",
+    "ProxyBenchmarkResult",
+    "ProxyHealthError",
+    "ProxyPool",
+    "ProxyPoolStats",
+    "ProxyStore",
+    "ProxyType",
+    "ProxyTypeId",
+    "RateLimitError",
+    "ServerPortType",
+    "SmartProxy",
+    "StateInfo",
+    "UpdatePortRequest",
+    "UpdateTemplateRequest",
+    "WhitelistAddRequest",
+    "benchmark_proxies",
+    "find_best_proxies",
+    "get_proxies",
+    "get_proxies_sync",
+    "ping_proxy",
+    "select_best_proxies",
+]
+
+__version__ = "0.1.0"

asockslib-0.1.0/src/asockslib/_console.py

@@ -0,0 +1,18 @@
+"""Centralized Rich Console singleton.
+
+Every module that needs to print to the terminal should import
+``console`` from here instead of creating its own instance.
+
+Usage::
+
+    from asockslib._console import console
+
+    console.print("[green]OK[/green]")
+"""
+
+from __future__ import annotations
+
+from rich.console import Console
+
+console: Console = Console()
+"""Module-level singleton :class:`~rich.console.Console` instance."""