evoseer-utils 0.1.4__tar.gz

evoseer_utils-0.1.4/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.1
+Name: evoseer-utils
+Version: 0.1.4
+Summary: Shared library for mutation management across modules
+Author: benoît de Witte
+Requires-Python: >=3.9,<4.0
+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: Programming Language :: Python :: 3.13
+Requires-Dist: pydantic (>=2.0,<3.0)
+Description-Content-Type: text/markdown
+
+# Mutation Library
+
+Shared library for mutation management across modules.
+
+## Components
+
+### `DbConnection` - Singleton DB connection
+```python
+from libs import DbConnection
+
+DbConnection.set_db_path("mutations.db")
+conn = DbConnection.get_connection()
+```
+
+### `Mutation` - Pydantic model with DB integration
+
+#### States
+- `"full"`: Has both id and (chrom, pos, ref, alt)
+- `"miss_id"`: Has coordinates, missing id
+- `"miss_attributes"`: Has id, missing coordinates
+
+#### Creation patterns
+
+```python
+# With coordinates (lazy load id)
+mut = Mutation(chrom=17, pos=7577548, ref="C", alt="T")
+
+# With id (lazy load attributes)
+mut = Mutation(id=123)
+
+# With both
+mut = Mutation(id=123, chrom=17, pos=7577548, ref="C", alt="T")
+```
+
+#### Methods
+
+**Instance methods:**
+```python
+mut.fetch_id_from_db()           # Get id from coordinates
+mut.fetch_attributes_from_db()   # Get coordinates from id
+mut.ensure_in_db()              # Create if missing, return id
+```
+
+**Class methods (batch):**
+```python
+Mutation.fetch_ids_from_db_batch(mutations)
+Mutation.fetch_attributes_from_db_batch(mutations)
+Mutation.ensure_in_db_batch(mutations)
+```
+
+## Usage in modules with OutputDescription (fully automatic)
+
+`OutputDescription` is a base class that provides automatic DB insertion for module outputs.
+
+```python
+from pydantic import Field
+from typing import ClassVar, List
+from libs import OutputDescription, DbConnection, Mutation
+
+class MyModuleOutput(OutputDescription):
+    table_name: ClassVar[str] = "tool_mymodule"
+    db_fields: ClassVar[List[str]] = ["my_score", "my_prediction"]
+
+    my_score: float = Field(..., description="Module score")
+    my_prediction: str = Field(..., description="Prediction")
+
+# Setup
+DbConnection.set_db_path("mutations.db")
+
+# Single insertion (automatic table creation + mutation insertion)
+output = MyModuleOutput(
+    mutation=Mutation(chrom=17, pos=7577548, ref="C", alt="T"),
+    version="1.0.0",  # Required field (free text)
+    my_score=0.85,
+    my_prediction="pathogenic"
+)
+output.insert_to_db()  # Creates table if needed, ensures mutation exists, inserts
+
+# Batch insertion
+outputs = [...]
+MyModuleOutput.insert_batch_to_db(outputs)
+```
+
+**What happens automatically:**
+- Table creation with correct SQL types (inferred from Python types)
+- Mutation insertion/lookup
+- Index creation on mutation_id
+- `version` field automatically added to table and insertion
+- INSERT OR REPLACE (idempotent)
+
+**Note:** `version` field is required in all OutputDescription subclasses. Format is free text.
+
+## Chromosome encoding
+
+- Autosomes: `1-22`
+- X: `23`
+- Y: `24`
+
+Helper functions:
+
+```python
+from libs.src.mutations import chrom_to_int, int_to_chrom
+
+chrom_to_int("chr17")  # 17
+chrom_to_int("chrX")  # 23
+int_to_chrom(23)  # "chrX"
+```
+
+## Tests
+
+```bash
+# From project root
+.venv/bin/python3 libs/tests/test_mutations_lib.py
+
+# Or use the test runner
+libs/tests/run_tests.sh
+```
+
+## Examples
+
+```bash
+python3 example_mutations_lib.py
+python3 modules/boostdm/output_description_example.py
+```
+

evoseer_utils-0.1.4/README.md

