disban 0.1.0__tar.gz

disban-0.1.0/.gitignore

@@ -0,0 +1,39 @@
+/bin/
+/dist/
+*.exe
+.env
+.DS_Store
+
+# Local recovery snapshots contain account and routing state.
+/data/launch-review/backups/
+
+# Authentication/provider credentials
+.env.*
+!.env.example
+
+# Temporary local administrator test credential (hash only)
+/web/data/local-test-login.json
+
+# Generated datasets, runtime state, backups, and local process output.
+/data/*
+!/data/providers.sample.txt
+/web/data/
+*.sqlite*
+*.db
+*.db-wal
+*.db-shm
+*.log
+*.pid
+
+# Dependencies, local tool settings, and standalone build output.
+node_modules/
+/.claude/settings.local.json
+/import-mx
+coverage/
+playwright-report/
+test-results/
+*.tsbuildinfo
+
+# Local Python benchmark bytecode.
+__pycache__/
+*.pyc

disban-0.1.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.5
+Name: disban
+Version: 0.1.0
+Summary: Detect disposable email at signup: classify an email domain as disposable, free, alias, testing, parked or unknown. Works without an API key.
+Project-URL: Homepage, https://disban.io
+Project-URL: Documentation, https://disban.io/docs
+Project-URL: Support, https://disban.io/support
+Author-email: Disban <info@disban.io>
+License-Expression: MIT
+Keywords: burner-email,disposable-email,email-validation,signup,temporary-email
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Email
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# disban
+
+Detect disposable email addresses at signup. `disban` classifies the domain of an email address as **disposable**, **free** (Gmail, Outlook), **alias** (privacy relays such as SimpleLogin), **testing**, **parked** or **unknown**, and tells you whether it can receive mail. Works without an API key. Standard library only.
+
+```sh
+pip install disban
+```
+
+```python
+from disban import is_disposable, signup_decision
+
+is_disposable("someone@yopmail.com")   # True; None means unknown (not verified safe)
+
+decision = signup_decision(email)
+if decision["action"] == "block":
+    raise ValueError("Please use a permanent email address.")
+if decision["action"] == "fix":
+    raise ValueError("That domain can't receive email. Check for a typo.")
+# "allow": create the account; if decision["hold"], hold free credits until the email is confirmed
+```
+
+`signup_decision` fails open: if Disban is slow, unreachable or rate-limited, it allows the signup with `hold: True`.
+
+## FastAPI
+
+```python
+from fastapi import FastAPI, HTTPException
+from disban import signup_decision
+
+app = FastAPI()
+
+@app.post("/signup")
+def signup(email: str):
+    decision = signup_decision(email)
+    if decision["action"] != "allow":
+        raise HTTPException(422, decision["reason"])
+    return {"ok": True, "review": decision.get("hold", False)}
+```
+
+## Limits and API keys
+
+Without a key: 10 checks an hour and 30 a day per network, from your server. For production, set `DISBAN_API_KEY`: a free key includes **2,000 checks a month** with the evidence behind each result. [disban.io/signup](https://disban.io/signup)
+
+```sh
+disban check someone@mailinator.com example.com
+```
+
+[Docs](https://disban.io/docs) · [Methodology](https://disban.io/methodology) · [llms.txt](https://disban.io/llms.txt)

disban-0.1.0/README.md

@@ -0,0 +1,48 @@
+# disban
+
+Detect disposable email addresses at signup. `disban` classifies the domain of an email address as **disposable**, **free** (Gmail, Outlook), **alias** (privacy relays such as SimpleLogin), **testing**, **parked** or **unknown**, and tells you whether it can receive mail. Works without an API key. Standard library only.
+
+```sh
+pip install disban
+```
+
+```python
+from disban import is_disposable, signup_decision
+
+is_disposable("someone@yopmail.com")   # True; None means unknown (not verified safe)
+
+decision = signup_decision(email)
+if decision["action"] == "block":
+    raise ValueError("Please use a permanent email address.")
+if decision["action"] == "fix":
+    raise ValueError("That domain can't receive email. Check for a typo.")
+# "allow": create the account; if decision["hold"], hold free credits until the email is confirmed
+```
+
+`signup_decision` fails open: if Disban is slow, unreachable or rate-limited, it allows the signup with `hold: True`.
+
+## FastAPI
+
+```python
+from fastapi import FastAPI, HTTPException
+from disban import signup_decision
+
+app = FastAPI()
+
+@app.post("/signup")
+def signup(email: str):
+    decision = signup_decision(email)
+    if decision["action"] != "allow":
+        raise HTTPException(422, decision["reason"])
+    return {"ok": True, "review": decision.get("hold", False)}
+```
+
+## Limits and API keys
+
+Without a key: 10 checks an hour and 30 a day per network, from your server. For production, set `DISBAN_API_KEY`: a free key includes **2,000 checks a month** with the evidence behind each result. [disban.io/signup](https://disban.io/signup)
+
+```sh
+disban check someone@mailinator.com example.com
+```
+
+[Docs](https://disban.io/docs) · [Methodology](https://disban.io/methodology) · [llms.txt](https://disban.io/llms.txt)

disban-0.1.0/disban/__init__.py

@@ -0,0 +1,69 @@
+"""Disban: detect disposable email at signup. Standard library only.
+
+    from disban import is_disposable, signup_decision
+    is_disposable("someone@yopmail.com")  # True
+
+Without an API key this uses the keyless endpoint (10/hour, 30/day per network). Set DISBAN_API_KEY
+(or pass api_key=) for 2,000 free checks a month with full evidence: https://disban.io/signup
+"""
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+
+__all__ = ["check", "is_disposable", "signup_decision", "DisbanError"]
+__version__ = "0.1.0"
+BASE = "https://disban.io"
+
+
+class DisbanError(Exception):
+    def __init__(self, message, status=None, retry_after=None):
+        super().__init__(message)
+        self.status = status
+        self.retry_after = retry_after
+
+
+def check(value, api_key=None, timeout=5.0, base_url=BASE):
+    """Classify the domain of an email address or a bare domain. Returns the API's JSON as a dict."""
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError("Pass an email address or domain.")
+    api_key = api_key or os.environ.get("DISBAN_API_KEY")
+    headers = {"User-Agent": f"disban-python/{__version__}"}
+    if api_key:
+        headers.update({"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"})
+        req = urllib.request.Request(f"{base_url}/api/check", json.dumps({"input": value.strip()}).encode(), headers)
+    else:
+        req = urllib.request.Request(f"{base_url}/api/v1/check/{urllib.parse.quote(value.strip(), safe='')}", headers=headers)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as r:
+            return json.load(r)
+    except urllib.error.HTTPError as e:
+        try:
+            message = json.load(e).get("error")
+        except Exception:
+            message = None
+        retry = e.headers.get("Retry-After")
+        raise DisbanError(message or f"Disban returned HTTP {e.code}", e.code, int(retry) if retry and retry.isdigit() else None) from None
+    except (urllib.error.URLError, TimeoutError) as e:
+        raise DisbanError(f"Disban unreachable: {e}") from None
+
+
+def is_disposable(value, **options):
+    """True, False, or None when unknown (not verified safe)."""
+    return check(value, **options).get("disposable")
+
+
+def signup_decision(value, **options):
+    """block disposable/testing, fix undeliverable domains, allow the rest; fail open (hold=True) on errors."""
+    try:
+        r = check(value, **options)
+    except DisbanError as e:
+        return {"action": "allow", "hold": True, "reason": f"disban_{e.status}" if e.status else "disban_unavailable"}
+    routing = r.get("mail_routing")
+    routing = routing.get("status") if isinstance(routing, dict) else routing
+    if routing == "invalid":
+        return {"action": "fix", "reason": "no_mail_route", "result": r}
+    if r.get("category") in ("disposable", "testing"):
+        return {"action": "block", "reason": r["category"], "result": r}
+    return {"action": "allow", "hold": r.get("category") == "unknown", "reason": r.get("category"), "result": r}

disban-0.1.0/disban/__main__.py

@@ -0,0 +1,24 @@
+"""python -m disban check <email|domain>..."""
+import json
+import sys
+
+from . import DisbanError, check
+
+
+def main():
+    args = sys.argv[1:]
+    if len(args) < 2 or args[0] != "check":
+        print("Usage: disban check <email|domain>...\nSet DISBAN_API_KEY for 2,000 free checks a month: https://disban.io/signup")
+        return 1
+    failed = False
+    for value in args[1:]:
+        try:
+            print(json.dumps(check(value)))
+        except DisbanError as e:
+            failed = True
+            print(f"{value}: {e}", file=sys.stderr)
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

disban-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "disban"
+version = "0.1.0"
+description = "Detect disposable email at signup: classify an email domain as disposable, free, alias, testing, parked or unknown. Works without an API key."
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+authors = [{ name = "Disban", email = "info@disban.io" }]
+keywords = ["disposable-email", "temporary-email", "email-validation", "signup", "burner-email"]
+classifiers = ["Programming Language :: Python :: 3", "Topic :: Communications :: Email", "Intended Audience :: Developers"]
+
+[project.urls]
+Homepage = "https://disban.io"
+Documentation = "https://disban.io/docs"
+Support = "https://disban.io/support"
+
+[project.scripts]
+disban = "disban.__main__:main"

disban-0.1.0/test_disban.py

@@ -0,0 +1,30 @@
+import io, json, unittest, urllib.error
+from unittest import mock
+import disban
+
+
+def response(body):
+    return mock.MagicMock(__enter__=lambda s: io.BytesIO(json.dumps(body).encode()), __exit__=lambda *a: False)
+
+
+class Test(unittest.TestCase):
+    def test_keyless_and_keyed_urls(self):
+        with mock.patch("urllib.request.urlopen", return_value=response({"disposable": True})) as u:
+            self.assertTrue(disban.is_disposable("p@x.com", api_key=None))
+            self.assertTrue(u.call_args[0][0].full_url.endswith("/api/v1/check/p%40x.com"))
+        with mock.patch("urllib.request.urlopen", return_value=response({"category": "free"})) as u:
+            disban.check("p@x.com", api_key="k")
+            self.assertEqual(u.call_args[0][0].get_header("Authorization"), "Bearer k")
+
+    def test_fail_open_and_decisions(self):
+        err = urllib.error.HTTPError("u", 429, "x", {"Retry-After": "60"}, io.BytesIO(b'{"error":"limit"}'))
+        with mock.patch("urllib.request.urlopen", side_effect=err):
+            self.assertEqual(disban.signup_decision("x.com", api_key=None), {"action": "allow", "hold": True, "reason": "disban_429"})
+        with mock.patch("urllib.request.urlopen", return_value=response({"category": "unknown", "mail_routing": "invalid"})):
+            self.assertEqual(disban.signup_decision("a@gmial.com", api_key=None)["action"], "fix")
+        with mock.patch("urllib.request.urlopen", return_value=response({"category": "disposable", "mail_routing": "routable"})):
+            self.assertEqual(disban.signup_decision("a@yopmail.com", api_key=None)["action"], "block")
+
+
+if __name__ == "__main__":
+    unittest.main()