### Install pyfreeproxy

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

Choose one of the three installation methods provided. Ensure you have pip or git installed.

```sh
pip install pyfreeproxy
```

```sh
pip install git+https://github.com/CharlesPikachu/freeproxy.git@master
```

```sh
git clone https://github.com/CharlesPikachu/freeproxy.git
cd freeproxy
python setup.py install
```

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

### Install FreeProxy via pip or source

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

Provides commands for installing the package from PyPI, a direct GitHub URL, or by cloning the 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
```

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

### ProxiedSessionClient Initialization and Usage

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

Demonstrates how to initialize ProxiedSessionClient with specific proxy sources and filter rules, and how to make GET requests.

```APIDOC
## ProxiedSessionClient Initialization and Usage

### Description
This example shows how to create an instance of `ProxiedSessionClient`, configure it with proxy sources and filtering rules, and then use it to make a GET request.

### Method
N/A (This is a client class initialization and usage example)

### Endpoint
N/A

### Parameters
#### Initialization Arguments
- **proxy_sources** (list[str]) - Required - List of proxy source class names to use.
- **init_proxied_session_cfg** (dict) - Optional - Configuration for initializing the session, including:
  - **max_pages** (int) - Optional - Maximum number of pages to fetch per source.
  - **filter_rule** (dict) - Optional - Rules for filtering proxies (e.g., `{"country_code": ["CN", "US"]}`).
  - Plus standard `requests.Session` options.
- **disable_print** (bool) - Optional - If True, suppresses proxy usage logs.
- **max_tries** (int) - Optional - Maximum attempts for each GET/POST call.

### Request Example
```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)
```

### Response
#### Success Response (200)
- **resp.text** (str) - The HTML content of the response.

#### Response Example
(Output will be the HTML content of the requested URL)
```

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

### JSON output format

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

Example structure of the generated free_proxies.json file.

```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": [],
  "ProxylistProxiedSession": []
}
```

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

### Terminal output example

Source: https://github.com/charlespikachu/freeproxy/blob/master/README.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  |
+-----------+-------------------------------+------+-------+--------+--------+------------+-------+-------+
```

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

### Initialize and Use ProxiedSessionClient

Source: https://context7.com/charlespikachu/freeproxy/llms.txt

Initialize `ProxiedSessionClient` with proxy sources and filtering rules. Use it like `requests.Session` for GET and POST requests with automatic proxy rotation. Proxies can be retrieved in different formats or saved to a file.

```python
from freeproxy.freeproxy import ProxiedSessionClient

# Initialize client with multiple proxy sources and filtering rules
client = ProxiedSessionClient(
    proxy_sources=["KuaidailiProxiedSession", "ProxiflyProxiedSession"],
    init_proxied_session_cfg={
        "max_pages": 2,
        "filter_rule": {
            "country_code": ["CN", "US"],
            "anonymity": ["elite"],
            "protocol": ["http", "https"],
        },
    },
    disable_print=False,
    max_tries=20,
)

# Make GET request with automatic proxy rotation
headers = {
    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
}
response = client.get("https://httpbin.org/ip", timeout=10, headers=headers)
print(response.json())
# Output: {"origin": "203.45.67.89"}

# Make POST request
response = client.post(
    "https://httpbin.org/post",
    json={"key": "value"},
    timeout=15
)
print(response.json())

# Get a random proxy without making a request
proxy = client.getrandomproxy(proxy_format="requests")
print(proxy)
# Output: {"http": "http://203.45.67.89:8080", "https": "http://203.45.67.89:8080"}

# Save all collected proxies to JSON file
client.savetojson(save_path="./my_proxies.json")
```

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

### Initialize and use ProxiedSessionClient

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

Basic usage of ProxiedSessionClient to perform a GET request with a filtered proxy pool.

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

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

### Filter Proxies by Protocol and Speed

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

Example of initializing a session with FreeproxylistProxiedSession and applying filters for HTTP/HTTPS protocols and maximum TCP/HTTP latencies.

```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 Anonymity and Country

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

Example of initializing a session with SpysoneProxiedSession and applying filters for elite anonymity and United States country code.

```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 Country Code

Source: https://context7.com/charlespikachu/freeproxy/llms.txt

Example of using `BuildProxiedSession` with a `filter_rule` to retrieve proxies from specific countries.

