proxyhat 0.2.0__py3-none-any.whl

proxyhat/types/proxy_presets.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class ProxyPreset:
+    id: str
+    name: str
+    data: dict[str, Any]
+    created_at: str | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ProxyPreset:
+        return cls(
+            id=data.get("id", ""),
+            name=data.get("name", ""),
+            data=data.get("data", {}),
+            created_at=data.get("created_at"),
+        )

proxyhat/types/sub_user.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class SubUser:
+    uuid: str
+    proxy_username: str
+    is_default_user: bool
+    is_traffic_limited: bool
+    used_traffic: int
+    traffic_limit: int
+    lifecycle_status: str
+    name: str | None
+    notes: str | None
+    sub_user_group_id: str | None
+    created_at: str
+    # Gateway password: present on list/get, masked for suspended/deleting sub-users.
+    proxy_password: str | None = None
+    # ISO timestamp when the sub-user was suspended (traffic overage), else None.
+    suspended_at: str | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> SubUser:
+        return cls(
+            uuid=data.get("uuid", ""),
+            proxy_username=data.get("proxy_username", ""),
+            is_default_user=data.get("is_default_user", False),
+            is_traffic_limited=data.get("is_traffic_limited", False),
+            used_traffic=data.get("used_traffic", 0),
+            traffic_limit=data.get("traffic_limit", 0),
+            lifecycle_status=data.get("lifecycle_status", ""),
+            name=data.get("name"),
+            notes=data.get("notes"),
+            sub_user_group_id=data.get("sub_user_group_id"),
+            created_at=data.get("created_at", ""),
+            proxy_password=data.get("proxy_password"),
+            suspended_at=data.get("suspended_at"),
+        )
+
+
+@dataclass
+class ResetUsageResponse:
+    reset: int
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ResetUsageResponse:
+        return cls(reset=data.get("reset", 0))
+
+
+@dataclass
+class BulkDeleteResponse:
+    requested: int
+    deleted: int
+    skipped: int
+    not_found: int
+    failed: int
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> BulkDeleteResponse:
+        return cls(
+            requested=data.get("requested", 0),
+            deleted=data.get("deleted", 0),
+            skipped=data.get("skipped", 0),
+            not_found=data.get("not_found", 0),
+            failed=data.get("failed", 0),
+        )

proxyhat/types/sub_user_groups.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class SubUserGroup:
+    id: str
+    name: str
+    description: str | None
+    sub_users_count: int
+    created_at: str
+    sub_users: list[Any] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> SubUserGroup:
+        return cls(
+            id=data.get("id", ""),
+            name=data.get("name", ""),
+            description=data.get("description"),
+            sub_users_count=data.get("sub_users_count", 0),
+            created_at=data.get("created_at", ""),
+            sub_users=data.get("sub_users", []),
+        )

proxyhat/types/two_factor.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class TwoFactorStatus:
+    enabled: bool
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> TwoFactorStatus:
+        return cls(enabled=data.get("enabled", False))
+
+
+@dataclass
+class TwoFactorEnableResponse:
+    qr: str
+    secret: str
+    recovery_codes: list[str] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> TwoFactorEnableResponse:
+        return cls(
+            qr=data.get("qr", ""),
+            secret=data.get("secret", ""),
+            recovery_codes=data.get("recovery_codes", []),
+        )
+
+
+@dataclass
+class RecoveryCodes:
+    codes: list[str] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> RecoveryCodes:
+        return cls(codes=data if isinstance(data, list) else data.get("codes", []))

