PythonCodingGuidelines
1.0.0
Les directives de codage Python sont un ensemble de directives, de règles et de bonnes pratiques éprouvées concernant le codage en Python.
L'objectif de ces lignes directrices est d'aider les développeurs à utiliser Python efficacement et de fournir un style Python moderne plus lisible. Un code facilement maintenable et évolutif. Également, pour établir une norme de développement à suivre lors du développement d'applications ou de bibliothèques en Python.
J'espère que ce document pourra également vous aider à démarrer avec Python. Si vous venez d'un autre langage de script tel que JavaScript, vous constaterez que Python est très similaire et ce document est un moyen de transition vers Python.
Les lignes directrices se concentrent sur toutes les ressources fournies par le langage Python habituellement défini dans le standard PEP8. PEP8 PEP8 est ici simplement utilisé comme base pour cette proposition de lignes directrices de codage. Je souhaite promouvoir un style Python plus lisible et moderne.
Vous constaterez peut-être que certaines des règles de cette ligne directrice sont contraires à vos attentes ou même contraires à votre expérience.
Si je ne vous ai pas suggéré de modifier votre style de codage de quelque manière que ce soit, j'ai échoué !
Veuillez essayer de vérifier ou de réfuter les règles de cette directive. En particulier, j'aimerais vraiment que certaines des règles proposées soient étayées par des mesures ou de meilleurs exemples.
Est une règle générale du développement de logiciels visant à créer des applications lisibles, maintenables et évolutives. Ce n’est pas toujours la vérité, mais nous visons cet objectif.
Les normes de code sont des outils qui aident à créer des applications avec les principes de la triade mentionnés ci-dessus. Voici quelques-uns des avantages offerts par l’établissement d’une norme de développement cohérente :
️ Avertissement : Il s'agit d'un document évolutif en constante amélioration. Les commentaires et suggestions d’améliorations sont les bienvenus. Je prévois de modifier et d'étendre ce document à mesure que notre compréhension s'améliore et que le langage dans lequel l'ensemble des bibliothèques disponibles évolue.
| Nom | Convention | Exemple de code |
|---|---|---|
| nom de variable unique | cas_serpent | age: int = 100 |
| nom de la variable composée | cas_serpent | first_name: str = "Akira" |
| nom de constante | CONST | CPU: number = 8 |
| nom de constante composée | CONST | MAX_NUMBER: number = 100 |
| nom d'énumération | PascalCase | class Color(Enum): RED = 1 GREEN = 2 |
| nom de la fonction | cas_serpent | def main() |
| fonction avec paramètres | cas_serpent | def calculate(n1: int, n2: int) |
| fonction avec type de retour | cas_serpent | def calculate(n1: int, n2: int) -> int: |
| nom de la fonction composée | cas_serpent | def add_two_numbers(n1: int, n2: int) -> int: |
| nom de classe | PascalCase | class Base |
| nom de classe composé | PascalCase | class MyClass |
| interfaces | PascalCase | class IUser(ABC) |
| fonderie | défaut | age: int = int(100) |
| liste | chameauCas | myList: list[int] = [1,2,3] |
| tuple | chameauCas | myTuple: tuple[int] = (1,2,3) |
| ensemble | cas_serpent | my_set: set[int] = {1,2,3} |
| dictionnaire | cas_serpent | my_dictionary: dict = {"name": "John", "age": 100} |
| indice de type multiple | cas_serpent | var_a: Union[int, str] |
Nous avons proposé d'utiliser Google Doc Style pour la documentation Python car c'est le plus simple à lire et à comprendre. Le guide de style Google est également très populaire et largement utilisé dans la communauté Python.
def add_binary ( a : int , b : int ) -> int :
"""
Returns the sum of two decimal numbers in binary format.
Parameters:
a (int): First number to add
b (int): Second number to add
Returns:
binary (int): Binary int of the sum of a and b
"""
binary_sum = bin ( a + b )[ 2 :]
return int ( binary_sum )L’indication de type est une solution formelle pour indiquer statiquement le type de valeur.
Exemple:
def addBinary(a: int, b: int)-> int:
...
Dans cette fonction ci-dessus, il est explicite que la fonction attend la valeur int dans les variables a et b et renvoie la valeur int .
Vérifiez ce lien : Documentation officielle de typage Python
Mais python n'est-il pas un langage non typé ? Oui, ce n'est pas le cas. Si vous transmettez une valeur différente de int , cela fonctionne.
Comment vérifier le type de frappe en Python ?
Vous devriez utiliser la bibliothèque mypy .
Mypy est un vérificateur de type statique facultatif pour Python qui vise à combiner les avantages du typage dynamique (ou « canard ») et du typage statique. (Source : Documentation officielle)
pip install mypy
mypy mycode.py
L'idée d'utiliser linter pour python est d'appliquer les directives de codage proposées dans ce document. J'utiliserai Precommit.
pip install pre-commit
Configuration de base :
.pre-commit-config.yml pour enregistrer les configurations de pré-commitDans cet exemple ci-dessous, le script exécutera ces étapes :
Exemple:
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v2.3.0
hooks:
- id: check-yaml
- id: end-of-file-fixer
- id: trailing-whitespace
- id: check-json
- id: detect-private-key
- repo: https://github.com/PyCQA/isort
rev: 5.12.0
hooks:
- id: isort
- repo: https://github.com/psf/black
rev: 22.12.0
hooks:
- id: black
language_version: python3.10
- repo: https://github.com/charliermarsh/ruff-pre-commit
rev: 'v0.0.260'
hooks:
- id: ruff
pyproject.toml pour enregistrer les configurations des coureurs de pré-validationExemple:
[tool.black]
line-length = 80
target-version = ['py310']
include = '.pyi?$'
[tool.isort]
line_length = 79
multi_line_output = 3
include_trailing_comma = true
force_grid_wrap = 0
use_parentheses = true
ensure_newline_before_comments = true
Après ces configurations, chaque fois que vous effectuez une validation, la pré-validation s'exécutera
Documentation officielle de pré-engagement
Le framework proposé pour les tests est pytest. C'est également un framework de test très populaire pour Python.
tests : pytest
pytest --cov . 
Pour plus de commandes pytest, suivez la documentation officielle ici pytest
Voici un exemple de définition de fonction pour un test :
Après avoir créé votre fonction comme illustré dans l'exemple ci-dessous : 
Vous pouvez créer votre test unitaire en suivant ces étapes :
test_ dans le nom de la fonction.
Pour démarrer un nouveau projet, vous pouvez cloner le projet à l'aide de la commande suivante :
git clone https://github.com/rsaz/python-project-templateVoici une structure par défaut de projet proposée.
La structure du projet est basée sur les éléments suivants :
| Dossier/Fichier | Description |
|---|---|
| utilitaires | Scripts PowerShell qui permettent de créer, activer, désactiver et supprimer des environnements, ainsi que de mettre à jour et créer les dépendances |
| .vscode | Configuration spécifique à l'éditeur |
| src | Dossier source principal du projet |
| test | Dossier contenant tous les tests unitaires de l'application |
| venv | Environnement virtuel Python |
| .pylintrc | Fichier de configuration pour l'analyseur de code statique pylint pour Python |
| pytest.ini | Fichier de configuration pour pytest |
| LICENCE.txt | Conditions de licence du projet |
| LISEZMOI.md | Détails du projet |
| exigences.txt | Dépendances du projet |
| setup.cfg et setup.py | Configuration initiale du projet |
