swiftshadow 1.2.0__py3-none-any.whl → 2.0.0__py3-none-any.whl

swiftshadow/__init__.py

@@ -1,25 +1,30 @@
+from typing import Literal
 from swiftshadow.providers import Providers
+from swiftshadow.models import Proxy
+from asyncio import run
 
 
-def QuickProxy(countries: list = [], protocol: str = "http"):
+def QuickProxy(
+    countries: list[str] = [], protocol: Literal["http", "https"] = "http"
+) -> Proxy | None:
     """
-    This function is a faster alternative to `Proxy` class.
+    This function is a faster alternative to `ProxyInterface` class.
     No caching is done.
 
     Args:
-     countries: ISO 3166-2 Two letter country codes to filter proxies.
-     protocol: HTTP/HTTPS protocol to filter proxies.
+        countries: ISO 3166-2 Two letter country codes to filter proxies.
+        protocol: HTTP/HTTPS protocol to filter proxies.
 
     Returns:
-                    proxyObject (dict): A working proxy object.
+        proxyObject (Proxy): A working proxy object if found or else None.
     """
-    for providerDict in Providers:
-        if protocol not in providerDict["protocols"]:
+    for provider in Providers:
+        if protocol not in provider.protocols:
             continue
-        if (len(countries) != 0) and (not providerDict["countryFilter"]):
+        if (len(countries) != 0) and (not provider.countryFilter):
             continue
         try:
-            return providerDict["provider"](1, countries, protocol)[0]
-        except:
+            return run(provider.providerFunction(countries, protocol))[0]
+        except Exception:
             continue
     return None

swiftshadow/cache.py

@@ -1,16 +1,33 @@
 from datetime import datetime, timezone, timedelta
 
 
-def getExpiry(expiryIn):
+def getExpiry(timeToLive: int) -> datetime:
+    """
+    Fetch a datetime object representing the cache expiry based on TTL.
+
+    Args:
+        timeToLive(int): Time in minutes the cache should expire.
+
+    Returns:
+        expiry(datetime): Datetime object representing the expiry time.
+    """
     now = datetime.now(timezone.utc)
-    expiry = now + timedelta(minutes=expiryIn)
+    expiry = now + timedelta(minutes=timeToLive)
     return expiry
 
 
-def checkExpiry(expiryDateString):
+def checkExpiry(expiryDate: datetime) -> bool:
+    """
+    Check if a expiry date object has expired.
+
+    Args:
+        expiryDate(datetime): Expiry date object.
+
+    Returns:
+        expiry(bool): Expire Status.
+    """
     now = datetime.now(timezone.utc)
-    expiryDateObject = datetime.fromisoformat(expiryDateString)
-    if (now - expiryDateObject).days < 0:
+    if (now - expiryDate).days < 0:
         return False
     else:
         return True

swiftshadow/classes.py

@@ -1,145 +1,213 @@
-from requests import get
+from datetime import datetime
 from random import choice
-from json import dump, load
-from swiftshadow.helpers import log
+from typing import Literal
+from pathlib import Path
+from appdirs import user_cache_dir
+from logging import FileHandler, getLogger, Formatter, StreamHandler, INFO, DEBUG
+from sys import stdout
+from pickle import load, dump
+from swiftshadow.cache import checkExpiry, getExpiry
+from swiftshadow.models import CacheData, Proxy as Proxy
+
+from swiftshadow.exceptions import UnsupportedProxyProtocol
 from swiftshadow.providers import Providers
-import swiftshadow.cache as cache
-import logging
-import sys
-
-logger = logging.getLogger("swiftshadow")
-logger.setLevel(logging.INFO)
-logFormat = logging.Formatter("%(asctime)s - %(name)s [%(levelname)s]:%(message)s")
-streamhandler = logging.StreamHandler(stream=sys.stdout)
+from asyncio import run
+
+logger = getLogger("swiftshadow")
+logger.setLevel(INFO)
+logFormat = Formatter("%(asctime)s - %(name)s [%(levelname)s]:%(message)s")
+streamhandler = StreamHandler(stream=stdout)
 streamhandler.setFormatter(logFormat)
 logger.addHandler(streamhandler)
 
 
-class Proxy:
+class ProxyInterface:
+    """Manages proxy acquisition, caching, and rotation from various providers.
+
+    This class handles proxy retrieval either through fresh fetching from registered providers
+    or via cached data. It supports protocol filtering, country filtering, cache management,
+    and automatic/manual proxy rotation.
+
+    Attributes:
+        countries (list[str]): List of ISO country codes to filter proxies by (e.g., ["US", "CA"]).
+        protocol (Literal['https', 'http']): Proxy protocol to use. Defaults to 'http'.
+        maxproxies (int): Maximum number of proxies to collect from providers. Defaults to 10.
+        autorotate (bool): Whether to automatically rotate proxy on each get() call. Defaults to False.
+        cachePeriod (int): Number of minutes before cache is considered expired. Defaults to 10.
+        cacheFolderPath (Path): Filesystem path for cache storage. Uses system cache dir by default.
+        proxies (list[Proxy]): List of available proxy objects.
+        current (Proxy | None): Currently active proxy. None if no proxies available.
+        cacheExpiry (datetime | None): Timestamp when cache expires. None if no cache exists.
+
+    Example:
+        ```python
+        proxy_manager = ProxyInterface(
+            countries=["US"],
+            protocol="http",
+            autoRotate=True
+        )
+        print(proxy_manager.get())
+        ```
+
+    Raises:
+        UnsupportedProxyProtocol: If invalid protocol is specified during initialization.
+        ValueError: If no proxies match filters during update().
+    """
+
     def __init__(
         self,
-        countries: list = [],
-        protocol: str = "http",
+        countries: list[str] = [],
+        protocol: Literal["https", "http"] = "http",
         maxProxies: int = 10,
         autoRotate: bool = False,
         cachePeriod: int = 10,
-        cacheFolder: str = "",
+        cacheFolderPath: Path | None = None,
         debug: bool = False,
         logToFile: bool = False,
     ):
