Metadata-Version: 2.1
Name: zpp-logs
Version: 1.0.0
Summary: Module de gestion de logs
Home-page: https://github.com/ZephyrOff/py-zpp_logs
Author: ZephyrOff <contact@apajak.fr>
License: MIT License
Project-URL: Documentation, https://github.com/ZephyrOff/py-zpp_logs
Keywords: logs module zephyroff
Platform: ALL
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Description-Content-Type: text/markdown
License-File: LICENSE

# zpp-logs
## Informations
Module pour la gestion des logs (Ã  l'image de logging) avec des tuning personnalisÃ©s par niveau de logs
<br>

## PrÃ©requis
- Python 3
<br>

## Installation
```console
pip install zpp-logs
```
<br>

## Utilisation
### <ins>Logger</ins>

Un logger est un objet qui permet de dÃ©finir des options (handler, formatter, filter) pour un log.

```python
from zpp_logs import Logger

log = Logger()
```
<br>
Il est possible de lui donner en paramÃ¨tre un fichier de configuration au format yaml pour configurer directement les diffÃ©rentes options

```python
from zpp_logs import Logger

log = Logger(configfile='config.yaml')
```

_Exemple de fichier yaml:_
```config
formatters:
    standard:
        format: "%(fore:deep_sky_blue_3a)%[%(date:%d/%m/%Y %H:%M:%S)%]%(attr:0)% - %(fore:medium_purple_4)%%(levelname)%%(attr:0)% - %(fore:grey_46)%%(msg)%%(attr:0)%"
    test:
        format: "%(epoch)% - %(msg)%"

filters:
    testfunc: test3.test

handlers:
    console:
        class: zpp_logs.Console_handler
        level: zpp_logs.CRITICAL
        ops: "<"
        formatter: test
        output: sys.stdout


logger:
    handlers: [console]
    filters: [testfunc]
```

<br>

Dans un Logger, nous pouvons ajouter/supprimer des handler et des filtres, afficher le compteur de log et appeler les mÃ©thodes de log.
Toutes ces options sont dÃ©taillÃ©es dans la suite.

<br>

### <ins>Handler</ins>

DiffÃ©rents handler sont disponibles pour permettre d'envoyer les logs dans la console, dans un fichier ou par mail.
Tous les handler disposent des mÃ©thodes:
- __setFormatter()__ pour ajouter un formatter
```python
cons.setFormatter(form)
```
la mÃ©thode attend un objet Formatter

<br>

- __setLevel()__ pour dÃ©finir le niveau de log Ã  appliquer
```python
cons.setLevel(zpp_logs.DEBUG)
```
la mÃ©thode attend un niveau de logs.
Il est possible de lui envoyer un argument ops pour dÃ©finir le comportement du handler. (Par dÃ©faut ==)
```python
cons.setLevel(zpp_logs.ERROR, ops="<=")
```
le ops permet de comparaison pour trigger le handler. Dans l'exemple du dessus, le handler se dÃ©clenche si le log est de niveau ERROR ou infÃ©rieur.

<br>

- __addFilter()__ pour ajouter un filtre.
Le filter est soit un script (qui peut Ãªtre une regex), soit une fonction (dans ce cas, le filter attends un retour True pour se dÃ©clencer)
```python
def test(message):
    if "bjr" in message:
        return True
    return False

cons.addFilter(MonModule.test)
```

<br>

- __removeFilter()__ pour supprimer un filtre.
Cette mÃ©thode permet de supprimer un filtre configurÃ©

<br>

### Console_handler

Un Console_handler permet d'envoyer des messages dans la console.
Par dÃ©faut, le handler n'attend pas de paramÃ¨tre mais peut recevoir:
- output: pour dÃ©finir la destination (Par dÃ©faut sys.stdout)
- level: pour dÃ©finir le niveau de logs attendu (Par dÃ©faut NOTSET)
- ops: pour dÃ©finir le comportement du handler. (Par dÃ©faut ==) (Voir setLevel)

```python
log = Logger()
cons = Console_handler()
log.add_handler(cons)
```

<br>

### File_handler

Un File_handler permet d'envoyer des messages dans un fichier.
Par dÃ©faut, le handler attend le chemin du fichier de destination. (Peut recevoir un nom de fichier dynamique avec la syntaxe des formatter) <br>
Il peut aussi recevoir:
- rewrite: pour dÃ©finir si le handler rÃ©Ã©crit sur un fichier existant (Par dÃ©faut False)
- level: pour dÃ©finir le niveau de logs attendu (Par dÃ©faut NOTSET)
- ops: pour dÃ©finir le comportement du handler. (Par dÃ©faut ==) (Voir setLevel)

```python
log = Logger()
cons = File_handler('content.log')
log.add_handler(cons)
```

<br>

### RotateFile_handler

Un RotateFile_handler permet d'envoyer des messages dans un fichier en prenant en charge une rotation de logs en fonction d'une taille max.
Par dÃ©faut, le handler attend le chemin du fichier de destination. (Peut recevoir un nom de fichier dynamique avec la syntaxe des formatter) <br>
Il peut aussi recevoir:
- rewrite: pour dÃ©finir si le handler rÃ©Ã©crit sur un fichier existant (Par dÃ©faut False)
- level: pour dÃ©finir le niveau de logs attendu (Par dÃ©faut NOTSET)
- ops: pour dÃ©finir le comportement du handler. (Par dÃ©faut ==) (Voir setLevel)
- maxBytes: pour dÃ©finir la taille max du fichier de log
- backupCount: pour dÃ©finir le nombre maximum de fichier de log. Si la limite est atteinte, il supprime le fichier le plus ancien.

```python
log = Logger()
cons = RotateFile_handler('content.log')
log.add_handler(cons)
```

<br>

### SMTP_handler

Un SMTP_handler permet d'envoyer des messages par mail.
Par dÃ©faut, le handler attend les paramÃ¨tres:
- smtphost: l'ip ou l'adresse du serveur SMTP sous forme de str. PossibilitÃ© de lui envoyer un tuple pour dÃ©finir le port Ã  utiliser (HOST, PORT)
- fromaddr: l'adresse mail de l'expÃ©diteur sous forme de str
- toaddrs: la/les adresses mail des destinataires sous forme de str pour un destination ou une liste pour plusieurs 
- subject: l'objet du mail (Peut recevoir un objet dynamique avec la syntaxe des formatter)
<br>

Il peut aussi recevoir:
- credentials: pour dÃ©finir les login de connexion sous forme de liste ou tuple (USERNAME, PASSWORD)
- secure: pour dÃ©finir si la connexion doit Ãªtre sÃ©curisÃ©e (Par dÃ©faut None)
- timeout: pour dÃ©finir le temps timeout pour la rÃ©ponse du serveur SMTP (Par dÃ©faut 5.0)
- level: pour dÃ©finir le niveau de logs attendu (Par dÃ©faut NOTSET)
- ops: pour dÃ©finir le comportement du handler. (Par dÃ©faut ==) (Voir setLevel)

```python
log = Logger()
cons = SMTP_handler(smtphost='smtp.local.com', fromaddr='private@local.com', toaddrs=['user1@gmail.com', 'user2@gmail.com'], subject="Test de notification")
log.add_handler(cons)
```

<br>

### <ins>Formatter</ins>

Un formatter est un objet qui permet de dÃ©finir le format du message de log envoyÃ©
Dans un formatter, les trigger doivent Ãªtre de la forme _%(trigger_name)%_
Si on veut formater un peu de texte pour aligner les logs, on peut dÃ©finir un padding en ajoutant la taille avec le 2Ã¨me %
Par exemple, _%(trigger_name)5%_

Voici la liste des trigger disponibles

| Name | Description |
|----------|-------------|
| asctime | Date au format %d/%m/%Y %H:%M:%S:%f |
| date: strftime_format | Date dans le format qu'on veut |
| epoch | Date au format epoch |
| exc_info			 | RÃ©cupÃ©ration du traceback |
| levelname | Nom du niveau de log |
| levelno			 | ID du niveau de log |
| msg | Message de log |
| filename | Nom du fichier d'exÃ©cution |
| filepath | RÃ©pertoire parent du fichier d'exÃ©cution |
| lineno | NumÃ©ro de la ligne du fichier d'exÃ©cution |
| functname | Nom de la fonction |
| path | Chemin actuel |
| process | Nom du process |
| processid | PID du process |
| username | Nom d'utilisateur qui exÃ©cute le script |
| uid | uid de l'utilisateur qui exÃ©cute le script (only linux) |
| os_name | Nom de l'OS |
| os_version | Version de l'OS |
| os_archi | Architecture de l'OS |
| mem_total | CapacitÃ© max de RAM |
| mem_available | CapacitÃ© disponible de RAM |
| mem_used | CapacitÃ© utilisÃ©e de RAM |
| mem_free | CapacitÃ© disponible de RAM |
| mem_percent | CapacitÃ© utilisÃ©e de RAM en pourcentage |
| swap_total | CapacitÃ© max de Swap |
| swap_used | CapacitÃ© utilisÃ©e de Swap |
| swap_free | CapacitÃ© disponible de Swap |
| swap_percent | CapacitÃ© utilisÃ©e de Swap en pourcentage |
| cpu_count | Nombre de core physique |
| cpu_logical_count | Nombre de core logique |
| cpu_percent | Pourcentage de CPU utilisÃ© |
| current_disk_device | Nom du disque oÃ¹ se trouve le script |
| current_disk_mountpoint | Point de montage du disque oÃ¹ se trouve le script |
| current_disk_fstype | Format du disque oÃ¹ se trouve le script |
| current_disk_total | CapacitÃ© max du disque oÃ¹ se trouve le script |
| current_disk_used | CapacitÃ© utilisÃ©e du disque oÃ¹ se trouve le script |
| current_disk_free | CapacitÃ© disponible du disque oÃ¹ se trouve le script |
| current_disk_percent | CapacitÃ© utilisÃ©e en pourcentage du disque oÃ¹ se trouve le script |
| fore: color | Couleur de la police d'Ã©criture |
| back: color | Couleur du fond de la police d'Ã©criture |
| attr: attribute | Style de la police d'Ã©criture |

<br>
Pour son utilisation, il suffit de crÃ©er un objet Formatter et de l'ajouter dans un handler.

```python
from zpp_logs import Logger, Formatter, Console_handler

log = Logger()
form = Formatter("%(fore:deep_sky_blue_3a)%[%(date:%d/%m/%Y %H:%M:%S)%]%(attr:0)% - %(fore:medium_purple_4)%%(levelname)%%(attr:0)% - %(fore:grey_46)%%(msg)%%(attr:0)%")
cons = Console_handler()
cons.setFormatter(form)
```

<br>

### <ins>Envoi des logs</ins>

Les mÃ©thodes pour envoyer des logs se dÃ©clinent en 7 niveaux: 
- log(message): zpp_logs.NOTSET
- good(message): zpp_logs.GOOD
- debug(message): zpp_logs.DEBUG
- info(message): zpp_logs.INFO
- warning(message): zpp_logs.WARNING
- error(message): zpp_logs.ERROR
- critical(message): zpp_logs.CRITICAL

<br>

Ces mÃ©thodes peuvent Ãªtre appelÃ©es soit en direct, soit depuis un logger.
```python
from zpp_logs import Logger

logger = Logger(configfile="config.yaml")
logger.warning("Test de logs")
```
<br> 

### <ins>Compteur des logs</ins>

Il est possible de rÃ©cupÃ©rer un dictionnaire contenant le compteur des logs envoyÃ©s par un logger.
```python
>>> logger.count()
{'CRITICAL': 0, 'ERROR': 0, 'WARNING': 1, 'INFO': 0, 'GOOD': 0, 'DEBUG': 0, 'NOTSET': 0}
```
