### Install FreeProxy via pip or GitHub

Source: https://github.com/charlespikachu/freeproxy/blob/master/docs/Install.md

Provides commands for installing the package from PyPI or directly from the GitHub repository.

```sh
# from pip
pip install pyfreeproxy
# from github repo method-1
pip install git+https://github.com/CharlesPikachu/freeproxy.git@master
# from github repo method-2
git clone https://github.com/CharlesPikachu/freeproxy.git
cd freeproxy
python setup.py install
```

--------------------------------

### Terminal output example

Source: https://github.com/charlespikachu/freeproxy/blob/master/docs/Quickstart.md

Shows the expected console output after running the proxy scraping script.

```bash
C:\Users\Charles\Desktop>python test.py
KuaidailiProxiedSession >>> adding country_code: 37it [00:05,  6.57it/s]                 | 1/4 [00:18<00:56, 18.95s/it]
100%|████████████████████████████████████████████████████████████████████████████████████| 4/4 [00:28<00:00,  7.17s/it]
The proxy distribution for each source you specified is as follows:
+-----------+-------------------------------+------+-------+--------+--------+------------+-------+-------+
|   Source  |       Retrieved Example       | HTTP | HTTPS | SOCKS4 | SOCKS5 | Chinese IP | Elite | Total |
+-----------+-------------------------------+------+-------+--------+--------+------------+-------+-------+
|  Proxifly |   http://195.231.69.203:443   | 5112 |   0   |  1043  |  477   |     48     |  2157 |  6632 |
| Kuaidaili |   http://113.45.158.25:3128   |  20  |   13  |   0    |   0    |     19     |   33  |   33  |
|  Qiyunip  |   https://114.103.88.18:8089  |  6   |   9   |   0    |   0    |     15     |   14  |   15  |
| Proxylist | socks4://184.181.217.206:4145 | 420  |   59  |  182   |  156   |     54     |  699  |  817  |
+-----------+-------------------------------+------+-------+--------+--------+------------+-------+-------+
```

--------------------------------

### JSON output format

Source: https://github.com/charlespikachu/freeproxy/blob/master/docs/Quickstart.md

Example structure of the generated free_proxies.json file containing the scraped proxy data.

```json
{
  "KuaidailiProxiedSession": [
    {
      "source": "KuaidailiProxiedSession",
      "protocol": "http",
      "ip": "58.216.109.17",
      "port": "800",
      "country_code": "CN",
      "in_chinese_mainland": true,
      "anonymity": "elite",
      "delay": 124,
      "test_timeout": 5,
      "test_url": "http://www.baidu.com",
      "test_headers": {
        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36"
      },
      "failed_connection_default_timeout": 3600000,
      "created_at": "2025-12-03T12:43:25.018208",
      "extra": {}
    }
  ],
  "ProxiflyProxiedSession": [],
  "QiyunipProxiedSession": [],
  "TrustyTechProxiedSession": []
}
```

--------------------------------

### ProxiedSessionClient.get

Source: https://github.com/charlespikachu/freeproxy/blob/master/docs/Quickstart.md

Performs a GET request using an automatically selected proxy from the managed pool.

```APIDOC
## ProxiedSessionClient.get

### Description
Sends a GET request to the specified URL using a proxy from the internal pool.

### Parameters
- **url** (str) - Required - The URL to request.
- **headers** (dict) - Optional - HTTP headers to include in the request.
- **timeout** (int) - Optional - Request timeout in seconds.
```

--------------------------------

### Apply proxy filtering rules

Source: https://github.com/charlespikachu/freeproxy/blob/master/README.md

Examples of applying filter_rule to proxy sessions to constrain results by country, anonymity, protocol, and latency.

```python
from freeproxy.modules.proxies import IP3366ProxiedSession

sess = IP3366ProxiedSession(filter_rule={"country_code": ["CN"]})
sess.refreshproxies()
print(sess.getrandomproxy(proxy_format="freeproxy"))
```

