Ressources et Image de Marque

AppriseAsset définit le contexte global d’exécution d’une session Apprise.

Il ne se limite pas à l’image de marque ou au thème. Une instance d’asset influence le comportement de :

• tous les plugins de notification ;
• tous les threads d’envoi ;
• le stockage persistant et le matériel de clé ;
• les limites de sécurité globales (masquage des journaux et protection contre la récursion).

Dans la plupart des cas, un asset est créé une seule fois puis passé à Apprise(...) lors de son instanciation.

from apprise import Apprise, AppriseAsset

asset = AppriseAsset(app_id="Mon application", theme="default")
apobj = Apprise(asset=asset)

Si aucun asset n’est fourni, Apprise en crée un par défaut.

Cycle de Vie et Portée

• créé une seule fois, en général au démarrage de l’application ;
• partagé entre tous les plugins chargés et le traitement de configuration ;
• destiné à être considéré comme immuable pendant toute la durée de vie d’une instance Apprise.

Modifier un asset après l’avoir lié à Apprise peut produire des résultats incohérents d’un plugin à l’autre.

Initialisation de l’Objet

AppriseAsset.__init__() fournit des arguments nommés pour le stockage, les délais d’attente, les limites de messages et d’autres réglages partagés. Utilisez toujours le nom documenté du constructeur, comme timezone=, service_timeout= ou payload_max_size=. Ces arguments valident les valeurs avant de les appliquer.

Les arguments du constructeur Python et les clés YAML asset: sont des interfaces distinctes. Certains réglages sont accessibles aux applications par AppriseAsset(...), mais volontairement indisponibles dans la configuration YAML.

---

Valeurs par Défaut et Référence des Champs

Ce tableau documente les vraies valeurs par défaut issues de l’implémentation, ainsi que l’endroit où chaque champ est utilisé.

Identité et Présentation

Champ	Type	Par défaut	Utilisé par	Notes
app_id	str	Apprise	En-têtes de plugins, noms de clés	Utilisé comme identifiant applicatif lisible et comme nom par défaut pour la génération de clés PGP.
app_desc	str	Apprise Notifications	Métadonnées / présentation	Utilisé par les outils et services qui affichent une description d’application.
app_url	str	https://github.com/caronc/apprise	Métadonnées / présentation	URL du fournisseur exposée dans la documentation et certaines métadonnées de plugins.
theme	str	default	Résolution d’URL/chemin d’icônes	Pilote la substitution {THEME} lors de la recherche d’icônes.
language	str	langue du système	Textes traduits	Définit la langue utilisée par Apprise pour ses propres textes, comme les noms de champs renvoyés par details(). Accepte en, en-CA ou en_CA. Une région revient à sa langue de base, puis à l’anglais, lorsque aucune traduction n’est installée. YAML accepte language ou son alias lang.
default_extension	str	.png	Résolution d’URL/chemin d’icônes	Utilisé lorsque extension n’est pas fourni à image_url() ou image_path().
default_image_size	NotifyImageSize	XY_256	Résolution d’URL d’icônes	Utilisé quand la taille est omise.
image_url_mask	str	URL GitHub raw	image_url()	Produit une URL d’image thémée pour NotifyType + taille.
image_url_logo	str	URL GitHub raw	image_url(logo=True)	Utilisé pour le logo de l’application.
image_path_mask	str	local assets/themes/...	image_path() / image_raw()	Utilisé pour la résolution locale d’icônes et le chargement des octets bruts.

Aides de Correspondance de Type

Champ	Type	Valeur par défaut	Utilisé par	Notes
html_notify_map	dict[NotifyType,str]	mappage type vers hex	color()	Mappage couleur par défaut pour les services HTML.
default_html_color	str	#888888	color()	Utilisé lorsqu’un mappage est absent.
ascii_notify_map	dict[NotifyType,str]	mappage type vers jeton	ascii()	Jetons ASCII par défaut pour les contextes purement texte.
default_ascii_chars	str	[?]	ascii()	Utilisé lorsqu’un mappage est absent.

Interprétation du Contenu

Champ	Type	Défaut	Utilisé par	Notes
body_format	NotifyFormat	None	Pré-traitement message	Sélectionne le format d’entrée par défaut. Si None, aucun pré-formatage n’est appliqué.
interpret_emojis	bool	None	Pré-traitement message	Contrôle la conversion des emojis. Si None, le réglage de chaque service s’applique (par exemple emojis=yes dans l’URL).
interpret_escapes	bool	False	Pré-traitement message	Active \n, \t, etc. avant l’envoi.
encoding	str	utf-8	Encodage	Utilisé lors du traitement des chaînes et par certains services pendant l’envoi. Conservez la valeur par défaut sauf besoin particulier.

