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).