```python
from freeproxy.modules.proxies import SpysoneProxiedSession

sess = SpysoneProxiedSession(filter_rule={"anonymity": ["elite"], "country_code": ["US"]})
sess.refreshproxies()
print(sess.getrandomproxy(proxy_format="freeproxy"))
```

```python
from freeproxy.modules.proxies import FreeproxylistProxiedSession

sess = FreeproxylistProxiedSession(
    filter_rule={
        "protocol": ["http", "https"],
        "max_tcp_ms": 10000,
        "max_http_ms": 10000,
    }
)
sess.refreshproxies()
print(sess.getrandomproxy(proxy_format="freeproxy"))
```

--------------------------------

### Initialize ProxiedSessionClient with minimal configuration

Source: https://github.com/charlespikachu/freeproxy/blob/master/docs/Quickstart.md

Sets up a client using KuaidailiProxiedSession with a filter rule for specific country codes.

```python
from freeproxy.freeproxy import ProxiedSessionClient

proxy_sources = ["KuaidailiProxiedSession"]
init_proxied_session_cfg = {"filter_rule": {"country_code": ["CN", "US"]}}
client = ProxiedSessionClient(
    proxy_sources=proxy_sources, init_proxied_session_cfg=init_proxied_session_cfg,
)
headers = {
    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/98.0.4758.102 Safari/537.36"
}
resp = client.get("https://space.bilibili.com/406756145", headers=headers)
print(resp.text)
```

--------------------------------

### ProxiedSessionClient.__init__

Source: https://github.com/charlespikachu/freeproxy/blob/master/docs/Quickstart.md

Initializes the ProxiedSessionClient with specified proxy sources and configuration settings.

```APIDOC
## ProxiedSessionClient.__init__

### Description
Initializes a new instance of the ProxiedSessionClient to manage proxy-enabled HTTP requests.

### Parameters
- **proxy_sources** (list[str]) - Required - List of proxy source identifiers to use.
- **init_proxied_session_cfg** (dict) - Optional - Configuration dictionary including 'max_pages', 'filter_rule', and standard requests.Session options.
- **disable_print** (bool) - Optional - If set to True, suppresses proxy usage logs.
- **max_tries** (int) - Optional - Maximum number of attempts per request.
```

--------------------------------

### List supported proxy sources via CLI

Source: https://github.com/charlespikachu/freeproxy/blob/master/docs/Quickstart.md

Executes a Python one-liner to print the keys of all registered proxy modules.

```bash
python -c "from freeproxy.modules import ProxiedSessionBuilder; print(ProxiedSessionBuilder.REGISTERED_MODULES.keys())"
```

--------------------------------

### Initialize Proxy Lab UI and Localization

Source: https://github.com/charlespikachu/freeproxy/blob/master/index.html

Updates DOM elements based on the selected language and provides placeholders for proxy testing.