@@ -0,0 +1,124 @@
+# Mutation Library
+
+Shared library for mutation management across modules.
+
+## Components
+
+### `DbConnection` - Singleton DB connection
+```python
+from libs import DbConnection
+
+DbConnection.set_db_path("mutations.db")
+conn = DbConnection.get_connection()
+```
+
+### `Mutation` - Pydantic model with DB integration
+
+#### States
+- `"full"`: Has both id and (chrom, pos, ref, alt)
+- `"miss_id"`: Has coordinates, missing id
+- `"miss_attributes"`: Has id, missing coordinates
+
+#### Creation patterns
+
+```python
+# With coordinates (lazy load id)
+mut = Mutation(chrom=17, pos=7577548, ref="C", alt="T")
+
+# With id (lazy load attributes)
+mut = Mutation(id=123)
+
+# With both
+mut = Mutation(id=123, chrom=17, pos=7577548, ref="C", alt="T")
+```
+
+#### Methods
+
+**Instance methods:**
+```python
+mut.fetch_id_from_db()           # Get id from coordinates
+mut.fetch_attributes_from_db()   # Get coordinates from id
+mut.ensure_in_db()              # Create if missing, return id
+```
+
+**Class methods (batch):**
+```python
+Mutation.fetch_ids_from_db_batch(mutations)
+Mutation.fetch_attributes_from_db_batch(mutations)
+Mutation.ensure_in_db_batch(mutations)
+```
+
+## Usage in modules with OutputDescription (fully automatic)
+
+`OutputDescription` is a base class that provides automatic DB insertion for module outputs.
+
+```python
+from pydantic import Field
+from typing import ClassVar, List
+from libs import OutputDescription, DbConnection, Mutation
+
+class MyModuleOutput(OutputDescription):
+    table_name: ClassVar[str] = "tool_mymodule"
+    db_fields: ClassVar[List[str]] = ["my_score", "my_prediction"]
+
+    my_score: float = Field(..., description="Module score")
+    my_prediction: str = Field(..., description="Prediction")
+
+# Setup
+DbConnection.set_db_path("mutations.db")
+
+# Single insertion (automatic table creation + mutation insertion)
+output = MyModuleOutput(
+    mutation=Mutation(chrom=17, pos=7577548, ref="C", alt="T"),
+    version="1.0.0",  # Required field (free text)
+    my_score=0.85,
+    my_prediction="pathogenic"
+)
+output.insert_to_db()  # Creates table if needed, ensures mutation exists, inserts
+
+# Batch insertion
+outputs = [...]
+MyModuleOutput.insert_batch_to_db(outputs)
+```
+
+**What happens automatically:**
+- Table creation with correct SQL types (inferred from Python types)
+- Mutation insertion/lookup
+- Index creation on mutation_id
+- `version` field automatically added to table and insertion
+- INSERT OR REPLACE (idempotent)
+
+**Note:** `version` field is required in all OutputDescription subclasses. Format is free text.
+
+## Chromosome encoding
+
+- Autosomes: `1-22`
+- X: `23`
+- Y: `24`
+
+Helper functions:
+
+```python
+from libs.src.mutations import chrom_to_int, int_to_chrom
+
+chrom_to_int("chr17")  # 17
+chrom_to_int("chrX")  # 23
+int_to_chrom(23)  # "chrX"
+```
+
+## Tests
+
+```bash
+# From project root
+.venv/bin/python3 libs/tests/test_mutations_lib.py
+
+# Or use the test runner
+libs/tests/run_tests.sh
+```
+
+## Examples
+
+```bash
+python3 example_mutations_lib.py
+python3 modules/boostdm/output_description_example.py
+```

evoseer_utils-0.1.4/evoseer_utils/__init__.py

@@ -0,0 +1,5 @@
+from evoseer_utils.db_connection import DbConnection
+from evoseer_utils.mutations import Mutation
+from evoseer_utils.output_description import OutputDescription
+
+__all__ = ["DbConnection", "Mutation", "OutputDescription"]

evoseer_utils-0.1.4/evoseer_utils/data/schema.sql

