proxyhat 0.2.0__tar.gz

proxyhat-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: pip install ruff
+      - name: Lint
+        run: ruff check src/ tests/
+      - name: Format check
+        run: ruff format --check src/ tests/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Run tests
+        run: pytest -v
+
+  publish:
+    needs: [lint, test]
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build tools
+        run: pip install build
+      - name: Build package
+        run: python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

proxyhat-0.2.0/.gitignore

@@ -0,0 +1,29 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+dist/
+build/
+*.egg-info/
+*.egg
+.eggs/
+*.whl
+.venv/
+venv/
+env/
+.env
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+htmlcov/
+.coverage
+coverage.xml
+*.log
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+SDK_PROMPT.md

proxyhat-0.2.0/.python-version

@@ -0,0 +1 @@
+3.12

proxyhat-0.2.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-07-13
+
+### Added
+
+- **Proxy connection helpers** — turn an API key or sub-user credentials into a ready proxy URL:
+  - `client.connection_url(...)` (sync + async) — picks an active sub-user and builds the gateway URL
+  - `build_connection_url()` / `build_proxy_username()` — offline gateway URL/username builder
+  - `client.proxy_descriptors.create()` — server-built connection descriptor (`POST /v1/proxy-descriptors`)
+- `SubUser.proxy_password` and `SubUser.suspended_at` fields
+
+## [0.1.0] - 2026-02-13
+
+### Added
+
+- Initial release of the ProxyHat Python SDK
+- Sync (`ProxyHat`) and async (`AsyncProxyHat`) clients
+- Full coverage of ProxyHat API v1 endpoints
+- Typed responses using dataclasses
+- Comprehensive error handling with typed exceptions
+- Pagination support for location endpoints

proxyhat-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ProxyHat
+
+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.