```javascript
document.getElementById("lab-title").textContent = "代理测试实验室"; document.getElementById("lab-badge").textContent = "流程演示 · cURL 示例"; document.getElementById("lab-desc").textContent = "从左侧列表选一个代理，一键生成 curl 命令，并模拟展示请求过程和结果。"; document.getElementById("url-label").textContent = "目标 URL"; document.getElementById("test-url").placeholder = "例如：https://httpbin.org/ip"; document.getElementById("proxy-label").textContent = "选择代理"; document.getElementById("run-text").textContent = "开始模拟测试"; document.getElementById("preview-title").textContent = "cURL 示例（前端不能直接使用代理，请在后端真实执行）"; document.getElementById("log-title").textContent = "请求过程与结果（模拟）"; document.getElementById("lab-tip").textContent = "注意：浏览器 JS 不能像 curl 一样直接用 HTTP 代理。真实测试请在后端实现 /test-proxy 接口，再把结果展示在这里。"; document.getElementById("pikachu-note").textContent = "皮卡丘提示：你可以在服务器上实现一个 /test-proxy 接口，接收 {ip,port,url}，用代理去请求，然后把真实返回结果显示在上面的日志里。"; document.getElementById("pattern-text").textContent = "切换粒子图案"; } else { document.getElementById("title-text").textContent = "Pikachu Proxy Hub"; document.getElementById("subtitle-text").textContent = "Visualize free proxies · Multi-protocol support · Auto-updated by GitHub Actions ⚡"; document.getElementById("lang-flag").textContent = "🇺🇸"; document.getElementById("list-title").textContent = "Live Proxy List"; document.getElementById("list-badge").textContent = "Multi-protocol · Free source"; document.getElementById("list-desc").textContent = "Reads from proxies.json in this repo; proxies.json is periodically updated by a GitHub Actions workflow."; document.getElementById("search-input").placeholder = "Search IP / protocol / location..."; document.getElementById("th-country").textContent = "Country"; document.getElementById("th-ip").textContent = "IP:Port"; document.getElementById("th-proto").textContent = "Protocol(s)"; document.getElementById("th-anon").textContent = "Anonymity"; document.getElementById("th-speed").textContent = "Speed"; document.getElementById("lab-title").textContent = "Proxy Test Lab"; document.getElementById("lab-badge").textContent = "Flow demo · cURL example"; document.getElementById("lab-desc").textContent = "Pick a proxy on the left, auto-generate a curl command and simulate the request flow."; document.getElementById("url-label").textContent = "Target URL"; document.getElementById("test-url").placeholder = "e.g. https://httpbin.org/ip"; document.getElementById("proxy-label").textContent = "Proxy"; document.getElementById("run-text").textContent = "Run simulated test"; document.getElementById("preview-title").textContent = "cURL example (frontend JS cannot directly use HTTP proxies; execute on server side)."; document.getElementById("log-title").textContent = "Request flow & result (simulation)"; document.getElementById("lab-tip").textContent = "Note: browser JS cannot use HTTP proxies like curl. Implement a /test-proxy endpoint on your server and show its results here."; document.getElementById("pikachu-note").textContent = "Pikachu tip: implement /test-proxy on your server to send requests via {ip,port,url} and display the real response above."; document.getElementById("pattern-text").textContent = "Switch particle pattern"; } updateStats(); setUpdateTime(); } document.getElementById("lang-btn").addEventListener("click", () => { currentLang = currentLang === "zh" ? "en" : "zh"; applyLang(); });
```

--------------------------------

### Scrape, summarize, and save proxies

Source: https://github.com/charlespikachu/freeproxy/blob/master/docs/Quickstart.md

Uses BuildProxiedSession to fetch proxies, calculates protocol and anonymity statistics, and exports the data to a JSON file.

