kliz 0.2.0__py3-none-any.whl

kliz/__init__.py

@@ -0,0 +1,29 @@
+"""Public API for kliz."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from kliz.core import Kliz
+from kliz.exceptions import KlizError, ProviderError
+from kliz.providers import (
+    BaseProvider,
+    BatchProvider,
+    GoogleProvider,
+    IndexNowProvider,
+)
+from kliz.results import NotificationResult
+
+__all__ = [
+    "BaseProvider",
+    "BatchProvider",
+    "GoogleProvider",
+    "IndexNowProvider",
+    "Kliz",
+    "KlizError",
+    "NotificationResult",
+    "ProviderError",
+]
+
+try:
+    __version__ = version("kliz")
+except PackageNotFoundError:  # pragma: no cover - source tree without installation
+    __version__ = "0.0.0"

kliz/_http.py

@@ -0,0 +1,64 @@
+"""Shared HTTP helpers for indexing providers."""
+
+from collections.abc import Mapping
+from typing import Any, Optional
+
+import requests
+
+from kliz.exceptions import ProviderError
+
+DEFAULT_SUCCESS_STATUSES: set[int] = {200, 202}
+
+
+def create_session(session: Optional[requests.Session] = None) -> requests.Session:
+    """Return *session* or a fresh :class:`requests.Session`."""
+
+    return session if session is not None else requests.Session()
+
+
+def post_json(
+    session: requests.Session,
+    url: str,
+    *,
+    payload: Mapping[str, Any],
+    timeout: float,
+    provider: str,
+) -> requests.Response:
+    """POST JSON and map transport failures to :class:`ProviderError`."""
+
+    try:
+        return session.post(url, json=dict(payload), timeout=timeout)
+    except (requests.Timeout, requests.ConnectionError) as exc:
+        raise ProviderError(
+            f"{provider} could not be reached",
+            provider=provider,
+            retryable=True,
+        ) from exc
+    except requests.RequestException as exc:
+        raise ProviderError(
+            f"{provider} request failed",
+            provider=provider,
+        ) from exc
+
+
+def raise_for_indexing_status(
+    response: requests.Response,
+    *,
+    provider: str,
+    success_statuses: Optional[set[int]] = None,
+) -> bool:
+    """Return ``True`` for accepted statuses or raise :class:`ProviderError`."""
+
+    accepted = (
+        success_statuses if success_statuses is not None else DEFAULT_SUCCESS_STATUSES
+    )
+    if response.status_code in accepted:
+        return True
+
+    retryable = response.status_code == 429 or response.status_code >= 500
+    raise ProviderError(
+        f"{provider} rejected the notification with HTTP {response.status_code}",
+        provider=provider,
+        retryable=retryable,
+        status_code=response.status_code,
+    )

kliz/_validation.py

@@ -0,0 +1,34 @@
+"""Shared input validation helpers."""
+
+from urllib.parse import SplitResult, urlsplit
+
+
+def parse_http_url(url: str, *, require_clean: bool = False) -> SplitResult:
+    """Return a parsed absolute HTTP(S) URL or raise ``ValueError``.
+
+    A fragment (``#...``) is always rejected because it is never sent to the
+    server: ``page`` and ``page#top`` address the same resource, so a fragment
+    can never be meaningful for indexing and may even carry auth tokens.
+
+    A query string (``?...``) is rejected only when ``require_clean`` is true.
+    The server does receive the query, so it can address a real resource;
+    whether a clean canonical URL is mandatory is the caller's decision.
+    """
+
+    if not isinstance(url, str) or not url.strip():
+        raise ValueError("url must be a non-empty string")
+
+    normalized_url = url.strip()
+    parsed_url = urlsplit(normalized_url)
+    if parsed_url.scheme.lower() not in {"http", "https"}:
+        raise ValueError("url must use the http or https scheme")
+    if not parsed_url.hostname:
+        raise ValueError("url must include a hostname")
+    if parsed_url.username is not None or parsed_url.password is not None:
+        raise ValueError("url must not contain credentials")
+    if parsed_url.fragment:
+        raise ValueError("url must not contain a fragment")
+    if require_clean and parsed_url.query:
+        raise ValueError("url must not contain a query string")
+
+    return parsed_url

kliz/cli.py

@@ -0,0 +1,164 @@
+"""CLI entry point for kliz."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from typing import Callable
+
+from kliz import Kliz, __version__
+from kliz.exceptions import KlizError
+from kliz.providers import GoogleProvider, IndexNowProvider
+
+
+class ConfigurationError(ValueError):
+    """Raised when the CLI is misconfigured."""
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    try:
+        args = parser.parse_args(argv)
+    except SystemExit as exc:
+        code: int = exc.code if isinstance(exc.code, int) else 0
+        return code
+    try:
+        command: Callable[[argparse.Namespace], int] = args.command
+        return command(args)
+    except ConfigurationError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    except KlizError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print("\naborted", file=sys.stderr)
+        return 130
+    except Exception as exc:  # noqa: BLE001
+        print(f"error: unexpected error: {exc}", file=sys.stderr)
+        return 1
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="kliz",
+        description=(
+            "Bot d'indexation SEO agnostique pour notifier les moteurs de recherche."
+        ),
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=__version__,
+    )
+    parser.add_argument(
+        "--indexnow-api-key",
+        default=os.environ.get("KLIZ_INDEXNOW_API_KEY"),
+        help="IndexNow API key (KLIZ_INDEXNOW_API_KEY env var)",
+    )
+    parser.add_argument(
+        "--indexnow-key-location",
+        default=os.environ.get("KLIZ_INDEXNOW_KEY_LOCATION"),
+        help="URL where the IndexNow key file is hosted",
+    )
+    parser.add_argument(
+        "--google-service-account-file",
+        default=os.environ.get("KLIZ_GOOGLE_SERVICE_ACCOUNT_FILE"),
+        help="Path to the Google service account JSON file",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+    p_notify = sub.add_parser("notify", help="Notify providers of a URL")
+    p_notify.add_argument("url", nargs="?", default=None, help="URL to notify")
+    p_notify.add_argument(
+        "--batch",
+        default=None,
+        help="File with one URL per line",
+    )
+    p_notify.set_defaults(command=_cmd_notify)
+    p_providers = sub.add_parser("providers", help="List configured providers")
+    p_providers.set_defaults(command=_cmd_providers)
+    return parser
+
+
+def _cmd_notify(args: argparse.Namespace) -> int:
+    urls = _resolve_urls(args)
+    indexer = _build_indexer(args)
+    all_ok = True
+    for url in urls:
+        results = indexer.notify_all_detailed(url)
+        failures = {
+            name: result.error for name, result in results.items() if not result.success
+        }
+        if failures:
+            all_ok = False
+            for name, error in failures.items():
+                print(
+                    f"❌ {url} → {name}: {error}",
+                    file=sys.stderr,
+                )
+        else:
+            names = ", ".join(results)
+            print(f"✅ {url} → {names}: OK")
+    return 0 if all_ok else 1
+
+
+def _cmd_providers(args: argparse.Namespace) -> int:
+    indexer = _build_indexer(args)
+    for provider in indexer.providers:
+        kind = provider.__class__.__name__
+        print(f"{kind} ({provider.name})")
+    return 0
+
+
+def _resolve_urls(args: argparse.Namespace) -> list[str]:
+    if args.batch:
+        return _read_urls_from_file(args.batch)
+    if args.url:
+        return [args.url]
+    raise ConfigurationError("provide a URL or --batch <file>")
+
+
+def _read_urls_from_file(path: str) -> list[str]:
+    try:
+        with open(path) as handle:
+            urls = [
+                line.strip()
+                for line in handle
+                if line.strip() and not line.startswith("#")
+            ]
+    except OSError as exc:
+        raise ConfigurationError(f"cannot read {path}: {exc}") from exc
+    if not urls:
+        raise ConfigurationError(f"no URLs found in {path}")
+    return urls
+
+
+def _build_indexer(args: argparse.Namespace) -> Kliz:
+    providers: list[IndexNowProvider | GoogleProvider] = []
+    if args.indexnow_api_key:
+        if not args.indexnow_key_location:
+            raise ConfigurationError(
+                "--indexnow-key-location is required when --indexnow-api-key is set",
+            )
+        providers.append(
+            IndexNowProvider(
+                api_key=args.indexnow_api_key,
+                key_location=args.indexnow_key_location,
+            ),
+        )
+    if args.google_service_account_file:
+        if not os.path.exists(args.google_service_account_file):
+            raise ConfigurationError(
+                f"service account file not found: {args.google_service_account_file}",
+            )
+        providers.append(
+            GoogleProvider(args.google_service_account_file),
+        )
+    if not providers:
+        raise ConfigurationError(
+            "no providers configured: set --indexnow-api-key + "
+            "--indexnow-key-location or --google-service-account-file "
+            "(or the KLIZ_* env vars)",
+        )
+    return Kliz(providers)

kliz/core.py

@@ -0,0 +1,177 @@
+"""Provider orchestration for kliz."""
+
+from __future__ import annotations
+
+import random
+import time
+from collections import Counter
+from collections.abc import Callable, Iterable, Sequence
+from typing import Any
+
+from kliz.exceptions import ProviderError
+from kliz.providers.base import BaseProvider
+from kliz.results import NotificationResult
+
+_RETRY_BASE_DELAY = 1.0
+_JITTER_RANGE = 0.25
+
+
+class Kliz:
+    """Dispatch indexing notifications to a collection of providers."""
+
+    def __init__(
+        self,
+        providers: Iterable[BaseProvider],
+        *,
+        max_attempts: int = 1,
+        sleep: Callable[[float], None] = time.sleep,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        if isinstance(providers, (str, bytes)):
+            raise TypeError("providers must be an iterable of BaseProvider instances")
+
+        provider_list = list(providers)
+        if not all(isinstance(provider, BaseProvider) for provider in provider_list):
+            raise TypeError("every provider must inherit from BaseProvider")
+
+        if (
+            isinstance(max_attempts, bool)
+            or not isinstance(max_attempts, int)
+            or max_attempts < 1
+        ):
+            raise ValueError("max_attempts must be a positive integer")
+
+        self.providers = tuple(provider_list)
+        self.max_attempts = max_attempts
+        self._sleep = sleep
+        self._clock = clock
+
+    def close(self) -> None:
+        """Close every provider, releasing pooled connections."""
+
+        for provider in self.providers:
+            provider.close()
+
+    def __enter__(self) -> Kliz:
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def notify_all(self, url: str) -> dict[str, bool]:
+        """Notify every provider and return simple boolean statuses."""
+
+        return {
+            name: result.success
+            for name, result in self.notify_all_detailed(url).items()
+        }
+
+    def notify_all_detailed(self, url: str) -> dict[str, NotificationResult]:
+        """Notify all providers without hiding error and retry information."""
+
+        return {
+            name: self._notify_provider(provider, url)
+            for provider, name in zip(self.providers, self._result_names())
+        }
+
+    def notify_many(self, urls: Sequence[str]) -> dict[str, bool]:
+        """Notify every provider with a batch of URLs and return boolean statuses."""
+
+        return {
+            name: all(result.success for result in results)
+            for name, results in self.notify_many_detailed(urls).items()
+        }
+
+    def notify_many_detailed(
+        self, urls: Sequence[str]
+    ) -> dict[str, list[NotificationResult]]:
+        """Notify all providers with multiple URLs.
+
+        Preserves per-chunk outcome details without hiding errors.
+        """
+
+        url_list = self._validate_urls(urls)
+        return {
+            name: self._notify_provider_many(provider, url_list)
+            for provider, name in zip(self.providers, self._result_names())
+        }
+
+    def _notify_provider(self, provider: BaseProvider, url: str) -> NotificationResult:
+        return self._execute_with_retry(provider, provider.notify, url)
+
+    def _notify_provider_many(
+        self, provider: BaseProvider, urls: list[str]
+    ) -> list[NotificationResult]:
+        notify_many_fn = getattr(provider, "notify_many", None)
+        if callable(notify_many_fn):
+            max_urls = getattr(provider, "max_urls_per_request", None)
+            if isinstance(max_urls, int) and max_urls > 0:
+                chunks = [urls[i : i + max_urls] for i in range(0, len(urls), max_urls)]
+            else:
+                chunks = [urls]
+
+            return [
+                self._execute_with_retry(provider, notify_many_fn, chunk)
+                for chunk in chunks
+            ]
+
+        return [
+            self._execute_with_retry(provider, provider.notify, url) for url in urls
+        ]
+
+    def _execute_with_retry(
+        self, provider: BaseProvider, func: Callable[..., Any], *args: Any
+    ) -> NotificationResult:
+        for attempt in range(1, self.max_attempts + 1):
+            try:
+                success = bool(func(*args))
+                return NotificationResult(
+                    provider=provider.name,
+                    success=success,
+                    error=None if success else "provider returned False",
+                )
+            except ProviderError as exc:
+                if attempt < self.max_attempts and exc.retryable:
+                    self._sleep_between_attempts(attempt)
+                    continue
+                return NotificationResult(
+                    provider=provider.name,
+                    success=False,
+                    retryable=exc.retryable,
+                    error=str(exc),
+                    status_code=exc.status_code,
+                )
+            except Exception as exc:
+                return NotificationResult(
+                    provider=provider.name,
+                    success=False,
+                    error=str(exc) or exc.__class__.__name__,
+                )
+        raise AssertionError("unreachable")  # pragma: no cover
+
+    def _validate_urls(self, urls: Sequence[str]) -> list[str]:
+        if isinstance(urls, (str, bytes)):
+            raise TypeError("urls must be a sequence of strings, not a string or bytes")
+        try:
+            url_list = list(urls)
+        except TypeError as exc:
+            raise TypeError("urls must be an iterable sequence of strings") from exc
+
+        if not url_list:
+            raise ValueError("urls must be a non-empty sequence")
+        return url_list
+
+    def _sleep_between_attempts(self, attempt: int) -> None:
+        delay = _RETRY_BASE_DELAY * (2 ** (attempt - 1))
+        delay += random.Random(self._clock()).uniform(0.0, _JITTER_RANGE)
+        self._sleep(delay)
+
+    def _result_names(self) -> list[str]:
+        counts: Counter[str] = Counter()
+        names: list[str] = []
+        for provider in self.providers:
+            counts[provider.name] += 1
+            occurrence = counts[provider.name]
+            suffix = "" if occurrence == 1 else f"#{occurrence}"
+            names.append(f"{provider.name}{suffix}")
+        return names

kliz/exceptions.py

@@ -0,0 +1,24 @@
+"""Exceptions exposed by kliz."""
+
+from typing import Optional
+
+
+class KlizError(Exception):
+    """Base class for all kliz-specific errors."""
+
+
+class ProviderError(KlizError):
+    """An indexing provider could not complete a notification."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        provider: str,
+        retryable: bool = False,
+        status_code: Optional[int] = None,
+    ) -> None:
+        super().__init__(message)
+        self.provider = provider
+        self.retryable = retryable
+        self.status_code = status_code

kliz/providers/__init__.py

@@ -0,0 +1,8 @@
+"""Built-in indexing providers."""
+
+from kliz.providers.base import BaseProvider
+from kliz.providers.batch import BatchProvider
+from kliz.providers.google import GoogleProvider
+from kliz.providers.indexnow import IndexNowProvider
+
+__all__ = ["BaseProvider", "BatchProvider", "GoogleProvider", "IndexNowProvider"]

kliz/providers/base.py

@@ -0,0 +1,32 @@
+"""Contracts implemented by indexing providers."""
+
+from abc import ABC, abstractmethod
+
+
+class BaseProvider(ABC):
+    """Strategy interface for a search-engine indexing provider."""
+
+    @property
+    def name(self) -> str:
+        """Return the provider name used in orchestration results."""
+
+        return self.__class__.__name__
+
+    @abstractmethod
+    def notify(self, url: str) -> bool:
+        """Notify the provider that *url* was updated.
+
+        Implementations return ``True`` after a successful notification and
+        raise :class:`kliz.exceptions.ProviderError` when the remote service
+        rejects the request or cannot be reached.
+        """
+
+        raise NotImplementedError
+
+    def close(self) -> None:  # noqa: B027
+        """Release resources held by this provider.
+
+        The default implementation is a no-op.  Subclasses that hold
+        persistent connections (HTTP sessions, gRPC channels, etc.)
+        should override this method.
+        """

kliz/providers/batch.py

@@ -0,0 +1,79 @@
+"""Reusable batch provider base for host-scoped indexing APIs."""
+
+from abc import abstractmethod
+from collections.abc import Sequence
+from typing import Optional
+from urllib.parse import SplitResult
+
+import requests
+
+from kliz._http import create_session
+from kliz._validation import parse_http_url
+from kliz.providers.base import BaseProvider
+
+
+class BatchProvider(BaseProvider):
+    """Provider that notifies one or many URLs belonging to the same host.
+
+    Subclasses implement :meth:`_notify_many`. ``notify`` is implemented as a
+    single-URL batch so adapters only maintain one submission path.
+    """
+
+    max_urls_per_request: int = 1
+
+    def __init__(
+        self,
+        *,
+        timeout: float = 10.0,
+        session: Optional[requests.Session] = None,
+    ) -> None:
+        if timeout <= 0:
+            raise ValueError("timeout must be greater than zero")
+
+        self.timeout = timeout
+        self._session = create_session(session)
+
+    def close(self) -> None:
+        """Release the pooled connections held by this provider."""
+
+        self._session.close()
+
+    def notify(self, url: str) -> bool:
+        """Notify the provider that *url* was updated."""
+
+        return self.notify_many([url])
+
+    def notify_many(self, urls: Sequence[str]) -> bool:
+        """Submit up to ``max_urls_per_request`` URLs for the same host."""
+
+        normalized_urls, parsed_urls = self._validate_urls(urls)
+        return self._notify_many(normalized_urls, parsed_urls)
+
+    @abstractmethod
+    def _notify_many(
+        self,
+        urls: list[str],
+        parsed_urls: list[SplitResult],
+    ) -> bool:
+        """Submit an already validated same-host URL batch."""
+
+        raise NotImplementedError
+
+    def _validate_urls(
+        self, urls: Sequence[str]
+    ) -> tuple[list[str], list[SplitResult]]:
+        if isinstance(urls, (str, bytes)) or not urls:
+            raise ValueError("urls must be a non-empty sequence")
+        if len(urls) > self.max_urls_per_request:
+            raise ValueError(
+                f"provider accepts at most {self.max_urls_per_request} URLs per request"
+            )
+
+        normalized_urls = [url.strip() for url in urls]
+        parsed_urls = [
+            parse_http_url(url, require_clean=True) for url in normalized_urls
+        ]
+        hosts = {parsed.hostname.lower() for parsed in parsed_urls if parsed.hostname}
+        if len(hosts) != 1:
+            raise ValueError("all batch URLs must belong to the same host")
+        return normalized_urls, parsed_urls

kliz/providers/google.py

@@ -0,0 +1,105 @@
+"""Google Indexing API provider implementation."""
+
+from pathlib import Path
+from typing import Any, Optional, Union
+
+import google_auth_httplib2
+import httplib2
+from google.auth.exceptions import GoogleAuthError, TransportError
+from google.oauth2 import service_account
+from googleapiclient.discovery import build
+from googleapiclient.errors import HttpError
+
+from kliz._validation import parse_http_url
+from kliz.exceptions import ProviderError
+from kliz.providers.base import BaseProvider
+
+
+class GoogleProvider(BaseProvider):
+    """Notify Google for eligible JobPosting or BroadcastEvent pages only."""
+
+    scope = "https://www.googleapis.com/auth/indexing"
+
+    def __init__(
+        self,
+        service_account_file: Union[str, Path],
+        *,
+        timeout: float = 60.0,
+        num_retries: int = 2,
+    ) -> None:
+        if not str(service_account_file):
+            raise ValueError("service_account_file must not be empty")
+        if timeout <= 0:
+            raise ValueError("timeout must be greater than zero")
+        if num_retries < 0:
+            raise ValueError("num_retries must not be negative")
+
+        self.service_account_file = service_account_file
+        self.timeout = timeout
+        self.num_retries = num_retries
+        self._service: Optional[Any] = None
+
+    def notify(self, url: str) -> bool:
+        """Publish a ``URL_UPDATED`` notification to Google."""
+
+        parse_http_url(url, require_clean=True)
+        normalized_url = url.strip()
+        service = self._get_service()
+
+        try:
+            (
+                service.urlNotifications()
+                .publish(body={"url": normalized_url, "type": "URL_UPDATED"})
+                .execute(num_retries=self.num_retries)
+            )
+        except HttpError as exc:
+            status_code = int(exc.resp.status)
+            retryable = status_code in {408, 429} or status_code >= 500
+            raise ProviderError(
+                f"Google rejected the notification with HTTP {status_code}",
+                provider=self.name,
+                retryable=retryable,
+                status_code=status_code,
+            ) from exc
+        except (TransportError, httplib2.HttpLib2Error, OSError) as exc:
+            raise ProviderError(
+                "Google could not be reached",
+                provider=self.name,
+                retryable=True,
+            ) from exc
+        return True
+
+    def _get_service(self) -> Any:
+        """Return the Google API client, building it once on first use."""
+
+        if self._service is None:
+            self._service = self._build_service()
+        return self._service
+
+    def _build_service(self) -> Any:
+        """Build the authenticated Google Indexing API client.
+
+        Only successes are cached: if building fails the provider retries on
+        a later notification instead of remaining broken forever.
+        """
+
+        try:
+            credentials = service_account.Credentials.from_service_account_file(  # type: ignore[no-untyped-call]
+                str(self.service_account_file),
+                scopes=[self.scope],
+            )
+            authorized_http = google_auth_httplib2.AuthorizedHttp(
+                credentials,
+                http=httplib2.Http(timeout=self.timeout),
+            )
+            return build(
+                "indexing",
+                "v3",
+                http=authorized_http,
+                cache_discovery=False,
+            )
+        except (OSError, ValueError, GoogleAuthError) as exc:
+            raise ProviderError(
+                "Google service account could not be loaded",
+                provider=self.name,
+            ) from exc

kliz/providers/indexnow.py

@@ -0,0 +1,88 @@
+"""IndexNow provider implementation."""
+
+import re
+from pathlib import PurePosixPath
+from typing import Optional, Union
+from urllib.parse import SplitResult
+
+import requests
+
+from kliz._http import post_json, raise_for_indexing_status
+from kliz._validation import parse_http_url
+from kliz.providers.batch import BatchProvider
+
+PayloadValue = Union[str, list[str]]
+
+
+class IndexNowProvider(BatchProvider):
+    """Notify search engines that support the IndexNow protocol."""
+
+    endpoint = "https://api.indexnow.org/indexnow"
+    max_urls_per_request = 10_000
+    _key_pattern = re.compile(r"^[A-Za-z0-9-]{8,128}$")
+
+    def __init__(
+        self,
+        api_key: str,
+        key_location: Optional[str] = None,
+        timeout: float = 10.0,
+        *,
+        session: Optional[requests.Session] = None,
+    ) -> None:
+        if not isinstance(api_key, str) or not self._key_pattern.fullmatch(api_key):
+            raise ValueError(
+                "api_key must contain 8 to 128 letters, numbers, or dashes"
+            )
+        if key_location is not None:
+            parse_http_url(key_location, require_clean=True)
+
+        super().__init__(timeout=timeout, session=session)
+        self.api_key = api_key
+        self.key_location = key_location
+
+    def _notify_many(
+        self,
+        urls: list[str],
+        parsed_urls: list[SplitResult],
+    ) -> bool:
+        host = parsed_urls[0].hostname
+        if host is None:  # Defensive: parse_http_url already enforces this.
+            raise ValueError("url must include a hostname")
+
+        self._validate_key_location(parsed_urls[0])
+        payload: dict[str, PayloadValue] = {
+            "host": host,
+            "key": self.api_key,
+            "urlList": urls,
+        }
+        if self.key_location:
+            payload["keyLocation"] = self.key_location
+
+        response = post_json(
+            self._session,
+            self.endpoint,
+            payload=payload,
+            timeout=self.timeout,
+            provider=self.name,
+        )
+        return raise_for_indexing_status(response, provider=self.name)
+
+    def _validate_key_location(self, submitted_url: SplitResult) -> None:
+        if self.key_location is None:
+            return
+
+        key_url = parse_http_url(self.key_location, require_clean=True)
+        if key_url.hostname is None or submitted_url.hostname is None:
+            raise ValueError("key_location and url must include a hostname")
+        if key_url.hostname.lower() != submitted_url.hostname.lower():
+            raise ValueError("key_location must use the same host as the submitted URL")
+
+        key_directory = str(PurePosixPath(key_url.path).parent)
+        if key_directory == ".":
+            key_directory = "/"
+        normalized_directory = key_directory.rstrip("/") + "/"
+        submitted_path = submitted_url.path or "/"
+        if normalized_directory != "/" and not submitted_path.startswith(
+            normalized_directory
+        ):
+            raise ValueError("url must be within the path covered by key_location")

kliz/py.typed

@@ -0,0 +1 @@
+

kliz/results.py

@@ -0,0 +1,15 @@
+"""Result models returned by the kliz orchestrator."""
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class NotificationResult:
+    """Detailed outcome of one provider notification."""
+
+    provider: str
+    success: bool
+    retryable: bool = False
+    error: Optional[str] = None
+    status_code: Optional[int] = None

kliz-0.2.0.dist-info/METADATA

@@ -0,0 +1,436 @@
+Metadata-Version: 2.4
+Name: kliz
+Version: 0.2.0
+Summary: Bot d'indexation SEO agnostique pour notifier les moteurs de recherche.
+Author: Freddy Choudja
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/freddychoudja/kliz-
+Project-URL: Repository, https://github.com/freddychoudja/kliz-.git
+Project-URL: Issues, https://github.com/freddychoudja/kliz-/issues
+Project-URL: Documentation, https://github.com/freddychoudja/kliz-#readme
+Keywords: seo,indexing,indexnow,google
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Requires-Dist: google-auth>=2.0.0
+Requires-Dist: google-auth-httplib2>=0.1.0
+Requires-Dist: google-api-python-client>=2.0.0
+Requires-Dist: httplib2<1.0.0,>=0.19.0
+Provides-Extra: test
+Requires-Dist: pytest<10.0,>=8.0; extra == "test"
+Requires-Dist: pytest-cov<8.0,>=5.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: build<2.0,>=1.2; extra == "dev"
+Requires-Dist: mypy<3.0,>=1.11; extra == "dev"
+Requires-Dist: pip-audit<3.0,>=2.7; extra == "dev"
+Requires-Dist: pytest<10.0,>=8.0; extra == "dev"
+Requires-Dist: pytest-cov<8.0,>=5.0; extra == "dev"
+Requires-Dist: ruff<1.0,>=0.9; extra == "dev"
+Requires-Dist: twine<8.0,>=5.1; extra == "dev"
+Requires-Dist: types-requests>=2.28.0; extra == "dev"
+Dynamic: license-file
+
+# kliz
+
+[![CI](https://github.com/freddychoudja/kliz-/actions/workflows/ci.yml/badge.svg)](https://github.com/freddychoudja/kliz-/actions/workflows/ci.yml)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/kliz)](https://pypi.org/project/kliz/)
+[![GitHub issues](https://img.shields.io/github/issues/freddychoudja/kliz-)](https://github.com/freddychoudja/kliz-/issues)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+`kliz` est un bot d'indexation SEO agnostique. Il permet à une application de
+notifier plusieurs moteurs de recherche dès qu'une URL est créée ou mise à
+jour.
+
+Le package ne dépend ni de Django, ni de Celery, ni de Redis. Il expose une API
+Python synchrone que l'application appelante peut exécuter directement ou
+encapsuler dans le système de tâches de son choix.
+
+## Installation
+
+```bash
+pip install kliz
+```
+
+Une documentation web statique est disponible dans
+[`docs/index.html`](docs/index.html). Elle peut aussi être publiée via GitHub
+Pages avec le workflow fourni.
+
+Une traduction anglaise est disponible dans
+[`README.en.md`](README.en.md).
+
+Pour contribuer et exécuter les tests :
+
+```bash
+python -m pip install -e ".[dev]"
+pytest --cov=kliz
+```
+
+## Démarrage rapide
+
+```python
+from kliz import GoogleProvider, IndexNowProvider, Kliz
+
+indexer = Kliz(
+    [
+        IndexNowProvider(
+            api_key="votre-cle-indexnow",
+            key_location="https://example.com/votre-cle-indexnow.txt",
+        ),
+        GoogleProvider("/run/secrets/google-service-account.json"),
+    ]
+)
+
+statuses = indexer.notify_all("https://example.com/articles/nouvel-article")
+# {
+#     "IndexNowProvider": True,
+#     "GoogleProvider": True,
+# }
+```
+
+Pour soumettre plusieurs URL d'un coup, `notify_many` découpe selon
+`max_urls_per_request` (lots IndexNow) et retombe sur une boucle `notify` pour
+les autres providers :
+
+```python
+statuses = indexer.notify_many(
+    [
+        "https://example.com/articles/a",
+        "https://example.com/articles/b",
+    ]
+)
+```
+
+Le retry intégré est **désactivé par défaut** (`max_attempts=1`). Pour l'activer
+avec backoff exponentiel et jitter :
+
+```python
+indexer = Kliz(
+    [IndexNowProvider(api_key="votre-cle-indexnow")],
+    max_attempts=3,
+)
+```
+
+`notify_all` continue d'appeler les autres fournisseurs lorsqu'un fournisseur
+échoue. Son statut vaut alors `False`. Un appel direct à `provider.notify(url)`
+laisse en revanche remonter une `ProviderError` afin que l'application puisse
+appliquer sa propre politique de retry.
+
+Pour obtenir la cause, le statut HTTP et l'indication de retry :
+
+```python
+results = indexer.notify_all_detailed(
+    "https://example.com/articles/nouvel-article"
+)
+
+for name, result in results.items():
+    print(name, result.success, result.retryable, result.error)
+```
+
+Si plusieurs instances ont le même nom, leurs clés sont suffixées :
+`IndexNowProvider`, `IndexNowProvider#2`, etc.
+
+## Architecture agnostique
+
+`BaseProvider` définit une stratégie minimale : `notify(url) -> bool`. Chaque
+adaptateur traduit ce contrat vers l'API distante concernée :
+
+- `IndexNowProvider` envoie une requête HTTP à l'API IndexNow ;
+- `GoogleProvider` publie une notification `URL_UPDATED` via l'API Google
+  Indexing ;
+- `Kliz` orchestre les stratégies injectées dans son constructeur.
+
+Cette séparation permet d'ajouter un moteur sans modifier l'orchestrateur et
+laisse l'application libre de choisir son framework web, sa file d'attente et
+sa politique de retry.
+
+Un fournisseur personnalisé doit uniquement hériter de `BaseProvider` :
+
+```python
+from kliz import BaseProvider
+
+
+class CustomProvider(BaseProvider):
+    def notify(self, url: str) -> bool:
+        # Appel vers l'API du moteur concerné
+        return True
+```
+
+Pour un moteur qui accepte des lots d'URL sur le même hôte, héritez de
+`BatchProvider` : `notify` et la validation (hôte commun, taille max, URL
+propres) sont fournis ; il reste à implémenter `_notify_many`.
+
+```python
+from urllib.parse import SplitResult
+
+from kliz import BatchProvider
+
+
+class CustomBatchProvider(BatchProvider):
+    max_urls_per_request = 100
+
+    def _notify_many(
+        self, urls: list[str], parsed_urls: list[SplitResult]
+    ) -> bool:
+        # Appel HTTP groupé vers le moteur
+        return True
+```
+
+## Validation des URL
+
+Toutes les URL soumises à un provider sont contrôlées avant tout envoi :
+
+- le schéma doit être `http` ou `https` et l'hôte doit être présent ;
+- les identifiants (`https://user:pass@...`) sont interdits ;
+- les fragments (`#...`) sont toujours rejetés : ils ne sont jamais transmis au
+  serveur et ne peuvent donc désigner un contenu distinct ;
+- les chaînes de requête (`?...`) sont rejetées pour les notifications : seule
+  une URL canonique propre est soumise aux moteurs.
+
+La fonction partagée `parse_http_url(url, require_clean=True)` applique ces
+règles. `require_clean` vaut `False` par défaut afin de ne pas casser les
+usages existants ; seules les notifications exigent une URL propre.
+
+## Configuration des fournisseurs
+
+### IndexNow
+
+La clé doit être publiée conformément aux règles d'IndexNow. Si
+`key_location` est fourni, il est transmis dans le champ `keyLocation`.
+
+```python
+from kliz import IndexNowProvider
+
+provider = IndexNowProvider(
+    api_key="votre-cle-valide",
+    key_location="https://example.com/votre-cle-valide.txt",  # optionnel
+    timeout=10.0,
+)
+provider.notify("https://example.com/page")
+```
+
+Le provider réutilise une connexion HTTP persistante (`requests.Session`) entre
+les notifications, afin de ne pas reconstruire une connexion et une poignée de
+main TLS à chaque appel. Vous pouvez injecter votre propre session (tests,
+configuration réseau partagée, proxies) :
+
+```python
+import requests
+
+provider = IndexNowProvider(
+    api_key="votre-cle-valide",
+    session=requests.Session(),
+)
+```
+
+La session interne garde les connexions ouvertes ; appelez `provider.close()` à
+l'arrêt de votre application pour les libérer proprement.
+
+Pour soumettre plusieurs URL du même hôte dans un seul appel :
+
+```python
+provider.notify_many(
+    [
+        "https://example.com/page-1",
+        "https://example.com/page-2",
+    ]
+)
+```
+
+IndexNow accepte jusqu'à 10 000 URL par requête. `kliz` classe les erreurs
+`429` et `5xx` comme retentables.
+
+### Google
+
+Activez l'API Google Indexing pour votre projet, créez un compte de service et
+autorisez-le sur la propriété concernée. Ne versionnez jamais le fichier JSON
+du compte de service.
+
+> **Restriction importante :** l'API Google Indexing est officiellement
+> réservée aux pages contenant un `JobPosting` ou un `BroadcastEvent` intégré
+> dans un `VideoObject`. N'utilisez pas ce provider comme API d'indexation
+> générique pour les autres contenus ; utilisez notamment un sitemap pour leur
+> couverture.
+
+```python
+from kliz import GoogleProvider
+
+provider = GoogleProvider(
+    "/run/secrets/google-service-account.json",
+    timeout=60.0,
+    num_retries=2,
+)
+provider.notify("https://example.com/jobs/backend-python")
+```
+
+L'API Google Indexing est soumise aux règles d'éligibilité et aux quotas de
+Google. Une notification ne garantit pas l'indexation de l'URL.
+
+Le client Indexing est construit de manière paresseuse : le fichier de compte
+de service n'est lu qu'au premier appel de `notify`, puis réutilisé pour les
+appels suivants. La création du provider ne déclenche donc aucune lecture de
+fichier. Les erreurs de configuration (fichier absent, JSON invalide)
+remontent au moment de la notification, sont marquées comme non retentables, et
+le provider se rétablit dès que le fichier est corrigé.
+
+## Recettes / Intégration Asynchrone
+
+`kliz` reste volontairement synchrone. Pour une exécution asynchrone, placez
+l'appel dans un worker, une tâche ou un job appartenant à votre application.
+Ainsi, les dépendances d'infrastructure ne contaminent pas le package.
+
+### Tâche Celery (Python/Django)
+
+Dans un projet Django utilisant déjà Celery, la tâche peut lire sa
+configuration depuis les settings et laisser Celery gérer les retries :
+
+```python
+# myapp/tasks.py — ce code appartient à l'application, pas à kliz
+from dataclasses import asdict
+
+from celery import shared_task
+from django.conf import settings
+
+from kliz import IndexNowProvider, Kliz
+
+
+@shared_task(bind=True, max_retries=5)
+def notify_search_engines(self, url: str) -> dict[str, dict[str, object]]:
+    indexer = Kliz(
+        [
+            IndexNowProvider(
+                api_key=settings.INDEXNOW_API_KEY,
+                key_location=settings.INDEXNOW_KEY_LOCATION,
+            ),
+        ]
+    )
+    results = indexer.notify_all_detailed(url)
+    retryable = [result for result in results.values() if result.retryable]
+
+    if retryable:
+        raise self.retry(
+            exc=RuntimeError("temporary indexing provider failure"),
+            countdown=min(60 * (2**self.request.retries), 3600),
+        )
+
+    return {name: asdict(result) for name, result in results.items()}
+```
+
+Depuis une vue, un signal ou un service Django :
+
+```python
+from myapp.tasks import notify_search_engines
+
+notify_search_engines.delay("https://example.com/articles/nouveau")
+```
+
+Pour isoler les retries et quotas de chaque moteur, utilisez idéalement une
+tâche par provider. Le provider Google ne doit être ajouté que pour les pages
+officiellement éligibles.
+
+### Job générique
+
+Le même principe fonctionne avec un scheduler, un worker maison, RQ, Dramatiq,
+une fonction serverless ou un cron. Le job ne connaît que l'API publique de
+`kliz` :
+
+```python
+from kliz import IndexNowProvider, Kliz
+
+
+class ContentIndexingJob:
+    def __init__(self, api_key: str) -> None:
+        self.indexer = Kliz([IndexNowProvider(api_key=api_key)])
+
+    def run(self, payload: dict[str, str]) -> dict[str, bool]:
+        return self.indexer.notify_all(payload["url"])
+
+
+# Le système de jobs choisi sérialise ce payload et appelle job.run(payload).
+job = ContentIndexingJob(api_key="votre-cle")
+result = job.run({"url": "https://example.com/page-modifiee"})
+```
+
+## Interface en ligne de commande
+
+L'installation fournit aussi une commande `kliz` :
+
+```bash
+export KLIZ_INDEXNOW_API_KEY="votre-cle"
+export KLIZ_INDEXNOW_KEY_LOCATION="https://example.com/votre-cle.txt"
+
+kliz notify https://example.com/page  # une URL
+kliz notify --batch urls.txt          # une URL par ligne, `#` pour un commentaire
+kliz providers                        # liste des providers configurés
+kliz --version
+```
+
+Les crédits se passent aussi en options (`--indexnow-api-key`,
+`--indexnow-key-location`, `--google-service-account-file`). Le processus
+termine avec le code `0` si tout a réussi, `1` en cas d'échec de notification
+et `2` en cas de configuration invalide.
+
+## Tests
+
+Les tests mockent les appels `requests` et le client Google. Ils ne nécessitent
+donc ni accès réseau, ni clé IndexNow, ni compte de service Google.
+
+La validation complète locale est :
+
+```bash
+ruff format --check src tests
+ruff check src tests
+mypy src
+pytest --cov=kliz
+python -m build
+twine check --strict dist/*
+pip-audit . --strict
+```
+
+## Exploitation en production
+
+Le package ne stocke aucun secret et n'impose aucun système de tâches. Dans
+l'application qui l'utilise :
+
+- injectez les clés par un gestionnaire de secrets ;
+- activez le retry opt-in de `Kliz` (`max_attempts`) ou appliquez un backoff
+  applicatif aux résultats `retryable=True` ;
+- placez les échecs définitifs dans une dead-letter queue ;
+- mesurez latence, taux de succès, codes HTTP et quotas par provider ;
+- ne partagez pas une même instance `GoogleProvider` entre plusieurs threads ;
+- conservez un sitemap à jour : une notification ne garantit jamais
+  l'indexation.
+
+## Publication
+
+Les tags `vX.Y.Z` déclenchent le workflow de release. Le tag doit correspondre
+exactement à la version de `pyproject.toml`. La publication utilise le Trusted
+Publishing PyPI et ne nécessite aucun token PyPI permanent dans GitHub.
+
+Avant la première release, configurez sur PyPI un publisher avec le dépôt
+`freddychoudja/kliz-`, le workflow `release.yml` et l'environnement `pypi`.
+
+## Contribuer
+
+Les contributions sont les bienvenues. Consultez
+[CONTRIBUTING.md](CONTRIBUTING.md) avant d'ouvrir une issue ou une pull
+request.
+
+Le code source et le suivi du projet sont disponibles sur
+[GitHub](https://github.com/freddychoudja/kliz-).
+
+## Licence
+
+`kliz` est distribué sous la [licence MIT](LICENSE). Copyright © 2026 Freddy
+Choudja.

kliz-0.2.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+kliz/__init__.py,sha256=91H-r1VX8Otn-s9NR28Y8fB8Q4tuaPe0oNYNFyN4Wrk,652
+kliz/_http.py,sha256=-qNHQ2YsrCwFeyYrHB60wq4ss9Fp1S-637-m9nB7DqU,1842
+kliz/_validation.py,sha256=NDBpi7Xzv1yZ1y7z6uhnn6CAG7TsbkhsexQYsMqqbJM,1455
+kliz/cli.py,sha256=GFhLhLsTE5iFmy_CBkjqaxCWcwrxVoOpPIPK-0pFlfY,5289
+kliz/core.py,sha256=AQ2aamSnUss5hF_8I7Ok1KbbD8VLGhfCW-WMagYKW1Q,6276
+kliz/exceptions.py,sha256=9AafUFFDVOien0lpBwSLItZAwKHUWrRZ0v2JpRdgHs0,565
+kliz/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+kliz/results.py,sha256=RcEsm_pVb93mMUUwb9A5WI0S_YCaCeld5ODp06LHNoc,362
+kliz/providers/__init__.py,sha256=v_dYpfOxclltln99eMw4g0IqQ5biiim-5eqeb2hiHa4,313
+kliz/providers/base.py,sha256=3hfRXkGTgwOqKhODM1vSThZCv0AVk58pQZw-xGna2i0,985
+kliz/providers/batch.py,sha256=P5DFtPo9OsZPUEApquYyeQOYDGKPRsi_fvA3zoO9e_M,2539
+kliz/providers/google.py,sha256=gz9rSXceoVcWGrpCf6ZS_9Pcy8FL-OH7yQqBUDyiz-E,3671
+kliz/providers/indexnow.py,sha256=1g7q9FN4RwxbPkNTr1ch8uicOVfzLJxWzs1YrZyihY4,3052
+kliz-0.2.0.dist-info/licenses/LICENSE,sha256=eOlskYaawwtAU6sGhMd7o6xD1iPyjaQUpQY_bMrUCRg,1071
+kliz-0.2.0.dist-info/METADATA,sha256=gK_Cm0pjH36iW0911soOOu9htEVovbRibxHCZWc4yVY,14407
+kliz-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+kliz-0.2.0.dist-info/entry_points.txt,sha256=-69WW759zTomRAmrXJRTWIpaLy1jCqMjRB3jwAPpTi8,39
+kliz-0.2.0.dist-info/top_level.txt,sha256=GZNKut60zID1o86dl8rdWDt-5Yo9KepGFX63ey8983c,5
+kliz-0.2.0.dist-info/RECORD,,

kliz-0.2.0.dist-info/WHEEL

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

kliz-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+kliz = kliz.cli:main

kliz-0.2.0.dist-info/licenses/LICENSE

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

kliz-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+kliz