feat(pypi): added getfreeproxy package

Author: gfpcom

.github/workflows/ci.yml

@@ -0,0 +1,19 @@
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[dev]
+      - name: Run tests
+        run: pytest -q

.github/workflows/release.yml

@@ -0,0 +1,26 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+      - name: Upgrade pip and install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+      - name: Build distributions
+        run: python -m build
+      - name: Publish to PyPI
+        uses: pypa/[email protected]
+        with:
+          user: __token__
+          password: ${{ secrets.PYPI_API_TOKEN }}

README.md

@@ -0,0 +1,81 @@
+GetFreeProxy Python client
+=================================
+
+Install
+-------
+
+```bash
+pip install .
+```
+
+Usage (sync)
+------------
+
+```py
+from getfreeproxy import FreeProxyClient
+
+client = FreeProxyClient(api_key="YOUR_API_KEY")
+proxies = client.query(country="US", protocol="https")
+for p in proxies:
+    print(p.proxy_url)
+client.close()
+```
+
+Usage (async)
+-------------
+
+```py
+import asyncio
+from getfreeproxy import AsyncFreeProxyClient
+
+async def main():
+    client = AsyncFreeProxyClient(api_key="YOUR_API_KEY")
+    proxies = await client.query(country="US")
+    for p in proxies:
+        print(p.proxy_url)
+    await client.aclose()
+
+asyncio.run(main())
+```
+
+Tests
+-----
+
+Install dev dependencies and run tests:
+
+```bash
+pip install -e .[dev]
+pytest -q
+```
+
+Publishing
+----------
+
+This repository uses a GitHub Actions workflow to publish to PyPI when a tag matching `vX.Y.Z` is pushed.
+
+Preparation (one-time):
+- Create a PyPI API token at https://pypi.org/ (Account > API tokens).
+- Add the token to GitHub repository secrets as `PYPI_API_TOKEN` (Repository Settings > Secrets).
+
+Release steps (recommended via CI):
+
+1. Bump `version` in `pyproject.toml` to the new release version (for example `0.0.2`).
+2. Create a signed or annotated tag and push it:
+
+```bash
+git tag -a v0.0.2 -m "Release v0.0.2"
+git push origin v0.0.2
+```
+
+When the tag is pushed, GitHub Actions will run `.github/workflows/release.yml` and publish the built distributions to PyPI using the `PYPI_API_TOKEN` secret.
+
+You can also build and upload locally (useful for dry-run checks):
+
+```bash
+python -m pip install --upgrade build twine
+python -m build
+python -m twine check dist/*
+# then upload (will require PyPI credentials or token):
+python -m twine upload dist/*
+```
+

getfreeproxy/__init__.py

@@ -0,0 +1,6 @@
+from ._version import __version__
+from .models import Proxy
+from .client import FreeProxyClient
+from .async_client import AsyncFreeProxyClient
+
+__all__ = ["__version__", "Proxy", "FreeProxyClient", "AsyncFreeProxyClient"]

getfreeproxy/_utils.py

@@ -0,0 +1,22 @@
+from typing import Dict, Optional
+
+
+def build_headers(api_key: str, user_agent: Optional[str] = None) -> Dict[str, str]:
+    headers = {"Authorization": f"Bearer {api_key}", "Accept": "application/json"}
+    if user_agent:
+        headers["User-Agent"] = user_agent
+    return headers
+
+
+def extract_error_message(body_text: str, json_body: Optional[Dict] = None) -> str:
+    if json_body:
+        if isinstance(json_body, dict):
+            if "error" in json_body:
+                return str(json_body.get("error"))
+            if "message" in json_body:
+                return str(json_body.get("message"))
+            # fallback to first string-like field
+            for k in ("detail", "code"):
+                if k in json_body:
+                    return str(json_body.get(k))
+    return body_text or "Unknown error"

getfreeproxy/_version.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

getfreeproxy/async_client.py

