proxyproviders 0.1.1__tar.gz → 0.2.0__tar.gz

{proxyproviders-0.1.1 → proxyproviders-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: proxyproviders
-Version: 0.1.1
+Version: 0.2.0
 Summary: A unified interface for different proxy providers
 License: MIT License
          
@@ -23,6 +23,7 @@ License: MIT License
          LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
          OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
          SOFTWARE.
+License-File: LICENSE
 Author: David Teather
 Author-email: contact.davidteather@gmail.com
 Requires-Python: >=3.9
@@ -45,7 +46,7 @@ Description-Content-Type: text/markdown
 
 The Unified Python Proxy API for managing proxies with support for BrightData, WebShare, and more.
 
-[![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white&style=flat-square)](https://www.linkedin.com/in/davidteather/) [![Sponsor Me](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/davidteather) [![GitHub release (latest by date)](https://img.shields.io/github/v/release/davidteather/proxyproviders)](https://github.com/davidteather/proxyproviders/releases) [![GitHub](https://img.shields.io/github/license/davidteather/proxyproviders)](https://github.com/davidteather/proxyproviders/blob/main/LICENSE) [![Downloads](https://pepy.tech/badge/proxyproviders)](https://pypi.org/project/proxyproviders/) ![](https://visitor-badge.laobi.icu/badge?page_id=davidteather.proxyproviders) [![Support Server](https://img.shields.io/discord/783108952111579166.svg?color=7289da&logo=discord&style=flat-square)](https://discord.gg/yyPhbfma6f)
+ [![codecov](https://codecov.io/gh/davidteather/proxyproviders/graph/badge.svg?token=MZF0KP7YMA)](https://codecov.io/gh/davidteather/proxyproviders) [![Sponsor Me](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/davidteather) [![GitHub release (latest by date)](https://img.shields.io/github/v/release/davidteather/proxyproviders)](https://github.com/davidteather/proxyproviders/releases) [![GitHub](https://img.shields.io/github/license/davidteather/proxyproviders)](https://github.com/davidteather/proxyproviders/blob/main/LICENSE) [![Downloads](https://pepy.tech/badge/proxyproviders)](https://pypi.org/project/proxyproviders/) ![](https://visitor-badge.laobi.icu/badge?page_id=davidteather.proxyproviders) [![Support Server](https://img.shields.io/discord/783108952111579166.svg?color=7289da&logo=discord&style=flat-square)](https://discord.gg/yyPhbfma6f) [![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white&style=flat-square)](https://www.linkedin.com/in/davidteather/)
 
 ## Table of Contents
 
@@ -105,6 +106,24 @@ proxies = proxy_provider.list_proxies()
 print(proxies)
 ```
 
+For simple usage, you can get a proxy and use it immediately:
+```py
+from proxyproviders import Webshare
+import requests
+
+provider = Webshare(api_key="your-api-key")
+
+# Get a proxy (uses RoundRobin by default) and use it with requests
+from proxyproviders.models.proxy import ProxyFormat
+
+proxy = provider.get_proxy()
+response = requests.get("https://httpbin.org/ip", proxies=proxy.format(ProxyFormat.REQUESTS))
+print(response.json())
+
+# Or in one-line
+response = requests.get("https://httpbin.org/ip", proxies=provider.get_proxy().format(ProxyFormat.REQUESTS))
+```
+
 Each provider has their own custom options, the `Webshare` class lets you specify url params according to their [api spec](https://apidocs.webshare.io/proxy-list/list#parameters), here's an example which will only return proxies that are based in the US.
 
 ```py
@@ -150,32 +169,86 @@ some_function(brightdata)
 
 Here's a more meaningful example that takes the `Proxy` class and uses it to create a python requests http proxy.
 
+#### Simple Usage
 ```py
-from proxyproviders import Webshare, BrightData, ProxyProvider
+from proxyproviders import Webshare
+from proxyproviders.algorithms import Random, RoundRobin
+from proxyproviders.models.proxy import ProxyFormat
 import requests
-import os
 
+provider = Webshare(api_key="your_api_key")
 
-def request_with_proxy(provider: ProxyProvider):
-    requests_proxy = None
+# Get proxy using default RoundRobin and make request
+proxy = provider.get_proxy()
+response = requests.get("https://httpbin.org/ip", proxies=proxy.format(ProxyFormat.REQUESTS))
 
-    if provider:
-        proxies = provider.list_proxies()
+# Or in one-line
+response = requests.get("https://httpbin.org/ip", proxies=provider.get_proxy().format(ProxyFormat.REQUESTS))
+```
 
-        requests_proxy = {
-            "http": f"http://{proxies[0].username}:{proxies[0].password}@{proxies[0].proxy_address}:{proxies[0].port}",
-            "https": f"http://{proxies[0].username}:{proxies[0].password}@{proxies[0].proxy_address}:{proxies[0].port}",
-        }
+#### Built-in Algorithms
+```py
+from proxyproviders import Webshare
+from proxyproviders.algorithms import Random, RoundRobin, First
 
-    r = requests.get("https://httpbin.org/ip", proxies=requests_proxy)
-    return r.json()
+provider = Webshare(api_key="your_api_key")
 
-webshare = Webshare(api_key="your_api_key")
-brightdata = BrightData(api_key="your_api_key", zone="your_zone")
+# Default: RoundRobin (cycles through proxies for load balancing)
+proxy = provider.get_proxy()
 
-print(f"Your IP: {request_with_proxy(None)}")
-print(f"Webshare: {request_with_proxy(webshare)}")
-print(f"BrightData: {request_with_proxy(brightdata)}")
+# Random selection
+proxy = provider.get_proxy(Random())
+
+# Always first proxy (deterministic)
+proxy = provider.get_proxy(First())
+
+# Algorithm can maintain state when reused
+round_robin = RoundRobin()
+proxy1 = provider.get_proxy(round_robin)
+proxy2 = provider.get_proxy(round_robin)  # Next in sequence
+```
+
+#### Algorithm State Management
+```py
+from proxyproviders import Webshare
+from proxyproviders.algorithms import RoundRobin, Random
+
+provider = Webshare(api_key="your_api_key")
+
+# Create reusable algorithm for state management
+round_robin = RoundRobin()  # Maintains state across calls
+random_algo = Random()      # Stateless but reusable
+
+# Each call to round_robin will cycle to next proxy
+for i in range(3):
+    proxy = provider.get_proxy(round_robin)
+    print(f"RoundRobin {i}: {proxy.proxy_address}")
+
+# Provider also maintains its own default RoundRobin state when not specified
+for i in range(3):
+    proxy = provider.get_proxy()  # Uses provider's default RoundRobin
+    print(f"Default {i}: {proxy.proxy_address}")
+```
+
+#### Custom Algorithms
+```py
+from proxyproviders.algorithms import Algorithm
+from typing import List
+from proxyproviders.models.proxy import Proxy
+
+class USProxyAlgorithm(Algorithm):
+    """Prefers US proxies, falls back to first available."""
+
+    def select(self, proxies: List[Proxy]) -> Proxy:
+        # Try to find a US proxy
+        for proxy in proxies:
+            if proxy.country_code == "US":
+                return proxy
+        # Fall back to first proxy
+        return proxies[0]
+
+# Use your custom algorithm
+proxy = provider.get_proxy(USProxyAlgorithm())
 ```
 
 ### Making Your Own Proxy Provider

{proxyproviders-0.1.1 → proxyproviders-0.2.0}/README.md

@@ -2,7 +2,7 @@
 
 The Unified Python Proxy API for managing proxies with support for BrightData, WebShare, and more.
 
-[![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white&style=flat-square)](https://www.linkedin.com/in/davidteather/) [![Sponsor Me](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/davidteather) [![GitHub release (latest by date)](https://img.shields.io/github/v/release/davidteather/proxyproviders)](https://github.com/davidteather/proxyproviders/releases) [![GitHub](https://img.shields.io/github/license/davidteather/proxyproviders)](https://github.com/davidteather/proxyproviders/blob/main/LICENSE) [![Downloads](https://pepy.tech/badge/proxyproviders)](https://pypi.org/project/proxyproviders/) ![](https://visitor-badge.laobi.icu/badge?page_id=davidteather.proxyproviders) [![Support Server](https://img.shields.io/discord/783108952111579166.svg?color=7289da&logo=discord&style=flat-square)](https://discord.gg/yyPhbfma6f)
+ [![codecov](https://codecov.io/gh/davidteather/proxyproviders/graph/badge.svg?token=MZF0KP7YMA)](https://codecov.io/gh/davidteather/proxyproviders) [![Sponsor Me](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/davidteather) [![GitHub release (latest by date)](https://img.shields.io/github/v/release/davidteather/proxyproviders)](https://github.com/davidteather/proxyproviders/releases) [![GitHub](https://img.shields.io/github/license/davidteather/proxyproviders)](https://github.com/davidteather/proxyproviders/blob/main/LICENSE) [![Downloads](https://pepy.tech/badge/proxyproviders)](https://pypi.org/project/proxyproviders/) ![](https://visitor-badge.laobi.icu/badge?page_id=davidteather.proxyproviders) [![Support Server](https://img.shields.io/discord/783108952111579166.svg?color=7289da&logo=discord&style=flat-square)](https://discord.gg/yyPhbfma6f) [![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white&style=flat-square)](https://www.linkedin.com/in/davidteather/)
 
 ## Table of Contents
 
@@ -62,6 +62,24 @@ proxies = proxy_provider.list_proxies()
 print(proxies)
 ```
 
+For simple usage, you can get a proxy and use it immediately:
+```py
+from proxyproviders import Webshare
+import requests
+
+provider = Webshare(api_key="your-api-key")
+
+# Get a proxy (uses RoundRobin by default) and use it with requests
+from proxyproviders.models.proxy import ProxyFormat
+
+proxy = provider.get_proxy()
+response = requests.get("https://httpbin.org/ip", proxies=proxy.format(ProxyFormat.REQUESTS))
+print(response.json())
+
+# Or in one-line
+response = requests.get("https://httpbin.org/ip", proxies=provider.get_proxy().format(ProxyFormat.REQUESTS))
+```
+
 Each provider has their own custom options, the `Webshare` class lets you specify url params according to their [api spec](https://apidocs.webshare.io/proxy-list/list#parameters), here's an example which will only return proxies that are based in the US.
 
 ```py
@@ -107,32 +125,86 @@ some_function(brightdata)
 
 Here's a more meaningful example that takes the `Proxy` class and uses it to create a python requests http proxy.
 
+#### Simple Usage
 ```py
-from proxyproviders import Webshare, BrightData, ProxyProvider
+from proxyproviders import Webshare
+from proxyproviders.algorithms import Random, RoundRobin
+from proxyproviders.models.proxy import ProxyFormat
 import requests
-import os
 
+provider = Webshare(api_key="your_api_key")
 
-def request_with_proxy(provider: ProxyProvider):
-    requests_proxy = None
+# Get proxy using default RoundRobin and make request
+proxy = provider.get_proxy()
+response = requests.get("https://httpbin.org/ip", proxies=proxy.format(ProxyFormat.REQUESTS))
 
-    if provider:
-        proxies = provider.list_proxies()
+# Or in one-line
+response = requests.get("https://httpbin.org/ip", proxies=provider.get_proxy().format(ProxyFormat.REQUESTS))
+```
 
-        requests_proxy = {
-            "http": f"http://{proxies[0].username}:{proxies[0].password}@{proxies[0].proxy_address}:{proxies[0].port}",
-            "https": f"http://{proxies[0].username}:{proxies[0].password}@{proxies[0].proxy_address}:{proxies[0].port}",
-        }
+#### Built-in Algorithms
+```py
+from proxyproviders import Webshare
+from proxyproviders.algorithms import Random, RoundRobin, First
 
-    r = requests.get("https://httpbin.org/ip", proxies=requests_proxy)
-    return r.json()
+provider = Webshare(api_key="your_api_key")
 
-webshare = Webshare(api_key="your_api_key")
-brightdata = BrightData(api_key="your_api_key", zone="your_zone")
+# Default: RoundRobin (cycles through proxies for load balancing)
+proxy = provider.get_proxy()
 
-print(f"Your IP: {request_with_proxy(None)}")
-print(f"Webshare: {request_with_proxy(webshare)}")
-print(f"BrightData: {request_with_proxy(brightdata)}")
+# Random selection
+proxy = provider.get_proxy(Random())
+
+# Always first proxy (deterministic)
+proxy = provider.get_proxy(First())
+
+# Algorithm can maintain state when reused
+round_robin = RoundRobin()
+proxy1 = provider.get_proxy(round_robin)
+proxy2 = provider.get_proxy(round_robin)  # Next in sequence
+```
+
+#### Algorithm State Management
+```py
+from proxyproviders import Webshare
+from proxyproviders.algorithms import RoundRobin, Random
+
+provider = Webshare(api_key="your_api_key")
+
+# Create reusable algorithm for state management
+round_robin = RoundRobin()  # Maintains state across calls
+random_algo = Random()      # Stateless but reusable
+
+# Each call to round_robin will cycle to next proxy
+for i in range(3):
+    proxy = provider.get_proxy(round_robin)
+    print(f"RoundRobin {i}: {proxy.proxy_address}")
+
+# Provider also maintains its own default RoundRobin state when not specified
+for i in range(3):
+    proxy = provider.get_proxy()  # Uses provider's default RoundRobin
+    print(f"Default {i}: {proxy.proxy_address}")
+```
+
+#### Custom Algorithms
+```py
+from proxyproviders.algorithms import Algorithm
+from typing import List
+from proxyproviders.models.proxy import Proxy
+
+class USProxyAlgorithm(Algorithm):
+    """Prefers US proxies, falls back to first available."""
+
+    def select(self, proxies: List[Proxy]) -> Proxy:
+        # Try to find a US proxy
+        for proxy in proxies:
+            if proxy.country_code == "US":
+                return proxy
+        # Fall back to first proxy
+        return proxies[0]
+
+# Use your custom algorithm
+proxy = provider.get_proxy(USProxyAlgorithm())
 ```
 
 ### Making Your Own Proxy Provider

proxyproviders-0.2.0/proxyproviders/__init__.py

@@ -0,0 +1,14 @@
+from . import algorithms
+from .models.proxy import Proxy
+from .providers.brightdata import BrightData
+from .providers.webshare import Webshare
+from .proxy_provider import ProxyConfig, ProxyProvider
+
+__all__ = [
+    "ProxyProvider",
+    "ProxyConfig",
+    "Proxy",
+    "Webshare",
+    "BrightData",
+    "algorithms",
+]

proxyproviders-0.2.0/proxyproviders/algorithms.py

@@ -0,0 +1,112 @@
+"""Selection algorithms for choosing proxies from a provider."""
+
+import random
+import threading
+from abc import ABC, abstractmethod
+from typing import Dict, List
+
+from .models.proxy import Proxy
+
+
+class Algorithm(ABC):
+    """Base class for proxy selection algorithms.
+
+    Users can extend this class to create custom proxy selection logic.
+
+    Example:
+        >>> class MyAlgorithm(Algorithm):
+        ...     def select(self, proxies):
+        ...         return proxies[0]  # Always return first proxy
+        ...
+        >>> algorithm = MyAlgorithm()
+        >>> proxy = provider.get_proxy(algorithm)
+    """
+
+    @abstractmethod
+    def select(self, proxies: List[Proxy]) -> Proxy:
+        """Select a proxy from the list.
+
+        :param proxies: List of available proxies
+        :return: Selected proxy
+        :raises ValueError: If proxy list is empty
+        """
+        pass
+
+
+class Random(Algorithm):
+    """Random proxy selection algorithm.
+
+    Selects a random proxy from the available list on each call.
+
+    Example:
+        >>> algorithm = Random()
+        >>> proxy = provider.get_proxy(algorithm)
+    """
+
+    def select(self, proxies: List[Proxy]) -> Proxy:
+        """Select a random proxy from the list.
+
+        :param proxies: List of available proxies
+        :return: Randomly selected proxy
+        :raises ValueError: If proxy list is empty
+        """
+        if not proxies:
+            raise ValueError("Cannot select from empty proxy list")
+        return random.choice(proxies)
+
+
+class RoundRobin(Algorithm):
+    """Round-robin proxy selection algorithm with state tracking.
+
+    Cycles through proxies in order, maintaining state across calls.
+    Each RoundRobin instance maintains its own independent state.
+
+    Example:
+        >>> algorithm = RoundRobin()
+        >>> proxy1 = provider.get_proxy(algorithm)
+        >>> proxy2 = provider.get_proxy(algorithm)  # Next proxy in sequence
+    """
+
+    def __init__(self):
+        """Initialize round-robin algorithm with state tracking."""
+        self._current_index = 0
+        self._lock = threading.Lock()
+
+    def select(self, proxies: List[Proxy]) -> Proxy:
+        """Select next proxy in round-robin sequence.
+
+        :param proxies: List of available proxies
+        :return: Next proxy in round-robin sequence
+        :raises ValueError: If proxy list is empty
+        """
+        if not proxies:
+            raise ValueError("Cannot select from empty proxy list")
+
+        with self._lock:
+            selected_proxy = proxies[self._current_index % len(proxies)]
+            self._current_index = (self._current_index + 1) % len(proxies)
+
+        return selected_proxy
+
+
+class First(Algorithm):
+    """First proxy selection algorithm.
+
+    Always selects the first proxy from the list.
+    Useful for deterministic behavior or when proxies are pre-sorted.
+
+    Example:
+        >>> algorithm = First()
+        >>> proxy = provider.get_proxy(algorithm)  # Always first proxy
+    """
+
+    def select(self, proxies: List[Proxy]) -> Proxy:
+        """Select the first proxy from the list.
+
+        :param proxies: List of available proxies
+        :return: First proxy in the list
+        :raises ValueError: If proxy list is empty
+        """
+        if not proxies:
+            raise ValueError("Cannot select from empty proxy list")
+        return proxies[0]

proxyproviders-0.2.0/proxyproviders/models/proxy.py

@@ -0,0 +1,118 @@
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import Dict, List, Optional, Union
+
+
+class ProxyFormat(Enum):
+    """Supported proxy output formats."""
+
+    REQUESTS = "requests"
+    """Requests format, for use in requests library HTTP calls"""
+
+    CURL = "curl"
+    """CURL format, for use in curl commands"""
+
+    HTTPX = "httpx"
+    """HTTPX format, for use in httpx library HTTP calls"""
+
+    AIOHTTP = "aiohttp"
+    """AIOHTTP format, for use in aiohttp library HTTP calls"""
+
+    URL = "url"
+    """URL format, for use in URL strings"""
+
+
+@dataclass
+class Proxy:
+    """Our shared data model for a proxy object across all providers."""
+
+    id: str
+    """A unique identifier for the proxy"""
+
+    username: str
+    """The username required for authenticating with the proxy"""
+
+    password: str
+    """The password required for authenticating with the proxy"""
+
+    proxy_address: str
+    """The IP address or domain name of the proxy"""
+
+    port: int
+    """The port number through which the proxy connection is established"""
+
+    country_code: Optional[str] = None
+    """The country code where the proxy is located, e.g., 'US', 'FR'. Optional"""
+
+    city_name: Optional[str] = None
+    """The city name where the proxy is located, e.g., 'New York', 'Paris'. Optional"""
+
+    created_at: Optional[datetime] = None
+    """The timestamp when the proxy was created. Optional"""
+
+    protocols: Optional[List[str]] = None
+    """A list of connection protocols supported by the proxy, e.g., ['http', 'https']"""
+
+    def to_url(self, protocol: str = "http") -> str:
+        """Convert proxy to URL format for use with HTTP clients.
+
+        :param protocol: The protocol to use in the URL (default: 'http')
+        :return: Proxy URL in format 'protocol://username:password@host:port'
+
+        Example:
+            >>> proxy.to_url()
+            'http://user:pass@192.168.1.1:8080'
+            >>> proxy.to_url('https')
+            'https://user:pass@192.168.1.1:8080'
+        """
+        return f"{protocol}://{self.username}:{self.password}@{self.proxy_address}:{self.port}"
+
+    def format(
+        self, format_type: Union[ProxyFormat, str] = ProxyFormat.URL, **kwargs
+    ) -> Union[str, Dict[str, str], List[str]]:
+        """Format proxy for different HTTP clients and tools.
+
+        :param format_type: Output format (default: URL string)
+        :param kwargs: Format-specific options
+        :return: Formatted proxy data
+
+        Examples:
+            >>> proxy.format()  # Default URL string
+            'http://user:pass@192.168.1.1:8080'
+
+            >>> proxy.format(ProxyFormat.REQUESTS)
+            {'http': 'http://user:pass@192.168.1.1:8080', 'https': 'http://user:pass@192.168.1.1:8080'}
+
+            >>> proxy.format('curl')  # String also works
+            ['-x', 'http://user:pass@192.168.1.1:8080']
+
+            >>> proxy.format(ProxyFormat.HTTPX)
+            {'http://': 'http://user:pass@192.168.1.1:8080', 'https://': 'http://user:pass@192.168.1.1:8080'}
+        """
+        if isinstance(format_type, str):
+            format_type = ProxyFormat(format_type)
+
+        if format_type == ProxyFormat.URL:
+            protocol = kwargs.get("protocol", "http")
+            return self.to_url(protocol)
+
+        elif format_type == ProxyFormat.REQUESTS:
+            protocols = kwargs.get("protocols", self.protocols or ["http", "https"])
+            proxy_url = self.to_url("http")
+            return {protocol: proxy_url for protocol in protocols}
+
+        elif format_type == ProxyFormat.CURL:
+            return ["-x", self.to_url("http")]
+
+        elif format_type == ProxyFormat.HTTPX:
+            # httpx uses 'http://' and 'https://' as keys
+            proxy_url = self.to_url("http")
+            return {"http://": proxy_url, "https://": proxy_url}
+
+        elif format_type == ProxyFormat.AIOHTTP:
+            # aiohttp takes a single URL string
+            return self.to_url("http")
+
+        else:
+            raise ValueError(f"Unsupported format: {format_type}")

{proxyproviders-0.1.1 → proxyproviders-0.2.0}/proxyproviders/providers/brightdata.py

@@ -1,9 +1,10 @@
+from typing import Dict, List, Optional
+
 import requests
-from typing import List, Dict, Optional
-from ..proxy_provider import ProxyProvider, ProxyConfig
+
 from ..exceptions import ProxyFetchException, ProxyInvalidResponseException
 from ..models.proxy import Proxy
-import threading
+from ..proxy_provider import ProxyConfig, ProxyProvider
 
 
 class BrightData(ProxyProvider):

{proxyproviders-0.1.1 → proxyproviders-0.2.0}/proxyproviders/providers/webshare.py

@@ -1,13 +1,15 @@
-import requests
 from datetime import datetime
-from typing import List, Dict, Optional
-from ..proxy_provider import ProxyProvider, ProxyConfig
+from typing import Dict, List, Optional
+
+import requests
+
 from ..exceptions import (
-    ProxyFetchException,
     ProxyConversionException,
+    ProxyFetchException,
     ProxyInvalidResponseException,
 )
 from ..models.proxy import Proxy
+from ..proxy_provider import ProxyConfig, ProxyProvider
 
 
 class Webshare(ProxyProvider):
@@ -85,7 +87,7 @@ class Webshare(ProxyProvider):
             data = response.json()
 
             proxy_data = data.get("results")
-            if not proxy_data:
+            if proxy_data is None:
                 raise ProxyInvalidResponseException(response.text)
 
             all_proxies.extend([self._convert_to_proxy(proxy) for proxy in proxy_data])

{proxyproviders-0.1.1 → proxyproviders-0.2.0}/proxyproviders/proxy_provider.py

@@ -1,9 +1,13 @@
+import threading
 from abc import ABC, abstractmethod
+from dataclasses import dataclass
 from datetime import datetime
-from typing import List, Optional
+from typing import TYPE_CHECKING, List, Optional
+
 from .models.proxy import Proxy
-from dataclasses import dataclass
-import threading
+
+if TYPE_CHECKING:
+    from .algorithms import Algorithm
 
 
 @dataclass
@@ -44,6 +48,11 @@ class ProxyProvider(ABC):
         self._last_refresh: Optional[datetime] = None
         self._lock = threading.Lock()
 
+        # Initialize default algorithm (RoundRobin for state persistence)
+        from .algorithms import RoundRobin
+
+        self._default_algorithm = RoundRobin()
+
     def list_proxies(self, force_refresh: bool = False) -> List[Proxy]:
         """
         Returns the stored proxies.
@@ -58,6 +67,39 @@ class ProxyProvider(ABC):
         with self._lock:
             return list(self._proxies) if self._proxies else []
 
+    def get_proxy(self, algorithm: Optional["Algorithm"] = None) -> Proxy:
+        """Get a single proxy using the specified selection algorithm.
+
+        :param algorithm: Selection algorithm to use. If None, uses the provider's default RoundRobin algorithm.
+        :return: Selected proxy
+        :raises ValueError: If no proxies are available
+
+        Example:
+            >>> from proxyproviders import Webshare
+            >>> from proxyproviders.algorithms import Random, RoundRobin
+            >>>
+            >>> provider = Webshare(api_key="your-key")
+            >>>
+            >>> # Uses default RoundRobin (cycles through proxies)
+            >>> proxy = provider.get_proxy()
+            >>>
+            >>> # Uses Random selection
+            >>> proxy = provider.get_proxy(Random())
+            >>>
+            >>> # One-liner with requests
+            >>> import requests
+            >>> from proxyproviders.models.proxy import ProxyFormat
+            >>> requests.get("https://httpbin.org/ip", proxies=provider.get_proxy().format(ProxyFormat.REQUESTS))
+        """
+        proxies = self.list_proxies()
+        if not proxies:
+            raise ValueError("No proxies available from provider")
+
+        if algorithm is None:
+            algorithm = self._default_algorithm
+
+        return algorithm.select(proxies)
+
     #
     # Internal Methods
     #

{proxyproviders-0.1.1 → proxyproviders-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "proxyproviders"
-version = "0.1.1"
+version = "0.2.0"
 description = "A unified interface for different proxy providers"
 readme = "README.md"
 authors = [{ name = "David Teather", email = "contact.davidteather@gmail.com" }]

proxyproviders-0.1.1/proxyproviders/__init__.py

@@ -1,6 +0,0 @@
-from .proxy_provider import ProxyProvider, ProxyConfig
-from .providers.webshare import Webshare
-from .providers.brightdata import BrightData
-from .models.proxy import Proxy
-
-__all__ = ["ProxyProvider", "ProxyConfig", "Proxy", "Webshare", "BrightData"]

proxyproviders-0.1.1/proxyproviders/models/proxy.py

@@ -1,35 +0,0 @@
-from dataclasses import dataclass
-from typing import Optional, List
-from datetime import datetime
-
-
-@dataclass
-class Proxy:
-    """Our shared data model for a proxy object across all providers."""
-
-    id: str
-    """A unique identifier for the proxy"""
-
-    username: str
-    """The username required for authenticating with the proxy"""
-
-    password: str
-    """The password required for authenticating with the proxy"""
-
-    proxy_address: str
-    """The IP address or domain name of the proxy"""
-
-    port: int
-    """The port number through which the proxy connection is established"""
-
-    country_code: Optional[str] = None
-    """The country code where the proxy is located, e.g., 'US', 'FR'. Optional"""
-
-    city_name: Optional[str] = None
-    """The city name where the proxy is located, e.g., 'New York', 'Paris'. Optional"""
-
-    created_at: Optional[datetime] = None
-    """The timestamp when the proxy was created. Optional"""
-
-    protocols: Optional[List[str]] = None
-    """A list of connection protocols supported by the proxy, e.g., ['http', 'https']"""