```python
from freeproxy.modules import BuildProxiedSession

# Filter by country code (ISO 3166-1 alpha-2)
session = BuildProxiedSession({
    "type": "ProxiflyProxiedSession",
    "max_pages": 2,
    "filter_rule": {
        "country_code": ["US", "GB", "DE", "FR"],  # Multiple countries
    }
})
```

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

### Filter Proxies by Country Code

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

Example of initializing a session with IP3366ProxiedSession and applying a filter rule to only include proxies from mainland China.

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

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

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

### Get Selected Proxy Details

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

Retrieves the IP, port, and protocol of the currently selected proxy from the dropdown list.

```javascript
function selectedProxy() {
  const sel = document.getElementById("proxy-select");
  if (!sel) return null;
  const opt = sel.options[sel.selectedIndex];
  if (!opt || !opt.dataset.ip) return null;
  return { ip: opt.dataset.ip, port: opt.dataset.port, protocol: opt.dataset.protocol };
}
```

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

### Create and Use ProxyInfo Object

Source: https://context7.com/charlespikachu/freeproxy/llms.txt

Demonstrates how to manually create a ProxyInfo object, access its properties in different formats, validate its structure, test connection latency, and serialize/deserialize it.

```python
from freeproxy.modules import ProxyInfo

# Create a ProxyInfo manually
proxy = ProxyInfo(
    source="CustomSource",
    protocol="http",
    ip="192.168.1.100",
    port="8080",
    country_code="US",
    anonymity="elite",
    in_chinese_mainland=False,
)

# Get proxy in different formats
print(proxy.proxy)  # Output: http://192.168.1.100:8080
print(proxy.requests_format_proxy)
# Output: {"http": "http://192.168.1.100:8080", "https": "http://192.168.1.100:8080"}

# Validate proxy format
is_valid, error_msg = proxy.selfcheck()
if is_valid:
    print("Proxy is valid")
else:
    print(f"Invalid proxy: {error_msg}")

# Test connection latency
tcp_delay = proxy.tcp_connect_delay  # TCP connect time in ms
http_delay = proxy.http_connect_delay  # HTTP request time in ms
print(f"TCP delay: {tcp_delay}ms, HTTP delay: {http_delay}ms")

# Serialize to/from dictionary
proxy_dict = proxy.todict()
print(proxy_dict)
# Output: {"source": "CustomSource", "protocol": "http", "ip": "192.168.1.100", ...}

# Deserialize from dictionary
restored_proxy = ProxyInfo.fromdict(proxy_dict)
```

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

### List Supported Proxy Sources

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

Use this command to see all proxy sources your current freeproxy version supports. It prints a dictionary of registered module keys.

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

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

### Scrape, summarize, and save proxies

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

Uses BuildProxiedSession to fetch proxies and print a summary table before saving 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", "ProxylistProxiedSession"]
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()
```

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

### List Available Proxy Sources

Source: https://context7.com/charlespikachu/freeproxy/llms.txt

Shows how to use `ProxiedSessionBuilder` to discover and access all registered proxy source modules available in the library.

```python
from freeproxy.modules import ProxiedSessionBuilder

# List all available proxy sources
available_sources = ProxiedSessionBuilder.REGISTERED_MODULES.keys()
print("Available proxy sources:")
for source in available_sources:
    print(f"  - {source}")

# Output:
#   - ProxiflyProxiedSession
#   - FreeproxylistProxiedSession
#   - KuaidailiProxiedSession
#   - ProxyScrapeProxiedSession
#   - GeonodeProxiedSession
#   - ... (30+ sources)

# Get a specific session class
SessionClass = ProxiedSessionBuilder.REGISTERED_MODULES["GeonodeProxiedSession"]
session = SessionClass(max_pages=1)
proxies = session.refreshproxies()
```

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

### Configure ProxiedSessionClient in quiet mode

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

Initialize the client with logging suppressed by setting disable_print to True.

```python
from freeproxy import freeproxy

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

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

### Run Proxy Test

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

Initiates the proxy testing process when the 'Run' button is clicked. It retrieves the selected proxy and test URL, then clears the log box.

```javascript
document.getElementById("run-btn").addEventListener("click", () => {
  const proxy = selectedProxy();
  const url = document.getElementById("test-url").value.trim() || "https://httpbin.org/ip";
  const box = document.getElementById("log-box");
  box.innerHTML
```

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

### Initialize and Set Bar Chart Options with Echarts

Source: https://github.com/charlespikachu/freeproxy/blob/master/examples/ICU996/analysis/点赞用户的邮箱域名统计.html

