mobileproxy-sdk 1.0.0__tar.gz

mobileproxy_sdk-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MOBIROX LLP / MobileProxy.Space
+
+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.

mobileproxy_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: mobileproxy-sdk
+Version: 1.0.0
+Summary: Official Python SDK for MobileProxy.Space API — private mobile proxies on real GSM devices
+Author-email: "MobileProxy.Space" <support@mobirox.co.uk>
+License: MIT
+Project-URL: Homepage, https://mobileproxy.space
+Project-URL: Documentation, https://mobileproxy.space/en/user.html?api
+Project-URL: Repository, https://github.com/mobileproxy/python-sdk
+Project-URL: Issues, https://github.com/mobileproxy/python-sdk/issues
+Project-URL: Changelog, https://github.com/mobileproxy/python-sdk/releases
+Keywords: proxy,mobile-proxy,mobileproxy,socks5,http-proxy,scraping,api-client,ip-rotation
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: Topic :: Internet :: Proxy Servers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.20.0
+Provides-Extra: async
+Requires-Dist: httpx>=0.24.0; extra == "async"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Dynamic: license-file
+
+# MobileProxy.Space Python SDK
+
+[![CI](https://github.com/mobileproxy/python-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/mobileproxy/python-sdk/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/mobileproxy-sdk)](https://pypi.org/project/mobileproxy-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/mobileproxy-sdk)](https://pypi.org/project/mobileproxy-sdk/)
+
+Official Python SDK for the [MobileProxy.Space](https://mobileproxy.space) API — private mobile proxies on real GSM devices across 52 countries.
+
+## Features
+
+- **Full API coverage** — all endpoints wrapped in typed, documented methods
+- **Context manager** support (`with Client(...) as client:`)
+- **Typed exceptions** — `ApiError`, `AuthenticationError`, `RateLimitError`
+- **IP rotation** — dedicated `change_ip()` with no rate limit
+- **Python 3.8+** compatible
+- **Type hints** throughout + `py.typed` marker (PEP 561)
+
+## Installation
+
+```bash
+pip install mobileproxy-sdk
+```
+
+## Quick Start
+
+```python
+from mobileproxy import Client
+
+client = Client("YOUR_API_TOKEN")
+
+# Check balance
+balance = client.get_balance()
+print(balance)
+
+# List active proxies
+proxies = client.get_my_proxy()
+
+# Get current IP
+ip = client.get_proxy_ip(12345)
+
+# Rotate IP (no rate limit)
+client.change_ip("your_proxy_key")
+```
+
+### Context Manager
+
+```python
+with Client("YOUR_API_TOKEN") as client:
+    balance = client.get_balance()
+    print(balance)
+# session is closed automatically
+```
+
+## API Methods
+
+### Proxy Information
+
+| Method | Description |
+|--------|-------------|
+| `get_proxy_ip(proxy_id, *, check_spam=)` | Get current IP address of a proxy |
+| `get_my_proxy(proxy_id=)` | List active proxies (all or specific) |
+| `get_ip_stats()` | IP address statistics by GEO |
+
+### Proxy Management
+
+| Method | Description |
+|--------|-------------|
+| `change_proxy_credentials(proxy_id, login, password)` | Change proxy login/password |
+| `reboot_proxy(proxy_id)` | Restart the modem |
+| `edit_proxy(proxy_id, *, reboot_time=, ip_auth=, comment=)` | Update proxy settings |
+| `change_ip(proxy_key, *, format=, user_agent=)` | Rotate IP (no rate limit) |
+
+### Equipment & GEO
+
+| Method | Description |
+|--------|-------------|
+| `change_equipment(proxy_id, **kwargs)` | Switch modem/SIM/operator/city |
+| `get_available_equipment(proxy_id, **kwargs)` | List available equipment by GEO |
+| `get_geo_list(proxy_id, geo_id)` | Available GEOs for a proxy |
+| `get_operators(geo_id)` | Operators for a GEO |
+| `get_countries(only_available=)` | List of countries |
+| `get_cities()` | List of cities |
+
+### Blacklist
+
+| Method | Description |
+|--------|-------------|
+| `get_black_list(proxy_id)` | Get equipment/operator blacklist |
+| `add_operator_to_black_list(proxy_id, operator_id)` | Block an operator |
+| `remove_operator_from_black_list(proxy_id, operator_id)` | Unblock an operator |
+| `remove_from_black_list(proxy_id, black_list_id, eid)` | Remove equipment from blacklist |
+
+### Purchasing & Billing
+
+| Method | Description |
+|--------|-------------|
+| `buy_proxy(**kwargs)` | Purchase a proxy |
+| `refund_proxy(proxy_id)` | Request a refund |
+| `get_balance()` | Account balance |
+| `get_prices(country_id)` | Prices for a country |
+| `get_test_proxy(geo_id, operator)` | Get a free 2-hour trial proxy |
+
+### Utilities
+
+| Method | Description |
+|--------|-------------|
+| `check_equipment_availability(eid)` | Check if equipment is available |
+| `view_url_from_different_ips(url, country_id)` | Anti-cloaking: view URL from another country |
+| `get_task_result(task_id)` | Get async task result |
+
+## Error Handling
+
+```python
+from mobileproxy import Client, ApiError, AuthenticationError, RateLimitError
+
+client = Client("YOUR_API_TOKEN")
+
+try:
+    client.get_balance()
+except AuthenticationError as e:
+    # Invalid API token
+    print(e, e.http_code)
+except RateLimitError as e:
+    # Too many requests — back off and retry
+    # Limit: 3 × (number of active proxies) requests/sec
+    print(e)
+except ApiError as e:
+    print(e.http_code, e.response_body)
+```
+
+## Configuration
+
+```python
+client = Client(
+    "YOUR_API_TOKEN",
+    timeout=120,     # request timeout in seconds
+    base_url="https://mobileproxy.space/api.html",  # default
+)
+```
+
+## Rate Limits
+
+API requests are limited to **3 × (number of active proxies)** per second. For example, 10 proxies = 30 req/s. The `change_ip()` method uses a separate endpoint with **no rate limit**.
+
+## Requirements
+
+- Python 3.8 or higher
+- `requests` library (installed automatically)
+
+## Links
+
+- [API Documentation](https://mobileproxy.space/en/user.html?api)
+- [Dashboard](https://mobileproxy.space/en/user.html)
+- [Website](https://mobileproxy.space)
+- [PHP SDK](https://github.com/mobileproxy/php-sdk)
+- [Node.js SDK](https://github.com/mobileproxy/node-sdk)
+- [Chrome Extension](https://chromewebstore.google.com/detail/mobile-proxy-manager/lhbdhjhflkejgkkhlgacbaogbaaollac)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

mobileproxy_sdk-1.0.0/README.md

@@ -0,0 +1,161 @@
+# MobileProxy.Space Python SDK
+
+[![CI](https://github.com/mobileproxy/python-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/mobileproxy/python-sdk/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/mobileproxy-sdk)](https://pypi.org/project/mobileproxy-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/mobileproxy-sdk)](https://pypi.org/project/mobileproxy-sdk/)
+
+Official Python SDK for the [MobileProxy.Space](https://mobileproxy.space) API — private mobile proxies on real GSM devices across 52 countries.
+
+## Features
+
+- **Full API coverage** — all endpoints wrapped in typed, documented methods
+- **Context manager** support (`with Client(...) as client:`)
+- **Typed exceptions** — `ApiError`, `AuthenticationError`, `RateLimitError`
+- **IP rotation** — dedicated `change_ip()` with no rate limit
+- **Python 3.8+** compatible
+- **Type hints** throughout + `py.typed` marker (PEP 561)
+
+## Installation
+
+```bash
+pip install mobileproxy-sdk
+```
+
+## Quick Start
+
+```python
+from mobileproxy import Client
+
+client = Client("YOUR_API_TOKEN")
+
+# Check balance
+balance = client.get_balance()
+print(balance)
+
+# List active proxies
+proxies = client.get_my_proxy()
+
+# Get current IP
+ip = client.get_proxy_ip(12345)
+
+# Rotate IP (no rate limit)
+client.change_ip("your_proxy_key")
+```
+
+### Context Manager
+
+```python
+with Client("YOUR_API_TOKEN") as client:
+    balance = client.get_balance()
+    print(balance)
+# session is closed automatically
+```
+
+## API Methods
+
+### Proxy Information
+
+| Method | Description |
+|--------|-------------|
+| `get_proxy_ip(proxy_id, *, check_spam=)` | Get current IP address of a proxy |
+| `get_my_proxy(proxy_id=)` | List active proxies (all or specific) |
+| `get_ip_stats()` | IP address statistics by GEO |
+
+### Proxy Management
+
+| Method | Description |
+|--------|-------------|
+| `change_proxy_credentials(proxy_id, login, password)` | Change proxy login/password |
+| `reboot_proxy(proxy_id)` | Restart the modem |
+| `edit_proxy(proxy_id, *, reboot_time=, ip_auth=, comment=)` | Update proxy settings |
+| `change_ip(proxy_key, *, format=, user_agent=)` | Rotate IP (no rate limit) |
+
+### Equipment & GEO
+
+| Method | Description |
+|--------|-------------|
+| `change_equipment(proxy_id, **kwargs)` | Switch modem/SIM/operator/city |
+| `get_available_equipment(proxy_id, **kwargs)` | List available equipment by GEO |
+| `get_geo_list(proxy_id, geo_id)` | Available GEOs for a proxy |
+| `get_operators(geo_id)` | Operators for a GEO |
+| `get_countries(only_available=)` | List of countries |
+| `get_cities()` | List of cities |
+
+### Blacklist
+
+| Method | Description |
+|--------|-------------|
+| `get_black_list(proxy_id)` | Get equipment/operator blacklist |
+| `add_operator_to_black_list(proxy_id, operator_id)` | Block an operator |
+| `remove_operator_from_black_list(proxy_id, operator_id)` | Unblock an operator |
+| `remove_from_black_list(proxy_id, black_list_id, eid)` | Remove equipment from blacklist |
+
+### Purchasing & Billing
+
+| Method | Description |
+|--------|-------------|
+| `buy_proxy(**kwargs)` | Purchase a proxy |
+| `refund_proxy(proxy_id)` | Request a refund |
+| `get_balance()` | Account balance |
+| `get_prices(country_id)` | Prices for a country |
+| `get_test_proxy(geo_id, operator)` | Get a free 2-hour trial proxy |
+
+### Utilities
+
+| Method | Description |
+|--------|-------------|
+| `check_equipment_availability(eid)` | Check if equipment is available |
+| `view_url_from_different_ips(url, country_id)` | Anti-cloaking: view URL from another country |
+| `get_task_result(task_id)` | Get async task result |
+
+## Error Handling
+
+```python
+from mobileproxy import Client, ApiError, AuthenticationError, RateLimitError
+
+client = Client("YOUR_API_TOKEN")
+
+try:
+    client.get_balance()
+except AuthenticationError as e:
+    # Invalid API token
+    print(e, e.http_code)
+except RateLimitError as e:
+    # Too many requests — back off and retry
+    # Limit: 3 × (number of active proxies) requests/sec
+    print(e)
+except ApiError as e:
+    print(e.http_code, e.response_body)
+```
+
+## Configuration
+
+```python
+client = Client(
+    "YOUR_API_TOKEN",
+    timeout=120,     # request timeout in seconds
+    base_url="https://mobileproxy.space/api.html",  # default
+)
+```
+
+## Rate Limits
+
+API requests are limited to **3 × (number of active proxies)** per second. For example, 10 proxies = 30 req/s. The `change_ip()` method uses a separate endpoint with **no rate limit**.
+
+## Requirements
+
+- Python 3.8 or higher
+- `requests` library (installed automatically)
+
+## Links
+
+- [API Documentation](https://mobileproxy.space/en/user.html?api)
+- [Dashboard](https://mobileproxy.space/en/user.html)
+- [Website](https://mobileproxy.space)
+- [PHP SDK](https://github.com/mobileproxy/php-sdk)
+- [Node.js SDK](https://github.com/mobileproxy/node-sdk)
+- [Chrome Extension](https://chromewebstore.google.com/detail/mobile-proxy-manager/lhbdhjhflkejgkkhlgacbaogbaaollac)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

mobileproxy_sdk-1.0.0/mobileproxy/__init__.py

@@ -0,0 +1,26 @@
+"""MobileProxy.Space Python SDK.
+
+Official Python SDK for interacting with the MobileProxy.Space API.
+Provides private mobile proxies on real GSM devices across 52 countries.
+
+Quick start::
+
+    from mobileproxy import Client
+
+    client = Client("YOUR_API_TOKEN")
+    print(client.get_balance())
+
+See https://mobileproxy.space/api.html
+"""
+
+from .client import Client
+from .exceptions import ApiError, AuthenticationError, RateLimitError
+
+__all__ = [
+    "Client",
+    "ApiError",
+    "AuthenticationError",
+    "RateLimitError",
+]
+
+__version__ = "1.0.0"

mobileproxy_sdk-1.0.0/mobileproxy/client.py

@@ -0,0 +1,432 @@
+"""MobileProxy.Space API Client.
+
+Official Python SDK for interacting with the MobileProxy.Space API.
+Provides private mobile proxies on real GSM devices across 52 countries.
+
+Example::
+
+    from mobileproxy import Client
+
+    client = Client("YOUR_API_TOKEN")
+    balance = client.get_balance()
+    print(balance)
+
+See https://mobileproxy.space/api.html for API documentation.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+import requests
+
+from .exceptions import ApiError
+from .http_client import HttpClient
+
+
+class Client:
+    """MobileProxy.Space API client.
+
+    Args:
+        api_token: Your API token (find it in your dashboard).
+        base_url: API endpoint override.
+        timeout: Request timeout in seconds (default: 60).
+    """
+
+    def __init__(
+        self,
+        api_token: str,
+        *,
+        base_url: str = "https://mobileproxy.space/api.html",
+        timeout: int = 60,
+    ):
+        if not api_token:
+            raise ValueError("API token is required")
+        self._http = HttpClient(api_token, base_url=base_url, timeout=timeout)
+
+    def close(self):
+        """Close the underlying HTTP session."""
+        self._http.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+    # ──────────────────────────────────────────────
+    #  Proxy Information
+    # ──────────────────────────────────────────────
+
+    def get_proxy_ip(
+        self, proxy_id: int, *, check_spam: Optional[str] = None
+    ) -> dict:
+        """Get the current IP address of a proxy.
+
+        Args:
+            proxy_id: Proxy ID.
+            check_spam: Pass "1" to check IP against spam databases.
+        """
+        params: Dict[str, Any] = {"proxy_id": proxy_id}
+        if check_spam is not None:
+            params["check_spam"] = check_spam
+        return self._http.request("proxy_ip", "GET", params)
+
+    def get_my_proxy(self, proxy_id: Optional[int] = None) -> dict:
+        """Get a list of your active proxies.
+
+        Args:
+            proxy_id: Filter by specific proxy ID, or None for all.
+        """
+        params: Dict[str, Any] = {}
+        if proxy_id is not None:
+            params["proxy_id"] = proxy_id
+        return self._http.request("get_my_proxy", "GET", params)
+
+    def get_ip_stats(self) -> dict:
+        """Get IP address statistics by GEO."""
+        return self._http.request("get_ipstat")
+
+    # ──────────────────────────────────────────────
+    #  Proxy Management
+    # ──────────────────────────────────────────────
+
+    def change_proxy_credentials(
+        self, proxy_id: int, login: str, password: str
+    ) -> dict:
+        """Change the login and password of a proxy.
+
+        Args:
+            proxy_id: Proxy ID.
+            login: New login.
+            password: New password.
+        """
+        return self._http.request(
+            "change_proxy_login_password",
+            "GET",
+            {"proxy_id": proxy_id, "proxy_login": login, "proxy_pass": password},
+        )
+
+    def reboot_proxy(self, proxy_id: int) -> dict:
+        """Restart a proxy (reboot the modem).
+
+        Args:
+            proxy_id: Proxy ID.
+        """
+        return self._http.request("reboot_proxy", "GET", {"proxy_id": proxy_id})
+
+    def edit_proxy(
+        self,
+        proxy_id: int,
+        *,
+        reboot_time: Optional[int] = None,
+        ip_auth: Optional[str] = None,
+        comment: Optional[str] = None,
+    ) -> dict:
+        """Change existing proxy settings.
+
+        Args:
+            proxy_id: Proxy ID.
+            reboot_time: Auto-reboot interval in minutes (0 to disable).
+            ip_auth: Authorized IP address (empty string to disable).
+            comment: Comment / label for this proxy.
+        """
+        params: Dict[str, Any] = {"proxy_id": proxy_id}
+        if reboot_time is not None:
+            params["proxy_reboot_time"] = reboot_time
+        if ip_auth is not None:
+            params["proxy_ipauth"] = ip_auth
+        if comment is not None:
+            params["proxy_comment"] = comment
+        return self._http.request("edit_proxy", "GET", params)
+
+    # ──────────────────────────────────────────────
+    #  Equipment & GEO
+    # ──────────────────────────────────────────────
+
+    def change_equipment(self, proxy_id: int, **kwargs) -> dict:
+        """Change proxy equipment (modem/SIM).
+
+        Args:
+            proxy_id: Proxy ID.
+            **kwargs: Optional parameters:
+                operator (str): Target operator name.
+                geo_id (int): GEO ID.
+                country_id (int): Country ID.
+                city_id (int): City ID.
+                eid (int): Equipment ID.
+                add_to_black_list: Add current equipment to blacklist.
+                check_after_change: Check IP after change.
+                check_spam: Check spam after change.
+        """
+        params: Dict[str, Any] = {"proxy_id": proxy_id}
+        mapping = {
+            "operator": "operator",
+            "geo_id": "geoid",
+            "country_id": "id_country",
+            "city_id": "id_city",
+            "eid": "eid",
+            "add_to_black_list": "add_to_black_list",
+            "check_after_change": "check_after_change",
+            "check_spam": "check_spam",
+        }
+        for py_key, api_key in mapping.items():
+            if py_key in kwargs and kwargs[py_key] is not None:
+                params[api_key] = kwargs[py_key]
+        return self._http.request("change_equipment", "GET", params)
+
+    def get_available_equipment(self, proxy_id: int, **kwargs) -> dict:
+        """Get available equipment grouped by GEO and operator.
+
+        Args:
+            proxy_id: Proxy ID.
+            **kwargs: Optional parameters:
+                equipments_back_list (int): Exclude equipment IDs.
+                operators_back_list (int): Exclude operator IDs.
+                show_count_null: Show items with 0 count.
+        """
+        params: Dict[str, Any] = {"proxy_id": proxy_id}
+        for key in ("equipments_back_list", "operators_back_list", "show_count_null"):
+            if key in kwargs and kwargs[key] is not None:
+                params[key] = kwargs[key]
+        return self._http.request("get_geo_operator_list", "GET", params)
+
+    def get_geo_list(self, proxy_id: int, geo_id: int) -> dict:
+        """Get list of available GEOs for a proxy.
+
+        Args:
+            proxy_id: Proxy ID.
+            geo_id: GEO ID.
+        """
+        return self._http.request(
+            "get_geo_list", "GET", {"proxy_id": proxy_id, "geoid": geo_id}
+        )
+
+    def get_operators(self, geo_id: int) -> dict:
+        """Get list of operators for a GEO.
+
+        Args:
+            geo_id: GEO ID.
+        """
+        return self._http.request("get_operators_list", "GET", {"geoid": geo_id})
+
+    def get_countries(self, only_available: Optional[str] = None) -> dict:
+        """Get list of countries.
+
+        Args:
+            only_available: Filter to only available countries.
+        """
+        params: Dict[str, Any] = {}
+        if only_available is not None:
+            params["only_avaliable"] = only_available
+        return self._http.request("get_id_country", "GET", params)
+
+    def get_cities(self) -> dict:
+        """Get list of cities."""
+        return self._http.request("get_id_city")
+
+    # ──────────────────────────────────────────────
+    #  Blacklist Management
+    # ──────────────────────────────────────────────
+
+    def get_black_list(self, proxy_id: int) -> dict:
+        """Get the blacklist of equipment and operators for a proxy.
+
+        Args:
+            proxy_id: Proxy ID.
+        """
+        return self._http.request("get_black_list", "GET", {"proxy_id": proxy_id})
+
+    def add_operator_to_black_list(self, proxy_id: int, operator_id: int) -> dict:
+        """Add an operator to the blacklist.
+
+        Args:
+            proxy_id: Proxy ID.
+            operator_id: Operator ID.
+        """
+        return self._http.request(
+            "add_operator_to_black_list",
+            "GET",
+            {"proxy_id": proxy_id, "operator_id": operator_id},
+        )
+
+    def remove_operator_from_black_list(
+        self, proxy_id: int, operator_id: int
+    ) -> dict:
+        """Remove an operator from the blacklist.
+
+        Args:
+            proxy_id: Proxy ID.
+            operator_id: Operator ID.
+        """
+        return self._http.request(
+            "remove_operator_black_list",
+            "GET",
+            {"proxy_id": proxy_id, "operator_id": operator_id},
+        )
+
+    def remove_from_black_list(
+        self, proxy_id: int, black_list_id: int, eid: int
+    ) -> dict:
+        """Remove an entry from the equipment blacklist.
+
+        Args:
+            proxy_id: Proxy ID.
+            black_list_id: Blacklist entry ID.
+            eid: Equipment ID.
+        """
+        return self._http.request(
+            "remove_black_list",
+            "GET",
+            {"proxy_id": proxy_id, "black_list_id": black_list_id, "eid": eid},
+        )
+
+    # ──────────────────────────────────────────────
+    #  Purchasing & Billing
+    # ──────────────────────────────────────────────
+
+    def buy_proxy(self, **kwargs) -> dict:
+        """Purchase a proxy.
+
+        Args:
+            **kwargs:
+                country_id (int): Country ID (required).
+                period (int): Rental period in days (required).
+                num (int): Number of proxies (default: 1).
+                operator (str): Preferred operator.
+                geo_id (int): GEO ID.
+                city_id (int): City ID.
+                coupon_code (str): Discount coupon code.
+                auto_renewal: Enable auto-renewal.
+                proxy_id (int): Extend an existing proxy.
+        """
+        params: Dict[str, Any] = {}
+        mapping = {
+            "country_id": "id_country",
+            "period": "period",
+            "num": "num",
+            "operator": "operator",
+            "geo_id": "geoid",
+            "city_id": "id_city",
+            "coupon_code": "coupons_code",
+            "auto_renewal": "auto_renewal",
+            "proxy_id": "proxy_id",
+        }
+        for py_key, api_key in mapping.items():
+            if py_key in kwargs and kwargs[py_key] is not None:
+                params[api_key] = kwargs[py_key]
+        return self._http.request("buyproxy", "GET", params)
+
+    def refund_proxy(self, proxy_id: int) -> dict:
+        """Refund a proxy.
+
+        Args:
+            proxy_id: Proxy ID.
+        """
+        return self._http.request("refund_proxy", "GET", {"proxy_id": proxy_id})
+
+    def get_balance(self) -> dict:
+        """Get your account balance."""
+        return self._http.request("get_balance")
+
+    def get_prices(self, country_id: int) -> dict:
+        """Get proxy prices for a country.
+
+        Args:
+            country_id: Country ID.
+        """
+        return self._http.request("get_price", "GET", {"id_country": country_id})
+
+    def get_test_proxy(self, geo_id: int, operator: str) -> dict:
+        """Get a free 2-hour test proxy.
+
+        Args:
+            geo_id: GEO ID.
+            operator: Operator name.
+        """
+        return self._http.request(
+            "get_test_proxy", "GET", {"geoid": geo_id, "operator": operator}
+        )
+
+    # ──────────────────────────────────────────────
+    #  Utilities
+    # ──────────────────────────────────────────────
+
+    def check_equipment_availability(self, eid: int) -> dict:
+        """Check if a specific equipment is available.
+
+        Args:
+            eid: Equipment ID.
+        """
+        return self._http.request("eid_avaliable", "GET", {"eid": eid})
+
+    def view_url_from_different_ips(self, url: str, country_id: int) -> dict:
+        """View a URL from different IPs (anti-cloaking tool).
+
+        Args:
+            url: URL to fetch.
+            country_id: Country ID to fetch from.
+        """
+        return self._http.request(
+            "see_the_url_from_different_IPs",
+            "POST",
+            {"url": url, "id_country": country_id},
+        )
+
+    def get_task_result(self, task_id: int) -> dict:
+        """Get the result of an async task.
+
+        Args:
+            task_id: Task ID.
+        """
+        return self._http.request("tasks", "GET", {"tasks_id": task_id})
+
+    # ──────────────────────────────────────────────
+    #  IP Rotation (via changeip.mobileproxy.space)
+    # ──────────────────────────────────────────────
+
+    def change_ip(
+        self,
+        proxy_key: str,
+        *,
+        format: str = "json",
+        user_agent: str = "MobileProxy-Python-SDK/1.0",
+    ) -> dict:
+        """Change proxy IP address using the dedicated rotation endpoint.
+
+        This method uses a separate endpoint with NO rate limit
+        (unlike other API methods).
+
+        Args:
+            proxy_key: Proxy key from your dashboard.
+            format: Response format: 'json' or '0' for plain text.
+            user_agent: Custom User-Agent header.
+        """
+        response = requests.get(
+            "https://changeip.mobileproxy.space/",
+            params={"proxy_key": proxy_key, "format": format},
+            headers={"User-Agent": user_agent},
+            timeout=30,
+        )
+
+        if format == "json":
+            try:
+                return response.json()
+            except ValueError:
+                return {"response": response.text}
+
+        return {"response": response.text}
+
+    # ──────────────────────────────────────────────
+    #  Debug
+    # ──────────────────────────────────────────────
+
+    @property
+    def last_request(self) -> dict:
+        """Get the last HTTP request details (for debugging)."""
+        return self._http.last_request
+
+    @property
+    def last_response(self) -> dict:
+        """Get the last HTTP response details (for debugging)."""
+        return self._http.last_response

mobileproxy_sdk-1.0.0/mobileproxy/exceptions.py

@@ -0,0 +1,23 @@
+"""MobileProxy.Space API exceptions."""
+
+
+class ApiError(Exception):
+    """Base exception for API errors."""
+
+    def __init__(self, message: str, http_code: int = 0, response_body: dict = None):
+        super().__init__(message)
+        self.http_code = http_code
+        self.response_body = response_body
+
+
+class AuthenticationError(ApiError):
+    """Raised when the API token is invalid or missing."""
+    pass
+
+
+class RateLimitError(ApiError):
+    """Raised when the API rate limit is exceeded.
+
+    Limit: 3 × (number of active proxies) requests per second.
+    """
+    pass

mobileproxy_sdk-1.0.0/mobileproxy/http_client.py

@@ -0,0 +1,118 @@
+"""HTTP transport layer for MobileProxy.Space API."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+import requests
+
+from .exceptions import ApiError, AuthenticationError, RateLimitError
+
+
+class HttpClient:
+    """Low-level HTTP client for the MobileProxy.Space API."""
+
+    def __init__(
+        self,
+        api_token: str,
+        base_url: str = "https://mobileproxy.space/api.html",
+        timeout: int = 60,
+    ):
+        self.api_token = api_token
+        self.base_url = base_url
+        self.timeout = timeout
+        self.session = requests.Session()
+        self.session.headers.update(
+            {
+                "Authorization": f"Bearer {api_token}",
+                "Accept": "application/json",
+                "User-Agent": "MobileProxy-Python-SDK/1.0",
+            }
+        )
+        self.last_request: Dict[str, Any] = {}
+        self.last_response: Dict[str, Any] = {}
+
+    def request(
+        self,
+        command: str,
+        method: str = "GET",
+        params: Optional[Dict[str, Any]] = None,
+    ) -> dict:
+        """Execute an API request.
+
+        Args:
+            command: API command name.
+            method: HTTP method (GET or POST).
+            params: Additional query/body parameters.
+
+        Returns:
+            Parsed JSON response.
+
+        Raises:
+            ApiError: On API-level errors.
+            AuthenticationError: On auth failures.
+            RateLimitError: When rate limit is exceeded.
+        """
+        if params is None:
+            params = {}
+        params["command"] = command
+
+        self.last_request = {
+            "command": command,
+            "method": method,
+            "params": params.copy(),
+        }
+
+        try:
+            if method == "POST":
+                response = self.session.post(
+                    self.base_url,
+                    params={"command": command},
+                    data=params,
+                    timeout=self.timeout,
+                )
+            else:
+                response = self.session.get(
+                    self.base_url,
+                    params=params,
+                    timeout=self.timeout,
+                )
+        except requests.exceptions.Timeout:
+            raise ApiError(f"Request timed out after {self.timeout}s")
+        except requests.exceptions.ConnectionError as e:
+            raise ApiError(f"Connection error: {e}")
+        except requests.exceptions.RequestException as e:
+            raise ApiError(f"Request failed: {e}")
+
+        try:
+            json_data = response.json()
+        except ValueError:
+            raise ApiError(
+                f"Invalid JSON response: {response.text[:200]}",
+                http_code=response.status_code,
+            )
+
+        self.last_response = {
+            "http_code": response.status_code,
+            "headers": dict(response.headers),
+            "json": json_data,
+        }
+
+        if "error" in json_data:
+            msg = json_data["error"]
+
+            if response.status_code == 401 or any(
+                w in msg.lower() for w in ("auth", "token")
+            ):
+                raise AuthenticationError(msg, response.status_code, json_data)
+
+            if response.status_code == 429 or "too many requests" in msg.lower():
+                raise RateLimitError(msg, response.status_code, json_data)
+
+            raise ApiError(msg, response.status_code, json_data)
+
+        return json_data
+
+    def close(self):
+        """Close the underlying HTTP session."""
+        self.session.close()

mobileproxy_sdk-1.0.0/mobileproxy_sdk.egg-info/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: mobileproxy-sdk
+Version: 1.0.0
+Summary: Official Python SDK for MobileProxy.Space API — private mobile proxies on real GSM devices
+Author-email: "MobileProxy.Space" <support@mobirox.co.uk>
+License: MIT
+Project-URL: Homepage, https://mobileproxy.space
+Project-URL: Documentation, https://mobileproxy.space/en/user.html?api
+Project-URL: Repository, https://github.com/mobileproxy/python-sdk
+Project-URL: Issues, https://github.com/mobileproxy/python-sdk/issues
+Project-URL: Changelog, https://github.com/mobileproxy/python-sdk/releases
+Keywords: proxy,mobile-proxy,mobileproxy,socks5,http-proxy,scraping,api-client,ip-rotation
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: Topic :: Internet :: Proxy Servers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.20.0
+Provides-Extra: async
+Requires-Dist: httpx>=0.24.0; extra == "async"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Dynamic: license-file
+
+# MobileProxy.Space Python SDK
+
+[![CI](https://github.com/mobileproxy/python-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/mobileproxy/python-sdk/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/mobileproxy-sdk)](https://pypi.org/project/mobileproxy-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/mobileproxy-sdk)](https://pypi.org/project/mobileproxy-sdk/)
+
+Official Python SDK for the [MobileProxy.Space](https://mobileproxy.space) API — private mobile proxies on real GSM devices across 52 countries.
+
+## Features
+
+- **Full API coverage** — all endpoints wrapped in typed, documented methods
+- **Context manager** support (`with Client(...) as client:`)
+- **Typed exceptions** — `ApiError`, `AuthenticationError`, `RateLimitError`
+- **IP rotation** — dedicated `change_ip()` with no rate limit
+- **Python 3.8+** compatible
+- **Type hints** throughout + `py.typed` marker (PEP 561)
+
+## Installation
+
+```bash
+pip install mobileproxy-sdk
+```
+
+## Quick Start
+
+```python
+from mobileproxy import Client
+
+client = Client("YOUR_API_TOKEN")
+
+# Check balance
+balance = client.get_balance()
+print(balance)
+
+# List active proxies
+proxies = client.get_my_proxy()
+
+# Get current IP
+ip = client.get_proxy_ip(12345)
+
+# Rotate IP (no rate limit)
+client.change_ip("your_proxy_key")
+```
+
+### Context Manager
+
+```python
+with Client("YOUR_API_TOKEN") as client:
+    balance = client.get_balance()
+    print(balance)
+# session is closed automatically
+```
+
+## API Methods
+
+### Proxy Information
+
+| Method | Description |
+|--------|-------------|
+| `get_proxy_ip(proxy_id, *, check_spam=)` | Get current IP address of a proxy |
+| `get_my_proxy(proxy_id=)` | List active proxies (all or specific) |
+| `get_ip_stats()` | IP address statistics by GEO |
+
+### Proxy Management
+
+| Method | Description |
+|--------|-------------|
+| `change_proxy_credentials(proxy_id, login, password)` | Change proxy login/password |
+| `reboot_proxy(proxy_id)` | Restart the modem |
+| `edit_proxy(proxy_id, *, reboot_time=, ip_auth=, comment=)` | Update proxy settings |
+| `change_ip(proxy_key, *, format=, user_agent=)` | Rotate IP (no rate limit) |
+
+### Equipment & GEO
+
+| Method | Description |
+|--------|-------------|
+| `change_equipment(proxy_id, **kwargs)` | Switch modem/SIM/operator/city |
+| `get_available_equipment(proxy_id, **kwargs)` | List available equipment by GEO |
+| `get_geo_list(proxy_id, geo_id)` | Available GEOs for a proxy |
+| `get_operators(geo_id)` | Operators for a GEO |
+| `get_countries(only_available=)` | List of countries |
+| `get_cities()` | List of cities |
+
+### Blacklist
+
+| Method | Description |
+|--------|-------------|
+| `get_black_list(proxy_id)` | Get equipment/operator blacklist |
+| `add_operator_to_black_list(proxy_id, operator_id)` | Block an operator |
+| `remove_operator_from_black_list(proxy_id, operator_id)` | Unblock an operator |
+| `remove_from_black_list(proxy_id, black_list_id, eid)` | Remove equipment from blacklist |
+
+### Purchasing & Billing
+
+| Method | Description |
+|--------|-------------|
+| `buy_proxy(**kwargs)` | Purchase a proxy |
+| `refund_proxy(proxy_id)` | Request a refund |
+| `get_balance()` | Account balance |
+| `get_prices(country_id)` | Prices for a country |
+| `get_test_proxy(geo_id, operator)` | Get a free 2-hour trial proxy |
+
+### Utilities
+
+| Method | Description |
+|--------|-------------|
+| `check_equipment_availability(eid)` | Check if equipment is available |
+| `view_url_from_different_ips(url, country_id)` | Anti-cloaking: view URL from another country |
+| `get_task_result(task_id)` | Get async task result |
+
+## Error Handling
+
+```python
+from mobileproxy import Client, ApiError, AuthenticationError, RateLimitError
+
+client = Client("YOUR_API_TOKEN")
+
+try:
+    client.get_balance()
+except AuthenticationError as e:
+    # Invalid API token
+    print(e, e.http_code)
+except RateLimitError as e:
+    # Too many requests — back off and retry
+    # Limit: 3 × (number of active proxies) requests/sec
+    print(e)
+except ApiError as e:
+    print(e.http_code, e.response_body)
+```
+
+## Configuration
+
+```python
+client = Client(
+    "YOUR_API_TOKEN",
+    timeout=120,     # request timeout in seconds
+    base_url="https://mobileproxy.space/api.html",  # default
+)
+```
+
+## Rate Limits
+
+API requests are limited to **3 × (number of active proxies)** per second. For example, 10 proxies = 30 req/s. The `change_ip()` method uses a separate endpoint with **no rate limit**.
+
+## Requirements
+
+- Python 3.8 or higher
+- `requests` library (installed automatically)
+
+## Links
+
+- [API Documentation](https://mobileproxy.space/en/user.html?api)
+- [Dashboard](https://mobileproxy.space/en/user.html)
+- [Website](https://mobileproxy.space)
+- [PHP SDK](https://github.com/mobileproxy/php-sdk)
+- [Node.js SDK](https://github.com/mobileproxy/node-sdk)
+- [Chrome Extension](https://chromewebstore.google.com/detail/mobile-proxy-manager/lhbdhjhflkejgkkhlgacbaogbaaollac)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

mobileproxy_sdk-1.0.0/mobileproxy_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+mobileproxy/__init__.py
+mobileproxy/client.py
+mobileproxy/exceptions.py
+mobileproxy/http_client.py
+mobileproxy/py.typed
+mobileproxy_sdk.egg-info/PKG-INFO
+mobileproxy_sdk.egg-info/SOURCES.txt
+mobileproxy_sdk.egg-info/dependency_links.txt
+mobileproxy_sdk.egg-info/requires.txt
+mobileproxy_sdk.egg-info/top_level.txt
+tests/test_client.py

mobileproxy_sdk-1.0.0/mobileproxy_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mobileproxy_sdk-1.0.0/mobileproxy_sdk.egg-info/requires.txt

@@ -0,0 +1,8 @@
+requests>=2.20.0
+
+[async]
+httpx>=0.24.0
+
+[dev]
+pytest>=7.0
+pytest-asyncio>=0.21

mobileproxy_sdk-1.0.0/mobileproxy_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+mobileproxy

mobileproxy_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mobileproxy-sdk"
+version = "1.0.0"
+description = "Official Python SDK for MobileProxy.Space API — private mobile proxies on real GSM devices"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.8"
+authors = [
+    {name = "MobileProxy.Space", email = "support@mobirox.co.uk"},
+]
+keywords = ["proxy", "mobile-proxy", "mobileproxy", "socks5", "http-proxy", "scraping", "api-client", "ip-rotation"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "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",
+    "Topic :: Internet :: Proxy Servers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "requests>=2.20.0",
+]
+
+[project.optional-dependencies]
+async = ["httpx>=0.24.0"]
+dev = ["pytest>=7.0", "pytest-asyncio>=0.21"]
+
+[project.urls]
+Homepage = "https://mobileproxy.space"
+Documentation = "https://mobileproxy.space/en/user.html?api"
+Repository = "https://github.com/mobileproxy/python-sdk"
+Issues = "https://github.com/mobileproxy/python-sdk/issues"
+Changelog = "https://github.com/mobileproxy/python-sdk/releases"
+
+[tool.setuptools.packages.find]
+include = ["mobileproxy*"]

mobileproxy_sdk-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mobileproxy_sdk-1.0.0/tests/test_client.py

@@ -0,0 +1,86 @@
+"""Tests for the MobileProxy.Space Python SDK."""
+
+import pytest
+
+from mobileproxy import Client, ApiError, AuthenticationError, RateLimitError
+from mobileproxy.http_client import HttpClient
+
+
+class TestClient:
+    def test_instantiate_with_token(self):
+        client = Client("test_token")
+        assert isinstance(client, Client)
+
+    def test_accepts_options(self):
+        client = Client("test_token", base_url="https://custom.api/api.html", timeout=120)
+        assert isinstance(client, Client)
+
+    def test_raises_on_empty_token(self):
+        with pytest.raises(ValueError, match="API token is required"):
+            Client("")
+
+    def test_context_manager(self):
+        with Client("test_token") as client:
+            assert isinstance(client, Client)
+
+    def test_last_request_empty_initially(self):
+        client = Client("test_token")
+        assert client.last_request == {}
+
+    def test_last_response_empty_initially(self):
+        client = Client("test_token")
+        assert client.last_response == {}
+
+
+class TestHttpClient:
+    def test_instantiate_with_defaults(self):
+        http = HttpClient("test_token")
+        assert http.base_url == "https://mobileproxy.space/api.html"
+        assert http.timeout == 60
+
+    def test_custom_base_url_and_timeout(self):
+        http = HttpClient("test_token", base_url="https://custom.api/api.html", timeout=5)
+        assert http.base_url == "https://custom.api/api.html"
+        assert http.timeout == 5
+
+    def test_session_headers(self):
+        http = HttpClient("test_token_123")
+        assert http.session.headers["Authorization"] == "Bearer test_token_123"
+        assert "MobileProxy-Python-SDK" in http.session.headers["User-Agent"]
+
+
+class TestExceptions:
+    def test_api_error_carries_details(self):
+        body = {"error": "Something went wrong"}
+        err = ApiError("Test error", http_code=400, response_body=body)
+        assert str(err) == "Test error"
+        assert err.http_code == 400
+        assert err.response_body == body
+
+    def test_authentication_error_extends_api_error(self):
+        err = AuthenticationError("Invalid token", http_code=401)
+        assert isinstance(err, ApiError)
+        assert err.http_code == 401
+
+    def test_rate_limit_error_extends_api_error(self):
+        err = RateLimitError("Too many requests", http_code=429)
+        assert isinstance(err, ApiError)
+        assert err.http_code == 429
+
+    def test_api_error_defaults(self):
+        err = ApiError("fail")
+        assert err.http_code == 0
+        assert err.response_body is None
+
+
+class TestExports:
+    def test_all_classes_importable(self):
+        from mobileproxy import Client, ApiError, AuthenticationError, RateLimitError
+        assert Client is not None
+        assert ApiError is not None
+        assert AuthenticationError is not None
+        assert RateLimitError is not None
+
+    def test_version(self):
+        import mobileproxy
+        assert mobileproxy.__version__ == "1.0.0"