fox-proxy-kit 0.1.1

Библиотека для работы с прокси: проверка IP, геолокации и парсинг прокси из файлов

Proxy Tool Kit

Библиотека для работы с прокси: проверка IP, геолокации и парсинг прокси из файлов.

Установка

pip install proxy-tool-kit

Установка для разработки

git clone <repository-url>
cd proxy-tool-kit

# Создать виртуальное окружение
python -m venv venv
source venv/bin/activate  # На Windows: venv\Scripts\activate

# Установить зависимости
pip install httpx

# Или установить пакет в режиме разработки (включает все зависимости)
pip install -e ".[dev]"

Запуск тестов

pytest

Примеры использования

В папке examples/ находятся демонстрационные примеры:

• basic_usage.py - базовое использование
• check_ip_geo.py - проверка IP и геолокации
• parse_proxies.py - парсинг прокси из файла
• full_example.py - полный пример работы

Запуск примеров:

Вариант 1: Используя виртуальное окружение (рекомендуется)

# Активировать виртуальное окружение
source venv/bin/activate  # На Windows: venv\Scripts\activate

# Запустить пример
python examples/basic_usage.py
python examples/parse_proxies.py
python examples/check_ip_geo.py
python examples/full_example.py

Вариант 2: Используя скрипт-помощник

./run_example.sh basic_usage
./run_example.sh parse_proxies
./run_example.sh check_ip_geo
./run_example.sh full_example

Вариант 3: Установить пакет в режиме разработки

pip install -e ".[dev]"
python examples/basic_usage.py

Основные возможности

• Proxy DTO - класс для работы с прокси с методами проверки IP и геолокации
• ProxyParser - парсинг прокси из файлов с поддержкой различных форматов
• Циклическая очередь - автоматическая ротация прокси при использовании
• Асинхронные запросы - проверка прокси через различные API сервисы
• Поддержка протоколов - HTTP, HTTPS (SOCKS5 требует дополнительных библиотек)

Использование

Создание прокси

from proxy_kit import Proxy

# Прокси без авторизации
proxy = Proxy(protocol="http", host="127.0.0.1", port=8080)

# Прокси с авторизацией
proxy = Proxy(
    protocol="socks5",
    host="127.0.0.1",
    port=1080,
    username="user",
    password="pass"
)

Проверка IP

import asyncio
from proxy_kit import Proxy

async def main():
    proxy = Proxy(protocol="http", host="127.0.0.1", port=8080)
    
    # Проверка IP через случайный API сервис
    info = await proxy.check_ip()
    print(f"IP: {info.ip}")
    
    # Проверка через конкретный URL
    info = await proxy.check_ip(url="https://api.ipify.org?format=json")
    
    # Проверка через список URL (случайный выбор)
    info = await proxy.check_ip(urls=[
        "https://api.ipify.org?format=json",
        "https://api64.ipify.org?format=json"
    ])

asyncio.run(main())

Проверка IP и геолокации

import asyncio
from proxy_kit import Proxy

async def main():
    proxy = Proxy(protocol="http", host="127.0.0.1", port=8080)
    
    # Проверка IP и геолокации
    info = await proxy.check_ip_geo()
    print(f"IP: {info.ip}")
    print(f"Country: {info.country}")
    print(f"City: {info.city}")
    print(f"Geo: {info.geo}")

asyncio.run(main())

Парсинг прокси из файла

from proxy_kit import ProxyParser

parser = ProxyParser()

# Формат: host:port
parser.parse_file("proxies.txt", "{host}:{port}", default_protocol="http")

# Формат: protocol://host:port
parser.parse_file("proxies.txt", "{protocol}://{host}:{port}")

# Формат: host:port:username:password
parser.parse_file("proxies.txt", "{host}:{port}:{username}:{password}", default_protocol="http")

# Формат: protocol://host:port:username:password
parser.parse_file("proxies.txt", "{protocol}://{host}:{port}:{username}:{password}")

# Формат с rotation_url: host:port:rotation_url
parser.parse_file("proxies.txt", "{host}:{port}:{rotation_url}", default_protocol="http")

# Получение прокси (циклическая очередь)
proxy = parser.get_proxy()  # rotate=True по умолчанию

# Получение без ротации
proxy = parser.get_proxy(rotate=False)

Пример файла proxies.txt

# HTTP прокси
127.0.0.1:8080
192.168.1.1:3128