```python
import json, random
from tqdm import tqdm
from freeproxy.modules import BaseProxiedSession, ProxyInfo, BuildProxiedSession, printtable, colorize

'''settings'''
SOURCES = ["ProxiflyProxiedSession", "KuaidailiProxiedSession", "QiyunipProxiedSession", "TrustyTechProxiedSession"]
TITLES = ["Source", "Retrieved Example", "HTTP", "HTTPS", "SOCKS4", "SOCKS5", "Chinese IP", "Elite", "Total"]

'''scrape'''
def scrape(src: str) -> list[ProxyInfo]:
    try:
        sess: BaseProxiedSession = BuildProxiedSession({"max_pages": 1, "type": src, "disable_print": False})
        return sess.refreshproxies()
    except Exception:
        return []

'''stats'''
def stats(proxies: list[ProxyInfo]) -> dict:
    return {
        "http":   sum(p.protocol.lower() == "http"   for p in proxies),
        "https":  sum(p.protocol.lower() == "https"  for p in proxies),
        "socks4": sum(p.protocol.lower() == "socks4" for p in proxies),
        "socks5": sum(p.protocol.lower() == "socks5" for p in proxies),
        "cn":     sum(bool(p.in_chinese_mainland) for p in proxies),
        "elite":  sum(p.anonymity.lower() == "elite" for p in proxies),
        "total":  len(proxies),
        "ex":     (random.choice(proxies).proxy if proxies else "NULL"),
    }

'''row'''
def row(src: str, s: dict) -> list:
    ex = colorize(s["ex"], "green") if s["total"] else "NULL"
    return [
        src.removesuffix("ProxiedSession"),
        ex,
        colorize(s["http"], "number"),
        colorize(s["https"], "number"),
        colorize(s["socks4"], "number"),
        colorize(s["socks5"], "number"),
        colorize(s["cn"], "number"),
        colorize(s["elite"], "number"),
        colorize(s["total"], "number"),
    ]

'''main'''
def main():
    free_proxies, items = {}, []
    for src in tqdm(SOURCES):
        proxies = scrape(src)
        items.append(row(src, stats(proxies)))
        free_proxies[src] = [p.todict() for p in proxies]
    print("The proxy distribution for each source you specified is as follows:")
    printtable(titles=TITLES, items=items, terminal_right_space_len=1)
    json.dump(free_proxies, open("free_proxies.json", "w"), indent=2)

'''tests'''
if __name__ == "__main__":
    main()
```

--------------------------------

### Initialize ProxiedSessionClient in quiet mode

Source: https://github.com/charlespikachu/freeproxy/blob/master/docs/Quickstart.md

Disables logging output by setting disable_print to True.

```python
from freeproxy import freeproxy

client = freeproxy.ProxiedSessionClient(
    proxy_sources=["ProxydbProxiedSession"], disable_print=True,
)
```

--------------------------------

### Filter scraped proxies with advanced configuration

Source: https://github.com/charlespikachu/freeproxy/blob/master/docs/Quickstart.md

Configures multiple proxy sources with specific filtering rules for country, anonymity, and protocol.

```python
from freeproxy.freeproxy import ProxiedSessionClient

client = ProxiedSessionClient(
    proxy_sources=["ProxyScrapeProxiedSession", "TrustyTechProxiedSession"],
    init_proxied_session_cfg={
        "max_pages": 2,
        "filter_rule": {
            "country_code": ["CN"],
            "anonymity": ["elite"],
            "protocol": ["http", "https"],
        },
    },
    disable_print=False,
    max_tries=20,
)
headers = {
    'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/143.0.0.0',
}
resp = client.get("https://www.baidu.com/", timeout=10, headers=headers)
print(resp.text)
resp = client.get("https://httpbin.org/ip", timeout=5)
print(resp.json())
resp = client.get("https://httpbin.org/anything", timeout=15)
print(resp.json())
print("origin:", resp.json().get("origin"))
print("X-Forwarded-For:", resp.json()["headers"].get("X-Forwarded-For"))
print("Forwarded:", resp.json()["headers"].get("Forwarded"))
```

--------------------------------

### Render Proxy Data and Filters

Source: https://github.com/charlespikachu/freeproxy/blob/master/index.html

Functions to populate the country filter dropdown and the proxy selection list from the proxies.json API.