@@ -0,0 +1,55 @@
+-- Schéma SQLite pour annotations de mutations génomiques
+-- Simple, modulaire, optimisé pour ML
+-- Convention chromosomes: 1-22 (autosomes), 23=X, 24=Y
+
+-- Table centrale des mutations
+CREATE TABLE mutations (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    chrom INTEGER NOT NULL,         -- 1-22, 23=X, 24=Y
+    pos INTEGER NOT NULL,
+    ref TEXT NOT NULL,
+    alt TEXT NOT NULL,
+    UNIQUE(chrom, pos, ref, alt)
+);
+CREATE INDEX idx_mutations_location ON mutations(chrom, pos);
+
+-- Table des gènes (depuis GTF canonique)
+CREATE TABLE genes (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    gene_id TEXT NOT NULL UNIQUE,  -- ENSG...
+    gene_name TEXT,                 -- Symbole (ex: TP53)
+    chrom INTEGER NOT NULL,         -- 1-22, 23=X, 24=Y
+    start INTEGER NOT NULL,         -- Start du gène
+    end INTEGER NOT NULL,           -- End du gène
+    strand TEXT NOT NULL,           -- + ou -
+    tss INTEGER NOT NULL            -- Transcription Start Site (pour promoteur)
+);
+CREATE INDEX idx_genes_location ON genes(chrom, start, end);
+CREATE INDEX idx_genes_name ON genes(gene_name);
+
+-- Table des features génomiques (depuis GTF)
+-- Stocke les coordonnées permanentes des exons, introns, UTRs, promoteurs
+CREATE TABLE genomic_features (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    gene_id INTEGER NOT NULL,
+    annotation_type TEXT NOT NULL,      -- 'exon', 'intron', 'UTR5', 'UTR3', 'promoter'
+    feature_start INTEGER NOT NULL,
+    feature_end INTEGER NOT NULL,
+    transcript_id TEXT,                 -- ID du transcript canonique
+    FOREIGN KEY (gene_id) REFERENCES genes(id) ON DELETE CASCADE
+);
+CREATE INDEX idx_genomic_features_gene ON genomic_features(gene_id);
+CREATE INDEX idx_genomic_features_location ON genomic_features(feature_start, feature_end);
+
+-- Table de liaison: mutation <-> genomic_feature
+-- Une mutation peut toucher plusieurs features (ex: exon de 2 gènes chevauchants)
+CREATE TABLE mutation_annotations (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    mutation_id INTEGER NOT NULL,
+    feature_id INTEGER,                 -- NULL si intergenic
+    FOREIGN KEY (mutation_id) REFERENCES mutations(id) ON DELETE CASCADE,
+    FOREIGN KEY (feature_id) REFERENCES genomic_features(id) ON DELETE CASCADE,
+    UNIQUE(mutation_id, feature_id)     -- Éviter les doublons
+);
+CREATE INDEX idx_mutation_annotations_mutation ON mutation_annotations(mutation_id);
+CREATE INDEX idx_mutation_annotations_feature ON mutation_annotations(feature_id);

evoseer_utils-0.1.4/evoseer_utils/db_connection.py

@@ -0,0 +1,80 @@
+"""
+Gestion de la connexion à la base de données SQLite (singleton)
+"""
+
+import sqlite3
+from pathlib import Path
+from typing import Optional
+
+
+class DbConnection:
+    """
+    Singleton pour gérer la connexion à la base de données SQLite
+
+    Usage:
+        DbConnection.set_db_path("mutations.db")
+        conn = DbConnection.get_connection()
+    """
+
+    _instance: Optional["DbConnection"] = None
+    _connection: Optional[sqlite3.Connection] = None
+    _db_path: Optional[str] = None
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    @classmethod
+    def set_db_path(cls, db_path: str) -> None:
+        """
+        Configure le chemin vers la base de données
+
+        Args:
+            db_path: Chemin vers le fichier SQLite
+        """
+        if cls._db_path != db_path:
+            # Fermer l'ancienne connexion si elle existe
+            if cls._connection is not None:
+                cls._connection.close()
+                cls._connection = None
+
+            cls._db_path = db_path
+
+    @classmethod
+    def get_connection(cls) -> sqlite3.Connection:
+        """
+        Retourne la connexion SQLite (crée si nécessaire)
+
+        Returns:
+            Connexion SQLite
+
+        Raises:
+            RuntimeError: Si le chemin DB n'a pas été configuré
+        """
+        if cls._db_path is None:
+            raise RuntimeError("Database path not set. Call DbConnection.set_db_path() first.")
+
+        if not Path(cls._db_path).exists():
+            raise FileNotFoundError(
+                f"Database file not found: {cls._db_path}. " f"Run init_database.py first."
+            )
+
+        # Créer la connexion si elle n'existe pas
+        if cls._connection is None:
+            cls._connection = sqlite3.connect(cls._db_path)
+            cls._connection.row_factory = sqlite3.Row  # Accès par nom de colonne
+
+        return cls._connection
+
+    @classmethod
+    def close(cls) -> None:
+        """Ferme la connexion à la base de données"""
+        if cls._connection is not None:
+            cls._connection.close()
+            cls._connection = None
+
+    @classmethod
+    def is_configured(cls) -> bool:
+        """Vérifie si la connexion est configurée"""
+        return cls._db_path is not None

evoseer_utils-0.1.4/evoseer_utils/mutations.py