proxyhat-0.2.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: proxyhat
+Version: 0.2.0
+Summary: The official Python SDK for the ProxyHat residential proxy API
+Project-URL: Homepage, https://proxyhat.com
+Project-URL: Documentation, https://docs.proxyhat.com
+Project-URL: Repository, https://github.com/ProxyHatCom/python-sdk
+Project-URL: Changelog, https://github.com/ProxyHatCom/python-sdk/blob/main/CHANGELOG.md
+Author-email: ProxyHat <support@proxyhat.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,proxy,proxyhat,residential-proxy,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ProxyHat Python SDK
+
+The official Python SDK for the [ProxyHat](https://proxyhat.com?utm_source=github&utm_medium=readme&utm_campaign=sdk-python&utm_content=hero) residential proxy API.
+
+[![CI](https://github.com/ProxyHatCom/python-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/ProxyHatCom/python-sdk/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/proxyhat)](https://pypi.org/project/proxyhat/)
+[![Python](https://img.shields.io/pypi/pyversions/proxyhat)](https://pypi.org/project/proxyhat/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## Features
+
+- **One-call proxy connection** — `client.connection_url()` turns your API key into a ready-to-use residential proxy URL
+- Full coverage of the ProxyHat API
+- Local gateway URL builder (`build_connection_url`) — no network needed
+- Sync (`ProxyHat`) and async (`AsyncProxyHat`) clients
+- Typed responses using dataclasses
+- Comprehensive error handling with typed exceptions
+- Pagination support for location endpoints
+
+## Installation
+
+```bash
+pip install proxyhat
+```
+
+## Quick Start
+
+```python
+from proxyhat import ProxyHat
+
+client = ProxyHat(api_key="ph_your_api_key")
+
+# List sub-users
+users = client.sub_users.list()
+for user in users:
+    print(user.proxy_username, user.lifecycle_status)
+
+# Create a sub-user
+new_user = client.sub_users.create(
+    proxy_password="secure_pass",
+    is_traffic_limited=True,
+    traffic_limit="5GB",
+    name="Scraper",
+)
+print(new_user.uuid)
+```
+
+### Async Usage
+
+```python
+import asyncio
+from proxyhat import AsyncProxyHat
+
+async def main():
+    async with AsyncProxyHat(api_key="ph_your_api_key") as client:
+        users = await client.sub_users.list()
+        for user in users:
+            print(user.proxy_username)
+
+asyncio.run(main())
+```
+
+## Connecting to a proxy
+
+From an API key to actually routing traffic in one call — the SDK looks up an active sub-user and builds the gateway URL for you:
+
+```python
+from proxyhat import ProxyHat
+
+proxy = ProxyHat(api_key="ph_your_api_key")
+
+# Rotating residential IP, US exit:
+url = proxy.connection_url(country="us")
+# → http://<user>-country-us:<pass>@gate.proxyhat.com:8080
+
+# Sticky session (same IP for 30m), city-targeted, SOCKS5:
+sticky = proxy.connection_url(country="de", city="berlin", sticky="30m", protocol="socks5")
+
+# Use it with any HTTP client:
+import httpx
+resp = httpx.get("https://api.ipify.org", proxy=url)
+```
+
+**Offline builder** — if you already have a sub-user's credentials, build the URL with no network call:
+
+```python
+from proxyhat import build_connection_url
+
+url = build_connection_url(username="ph-8f2a1c", password="PxSecret123", country="gb", filter="high")
+```
+
+**Server-built descriptor** — let the API assemble it (validates the sub-user is active):
+
+```python
+d = proxy.proxy_descriptors.create(
+    sub_user_uuid=user.uuid,
+    protocol="http",
+    location={"country": "us", "city": "new_york"},
+    session={"mode": "sticky", "ttl": "30m"},
+)
+print(d.url)
+```
+
+## Authentication
+
+Get your API key from the [ProxyHat Dashboard](https://dashboard.proxyhat.com/register?utm_source=github&utm_medium=readme&utm_campaign=sdk-python&utm_content=signup).
+
+See the [Authentication Guide](https://docs.proxyhat.com/authentication?utm_source=github&utm_medium=readme&utm_campaign=sdk-python&utm_content=auth-guide) for details.
+
+## API Reference
+
+| Resource | Methods |
+|----------|---------|
+| `client.auth` | `register`, `login`, `user`, `logout`, `supported_providers`, `social_accounts`, `disconnect_social`, `oauth_redirect` |
+| `client.sub_users` | `list`, `create`, `get`, `update`, `delete`, `reset_usage`, `bulk_delete`, `bulk_move_to_group` |
+| `client.sub_user_groups` | `list`, `create`, `get`, `update`, `delete` |
+| `client.locations` | `countries`, `regions`, `cities`, `isps`, `zipcodes` |
+| `client.analytics` | `traffic`, `traffic_total`, `requests`, `requests_total`, `domain_breakdown` |
+| `client.proxy_presets` | `list`, `create`, `get`, `update`, `delete` |
+| `client.proxy_descriptors` | `create` |
+| `client.connection_url(...)` | build a ready proxy URL from an active sub-user |
+| `client.profile` | `get_preferences`, `update_preferences`, `list_api_keys`, `create_api_key`, `delete_api_key`, `regenerate_api_key` |
+| `client.two_factor` | `status`, `enable`, `confirm`, `disable`, `qr_code`, `recovery_codes`, `disable_by_recovery`, `change_password` |
+| `client.email` | `request_change`, `confirm_change`, `cancel_change`, `resend_verification` |
+| `client.coupons` | `validate`, `apply`, `redeem` |
+| `client.plans` | `list_regular`, `list_subscriptions`, `get_regular`, `get_subscription`, `pricing_regular`, `pricing_subscriptions` |
+| `client.payments` | `list`, `create`, `get`, `check`, `invoice`, `cryptocurrencies` |
+
+## Error Handling
+
+```python
+from proxyhat import ProxyHat, ProxyHatError, NotFoundError, RateLimitError, ValidationError
+
+client = ProxyHat(api_key="ph_your_api_key")
+
+try:
+    user = client.sub_users.get("nonexistent-id")
+except NotFoundError as e:
+    print(f"Not found: {e.message}")
+except RateLimitError as e:
+    print(f"Rate limited. Retry after {e.retry_after}s")
+except ValidationError as e:
+    print(f"Validation failed: {e.errors}")
+except ProxyHatError as e:
+    print(f"API error {e.status_code}: {e.message}")
+```
+
+See the [Error Handling Guide](https://docs.proxyhat.com/errors?utm_source=github&utm_medium=readme&utm_campaign=sdk-python&utm_content=error-handling) for the full list of error codes.
+
+## Documentation
+
+- [Getting Started](https://docs.proxyhat.com?utm_source=github&utm_medium=readme&utm_campaign=sdk-python&utm_content=getting-started)
+- [API Reference](https://docs.proxyhat.com/api/auth?utm_source=github&utm_medium=readme&utm_campaign=sdk-python&utm_content=api-reference)
+- [Full Documentation](https://docs.proxyhat.com?utm_source=github&utm_medium=readme&utm_campaign=sdk-python&utm_content=docs-home)
+
+## Links
+
+- [ProxyHat](https://proxyhat.com?utm_source=github&utm_medium=readme&utm_campaign=sdk-python&utm_content=links) — Residential & mobile proxy network
+- [Dashboard](https://dashboard.proxyhat.com?utm_source=github&utm_medium=readme&utm_campaign=sdk-python&utm_content=links) — Manage proxies, sub-users, and API keys
+- [GitHub](https://github.com/ProxyHatCom/python-sdk) — Source code & issue tracker
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

proxyhat-0.2.0/README.md

@@ -0,0 +1,164 @@
+# ProxyHat Python SDK
+
+The official Python SDK for the [ProxyHat](https://proxyhat.com?utm_source=github&utm_medium=readme&utm_campaign=sdk-python&utm_content=hero) residential proxy API.
+
+[![CI](https://github.com/ProxyHatCom/python-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/ProxyHatCom/python-sdk/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/proxyhat)](https://pypi.org/project/proxyhat/)
+[![Python](https://img.shields.io/pypi/pyversions/proxyhat)](https://pypi.org/project/proxyhat/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## Features
+
+- **One-call proxy connection** — `client.connection_url()` turns your API key into a ready-to-use residential proxy URL
+- Full coverage of the ProxyHat API
+- Local gateway URL builder (`build_connection_url`) — no network needed
+- Sync (`ProxyHat`) and async (`AsyncProxyHat`) clients
+- Typed responses using dataclasses
+- Comprehensive error handling with typed exceptions
+- Pagination support for location endpoints
+
+## Installation
+
+```bash
+pip install proxyhat
+```
+
+## Quick Start
+
+```python
+from proxyhat import ProxyHat
+
+client = ProxyHat(api_key="ph_your_api_key")
+
+# List sub-users
+users = client.sub_users.list()
+for user in users:
+    print(user.proxy_username, user.lifecycle_status)
+
+# Create a sub-user
+new_user = client.sub_users.create(
+    proxy_password="secure_pass",
+    is_traffic_limited=True,
+    traffic_limit="5GB",
+    name="Scraper",
+)
+print(new_user.uuid)
+```
+
+### Async Usage
+
+```python
+import asyncio
+from proxyhat import AsyncProxyHat
+
+async def main():
+    async with AsyncProxyHat(api_key="ph_your_api_key") as client:
+        users = await client.sub_users.list()
+        for user in users:
+            print(user.proxy_username)
+
+asyncio.run(main())
+```
+
+## Connecting to a proxy
+
+From an API key to actually routing traffic in one call — the SDK looks up an active sub-user and builds the gateway URL for you:
+
+```python
+from proxyhat import ProxyHat
+
+proxy = ProxyHat(api_key="ph_your_api_key")
+
+# Rotating residential IP, US exit:
+url = proxy.connection_url(country="us")
+# → http://<user>-country-us:<pass>@gate.proxyhat.com:8080
+
+# Sticky session (same IP for 30m), city-targeted, SOCKS5:
+sticky = proxy.connection_url(country="de", city="berlin", sticky="30m", protocol="socks5")
+
+# Use it with any HTTP client:
+import httpx
+resp = httpx.get("https://api.ipify.org", proxy=url)
+```
+
+**Offline builder** — if you already have a sub-user's credentials, build the URL with no network call:
+
+```python
+from proxyhat import build_connection_url
+
+url = build_connection_url(username="ph-8f2a1c", password="PxSecret123", country="gb", filter="high")
+```
+
+**Server-built descriptor** — let the API assemble it (validates the sub-user is active):
+
+```python
+d = proxy.proxy_descriptors.create(
+    sub_user_uuid=user.uuid,
+    protocol="http",
+    location={"country": "us", "city": "new_york"},
+    session={"mode": "sticky", "ttl": "30m"},
+)
+print(d.url)
+```
+
+## Authentication
+
+Get your API key from the [ProxyHat Dashboard](https://dashboard.proxyhat.com/register?utm_source=github&utm_medium=readme&utm_campaign=sdk-python&utm_content=signup).
+
+See the [Authentication Guide](https://docs.proxyhat.com/authentication?utm_source=github&utm_medium=readme&utm_campaign=sdk-python&utm_content=auth-guide) for details.
+
+## API Reference
+
+| Resource | Methods |
+|----------|---------|
+| `client.auth` | `register`, `login`, `user`, `logout`, `supported_providers`, `social_accounts`, `disconnect_social`, `oauth_redirect` |
+| `client.sub_users` | `list`, `create`, `get`, `update`, `delete`, `reset_usage`, `bulk_delete`, `bulk_move_to_group` |
+| `client.sub_user_groups` | `list`, `create`, `get`, `update`, `delete` |
+| `client.locations` | `countries`, `regions`, `cities`, `isps`, `zipcodes` |
+| `client.analytics` | `traffic`, `traffic_total`, `requests`, `requests_total`, `domain_breakdown` |
+| `client.proxy_presets` | `list`, `create`, `get`, `update`, `delete` |
+| `client.proxy_descriptors` | `create` |
+| `client.connection_url(...)` | build a ready proxy URL from an active sub-user |
+| `client.profile` | `get_preferences`, `update_preferences`, `list_api_keys`, `create_api_key`, `delete_api_key`, `regenerate_api_key` |
+| `client.two_factor` | `status`, `enable`, `confirm`, `disable`, `qr_code`, `recovery_codes`, `disable_by_recovery`, `change_password` |
+| `client.email` | `request_change`, `confirm_change`, `cancel_change`, `resend_verification` |
+| `client.coupons` | `validate`, `apply`, `redeem` |
+| `client.plans` | `list_regular`, `list_subscriptions`, `get_regular`, `get_subscription`, `pricing_regular`, `pricing_subscriptions` |
+| `client.payments` | `list`, `create`, `get`, `check`, `invoice`, `cryptocurrencies` |
+
+## Error Handling
+
+```python
+from proxyhat import ProxyHat, ProxyHatError, NotFoundError, RateLimitError, ValidationError
+
+client = ProxyHat(api_key="ph_your_api_key")
+
+try:
+    user = client.sub_users.get("nonexistent-id")
+except NotFoundError as e:
+    print(f"Not found: {e.message}")
+except RateLimitError as e:
+    print(f"Rate limited. Retry after {e.retry_after}s")
+except ValidationError as e:
+    print(f"Validation failed: {e.errors}")
+except ProxyHatError as e:
+    print(f"API error {e.status_code}: {e.message}")
+```
+
+See the [Error Handling Guide](https://docs.proxyhat.com/errors?utm_source=github&utm_medium=readme&utm_campaign=sdk-python&utm_content=error-handling) for the full list of error codes.
+
+## Documentation
+
+- [Getting Started](https://docs.proxyhat.com?utm_source=github&utm_medium=readme&utm_campaign=sdk-python&utm_content=getting-started)
+- [API Reference](https://docs.proxyhat.com/api/auth?utm_source=github&utm_medium=readme&utm_campaign=sdk-python&utm_content=api-reference)
+- [Full Documentation](https://docs.proxyhat.com?utm_source=github&utm_medium=readme&utm_campaign=sdk-python&utm_content=docs-home)
+
+## Links
+
+- [ProxyHat](https://proxyhat.com?utm_source=github&utm_medium=readme&utm_campaign=sdk-python&utm_content=links) — Residential & mobile proxy network
+- [Dashboard](https://dashboard.proxyhat.com?utm_source=github&utm_medium=readme&utm_campaign=sdk-python&utm_content=links) — Manage proxies, sub-users, and API keys
+- [GitHub](https://github.com/ProxyHatCom/python-sdk) — Source code & issue tracker
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

proxyhat-0.2.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "proxyhat"
+version = "0.2.0"
+description = "The official Python SDK for the ProxyHat residential proxy API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "ProxyHat", email = "support@proxyhat.com" }]
+keywords = ["proxy", "residential-proxy", "proxyhat", "sdk", "api"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.24.0"]
+
+[project.urls]
+Homepage = "https://proxyhat.com"
+Documentation = "https://docs.proxyhat.com"
+Repository = "https://github.com/ProxyHatCom/python-sdk"
+Changelog = "https://github.com/ProxyHatCom/python-sdk/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "respx>=0.20",
+    "ruff>=0.4",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/proxyhat"]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

proxyhat-0.2.0/src/proxyhat/__init__.py

@@ -0,0 +1,39 @@
+"""ProxyHat Python SDK — official client for the ProxyHat residential proxy API."""
+
+from proxyhat.async_client import AsyncProxyHat
+from proxyhat.client import ProxyHat
+from proxyhat.connection import (
+    PROXYHAT_GATEWAY,
+    PROXYHAT_PORT_HTTP,
+    PROXYHAT_PORT_SOCKS5,
+    build_connection_url,
+    build_proxy_username,
+)
+from proxyhat.errors import (
+    APIError,
+    AuthenticationError,
+    NotFoundError,
+    PermissionError,
+    ProxyHatError,
+    RateLimitError,
+    ValidationError,
+)
+
+__all__ = [
+    "PROXYHAT_GATEWAY",
+    "PROXYHAT_PORT_HTTP",
+    "PROXYHAT_PORT_SOCKS5",
+    "APIError",
+    "AsyncProxyHat",
+    "AuthenticationError",
+    "NotFoundError",
+    "PermissionError",
+    "ProxyHat",
+    "ProxyHatError",
+    "RateLimitError",
+    "ValidationError",
+    "build_connection_url",
+    "build_proxy_username",
+]
+
+__version__ = "0.2.0"