```javascript
/***************** 代理数据：只从本仓库的 proxies.json 读取 *****************/
const API_URL = "./proxies.json";

function renderCountryFilter() {
  const sel = document.getElementById("country-filter");
  if (!sel) return;
  const oldVal = sel.value;
  sel.innerHTML = "";
  const optAll = document.createElement("option");
  optAll.value = "";
  optAll.textContent = currentLang === "zh" ? "全部国家" : "All countries";
  sel.appendChild(optAll);
  const set = new Set(allProxies.map(p => p.country).filter(Boolean));
  [...set].sort().forEach(c => {
    const o = document.createElement("option");
    o.value = c;
    o.textContent = c;
    sel.appendChild(o);
  });
  sel.value = oldVal;
}

function fillProxySelect(list) {
  const sel = document.getElementById("proxy-select");
  if (!sel) return;
  sel.innerHTML = "";
  const defaultOpt = document.createElement("option");
  defaultOpt.value = "";
  defaultOpt.textContent = currentLang === "zh" ? "请选择一个代理" : "Choose a proxy";
  sel.appendChild(defaultOpt);
  (list.length ? list : allProxies).slice(0, 200).forEach((p, idx) => {
    const o = document.createElement("option");
    o.value = idx;
    o.textContent = `[${p.country || "-"}] ${p.ip}:${p.port} (${p.protocol})`;
    o.dataset.ip = p.ip;
    o.dataset.port = p.port;
    o.dataset.protocol = p.protocol;
    sel.appendChild(o);
  });
  updatePreviewCmd();
}

function applyFiltersAndRender() {
  const tbody = document.getElementById("proxy-tbody");
  if (!tbody) return;
  tbody.innerHTML = "";
  const keyword = document.getElementById("search-input").value.trim().toLowerCase();
  const country = document.getElementById("country-filter").value;
  const proto =
```

--------------------------------

### Cite FreeProxy in BibTeX

Source: https://github.com/charlespikachu/freeproxy/blob/master/README.md

Use this BibTeX entry to cite the FreeProxy repository in academic or research work.

```bibtex
@misc{freeproxy2022,
    author = {Zhenchao Jin},
    title = {FreeProxy: Collecting free proxies from internet},
    year = {2022},
    publisher = {GitHub},
    journal = {GitHub repository},
    howpublished = {\url{https://github.com/CharlesPikachu/freeproxy}},
}
```

--------------------------------

### ProxiedSessionClient.post

Source: https://github.com/charlespikachu/freeproxy/blob/master/docs/Quickstart.md

Performs a POST request using an automatically selected proxy from the managed pool.

```APIDOC
## ProxiedSessionClient.post

### Description
Sends a POST request to the specified URL using a proxy from the internal pool.

### Parameters
- **url** (str) - Required - The URL to request.
- **data** (dict) - Optional - Data to send in the body of the request.
- **headers** (dict) - Optional - HTTP headers to include in the request.
```

--------------------------------

### Filter proxies by country and anonymity

Source: https://github.com/charlespikachu/freeproxy/blob/master/docs/Quickstart.md

Combines geographic filtering with anonymity level requirements.

```python
from freeproxy.modules.proxies import SpysoneProxiedSession

sess = SpysoneProxiedSession(filter_rule={"anonymity": ["elite"], "country_code": ["US"]})
sess.refreshproxies()
print(sess.getrandomproxy(proxy_format="freeproxy"))
```

--------------------------------

### Filter proxies by protocol and latency

Source: https://github.com/charlespikachu/freeproxy/blob/master/docs/Quickstart.md

Constrains proxies by protocol type and maximum connection latency. Note that high latency constraints can significantly impact crawling performance.

```python
from freeproxy.modules.proxies import FreeproxylistProxiedSession

sess = FreeproxylistProxiedSession(
    filter_rule={
        "protocol": ["http", "https"],
        "max_tcp_ms": 10000,
        "max_http_ms": 10000,
    }
)
sess.refreshproxies()
print(sess.getrandomproxy(proxy_format="freeproxy"))
```

--------------------------------

### Filter proxies by country

Source: https://github.com/charlespikachu/freeproxy/blob/master/docs/Quickstart.md

Restricts proxy results to specific countries using the country_code field.

```python
from freeproxy.modules.proxies import IP3366ProxiedSession

sess = IP3366ProxiedSession(filter_rule={"country_code": ["CN"]})
sess.refreshproxies()
print(sess.getrandomproxy(proxy_format="freeproxy"))
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.