sentinel-python-client 2.0.0__tar.gz

sentinel_python_client-2.0.0/.githooks/pre-commit

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+
+STAGED_PY=$(git diff --cached --name-only --diff-filter=ACM -- '*.py')
+
+if [ -z "$STAGED_PY" ]; then
+  exit 0
+fi
+
+printf "Formatting Python files... "
+if ruff format $STAGED_PY > /dev/null 2>&1; then
+  echo "$STAGED_PY" | xargs git add
+  echo "OK"
+else
+  echo "FAILED"
+  exit 1
+fi

sentinel_python_client-2.0.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install -e ".[dev]"
+      - run: ruff check src/ tests/
+      - run: ruff format --check src/ tests/
+      - run: pytest -v
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - run: pyright src/

sentinel_python_client-2.0.0/.github/workflows/release.yml

@@ -0,0 +1,33 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

sentinel_python_client-2.0.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+
+# Environment variables
+.env
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Linting / type checking
+.ruff_cache/
+.pyright/
+.mypy_cache/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

sentinel_python_client-2.0.0/LICENSE

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

sentinel_python_client-2.0.0/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: sentinel-python-client
+Version: 2.0.0
+Summary: Official Python client for the Sentinel v2 license validation and management API
+Author: Demeng
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pynacl>=1.5
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+[![PyPI](https://img.shields.io/pypi/v/sentinel-python-client)](https://pypi.org/project/sentinel-python-client/)
+
+# Sentinel Python Client
+
+Official Python client library for the [Sentinel](https://demeng.dev/sentinel) v2 API.
+
+## Documentation
+
+Full documentation is available on GitBook:
+[https://demeng.gitbook.io/sentinel/clients/python](https://demeng.gitbook.io/sentinel/clients/python)
+
+## License
+
+[MIT](LICENSE)

sentinel_python_client-2.0.0/README.md

@@ -0,0 +1,14 @@
+[![PyPI](https://img.shields.io/pypi/v/sentinel-python-client)](https://pypi.org/project/sentinel-python-client/)
+
+# Sentinel Python Client
+
+Official Python client library for the [Sentinel](https://demeng.dev/sentinel) v2 API.
+
+## Documentation
+
+Full documentation is available on GitBook:
+[https://demeng.gitbook.io/sentinel/clients/python](https://demeng.gitbook.io/sentinel/clients/python)
+
+## License
+
+[MIT](LICENSE)

sentinel_python_client-2.0.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sentinel-python-client"
+version = "2.0.0"
+description = "Official Python client for the Sentinel v2 license validation and management API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "Demeng" }]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.0",
+    "PyNaCl>=1.5",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "respx>=0.21",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.8",
+    "pyright>=1.1",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sentinel"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+pythonpath = ["."]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 99
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.pyright]
+pythonVersion = "3.11"
+typeCheckingMode = "standard"

sentinel_python_client-2.0.0/src/sentinel/__init__.py

@@ -0,0 +1,69 @@
+"""Sentinel Python Client - Official client for the Sentinel v2 API."""
+
+from sentinel._async_client import AsyncSentinelClient
+from sentinel._client import SentinelClient
+from sentinel._exceptions import (
+    LicenseValidationError,
+    ReplayDetectedError,
+    SentinelApiError,
+    SentinelConnectionError,
+    SentinelError,
+    SignatureVerificationError,
+)
+from sentinel.models.license import (
+    BlacklistInfo,
+    License,
+    LicenseIssuer,
+    LicenseProduct,
+    LicenseTier,
+    SubUser,
+)
+from sentinel.models.page import Page
+from sentinel.models.requests import (
+    CLEAR,
+    CLEAR_EXPIRATION,
+    CreateLicenseRequest,
+    ListLicensesRequest,
+    UpdateLicenseRequest,
+    ValidationRequest,
+)
+from sentinel.models.validation import (
+    BlacklistFailureDetails,
+    ExcessiveIpsFailureDetails,
+    ExcessiveServersFailureDetails,
+    FailureDetails,
+    ValidationDetails,
+    ValidationResult,
+    ValidationResultType,
+)
+
+__all__ = [
+    "SentinelClient",
+    "AsyncSentinelClient",
+    "SentinelError",
+    "SentinelApiError",
+    "SentinelConnectionError",
+    "LicenseValidationError",
+    "SignatureVerificationError",
+    "ReplayDetectedError",
+    "License",
+    "LicenseProduct",
+    "LicenseTier",
+    "LicenseIssuer",
+    "SubUser",
+    "BlacklistInfo",
+    "ValidationResult",
+    "ValidationResultType",
+    "ValidationDetails",
+    "FailureDetails",
+    "BlacklistFailureDetails",
+    "ExcessiveServersFailureDetails",
+    "ExcessiveIpsFailureDetails",
+    "CreateLicenseRequest",
+    "UpdateLicenseRequest",
+    "ListLicensesRequest",
+    "ValidationRequest",
+    "CLEAR",
+    "CLEAR_EXPIRATION",
+    "Page",
+]

sentinel_python_client-2.0.0/src/sentinel/_async_client.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from datetime import timedelta
+
+from sentinel._http import AsyncSentinelHttpClient
+from sentinel._replay import ReplayProtector
+from sentinel._signature import SignatureVerifier
+from sentinel.services._async_license import AsyncLicenseService
+
+
+class AsyncSentinelClient:
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        public_key: str | None = None,
+        connect_timeout: float = 5.0,
+        read_timeout: float = 10.0,
+        replay_protection_window: timedelta = timedelta(seconds=30),
+        nonce_cache_size: int = 1000,
+    ) -> None:
+        if not base_url:
+            raise ValueError("base_url is required")
+        if not api_key:
+            raise ValueError("api_key is required")
+
+        self._http = AsyncSentinelHttpClient(
+            base_url=base_url,
+            api_key=api_key,
+            connect_timeout=connect_timeout,
+            read_timeout=read_timeout,
+        )
+
+        sig: SignatureVerifier | None = None
+        replay: ReplayProtector | None = None
+        if public_key is not None:
+            sig = SignatureVerifier(public_key)
+            replay = ReplayProtector(
+                window_seconds=replay_protection_window.total_seconds(),
+                max_size=nonce_cache_size,
+            )
+
+        self.licenses = AsyncLicenseService(
+            http_client=self._http,
+            signature_verifier=sig,
+            replay_protector=replay,
+        )
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncSentinelClient:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.aclose()

sentinel_python_client-2.0.0/src/sentinel/_client.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from datetime import timedelta
+
+from sentinel._http import SentinelHttpClient
+from sentinel._replay import ReplayProtector
+from sentinel._signature import SignatureVerifier
+from sentinel.services._license import LicenseService
+
+
+class SentinelClient:
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        public_key: str | None = None,
+        connect_timeout: float = 5.0,
+        read_timeout: float = 10.0,
+        replay_protection_window: timedelta = timedelta(seconds=30),
+        nonce_cache_size: int = 1000,
+    ) -> None:
+        if not base_url:
+            raise ValueError("base_url is required")
+        if not api_key:
+            raise ValueError("api_key is required")
+
+        self._http = SentinelHttpClient(
+            base_url=base_url,
+            api_key=api_key,
+            connect_timeout=connect_timeout,
+            read_timeout=read_timeout,
+        )
+
+        sig: SignatureVerifier | None = None
+        replay: ReplayProtector | None = None
+        if public_key is not None:
+            sig = SignatureVerifier(public_key)
+            replay = ReplayProtector(
+                window_seconds=replay_protection_window.total_seconds(),
+                max_size=nonce_cache_size,
+            )
+
+        self.licenses = LicenseService(
+            http_client=self._http,
+            signature_verifier=sig,
+            replay_protector=replay,
+        )
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> SentinelClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()

sentinel_python_client-2.0.0/src/sentinel/_exceptions.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from sentinel.models.validation import ValidationResultType
+
+
+class SentinelError(Exception):
+    pass
+
+
+class SentinelApiError(SentinelError):
+    def __init__(
+        self,
+        http_status: int,
+        type: str | None,
+        message: str,
+        retry_after_seconds: float | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.http_status = http_status
+        self.type = type
+        self.retry_after_seconds = retry_after_seconds
+
+
+class SentinelConnectionError(SentinelError):
+    def __init__(self, message: str, cause: Exception | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        if cause is not None:
+            self.__cause__ = cause
+
+
+class LicenseValidationError(SentinelError):
+    def __init__(
+        self,
+        type: ValidationResultType,
+        message: str,
+        failure_details: object | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.type = type
+        self.failure_details = failure_details
+
+
+class SignatureVerificationError(SentinelError):
+    pass
+
+
+class ReplayDetectedError(SentinelError):
+    pass

sentinel_python_client-2.0.0/src/sentinel/_http.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import urlencode
+
+import httpx
+
+from sentinel._exceptions import SentinelApiError, SentinelConnectionError
+
+
+@dataclass
+class ApiResponse:
+    http_status: int
+    type: str | None
+    message: str | None
+    result: dict[str, Any] | None
+
+    def require_result(self) -> dict[str, Any]:
+        if self.result is None:
+            raise SentinelApiError(
+                http_status=self.http_status,
+                type=self.type,
+                message="Response contained no result",
+            )
+        return self.result
+
+
+def _parse_response(
+    status_code: int,
+    body: str,
+    headers: httpx.Headers,
+    allowed_statuses: set[int] | None,
+) -> ApiResponse:
+    if status_code == 204:
+        return ApiResponse(http_status=204, type=None, message=None, result=None)
+
+    try:
+        data = json.loads(body)
+    except (json.JSONDecodeError, ValueError) as e:
+        raise SentinelApiError(
+            http_status=status_code, type=None, message="Failed to parse response body"
+        ) from e
+
+    resp_type = data.get("type")
+    message = data.get("message")
+    result = data.get("result") if isinstance(data.get("result"), dict) else None
+
+    if 200 <= status_code < 300:
+        return ApiResponse(http_status=status_code, type=resp_type, message=message, result=result)
+
+    if allowed_statuses and status_code in allowed_statuses:
+        return ApiResponse(http_status=status_code, type=resp_type, message=message, result=result)
+
+    retry_after: float | None = None
+    if status_code == 429:
+        raw = headers.get("X-Rate-Limit-Retry-After-Seconds")
+        if raw is not None:
+            try:
+                retry_after = int(raw)
+            except ValueError:
+                pass
+
+    raise SentinelApiError(
+        http_status=status_code,
+        type=resp_type,
+        message=message or "Unknown error",
+        retry_after_seconds=retry_after,
+    )
+
+
+def _build_url(
+    base_url: str,
+    path: str,
+    query_params: dict[str, str] | None = None,
+    multi_query_params: dict[str, list[str]] | None = None,
+) -> str:
+    url = base_url + path
+    if multi_query_params:
+        parts: list[str] = []
+        for key in sorted(multi_query_params):
+            for val in sorted(multi_query_params[key]):
+                parts.append(f"{urlencode({key: val})}")
+        url += "?" + "&".join(parts)
+        return url
+    if query_params:
+        sorted_params = sorted(query_params.items())
+        url += "?" + urlencode(sorted_params)
+    return url
+
+
+class SentinelHttpClient:
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        connect_timeout: float = 5.0,
+        read_timeout: float = 10.0,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        if http_client is not None:
+            self._client = http_client
+        else:
+            self._client = httpx.Client(
+                timeout=httpx.Timeout(
+                    connect=connect_timeout, read=read_timeout, write=5.0, pool=5.0
+                ),
+            )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        json_body: dict[str, Any] | list[Any] | None = None,
+        query_params: dict[str, str] | None = None,
+        multi_query_params: dict[str, list[str]] | None = None,
+        allowed_statuses: set[int] | None = None,
+    ) -> ApiResponse:
+        url = _build_url(self._base_url, path, query_params, multi_query_params)
+        headers = {"Authorization": f"Bearer {self._api_key}"}
+        kwargs: dict[str, Any] = {"headers": headers}
+
+        if json_body is not None:
+            headers["Content-Type"] = "application/json"
+            kwargs["content"] = json.dumps(json_body)
+        try:
+            response = self._client.request(method, url, **kwargs)
+        except httpx.TimeoutException as e:
+            raise SentinelConnectionError("Failed to connect to Sentinel API", e) from e
+        except httpx.NetworkError as e:
+            raise SentinelConnectionError("Failed to connect to Sentinel API", e) from e
+
+        return _parse_response(
+            response.status_code, response.text, response.headers, allowed_statuses
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+
+class AsyncSentinelHttpClient:
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        connect_timeout: float = 5.0,
+        read_timeout: float = 10.0,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        if http_client is not None:
+            self._client = http_client
+        else:
+            self._client = httpx.AsyncClient(
+                timeout=httpx.Timeout(
+                    connect=connect_timeout, read=read_timeout, write=5.0, pool=5.0
+                ),
+            )
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        json_body: dict[str, Any] | list[Any] | None = None,
+        query_params: dict[str, str] | None = None,
+        multi_query_params: dict[str, list[str]] | None = None,
+        allowed_statuses: set[int] | None = None,
+    ) -> ApiResponse:
+        url = _build_url(self._base_url, path, query_params, multi_query_params)
+        headers = {"Authorization": f"Bearer {self._api_key}"}
+        kwargs: dict[str, Any] = {"headers": headers}
+
+        if json_body is not None:
+            headers["Content-Type"] = "application/json"
+            kwargs["content"] = json.dumps(json_body)
+        try:
+            response = await self._client.request(method, url, **kwargs)
+        except httpx.TimeoutException as e:
+            raise SentinelConnectionError("Failed to connect to Sentinel API", e) from e
+        except httpx.NetworkError as e:
+            raise SentinelConnectionError("Failed to connect to Sentinel API", e) from e
+
+        return _parse_response(
+            response.status_code, response.text, response.headers, allowed_statuses
+        )
+
+    async def aclose(self) -> None:
+        await self._client.aclose()