cipawebfiltering 1.0.0__py3-none-any.whl

cipawebfiltering/__init__.py

@@ -0,0 +1,25 @@
+"""
+cipawebfiltering — Python client for the CIPA Web Filtering API.
+
+A lightweight wrapper around the REST API at
+https://www.cipawebfiltering.com that lets school districts, libraries,
+and managed service providers look up, filter, and synchronize a
+120-million-domain content classification database from Python.
+"""
+
+from .client import (
+    CIPAWebFilteringClient,
+    CIPAWebFilteringError,
+    AuthenticationError,
+    RateLimitError,
+    NotFoundError,
+)
+
+__version__ = "1.0.0"
+__all__ = [
+    "CIPAWebFilteringClient",
+    "CIPAWebFilteringError",
+    "AuthenticationError",
+    "RateLimitError",
+    "NotFoundError",
+]

cipawebfiltering/client.py

@@ -0,0 +1,209 @@
+"""
+CIPA Web Filtering API client.
+
+Wraps the REST endpoints at https://www.cipawebfiltering.com:
+
+    GET  /api/v1/lookup/{domain}   single domain classification
+    GET  /api/v1/categories        list all 57+ content categories
+    POST /api/v1/bulk-lookup       classify up to 1,000 domains
+    GET  /api/v1/delta             changes since a timestamp
+    GET  /api/v1/stats             database statistics
+
+Only the standard library and ``requests`` are required.
+"""
+
+import time
+from typing import Dict, Iterator, List, Optional
+
+import requests
+
+DEFAULT_BASE_URL = "https://cipawebfiltering.com/api/v1"
+DEFAULT_TIMEOUT = 30
+USER_AGENT = "cipawebfiltering-python/1.0.0 (+https://www.cipawebfiltering.com)"
+
+
+class CIPAWebFilteringError(Exception):
+    """Base exception for all client errors."""
+
+
+class AuthenticationError(CIPAWebFilteringError):
+    """Raised on 401/403 — missing, invalid, expired or revoked API key."""
+
+
+class RateLimitError(CIPAWebFilteringError):
+    """Raised on 429 — request quota exceeded for the current plan."""
+
+
+class NotFoundError(CIPAWebFilteringError):
+    """Raised on 404 — resource or endpoint not found."""
+
+
+class CIPAWebFilteringClient:
+    """
+    Client for the CIPA Web Filtering domain classification API.
+
+    Args:
+        api_key: Your API key from the account dashboard.
+        base_url: Override the API base URL (useful for testing).
+        timeout: Per-request timeout in seconds.
+        max_retries: Automatic retries on 429 / 5xx with backoff.
+
+    Example:
+        >>> from cipawebfiltering import CIPAWebFilteringClient
+        >>> client = CIPAWebFilteringClient("your_api_key")
+        >>> result = client.lookup("example.com")
+        >>> result["categories"]
+        ['Education']
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: int = DEFAULT_TIMEOUT,
+        max_retries: int = 3,
+    ):
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._session = requests.Session()
+        self._session.headers.update(
+            {
+                "Authorization": f"Bearer {api_key}",
+                "Accept": "application/json",
+                "Accept-Encoding": "gzip",
+                "User-Agent": USER_AGENT,
+            }
+        )
+
+    def _request(self, method: str, path: str, **kwargs) -> Dict:
+        url = f"{self.base_url}/{path.lstrip('/')}"
+        last_exc = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                resp = self._session.request(method, url, timeout=self.timeout, **kwargs)
+            except requests.RequestException as exc:
+                last_exc = exc
+                if attempt < self.max_retries:
+                    time.sleep(2 ** attempt)
+                    continue
+                raise CIPAWebFilteringError(f"Request to {url} failed: {exc}") from exc
+
+            if resp.status_code in (200, 201):
+                return resp.json()
+            if resp.status_code == 401:
+                raise AuthenticationError(self._msg(resp, "Invalid or missing API key."))
+            if resp.status_code == 403:
+                raise AuthenticationError(self._msg(resp, "API key revoked or plan does not include this endpoint."))
+            if resp.status_code == 404:
+                raise NotFoundError(self._msg(resp, "Resource not found."))
+            if resp.status_code == 429:
+                if attempt < self.max_retries:
+                    retry_after = int(resp.headers.get("Retry-After", 2 ** attempt))
+                    time.sleep(retry_after)
+                    continue
+                raise RateLimitError(self._msg(resp, "Rate limit exceeded."))
+            if resp.status_code >= 500:
+                if attempt < self.max_retries:
+                    time.sleep(2 ** attempt)
+                    continue
+                raise CIPAWebFilteringError(self._msg(resp, "Server error."))
+            raise CIPAWebFilteringError(self._msg(resp, f"Unexpected status {resp.status_code}."))
+        raise CIPAWebFilteringError(f"Request failed after retries: {last_exc}")
+
+    @staticmethod
+    def _msg(resp: requests.Response, default: str) -> str:
+        try:
+            body = resp.json()
+            return body.get("message") or body.get("error") or default
+        except ValueError:
+            return default
+
+    def lookup(self, domain: str) -> Dict:
+        """
+        Classify a single domain against the CIPA filtering database.
+        Returns multi-label categories, block recommendation, and confidence.
+        """
+        domain = self._clean_domain(domain)
+        return self._request("GET", f"/lookup/{domain}")
+
+    def is_blocked(self, domain: str, policy: str = "default") -> bool:
+        """Convenience boolean — should this domain be blocked under the given policy?"""
+        result = self.lookup(domain)
+        return bool(result.get("should_block", False))
+
+    def bulk_lookup(self, domains: List[str]) -> Dict:
+        """Classify up to 1,000 domains in a single request."""
+        if len(domains) > 1000:
+            raise ValueError("bulk_lookup accepts at most 1000 domains; use bulk_lookup_all().")
+        cleaned = [self._clean_domain(d) for d in domains]
+        return self._request("POST", "/bulk-lookup", json={"domains": cleaned})
+
+    def bulk_lookup_all(self, domains: List[str]) -> List[Dict]:
+        """Classify any number of domains by chunking into 1,000-item requests."""
+        results: List[Dict] = []
+        for i in range(0, len(domains), 1000):
+            chunk = domains[i : i + 1000]
+            resp = self.bulk_lookup(chunk)
+            results.extend(resp.get("results", resp.get("domains", [])))
+        return results
+
+    def categories(self) -> Dict:
+        """Return the full list of 57+ content categories with descriptions."""
+        return self._request("GET", "/categories")
+
+    def domains(
+        self,
+        category: Optional[str] = None,
+        status: Optional[str] = None,
+        cursor: Optional[str] = None,
+    ) -> Dict:
+        """Return one page of classified domains, optionally filtered by category."""
+        params = {}
+        if category:
+            params["category"] = category
+        if status:
+            params["status"] = status
+        if cursor:
+            params["cursor"] = cursor
+        return self._request("GET", "/domains", params=params)
+
+    def iter_domains(self, **filters) -> Iterator[Dict]:
+        """Yield every domain record matching filters, walking cursor-based pagination."""
+        cursor = None
+        while True:
+            page = self.domains(cursor=cursor, **filters)
+            for record in page.get("domains", []):
+                yield record
+            cursor = page.get("next_cursor")
+            if not cursor:
+                break
+
+    def delta(self, since: str) -> Dict:
+        """Return additions and removals since an ISO-8601 timestamp."""
+        return self._request("GET", "/delta", params={"since": since})
+
+    def stats(self) -> Dict:
+        """Return database statistics: total domains, category counts, last update."""
+        return self._request("GET", "/stats")
+
+    @staticmethod
+    def _clean_domain(domain: str) -> str:
+        d = domain.strip().lower()
+        for prefix in ("https://", "http://"):
+            if d.startswith(prefix):
+                d = d[len(prefix):]
+        d = d.split("/")[0].split("?")[0]
+        return d
+
+    def close(self) -> None:
+        self._session.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()

cipawebfiltering-1.0.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alpha Quantum
+
+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.

cipawebfiltering-1.0.0.dist-info/METADATA

@@ -0,0 +1,278 @@
+Metadata-Version: 2.1
+Name: cipawebfiltering
+Version: 1.0.0
+Summary: Python client for the CIPA Web Filtering API — 120M+ classified domains for K-12 schools, districts, and libraries.
+Home-page: https://www.cipawebfiltering.com
+Author: Alpha Quantum
+Author-email: info@alpha-quantum.com
+License: MIT
+Project-URL: Homepage, https://www.cipawebfiltering.com
+Project-URL: API Documentation, https://www.cipawebfiltering.com/docs/integration-guide.php
+Project-URL: Source, https://www.cipawebfiltering.com
+Keywords: cipa,web filtering,content filtering,dns filtering,k-12,school web filter,domain classification,url categorization,children's internet protection act,safe browsing,firewall edl,acceptable use policy,domain database
+Platform: UNKNOWN
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: Proxy Servers
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Networking :: Firewalls
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.20.0
+
+# cipawebfiltering
+
+A production-ready Python client for the [CIPA web filtering](https://www.cipawebfiltering.com) domain classification database — 120 million domains classified across 57+ content categories, purpose-built for K-12 school districts, public libraries, and any organization that must comply with the Children's Internet Protection Act. The package wraps the REST API in a small, typed, dependency-light interface so IT administrators, network engineers, and compliance teams can look up, filter, and synchronize domain intelligence directly from Python.
+
+---
+
+## What is CIPA and why does it matter?
+
+The Children's Internet Protection Act (CIPA) is a United States federal law enacted in 2000 that requires schools and libraries receiving E-Rate funding or LSTA grants to implement internet safety policies and technology protection measures. In practice, this means deploying a web filtering solution that blocks access to content that is obscene, contains child sexual abuse material (CSAM), or is harmful to minors. Districts must also adopt and enforce an acceptable-use policy that covers student activity on and off campus, including 1:1 device programs.
+
+Compliance is not optional: failure to meet CIPA requirements puts E-Rate funding at risk, which for many districts represents hundreds of thousands of dollars annually. Beyond the legal obligation, schools and libraries have a duty of care to protect minors from harmful material while preserving access to educational resources. Over-blocking legitimate content is almost as damaging as under-blocking, because it frustrates teachers, disrupts lesson plans, and erodes trust in the filtering system.
+
+The [CIPA web filtering](https://www.cipawebfiltering.com) database addresses both sides of this challenge. Every domain receives multi-label classification rather than a single verdict, so a domain that hosts both educational and social-media content is tagged with both categories. Policy engines can then make precise blocking decisions per category instead of relying on a blunt allow-or-deny list, dramatically reducing false positives while maintaining full coverage of CIPA-mandated content types.
+
+---
+
+## Installation
+
+```bash
+pip install cipawebfiltering
+```
+
+The only runtime dependency is [`requests`](https://requests.readthedocs.io/). Python 3.7 and newer are supported.
+
+---
+
+## Quick start
+
+```python
+from cipawebfiltering import CIPAWebFilteringClient
+
+client = CIPAWebFilteringClient("your_api_key_here")
+
+# Check a single domain
+result = client.lookup("example-games-site.com")
+print(result["categories"])       # ["Gaming", "Gambling"]
+print(result["should_block"])     # True
+print(result["confidence"])       # 0.97
+
+# Convenience boolean for inline policy decisions
+if client.is_blocked("unknown-domain.net"):
+    enforce_block("unknown-domain.net")
+```
+
+An API key is required and can be obtained from the account dashboard at [cipawebfiltering.com](https://www.cipawebfiltering.com) after subscribing to a plan. Keys are passed automatically as a Bearer token on every request.
+
+---
+
+## Configuration
+
+```python
+client = CIPAWebFilteringClient(
+    api_key="your_api_key_here",
+    base_url="https://cipawebfiltering.com/api/v1",   # override for testing
+    timeout=30,        # per-request timeout in seconds
+    max_retries=3,     # automatic backoff on 429 and 5xx
+)
+```
+
+Transient failures — HTTP 429 rate limits and 5xx server errors — are retried automatically with exponential backoff, honoring the `Retry-After` header when present. Authentication errors raise immediately.
+
+---
+
+## API methods
+
+### Single domain lookup
+
+```python
+result = client.lookup("social-media-site.com")
+```
+
+**Response:**
+
+```json
+{
+  "domain": "social-media-site.com",
+  "categories": ["Social Media", "User-Generated Content"],
+  "should_block": true,
+  "confidence": 0.95,
+  "last_seen": "2026-07-22T08:00:00Z",
+  "dns_active": true
+}
+```
+
+Pass a bare domain — `example.com`, not `https://example.com/page`. Subdomains resolve to their registrable domain automatically. The response includes multi-label categories, a block recommendation based on your policy tier, and a confidence score. Both found and not-found domains return HTTP 200; check the `should_block` boolean or the `categories` array.
+
+### Bulk lookup
+
+Classify up to 1,000 domains in a single request:
+
+```python
+report = client.bulk_lookup(["tiktok.com", "khanacademy.org", "steam-community.ru"])
+for row in report["results"]:
+    print(row["domain"], row["categories"], row["should_block"])
+```
+
+For arbitrarily large inputs, chunking is handled automatically:
+
+```python
+all_results = client.bulk_lookup_all(my_50000_domains)
+blocked = [r for r in all_results if r["should_block"]]
+```
+
+### List categories
+
+Retrieve the full taxonomy of 57+ content categories with descriptions:
+
+```python
+cats = client.categories()
+for cat in cats["categories"]:
+    print(cat["name"], "-", cat["description"])
+```
+
+Categories include CIPA-mandated types such as Adult Content, Violence, Weapons, Drugs, Gambling, and Malware, as well as productivity-relevant categories like Social Media, Streaming, Gaming, and Shopping.
+
+### Sync the full database
+
+For DNS-level filtering, firewall External Dynamic Lists (EDLs), or local proxy caches, stream the entire classified domain list:
+
+```python
+with open("blocked_domains.txt", "w") as fh:
+    for record in client.iter_domains(category="Adult Content"):
+        fh.write(record["domain"] + "\n")
+```
+
+Then keep it current with daily delta syncs instead of re-downloading everything:
+
+```python
+changes = client.delta(since="2026-07-21T00:00:00Z")
+for added in changes["added"]:
+    local_blocklist.add(added["domain"])
+for removed in changes["removed"]:
+    local_blocklist.discard(removed["domain"])
+```
+
+This "full load once, delta forever" pattern lets a modest API quota support millions of local lookups, because the actual matching happens in your own DNS resolver, Redis, SQLite, or flat file.
+
+### Database statistics
+
+```python
+stats = client.stats()
+print(stats["total_domains"])     # 120000000+
+print(stats["last_updated"])      # "2026-07-22T06:00:00Z"
+print(stats["new_today"])         # ~300000
+```
+
+---
+
+## Error handling
+
+The client raises a small, specific exception hierarchy:
+
+```python
+from cipawebfiltering import (
+    CIPAWebFilteringError,
+    AuthenticationError,
+    RateLimitError,
+    NotFoundError,
+)
+
+try:
+    result = client.lookup("example.com")
+except AuthenticationError:
+    # 401/403 — renew or rotate the key
+    ...
+except RateLimitError:
+    # 429 after retries — back off or upgrade the plan
+    ...
+except CIPAWebFilteringError:
+    # any other API or network failure
+    ...
+```
+
+The client is also a context manager, so the underlying HTTP session is cleaned up automatically:
+
+```python
+with CIPAWebFilteringClient("your_api_key_here") as client:
+    print(client.stats())
+```
+
+---
+
+## Use cases
+
+**District-wide filtering:** Apply consistent content policies across every building in a district. Import the database into your DNS resolver or secure web gateway and enforce category-based rules that distinguish between a blocked gaming site and a permitted educational game.
+
+**1:1 Chromebook and laptop programs:** Students take devices home, outside the school firewall. Feed the domain list into a DNS-over-HTTPS resolver or endpoint agent to maintain CIPA compliance on and off campus.
+
+**Public library internet access:** Libraries must filter content on public terminals while respecting patron privacy and intellectual freedom. Multi-label classification lets librarians allow research resources that a single-category system would wrongly block.
+
+**DNS and RPZ filtering:** Export the database as a Response Policy Zone (RPZ) file and load it into BIND, Unbound, or any RPZ-capable resolver. Blocking happens at the DNS layer with zero latency overhead on permitted traffic.
+
+**Firewall EDL integration:** Generate External Dynamic Lists for Palo Alto, Fortinet, or Cisco firewalls. The delta sync endpoint keeps the list current without manual intervention.
+
+**AI tool governance in schools:** The database includes a dedicated AI Tools subcategory covering 16,000+ domains — chatbots, essay writers, homework solvers, deepfake tools, and voice cloning services. Districts can permit approved AI tutoring tools while blocking services that undermine academic integrity.
+
+---
+
+## How the database is built
+
+The classification pipeline processes approximately 300,000 newly discovered domains every day. Each domain is fetched, its content extracted and analyzed through a multi-stage machine learning pipeline that assigns one or more of 57+ content categories. Unlike single-label classifiers that force every domain into exactly one bucket, the multi-label approach recognizes that real-world websites often span multiple topics. A domain hosting both educational math content and an unmoderated chat forum receives both the Education and the Chat/Messaging labels, allowing the policy engine to make a nuanced decision rather than defaulting to a blanket block or allow.
+
+Every classification is verified against a confidence threshold before entering the production database. Domains whose content changes significantly between crawls are re-evaluated and re-labeled automatically. The result is a living dataset that reflects the current state of the web rather than a static snapshot that grows stale within weeks.
+
+All content categories required by CIPA — obscene material, CSAM, and content harmful to minors — are maintained as top-level categories with the highest screening priority. Additional categories cover productivity concerns (Social Media, Streaming, Gaming, Shopping), security threats (Malware, Phishing, Command and Control), and emerging risks (AI Tools, Deepfakes, Cryptocurrency).
+
+## Delivery formats
+
+The [CIPA web filtering](https://www.cipawebfiltering.com) database is available in multiple formats beyond this Python client:
+
+- **REST API** — real-time lookups with millisecond response times
+- **CSV downloads** — daily-refreshed flat files for offline use
+- **DNS / RPZ blocklists** — ready-to-load zone files
+- **PAC files** — browser-level proxy auto-config
+- **Hosts files** — simple domain-to-localhost mapping
+- **Firewall EDLs** — external dynamic lists for next-gen firewalls
+
+---
+
+## Related services
+
+For organizations that need broader domain intelligence beyond CIPA compliance, the following services complement this package:
+
+* **[Website Categorization API](https://www.websitecategorizationapi.com):** Real-time URL classification using the IAB taxonomy across 700+ categories, supporting ad-tech, brand safety, and content analytics.
+
+* **[AI Tools Blocklist](https://www.aitoolsblocklist.com):** A daily-refreshed database of classified AI-tool domains — chatbots, code assistants, image generators, voice cloners — organized into functional categories for granular acceptable-use policies.
+
+* **[Web Filtering Database](https://www.webfilteringdatabase.com):** Enterprise-grade downloadable database of 100 million domains across 59 content categories, designed for DNS-level blocking in firewalls, proxies, and secure web gateways.
+
+* **[URL Categorization Database](https://www.urlcategorizationdatabase.com):** Categorized domains at enterprise scale for contextual targeting, brand safety, and large-scale analytics.
+
+* **[Phishing Detection API](https://www.phishingdetectionapi.com):** Real-time phishing domain detection powered by a daily-updated database of 390,000+ DNS-verified active phishing domains, built for cybersecurity teams, email providers, and safe browsing implementations.
+
+---
+
+## Links
+
+- Product and documentation: [https://www.cipawebfiltering.com](https://www.cipawebfiltering.com)
+- FCC — Children's Internet Protection Act: [https://www.fcc.gov/consumers/guides/childrens-internet-protection-act](https://www.fcc.gov/consumers/guides/childrens-internet-protection-act)
+- E-Rate program: [https://www.fcc.gov/general/e-rate-program](https://www.fcc.gov/general/e-rate-program)
+
+## License
+
+MIT
+
+

cipawebfiltering-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+cipawebfiltering/__init__.py,sha256=4h7EDEi_Hpb1cQ8iM7ecOHn0W6RPtSvsaSxRjwKGbnQ,632
+cipawebfiltering/client.py,sha256=uzcUUlhR74tRpnqMs4e4VSB10VZOF2-r94006ZdBeng,7789
+cipawebfiltering-1.0.0.dist-info/LICENSE,sha256=-kjrwollysEMZkPQkJIq5zyefl9XyPw5egz8knSXiB4,1070
+cipawebfiltering-1.0.0.dist-info/METADATA,sha256=hka-j1tcx8qryr6zsNwJO49XXb96mM5N-3ePUlPIjNc,13747
+cipawebfiltering-1.0.0.dist-info/WHEEL,sha256=tZoeGjtWxWRfdplE7E3d45VPlLNQnvbKiYnx7gwAy8A,92
+cipawebfiltering-1.0.0.dist-info/top_level.txt,sha256=rSgdN_xGPN4vAGf_jCA6tT31i5-ZXawyFojeBypUsVY,17
+cipawebfiltering-1.0.0.dist-info/RECORD,,

cipawebfiltering-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: bdist_wheel (0.45.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cipawebfiltering-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cipawebfiltering