Concurrence et Envoi

Champ	Type	Défaut	Utilisé par	Notes
async_mode	bool	True	Orchestration des envois	Contrôle l’envoi concurrent ou séquentiel.
default_service_retry	int	0	Tentatives par service	Nombre de tentatives par défaut pour tout service sans ?retry= dans son URL. Limité à [0, 10].
default_service_wait	float	0.5	Tentatives par service	Délai inter-tentative par défaut (secondes) pour les services sans ?wait=. Limité à [0.0, 20.0].
service_timeout	int / float	60.0	Délai par service	Nombre maximal de secondes qu’un service (toutes tentatives comprises) peut prendre avant qu’Apprise n’abandonne et ne signale un TIMEOUT. 0 désactive la limite. Voir Résultats de notification.
result_log_memory_size	int	0	Journaux du résultat	Octets conservés en mémoire avant de transférer les journaux vers un fichier temporaire. Utilisé seulement si result_log_disk_size est supérieur à 0.
result_log_disk_size	int	0	Journaux du résultat	Espace disque temporaire maximal pour le résultat d’une notification. 0 conserve tous les journaux en mémoire.

Découverte de Plugins

Champ	Type	Défaut	Utilisé par	Notes
plugin_paths	list[str]	[]	Chargement personnalisé	Déclenche la détection de modules à l’initialisation.

Stockage Persistant

Champ	Type	Défaut	Utilisé par	Notes
storage_path	str	None	None	Racine de PersistentStore. Si absent, Apprise fonctionne uniquement en mémoire pour ces fonctions.
storage_mode	PersistentStoreMode	auto	Comportement PersistentStore	auto, flush, memory.
storage_idlen	int	8	Génération d’espaces nommés	Contrôle la longueur des répertoires de namespace générés.
storage_salt	bytes	b""	Génération d’espaces nommés	Fournit un salage facultatif ; les chaînes sont encodées avec encoding.

Gestion du Matériel de Clé

Champ	Type	Défaut	Utilisé par	Notes
pgp_autogen	bool	True	Contrôleur PGP	Quand True, un auto-envoi avec pgp=encrypt peut générer la paire de clés RSA-2048 de l’expéditeur dans le stockage persistant. Les clés des destinataires et de pgp=sign ne sont jamais générées.
pem_autogen	bool	True	Contrôleur PEM	Active la génération automatique de clés PEM si le stockage le permet et qu’aucune clé n’est fournie.

Détails de la Génération Automatique PGP

Quand pgp_autogen = True, un auto-envoi avec pgp=encrypt peut générer les deux fichiers de clés de l’expéditeur si aucune clé n’est trouvée :

• {localpart}-pub.asc : clé publique RSA-2048 utilisée pour l’auto-envoi
• {localpart}-prv.asc : clé privée RSA-2048 utilisée pour les réponses et les signatures ultérieures

{localpart} est dérivé de l’adresse From de l’expéditeur (tout ce qui précède le @, en minuscules).

La clé privée peut ensuite être découverte par pgp=sign dans le même stockage. Importez-la dans le client qui lit les réponses chiffrées. Les destinataires externes nécessitent toujours une clé existante ; Apprise n’en génère jamais pour eux.

Pour désactiver la génération automatique globalement :

from apprise import AppriseAsset

asset = AppriseAsset(
    storage_path="/var/lib/apprise",
    pgp_autogen=False,
)

Avec pgp_autogen = False, aucune paire de clés n’est créée automatiquement. Une clé doit provenir du stockage local, de WKD ou d’un chemin pgppub= explicite.

Limites de Sécurité

Champ	Type	Défaut	Utilisé par	Notes
http_redirects	bool	True	Tous les plugins HTTP	Quand True (par défaut), les plugins suivent les redirections 3xx, conformément au comportement de la bibliothèque requests. Définir à False pour désactiver le suivi des redirections globalement sans toucher aux URLs individuelles.
secure_logging	bool	True	Pipeline de journalisation	Ajoute un coût pour masquer les secrets dans les logs ; recommandé de le laisser activé.
allow_templates	bool	True	Configuration YAML	Autorise une configuration YAML à déclarer une section template: et à remplir les marqueurs ${NOM}. Définir à False : la section est ignorée, ${NOM} reste du texte ordinaire et rien n’est lu dans l’environnement. Voir Variables de substitution.
payload_max_size	int	0	Formatage/découpage des messages	Limite facultative sur la taille combinée du titre et du corps avant formatage. 0 la désactive. S’applique à tous les modes overflow=.
payload_buffer_threshold	int	10	Formatage/découpage des messages	Un titre ou un corps de cette longueur ou moins peut rester entier ; voir Plafond de taille des messages.
payload_min_buffer	int	25	Formatage/découpage des messages	Caractères réservés à l’autre côté avant de conserver le côté court en entier ; voir Plafond de taille des messages.
timezone	str / tzinfo	fuseau système	Comportement temporel	Définit le fuseau horaire utilisé par les plugins qui génèrent des horodatages. Accepte un nom IANA comme "America/Toronto" ou un objet tzinfo. YAML accepte timezone ou son alias tz.