# С авторизацией
user:[e-mail]:8080

# С rotation_url
127.0.0.1:8080:https://api.example.com/rotate

# Разные форматы
http://127.0.0.1:8080
socks5://127.0.0.1:1080:username:password

Ротация прокси

import asyncio
import httpx
from proxy_kit import Proxy

async def rotation_function(**kwargs) -> bool:
    """
    Функция для ротации прокси через rotation_url.
    
    ВАЖНО: Функция ОБЯЗАТЕЛЬНО должна принимать **kwargs!
    
    Функция получает данные прокси через **kwargs:
    - protocol: протокол прокси
    - host: хост прокси
    - port: порт прокси
    - username: имя пользователя (может быть None)
    - password: пароль (может быть None)
    - rotation_url: URL для ротации (может быть None)
    - proxy_url: полный URL прокси
    """
    rotation_url = kwargs.get("rotation_url")
    proxy_url = kwargs.get("proxy_url")
    
    if not rotation_url:
        return False
    
    try:
        async with httpx.AsyncClient(proxy=proxy_url, verify=False) as client:
            response = await client.get(rotation_url)
            return response.status_code == 200
    except:
        return False

async def main():
    # Вариант 1: Функция передана при создании объекта
    proxy = Proxy(
        protocol="http",
        host="127.0.0.1",
        port=8080,
        rotation_url="https://api.example.com/rotate",
        rotation_func=rotation_function  # Функция получит данные через **kwargs
    )
    
    # Выполняем ротацию
    result = await proxy.rotation(delay=2.0, max_retries=3)
    if result:
        print("IP успешно изменен!")
    
    # Вариант 2: Функция передана в метод rotation
    proxy2 = Proxy(
        protocol="http",
        host="127.0.0.1",
        port=8080,
        rotation_url="https://api.example.com/rotate"
    )
    
    result = await proxy2.rotation(rotation_func=rotation_function, delay=2.0, max_retries=3)

asyncio.run(main())

Полный пример

import asyncio
from proxy_kit import ProxyParser

async def main():
    parser = ProxyParser()
    
    # Парсим прокси из файла
    parser.parse_file("proxies.txt", "{host}:{port}", default_protocol="http")
    
    # Проверяем каждый прокси
    for _ in range(len(parser)):
        proxy = parser.get_proxy()  # Циклическая очередь
        
        try:
            info = await proxy.check_ip_geo()
            print(f"Proxy: {proxy.proxy_url}")
            print(f"IP: {info.ip}, Country: {info.country}, City: {info.city}")
        except Exception as e:
            print(f"Ошибка при проверке {proxy.proxy_url}: {e}")

asyncio.run(main())

API Reference

Proxy

Класс для работы с прокси.

Атрибуты

• protocol - протокол (http, https, socks5)
• host - хост прокси
• port - порт прокси
• username - имя пользователя (опционально)
• password - пароль (опционально)
• rotation_url - URL для ротации прокси (опционально)
• rotation_func - асинхронная функция для ротации (опционально)
• proxy_url - полный URL прокси
• info - объект ProxyInfo с результатами проверки

Методы

• async check_ip(url=None, urls=None, timeout=10.0) - проверка IP
• async check_ip_geo(url=None, urls=None, timeout=10.0) - проверка IP и геолокации
• async rotation(rotation_func=None, delay=2.0, max_retries=3) - ротация прокси с проверкой изменения IP

ProxyParser

Класс для парсинга и управления прокси.

Методы

• parse_file(file_path, format_template, default_protocol=None) - парсинг файла
• get_proxy(rotate=True) - получение прокси из списка
• add_proxy(proxy) - добавление прокси
• clear() - очистка списка

ProxyInfo

DTO класс с информацией о прокси.

Атрибуты

• ip - IP адрес
• geo - геолокация (lat,lon)
• city - город
• country - страна
• country_code - код страны
• region - регион
• timezone - часовой пояс
• isp - провайдер
• raw_data - полные данные от API

Примечания

Поддержка SOCKS5

Для работы с SOCKS5 прокси требуется дополнительная библиотека httpx-socks:

pip install httpx-socks

После установки httpx автоматически будет использовать SOCKS5 прокси через httpx-socks.

API сервисы

Библиотека использует бесплатные API сервисы для проверки IP и геолокации. Для избежания лимитов рекомендуется передавать свои URL или списки URL в методы check_ip и check_ip_geo.

Лицензия

MIT