@@ -0,0 +1,406 @@
+"""
+Modèle Pydantic pour les mutations génomiques
+"""
+
+from typing import Literal, Optional
+
+from pydantic import BaseModel, field_validator, model_validator
+
+from .db_connection import DbConnection
+
+
+def chrom_to_int(chrom_str: str) -> Optional[int]:
+    """Convertit chr1-chr22, chrX, chrY en 1-24"""
+    chrom_str = str(chrom_str).upper().replace("chr", "")
+    if chrom_str == "X":
+        return 23
+    elif chrom_str == "Y":
+        return 24
+    elif chrom_str in ["M", "MT"]:
+        return None
+    else:
+        try:
+            return int(chrom_str)
+        except ValueError:
+            return None
+
+
+def int_to_chrom(chrom_int: int) -> str:
+    """Convertit 1-24 en chr1-chr22, chrX, chrY"""
+    if chrom_int == 23:
+        return "chrX"
+    elif chrom_int == 24:
+        return "chrY"
+    else:
+        return f"chr{chrom_int}"
+
+
+class Mutation(BaseModel):
+    """
+    Modèle pour une mutation génomique
+
+    Attributs:
+        id: ID de la mutation dans la DB (auto-généré)
+        chrom: Chromosome (1-22, 23=X, 24=Y)
+        pos: Position génomique
+        ref: Allèle de référence
+        alt: Allèle alternatif
+
+    Validation:
+        - Soit id est fourni
+        - Soit (chrom, pos, ref, alt) sont tous fournis
+        - Soit les deux
+
+    Usage:
+        # Avec ID seulement (lazy load des attributs)
+        mutation = Mutation(id=123)
+        mutation.fetch_attributes_from_db()
+
+        # Avec coordonnées (lazy load de l'ID)
+        mutation = Mutation(chrom=17, pos=7577548, ref="C", alt="T")
+        mutation.fetch_id_from_db()
+
+        # Avec tout
+        mutation = Mutation(id=123, chrom=17, pos=7577548, ref="C", alt="T")
+    """
+
+    id: Optional[int] = None
+    chrom: Optional[int] = None
+    pos: Optional[int] = None
+    ref: Optional[str] = None
+    alt: Optional[str] = None
+
+    @field_validator("chrom", mode="before")
+    @classmethod
+    def normalize_chrom(cls, v):
+        return chrom_to_int(v)
+
+    @model_validator(mode="after")
+    def validate_mutation(self):
+        """
+        Valide qu'on a soit id, soit (chrom, pos, ref, alt), soit les deux
+        """
+        has_id = self.id is not None
+        has_coords = all(
+            [
+                self.chrom is not None,
+                self.pos is not None,
+                self.ref is not None,
+                self.alt is not None,
+            ]
+        )
+
+        if not has_id and not has_coords:
+            raise ValueError("Must provide either 'id' or all of (chrom, pos, ref, alt)")
+
+        # Vérifier que si on a des coordonnées partielles, elles sont complètes
+        coord_fields = [self.chrom, self.pos, self.ref, self.alt]
+        partial_coords = any(f is not None for f in coord_fields)
+
+        if partial_coords and not has_coords:
+            raise ValueError("If providing coordinates, must provide all of (chrom, pos, ref, alt)")
+
+        return self
+
+    @property
+    def state(self) -> Literal["full", "miss_id", "miss_attributes"]:
+        """
+        Retourne l'état de la mutation
+
+        Returns:
+            - "full": id et attributs présents
+            - "miss_id": attributs présents, id manquant
+            - "miss_attributes": id présent, attributs manquants
+        """
+        has_id = self.id is not None
+        has_coords = all(
+            [
+                self.chrom is not None,
+                self.pos is not None,
+                self.ref is not None,
+                self.alt is not None,
+            ]
+        )
+
+        if has_id and has_coords:
+            return "full"
+        elif has_coords:
+            return "miss_id"
+        else:
+            return "miss_attributes"
+
+    def fetch_id_from_db(self) -> Optional[int]:
+        """
+        Récupère l'ID de la mutation depuis la DB via (chrom, pos, ref, alt)
+        Met à jour self.id si trouvé
+
+        Returns:
+            ID de la mutation ou None si non trouvée
+
+        Raises:
+            ValueError: Si les coordonnées ne sont pas complètes
+        """
+        if self.state == "miss_attributes":
+            raise ValueError("Cannot fetch ID: coordinates (chrom, pos, ref, alt) are required")
+
+        conn = DbConnection.get_connection()
+        cursor = conn.cursor()
+
+        cursor.execute(
+            """
+            SELECT id FROM mutations
+            WHERE chrom=? AND pos=? AND ref=? AND alt=?
+        """,
+            (self.chrom, self.pos, self.ref, self.alt),
+        )
+
+        result = cursor.fetchone()
+        if result:
+            self.id = result["id"]
+            return self.id
+
+        return None
+
+    def fetch_attributes_from_db(self) -> bool:
+        """
+        Récupère les attributs de la mutation depuis la DB via l'ID
+        Met à jour (chrom, pos, ref, alt) si trouvés
+
+        Returns:
+            True si trouvé, False sinon
+
+        Raises:
+            ValueError: Si l'ID n'est pas fourni
+        """
+        if self.id is None:
+            raise ValueError("Cannot fetch attributes: id is required")
+
+        conn = DbConnection.get_connection()
+        cursor = conn.cursor()
+
+        cursor.execute(
+            """
+            SELECT chrom, pos, ref, alt FROM mutations
+            WHERE id=?
+        """,
+            (self.id,),
+        )
+
+        result = cursor.fetchone()
+        if result:
+            self.chrom = result["chrom"]
+            self.pos = result["pos"]
+            self.ref = result["ref"]
+            self.alt = result["alt"]
+            return True
+
+        return False
+
+    def ensure_in_db(self, annotate: bool = True) -> int:
+        """
+        S'assure que la mutation existe dans la DB (crée si nécessaire)
+        Met à jour self.id
+
+        Args:
+            annotate: Si True, annote automatiquement avec le contexte génomique
+
+        Returns:
+            ID de la mutation
+
+        Raises:
+            ValueError: Si les coordonnées ne sont pas complètes
+        """
+        if self.state == "miss_attributes":
+            raise ValueError("Cannot ensure in DB: coordinates (chrom, pos, ref, alt) are required")
+
+        # Si on a déjà l'ID, on vérifie qu'il existe
+        if self.id is not None:
+            conn = DbConnection.get_connection()
+            cursor = conn.cursor()
+            cursor.execute("SELECT id FROM mutations WHERE id=?", (self.id,))
+            if cursor.fetchone():
+                return self.id
+
+        # Sinon, chercher par coordonnées
+        existing_id = self.fetch_id_from_db()
+        if existing_id is not None:
+            return existing_id
+
+        # Si pas trouvé, créer
+        conn = DbConnection.get_connection()
+        cursor = conn.cursor()
+
+        cursor.execute(
+            """
+            INSERT INTO mutations (chrom, pos, ref, alt)
+            VALUES (?, ?, ?, ?)
+        """,
+            (self.chrom, self.pos, self.ref, self.alt),
+        )
+
+        self.id = cursor.lastrowid
+
+        # Annoter si demandé
+        if annotate:
+            self._annotate_mutation()
+
+        conn.commit()
+        return self.id
+
+    def _annotate_mutation(self) -> None:
+        """
+        Annote la mutation avec le contexte génomique
+        (méthode interne, appelée par ensure_in_db)
+        """
+        if self.id is None or self.chrom is None or self.pos is None:
+            return
+
+        conn = DbConnection.get_connection()
+        cursor = conn.cursor()
+
+        # Supprimer les anciennes annotations
+        cursor.execute("DELETE FROM mutation_annotations WHERE mutation_id = ?", (self.id,))
+
+        # Trouver les features qui chevauchent
+        cursor.execute(
+            """
+            SELECT gf.id
+            FROM genomic_features gf
+            JOIN genes g ON gf.gene_id = g.id
+            WHERE g.chrom = ? AND gf.feature_start <= ? AND gf.feature_end >= ?
+        """,
+            (self.chrom, self.pos, self.pos),
+        )
+
+        feature_ids = [row["id"] for row in cursor.fetchall()]
+
+        if feature_ids:
+            for feature_id in feature_ids:
+                cursor.execute(
+                    """
+                    INSERT INTO mutation_annotations (mutation_id, feature_id)
+                    VALUES (?, ?)
+                """,
+                    (self.id, feature_id),
+                )
+        else:
+            # Intergenic
+            cursor.execute(
+                """
+                INSERT INTO mutation_annotations (mutation_id, feature_id)
+                VALUES (?, NULL)
+            """,
+                (self.id,),
+            )
+
+    @classmethod
+    def fetch_ids_from_db_batch(cls, mutations: list["Mutation"]) -> None:
+        """
+        Récupère les IDs pour un batch de mutations (modifie en place)
+
+        Args:
+            mutations: Liste de mutations (doivent avoir chrom, pos, ref, alt)
+
+        Raises:
+            ValueError: Si une mutation n'a pas de coordonnées complètes
+        """
+        conn = DbConnection.get_connection()
+        cursor = conn.cursor()
+
+        for mutation in mutations:
+            if mutation.state == "miss_attributes":
+                raise ValueError(f"Mutation {mutation} missing coordinates")
+
+            cursor.execute(
+                """
+                SELECT id FROM mutations
+                WHERE chrom=? AND pos=? AND ref=? AND alt=?
+            """,
+                (mutation.chrom, mutation.pos, mutation.ref, mutation.alt),
+            )
+
+            result = cursor.fetchone()
+            if result:
+                mutation.id = result["id"]
+
+    @classmethod
+    def fetch_attributes_from_db_batch(cls, mutations: list["Mutation"]) -> None:
+        """
+        Récupère les attributs pour un batch de mutations (modifie en place)
+
+        Args:
+            mutations: Liste de mutations (doivent avoir id)
+
+        Raises:
+            ValueError: Si une mutation n'a pas d'ID
+        """
+        conn = DbConnection.get_connection()
+        cursor = conn.cursor()
+
+        for mutation in mutations:
+            if mutation.id is None:
+                raise ValueError(f"Mutation {mutation} missing id")
+
+            cursor.execute(
+                """
+                SELECT chrom, pos, ref, alt FROM mutations
+                WHERE id=?
+            """,
+                (mutation.id,),
+            )
+
+            result = cursor.fetchone()
+            if result:
+                mutation.chrom = result["chrom"]
+                mutation.pos = result["pos"]
+                mutation.ref = result["ref"]
+                mutation.alt = result["alt"]
+
+    @classmethod
+    def ensure_in_db_batch(cls, mutations: list["Mutation"], annotate: bool = True) -> None:
+        """
+        S'assure que toutes les mutations existent dans la DB (crée si nécessaire)
+        Modifie les mutations en place pour ajouter les IDs
+
+        Args:
+            mutations: Liste de mutations (doivent avoir chrom, pos, ref, alt)
+            annotate: Si True, annote automatiquement avec le contexte génomique
+
+        Raises:
+            ValueError: Si une mutation n'a pas de coordonnées complètes
+        """
+        # D'abord, essayer de récupérer les IDs existants
+        cls.fetch_ids_from_db_batch(mutations)
+
+        # Créer les mutations qui n'existent pas
+        conn = DbConnection.get_connection()
+        cursor = conn.cursor()
+
+        for mutation in mutations:
+            if mutation.id is None:
+                # Créer la mutation
+                cursor.execute(
+                    """
+                    INSERT INTO mutations (chrom, pos, ref, alt)
+                    VALUES (?, ?, ?, ?)
+                """,
+                    (mutation.chrom, mutation.pos, mutation.ref, mutation.alt),
+                )
+
+                mutation.id = cursor.lastrowid
+
+                # Annoter si demandé
+                if annotate:
+                    mutation._annotate_mutation()
+
+        conn.commit()
+
+    def __repr__(self) -> str:
+        if self.state == "full":
+            chrom_str = int_to_chrom(self.chrom)
+            return f"Mutation(id={self.id}, {chrom_str}:{self.pos} {self.ref}>{self.alt})"
+        elif self.state == "miss_id":
+            chrom_str = int_to_chrom(self.chrom)
+            return f"Mutation({chrom_str}:{self.pos} {self.ref}>{self.alt}, id=?)"
+        else:
+            return f"Mutation(id={self.id}, coords=?)"

