opacte 0.1.0__py3-none-any.whl

opacte/__init__.py

@@ -0,0 +1,29 @@
+"""SDK Python de l'API Opacte — attestations, vérification et, bientôt, signature.
+
+Le contrat HTTP est publié (https://opacte.eu/api/openapi.json) ; ce SDK en est la voie recommandée.
+"""
+
+from opacte.client import Attestation, Client, Compte, __version__
+from opacte.erreurs import (
+    CleInvalide,
+    CompteSuspendu,
+    CreditsInsuffisants,
+    ErreurOpacte,
+    ErreurReseau,
+    Introuvable,
+    TropDeDemandes,
+)
+
+__all__ = [
+    "Attestation",
+    "CleInvalide",
+    "Client",
+    "Compte",
+    "CompteSuspendu",
+    "CreditsInsuffisants",
+    "ErreurOpacte",
+    "ErreurReseau",
+    "Introuvable",
+    "TropDeDemandes",
+    "__version__",
+]

opacte/client.py

@@ -0,0 +1,195 @@
+"""Client de l'API Opacte (contrat : https://opacte.eu/api/openapi.json ; 290_api_contrat.md).
+
+    from opacte import Client
+
+    client = Client()  # clé lue dans OPACTE_API_KEY
+    print(client.compte().solde)
+    attestation = client.attestations.creer("facture.pdf")
+
+Fiabilité : sur coupure, `429` ou `5xx`, l'appel est rejoué (au plus `essais` fois, en respectant `Retry-After`),
+avec la même `Idempotency-Key` pour les créations : jamais de second débit.
+"""
+
+import os
+import time
+import uuid
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, BinaryIO
+
+import httpx
+
+from opacte import empreintes
+from opacte.erreurs import ErreurReseau, TropDeDemandes, depuis_reponse
+
+URL = "https://opacte.eu"
+VERSION_API = "1"
+__version__ = "0.1.0"
+
+
+@dataclass(frozen=True)
+class Compte:
+    email: str
+    solde: int
+    requetes_par_minute: int
+    restantes: int
+
+
+@dataclass(frozen=True)
+class Attestation:
+    id_attestation: str
+    horodatage: str
+    statut: str  # provisoire | definitive | ancree
+    taille: int | None = None
+    email_visible: bool | None = None
+    # à la création seulement : le reçu provisoire, et le jeton (à conserver) qui donne accès au reçu par son URL
+    recu: dict[str, Any] | None = field(default=None, repr=False)
+    jeton_recuperation: str | None = field(default=None, repr=False)
+    url_recu: str | None = None
+    credits: int | None = None
+
+
+class Client:
+    def __init__(
+        self,
+        cle: str | None = None,
+        *,
+        url: str = URL,
+        essais: int = 3,
+        delai: float = 30.0,
+        http: httpx.Client | None = None,
+    ):
+        cle = cle or os.environ.get("OPACTE_API_KEY")
+        if not cle:
+            raise ValueError("clé API absente : passez cle=… ou définissez OPACTE_API_KEY")
+        self._entetes = {
+            "Authorization": f"Bearer {cle}",
+            "Said-Api-Version": VERSION_API,
+            "User-Agent": f"opacte-python/{__version__}",
+        }
+        self._http = http or httpx.Client(base_url=url, timeout=delai)
+        self._essais = max(1, essais)
+        self.attestations = Attestations(self)
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.fermer()
+
+    def fermer(self) -> None:
+        self._http.close()
+
+    # --- transport -----------------------------------------------------------------------------------------
+
+    def _appeler(
+        self,
+        methode: str,
+        chemin: str,
+        *,
+        idempotent: bool = False,
+        corps: Any = None,
+        fichier: tuple[Path | bytes, int] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        entetes = dict(self._entetes)
+        if idempotent:
+            entetes["Idempotency-Key"] = str(uuid.uuid4())  # la même pour toutes les tentatives
+        for essai in range(self._essais):
+            try:
+                if fichier is not None:
+                    source, taille = fichier
+                    entetes.update({"Content-Type": "application/octet-stream", "Content-Length": str(taille)})
+                    if isinstance(source, bytes):
+                        r = self._http.request(methode, chemin, content=source, headers=entetes, params=params)
+                    else:
+                        with open(source, "rb") as f:  # rouvert à chaque tentative : envoyé en flux
+                            r = self._http.request(methode, chemin, content=f, headers=entetes, params=params)
+                else:
+                    r = self._http.request(methode, chemin, json=corps, headers=entetes, params=params)
+            except httpx.TransportError as e:
+                if essai + 1 == self._essais:
+                    raise ErreurReseau(e) from e
+                time.sleep(2**essai)
+                continue
+            if r.status_code == 429 or r.status_code >= 500:
+                if essai + 1 < self._essais:
+                    time.sleep(float(r.headers.get("Retry-After") or 2**essai))
+                    continue
+            if r.status_code >= 400:
+                try:
+                    detail = r.json()
+                except ValueError:
+                    detail = {"erreur": "inconnue"}
+                exc = depuis_reponse(r.status_code, dict(detail))
+                if isinstance(exc, TropDeDemandes):
+                    exc.retry_after = float(r.headers.get("Retry-After") or 0)
+                raise exc
+            return r.json() if r.content else None
+        raise AssertionError("inatteignable")
+
+    # --- compte et vérification ------------------------------------------------------------------------------
+
+    def compte(self) -> Compte:
+        """L'adresse du compte, le solde de crédits (commun au site) et la marge de débit."""
+        c = self._appeler("GET", "/api/account")
+        return Compte(c["email"], c["solde"], c["limites"]["requetes_par_minute"], c["limites"]["restantes"])
+
+    def verifier(self, fichier: empreintes.Source) -> list[dict[str, Any]]:
+        """Attestations candidates pour un fichier reçu. Ses empreintes sont calculées ici : il ne part pas."""
+        taille, valeurs = empreintes.calculer(fichier)
+        reponse = self._appeler("POST", "/api/verifications", corps={"taille": taille, "empreintes": valeurs})
+        return reponse["candidates"]
+
+
+class Attestations:
+    def __init__(self, client: Client):
+        self._c = client
+
+    def creer(self, fichier: str | Path | bytes | BinaryIO, *, email_visible: bool = True) -> Attestation:
+        """Atteste un fichier (1 crédit). Envoyé en flux, lu à la volée, jamais conservé par Opacte."""
+        if isinstance(fichier, (str, Path)):
+            source: Path | bytes = Path(fichier)
+            taille = source.stat().st_size
+        elif isinstance(fichier, bytes):
+            source, taille = fichier, len(fichier)
+        else:
+            source = fichier.read()  # un flux ouvert ne se rejoue pas : lu une fois
+            taille = len(source)
+        a = self._c._appeler(
+            "POST",
+            "/api/attestations",
+            idempotent=True,
+            fichier=(source, taille),
+            params={"email_visible": "true" if email_visible else "false"},
+        )
+        return Attestation(
+            a["id_attestation"],
+            a["horodatage"],
+            a["statut"],
+            recu=a["recu"],
+            jeton_recuperation=a["jeton_recuperation"],
+            url_recu=a["url_recu"],
+            credits=a["credits"],
+        )
+
+    def lire(self, id_attestation: str) -> Attestation:
+        a = self._c._appeler("GET", f"/api/attestations/{id_attestation}")
+        return Attestation(a["id_attestation"], a["horodatage"], a["statut"], a["taille"], a["email_visible"])
+
+    def recu(self, id_attestation: str) -> dict[str, Any]:
+        """Le meilleur reçu signé disponible (provisoire, puis définitif avec son ancrage)."""
+        return self._c._appeler("GET", f"/api/attestations/{id_attestation}/receipt")
+
+    def lister(self, *, par_page: int = 100) -> Iterator[Attestation]:
+        """Toutes les attestations du compte, les plus récentes d'abord (pages chargées à la demande)."""
+        apres: str | None = None
+        while True:
+            params: dict[str, Any] = {"limite": par_page, **({"apres": apres} if apres else {})}
+            page = self._c._appeler("GET", "/api/attestations", params=params)
+            for a in page["elements"]:
+                yield Attestation(a["id_attestation"], a["horodatage"], a["statut"], a["taille"], a["email_visible"])
+            apres = page["suivant"]
+            if not apres:
+                return

opacte/empreintes.py

@@ -0,0 +1,42 @@
+"""Empreintes d'un fichier, calculées localement (110_formats_fc_v1.md) : le fichier ne part pas pour être vérifié.
+
+Les trois algorithmes du socle v1, en base64url sans remplissage ; le fichier est lu par blocs, jamais en entier.
+"""
+
+import base64
+import hashlib
+from collections.abc import Iterable
+from pathlib import Path
+from typing import BinaryIO
+
+ALGOS = {"blake2b-512": lambda: hashlib.blake2b(digest_size=64), "sha256": hashlib.sha256, "sha3-512": hashlib.sha3_512}
+BLOC = 1024 * 1024
+
+Source = str | Path | bytes | BinaryIO
+
+
+def _b64u(octets: bytes) -> str:
+    return base64.urlsafe_b64encode(octets).rstrip(b"=").decode("ascii")
+
+
+def _blocs(source: Source) -> Iterable[bytes]:
+    if isinstance(source, bytes):
+        yield source
+    elif isinstance(source, (str, Path)):
+        with open(source, "rb") as f:
+            while bloc := f.read(BLOC):
+                yield bloc
+    else:
+        while bloc := source.read(BLOC):
+            yield bloc
+
+
+def calculer(source: Source) -> tuple[int, list[dict[str, str]]]:
+    """Taille et empreintes (`[{"algo", "valeur"}]`, dans l'ordre fc-v1) d'un fichier, d'octets ou d'un flux."""
+    contextes = {algo: fabrique() for algo, fabrique in ALGOS.items()}
+    taille = 0
+    for bloc in _blocs(source):
+        taille += len(bloc)
+        for c in contextes.values():
+            c.update(bloc)
+    return taille, [{"algo": a, "valeur": _b64u(contextes[a].digest())} for a in sorted(contextes)]

opacte/erreurs.py

@@ -0,0 +1,58 @@
+"""Erreurs de l'API Opacte, en exceptions typées : le code stable de l'API (`erreur`) et ses détails."""
+
+from typing import Any
+
+
+class ErreurOpacte(Exception):
+    """Réponse d'erreur de l'API ; `code` est le champ `erreur` du contrat, `details` le reste du corps."""
+
+    def __init__(self, statut: int, code: str, details: dict[str, Any] | None = None):
+        super().__init__(f"{statut} {code}")
+        self.statut, self.code, self.details = statut, code, details or {}
+
+
+class CleInvalide(ErreurOpacte):
+    """Clé absente, inconnue ou révoquée : en créer une dans Réglages."""
+
+
+class CompteSuspendu(ErreurOpacte):
+    pass
+
+
+class CreditsInsuffisants(ErreurOpacte):
+    """Solde insuffisant ; `solde` donne le solde actuel. Les crédits s'achètent sur le site."""
+
+    @property
+    def solde(self) -> int | None:
+        return self.details.get("solde")
+
+
+class TropDeDemandes(ErreurOpacte):
+    """Limite de débit atteinte ; `retry_after` : secondes avant de réessayer (le SDK réessaie de lui-même)."""
+
+    retry_after: float = 0.0
+
+
+class Introuvable(ErreurOpacte):
+    pass
+
+
+class ErreurReseau(ErreurOpacte):
+    """Pas de réponse du serveur, après les nouvelles tentatives."""
+
+    def __init__(self, cause: Exception):
+        super().__init__(0, "reseau", {"cause": str(cause)})
+
+
+_PAR_CODE = {
+    "cle_invalide": CleInvalide,
+    "compte_suspendu": CompteSuspendu,
+    "credits_insuffisants": CreditsInsuffisants,
+    "trop_de_demandes": TropDeDemandes,
+}
+
+
+def depuis_reponse(statut: int, corps: dict[str, Any]) -> ErreurOpacte:
+    code = str(corps.pop("erreur", "inconnue"))
+    classe = _PAR_CODE.get(code) or (Introuvable if statut == 404 else ErreurOpacte)
+    return classe(statut, code, corps)

opacte-0.1.0.dist-info/METADATA

@@ -0,0 +1,83 @@
+Metadata-Version: 2.5
+Name: opacte
+Version: 0.1.0
+Summary: SDK Python de l'API Opacte : attester et vérifier des documents, sans qu'ils quittent votre serveur pour être conservés.
+Project-URL: Homepage, https://opacte.eu
+Project-URL: Documentation, https://opacte.eu/api
+Project-URL: Contrat HTTP, https://opacte.eu/api/openapi.json
+Project-URL: Tutoriel, https://opacte.eu/api-tutorial
+Author: Jean-Michel ARNAUD
+License-Expression: MIT
+License-File: LICENSE
+Keywords: attestation,bitcoin,horodatage,opacte,opentimestamps,preuve,signature électronique
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: French
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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 :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# opacte — SDK Python de l'API Opacte
+
+Attestez et vérifiez des documents depuis votre logiciel, sans captcha ni code. Comme sur
+[opacte.eu](https://opacte.eu), le document n'est jamais conservé : Opacte n'en garde que les empreintes, et la preuve
+est ancrée dans Bitcoin.
+
+## Installation
+
+```
+pip install opacte
+```
+
+Python 3.10 ou plus. Créez un compte sur [opacte.eu](https://opacte.eu/account), puis une clé API dans **Réglages**,
+et rendez-la disponible dans la variable d'environnement `OPACTE_API_KEY` (jamais dans votre code).
+
+## Exemple
+
+```python
+from opacte import Client, CreditsInsuffisants
+
+client = Client()  # clé lue dans OPACTE_API_KEY
+print(client.compte().solde)
+
+# Attester un fichier : 1 crédit. Envoyé en flux, lu à la volée, jamais conservé.
+attestation = client.attestations.creer("facture-2026-118.pdf", email_visible=False)
+print(attestation.id_attestation, attestation.url_recu)  # gardez url_recu : accès pérenne au reçu
+
+# Vérifier un document reçu : ses empreintes sont calculées ici, le fichier ne part pas. Gratuit.
+for candidate in client.verifier("document-recu.pdf"):
+    print(candidate["id_attestation"], candidate["horodatage"])
+```
+
+## Ce que fait le SDK
+
+- **Fichiers en flux** : un fichier est envoyé par blocs, jamais chargé en entier en mémoire.
+- **Nouvelles tentatives** : sur coupure, `429` ou `5xx`, l'appel est rejoué avec la même `Idempotency-Key` : jamais
+  de second débit.
+- **Erreurs typées** : `CleInvalide`, `CreditsInsuffisants` (avec `solde`), `TropDeDemandes`, `Introuvable`…
+- **Typé** : annotations complètes, vérifiables par votre éditeur ou mypy.
+
+## Liens
+
+- Documentation et référence : [opacte.eu/api](https://opacte.eu/api)
+- Tutoriel : [opacte.eu/api-tutorial](https://opacte.eu/api-tutorial)
+- Contrat HTTP publié (OpenAPI) : [opacte.eu/api/openapi.json](https://opacte.eu/api/openapi.json) — le SDK n'en est
+  qu'une mise en forme : vous pouvez vérifier ce qu'il envoie.
+
+La signature électronique par l'API, avec le document chiffré chez vous, arrive dans une prochaine version.
+
+Licence MIT.

opacte-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+opacte/__init__.py,sha256=7tLO_LIvDzcloph6bLjOCyvMUmQGIzFKVdaMPuQE-2w,659
+opacte/client.py,sha256=AVk29KAr2I0J1tHcN7h7V8D_jDY9WabVERUUs0a_W_4,7740
+opacte/empreintes.py,sha256=j2grbnlxqTvbfonXlbonrbFXS2qCziaK7sktocZ0GFU,1464
+opacte/erreurs.py,sha256=YjeNn1fdJ4K5HapEEwfwpr3EJiR_rMef9R0iWCw-ZdM,1739
+opacte/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+opacte-0.1.0.dist-info/METADATA,sha256=BcPUS4_zrSWE-2IfS6d9uTZk2IeANZn2GVG3cL-hOS0,3537
+opacte-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+opacte-0.1.0.dist-info/licenses/LICENSE,sha256=MwHg5Opb5TQcecAKibm8L649qPudrL1wCdnuz4PR54Q,1075
+opacte-0.1.0.dist-info/RECORD,,

opacte-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

opacte-0.1.0.dist-info/licenses/LICENSE

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