PyPILanguages & HTTP ClientsMIT
Python proxy SDK
A tiny, dependency-free Python SDK for aethyn.io residential proxies. Build correct proxy URLs with country / city / sticky-session / lifetime targeting and hand them straight to requests, httpx, Playwright, or Selenium — without hand-assembling fragile username strings.
Install
Add proxy-builder-sdk to your project.
Install
pip install proxy-builder-sdkPorts
The SDK picks the correct port from your tier and protocol automatically.
| Tier | HTTP | SOCKS5 |
|---|---|---|
| Premium | 2099 | 1099 |
| Elite | 5499 | 3499 |
White-label? Pass host: "gate.example.com" to the client constructor.
Usage
Copy-paste examples for common patterns.
Quickstart
import requests
from proxy_builder_sdk import AethynClient
client = AethynClient(username="aethyn-XXXXX", password="PASSWORD")
# or set AETHYN_USERNAME / AETHYN_PASSWORD
p = client.proxy(country="us")
r = requests.get("https://api.ipify.org?format=json", proxies=p.proxies)
print(r.json())Sticky sessions
p = client.session(country="de", session="cart42", ttl=10) # same IP for 10 min
# p.username -> "aethyn-XXXXX-country-de-session-cart42-lifetime-10"- ttl is minutes (1–1440).
- Leave session off for per-request rotation (the default).
Elite targeting (city / ISP)
p = client.session(
country="us", city="chicago", isp="comcast",
session="run1", ttl=30, tier="elite",
)
# city, state, isp, and zip are Elite-only — SDK raises a clear error if you pass them on Premiumhttpx
import httpx
p = client.proxy(country="gb")
with httpx.Client(proxy=p.url) as http:
http.get("https://example.com")Playwright
from playwright.sync_api import sync_playwright
p = client.session(country="fr", session="s1", ttl=15, tier="elite")
with sync_playwright() as pw:
browser = pw.chromium.launch(proxy=p.for_playwright())
# ...SOCKS5
p = client.proxy(country="jp", protocol="socks5")
# socks5://...@proxy.aethyn.io:1099Selenium (via SeleniumWire)
# pip install selenium-wire
from seleniumwire import webdriver
p = client.proxy(country="us")
options = {"proxy": {"http": p.url, "https": p.url}}
driver = webdriver.Chrome(seleniumwire_options=options)Return value reference
p = client.session(country="us", session="run1", ttl=10)
p.username # "aethyn-XXXXX-country-us-session-run1-lifetime-10"
p.host, p.port # ("proxy.aethyn.io", 2099)
p.url # "http://aethyn-XXXXX-...:PASSWORD@proxy.aethyn.io:2099"
p.proxies # {"http": ..., "https": ...}
p.for_playwright() # {"server": ..., "username": ..., "password": ...}
str(p) # password-redacted, safe to logOther providers
Aethyn is the default, but the same clean API drives other big residential providers too — use ProxyClient with a provider:
Other providers (ProxyClient)
from proxy_builder_sdk import ProxyClient
# Oxylabs — the SDK emits customer-...-cc-us-sessid-run1-sesstime-10
p = ProxyClient(username="customer-me", password="pw", provider="oxylabs").session(
country="us", session="run1", ttl=10
)| Provider | Gateway | Notes |
|---|---|---|
| aethyn (default) | proxy.aethyn.io | Premium/Elite tiers, city/ISP/state/zip |
| brightdata | brd.superproxy.io | pass brd-customer-<id>-zone-<zone> as the username |
| oxylabs | pr.oxylabs.io | cc/sessid/sesstime; state as us_california |
| smartproxy / decodo | gate.decodo.com | sessionduration (minutes) |
| iproyal | geo.iproyal.com | targeting goes in the password |
| soax | proxy.soax.com | ⚠️ community-verified; lifetime in seconds |
| netnut | gw.netnut.net | country + sticky session only |
Every non-Aethyn dialect was verified against the provider's official docs (each provider file records the source URL and a confidence level). SOAX is medium confidence — sanity-check it against SOAX's current docs before you lean on it. Each provider maps the same semantic call (country, city, state, session, ttl) to its own username/password format and throws a clear error for anything it can't express.
Tips
- Set AETHYN_USERNAME and AETHYN_PASSWORD env vars instead of hardcoding credentials.
- str(p) is safe to log — the password is redacted.
- Self-hosting or white-labeling? Pass host="gate.example.com" to the client constructor.
FAQ
Do I need the SDK to use Aethyn?
No. Aethyn speaks standard username:password@host:port proxy auth. The SDK is optional — it builds correct targeting strings for you so you don't hand-assemble fragile usernames.
Which port does the SDK pick?
Premium HTTP 2099, Premium SOCKS5 1099, Elite HTTP 5499, Elite SOCKS5 3499. The SDK selects the right port from your tier and protocol.
Can I use city or ISP targeting on Premium?
No. city, state, isp, and zip are Elite-only. The SDK validates this and raises a clear error if you pass them on Premium.
What is the ttl range for sticky sessions?
ttl is in minutes, from 1 to 1440. Leave session off for per-request rotation — that is the default when you call client.proxy().
Does it work with Scrapy?
Yes. Build p.url or p.proxies and pass them to Scrapy's proxy middleware. See the Scrapy integration guide for a full example.
Does it support other proxy providers?
Yes. Use ProxyClient with a provider param (oxylabs, brightdata, smartproxy, iproyal, soax, netnut). Aethyn is the default.
Docs, integrations & blog
Python (Requests)Copy-paste proxy config for scripts and notebooks.Scrapy integrationMiddleware-based proxy rotation for crawlers.Integrations hubCopy-paste proxy setup for Python, Node.js, Playwright, Scrapy, and 25+ developer tools.Premium residential proxiesCost-efficient rotating residential pool from €2.00/GB for bulk scraping and monitoring.Elite residential proxiesCurated high-trust pool with city and ISP targeting for hard anti-bot targets.Quickstart docsCredentials, endpoints, and your first proxied request.
License: MIT