evoseer_utils-0.1.4/evoseer_utils/output_description.py

@@ -0,0 +1,131 @@
+from typing import ClassVar, Optional, get_type_hints
+
+from pydantic import BaseModel
+
+from evoseer_utils.db_connection import DbConnection
+from evoseer_utils.mutations import Mutation
+
+
+class OutputDescription(BaseModel):
+    mutation: Mutation
+    version: ClassVar[str]
+
+    _table_name: ClassVar[str]
+    db_fields: ClassVar[list[str]]
+
+    @property
+    def table_name(self) -> str:
+        # we do that because it allows automatic views based on "annot_" prefix
+        return "annot_" + self._table_name
+
+    @classmethod
+    def _get_all_db_fields(cls) -> list[str]:
+        # Always include version automatically
+        return ["version"] + cls.db_fields
+
+    @classmethod
+    def _python_type_to_sql(cls, python_type: type) -> str:
+        type_map = {
+            int: "INTEGER",
+            float: "REAL",
+            str: "TEXT",
+            bool: "INTEGER",
+        }
+        # Handle Optional types
+        origin = getattr(python_type, "__origin__", None)
+        if origin is type(None) or str(python_type).startswith("typing.Union"):
+            args = getattr(python_type, "__args__", ())
+            if args:
+                python_type = args[0] if args[0] is not type(None) else args[1]
+
+        return type_map.get(python_type, "TEXT")
+
+    @classmethod
+    def _ensure_table_exists(cls, table_name: str) -> None:
+        conn = DbConnection.get_connection()
+        cursor = conn.cursor()
+
+        type_hints = get_type_hints(cls)
+        columns = ["id INTEGER PRIMARY KEY AUTOINCREMENT", "mutation_id INTEGER NOT NULL UNIQUE"]
+
+        for field_name in cls._get_all_db_fields():
+            field_type = type_hints.get(field_name, str)
+            sql_type = cls._python_type_to_sql(field_type)
+            columns.append(f"{field_name} {sql_type}")
+
+        columns.append("FOREIGN KEY (mutation_id) REFERENCES mutations(id) ON DELETE CASCADE")
+
+        cursor.execute(f"""
+            CREATE TABLE IF NOT EXISTS {table_name} (
+                {', '.join(columns)}
+            )
+        """)
+
+        cursor.execute(f"""
+            CREATE INDEX IF NOT EXISTS idx_{table_name}_mutation
+            ON {table_name}(mutation_id)
+        """)
+
+        conn.commit()
+
+    def insert_to_db(self, table_name: Optional[str] = None) -> None:
+        if table_name is None:
+            table_name = self.table_name
+
+        self._ensure_table_exists(table_name)
+        self.mutation.ensure_in_db()
+
+        conn = DbConnection.get_connection()
+        cursor = conn.cursor()
+
+        all_fields = self._get_all_db_fields()
+        fields = ["mutation_id"] + all_fields
+        values = [self.mutation.id] + [getattr(self, field) for field in all_fields]
+
+        placeholders = ", ".join(["?"] * len(values))
+
+        cursor.execute(
+            f"""
+            INSERT OR REPLACE INTO {table_name}
+            ({', '.join(fields)})
+            VALUES ({placeholders})
+        """,
+            values,
+        )
+
+        conn.commit()
+
+    @classmethod
+    def insert_batch_to_db(
+        cls, outputs: list["OutputDescription"], table_name: Optional[str] = None
+    ) -> None:
+        if table_name is None:
+            table_name = cls.table_name
+
+        cls._ensure_table_exists(table_name)
+
+        mutations = [output.mutation for output in outputs]
+        Mutation.ensure_in_db_batch(mutations)
+
+        conn = DbConnection.get_connection()
+        cursor = conn.cursor()
+
+        all_fields = cls._get_all_db_fields()
+        fields = ["mutation_id"] + all_fields
+        placeholders = ", ".join(["?"] * len(fields))
+
+        values_list = []
+        for output in outputs:
+            values = [output.mutation.id] + [getattr(output, field) for field in all_fields]
+            values_list.append(values)
+
+        cursor.executemany(
+            f"""
+            INSERT OR REPLACE INTO {table_name}
+            ({', '.join(fields)})
+            VALUES ({placeholders})
+        """,
+            values_list,
+        )
+
+        conn.commit()

