Bonnes pratiques pour créer un Projet Python

Nous allons voir dans ce tutoriels quelles sont les bonnes pratiques pour agencez un projet Python en vue de le partager et de le déployer.

Que ce soit pour un logiciel, une librairie, une interface graphique type web app ou mobile app, si vous souhaitez partager votre travail, il vous faut l’organiser et le documenter correctement.

Vous pouvez appliquer ces pratiques sur le projet Moniteur Série

Créer un environnement virtuel

Lorsque vous souhaitez créer un projet que vous allez partager et maintenir sur le long terme, il est primordiale de l’intégrer dans un environnement virtuel afin d’isoler ses dépendances (librairies utilisées, versions, etc.).

Sous Windows, assurez-vous que la version de python que vous utilisez peut être appelé avec python.exe

• python -m pip install python3-venv –> pour installer
• python -m venv venv –> créer un environnement virtuel
• source venv/bin/activate –> activer l’environnement
• deactivate –> désactiver l’environnement

N.B.: Sous Windows, pour ouvrir la console à l’endroit voulu, vous pouvez créer un fichier start_console.bat dans lequel vous copier la commande

start cmd.exe

Vous pouvez exécuter le fichier avec un double-clic pour ouvrir le terminal

Une fois l’environnement créé, vous pouvez rajouter ou supprimer des paquets

pip install <package_name>
pip install <package_name>==<version>
pip uninstall <package_name>

Et garder une trace des paquets et versions utilisés dans le fichier requirements.txt

pip freeze > requirements.txt

Architecture de dossier d’un projet Python

D’après les recommandations de Kenneth Reitz, voici la structure de dossier à adopter.

• Si votre projet ne comprends qu’un fichier

helloworld/
│
├── .gitignore
├── helloworld.py
├── LICENSE
├── README.md
├── requirements.txt
├── setup.py
└── tests.py

• Pour des projets plus complexes contenant différents modules

sample
│
├── docs
│   ├── conf.py
│   ├── index.rst
├── sample
│   ├── __init__.py
│   ├── core.py
│   ├── helpers.py
├── tests
│   ├── test_basic.py
│   ├── test_advanced.py
├── LICENSE
├── README.md
├── requirements.txt
├── setup.py

N.B.: Pour afficher l’arborescence de votre dossier, vous pouvez utiliser la commande tree /f à la racine du projet

Vous êtes, en pratique, assez libre pour créer l’architecture de dossier. L’important est que ce soit fonctionnel, modulable et organisé.

Voici une description des fichiers essentiels de l’architecture

• sample.py ou sample: contient le code source avec un ou plusieurs module
• README: description du projet, guide d’installation, source et exemple. Évolutions éventuelles
• LICENSE: contient licence et copyrights sous lesquelles vous publiez le code
• requirements.txt: contient toutes les dépendances et version que nécessitent le script
• setup.py : gère la distribution et la construction du projet Python
• docs: contient la documentation du projet
• tests: contient les scripts de test du projet

Une fois cette architecture mise en place, vous pouvez l’utilisez et l’adapter pour tous vos projets Python

En-tête de script Python

Un autre point important pour maintenir son code sur la durée est d’avoir un en-tête de même format pour chaque script avec des informations claires à revoir régulièrement. Les informations doivent permettre de rapidement;

• identifier l’auteur et son contact
• vérifier la licence
• connaitre la fonction du script
• savoir comment configurer et lancer le script

#! /user/bin/env python
# -*- coding: utf-8 -*-
"""
File: myscript.py
Author: John Doe
email: email@email.com
Date: 2023-07-19

Description: A simple Python script to print "Hello, world!"

Usage:
	python myscript.py [arguments]

Dependencies:
	pip install numpy

Modification:
	2023-07-19 : first issue 

Sources:
	https://www.python.org/dev/peps/pep-0008/
"""

N.B.: La partie sur le description des modifications doit être placée dans un fichier spécifique lorsque le projet devient conséquent.

Il est aussi possible de rajouter certaines informations dans des variables accessibles par le code.

__author__ = "Bobby"
__copyright__ = "Copyright 2024, BobbySAS"
__credits__ = ["Bobby"]
__license__ = "GPL"
__version__ = "1.0.1"
__maintainer__ = "Bobby"
__email__ = "email@email.com"
__status__ = "Prototype"

Archiver et versionner votre code

Lorsque vous travailler sur des projets en équipe et avec des enjeux importants, il est crucial de conserver une trace et pouvoir combiner des modifications faites au code afin de pouvoir revenir en arrière en cas de régression. Pour cela les outils comme Github, Gitlab sont très utiles.

Sources

• The Hitchhicker’s Guide To Python
• Python Applications Layout
• Python Project Good Practices