Schémas d’Utilisation Courants

Identité et image

Configure l’instance Apprise avec une image de marque personnalisée.

from apprise import AppriseAsset

asset = AppriseAsset(
    app_id="StatsBot",
    app_desc="Service d'agrégation de métriques",
    app_url="https://example.com",
)

Concurrence

Désactive l’envoi concurrent et force un envoi séquentiel des notifications.

from apprise import AppriseAsset

# Forcer l'envoi séquentiel (pas de concurrence)
asset = AppriseAsset(async_mode=False)

Délai par Service

Donne à chaque service de la session le même budget de temps, au lieu des 60 secondes par défaut. Voir Résultats de notification pour savoir comment un service qui dépasse son délai vous est signalé en retour.

from apprise import Apprise, AppriseAsset

# Donne 10 secondes à chaque service (toutes tentatives comprises)
# avant qu'Apprise n'abandonne et ne signale un TIMEOUT
asset = AppriseAsset(service_timeout=10)

apobj = Apprise(asset=asset)
apobj.add("slack://tokenA/tokenB/tokenC")

# Cet appel a également son propre plafond de 30 secondes, en plus du
# budget de 10 secondes par service de l'asset -- le délai le plus
# court l'emporte
apobj.notify(body="Alerte urgente", timeout=30)

Stockage des journaux du résultat

Conservez une petite partie des journaux en mémoire et placez les entrées suivantes dans un fichier temporaire supprimé automatiquement :

from apprise import Apprise, AppriseAsset

asset = AppriseAsset(
    result_log_memory_size=2 * 1024 * 1024,
    result_log_disk_size=256 * 1024 * 1024,
)
apobj = Apprise(asset=asset)

Ces limites sont partagées par tous les services et toutes les tentatives d’une notification. Si l’espace disque est épuisé ou indisponible, l’envoi continue et le résultat contient un avertissement indiquant que les journaux suivants n’ont pas pu être conservés.

Plugins personnalisés

Lorsque plugin_paths est défini, la détection des modules a lieu pendant l’initialisation de l’asset.

from apprise import AppriseAsset

asset = AppriseAsset(
    plugin_paths=[
        "/opt/apprise/plugins",
        "/srv/myapp/apprise_plugins",
    ]
)

Stockage persistant

Contrôle le cache sur disque et l’état persistant des plugins.

from apprise import AppriseAsset
from apprise.common import PersistentStoreMode

asset = AppriseAsset(
    storage_path="/var/lib/apprise",
    storage_mode=PersistentStoreMode.AUTO,
    storage_idlen=12,
    storage_salt="my-namespace-salt",
)

storage_salt peut être de type bytes ou str. Les chaînes sont encodées avec l’encoding de l’asset.

Contrôle du fuseau horaire

Les plugins qui génèrent des horodatages (par exemple les en-têtes Date des emails) utilisent le fuseau horaire configuré.

from apprise import AppriseAsset

asset = AppriseAsset(timezone="America/Toronto")

Contrôle de la langue

Apprise traduit ses propres textes lisibles, comme les noms de champs renvoyés par details(). Si language n’est pas défini, la langue du système sur lequel Apprise s’exécute est utilisée.

from apprise import AppriseAsset

# Les codes à deux lettres et les tags régionaux sont acceptés, sans tenir compte de la casse
asset = AppriseAsset(language="fr")
asset = AppriseAsset(language="en-CA")

Un tag régional recherche d’abord cette traduction exacte (en_CA), puis sa langue de base (en), et revient enfin à l’anglais. Apprise fournit des traductions pour ar, de, en, es, fr, hi, id, it, ja, ko, ms, nl, pl, pt, ru, th, tl, tr, vi et zh.

Seuls les textes lus par une personne sont traduits. Tout ce qui est lu par un programme, comme un code de statut ou une clé dans une réponse, reste en anglais.

