isof 0.1.0__tar.gz

isof-0.1.0/LICENSE

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

isof-0.1.0/PKG-INFO

@@ -0,0 +1,258 @@
+Metadata-Version: 2.4
+Name: isof
+Version: 0.1.0
+Summary: Lecteur et vérificateur du format ISOF — échange de données isotopiques
+Author-email: IsoFind SAS <colin.ferrari@isofind.tech>
+License: MIT
+Project-URL: Homepage, https://isofind.tech
+Project-URL: Repository, https://github.com/ColinFerrari/isof
+Project-URL: Bug Tracker, https://github.com/ColinFerrari/isof/issues
+Project-URL: Specification, https://isofind.tech/isof-spec
+Keywords: isotopes,geochemistry,traceability,forensics,ISOF
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=41.0
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.5; extra == "pandas"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pandas>=1.5; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Dynamic: license-file
+
+# isof
+
+Python reader and verifier for the **ISOF v1.0** format, an open standard for exchanging geochemical isotopic data.
+
+This format allows exchanging in a single file the isotopic data along with all associated metadata (analytical methods used for each sample, purification yields, analysis pipeline...), while enabling traceability of modifications once files are produced and certifying the origin of the file (laboratory certification).
+
+**Sovereignty and Confidentiality:** Signature verification is a 100% local process. No data is sent to a third-party server for validation.
+
+```python
+import isof
+
+report = isof.load("analyse_bolivie.isof")
+
+if report.is_authentic():
+    print(f"Signed by: {report.signature.signed_by}")
+
+df = report.to_pandas()
+print(df[["sample_name", "element", "ratio", "ratio_2se"]])
+```
+
+The ISOF format is used by [IsoFind](https://isofind.tech), but this parser is independent and can read any file compliant with the [ISOF v1.0 specification](https://isofind.tech/isof-spec).
+
+---
+
+## Installation
+
+```bash
+pip install isof
+```
+
+With pandas support:
+
+```bash
+pip install isof[pandas]
+```
+
+Requires Python ≥ 3.9.
+
+---
+
+## Usage
+
+### Load a file
+
+```python
+import isof
+
+report = isof.load("analyse.isof")
+print(report)
+# <ISOfDocument v1.0 — 12 échantillon(s) — IGE Grenoble>
+```
+
+From a JSON string (API, database):
+
+```python
+with open("analyse.isof") as f:
+    text = f.read()
+
+report = isof.loads(text)
+```
+
+### Verify integrity
+
+```python
+# Simple check
+if report.is_authentic():
+    print("Data integrity confirmed")
+
+# Detailed result
+result = report.verify()
+print(result.valid)      # bool
+print(result.level)      # 1 (SHA-256) or 2 (IsoFind PKI)
+print(result.signer)     # organisation or certificate CN
+print(result.signed_at)  # ISO 8601 timestamp
+print(result.reason)     # None if valid, error message otherwise
+```
+
+Two signature levels coexist in the format:
+
+| Level | Mechanism                  | Guarantee                                                      |
+| ----- | -------------------------- | -------------------------------------------------------------- |
+| 1     | SHA-256 over the data      | Integrity — file has not been modified since export            |
+| 2     | ECDSA P-256 + IsoFind PKI  | Authenticity — signed by a laboratory certified by IsoFind     |
+
+Verification works **offline**: IsoFind certificates are embedded in the package.
+
+### Access data
+
+```python
+# Sample list
+for sample in report.samples:
+    print(sample.id, sample.name, sample.classification)
+    for iso in sample.isotope_data:
+        print(f"  {iso.element} {iso.system} = {iso.ratio} ± {iso.ratio_2se}")
+
+# Look up a sample by identifier
+s = report.sample("BOL-24-01")
+
+# Filter
+sources = report.filter_samples(classification="source")
+sb_samples = report.filter_samples(element="Sb")
+combined = report.filter_samples(element="Pb", material_type="minerai")
+
+# Metadata
+print(report.created_by.organisation)
+print(report.project.reference)
+print(report.project.client)
+```
+
+### Purification yields
+
+```python
+# Yields for a sample
+yields = report.yields_for_sample("BOL-24-01")
+for y in yields:
+    print(f"{y.element}: {y.value_pct}%")
+
+# Contamination alerts (yield > 105%)
+suspects = report.suspicious_yields()
+for y in suspects:
+    print(f"Possible contamination — {y.sample_id} / {y.element}: {y.value_pct}%")
+```
+
+### Methods and pipelines
+
+```python
+# Preparation methods
+for key, method in report.methods.items():
+    print(f"{key} — {method.name} ({method.type})")
+    if method.yield_min_pct:
+        print(f"  Expected yield: {method.yield_min_pct}–{method.yield_max_pct}%")
+
+# Pipelines
+for key, pipeline in report.pipelines.items():
+    print(f"{pipeline.name} ({pipeline.element})")
+    for stage in pipeline.stages:
+        print(f"  {stage.order}. {stage.label}")
+```
+
+### Export to pandas
+
+```python
+df = report.to_pandas()
+
+# One row per isotopic measurement, sample metadata included
+df[["sample_name", "element", "ratio", "ratio_2se", "instrument"]]
+
+# Standard pandas filtering
+pb_data = df[df["element"] == "Pb"]
+sources = df[df["classification"] == "source"]
+```
+
+### CSV export
+
+```python
+report.to_csv("export.csv")
+# equivalent to report.to_pandas().to_csv("export.csv", index=False)
+```
+
+---
+
+## Error handling
+
+```python
+from isof.exceptions import ISOfParseError, ISOfVersionError, ISOfSignatureError
+
+try:
+    report = isof.load("file.isof")
+except ISOfVersionError as e:
+    print(f"Version {e.found} not supported, please update python-isof")
+except ISOfParseError as e:
+    print(f"Invalid file: {e}")
+
+# Corrupted vs. absent signature — two distinct cases
+result = report.verify()
+if result.level == 0:
+    print("No signature in this file")
+elif not result.valid:
+    print(f"Signature present but invalid: {result.reason}")
+```
+
+---
+
+## ISOF format
+
+Structure of an `.isof` document (JSON):
+
+```
+{
+  "isof_version": "1.0",
+  "created_at": "2025-03-10T14:32:00Z",
+  "created_by": { "software", "operator", "organisation" },
+  "project": { "name", "reference", "client", "classification" },
+  "samples": [ ... ],       ← isotopic data per sample
+  "methods": { ... },       ← preparation protocols
+  "pipelines": { ... },     ← method sequences per element
+  "purification": { ... },  ← measured yields per (sample, element)
+  "assignments": [ ... ],   ← method ↔ sample links
+  "signature": { ... }      ← optional
+}
+```
+
+Full specification: [isofind.tech/isof-spec](https://isofind.tech/isof-spec)
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/ColinFerrari/isof
+cd isof
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+This package is maintained by [Colin Ferrari](https://isofind.tech).
+The ISOF format is an open standard — third-party contributions and implementations are welcome.

isof-0.1.0/README.md

@@ -0,0 +1,223 @@
+# isof
+
+Python reader and verifier for the **ISOF v1.0** format, an open standard for exchanging geochemical isotopic data.
+
+This format allows exchanging in a single file the isotopic data along with all associated metadata (analytical methods used for each sample, purification yields, analysis pipeline...), while enabling traceability of modifications once files are produced and certifying the origin of the file (laboratory certification).
+
+**Sovereignty and Confidentiality:** Signature verification is a 100% local process. No data is sent to a third-party server for validation.
+
+```python
+import isof
+
+report = isof.load("analyse_bolivie.isof")
+
+if report.is_authentic():
+    print(f"Signed by: {report.signature.signed_by}")
+
+df = report.to_pandas()
+print(df[["sample_name", "element", "ratio", "ratio_2se"]])
+```
+
+The ISOF format is used by [IsoFind](https://isofind.tech), but this parser is independent and can read any file compliant with the [ISOF v1.0 specification](https://isofind.tech/isof-spec).
+
+---
+
+## Installation
+
+```bash
+pip install isof
+```
+
+With pandas support:
+
+```bash
+pip install isof[pandas]
+```
+
+Requires Python ≥ 3.9.
+
+---
+
+## Usage
+
+### Load a file
+
+```python
+import isof
+
+report = isof.load("analyse.isof")
+print(report)
+# <ISOfDocument v1.0 — 12 échantillon(s) — IGE Grenoble>
+```
+
+From a JSON string (API, database):
+
+```python
+with open("analyse.isof") as f:
+    text = f.read()
+
+report = isof.loads(text)
+```
+
+### Verify integrity
+
+```python
+# Simple check
+if report.is_authentic():
+    print("Data integrity confirmed")
+
+# Detailed result
+result = report.verify()
+print(result.valid)      # bool
+print(result.level)      # 1 (SHA-256) or 2 (IsoFind PKI)
+print(result.signer)     # organisation or certificate CN
+print(result.signed_at)  # ISO 8601 timestamp
+print(result.reason)     # None if valid, error message otherwise
+```
+
+Two signature levels coexist in the format:
+
+| Level | Mechanism                  | Guarantee                                                      |
+| ----- | -------------------------- | -------------------------------------------------------------- |
+| 1     | SHA-256 over the data      | Integrity — file has not been modified since export            |
+| 2     | ECDSA P-256 + IsoFind PKI  | Authenticity — signed by a laboratory certified by IsoFind     |
+
+Verification works **offline**: IsoFind certificates are embedded in the package.
+
+### Access data
+
+```python
+# Sample list
+for sample in report.samples:
+    print(sample.id, sample.name, sample.classification)
+    for iso in sample.isotope_data:
+        print(f"  {iso.element} {iso.system} = {iso.ratio} ± {iso.ratio_2se}")
+
+# Look up a sample by identifier
+s = report.sample("BOL-24-01")
+
+# Filter
+sources = report.filter_samples(classification="source")
+sb_samples = report.filter_samples(element="Sb")
+combined = report.filter_samples(element="Pb", material_type="minerai")
+
+# Metadata
+print(report.created_by.organisation)
+print(report.project.reference)
+print(report.project.client)
+```
+
+### Purification yields
+
+```python
+# Yields for a sample
+yields = report.yields_for_sample("BOL-24-01")
+for y in yields:
+    print(f"{y.element}: {y.value_pct}%")
+
+# Contamination alerts (yield > 105%)
+suspects = report.suspicious_yields()
+for y in suspects:
+    print(f"Possible contamination — {y.sample_id} / {y.element}: {y.value_pct}%")
+```
+
+### Methods and pipelines
+
+```python
+# Preparation methods
+for key, method in report.methods.items():
+    print(f"{key} — {method.name} ({method.type})")
+    if method.yield_min_pct:
+        print(f"  Expected yield: {method.yield_min_pct}–{method.yield_max_pct}%")
+
+# Pipelines
+for key, pipeline in report.pipelines.items():
+    print(f"{pipeline.name} ({pipeline.element})")
+    for stage in pipeline.stages:
+        print(f"  {stage.order}. {stage.label}")
+```
+
+### Export to pandas
+
+```python
+df = report.to_pandas()
+
+# One row per isotopic measurement, sample metadata included
+df[["sample_name", "element", "ratio", "ratio_2se", "instrument"]]
+
+# Standard pandas filtering
+pb_data = df[df["element"] == "Pb"]
+sources = df[df["classification"] == "source"]
+```
+
+### CSV export
+
+```python
+report.to_csv("export.csv")
+# equivalent to report.to_pandas().to_csv("export.csv", index=False)
+```
+
+---
+
+## Error handling
+
+```python
+from isof.exceptions import ISOfParseError, ISOfVersionError, ISOfSignatureError
+
+try:
+    report = isof.load("file.isof")
+except ISOfVersionError as e:
+    print(f"Version {e.found} not supported, please update python-isof")
+except ISOfParseError as e:
+    print(f"Invalid file: {e}")
+
+# Corrupted vs. absent signature — two distinct cases
+result = report.verify()
+if result.level == 0:
+    print("No signature in this file")
+elif not result.valid:
+    print(f"Signature present but invalid: {result.reason}")
+```
+
+---
+
+## ISOF format
+
+Structure of an `.isof` document (JSON):
+
+```
+{
+  "isof_version": "1.0",
+  "created_at": "2025-03-10T14:32:00Z",
+  "created_by": { "software", "operator", "organisation" },
+  "project": { "name", "reference", "client", "classification" },
+  "samples": [ ... ],       ← isotopic data per sample
+  "methods": { ... },       ← preparation protocols
+  "pipelines": { ... },     ← method sequences per element
+  "purification": { ... },  ← measured yields per (sample, element)
+  "assignments": [ ... ],   ← method ↔ sample links
+  "signature": { ... }      ← optional
+}
+```
+
+Full specification: [isofind.tech/isof-spec](https://isofind.tech/isof-spec)
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/ColinFerrari/isof
+cd isof
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+This package is maintained by [Colin Ferrari](https://isofind.tech).
+The ISOF format is an open standard — third-party contributions and implementations are welcome.

isof-0.1.0/isof/__init__.py

@@ -0,0 +1,93 @@
+"""
+isof — Lecteur et vérificateur du format ISOF v1.0 | ISOF v1.0 reader and verificator
+
+Usage minimal : | minimal use :
+
+    import isof
+
+    report = isof.load("analyse_bolivie.isof")
+    if report.is_authentic():
+        print(f"Signé par : {report.signature.signed_by}")
+    df = report.to_pandas()
+
+Le format ISOF est un standard ouvert pour l'échange de données isotopiques | ISOF format is an open standard for isotope data exchange
+Spécification : https://isofind.tech/isof-spec
+"""
+
+from .exceptions import ISOfError, ISOfParseError, ISOfSignatureError, ISOfVersionError
+from .models import (
+    Assignment,
+    CreatedBy,
+    IsotopeRecord,
+    Method,
+    Pipeline,
+    Project,
+    PurificationYield,
+    Sample,
+    Signature,
+)
+from .parser import ISOfDocument, load_file, load_string
+from .signature import VerificationResult
+
+__version__ = "0.1.0"
+__author__ = "Colin Ferrari"
+__all__ = [
+    # Fonctions d'entrée principales
+    "load",
+    "loads",
+    # Document
+    "ISOfDocument",
+    # Modèles
+    "Sample",
+    "IsotopeRecord",
+    "Method",
+    "Pipeline",
+    "PurificationYield",
+    "Assignment",
+    "CreatedBy",
+    "Project",
+    "Signature",
+    "VerificationResult",
+    # Exceptions
+    "ISOfError",
+    "ISOfParseError",
+    "ISOfVersionError",
+    "ISOfSignatureError",
+]
+
+
+def load(path) -> ISOfDocument:
+    """Charge un fichier .isof depuis le disque. | Load an .isof file from disk
+
+    Args:
+        path: Chemin vers le fichier, str ou pathlib.Path.
+
+    Returns:
+        ISOfDocument prêt à l'emploi. | Ready to use
+
+    Raises:
+        ISOfParseError: Fichier introuvable, JSON invalide, ou structure ISOF non reconnue. | Unfound file, invalid JSON or ISOF structure unrecognised
+        ISOfVersionError: Version du format non supportée par ce parser. | Format unsupported by this parser
+
+    Example: | Exemple :
+        >>> report = isof.load("analyse_bolivie.isof")
+        >>> print(report)
+        <ISOfDocument v1.0 — 12 échantillon(s) — IGE Grenoble>
+    """
+    _, doc = load_file(path)
+    return doc
+
+
+def loads(text: str) -> ISOfDocument:
+    """Charge un document ISOF depuis une chaîne JSON. | Load a ISOF document from a JSON chain.
+
+    Utile pour tester, ou pour lire depuis une API qui retourne du ISOF. | Useful to test or read from an API returning ISOF.
+
+    Args:
+        text: Contenu JSON d'un document ISOF. | JSON content of an ISOF document.
+
+    Returns:
+        ISOfDocument prêt à l'emploi. | ISOFDocument ready to use.
+    """
+    _, doc = load_string(text)
+    return doc

isof-0.1.0/isof/exceptions.py

@@ -0,0 +1,71 @@
+"""
+Hiérarchie d'exceptions du parser ISOF.
+
+On distingue les erreurs de parsing (fichier malformé ou incompatible)
+des erreurs de signature (fichier valide structurellement mais dont
+l'intégrité ne peut pas être confirmée). Cette séparation permet aux
+appelants de traiter les deux cas différemment sans inspecter le message.
+
+ISOF parser exception hierarchy.
+
+A distinction is made between parsing errors (malformed or incompatible file)
+and signature errors (structurally valid file but whose
+integrity cannot be confirmed). This separation allows
+callers to handle the two cases differently without inspecting the message.
+"""
+
+
+class ISOfError(Exception):
+    """
+    Classe de base, attraper celle-ci pour gérer toutes les erreurs ISOF.
+    Base class, catch this one to handle all ISOF errors.
+    """
+
+
+class ISOfParseError(ISOfError):
+    """
+    Le fichier n'est pas un document ISOF valide ou lisible.
+    Causes typiques : JSON malformé, champ obligatoire absent,
+    version du format incompatible avec ce parser.
+    
+    The file is not a valid or readable ISOF document.
+    Typical causes: Malformed JSON, missing required field,
+    format version incompatible with this parser.
+    """
+
+
+class ISOfVersionError(ISOfParseError):
+    """
+    La version du format déclarée dans le fichier n'est pas supportée.
+    Elle est différente d'ISOfParseError pour que les outils puissent
+    suggérer une mise à jour du parser plutôt qu'un message d'erreur classique.
+    
+    The format version declared in the file is not supported.
+    It differs from ISOfParseError so that tools can
+    suggest a parser update rather than a standard error message.
+    """
+
+    def __init__(self, found: str, supported: tuple[str, ...]) -> None:
+        self.found = found
+        self.supported = supported
+        super().__init__(
+            f"Version ISOF '{found}' non supportée. "
+            f"Versions supportées : {', '.join(supported)}"
+        )
+
+
+class ISOfSignatureError(ISOfError):
+    """
+    La signature est présente mais ne peut pas être vérifiée.
+
+    Distinct d'une signature invalide (is_authentic() → False) :
+    ici c'est le processus de vérification lui-même qui a échoué,
+    par exemple parce que l'algorithme est inconnu ou que le certificat
+    est illisible.
+    
+    The signature is present but cannot be verified.
+    
+    This differs from an invalid signature (is_authentic() → False):
+    here, the verification process itself failed, for example,
+    because the algorithm is unknown or the certificate is unreadable.
+    """