Initializes an Echarts instance with a 'vintage' theme and 'canvas' renderer, then sets the options for a bar chart displaying email domain statistics. Ensure the target DOM element exists and the Echarts library is loaded.

```javascript
var chart_c07278718a2e47389cd91465b9c0e37a = echarts.init( document.getElementById('c07278718a2e47389cd91465b9c0e37a'), 'vintage', {renderer: 'canvas'}); var option_c07278718a2e47389cd91465b9c0e37a = { "animation": true, "animationThreshold": 2000, "animationDuration": 1000, "animationEasing": "cubicOut", "animationDelay": 0, "animationDurationUpdate": 300, "animationEasingUpdate": "cubicOut", "animationDelayUpdate": 0, "series": [ { "type": "bar", "legendHoverLink": true, "data": [ 4280, 3933, 2006, 583, 519, 382, 330, 120, 112, 75 ], "showBackground": false, "barMinHeight": 0, "barCategoryGap": "20%", "barGap": "30%", "large": false, "largeThreshold": 400, "seriesLayoutBy": "column", "datasetIndex": 0, "clip": true, "zlevel": 0, "z": 2, "label": { "show": true, "position": "top", "margin": 8 } } ], "legend": [ { "data": [ "" ], "selected": { "": true }, "show": true, "left": "2%", "top": "15%", "orient": "vertical", "padding": 5, "itemGap": 10, "itemWidth": 25, "itemHeight": 14 } ], "tooltip": { "show": true, "trigger": "item", "triggerOn": "mousemove|click", "axisPointer": { "type": "line" }, "showContent": true, "alwaysShowContent": false, "showDelay": 0, "hideDelay": 100, "textStyle": { "fontSize": 14 }, "borderWidth": 0, "padding": 5 }, "xAxis": [ { "show": true, "scale": false, "nameLocation": "end", "nameGap": 15, "gridIndex": 0, "axisLabel": { "show": true, "position": "top", "rotate": -25, "margin": 8 }, "inverse": false, "offset": 0, "splitNumber": 5, "minInterval": 0, "splitLine": { "show": false, "lineStyle": { "show": true, "width": 1, "opacity": 1, "curveness": 0, "type": "solid" } }, "data": [ "gmail.com", "qq.com", "163.com", "outlook.com", "126.com", "foxmail.com", "hotmail.com", "sina.com", "live.com", "vip.qq.com" ] } "], "yAxis": [ { "show": true, "scale": false, "nameLocation": "end", "nameGap": 15, "gridIndex": 0, "inverse": false, "offset": 0, "splitNumber": 5, "minInterval": 0, "splitLine": { "show": false, "lineStyle": { "show": true, "width": 1, "opacity": 1, "curveness": 0, "type": "solid" } } } ], "title": [ { "text": "\u70b9\u8d5e\u7528\u6237\u7684\u90ae\u7bb1\u57df\u540d\u7edf\u8ba1", "left": "center", "padding": 5, "itemGap": 10 } ] }; chart_c07278718a2e47389cd91465b9c0e37a.setOption(option_c07278718a2e47389cd91465b9c0e37a);
```

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

### Create Proxy Sessions with BuildProxiedSession Factory

Source: https://context7.com/charlespikachu/freeproxy/llms.txt

Use the `BuildProxiedSession` factory to create individual proxy session instances for specific sources. This allows for direct control over a single proxy source, including refreshing proxies and retrieving them in various formats.

```python
from freeproxy.modules import BuildProxiedSession, ProxyInfo

# Create a session for a specific proxy source
session = BuildProxiedSession({
    "type": "KuaidailiProxiedSession",
    "max_pages": 3,
    "disable_print": False,
    "filter_rule": {
        "country_code": ["CN"],
        "anonymity": ["elite", "anonymous"],
    }
})

# Refresh and fetch proxies from the source
proxies: list[ProxyInfo] = session.refreshproxies()
print(f"Fetched {len(proxies)} proxies")

# Get a random proxy in different formats
proxy_freeproxy = session.getrandomproxy(proxy_format="freeproxy")
print(f"Protocol: {proxy_freeproxy.protocol}")
print(f"IP: {proxy_freeproxy.ip}")
print(f"Port: {proxy_freeproxy.port}")
print(f"Country: {proxy_freeproxy.country_code}")

proxy_requests = session.getrandomproxy(proxy_format="requests")
print(proxy_requests)
# Output: {"http": "http://113.45.158.25:3128", "https": "http://113.45.158.25:3128"}

# Set a random proxy on the session and make a request
session.setrandomproxy()
response = session.get("https://httpbin.org/ip", timeout=10)
print(response.json())
```

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