evoseer_utils-0.1.4/evoseer_utils/test_utils.py

@@ -0,0 +1,269 @@
+"""
+Test utilities for database testing
+
+Provides helpers for creating and managing test databases for unit tests.
+"""
+
+import sqlite3
+import tempfile
+from pathlib import Path
+from typing import Optional
+
+from evoseer_utils.db_connection import DbConnection
+
+
+class DatabaseFixture:
+    """
+    Context manager for creating and managing test databases.
+
+    Usage:
+        with DatabaseFixture() as db:
+            # Use db.path for database operations
+            DbConnection.set_db_path(db.path)
+            # Run tests...
+        # Database is automatically cleaned up
+    """
+
+    def __init__(self, schema_file: Optional[str] = None):
+        """
+        Initialize test database context manager.
+
+        Args:
+            schema_file: Optional path to schema.sql file. If not provided,
+                        uses the default schema from project root.
+        """
+        self.schema_file = schema_file
+        self.temp_file = None
+        self.path = None
+        self._conn = None
+
+    def __enter__(self):
+        """Create temporary database and initialize schema"""
+        # Create temporary database file
+        self.temp_file = tempfile.NamedTemporaryFile(mode="w", suffix=".db", delete=False)
+        self.path = self.temp_file.name
+        self.temp_file.close()
+
+        # Load schema
+        if self.schema_file is None:
+            # Use default schema from data directory
+            self.schema_file = str(Path(__file__).parent / "data" / "schema.sql")
+
+        self._init_schema()
+
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Clean up temporary database"""
+        # Close any active connections
+        if self._conn is not None:
+            self._conn.close()
+
+        # Close DbConnection singleton
+        DbConnection.close()
+
+        # Remove temporary file
+        if self.path and Path(self.path).exists():
+            Path(self.path).unlink()
+
+    def _init_schema(self):
+        """Initialize database with schema"""
+        conn = sqlite3.connect(self.path)
+        cursor = conn.cursor()
+
+        # Read and execute schema
+        with open(self.schema_file) as f:
+            schema = f.read()
+
+        cursor.executescript(schema)
+        conn.commit()
+        conn.close()
+
+    def get_connection(self) -> sqlite3.Connection:
+        """
+        Get a connection to the test database.
+
+        Returns:
+            sqlite3.Connection instance
+        """
+        if self._conn is None:
+            self._conn = sqlite3.connect(self.path)
+            self._conn.row_factory = sqlite3.Row
+
+        return self._conn
+
+    def add_test_gene(
+        self,
+        gene_id: str,
+        gene_name: str,
+        chrom: int,
+        start: int,
+        end: int,
+        strand: str = "+",
+        tss: Optional[int] = None,
+    ) -> int:
+        """
+        Add a test gene to the database.
+
+        Args:
+            gene_id: Ensembl gene ID (e.g., ENSG00000141510)
+            gene_name: Gene symbol (e.g., TP53)
+            chrom: Chromosome (1-24)
+            start: Gene start position
+            end: Gene end position
+            strand: Strand (+ or -)
+            tss: Transcription start site (defaults to start)
+
+        Returns:
+            Database ID of inserted gene
+        """
+        if tss is None:
+            tss = start
+
+        conn = self.get_connection()
+        cursor = conn.cursor()
+
+        cursor.execute(
+            """
+            INSERT INTO genes (gene_id, gene_name, chrom, start, end, strand, tss)
+            VALUES (?, ?, ?, ?, ?, ?, ?)
+        """,
+            (gene_id, gene_name, chrom, start, end, strand, tss),
+        )
+
+        conn.commit()
+        return cursor.lastrowid
+
+    def add_test_feature(
+        self,
+        gene_id: int,
+        annotation_type: str,
+        feature_start: int,
+        feature_end: int,
+        transcript_id: Optional[str] = None,
+    ) -> int:
+        """
+        Add a test genomic feature to the database.
+
+        Args:
+            gene_id: Database ID of the gene
+            annotation_type: Type (exon, intron, UTR5, UTR3, promoter)
+            feature_start: Feature start position
+            feature_end: Feature end position
+            transcript_id: Optional transcript ID
+
+        Returns:
+            Database ID of inserted feature
+        """
+        conn = self.get_connection()
+        cursor = conn.cursor()
+
+        cursor.execute(
+            """
+            INSERT INTO genomic_features
+            (gene_id, annotation_type, feature_start, feature_end, transcript_id)
+            VALUES (?, ?, ?, ?, ?)
+        """,
+            (gene_id, annotation_type, feature_start, feature_end, transcript_id),
+        )
+
+        conn.commit()
+        return cursor.lastrowid
+
+    def add_test_mutation(self, chrom: int, pos: int, ref: str, alt: str) -> int:
+        """
+        Add a test mutation to the database.
+
+        Args:
+            chrom: Chromosome (1-24)
+            pos: Genomic position
+            ref: Reference allele
+            alt: Alternate allele
+
+        Returns:
+            Database ID of inserted mutation
+        """
+        conn = self.get_connection()
+        cursor = conn.cursor()
+
+        cursor.execute(
+            """
+            INSERT INTO mutations (chrom, pos, ref, alt)
+            VALUES (?, ?, ?, ?)
+        """,
+            (chrom, pos, ref, alt),
+        )
+
+        conn.commit()
+        return cursor.lastrowid
+
+
+class DatabaseFixtureWithData(DatabaseFixture):
+    """DatabaseFixture that pre-populates with sample data"""
+
+    def __enter__(self):
+        """Create temporary database, initialize schema, and add sample data"""
+        super().__enter__()
+
+        # Add sample TP53 gene
+        tp53_id = self.add_test_gene(
+            gene_id="ENSG00000141510",
+            gene_name="TP53",
+            chrom=17,
+            start=7661779,
+            end=7687550,
+            strand="-",
+            tss=7687550,
+        )
+
+        # Add sample exon with canonical transcript
+        self.add_test_feature(
+            gene_id=tp53_id,
+            annotation_type="exon",
+            feature_start=7577100,
+            feature_end=7577600,
+            transcript_id="ENST00000269305",
+        )
+
+        # Add sample KRAS gene
+        kras_id = self.add_test_gene(
+            gene_id="ENSG00000133703",
+            gene_name="KRAS",
+            chrom=12,
+            start=25205246,
+            end=25250936,
+            strand="-",
+            tss=25250936,
+        )
+
+        # Add sample exon
+        self.add_test_feature(
+            gene_id=kras_id,
+            annotation_type="exon",
+            feature_start=25227000,
+            feature_end=25227500,
+            transcript_id="ENST00000311936",
+        )
+
+        return self
+
+
+def create_test_db(with_sample_data: bool = False) -> DatabaseFixture:
+    """
+    Factory function to create a test database.
+
+    Args:
+        with_sample_data: If True, populate with sample genes and features
+
+    Returns:
+        DatabaseFixture context manager
+
+    Usage:
+        with create_test_db(with_sample_data=True) as db:
+            DbConnection.set_db_path(db.path)
+            # Run tests...
+    """
+    if with_sample_data:
+        return DatabaseFixtureWithData()
+    else:
+        return DatabaseFixture()

evoseer_utils-0.1.4/pyproject.toml

@@ -0,0 +1,52 @@
+[tool.poetry]
+name = "evoseer-utils"
+version = "0.1.4"
+description = "Shared library for mutation management across modules"
+authors = ["benoît de Witte"]
+readme = "README.md"
+packages = [{include = "evoseer_utils"}]
+
+[tool.poetry.dependencies]
+python = "^3.9"
+pydantic = "^2.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0"
+ruff = "^0.8"
+pre-commit = "^4.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = [
+    "-v",
+    "--strict-markers",
+    "--tb=short",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py39"
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "N",   # pep8-naming
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+]
+ignore = []
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]  # Allow unused imports in __init__.py
+"tests/*" = ["D"]         # Disable docstring requirements in tests