@@ -0,0 +1,88 @@
+from typing import List, Optional, Dict
+import httpx
+
+from .models import Proxy
+from .exceptions import APIError, InvalidAPIKey, NetworkError, TimeoutError, ParseError
+from ._utils import build_headers, extract_error_message
+
+
+class AsyncFreeProxyClient:
+    def __init__(self, api_key: str, *, base_url: str = "https://api.getfreeproxy.com", timeout: float = 30.0, user_agent: Optional[str] = None, session: Optional[httpx.AsyncClient] = None):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.user_agent = user_agent
+        self._own_session = session is None
+        self.session = session or httpx.AsyncClient(timeout=timeout)
+
+    async def _handle_error_response(self, response: httpx.Response):
+        status = response.status_code
+        text = response.text
+        try:
+            j = response.json()
+        except Exception:
+            j = None
+
+        msg = extract_error_message(text, j)
+        if status == 401:
+            raise InvalidAPIKey(status, msg, raw_body=text)
+        raise APIError(status, msg, raw_body=text)
+
+    async def query(self, country: Optional[str] = None, protocol: Optional[str] = None, page: Optional[int] = None) -> List[Proxy]:
+        url = f"{self.base_url}/v1/proxies"
+        params: Dict[str, str] = {}
+        if country:
+            params["country"] = country
+        if protocol:
+            params["protocol"] = protocol
+        if page is not None:
+            params["page"] = str(page)
+
+        headers = build_headers(self.api_key, self.user_agent)
+        try:
+            resp = await self.session.get(url, headers=headers, params=params)
+        except httpx.ReadTimeout:
+            raise TimeoutError("request timed out")
+        except httpx.RequestError as e:
+            raise NetworkError(str(e))
+
+        if resp.status_code < 200 or resp.status_code >= 300:
+            await self._handle_error_response(resp)
+
+        try:
+            data = resp.json()
+        except Exception as e:
+            raise ParseError(f"failed to parse JSON response: {e}")
+
+        if not isinstance(data, list):
+            raise ParseError("expected JSON array of proxies")
+
+        proxies = [Proxy.from_dict(item) for item in data]
+        return proxies
+
+    async def query_country(self, country: str) -> List[Proxy]:
+        return await self.query(country=country)
+
+    async def query_protocol(self, protocol: str) -> List[Proxy]:
+        return await self.query(protocol=protocol)
+
+    async def query_page(self, page: int) -> List[Proxy]:
+        return await self.query(page=page)
+
+    async def iter_pages(self, *, start: int = 1):
+        page = start
+        while True:
+            items = await self.query(page=page)
+            yield items
+            if not items:
+                break
+            page += 1
+
+    async def raw_request(self, method: str, path: str, **kwargs) -> httpx.Response:
+        url = f"{self.base_url.rstrip('/')}/{path.lstrip('/')}"
+        headers = kwargs.pop("headers", None) or build_headers(self.api_key, self.user_agent)
+        return await self.session.request(method, url, headers=headers, timeout=self.timeout, **kwargs)
+
+    async def aclose(self) -> None:
+        if self._own_session:
+            await self.session.aclose()

getfreeproxy/client.py

@@ -0,0 +1,88 @@
+from typing import List, Optional, Dict
+import httpx
+
+from .models import Proxy
+from .exceptions import APIError, InvalidAPIKey, NetworkError, TimeoutError, ParseError
+from ._utils import build_headers, extract_error_message
+
+
+class FreeProxyClient:
+    def __init__(self, api_key: str, *, base_url: str = "https://api.getfreeproxy.com", timeout: float = 30.0, user_agent: Optional[str] = None, session: Optional[httpx.Client] = None):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.user_agent = user_agent
+        self._own_session = session is None
+        self.session = session or httpx.Client(timeout=timeout)
+
+    def _handle_error_response(self, response: httpx.Response):
+        status = response.status_code
+        text = response.text
+        try:
+            j = response.json()
+        except Exception:
+            j = None
+
+        msg = extract_error_message(text, j)
+        if status == 401:
+            raise InvalidAPIKey(status, msg, raw_body=text)
+        raise APIError(status, msg, raw_body=text)
+
+    def query(self, country: Optional[str] = None, protocol: Optional[str] = None, page: Optional[int] = None) -> List[Proxy]:
+        url = f"{self.base_url}/v1/proxies"
+        params: Dict[str, str] = {}
+        if country:
+            params["country"] = country
+        if protocol:
+            params["protocol"] = protocol
+        if page is not None:
+            params["page"] = str(page)
+
+        headers = build_headers(self.api_key, self.user_agent)
+        try:
+            resp = self.session.get(url, headers=headers, params=params)
+        except httpx.ReadTimeout:
+            raise TimeoutError("request timed out")
+        except httpx.RequestError as e:
+            raise NetworkError(str(e))
+
+        if resp.status_code < 200 or resp.status_code >= 300:
+            self._handle_error_response(resp)
+
+        try:
+            data = resp.json()
+        except Exception as e:
+            raise ParseError(f"failed to parse JSON response: {e}")
+
+        if not isinstance(data, list):
+            raise ParseError("expected JSON array of proxies")
+
+        proxies = [Proxy.from_dict(item) for item in data]
+        return proxies
+
+    def query_country(self, country: str) -> List[Proxy]:
+        return self.query(country=country)
+
+    def query_protocol(self, protocol: str) -> List[Proxy]:
+        return self.query(protocol=protocol)
+
+    def query_page(self, page: int) -> List[Proxy]:
+        return self.query(page=page)
+
+    def iter_pages(self, *, start: int = 1):
+        page = start
+        while True:
+            items = self.query(page=page)
+            yield items
+            if not items:
+                break
+            page += 1
+
+    def raw_request(self, method: str, path: str, **kwargs) -> httpx.Response:
+        url = f"{self.base_url.rstrip('/')}/{path.lstrip('/')}"
+        headers = kwargs.pop("headers", None) or build_headers(self.api_key, self.user_agent)
+        return self.session.request(method, url, headers=headers, timeout=self.timeout, **kwargs)
+
+    def close(self) -> None:
+        if self._own_session:
+            self.session.close()

getfreeproxy/exceptions.py

@@ -0,0 +1,25 @@
+from typing import Optional
+
+
+class APIError(Exception):
+    def __init__(self, status_code: Optional[int], message: str, raw_body: Optional[str] = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.message = message
+        self.raw_body = raw_body
+
+
+class InvalidAPIKey(APIError):
+    pass
+
+
+class NetworkError(Exception):
+    pass
+
+
+class TimeoutError(Exception):
+    pass
+
+
+class ParseError(Exception):
+    pass