### Event Listeners for Preview Command

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

Sets up event listeners for input changes on the test URL and selection changes on the proxy dropdown to update the curl command preview.

```javascript
document.getElementById("test-url").addEventListener("input", updatePreviewCmd);
document.getElementById("proxy-select").addEventListener("change", updatePreviewCmd);
```

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

### Initialize Proxy Data API

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

Defines the constant for the proxy data source.

```javascript
const API_URL = "./proxies.json";
```

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

### Create Custom Proxy Source Session

Source: https://context7.com/charlespikachu/freeproxy/llms.txt

Extend the BaseProxiedSession class to implement a custom proxy source. This involves defining the source name, homepage, and overriding the refreshproxies method to fetch and parse proxies from a specific API.

```python
import requests
from freeproxy.modules.proxies import BaseProxiedSession
from freeproxy.modules import filterinvalidproxies, applyfilterrule, ProxyInfo

class MyCustomProxiedSession(BaseProxiedSession):
    source = "MyCustomProxiedSession"
    homepage = "https://example.com/proxy-list"

    def __init__(self, **kwargs):
        super().__init__(**kwargs)

    @applyfilterrule()
    @filterinvalidproxies
    def refreshproxies(self):
        self.candidate_proxies = []

        # Fetch proxies from your custom source
        for page in range(1, self.max_pages + 1):
            try:
                resp = requests.get(
                    f"https://example.com/api/proxies?page={page}",
                    headers=self.getrandomheaders()
                )
                resp.raise_for_status()
                data = resp.json()

                for item in data.get("proxies", []):
                    proxy_info = ProxyInfo(
                        source=self.source,
                        protocol=item["protocol"],
                        ip=item["ip"],
                        port=str(item["port"]),
                        country_code=item.get("country", ""),
                        anonymity=item.get("anonymity", "unknown"),
                    )
                    self.candidate_proxies.append(proxy_info)
            except Exception:
                continue

        return self.candidate_proxies

# Use your custom session
session = MyCustomProxiedSession(
    max_pages=2,
    filter_rule={"protocol": ["http"]}
)
proxies = session.refreshproxies()
```

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

### Advanced ProxiedSessionClient Configuration

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

Illustrates advanced configuration options for ProxiedSessionClient, including multiple proxy sources, detailed filtering, and increased retry attempts.

```APIDOC
## Advanced ProxiedSessionClient Configuration

### Description
This example showcases advanced initialization of `ProxiedSessionClient` with multiple proxy sources, specific filtering rules (country code, anonymity, protocol), a custom number of pages to fetch, and a higher number of retry attempts for requests.

### Method
N/A (This is a client class initialization and usage example)

### Endpoint
N/A

### Parameters
#### Initialization Arguments
- **proxy_sources** (list[str]) - Required - List of proxy source class names (e.g., `["ProxyScrapeProxiedSession", "ProxylistProxiedSession"]`).
- **init_proxied_session_cfg** (dict) - Required - Session configuration:
  - **max_pages** (int) - Optional - Number of pages to fetch per source (default is 1).
  - **filter_rule** (dict) - Optional - Filtering rules:
    - **country_code** (list[str]) - Filter by country codes (e.g., `["CN"]`).
    - **anonymity** (list[str]) - Filter by anonymity level (e.g., `["elite"]`).
    - **protocol** (list[str]) - Filter by protocol (e.g., `["http", "https"]`).
- **disable_print** (bool) - Optional - Set to `True` to suppress logs.
- **max_tries** (int) - Optional - Maximum number of retries for each request (e.g., `20`).

### Request Example
```python
from freeproxy.freeproxy import ProxiedSessionClient

client = ProxiedSessionClient(
    proxy_sources=["ProxyScrapeProxiedSession", "ProxylistProxiedSession"],
    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/537.36',
}
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"))
```

### Response
#### Success Response (200)
- **resp.text** (str) - The HTML content of the response.
- **resp.json()** (dict) - JSON response from httpbin.org endpoints.

#### Response Example
(Output will vary based on the requests made, including HTML content and JSON data from httpbin.org)
```

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