Résolution d’Icônes et d’Images

Apprise résout les icônes à l’aide de masques configurables.

asset = AppriseAsset(
    image_path_mask="/icons/{THEME}/{TYPE}-{XY}{EXTENSION}",
    image_url_mask="https://cdn.example.com/{TYPE}-{XY}{EXTENSION}",
)

Jeton	Description
{THEME}	Thème actif
{TYPE}	info, success, warning, failure
{XY}	Taille de l’image
{EXTENSION}	Extension de fichier

---

Contrôles de Sécurité

Redirections HTTP

Par défaut, Apprise suit les redirections HTTP 3xx, conformément au comportement de la bibliothèque requests sous-jacente. Si vous souhaitez empêcher la transmission des en-têtes personnalisés et des identifiants vers des destinations différentes de l’URL d’origine, vous pouvez désactiver globalement le suivi des redirections :

asset = AppriseAsset(http_redirects=False)

Les URLs individuelles peuvent toujours remplacer la valeur par défaut de l’asset via le paramètre d’URL redirect= :

# Remplacement par URL, indépendamment du réglage de l'asset
schema://token/?redirect=yes
schema://token/?redirect=no

Journalisation Sécurisée

Lorsqu’elle est activée, les secrets sont masqués dans toutes les sorties de journal.

asset = AppriseAsset(secure_logging=True)

La désactiver est fortement déconseillé en dehors d’environnements isolés.

Plafond de Taille des Messages

payload_max_size définit la limite du message, c’est-à-dire le budget total de caractères (N) pour le titre et le corps avant le formatage ou le découpage. La valeur 0 désactive cette limite. Si le titre et le corps tiennent déjà dans N, Apprise les laisse inchangés.

asset = AppriseAsset(payload_max_size=100000)

Trois réglages fonctionnent ensemble lorsque le contenu dépasse N :

Réglage	Défaut	Rôle
payload_max_size	0	Définit N, le budget total. 0 désactive la limite.
payload_buffer_threshold	10	Un titre ou un corps aussi court peut être conservé en entier.
payload_min_buffer	25	Espace que l’autre côté doit conserver avant de garder le côté court en entier.

Avec les valeurs par défaut, un message trop volumineux est résolu dans cet ordre :

1. Un côté est vide : l’autre reçoit tout le budget.
2. Un côté est court : un titre de 10 caractères ou moins reste entier si le corps peut conserver 25 caractères, ou toute sa longueur s’il est plus court. La même règle vérifie ensuite si le corps est court. Si les deux sont admissibles, le titre est vérifié en premier.
3. Sinon : le titre et le corps se partagent N selon leurs longueurs d’origine. Lorsque N permet de représenter les deux, chacun conserve au moins un caractère.

Par exemple, un titre de 20 caractères et un corps de 18 caractères avec N=20 se répartissent environ 10/10. Une limite plus petite peut encore produire un fragment court, mais elle ne favorise pas un côté lorsque les deux peuvent être représentés.

Les utilisateurs de la bibliothèque peuvent modifier les deux réglages lors de la création de l’asset :

asset = AppriseAsset(
    payload_max_size=100000,
    payload_buffer_threshold=10,
    payload_min_buffer=25,
)

Avec payload_min_buffer=0, aucune place n’est réservée : un côté court admissible peut donc utiliser toute la limite.

Le formatage et l’échappement peuvent ensuite ajouter quelques caractères. La limite s’applique à tous les modes overflow=, y compris upstream.

Limites des Fichiers de Configuration

YAML prend volontairement en charge moins de réglages d’asset que le constructeur Python. Les contrôles numériques comme service_timeout, payload_max_size, payload_buffer_threshold et payload_min_buffer doivent être fournis par leurs arguments nommés dans AppriseAsset(...). Les chemins de plugins et les réglages de stockage sont également contrôlés par l’application afin qu’un fichier de configuration ne puisse ni charger du code ni rediriger le stockage persistant.

timezone est pris en charge dans YAML et peut aussi utiliser l’alias tz :

asset:
  timezone: America/Toronto # ou : tz: America/Toronto

language est pris en charge dans YAML et peut aussi utiliser l’alias lang :

asset:
  language: fr # ou : lang: fr

Voir Aussi

• Routage par Tags & Tentatives — comment configurer les tags de priorité, les tentatives/attente par service, les délais maximum par service et les remplacements par appel dans les fichiers de configuration.
• Résultats de notification — comment un service en échec ou dont le délai a expiré vous est signalé depuis notify().