altametris.sara.core.cache_manager
==================================

.. py:module:: altametris.sara.core.cache_manager

.. autoapi-nested-parse::

   Gestionnaire de cache local pour les poids téléchargés depuis Azure.

   Ce module fournit un système de cache intelligent pour stocker localement les poids
   de modèles téléchargés depuis Azure Blob Storage, avec support de TTL
   et nettoyage automatique.

   .. rubric:: Example

   >>> from altametris.sara.core import CacheManager
   >>> cache = CacheManager(cache_dir="/tmp/model_cache", ttl_seconds=86400)
   >>> # Vérifier si un weight est en cache
   >>> if cache.is_cached("models/yolo11x.pt"):
   ...     path = cache.get_cached_path("models/yolo11x.pt")
   ...     print(f"Model cached at: {path}")
   >>> # Mettre à jour les métadonnées après téléchargement
   >>> cache.update_cache_metadata(
   ...     "models/yolo11x.pt",
   ...     source="azure://models/yolo11x.pt",
   ...     size_bytes=104857600
   ... )



Attributes
----------

.. autoapisummary::

   altametris.sara.core.cache_manager.logger


Classes
-------

.. autoapisummary::

   altametris.sara.core.cache_manager.CacheManager


Module Contents
---------------

.. py:data:: logger

.. py:class:: CacheManager(cache_dir: Optional[str] = None, ttl_seconds: Optional[int] = None)

   Gestionnaire de cache local pour les poids de modèles téléchargés.

   Le cache utilise une structure de répertoires miroir du blob storage::

       cache_dir/
           models/
               yolo11x.pt
               yolo11x.pt.meta (métadonnées JSON)

   :param cache_dir: Répertoire racine du cache (défaut: ~/.cache/altametris/weights).
                     Stocké comme attribut après initialisation.
   :param ttl_seconds: Durée de vie des fichiers en secondes (défaut: 7 jours).
                       Après ce délai, les fichiers sont considérés comme expirés.
                       Valeur None = pas d'expiration. Stocké comme attribut après initialisation.

   .. note::

      Les attributs principaux sont ``cache_dir`` (Path), ``ttl_seconds`` (int | None),
      et ``_meta_suffix`` (str, toujours ".meta").

   .. rubric:: Example

   >>> cache = CacheManager(cache_dir="/tmp/cache", ttl_seconds=3600)
   >>> cache.is_cached("models/yolo11x.pt")
   False
   >>> cache.update_cache_metadata("models/yolo11x.pt", source="azure://models/yolo11x.pt", size_bytes=1024)
   >>> cache.is_cached("models/yolo11x.pt")
   True
   >>> stats = cache.get_cache_stats()
   >>> print(f"Cache contains {stats['total_files']} files, {stats['total_size_mb']:.2f} MB")


   .. py:attribute:: cache_dir


   .. py:attribute:: ttl_seconds
      :value: None



   .. py:method:: is_cached(cache_key: str) -> bool

      Vérifie si un élément est en cache et non expiré.

      Un élément est considéré comme valide si:
      1. Le fichier existe dans le cache
      2. Le fichier de métadonnées existe et est valide (JSON parsable)
      3. Le TTL n'est pas dépassé (si ttl_seconds est défini)

      :param cache_key: Clé de cache à vérifier (ex: "models/yolo11x.pt")

      :returns: True si l'élément est en cache et valide, False sinon

      .. rubric:: Example

      >>> cache = CacheManager(ttl_seconds=3600)
      >>> cache.is_cached("models/yolo11x.pt")
      False
      >>> # Après téléchargement et update_cache_metadata...
      >>> cache.is_cached("models/yolo11x.pt")
      True



   .. py:method:: get_cached_path(cache_key: str) -> pathlib.Path

      Retourne le chemin local d'un élément en cache.

      :param cache_key: Clé de cache (ex: "models/yolo11x.pt")

      :returns: Chemin absolu du fichier dans le cache

      .. rubric:: Example

      >>> cache = CacheManager()
      >>> if cache.is_cached("models/yolo11x.pt"):
      ...     path = cache.get_cached_path("models/yolo11x.pt")
      ...     print(f"Load model from: {path}")



   .. py:method:: update_cache_metadata(cache_key: str, source: Optional[str] = None, size_bytes: Optional[int] = None, **extra_metadata: Any) -> None

      Enregistre ou met à jour les métadonnées d'un fichier en cache.

      Cette méthode doit être appelée après avoir téléchargé un fichier
      dans le cache pour enregistrer ses métadonnées (timestamp, source, taille)!!!.

      Les métadonnées sont stockées dans un fichier JSON avec le suffixe .meta

      :param cache_key: Clé de cache (ex: "models/yolo11x.pt")
      :param source: URL ou chemin source (ex: "azure://models/yolo11x.pt")
      :param size_bytes: Taille du fichier en octets
      :param \*\*extra_metadata: Métadonnées additionnelles à stocker

      :raises ConfigurationError: Si le fichier cache n'existe pas ou si l'écriture échoue

      .. rubric:: Example

      >>> cache = CacheManager()
      >>> # Après avoir téléchargé le fichier dans cache.get_cached_path(...)
      >>> cache.update_cache_metadata(
      ...     "models/yolo11x.pt",
      ...     source="azure://models/yolo11x.pt",
      ...     size_bytes=104857600,
      ...     version="v1.0"
      ... )



   .. py:method:: cleanup_expired() -> int

      Supprime tous les fichiers expirés du cache.

      Parcourt récursivement le cache et supprime:
      1. Les fichiers dont le TTL est dépassé
      2. Les fichiers de métadonnées associés
      3. Les répertoires vides résultants

      :returns: Nombre de fichiers supprimés (paires fichier + métadonnées comptent comme 1)

      .. rubric:: Example

      >>> cache = CacheManager(ttl_seconds=3600)
      >>> # Après 2 heures...
      >>> removed = cache.cleanup_expired()
      >>> print(f"Removed {removed} expired files")



   .. py:method:: clear_cache(pattern: Optional[str] = None) -> int

      Vide le cache complètement ou selon un pattern.

      :param pattern: Pattern optionnel (glob style, ex: ``"models/*.pt"``, ``"yolo11*"``).
                      Si None, supprime tout le cache.

      :returns: Nombre de fichiers supprimés (paires fichier + métadonnées comptent comme 1)

      .. rubric:: Example

      >>> cache = CacheManager()
      >>> # Supprimer tous les modèles yolo11
      >>> removed = cache.clear_cache(pattern="models/yolo11*.pt")
      >>> print(f"Removed {removed} files")
      >>> # Vider complètement le cache
      >>> removed = cache.clear_cache()
      >>> print(f"Cache cleared: {removed} files removed")



   .. py:method:: get_cache_stats() -> dict[str, Any]

      Retourne des statistiques détaillées sur le cache.

      :returns:

                - total_files: Nombre total de fichiers en cache
                - total_size_bytes: Taille totale en octets
                - total_size_mb: Taille totale en MB
                - expired_files: Nombre de fichiers expirés (si TTL configuré)
                - valid_files: Nombre de fichiers valides (si TTL configuré)
                - cache_dir: Chemin du répertoire de cache
                - ttl_seconds: TTL configuré (ou None)
      :rtype: Dictionnaire contenant

      .. rubric:: Example

      >>> cache = CacheManager()
      >>> stats = cache.get_cache_stats()
      >>> print(f"Cache: {stats['total_files']} files, {stats['total_size_mb']:.2f} MB")
      >>> if stats['expired_files'] > 0:
      ...     print(f"Warning: {stats['expired_files']} expired files")