+        """Initializes ProxyInterface with specified configuration.
+
+        Args:
+            countries: List of ISO country codes to filter proxies. Empty list = no filtering.
+            protocol: Proxy protocol to retrieve. Choose between 'http' or 'https'.
+            maxProxies: Maximum proxies to collect from all providers combined.
+            autoRotate: Enable automatic proxy rotation on every get() call.
+            cachePeriod: Cache validity duration in minutes.
+            cacheFolderPath: Custom path for cache storage. Uses system cache dir if None.
+            debug: Enable debug logging level when True.
+            logToFile: Write logs to swiftshadow.log in cache folder when True.
         """
-        The one class for everything.
 
-        Proxy class contains all necessary methods required to use swiftshadow.
+        self.countries: list[str] = [i.upper() for i in countries]
 
-        Args:
-                countries: ISO 3166-2 Two letter country codes to filter proxies.
-                protocol: HTTP/HTTPS protocol to filter proxies.
-                maxProxies: Maximum number of proxies to store and rotate from.
-                autoRotate: Rotates proxy when `Proxy.proxy()` function is called.
-                cachePeriod: Time to cache proxies in minutes.
-                cacheFolder: Folder to store cache file.
-                debug: Sets Log Level to Debug.
-                logToFile: Whether to pipe log to a log file. If cacheFolder is set log file is saved there.
+        if protocol not in ["https", "http"]:
+            raise UnsupportedProxyProtocol(
+                f"Protocol {protocol} is not supported by swiftshadow, please choose between HTTP or HTTPS"
+            )
+        self.protocol: Literal["https", "http"] = protocol
+
+        self.maxproxies: int = maxProxies
+        self.autorotate: bool = autoRotate
+        self.cachePeriod: int = cachePeriod
 
-        Returns:
-                proxyClass (swiftshadow.Proxy): `swiftshadow.Proxy` class instance
-
-        Examples:
-                Simplest way to get a proxy
-                >>> from swiftshadow.swiftshadow import Proxy
-                >>> swift = Proxy()
-                >>> print(swift.proxy())
-                {'http':'192.0.0.1:8080'}
-        Note:
-                Proxies are sourced from **Proxyscrape** and **Scrapingant** websites which are freely available and validated locally.
-        """
-        self.countries = [i.upper() for i in countries]
-        self.protocol = protocol
-        self.maxProxies = maxProxies
-        self.autoRotate = autoRotate
-        self.cachePeriod = cachePeriod
-        if cacheFolder == "":
-            self.cacheFilePath = ".swiftshadow.json"
-        else:
-            self.cacheFilePath = f"{cacheFolder}/.swiftshadow.json"
         if debug:
-            logger.setLevel(logging.DEBUG)
+            logger.setLevel(DEBUG)
+
+        if not cacheFolderPath:
+            cacheFolderPath = Path(user_cache_dir(appname="swiftshadow"))
+            cacheFolderPath.mkdir(parents=True, exist_ok=True)
+            logger.debug(f"System Cache folder set at {cacheFolderPath}")
+        self.cacheFolderPath: Path = cacheFolderPath
+
         if logToFile:
-            if cacheFolder == "":
-                logFilePath = "swiftshadow.log"
-            else:
-                logFilePath = f"{cacheFolder}/swiftshadow.log"
-            fileHandler = logging.FileHandler(logFilePath)
-            fileHandler.setFormatter(logFormat)
-            logger.addHandler(fileHandler)
+            logFileHandler = FileHandler(
+                self.cacheFolderPath.joinpath("swiftshadow.log")
+            )
+            logFileHandler.setFormatter(logFormat)
+            logger.addHandler(logFileHandler)
+        self.proxies: list[Proxy] = []
+        self.current: Proxy | None = None
+        self.cacheExpiry: datetime | None = None
+
         self.update()
 
     def update(self):
+        """
+        Updates proxy list from providers or cache.
+
+        First attempts to load valid proxies from cache. If cache is expired/missing,
+        fetches fresh proxies from registered providers that match country and protocol filters.
+        Updates cache file with new proxies if fetched from providers.
+
+        Raises:
+            ValueError: If no proxies found after provider scraping.
+        """
         try:
-            with open(self.cacheFilePath, "r") as file:
-                data = load(file)
-                self.expiry = data[0]
-                expired = cache.checkExpiry(self.expiry)
-            if not expired:
-                logger.info(
-                    "Loaded proxies from cache",
-                )
-                self.proxies = data[1]
-                self.expiry = data[0]
-                self.current = self.proxies[0]
-                return
-            else:
-                logger.info(
-                    "Cache expired. Updating cache.",
-                )
+            with open(
+                self.cacheFolderPath.joinpath("swiftshadow.pickle"), "rb"
+            ) as cacheFile:
+                cache: CacheData = load(cacheFile)
+
+                if not checkExpiry(cache.expiryIn):
+                    self.proxies = cache.proxies
+                    logger.info("Loaded proxies from cache.")
+                    logger.debug(
+                        f"Cache with {len(cache.proxies)} proxies, expire in {cache.expiryIn}"
+                    )
+                    self.current = self.proxies[0]
+                    self.cacheExpiry = cache.expiryIn
+                    return
+                else:
+                    logger.info("Cache Expired")
         except FileNotFoundError:
-            logger.info("No cache found. Cache will be created after update")
+            logger.info("No cache found, will be created after update.")
 
-        self.proxies = []
-        for providerDict in Providers:
-            if self.protocol not in providerDict["protocols"]:
+        for provider in Providers:
+            if self.protocol not in provider.protocols:
                 continue
-            if (len(self.countries) != 0) and (not providerDict["countryFilter"]):
+            if (len(self.countries) != 0) and (not provider.countryFilter):
                 continue
-            self.proxies.extend(
-                providerDict["provider"](self.maxProxies, self.countries, self.protocol)
+            providerProxies: list[Proxy] = run(
+                provider.providerFunction(self.countries, self.protocol)
             )
-            if len(self.proxies) >= self.maxProxies:
+            logger.debug(
+                f"{len(providerProxies)} proxies from {provider.providerFunction.__name__}"
+            )
+            self.proxies.extend(providerProxies)
+
+            if len(self.proxies) >= self.maxproxies:
                 break
+
         if len(self.proxies) == 0:
-            logger.warning(
-                "No proxies found for current settings. To prevent runtime error updating the proxy list again.",
-            )
-            self.update()
-        with open(self.cacheFilePath, "w") as file:
-            self.expiry = cache.getExpiry(self.cachePeriod).isoformat()
-            dump([self.expiry, self.proxies], file)
+            raise ValueError("No proxies where found for the current filter settings.")
+
+        with open(
+            self.cacheFolderPath.joinpath("swiftshadow.pickle"), "wb+"
+        ) as cacheFile:
+            cacheExpiry = getExpiry(self.cachePeriod)
+            self.cacheExpiry = cacheExpiry
+            cache = CacheData(cacheExpiry, self.proxies)
+            dump(cache, cacheFile)
         self.current = self.proxies[0]
 
-    def rotate(self):
+    def rotate(self, validate_cache: bool = False):
         """
