# Use Python

> Use Requests with HTTP proxies or socks5h for remote DNS.
>
> Web page: https://ports.io/docs/guides/python/
> Documentation index: https://ports.io/llms.txt

Configure Python Requests with the same proxy for HTTP and HTTPS destinations. The proxy can be HTTP, HTTPS, or SOCKS5 with remote DNS. You need your assigned proxy URL supplied as `PORTS_PROXY_URL` and the full `rp1_...` key supplied as `PORTS_PROXY_KEY`.

## Install Requests

```sh
python -m pip install "requests[socks]"
```

The `socks` extra installs the optional SOCKS dependencies. It also supports the HTTP proxy example below. [Requests SOCKS documentation](https://requests.readthedocs.io/en/latest/user/advanced/#socks).

## Make a request

Set `PORTS_PROXY_URL` to your assigned proxy URL without embedded credentials. Use `http://` or `https://` for an HTTP proxy, or `socks5h://` with the assigned SOCKS hostname and port. Requests' `socks5://` mode resolves destinations locally and sends IP addresses, which this gateway rejects.

The SOCKS port can differ from the HTTPS proxy port. `socks5h://` does not establish TLS to the proxy, so do not reuse a TLS-only proxy port by changing the scheme alone. The destination URL must contain a hostname. This example reads credentials at runtime and encodes them for use inside a proxy URL.

```python
import os
from urllib.parse import quote, urlsplit

import requests

endpoint = urlsplit(os.environ["PORTS_PROXY_URL"])
if endpoint.scheme not in {"http", "https", "socks5h"} or not endpoint.hostname:
    raise ValueError("PORTS_PROXY_URL must use http://, https://, or socks5h://")
if endpoint.scheme == "socks5h" and endpoint.port is None:
    raise ValueError("Include the assigned SOCKS proxy port in PORTS_PROXY_URL")
password = quote(os.environ["PORTS_PROXY_KEY"], safe="")
username = "v1_rotate"
proxy = f"{endpoint.scheme}://{quote(username, safe='')}:{password}@{endpoint.netloc}"

response = requests.get(
    "https://example.com/",
    proxies={"http": proxy, "https": proxy},
    timeout=(10, 30),
)
response.raise_for_status()
print(response.status_code)
print(response.text)
```

The dictionary keys identify destination URL schemes, so they remain `http` and `https` when both values contain a `socks5h://` proxy URL. For SOCKS5, Requests sends the hostname for the exit to resolve; for an HTTP proxy and HTTPS destination, it establishes an HTTP CONNECT tunnel. TLS to the HTTPS destination is then negotiated through either tunnel. An `https://` HTTP proxy URL also encrypts the connection to the proxy. Passing `proxies` per request makes the intended configuration explicit. [Requests proxy documentation](https://requests.readthedocs.io/en/latest/user/advanced/#proxies).

`timeout=(10, 30)` sets connect and read timeouts in seconds; it is not a total download deadline. `raise_for_status()` raises for an unsuccessful destination HTTP status. [Requests API](https://requests.readthedocs.io/en/latest/api/#requests.request).

Keep TLS verification enabled and avoid logging the proxy URL.

## Target a country or reuse a route

Replace the username in the example with a routing policy:

```python
# Eligible United States exits.
username = "v1_rotate_countries_US"

# Related connections use the same sticky session.
username = "v1_sticky_session_job-42_countries_US"

# The session does not fail over to another exit.
username = "v1_fixed_session_job-42_countries_US"
```

Rebuild the proxy URL after changing the username. See [routing](https://ports.io/docs/reference/username-reference.md) and [sessions](https://ports.io/docs/reference/sessions.md) for filter and failover behavior.

## Understand connection reuse

A Requests `Session` can reuse established connections through HTTP or SOCKS5 proxies. `v1_rotate` selects an exit when a new tunnel opens, so several requests sent through one existing tunnel do not trigger a new exit selection. A rotation can also select the same eligible exit again. [Requests session documentation](https://requests.readthedocs.io/en/latest/user/advanced/#session-objects).

Treat a Requests session, a proxy routing session ID, and destination cookies as separate concepts. A routing session controls exit selection; it does not manage your application's cookies.