### Execute Proxy Request Simulation

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

Handles proxy validation and executes a multi-step simulated request process with localized logging.

```javascript
= ""; if (!proxy) { setStatus("error"); logLine(currentLang === "zh" ? "\[系统\] 请先选择一个代理。" : "\[system\] Please choose a proxy first."); setTimeout(() => setStatus("idle"), 1000); return; } setStatus("running"); const stepsZh = [ `🧪 \[步骤 1\] 构建请求：目标 URL = ${url}`, `⚡ \[步骤 2\] 通过代理连接：${proxy.ip}:${proxy.port} (${proxy.protocol})`, "📡 \[步骤 3\] 发送 HTTP 请求（模拟）...", "⏱️ \[步骤 4\] 等待响应中（约 300ms）...", "✅ \[步骤 5\] 请求成功（示意数据）：状态码 200。", `📦 \[示例返回体\] {"origin": "${proxy.ip}"}` ]; const stepsEn = [ `🧪 \[Step 1\] Build request: target URL = ${url}`, `⚡ \[Step 2\] Connect via proxy: ${proxy.ip}:${proxy.port} (${proxy.protocol})`, "📡 \[Step 3\] Send HTTP request (simulated)...", "⏱️ \[Step 4\] Waiting for response (~300ms)...", "✅ \[Step 5\] Request succeeded (mock data): status 200.", `📦 \[Sample body\] {"origin": "${proxy.ip}"}` ]; const steps = currentLang === "zh" ? stepsZh : stepsEn; let i = 0; function next() { if (i >= steps.length) { setStatus("idle"); return; } logLine(steps[i++]); setTimeout(next, 420); } next(); });
```

```javascript
/************** 启动：语言 + 加载数据 **************/ applyLang(); loadProxies();
```

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

### Scrape, Summarize, and Save Proxies with FreeProxy

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

This script scrapes proxies from predefined sources, displays their statistics in a formatted table, and saves all retrieved proxies to a JSON file named 'free_proxies.json'. Increase 'max_pages' to fetch more proxies.

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

'''settings'''
SOURCES = ["ProxiflyProxiedSession", "KuaidailiProxiedSession", "QiyunipProxiedSession", "ProxylistProxiedSession"]
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()

```

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

### Direct Usage of Individual Proxy Source Sessions

Source: https://context7.com/charlespikachu/freeproxy/llms.txt

Instantiate individual proxy source session classes directly for granular control. Each session extends `BaseProxiedSession` and supports filtering by country code, protocol, and connection latency.

```python
from freeproxy.modules.proxies import (
    KuaidailiProxiedSession,
    ProxiflyProxiedSession,
    ProxyScrapeProxiedSession,
    GeonodeProxiedSession,
    FreeproxylistProxiedSession,
)

# Use Kuaidaili proxy source (Chinese proxies)
kuaidaili = KuaidailiProxiedSession(
    max_pages=2,
    filter_rule={"country_code": ["CN"]}
)
proxies = kuaidaili.refreshproxies()
print(f"Kuaidaili: {len(proxies)} proxies")

# Use Proxifly for international proxies
proxifly = ProxiflyProxiedSession(
    max_pages=1,
    filter_rule={"protocol": ["socks5"]}
)
proxies = proxifly.refreshproxies()
print(f"Proxifly SOCKS5: {len(proxies)} proxies")

# Use ProxyScrape with speed filtering
proxyscrape = ProxyScrapeProxiedSession(
    max_pages=1,
    filter_rule={
        "protocol": ["http", "https"],
        "max_tcp_ms": 5000,
        "max_http_ms": 10000,
    }
)
proxies = proxyscrape.refreshproxies()
print(f"ProxyScrape fast proxies: {len(proxies)} proxies")
```

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

### ProxiedSessionClient Quiet Mode

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

Shows how to initialize ProxiedSessionClient in quiet mode to suppress logging output.

```APIDOC
## ProxiedSessionClient Quiet Mode

### Description
This example demonstrates how to initialize `ProxiedSessionClient` with the `disable_print` option set to `True` to prevent proxy usage logs from being displayed.

### Method
N/A (This is a client class initialization example)

### Endpoint
N/A

### Parameters
#### Initialization Arguments
- **proxy_sources** (list[str]) - Required - List of proxy source class names to use.
- **disable_print** (bool) - Required - Set to `True` to suppress logs.

