vpndetection 1.0.0__tar.gz

vpndetection-1.0.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+
+# Build output.
+build/
+dist/
+*.egg-info/
+
+# Virtualenvs, including any made to run codegen. Keep them out of the tree entirely.
+.venv/
+venv/
+.venv-*/
+
+# Tool caches.
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

vpndetection-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mslm Dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+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.

vpndetection-1.0.0/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.5
+Name: vpndetection
+Version: 1.0.0
+Summary: Official Python client library for the VPNDetection API. Detect VPNs, proxies, Tor, hosting and CDN IPs.
+Project-URL: Homepage, https://vpndetection.io
+Project-URL: Documentation, https://docs.vpndetection.io
+Project-URL: Source, https://github.com/vpndetection-io/sdk-python
+Project-URL: Issues, https://github.com/vpndetection-io/sdk-python/issues
+Author-email: Mslm Dev <support@vpndetection.io>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cdn,datacenter-proxy,fraud-prevention,hosting,ip-geolocation,ip-intelligence,mobile-proxy,proxy-detection,relay,residential-proxy,tor,vpn,vpn-detection
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Internet
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: attrs>=22.2.0
+Requires-Dist: cachetools>=5.3
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: openapi-python-client<0.30,>=0.29; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# [<img src="https://s3.vpndetection.io/vpndetection-public/brand/mark.svg" alt="VPNDetection" width="24"/>](https://vpndetection.io/) VPNDetection Python Client Library
+
+[![PyPI](https://img.shields.io/pypi/v/vpndetection.svg)](https://pypi.org/project/vpndetection/)
+[![license](https://img.shields.io/pypi/l/vpndetection.svg)](LICENSE)
+
+The official Python client library for the [VPNDetection](https://vpndetection.io) API.
+
+The library helps you query VPNDetection's APIs for anonymity detection including VPNs, residential proxies, Tor nodes, hosting servers, CDNs, relays and more.
+
+## Getting Started
+
+```bash
+pip install vpndetection
+```
+
+Requires Python 3.11 or newer. Type hints are included, and the package ships `py.typed`.
+
+## Usage
+
+**No API key needed to start.** The free tier answers `ip` and `is_vpn`, and allows 1000 requests per day per source address.
+
+```python
+from vpndetection import VPNDetection
+
+client = VPNDetection()
+
+result = client.lookup("45.83.91.1")
+print(result.is_vpn)   # True
+```
+
+The client holds an HTTP connection pool, so use it as a context manager, or call `client.close()` when you are done with it:
+
+```python
+with VPNDetection() as client:
+    print(client.lookup("45.83.91.1").is_vpn)
+```
+
+### With an API key
+
+An API key raises your quota, and raises your features on a paid plan. Create one in the [console](https://app.vpndetection.io), then pass it in:
+
+```python
+import os
+
+client = VPNDetection(os.environ["VPNDETECTION_API_KEY"])
+
+result = client.lookup("45.83.91.1")
+print(result.is_vpn)          # True
+print(result.vpn.provider)    # 'mullvad'
+print(result.is_hosting)      # True
+print(result.hosting.provider)
+```
+
+### Async
+
+Everything above works the same way under asyncio, with `AsyncVPNDetection`:
+
+```python
+import asyncio
+from vpndetection import AsyncVPNDetection
+
+async def main():
+    async with AsyncVPNDetection() as client:
+        result = await client.lookup("45.83.91.1")
+        print(result.is_vpn)   # True
+
+asyncio.run(main())
+```
+
+### Batch lookup
+
+You can do batch lookups with a list, which parallelizes requests for you efficiently:
+
+```python
+results = client.lookup_batch(["45.83.91.1", "8.8.8.8", "1.1.1.1"])
+
+for ip, result in results.items():
+    if isinstance(result, Exception):
+        print(f"{ip}: {result}")
+        continue
+    print(f"{ip}: {result.is_vpn}")
+```
+
+Results are keyed by address, so duplicates in your list collapse into a single request and one address failing never loses the rest.
+
+Concurrency and other variables are configurable per-call:
+
+```python
+results = client.lookup_batch(many_ips, concurrency=32, retries=4)
+```
+
+### Caching
+
+Answers are cached by default, so repeat lookups of the same address are free:
+
+```python
+client = VPNDetection()
+
+result = client.lookup("45.83.91.1")
+print(result.is_vpn)    # True, API request
+
+result2 = client.lookup("45.83.91.1")
+print(result2.is_vpn)   # True, no API request, result was cached
+```
+
+You can change the default cache variables (max size, TTL in seconds, etc) on initialization, or even disable it:
+
+```python
+client = VPNDetection(cache_max_size=50_000, cache_ttl=6 * 60 * 60)
+client_no_cache = VPNDetection(cache=False)
+```
+
+### Private and reserved addresses
+
+Private, loopback, link-local, documentation and multicast addresses (and their IPv6 equivalents, including the 6to4 and Teredo ranges) can never be VPN or proxy infrastructure. The library answers them locally, so they cost no request and no quota:
+
+```python
+result = client.lookup("192.168.1.1")
+result.is_bogon   # True, this answer was computed rather than served
+result.is_vpn     # False
+```
+
+The check is available on the client, which is handy when your inputs are addresses anyway:
+
+```python
+client.is_bogon("10.0.0.1")   # True
+client.is_bogon("8.8.8.8")    # False
+```
+
+It is also importable on its own, if you want it without a client:
+
+```python
+from vpndetection import is_bogon
+
+is_bogon("10.0.0.1")   # True
+```
+
+### Errors
+
+Failures raise a `VPNDetectionError` carrying a `kind` and a `retryable` flag:
+
+```python
+from vpndetection import VPNDetectionError
+
+try:
+    client.lookup("1.1.1.1")
+except VPNDetectionError as err:
+    print(err.kind, err.retryable)
+```
+
+`kind` is one of `bad_request`, `unauthorized`, `forbidden`, `rate_limited`, `quota_exceeded`, `server_error` or `network`.
+
+Note that `rate_limited` and `quota_exceeded` both arrive as HTTP 429 and are not the same thing. A rate limit is when the API faces extreme traffic bursts and so retrying later works; but a spent quota needs your allowance raised or the window to roll over. The library retries rate limits for you, but not if your quota is exceeded.
+
+### Database downloads
+
+If your key carries the `db.download` scope, the licensed datasets are available through `client.database`. `list` answers dataset families, and the ids the other calls take come from each family's `versions`. There are three ways to get a database: the time-limited link, the bytes, or straight to a file, which streams so nothing bigger than a chunk is ever held in memory:
+
+```python
+datasets = client.database.list()
+
+url = client.database.download_url("vpn_ip_extended_v1", "mmdb")
+raw = client.database.download_bytes("cdn_ip_v1", "csvgz")
+written = client.database.download("vpn_ip_extended_v1", "mmdb", "./vpn_ip_extended_v1.mmdb")
+```
+
+`download_bytes` holds the whole file in memory, and the catalog runs from `cdn_ip_v1` at 10 KB to `resproxy_ip_90d_v1` at 1.79 GB, so use `download` for anything you have not measured.
+
+### Fields your plan does not include
+
+Only `ip` and `is_vpn` come back on every plan. The rest are `None` when your plan does not include them, which means "not in your plan" rather than "checked, and no".
+
+```python
+result.flagged("is_hosting")   # False rather than None on a plan without it
+result.is_hosting is None      # True when hosting is not in your plan
+```
+
+## Other Libraries
+
+There are official VPNDetection client libraries available for many languages including PHP, Python, Go, Java, Ruby, and many popular frameworks such as Django, Rails, and Laravel. See our GitHub at https://github.com/vpndetection-io for more.
+
+## About VPNDetection
+
+VPN Detection API: Accurate anonymity detection identifying VPNs, residential proxies, hosting servers, Tor nodes, CDNs, relays and more.
+
+[<img src="https://s3.vpndetection.io/vpndetection-public/brand/mark.svg" alt="VPNDetection" width="96"/>](https://vpndetection.io/)
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

vpndetection-1.0.0/README.md

@@ -0,0 +1,190 @@
+# [<img src="https://s3.vpndetection.io/vpndetection-public/brand/mark.svg" alt="VPNDetection" width="24"/>](https://vpndetection.io/) VPNDetection Python Client Library
+
+[![PyPI](https://img.shields.io/pypi/v/vpndetection.svg)](https://pypi.org/project/vpndetection/)
+[![license](https://img.shields.io/pypi/l/vpndetection.svg)](LICENSE)
+
+The official Python client library for the [VPNDetection](https://vpndetection.io) API.
+
+The library helps you query VPNDetection's APIs for anonymity detection including VPNs, residential proxies, Tor nodes, hosting servers, CDNs, relays and more.
+
+## Getting Started
+
+```bash
+pip install vpndetection
+```
+
+Requires Python 3.11 or newer. Type hints are included, and the package ships `py.typed`.
+
+## Usage
+
+**No API key needed to start.** The free tier answers `ip` and `is_vpn`, and allows 1000 requests per day per source address.
+
+```python
+from vpndetection import VPNDetection
+
+client = VPNDetection()
+
+result = client.lookup("45.83.91.1")
+print(result.is_vpn)   # True
+```
+
+The client holds an HTTP connection pool, so use it as a context manager, or call `client.close()` when you are done with it:
+
+```python
+with VPNDetection() as client:
+    print(client.lookup("45.83.91.1").is_vpn)
+```
+
+### With an API key
+
+An API key raises your quota, and raises your features on a paid plan. Create one in the [console](https://app.vpndetection.io), then pass it in:
+
+```python
+import os
+
+client = VPNDetection(os.environ["VPNDETECTION_API_KEY"])
+
+result = client.lookup("45.83.91.1")
+print(result.is_vpn)          # True
+print(result.vpn.provider)    # 'mullvad'
+print(result.is_hosting)      # True
+print(result.hosting.provider)
+```
+
+### Async
+
+Everything above works the same way under asyncio, with `AsyncVPNDetection`:
+
+```python
+import asyncio
+from vpndetection import AsyncVPNDetection
+
+async def main():
+    async with AsyncVPNDetection() as client:
+        result = await client.lookup("45.83.91.1")
+        print(result.is_vpn)   # True
+
+asyncio.run(main())
+```
+
+### Batch lookup
+
+You can do batch lookups with a list, which parallelizes requests for you efficiently:
+
+```python
+results = client.lookup_batch(["45.83.91.1", "8.8.8.8", "1.1.1.1"])
+
+for ip, result in results.items():
+    if isinstance(result, Exception):
+        print(f"{ip}: {result}")
+        continue
+    print(f"{ip}: {result.is_vpn}")
+```
+
+Results are keyed by address, so duplicates in your list collapse into a single request and one address failing never loses the rest.
+
+Concurrency and other variables are configurable per-call:
+
+```python
+results = client.lookup_batch(many_ips, concurrency=32, retries=4)
+```
+
+### Caching
+
+Answers are cached by default, so repeat lookups of the same address are free:
+
+```python
+client = VPNDetection()
+
+result = client.lookup("45.83.91.1")
+print(result.is_vpn)    # True, API request
+
+result2 = client.lookup("45.83.91.1")
+print(result2.is_vpn)   # True, no API request, result was cached
+```
+
+You can change the default cache variables (max size, TTL in seconds, etc) on initialization, or even disable it:
+
+```python
+client = VPNDetection(cache_max_size=50_000, cache_ttl=6 * 60 * 60)
+client_no_cache = VPNDetection(cache=False)
+```
+
+### Private and reserved addresses
+
+Private, loopback, link-local, documentation and multicast addresses (and their IPv6 equivalents, including the 6to4 and Teredo ranges) can never be VPN or proxy infrastructure. The library answers them locally, so they cost no request and no quota:
+
+```python
+result = client.lookup("192.168.1.1")
+result.is_bogon   # True, this answer was computed rather than served
+result.is_vpn     # False
+```
+
+The check is available on the client, which is handy when your inputs are addresses anyway:
+
+```python
+client.is_bogon("10.0.0.1")   # True
+client.is_bogon("8.8.8.8")    # False
+```
+
+It is also importable on its own, if you want it without a client:
+
+```python
+from vpndetection import is_bogon
+
+is_bogon("10.0.0.1")   # True
+```
+
+### Errors
+
+Failures raise a `VPNDetectionError` carrying a `kind` and a `retryable` flag:
+
+```python
+from vpndetection import VPNDetectionError
+
+try:
+    client.lookup("1.1.1.1")
+except VPNDetectionError as err:
+    print(err.kind, err.retryable)
+```
+
+`kind` is one of `bad_request`, `unauthorized`, `forbidden`, `rate_limited`, `quota_exceeded`, `server_error` or `network`.
+
+Note that `rate_limited` and `quota_exceeded` both arrive as HTTP 429 and are not the same thing. A rate limit is when the API faces extreme traffic bursts and so retrying later works; but a spent quota needs your allowance raised or the window to roll over. The library retries rate limits for you, but not if your quota is exceeded.
+
+### Database downloads
+
+If your key carries the `db.download` scope, the licensed datasets are available through `client.database`. `list` answers dataset families, and the ids the other calls take come from each family's `versions`. There are three ways to get a database: the time-limited link, the bytes, or straight to a file, which streams so nothing bigger than a chunk is ever held in memory:
+
+```python
+datasets = client.database.list()
+
+url = client.database.download_url("vpn_ip_extended_v1", "mmdb")
+raw = client.database.download_bytes("cdn_ip_v1", "csvgz")
+written = client.database.download("vpn_ip_extended_v1", "mmdb", "./vpn_ip_extended_v1.mmdb")
+```
+
+`download_bytes` holds the whole file in memory, and the catalog runs from `cdn_ip_v1` at 10 KB to `resproxy_ip_90d_v1` at 1.79 GB, so use `download` for anything you have not measured.
+
+### Fields your plan does not include
+
+Only `ip` and `is_vpn` come back on every plan. The rest are `None` when your plan does not include them, which means "not in your plan" rather than "checked, and no".
+
+```python
+result.flagged("is_hosting")   # False rather than None on a plan without it
+result.is_hosting is None      # True when hosting is not in your plan
+```
+
+## Other Libraries
+
+There are official VPNDetection client libraries available for many languages including PHP, Python, Go, Java, Ruby, and many popular frameworks such as Django, Rails, and Laravel. See our GitHub at https://github.com/vpndetection-io for more.
+
+## About VPNDetection
+
+VPN Detection API: Accurate anonymity detection identifying VPNs, residential proxies, hosting servers, Tor nodes, CDNs, relays and more.
+
+[<img src="https://s3.vpndetection.io/vpndetection-public/brand/mark.svg" alt="VPNDetection" width="96"/>](https://vpndetection.io/)
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

vpndetection-1.0.0/integration/scripts/run.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+
+"""Runs the integration suite against the package as PUBLISHED on PyPI, which is the one
+thing the unit suite cannot check: that suite tests this working tree, so it stays green
+through a tag that was never pushed, an sdist that ships no `src`, or a wheel a consumer
+cannot import.
+
+    python3 scripts/run.py         # from integration/, with any python3 on PATH
+    ./scripts/run.sh               # the same thing in docker
+
+Two conditions make the run meaningless rather than failing, and each one skips with a
+reason instead:
+
+  1. Nothing on PyPI satisfies the constraint in requirements.txt. Before the first
+     release there is no artifact to test.
+  2. A tier's staging key is missing. The unauthenticated tests still run, and each tier
+     without a key skips from inside the suite, so the skip and its reason land in the
+     pytest output rather than in this script's preamble.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import venv
+from pathlib import Path
+
+INTEGRATION = Path(__file__).resolve().parent.parent
+PACKAGE = "vpndetection"
+
+# Imported before anything is installed, so it must not touch the package under test.
+sys.path.insert(0, str(INTEGRATION))
+import tiers
+
+
+def main() -> int:
+    constraint = requirement()
+    python = build_venv()
+
+    resolved = resolve(python, constraint)
+    if resolved is None:
+        skip(f"nothing on PyPI satisfies {constraint}, so there is no published artifact to test")
+        return 0
+    version, url = resolved
+    print(f"==> {constraint} matches published {version} at {url}")
+
+    with_key = [rung.tier for rung in tiers.observable()]
+    absent = [rung.tier for rung in tiers.RUNGS if rung.skip_reason() is not None]
+    print(f"==> tiers with a key: {', '.join(with_key)}")
+    if absent:
+        notice(f"no staging key for {', '.join(absent)}: those tiers are skipped")
+
+    run([str(python), "-m", "pip", "install", "--quiet", "-r", "requirements.txt"])
+    # The gate that proves the suite is testing the release rather than the tree beside it
+    # lives in conftest.py, where the import has actually happened.
+    return subprocess.run([str(python), "-m", "pytest"], cwd=INTEGRATION, check=False).returncode
+
+
+def requirement() -> str:
+    """The package constraint, read from requirements.txt so there is one copy of it."""
+    for line in (INTEGRATION / "requirements.txt").read_text().splitlines():
+        line = line.split("#")[0].strip()
+        if line.startswith(PACKAGE):
+            return line
+    raise SystemExit(f"requirements.txt names no {PACKAGE} constraint")
+
+
+def build_venv() -> Path:
+    """A virtualenv of its own, rebuilt every run.
+
+    Kept rather than reused so a daily run always resolves the constraint afresh: a venv
+    carrying yesterday's install would go on testing whatever the first run happened to
+    pick and stop noticing new releases.
+    """
+    root = INTEGRATION / ".venv"
+    shutil.rmtree(root, ignore_errors=True)
+    venv.EnvBuilder(with_pip=True, clear=True).create(root)
+    python = root / "bin" / "python"
+    run([str(python), "-m", "pip", "install", "--quiet", "--upgrade", "pip"])
+    return python
+
+
+def resolve(python: Path, constraint: str) -> tuple[str, str] | None:
+    """The version pip WOULD install, and where from, or None when nothing satisfies it.
+
+    This is pip's own resolver rather than a query against the JSON API, so the answer is
+    exactly what an install would see, yanked releases and requires-python included. A
+    package that does not exist and a constraint nothing satisfies both report the same
+    thing, and both mean the same thing here.
+    """
+    with tempfile.TemporaryDirectory() as scratch:
+        report = Path(scratch) / "report.json"
+        result = subprocess.run(
+            [
+                str(python),
+                "-m",
+                "pip",
+                "install",
+                "--dry-run",
+                "--no-deps",
+                "--quiet",
+                "--report",
+                str(report),
+                constraint,
+            ],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if result.returncode != 0:
+            if "no matching distribution" in result.stderr.lower():
+                return None
+            raise SystemExit(f"pip could not resolve {constraint}:\n{result.stderr}")
+        install = json.loads(report.read_text())["install"]
+
+    version = install[0]["metadata"]["version"]
+    url = install[0]["download_info"]["url"]
+    # A `file://` here is a local build being passed off as a release, which every test
+    # downstream would then pass against.
+    if not url.startswith("https://"):
+        raise SystemExit(f"{PACKAGE} resolved to {url}, which is not a registry")
+    return version, url
+
+
+def run(command: list[str]) -> None:
+    print(f"==> {' '.join(Path(part).name if '/' in part else part for part in command)}")
+    subprocess.run(command, cwd=INTEGRATION, check=True)
+
+
+def skip(reason: str) -> None:
+    print(f"==> SKIPPED: {reason}")
+    notice(f"Integration suite skipped: {reason}")
+
+
+def notice(message: str) -> None:
+    """Surfaced on the workflow run itself, so a skip is visible without opening the log
+    and reading to the end of it."""
+    if os.environ.get("GITHUB_ACTIONS") == "true":
+        print(f"::notice title=Integration::{message}")
+
+
+if __name__ == "__main__":
+    sys.exit(main())

vpndetection-1.0.0/integration/scripts/run.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+
+# The integration suite in docker, for a box whose python has no way to build a
+# virtualenv or reach PyPI. CI runs `python3 scripts/run.py` directly; this is
+# the same entry point with an interpreter around it.
+#
+#   ./scripts/run.sh
+#
+# The four tier keys are read from the environment and passed through by NAME, so
+# no key ever reaches a command line. Only the integration directory is mounted:
+# the suite must see the published package rather than the source beside it.
+
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+PYTHON_IMAGE="${PYTHON_IMAGE:-python:3.13-slim}"
+
+docker run --rm \
+    -v "$PWD:/app" -w /app \
+    -e PIP_ROOT_USER_ACTION=ignore \
+    -e VPNDETECTION_STAGING_KEY_FREE \
+    -e VPNDETECTION_STAGING_KEY_STARTER \
+    -e VPNDETECTION_STAGING_KEY_SCALE \
+    -e VPNDETECTION_STAGING_KEY_MAX \
+    "$PYTHON_IMAGE" python3 scripts/run.py "$@"