unprofane 0.1.0__tar.gz

unprofane-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tomer N. Marketing and Sales Ltd
+
+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.

unprofane-0.1.0/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.5
+Name: unprofane
+Version: 0.1.0
+Summary: Unprofane: a profanity and toxicity API that is hard to fool. Sync and async client with retries and a batch helper.
+Project-URL: Homepage, https://unprofane.com
+Project-URL: Documentation, https://unprofane.com/docs/
+Project-URL: Source, https://github.com/unprofane/unprofane-python
+Project-URL: Issues, https://github.com/unprofane/unprofane-python/issues
+Author-email: Unprofane <hello@unprofane.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: filter,moderation,perspective-api,profanity,toxicity
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# unprofane
+
+The Python client for [Unprofane](https://unprofane.com), a profanity and toxicity API that is hard to fool.
+
+```bash
+pip install unprofane
+```
+
+```python
+from unprofane import Unprofane
+
+client = Unprofane("up_live_YOUR_KEY")
+r = client.check("xXsh1tXx", context="username", policy="teen")
+if not r["allowed"]:
+    print(r["action"], r["evasion"], r["censored"])
+```
+
+Async:
+
+```python
+from unprofane import AsyncUnprofane
+
+async with AsyncUnprofane("up_live_YOUR_KEY") as client:
+    r = await client.check("hello", context="comment")
+```
+
+`check`, `check_batch` (up to 100), `check_many` (any number, chunked), `feedback`, `usage`, `get_list`, `put_list`, `delete_list`. Retries 429 and 5xx with jitter and honours `Retry-After`; other failures raise `UnprofaneError` with the problem details and the request id. Docs: https://unprofane.com/docs/.

unprofane-0.1.0/README.md

@@ -0,0 +1,27 @@
+# unprofane
+
+The Python client for [Unprofane](https://unprofane.com), a profanity and toxicity API that is hard to fool.
+
+```bash
+pip install unprofane
+```
+
+```python
+from unprofane import Unprofane
+
+client = Unprofane("up_live_YOUR_KEY")
+r = client.check("xXsh1tXx", context="username", policy="teen")
+if not r["allowed"]:
+    print(r["action"], r["evasion"], r["censored"])
+```
+
+Async:
+
+```python
+from unprofane import AsyncUnprofane
+
+async with AsyncUnprofane("up_live_YOUR_KEY") as client:
+    r = await client.check("hello", context="comment")
+```
+
+`check`, `check_batch` (up to 100), `check_many` (any number, chunked), `feedback`, `usage`, `get_list`, `put_list`, `delete_list`. Retries 429 and 5xx with jitter and honours `Retry-After`; other failures raise `UnprofaneError` with the problem details and the request id. Docs: https://unprofane.com/docs/.

unprofane-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "unprofane"
+version = "0.1.0"
+description = "Unprofane: a profanity and toxicity API that is hard to fool. Sync and async client with retries and a batch helper."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Unprofane", email = "hello@unprofane.com" }]
+keywords = ["profanity", "toxicity", "moderation", "filter", "perspective-api"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = ["httpx>=0.25"]
+
+[project.optional-dependencies]
+test = ["pytest>=8", "pytest-asyncio>=0.23"]
+
+[project.urls]
+Homepage = "https://unprofane.com"
+Documentation = "https://unprofane.com/docs/"
+Source = "https://github.com/unprofane/unprofane-python"
+Issues = "https://github.com/unprofane/unprofane-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["unprofane"]
+
+[tool.hatch.build.targets.sdist]
+include = ["unprofane", "tests", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

unprofane-0.1.0/tests/test_client.py

@@ -0,0 +1,97 @@
+import json
+
+import httpx
+import pytest
+
+from unprofane import AsyncUnprofane, Unprofane, UnprofaneError
+from unprofane.client import backoff
+
+
+def transport(handler):
+    return httpx.MockTransport(handler)
+
+
+def test_check_sends_the_key_and_body():
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["url"] = str(request.url)
+        seen["auth"] = request.headers["authorization"]
+        seen["body"] = json.loads(request.content)
+        return httpx.Response(200, json={"allowed": False, "action": "block"})
+
+    with Unprofane("up_test_abc", transport=transport(handler)) as client:
+        r = client.check("xXsh1tXx", context="username", policy="teen")
+    assert r["action"] == "block"
+    assert seen["url"] == "https://api.unprofane.com/v1/check"
+    assert seen["auth"] == "Bearer up_test_abc"
+    assert seen["body"] == {"text": "xXsh1tXx", "context": "username", "policy": "teen"}
+
+
+def test_refuses_a_foreign_key():
+    with pytest.raises(TypeError):
+        Unprofane("sk-nope")
+
+
+def test_retries_then_raises_a_problem(monkeypatch):
+    monkeypatch.setattr("unprofane.client.time.sleep", lambda s: None)
+    calls = {"n": 0}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls["n"] += 1
+        if calls["n"] == 1:
+            return httpx.Response(429, json={"title": "Too many requests.", "status": 429}, headers={"retry-after": "0"})
+        if calls["n"] == 2:
+            return httpx.Response(503, text="down")
+        return httpx.Response(200, json={"id": "chk_1", "allowed": True})
+
+    with Unprofane("up_live_k", transport=transport(handler)) as client:
+        assert client.check("hi")["allowed"] is True
+    assert calls["n"] == 3
+
+    def bad(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(400, json={"type": "https://unprofane.com/docs/errors/invalid-request", "title": "The request body is not valid.", "status": 400, "detail": "text: too long"}, headers={"request-id": "req_9"})
+
+    with Unprofane("up_live_k", transport=transport(bad)) as client:
+        with pytest.raises(UnprofaneError) as e:
+            client.check("")
+    assert e.value.status == 400
+    assert "invalid-request" in e.value.problem["type"]
+    assert e.value.request_id == "req_9"
+
+
+def test_check_many_chunks_and_keeps_order():
+    def handler(request: httpx.Request) -> httpx.Response:
+        items = json.loads(request.content)["items"]
+        return httpx.Response(200, json={"results": [{"id": i["id"], "result": {"allowed": i["text"] != "bad"}} for i in items], "counted": len(items)})
+
+    texts = ["bad" if i == 137 else f"t{i}" for i in range(250)]
+    with Unprofane("up_live_k", transport=transport(handler)) as client:
+        results = client.check_many(texts, context="comment")
+        with pytest.raises(ValueError):
+            client.check_batch([{"id": str(i), "text": "x"} for i in range(101)])
+    assert len(results) == 250
+    assert results[137] == {"id": "137", "result": {"allowed": False}}
+    assert results[249]["id"] == "249"
+
+
+def test_backoff():
+    assert backoff(1, "2") == 2.0
+    assert all(backoff(5, None) <= 8.0 for _ in range(20))
+    assert backoff(1, "soon") <= 0.5
+
+
+async def test_async_client_and_lists():
+    def handler(request: httpx.Request) -> httpx.Response:
+        if request.method == "DELETE":
+            return httpx.Response(204)
+        if request.url.path.endswith("/lists/allow"):
+            return httpx.Response(200, json={"kind": "allow", "terms": ["Scunthorpe"], "version": 2})
+        items = json.loads(request.content)["items"]
+        return httpx.Response(200, json={"results": [{"id": i["id"], "result": {"allowed": True}} for i in items], "counted": len(items)})
+
+    async with AsyncUnprofane("up_live_k", transport=httpx.MockTransport(handler)) as client:
+        assert (await client.get_list("prj_1", "allow"))["terms"] == ["Scunthorpe"]
+        assert await client.delete_list("prj_1", "allow") is None
+        results = await client.check_many([f"t{i}" for i in range(150)], concurrency=3)
+    assert [r["id"] for r in results] == [str(i) for i in range(150)]

unprofane-0.1.0/unprofane/__init__.py

@@ -0,0 +1,5 @@
+"""Unprofane: a profanity and toxicity API that is hard to fool."""
+
+from .client import AsyncUnprofane, Unprofane, UnprofaneError, __version__
+
+__all__ = ["AsyncUnprofane", "Unprofane", "UnprofaneError", "__version__"]

unprofane-0.1.0/unprofane/client.py

@@ -0,0 +1,228 @@
+"""The sync and async clients: one method per endpoint, retries with jitter
+on 429 and 5xx honouring Retry-After, a batch helper that chunks by 100.
+No dependency beyond httpx. Responses are plain dicts in the API's own
+field names (https://unprofane.com/docs/api/), so nothing here can drift
+from the contract without the contract changing."""
+
+from __future__ import annotations
+
+import random
+import time
+from typing import Any, Dict, Iterable, List, Optional, Union
+
+import httpx
+
+__version__ = "0.1.0"
+_DEFAULT_BASE = "https://api.unprofane.com"
+_RETRYABLE = {429, 502, 503, 504}
+_MAX_BATCH = 100
+
+Policy = Union[str, Dict[str, str]]
+
+
+class UnprofaneError(Exception):
+    """A failure the API answered, with its problem details."""
+
+    def __init__(self, message: str, status: int, problem: Optional[dict], request_id: Optional[str]):
+        super().__init__(message)
+        self.status = status
+        self.problem = problem
+        self.request_id = request_id
+
+
+def backoff(attempt: int, retry_after: Optional[str]) -> float:
+    """Exponential with full jitter, capped at eight seconds; Retry-After wins."""
+    if retry_after is not None:
+        try:
+            value = float(retry_after)
+            if value >= 0:
+                return min(value, 30.0)
+        except ValueError:
+            pass
+    return random.random() * min(8.0, 0.25 * (2**attempt))
+
+
+def _check_key(api_key: str) -> None:
+    if not api_key or not api_key.startswith(("up_live_", "up_test_", "up_pk_")):
+        raise TypeError("pass an API key (up_live_…, up_test_… or up_pk_…)")
+
+
+def _problem(res: httpx.Response) -> Optional[dict]:
+    try:
+        body = res.json()
+    except ValueError:
+        return None
+    if isinstance(body, dict) and isinstance(body.get("title"), str):
+        body.setdefault("status", res.status_code)
+        return body
+    return None
+
+
+def _error(res: httpx.Response, method: str, path: str) -> UnprofaneError:
+    problem = _problem(res)
+    message = (problem or {}).get("detail") or (problem or {}).get("title") or f"Unprofane {method} {path} failed ({res.status_code})"
+    return UnprofaneError(message, res.status_code, problem, res.headers.get("request-id"))
+
+
+def _chunks(texts: List[str]) -> List[List[dict]]:
+    return [
+        [{"id": str(i + j), "text": text} for j, text in enumerate(texts[i : i + _MAX_BATCH])]
+        for i in range(0, len(texts), _MAX_BATCH)
+    ]
+
+
+def _drop_none(body: Dict[str, Any]) -> Dict[str, Any]:
+    return {k: v for k, v in body.items() if v is not None}
+
+
+class _Base:
+    def __init__(self, api_key: str, base_url: str = _DEFAULT_BASE, retries: int = 3, timeout: float = 10.0):
+        _check_key(api_key)
+        self._headers = {"authorization": f"Bearer {api_key}", "user-agent": f"unprofane-python/{__version__}"}
+        self._base = base_url.rstrip("/")
+        self._retries = retries
+        self._timeout = timeout
+
+
+class Unprofane(_Base):
+    """The synchronous client. Use it as a context manager or call close()."""
+
+    def __init__(self, api_key: str, base_url: str = _DEFAULT_BASE, retries: int = 3, timeout: float = 10.0, transport: Optional[httpx.BaseTransport] = None):
+        super().__init__(api_key, base_url, retries, timeout)
+        self._http = httpx.Client(base_url=self._base, headers=self._headers, timeout=timeout, transport=transport)
+
+    def __enter__(self) -> "Unprofane":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def _call(self, method: str, path: str, body: Optional[dict] = None) -> Any:
+        attempt = 0
+        while True:
+            try:
+                res = self._http.request(method, path, json=body)
+            except httpx.TransportError:
+                if attempt >= self._retries:
+                    raise
+                attempt += 1
+                time.sleep(backoff(attempt, None))
+                continue
+            if res.is_success:
+                return None if res.status_code == 204 else res.json()
+            if res.status_code in _RETRYABLE and attempt < self._retries:
+                attempt += 1
+                time.sleep(backoff(attempt, res.headers.get("retry-after")))
+                continue
+            raise _error(res, method, path)
+
+    def check(self, text: str, *, context: Optional[str] = None, policy: Optional[Policy] = None, mode: Optional[str] = None, language: Optional[str] = None, mask: Optional[str] = None, engine: Optional[str] = None, lists: Optional[dict] = None) -> dict:
+        """One text: should it be allowed, with the evidence."""
+        return self._call("POST", "/v1/check", _drop_none({"text": text, "context": context, "policy": policy, "mode": mode, "language": language, "mask": mask, "engine": engine, "lists": lists}))
+
+    def check_batch(self, items: List[dict], *, context: Optional[str] = None, policy: Optional[Policy] = None, mode: Optional[str] = None, mask: Optional[str] = None, engine: Optional[str] = None, lists: Optional[dict] = None) -> dict:
+        """Up to 100 items of {id, text}, answered in order."""
+        if len(items) > _MAX_BATCH:
+            raise ValueError(f"check_batch takes at most {_MAX_BATCH} items; use check_many")
+        return self._call("POST", "/v1/check/batch", _drop_none({"items": items, "context": context, "policy": policy, "mode": mode, "mask": mask, "engine": engine, "lists": lists}))
+
+    def check_many(self, texts: Iterable[str], **options: Any) -> List[dict]:
+        """Any number of texts, chunked by 100, results in input order."""
+        out: List[dict] = []
+        for chunk in _chunks(list(texts)):
+            out.extend(self.check_batch(chunk, **options)["results"])
+        return out
+
+    def feedback(self, check_id: str, verdict: str, *, expected_action: Optional[str] = None, note: Optional[str] = None, text: Optional[str] = None) -> dict:
+        """Report a wrong result. `text` is stored only if you include it."""
+        return self._call("POST", "/v1/feedback", _drop_none({"check_id": check_id, "verdict": verdict, "expected_action": expected_action, "note": note, "text": text}))
+
+    def usage(self) -> dict:
+        return self._call("GET", "/v1/usage")
+
+    def get_list(self, project_id: str, kind: str) -> dict:
+        return self._call("GET", f"/v1/projects/{project_id}/lists/{kind}")
+
+    def put_list(self, project_id: str, kind: str, terms: List[str]) -> dict:
+        return self._call("PUT", f"/v1/projects/{project_id}/lists/{kind}", {"terms": terms})
+
+    def delete_list(self, project_id: str, kind: str) -> None:
+        self._call("DELETE", f"/v1/projects/{project_id}/lists/{kind}")
+
+
+class AsyncUnprofane(_Base):
+    """The asynchronous client, for asyncio. Use it as an async context manager."""
+
+    def __init__(self, api_key: str, base_url: str = _DEFAULT_BASE, retries: int = 3, timeout: float = 10.0, transport: Optional[httpx.AsyncBaseTransport] = None):
+        super().__init__(api_key, base_url, retries, timeout)
+        self._http = httpx.AsyncClient(base_url=self._base, headers=self._headers, timeout=timeout, transport=transport)
+
+    async def __aenter__(self) -> "AsyncUnprofane":
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def _call(self, method: str, path: str, body: Optional[dict] = None) -> Any:
+        import asyncio
+
+        attempt = 0
+        while True:
+            try:
+                res = await self._http.request(method, path, json=body)
+            except httpx.TransportError:
+                if attempt >= self._retries:
+                    raise
+                attempt += 1
+                await asyncio.sleep(backoff(attempt, None))
+                continue
+            if res.is_success:
+                return None if res.status_code == 204 else res.json()
+            if res.status_code in _RETRYABLE and attempt < self._retries:
+                attempt += 1
+                await asyncio.sleep(backoff(attempt, res.headers.get("retry-after")))
+                continue
+            raise _error(res, method, path)
+
+    async def check(self, text: str, *, context: Optional[str] = None, policy: Optional[Policy] = None, mode: Optional[str] = None, language: Optional[str] = None, mask: Optional[str] = None, engine: Optional[str] = None, lists: Optional[dict] = None) -> dict:
+        return await self._call("POST", "/v1/check", _drop_none({"text": text, "context": context, "policy": policy, "mode": mode, "language": language, "mask": mask, "engine": engine, "lists": lists}))
+
+    async def check_batch(self, items: List[dict], *, context: Optional[str] = None, policy: Optional[Policy] = None, mode: Optional[str] = None, mask: Optional[str] = None, engine: Optional[str] = None, lists: Optional[dict] = None) -> dict:
+        if len(items) > _MAX_BATCH:
+            raise ValueError(f"check_batch takes at most {_MAX_BATCH} items; use check_many")
+        return await self._call("POST", "/v1/check/batch", _drop_none({"items": items, "context": context, "policy": policy, "mode": mode, "mask": mask, "engine": engine, "lists": lists}))
+
+    async def check_many(self, texts: Iterable[str], *, concurrency: int = 2, **options: Any) -> List[dict]:
+        import asyncio
+
+        chunks = _chunks(list(texts))
+        out: List[Optional[dict]] = [None] * len(chunks)
+        sem = asyncio.Semaphore(max(1, concurrency))
+
+        async def one(i: int) -> None:
+            async with sem:
+                out[i] = await self.check_batch(chunks[i], **options)
+
+        await asyncio.gather(*(one(i) for i in range(len(chunks))))
+        return [r for batch in out for r in (batch or {}).get("results", [])]
+
+    async def feedback(self, check_id: str, verdict: str, *, expected_action: Optional[str] = None, note: Optional[str] = None, text: Optional[str] = None) -> dict:
+        return await self._call("POST", "/v1/feedback", _drop_none({"check_id": check_id, "verdict": verdict, "expected_action": expected_action, "note": note, "text": text}))
+
+    async def usage(self) -> dict:
+        return await self._call("GET", "/v1/usage")
+
+    async def get_list(self, project_id: str, kind: str) -> dict:
+        return await self._call("GET", f"/v1/projects/{project_id}/lists/{kind}")
+
+    async def put_list(self, project_id: str, kind: str, terms: List[str]) -> dict:
+        return await self._call("PUT", f"/v1/projects/{project_id}/lists/{kind}", {"terms": terms})
+
+    async def delete_list(self, project_id: str, kind: str) -> None:
+        await self._call("DELETE", f"/v1/projects/{project_id}/lists/{kind}")