### Request Example
```python
from freeproxy import freeproxy

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

### Response
N/A (This snippet focuses on initialization)
```

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

### Create Bar Chart with Vintage Theme

Source: https://github.com/charlespikachu/freeproxy/blob/master/examples/ICU996/analysis/点赞用户都是什么时候注册的.html

Initializes and sets options for a bar chart using the 'vintage' theme and 'canvas' renderer. Configure series data, legend, tooltip, and axes.

```javascript
var chart_383adfddeaa048e4a530beca85e8f952 = echarts.init( document.getElementById('383adfddeaa048e4a530beca85e8f952'), 'vintage', {renderer: 'canvas'}); var option_383adfddeaa048e4a530beca85e8f952 = { "animation": true, "animationThreshold": 2000, "animationDuration": 1000, "animationEasing": "cubicOut", "animationDelay": 0, "animationDurationUpdate": 300, "animationEasingUpdate": "cubicOut", "animationDelayUpdate": 0, "series": [ { "type": "bar", "legendHoverLink": true, "data": [ 22, 67, 236, 651, 1552, 3458, 4750, 7464, 9461, 7016, 4188, 1122 ], "showBackground": false, "barMinHeight": 0, "barCategoryGap": "20%", "barGap": "30%", "large": false, "largeThreshold": 400, "seriesLayoutBy": "column", "datasetIndex": 0, "clip": true, "zlevel": 0, "z": 2, "label": { "show": true, "position": "top", "margin": 8 } } ], "legend": [ { "data": [ "" ], "selected": { "": true }, "show": true, "left": "2%", "top": "15%", "orient": "vertical", "padding": 5, "itemGap": 10, "itemWidth": 25, "itemHeight": 14 } ], "tooltip": { "show": true, "trigger": "item", "triggerOn": "mousemove|click", "axisPointer": { "type": "line" }, "showContent": true, "alwaysShowContent": false, "showDelay": 0, "hideDelay": 100, "textStyle": { "fontSize": 14 }, "borderWidth": 0, "padding": 5 }, "xAxis": [ { "show": true, "scale": false, "nameLocation": "end", "nameGap": 15, "gridIndex": 0, "axisLabel": { "show": true, "position": "top", "rotate": -25, "margin": 8 }, "inverse": false, "offset": 0, "splitNumber": 5, "minInterval": 0, "splitLine": { "show": false, "lineStyle": { "show": true, "width": 1, "opacity": 1, "curveness": 0, "type": "solid" } }, "data": [ "2008", "2009", "2010", "2011", "2012", "2013", "2014", "2015", "2016", "2017", "2018", "2019" ] } ], "yAxis": [ { "show": true, "scale": false, "nameLocation": "end", "nameGap": 15, "gridIndex": 0, "inverse": false, "offset": 0, "splitNumber": 5, "minInterval": 0, "splitLine": { "show": false, "lineStyle": { "show": true, "width": 1, "opacity": 1, "curveness": 0, "type": "solid" } } } ], "title": [ { "text": "\u70b9\u8d5e\u7528\u6237\u90fd\u662f\u4ec0\u4e48\u65f6\u5019\u6ce8\u518c\u7684", "left": "center", "padding": 5, "itemGap": 10 } ] }; chart_383adfddeaa048e4a530beca85e8f952.setOption(option_383adfddeaa048e4a530beca85e8f952);
```

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

### Populate Proxy Selection

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

Fills the proxy selection dropdown with up to 200 entries from the provided list.

```javascript
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();
}
```

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

### Load Proxies from API

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

Fetches proxy data from the API, handles potential errors, and updates the global proxy list. It then triggers the rendering of filters and the proxy table.

```javascript
async function loadProxies() {
  const tbody = document.getElementById("proxy-tbody");
  if (tbody) {
    tbody.innerHTML = `<tr><td colspan="6" style="font-size:12px;">${ currentLang === "zh" ? "正在加载 proxies.json..." : "Loading proxies.json..." }</td></tr>`;
  }
  try {
    const res = await fetch(API_URL, {
      cache: "no-store"
    });
    if (!res.ok) throw new Error("HTTP " + res.status);
    const json = await res.json();
    allProxies = json.data || [];
    lastUpdated = json.updated_at || "";
  } catch (e) {
    console.error("加载 proxies.json 失败：", e);
    allProxies = [];
    lastUpdated = "";
  }
  renderCountryFilter();
  applyFiltersAndRender();
  setUpdateTime();
}
```