proxyhat-0.2.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,39 @@
+proxyhat/__init__.py,sha256=_gzwuxhQzFqx95etmCKysn-tjiEBT1NHGylPYholH8w,865
+proxyhat/_base_client.py,sha256=19KsPRECsyhjl1cugoX-DfmXm85_WmO0rPGrI1eBouQ,2998
+proxyhat/async_client.py,sha256=E9xNPz82VnJZIk2dX7drPEsyAAQFVjxKCyqOLV9Er5A,4943
+proxyhat/client.py,sha256=32waqyQmS_kNJyaHoTmMvln0ixGX8Ef0Oj8HHDGaFD4,4893
+proxyhat/connection.py,sha256=B8BbpKw_jiknvtAXxOn4QH9I_gL6ZkZh39eyL5BoQBs,2795
+proxyhat/errors.py,sha256=6k_7oXxcgUvBpyjzZPC5T-vWlOepwMr9tF074Laybqo,2112
+proxyhat/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+proxyhat/resources/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+proxyhat/resources/analytics.py,sha256=NfbvTAk59358krtsKe1EtEiWDGRxYoQ94gpAayFhYPg,4484
+proxyhat/resources/auth.py,sha256=o1cIARdGuOEN45fXtNrR0SqQYqCfBIub5LC7F2G62Pk,5309
+proxyhat/resources/coupons.py,sha256=5M3vmROrpAH7PMUQDKdGzpzhdbSemxIfj1nO-mmOdUs,3197
+proxyhat/resources/email.py,sha256=ERBjWHe_VVxk30NjlvgwAg5NJCMAmJUgoAbalCZaqvI,2420
+proxyhat/resources/locations.py,sha256=tn3bLccWNVwgK0Ni0Z9YUT7BsStyOFYJc2x_60bjz2E,7472
+proxyhat/resources/payments.py,sha256=kP3ZSYb-dDZSgxPUzfeRs4rADw5Tz78QB1QQH08rv9M,3714
+proxyhat/resources/plans.py,sha256=XuKz4V21Ag8ljVemNG2ksJWVORyVyHPcANAPGsOs_Rs,2972
+proxyhat/resources/profile.py,sha256=ENgJCX838FfJMe_gVch92k1leu3riKKG6V-VqGKtrTI,2824
+proxyhat/resources/proxy_descriptors.py,sha256=qZRxeY5JxuwfDCghjFD0_FFs6WnL-lie7FOnA9M_NUk,1869
+proxyhat/resources/proxy_presets.py,sha256=BQkEVMVo_GrmkPRnXJGeFmAtmr-ehpr7I_LSjO5nOlM,2708
+proxyhat/resources/sub_user_groups.py,sha256=jx7upneuErImc1mz2F64e_VwIruUAVzVLx1EhdBHZ6o,2995
+proxyhat/resources/sub_users.py,sha256=CJ9PwbQnsjdU-y_dvRLEcDpCBrilWnIOIu_rrfFV_kQ,6109
+proxyhat/resources/two_factor.py,sha256=S4d80eg-lQ5nnseTLCGs9x_wSzIxRI1-0D0k-N8WgAY,4003
+proxyhat/types/__init__.py,sha256=wey2ENfU2Yi-U3nmOHi2SQofjdCMr-FJuGbWlBi5Rmg,1639
+proxyhat/types/analytics.py,sha256=HyDWJzPDQMuo7c6lFqMoMdLTH6LytzCx1aZikQwbN5s,1290
+proxyhat/types/auth.py,sha256=WH4QN8EkFhbgmLG2oJDht_h9yLBiipNR-wSNWE89Cco,2761
+proxyhat/types/coupons.py,sha256=Jr_DT7ZH1_JVL1uPsSkhQRqUjnsWWnuadsd5mdd5Fgs,954
+proxyhat/types/email.py,sha256=LOn4TtshkPvheuIE8TZn6k4I9XFUzkaEw2lH0KBacy0,289
+proxyhat/types/locations.py,sha256=-9x50U3hW9ZheG5YhDDvbjUCUR9tZzL6HfFRzwWj6ks,2637
+proxyhat/types/payments.py,sha256=WfprgboOW7OGsa_9E3Mys0SQgNcqebTnlRdYBTp7X6k,2579
+proxyhat/types/plans.py,sha256=Y7Nkw3JDDTOWZJsbTHCyrXGZNAbrfr8MRz-AVrRRrns,1462
+proxyhat/types/profile.py,sha256=kQT8WvQQHCSHrZaYWK-ceINpbm2lY4QBowpxbsiaOEg,673
+proxyhat/types/proxy_descriptor.py,sha256=5ZBw-JIPKhLNHFW1uqERk0xNV8cViyMrzpo9oMXfRhQ,881
+proxyhat/types/proxy_presets.py,sha256=jWv-ykfWSfoLKCN4zR8z6tbGAz4j3ltdIeS2GtPPsBA,479
+proxyhat/types/sub_user.py,sha256=ZZcKkcd_XEhzJVRjfzDeaSPYu6kzdS0enBuyGxNqk0A,2080
+proxyhat/types/sub_user_groups.py,sha256=MoRMkhnpEgFxV9hutVdtje5i5NlZATS8INiToy-NXf0,680
+proxyhat/types/two_factor.py,sha256=NIe6uh43lQhpu94LcLAuoJaRznm_8UP2vJM2bYqE22w,932
+proxyhat-0.2.0.dist-info/METADATA,sha256=RpPBha60ZdM0nUqbAmsn8hLbIfFBaZZH1OXo_tgJkbY,7710
+proxyhat-0.2.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+proxyhat-0.2.0.dist-info/licenses/LICENSE,sha256=_yoC1-ij-yJ3LPoEUetu723duo_t9XcI08QcSS6jSiQ,1065
+proxyhat-0.2.0.dist-info/RECORD,,

proxyhat-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

proxyhat-0.2.0.dist-info/licenses/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.