-        Rotate the current proxy.
+        Rotates to a random proxy from available proxies.
 
-        Sets the current proxy to a random one from available proxies and also validates cache.
+        Args:
+            validate_cache: Force cache validation before rotation when True.
 
         Note:
-                Function only for manual rotation. If `autoRotate` is set to `True` then no need to call this function.
+            Only required for manual rotation when autoRotate=False. Automatic rotation
+            occurs during get() calls when autoRotate=True.
+
+        Raises:
+            ValueError: If validate_cache=True but no cache exists.
         """
-        if cache.checkExpiry(self.expiry):
-            self.update()
+        if self.cacheExpiry and not validate_cache:
+            if checkExpiry(self.cacheExpiry):
+                self.update()
+        else:
+            raise ValueError("No cache availabel but validate_cache is true.")
         self.current = choice(self.proxies)
 
-    def proxy(self):
+    def get(self) -> Proxy:
         """
-        Returns a proxy dict.
+        Retrieves current active proxy.
 
         Returns:
-                proxyDict (dict):A proxy dict of format `{protocol:address}`
+            Proxy: Current proxy object with connection details.
+
+        Note:
+            Performs automatic rotation if autorotate=True before returning proxy.
+
+        Raises:
+            ValueError: If no proxies are available (current is None).
         """
-        if cache.checkExpiry(self.expiry):
-            self.update()
-        if self.autoRotate == True:
-            return choice(self.proxies)
-        else:
+
+        if self.autorotate:
+            self.rotate()
+        if self.current:
             return self.current
+        else:
+            raise ValueError("No proxy available in current, current is None")

swiftshadow/exceptions.py

@@ -0,0 +1,4 @@
+class UnsupportedProxyProtocol(Exception):
+    """Exception raised when a unsupported proxy protocol is intialised."""
+
+    pass

swiftshadow/helpers.py

@@ -1,5 +1,8 @@
-from requests import get
 from datetime import datetime
+from typing import Literal
+
+from requests import get
+from swiftshadow.models import Proxy
 
 
 def checkProxy(proxy):
@@ -11,12 +14,24 @@ def checkProxy(proxy):
         if resp.count(".") == 3:
             return True
         return False
-    except Exception as e:
+    except Exception:
         return False
 
 
 def log(level, message):
     level = level.upper()
     print(
-        f'{datetime.now().strftime("%d/%m/%Y %H:%M:%S")} - [swiftshadow] - {level} : {message}'
+        f"{datetime.now().strftime('%d/%m/%Y %H:%M:%S')} - [swiftshadow] - {level} : {message}"
     )
+
+
+def plaintextToProxies(text: str, protocol: Literal["http", "https"]) -> list[Proxy]:
+    proxies: list[Proxy] = []
+    for line in text.splitlines():
+        try:
+            ip, port = line.split(":")
+        except ValueError:
+            continue
+        proxy = Proxy(ip=ip, port=int(port), protocol=protocol)
+        proxies.append(proxy)
+    return proxies

swiftshadow/models.py

@@ -0,0 +1,71 @@
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Callable, Coroutine, Literal
+
+
+@dataclass
+class Proxy:
+    """
+    Class representing a Proxy object.
+
+    Attributes:
+        ip: IP Address of the proxy.
+        port: Port associated with the proxy.
+        protocol: Protocol type of the proxy.
+
+    """
+
+    ip: str
+    protocol: Literal["http", "https"]
+    port: int
+
+    def as_requests_dict(self) -> dict[Literal["http", "https"], str]:
+        """
+        Return proxy in requests commpatible dict format.
+
+        Returns:
+            dict: Dict representation of Proxy class.
+        """
+        return {self.protocol: f"{self.ip}:{self.port}"}
+
+    def as_string(self) -> str:
+        """
+        Return proxy in a string of format
+        <protocol>://<ip>:<port>
+
+        Returns:
+            string: Proxy in string format.
+        """
+        return f"{self.protocol}://{self.ip}:{self.port}"
+
+
+@dataclass
+class CacheData:
+    """
+    Class repersenting data structure if the cache in cache file.
+
+    Attributes:
+        expiryIn: Expiry date object.
+        proxies: Proxies to head.
+    """
+
+    expiryIn: datetime
+    proxies: list[Proxy]
+
+
+@dataclass
+class Provider:
+    """
+    Class repersenting a Provider.
+
+    Attributes:
+        providerFunction: Callable function for this provider.
+        countryFilter: Whether the provider supports country based filters.
+        protocols: Protocols supported by the provider.
+    """
+
+    providerFunction: Callable[
+        [list[str], Literal["http", "https"]], Coroutine[Any, Any, list[Proxy]]
+    ]
+    countryFilter: bool
+    protocols: list[Literal["http", "https"]]

swiftshadow/providers.py

@@ -1,57 +1,162 @@
+from typing import Literal
+
 from requests import get
-from swiftshadow.helpers import checkProxy
-
-def Monosans(max, countries=[],protocol="http"):
-    raw = get('https://raw.githubusercontent.com/monosans/proxy-list/main/proxies.json').json()
-    results = []
-    count = 0
-    for proxy in raw:
-        if count == max:
-            return results
-        if proxy['protocol'] == protocol:
-            if len(countries) != 0 and proxy['geolocation']['country']['iso_code'] not in countries:
-                continue
-            proxy = [f'{proxy['host']}:{proxy['port']}',proxy['protocol']]
-            if checkProxy(proxy):
-                results.append(proxy)
-                count += 1
-    return results
-
-def Thespeedx(max,countries=[],protocol='http'):
-    results = []
-    count =0
-    raw = get('https://raw.githubusercontent.com/TheSpeedX/PROXY-List/master/http.txt').text
-    for line in raw.splitlines():
-        if count == max:
-            break
-        proxy = [line,'http']
-        if checkProxy(proxy):
-            results.append(proxy)
-            print(proxy,True)
-            count +=1
-        else:
+
+from swiftshadow.helpers import plaintextToProxies
+from swiftshadow.models import Proxy, Provider
+from swiftshadow.types import MonosansProxyDict
+from swiftshadow.validator import validate_proxies
+
+
+async def Monosans(
+    countries: list[str] = [],
+    protocol: Literal["http", "https"] = "http",
+) -> list[Proxy]:
+    response = get(
+        "https://raw.githubusercontent.com/monosans/proxy-list/main/proxies.json"
+    )
+    proxy_dicts: list[MonosansProxyDict] = response.json()
+    proxies_to_validate: list[Proxy] = []
+    for proxy_dict in proxy_dicts:
+        if proxy_dict["protocol"] != protocol:
             continue
+        if (
+            len(countries) != 0
+            and proxy_dict["geolocation"]["country"]["iso_code"] not in countries
+        ):
+            continue
+        proxy = Proxy(
+            ip=proxy_dict["host"],
+            port=proxy_dict["port"],
+            protocol=proxy_dict["protocol"],
+        )
+        proxies_to_validate.append(proxy)
+    result = await validate_proxies(proxies_to_validate)
+    return result
+
+
+async def Thespeedx(
+    countries: list[str] = [], protocol: Literal["http", "https"] = "http"
+):
+    raw: str = get(
+        "https://raw.githubusercontent.com/TheSpeedX/PROXY-List/master/http.txt"
+    ).text
+    proxies: list[Proxy] = plaintextToProxies(raw, protocol="http")
+    results = await validate_proxies(proxies)
     return results
-        
-def ProxyScrape(max,countries=[],protocol='http'):
-    baseUrl = 'https://api.proxyscrape.com/v3/free-proxy-list/get?request=displayproxies&protocol=http&proxy_format=ipport&format=json'
-    results = []
-    count = 0
+
+
+async def ProxyScrape(
+    countries: list[str] = [], protocol: Literal["http", "https"] = "http"
+):
+    baseUrl = "https://api.proxyscrape.com/v3/free-proxy-list/get?request=displayproxies&protocol=http&proxy_format=ipport&format=json"
+    proxies: list[Proxy] = []
     if len(countries) == 0:
-        apiUrl = baseUrl + '&country=all'
+        apiUrl = baseUrl + "&country=all"
     else:
-        apiUrl = baseUrl + '&country=' + ','.join([i.upper() for i in countries])
+        apiUrl = baseUrl + "&country=" + ",".join([i.upper() for i in countries])
     raw = get(apiUrl).json()
-    for ipRaw in raw['proxies']:
-        if count == max:
-            break
-        proxy = [ipRaw['proxy'],'http']  
-        if checkProxy(proxy):
-            results.append(proxy)
-            count += 1
-        else:
-            print(proxy,False)
+    for ipRaw in raw["proxies"]:
+        proxy = Proxy(protocol="http", ip=ipRaw["ip"], port=ipRaw["port"])
+        proxies.append(proxy)
+    results = await validate_proxies(proxies)
+    return results
+
+
+async def GoodProxy(
+    countries: list[str] = [], protocol: Literal["http", "https"] = "http"
+):
+    baseUrl = "https://raw.githubusercontent.com/yuceltoluyag/GoodProxy/refs/heads/main/GoodProxy.txt"
+    proxies: list[Proxy] = []
+    raw = get(baseUrl).text
+
+    for line in raw.splitlines():
+        if line == "":
             continue
-    return results          
+        line = line.split("|")[0].split(":")
+        proxy = Proxy(ip=line[0], port=int(line[1]), protocol="http")
+        proxies.append(proxy)
+    results = await validate_proxies(proxies)
+    return results
+
+
+async def OpenProxyList(
+    countries: list[str] = [], protocol: Literal["http", "https"] = "http"
+):
+    raw = get("https://api.openproxylist.xyz/http.txt").text
+    proxies: list[Proxy] = plaintextToProxies(raw, protocol="http")
+    results = await validate_proxies(proxies)
+    return results
+
+
+async def MuRongPIG(
+    countries: list[str] = [], protocol: Literal["http", "https"] = "http"
+):
+    raw = get(
+        "https://raw.githubusercontent.com/MuRongPIG/Proxy-Master/refs/heads/main/http_checked.txt"
+    ).text
+    proxies: list[Proxy] = plaintextToProxies(raw, protocol="http")
+    results = await validate_proxies(proxies)
+    return results
+
+
+async def KangProxy(
+    countries: list[str] = [], protocol: Literal["http", "https"] = "http"
+):
+    raw = get(
+        f"https://github.com/officialputuid/KangProxy/raw/refs/heads/KangProxy/{protocol}/{protocol}.txt"
+    ).text
+    proxies: list[Proxy] = plaintextToProxies(raw, protocol=protocol)
+    results = await validate_proxies(proxies)
+    return results
+
+
+async def Mmpx12(
+    countries: list[str] = [], protocol: Literal["http", "https"] = "http"
+):
+    raw = get(
+        f"https://github.com/mmpx12/proxy-list/raw/refs/heads/master/{protocol}.txt"
+    ).text
+    proxies: list[Proxy] = plaintextToProxies(raw, protocol=protocol)
+    results = await validate_proxies(proxies)
+    return results
+
+
+async def Anonym0usWork1221(
+    countries: list[str] = [], protocol: Literal["http", "https"] = "http"
+):
+    raw = get(
+        f"https://github.com/Anonym0usWork1221/Free-Proxies/raw/refs/heads/main/proxy_files/{protocol}_proxies.txt"
+    ).text
+    proxies: list[Proxy] = plaintextToProxies(raw, protocol=protocol)
+    results = await validate_proxies(proxies)
+    return results
+
+
+async def ProxySpace(
+    countries: list[str] = [], protocol: Literal["http", "https"] = "http"
+):
+    raw = get("https://proxyspace.pro/http.txt").text
+    proxies: list[Proxy] = plaintextToProxies(raw, protocol="http")
+    results = await validate_proxies(proxies)
+    return results
+
 
-Providers = [{'provider':Monosans,'countryFilter':True,'protocols':['http']},{'provider':Thespeedx,'countryFilter':False,'protocols':['http']},{'provider':ProxyScrape,'countryFilter':True,'protocols':['http']}]
+Providers: list[Provider] = [
+    Provider(providerFunction=ProxyScrape, countryFilter=True, protocols=["http"]),
+    Provider(providerFunction=Monosans, countryFilter=True, protocols=["http"]),
+    Provider(providerFunction=MuRongPIG, countryFilter=False, protocols=["http"]),
+    Provider(providerFunction=Thespeedx, countryFilter=False, protocols=["http"]),
+    Provider(
+        providerFunction=Anonym0usWork1221,
+        countryFilter=False,
+        protocols=["http", "https"],
+    ),
+    Provider(providerFunction=Mmpx12, countryFilter=False, protocols=["http", "https"]),
+    Provider(providerFunction=GoodProxy, countryFilter=False, protocols=["http"]),
+    Provider(
+        providerFunction=KangProxy, countryFilter=False, protocols=["http", "https"]
+    ),
+    Provider(providerFunction=ProxySpace, countryFilter=False, protocols=["http"]),
+    Provider(providerFunction=OpenProxyList, countryFilter=False, protocols=["http"]),
+]

swiftshadow/types.py

@@ -0,0 +1,50 @@
+from typing import TypedDict
+
+
+class MonosansNames(TypedDict):
+    de: str
+    en: str
+    es: str
+    fr: str
+    ja: str
+    pt_BR: str
+    ru: str
+    zh_CN: str
+
+
+class MonosansContinent(TypedDict):
+    code: str
+    geoname_id: int
+    names: MonosansNames
+
+
+class MonosansCountry(TypedDict):
+    geoname_id: int
+    is_in_european_union: bool
+    iso_code: str
+    names: MonosansNames
+
+
+class MonosansLocation(TypedDict):
+    accuracy_radius: int
+    latitude: float
+    longitude: float
+    time_zone: str
+
+
+class MonosansGeolocation(TypedDict):
+    continent: MonosansContinent
+    country: MonosansCountry
+    location: MonosansLocation
+    registered_country: MonosansCountry
+
+
+class MonosansProxyDict(TypedDict):
+    protocol: str
+    username: str | None
+    password: str | None
+    host: str
+    port: int
+    exit_ip: str
+    timeout: float
+    geolocation: MonosansGeolocation

swiftshadow/validator.py

@@ -0,0 +1,50 @@
+import asyncio
+
+import aiohttp
+
+from swiftshadow.models import Proxy
+
+
+async def check_proxy(async_session: aiohttp.ClientSession, proxy: Proxy) -> str:
+    """
+    Check one proxy abject.
+
+    Args:
+        async_session: aiohttp client session object
+        proxy: Proxy Object
+
+    Returns:
+        text: API response text
+    """
+    async with async_session.get(
+        url=f"{proxy.protocol}://checkip.amazonaws.com",
+        proxy=proxy.as_string(),
+        timeout=4,
+    ) as response:
+        text = await response.text()
+        return text
+
+
+async def validate_proxies(proxies: list[Proxy]) -> list[Proxy]:
+    """
+    Validate all proxies asynchronously.
+
+    Args:
+        proxies: List of Proxy objects
+
+    Returns:
+        working_proxies: List of working Proxies
+    """
+    working_proxies: list[Proxy] = []
+    async with aiohttp.ClientSession() as async_session:
+        tasks = []
+        for proxy in proxies:
+            task = asyncio.create_task(coro=check_proxy(async_session, proxy))
+            tasks.append(task)
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+        for proxy, result in zip(proxies, results):
+            if type(result) is not str:
+                continue
+            if result.count(".") == 3:
+                working_proxies.append(proxy)
+    return working_proxies

swiftshadow-2.0.0.dist-info/METADATA

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: swiftshadow
+Version: 2.0.0
+Summary: Free IP Proxy rotator for python
+Author-email: sachin-sankar <mail.sachinsankar@gmail.com>
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: aiohttp>=3.11.11
+Requires-Dist: appdirs>=1.4.4
+Requires-Dist: requests>=2.32.3
+Description-Content-Type: text/markdown
+
+# Swiftshadow
+
+![PyPI - Downloads](https://img.shields.io/pypi/dm/swiftshadow)  
+![GitHub release (latest by date including pre-releases)](https://img.shields.io/github/v/release/sachin-sankar/swiftshadow?include_prereleases&style=flat)
+
+> [!WARNING]  
+> **Heads up!** If you're using **versions 1.2.1 or below**, please note that **version 2.0.0 and above** includes breaking changes. Before upgrading, read the [documentation](https://sachin-sankar.github.io/swiftshadow/) to understand the changes and ensure compatibility with your code. If you encounter issues, please review the docs before opening a GitHub issue.
+
+## About
+
+**Swiftshadow** is a lightweight and efficient Python library designed to simplify IP proxy rotation for web scraping, data mining, and other automated tasks. It helps you bypass common challenges like IP bans, rate limits, and detection mechanisms, ensuring smooth and uninterrupted data collection.
+
+### Key Features
+- **Speed**: Optimized for fast proxy retrieval and rotation.
+- **Reliability**: Automatically switches to working proxies if one fails.
+- **Customization**: Configure proxy filters, rotation frequency, and caching behavior.
+- **Low Dependencies**: Only one third-party dependency (`requests`), making it easy to use and maintain.
+- **Caching**: Built-in caching mechanism to reduce load times and improve performance.
+
+Whether you're a seasoned developer or a beginner, **Swiftshadow** makes proxy management effortless.
+
+---
+
+## Installation
+
+Install the library using pip:
+
+```bash
+pip install swiftshadow
+```
+
+---
+
+## Quick Start
+
+### Get a Proxy in 2 Lines
+Fetch a random proxy with just two lines of code:
+
+```python
+from swiftshadow import QuickProxy
+
+print(QuickProxy())  # Output: http://<ip>:<port>
+```
+
+### Advanced Usage
+For more control, use the `ProxyInterface` class:
+
+```python
+from swiftshadow.classes import ProxyInterface
+
+# Fetch HTTPS proxies from the US
+swift = ProxyInterface(countries=["US"], protocol="https")
+print(swift.get().as_string())  # Output: https://<ip>:<port>
+```
+
+---
+
+## Documentation
+
+Explore the full documentation to learn more about **Swiftshadow**'s features and advanced usage:
+
+📚 [Documentation](https://sachin-sankar.github.io/swiftshadow/)
+
+---
+
+## Why Swiftshadow?
+
+- **Lightweight**: Minimal dependencies and easy to integrate.
+- **Flexible**: Supports filtering by country and protocol.
+- **Scalable**: Ideal for both small scripts and large-scale scraping projects.
+- **Open Source**: Free to use, modify, and contribute to under the MIT License.
+
+---
+
+## Contributing
+
+Contributions are welcome! If you'd like to improve **Swiftshadow**, feel free to open an issue or submit a pull request on [GitHub](https://github.com/sachin-sankar/swiftshadow).
+
+---
+
+## License
+
+**Swiftshadow** is licensed under the MIT License. See the [LICENSE](https://github.com/sachin-sankar/swiftshadow/blob/main/LICENSE) file for details.

swiftshadow-2.0.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+swiftshadow/__init__.py,sha256=DCxCxaMrluQDVJLyK5K61NxSaadD1d-nyTrFKsjfNDI,921
+swiftshadow/cache.py,sha256=eA_AWa8EsPdB6xD__ButvQdqETC4i89qEgxmHQV2XWU,800
+swiftshadow/classes.py,sha256=4hr0h2aOb-CXYPrf_ESf05RSEdRVLmYtvx09npnUVhQ,8242
+swiftshadow/exceptions.py,sha256=qu4eXyrkWD9qd4HCIR-8vRfVcqLlTupo4sD72alCdug,129
+swiftshadow/helpers.py,sha256=hHJ_JjRx2UFC5Ircl75LeYKBNDYTY_xMy2iWCk-UPqo,959
+swiftshadow/models.py,sha256=YyfZV98tPdLnF1O3WmTNUNoK4t0GuchfEftzjiM03ck,1678
+swiftshadow/providers.py,sha256=myJ6t-WD20wrjc7qDhxCpX1-oi7ipQutp34XKM2tjeI,5660
+swiftshadow/types.py,sha256=Alyw3n54OESX1vSR-0kTvpYTlJ8LKfy5J9WZbtglHpE,894
+swiftshadow/validator.py,sha256=dBcb6Lev6ojsk9f45IjyEUHZXsCcylyn6RoZA1WPDNQ,1345
+swiftshadow-2.0.0.dist-info/METADATA,sha256=MSM2WB68lsN__C1JiNwMH2sPMah2GrPUoCwyNbPoF9U,3261
+swiftshadow-2.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+swiftshadow-2.0.0.dist-info/entry_points.txt,sha256=yMj0uEagcmXK2dmMmNXWebTpTT9j5K03oaRrd2wkyLA,49
+swiftshadow-2.0.0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+swiftshadow-2.0.0.dist-info/RECORD,,

{swiftshadow-1.2.0.dist-info → swiftshadow-2.0.0.dist-info}/WHEEL

@@ -1,5 +1,4 @@
 Wheel-Version: 1.0
-Generator: setuptools (70.2.0)
+Generator: hatchling 1.27.0
 Root-Is-Purelib: true
 Tag: py3-none-any
-

swiftshadow-2.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+swiftshadow = swiftshadow:main

swiftshadow/constants.py

@@ -1,250 +0,0 @@
-CountryCodes = {
-    "Afghanistan": "AF",
-    "Åland Islands": "AX",
-    "Albania": "AL",
-    "Algeria": "DZ",
-    "American Samoa": "AS",
-    "Andorra": "AD",
-    "Angola": "AO",
-    "Anguilla": "AI",
-    "Antarctica": "AQ",
-    "Antigua and Barbuda": "AG",
-    "Argentina": "AR",
-    "Armenia": "AM",
-    "Aruba": "AW",
-    "Australia": "AU",
-    "Austria": "AT",
-    "Azerbaijan": "AZ",
-    "Bahamas": "BS",
-    "Bahrain": "BH",
-    "Bangladesh": "BD",
-    "Barbados": "BB",
-    "Belarus": "BY",
-    "Belgium": "BE",
-    "Belize": "BZ",
-    "Benin": "BJ",
-    "Bermuda": "BM",
-    "Bhutan": "BT",
-    "Bolivia (Plurinational State of)": "BO",
-    '"Bonaire': ' Sint Eustatius and Saba"',
-    "Bosnia and Herzegovina": "BA",
-    "Botswana": "BW",
-    "Bouvet Island": "BV",
-    "Brazil": "BR",
-    "British Indian Ocean Territory": "IO",
-    "Brunei Darussalam": "BN",
-    "Bulgaria": "BG",
-    "Burkina Faso": "BF",
-    "Burundi": "BI",
-    "Cabo Verde": "CV",
-    "Cambodia": "KH",
-    "Cameroon": "CM",
-    "Canada": "CA",
-    "Cayman Islands": "KY",
-    "Central African Republic": "CF",
-    "Chad": "TD",
-    "Chile": "CL",
-    "China": "CN",
-    "Christmas Island": "CX",
-    "Cocos (Keeling) Islands": "CC",
-    "Colombia": "CO",
-    "Comoros": "KM",
-    "Congo": "CG",
-    '"Congo': ' Democratic Republic of the"',
-    "Cook Islands": "CK",
-    "Costa Rica": "CR",
-    "Côte d'Ivoire": "CI",
-    "Croatia": "HR",
-    "Cuba": "CU",
-    "Curaçao": "CW",
-    "Cyprus": "CY",
-    "Czechia": "CZ",
-    "Denmark": "DK",
-    "Djibouti": "DJ",
-    "Dominica": "DM",
-    "Dominican Republic": "DO",
-    "Ecuador": "EC",
-    "Egypt": "EG",
-    "El Salvador": "SV",
-    "Equatorial Guinea": "GQ",
-    "Eritrea": "ER",
-    "Estonia": "EE",
-    "Eswatini": "SZ",
-    "Ethiopia": "ET",
-    "Falkland Islands (Malvinas)": "FK",
-    "Faroe Islands": "FO",
-    "Fiji": "FJ",
-    "Finland": "FI",
-    "France": "FR",
-    "French Guiana": "GF",
-    "French Polynesia": "PF",
-    "French Southern Territories": "TF",
-    "Gabon": "GA",
-    "Gambia": "GM",
-    "Georgia": "GE",
-    "Germany": "DE",
-    "Ghana": "GH",
-    "Gibraltar": "GI",
-    "Greece": "GR",
-    "Greenland": "GL",
-    "Grenada": "GD",
-    "Guadeloupe": "GP",
-    "Guam": "GU",
-    "Guatemala": "GT",
-    "Guernsey": "GG",
-    "Guinea": "GN",
-    "Guinea-Bissau": "GW",
-    "Guyana": "GY",
-    "Haiti": "HT",
-    "Heard Island and McDonald Islands": "HM",
-    "Holy See": "VA",
-    "Honduras": "HN",
-    "Hong Kong": "HK",
-    "Hungary": "HU",
-    "Iceland": "IS",
-    "India": "IN",
-    "Indonesia": "ID",
-    "Iran (Islamic Republic of)": "IR",
-    "Iraq": "IQ",
-    "Ireland": "IE",
-    "Isle of Man": "IM",
-    "Israel": "IL",
-    "Italy": "IT",
-    "Jamaica": "JM",
-    "Japan": "JP",
-    "Jersey": "JE",
-    "Jordan": "JO",
-    "Kazakhstan": "KZ",
-    "Kenya": "KE",
-    "Kiribati": "KI",
-    "Korea (Democratic People's Republic of)": "KP",
-    '"Korea': ' Republic of"',
-    "Kuwait": "KW",
-    "Kyrgyzstan": "KG",
-    "Lao People's Democratic Republic": "LA",
-    "Latvia": "LV",
-    "Lebanon": "LB",
-    "Lesotho": "LS",
-    "Liberia": "LR",
-    "Libya": "LY",
-    "Liechtenstein": "LI",
-    "Lithuania": "LT",
-    "Luxembourg": "LU",
-    "Macao": "MO",
-    "Madagascar": "MG",
-    "Malawi": "MW",
-    "Malaysia": "MY",
-    "Maldives": "MV",
-    "Mali": "ML",
-    "Malta": "MT",
-    "Marshall Islands": "MH",
-    "Martinique": "MQ",
-    "Mauritania": "MR",
-    "Mauritius": "MU",
-    "Mayotte": "YT",
-    "Mexico": "MX",
-    "Micronesia (Federated States of)": "FM",
-    '"Moldova': ' Republic of"',
-    "Monaco": "MC",
-    "Mongolia": "MN",
-    "Montenegro": "ME",
-    "Montserrat": "MS",
-    "Morocco": "MA",
-    "Mozambique": "MZ",
-    "Myanmar": "MM",
-    "Namibia": "NA",
-    "Nauru": "NR",
-    "Nepal": "NP",
-    "Netherlands": "NL",
-    "New Caledonia": "NC",
-    "New Zealand": "NZ",
-    "Nicaragua": "NI",
-    "Niger": "NE",
-    "Nigeria": "NG",
-    "Niue": "NU",
-    "Norfolk Island": "NF",
-    "North Macedonia": "MK",
-    "Northern Mariana Islands": "MP",
-    "Norway": "NO",
-    "Oman": "OM",
-    "Pakistan": "PK",
-    "Palau": "PW",
-    '"Palestine': ' State of"',
-    "Panama": "PA",
-    "Papua New Guinea": "PG",
-    "Paraguay": "PY",
-    "Peru": "PE",
-    "Philippines": "PH",
-    "Pitcairn": "PN",
-    "Poland": "PL",
-    "Portugal": "PT",
-    "Puerto Rico": "PR",
-    "Qatar": "QA",
-    "Réunion": "RE",
-    "Romania": "RO",
-    "Russian Federation": "RU",
-    "Rwanda": "RW",
-    "Saint Barthélemy": "BL",
-    '"Saint Helena': ' Ascension and Tristan da Cunha"',
-    "Saint Kitts and Nevis": "KN",
-    "Saint Lucia": "LC",
-    "Saint Martin (French part)": "MF",
-    "Saint Pierre and Miquelon": "PM",
-    "Saint Vincent and the Grenadines": "VC",
-    "Samoa": "WS",
-    "San Marino": "SM",
-    "Sao Tome and Principe": "ST",
-    "Saudi Arabia": "SA",
-    "Senegal": "SN",
-    "Serbia": "RS",
-    "Seychelles": "SC",
-    "Sierra Leone": "SL",
-    "Singapore": "SG",
-    "Sint Maarten (Dutch part)": "SX",
-    "Slovakia": "SK",
-    "Slovenia": "SI",
-    "Solomon Islands": "SB",
-    "Somalia": "SO",
-    "South Africa": "ZA",
-    "South Georgia and the South Sandwich Islands": "GS",
-    "South Sudan": "SS",
-    "Spain": "ES",
-    "Sri Lanka": "LK",
-    "Sudan": "SD",
-    "Suriname": "SR",
-    "Svalbard and Jan Mayen": "SJ",
-    "Sweden": "SE",
-    "Switzerland": "CH",
-    "Syrian Arab Republic": "SY",
-    '"Taiwan': ' Province of China"',
-    "Tajikistan": "TJ",
-    '"Tanzania': ' United Republic of"',
-    "Thailand": "TH",
-    "Timor-Leste": "TL",
-    "Togo": "TG",
-    "Tokelau": "TK",
-    "Tonga": "TO",
-    "Trinidad and Tobago": "TT",
-    "Tunisia": "TN",
-    "Turkey": "TR",
-    "Turkmenistan": "TM",
-    "Turks and Caicos Islands": "TC",
-    "Tuvalu": "TV",
-    "Uganda": "UG",
-    "Ukraine": "UA",
-    "United Arab Emirates": "AE",
-    "United Kingdom of Great Britain and Northern Ireland": "GB",
-    "United States of America": "US",
-    "United States Minor Outlying Islands": "UM",
-    "Uruguay": "UY",
-    "Uzbekistan": "UZ",
-    "Vanuatu": "VU",
-    "Venezuela (Bolivarian Republic of)": "VE",
-    "Viet Nam": "VN",
-    "Virgin Islands (British)": "VG",
-    "Virgin Islands (U.S.)": "VI",
-    "Wallis and Futuna": "WF",
-    "Western Sahara": "EH",
-    "Yemen": "YE",
-    "Zambia": "ZM",
-}

swiftshadow-1.2.0.dist-info/METADATA

@@ -1,54 +0,0 @@
-Metadata-Version: 2.1
-Name: swiftshadow
-Version: 1.2.0
-Summary: Free IP Proxy rotator for python
-Home-page: https://github.com/sachin-sankar/swiftshadow
-Author: Sachin Sankar
-Author-email: mail.sachinsankar@gmail.com
-Classifier: Development Status :: 5 - Production/Stable
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: requests
-
-# Swiftshadow
-
-![PyPI - Downloads](https://img.shields.io/pypi/dm/swiftshadow) ![GitHub release (latest by date including pre-releases)](https://img.shields.io/github/v/release/sachin-sankar/swiftshadow?include_prereleases&style=flat)
-
-> [!TIP]  
-> I'm refactoring the library for better speed and maintainability. Future updates might have breaking changes, but I'll keep you posted!
-
-## About
-
-Swiftshadow is a powerful Python library designed to simplify the process of rotating IP proxies for web scraping, data mining, and other automated tasks. With its advanced features, Swiftshadow can help you overcome many of the challenges associated with web scraping, including blocked IP addresses and other forms of detection.
-
-One of the key benefits of Swiftshadow is its speed. The library is designed to operate quickly and efficiently, which means you can scrape data at a faster rate than with other tools. Additionally, Swiftshadow includes a built-in caching mechanism that helps to reduce the load time and improve performance.
-
-Another important feature of Swiftshadow is its reliability. The library is designed to be robust and resilient, which means that even if one of your proxies fails or is blocked, the system will automatically switch to another proxy to ensure continuity of your scraping process. This feature helps to ensure that your scraping efforts are not interrupted by technical issues or other problems.
-
-Swiftshadow is also highly customizable. You can easily configure the library to suit your specific needs, including specifying the number of proxies to use, the frequency of rotation, and other parameters. This level of flexibility makes Swiftshadow a versatile tool that can be adapted to a wide range of use cases.
-
-Finally, Swiftshadow has a low dependency on third-party libraries (only one), which makes it easier to use and maintain. Whether you are a seasoned developer or a novice, you can quickly get started with Swiftshadow and start scraping data with ease.
-
-## Installation
-
-To get started install the library using pip.
-
-``` py
-pip install swiftshadow
-```
-
-## One class rules all
-
-Everything in swiftshadow is under one class for ease of use and minimal code.
-
-Get a proxy using just 2 lines of code!
-
-``` py
-from swiftshadow.swiftshadow import QuickProxy
-
-print(QuickProxy())
-```
-
-That was easy.
-
-Head to [Documentation](https://sachin-sankar.github.io/swiftshadow/) to get started.

swiftshadow-1.2.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-swiftshadow/__init__.py,sha256=UGscPyIFECuTgLjcMxp9_QNyfxd6b-msRAtubenBAL0,764
-swiftshadow/cache.py,sha256=tNj07m0Ii_r0wLu9NKTYxOyS8uYeC7BbgFdMnuLqK7Y,411
-swiftshadow/classes.py,sha256=YlXuV5QobEwvIMQDt2sjT173Q-EQbGk6bz5nfyn0Cds,5249
-swiftshadow/constants.py,sha256=FRhoYg8WNaLy8RLDD4BsANlXlY2tctBCdy7sCnkaVY0,6303
-swiftshadow/helpers.py,sha256=RGC-Tq9vWqiddu_KEKYWc_URO-ISm3PXuMBqB_cl7XQ,533
-swiftshadow/providers.py,sha256=qUYUxUuSifwuWWs3KxW2al_T5ee9Lr7MRaTddIR9lyw,2060
-swiftshadow-1.2.0.dist-info/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-swiftshadow-1.2.0.dist-info/METADATA,sha256=RRq0DPKJlgD1gboURK0gtCJ_Fq04P08hinNvz988BjY,2793
-swiftshadow-1.2.0.dist-info/WHEEL,sha256=y4mX-SOX4fYIkonsAGA5N0Oy-8_gI4FXw5HNI1xqvWg,91
-swiftshadow-1.2.0.dist-info/top_level.txt,sha256=GClzVDF5vWSzqHOwgG2ycQAAJXRxd-QOdP1h3YrHOuM,12
-swiftshadow-1.2.0.dist-info/RECORD,,

swiftshadow-1.2.0.dist-info/top_level.txt

@@ -1 +0,0 @@
-swiftshadow