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__() accepte un petit nombre d’arguments explicites, ainsi que **kwargs.

• Les arguments explicites (plugin_paths, storage_*, timezone) sont validés et normalisés.
• **kwargs peut surcharger n’importe quel attribut d’asset existant et lèvera une erreur si une clé invalide est fournie.

Ce comportement est intentionnel. Il empêche qu’un fichier de configuration définisse silencieusement des champs inconnus et maintient une surface de configuration stricte.

---

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é. Les champs préfixés par _ ou __ ne sont volontairement pas configurables via un fichier de configuration.

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.
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→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→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	None	Pipeline de formatage. Si None, aucun pré-formatage n’est appliqué par défaut.
interpret_emojis	bool	None	None	Pré-traitement des messages. Si None, cela s’en remet à la configuration par service (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 de l’encodage des chaînes internes. Joue aussi un rôle dans la manière dont certains services envoient leur contenu en amont.

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].

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 et que le stockage persistant est configuré, génère une paire de clés RSA-2048 ({localpart}-pub.asc + {localpart}-prv.asc) la première fois qu’aucune clé n’est trouvée. S’applique uniquement à pgp=encrypt — l’étape opportuniste de pgp=sign ne génère jamais de clé.
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, Apprise génère les deux clés (publique et privée) lors du premier envoi pgp=encrypt où aucune clé n’est trouvée :

• {localpart}-pub.asc — clé publique RSA-2048, utilisée pour chiffrer les messages sortants
• {localpart}-prv.asc — clé privée RSA-2048, découverte automatiquement par le mode pgp=sign

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

L’amorçage est donc automatique : configurez pgp=encrypt une fois avec le stockage persistant, laissez le premier envoi générer les deux clés, puis passez à pgp=sign — la clé privée sera découverte depuis le même répertoire de stockage, sans paramètre pgpprv=.

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. Apprise passe à la méthode de découverte suivante (WKD ou un chemin pgppub= explicite) et échoue l’envoi si aucune clé n’est trouvée.

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é.
_recursion	int	0	Garde-fou de récursion API	Empêche les boucles lorsqu’une instance Apprise API en appelle une autre.
_uid	str	UUID4 aléatoire	Corrélation / identité	Identifiant interne destiné à la corrélation interne.
_tzinfo	tzinfo	fuseau système	Comportement temporel	Objet fuseau horaire résolu utilisé par les plugins ayant besoin d’horodatages localisés.

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)

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 tzinfo résolu.

from apprise import AppriseAsset

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

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.

Protection contre la récursion

L’asset suit en interne la profondeur de récursion afin d’éviter les boucles de notification, en particulier lorsque plusieurs instances Apprise interagissent entre elles.

Limites des fichiers de configuration

Les champs suivants ne peuvent pas être définis via des fichiers de configuration :

• plugin_paths
• storage_*
• les indicateurs internes préfixés par _

Ils doivent être fournis par code afin d’empêcher l’exécution de code non fiable.

Voir aussi

• Routage par Tags & Tentatives — comment configurer les tags de priorité, les tentatives/délai par service et les remplacements par appel dans les fichiers de configuration.