Style de code et conventions - Hydro-Informatics

Make your code consistent through style conventions. For interactive reading and executing code blocks and find b08-pystyle.ipynb, or install Python and JupyterLab locally.

Watch this section as a video

Watch this section as a video on the @Hydro-Morphodynamics channel on YouTube.

Respirez profondément, décollez et regardez ce que vous avez appris si loin d’une nouvelle perspective. Après ce chapitre, il sera utile d’avoir un autre regard sur votre ancien code et de le formater avec robustesse. Les lignes directrices de style présentées ici vont au-delà de l’esthétique visuelle et aident à écrire un code efficace.

incubate to solve Python programming problems

Historique et PPE-TSE¶

Ce guide de style met en lumière des parties du PEP 8 - Guide de style pour Python Code par Guido van Rossum, Barry Varsovie et Nick Coghlan. Le document complet est disponible à python.org et seuls les aspects pertinents pour les applications présentées dans ce livre électronique sont présentés dans ce chapitre.

Qu’est-ce qu’une PEP? La PEP représente la proposition d’amélioration du python**. Un PEP est un document de conception qui fournit de l’information à la communauté Python ou décrit une caractéristique, un processus ou un changement connexe proposé. Il y a de nombreux PEP, y compris la filière des normes, l’information et les propositions de processus. Ce chapitre met en lumière les recommandations de PEP 8, le guide de style pour le code Python, de Guido van Rossum, Barry Varsovie et Alyssa Coghlan.

De nombreux IDE, y compris PyCharm ou VS Code, fournissent une auto-complétion et des outils avec des conseils de style PEP pour faciliter une programmation cohérente. Ainsi, lorsque votre IDE souligne quelque chose dans votre script, vérifiez la raison de cela et envisagez de modifier le code en conséquence.

Le Zen de Python¶

On devient spirituels ? Loin de là. Le Zen de Python est une information PEP (20) de Tim Peters pour guider les programmeurs. Il s’agit de quelques lignes résumant les bonnes pratiques en matière de codage. Python Egg import this imprime le Zen de Python dans n’importe quel interprète Python :

import this

The Zen of Python, by Tim Peters

Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!

Définition du code¶

Longueur maximale de la ligne¶

PEP 8 recommande de limiter les lignes de code à 79 caractères. Le texte en flux dans les commentaires et docstrings doit être limité à 72 caractères. Une équipe peut convenir d’une limite de ligne de code allant jusqu’à 99 caractères, à condition que les commentaires et docstrings restent limités à 72 caractères.

Indication¶

L’identification regroupe les déclarations dans des suites contrôlées par des constructions telles que for, if, while, try, with, def, et class. Le PEP 8 recommande quatre espaces par niveau d’indentation. L’identification ne crée pas en soi une nouvelle portée variable : les noms attribués dans une suite if ou for restent dans la portée environnante. Les fonctions, les classes, les modules et certaines compréhensions ont leurs propres règles de cadrage.

for i in range(1, 2):
  print("I'm one level indented.")
  if i == 1:
	  print("I'm two levels indented.")

I'm one level indented.
I'm two levels indented.

Parce que les longues lignes de code sont de mauvaises pratiques, nous devons parfois utiliser les pauses de ligne lors de l’attribution d’une list ou de l’appel d’une fonction. Dans ces cas, la prochaine ligne continue est également insérée et il y a différentes options pour les cessions multilignes. Ici, nous voulons utiliser le code de style d’utiliser un délimiteur d’ouverture pour l’indentation:

a_too_long_word_list = ["Do", "not", "hard-code", "something", "like", "this.",
                        "There", "are", "better", "ways."]
a_better_indented_list = [
    "Do",
    "not",
    "hard-code",
    "something",
    "like",
    "this.",
    "...",
    ]

Rappel : PyCharm, VS Code et beaucoup d’autres IDE mettent automatiquement en page l’indentation.

Pause de ligne des expressions avec les opérateurs binaires¶

Lorsque les opérateurs binaires font partie d’une expression qui dépasse la longueur maximale de la ligne de 79 caractères, la rupture de ligne doit être devant les opérateurs binaires.

import pandas as pd

dummy_df = pd.get_dummies(
  pd.Series(["variable1", "parameter2", "sensor3"]),
  dtype=int,
)
print(dummy_df.head(3))

dum_sum = (
  dummy_df["variable1"]
  + dummy_df["parameter2"]
  - dummy_df["sensor3"]
)

   parameter2  sensor3  variable1
0           0        0          1
1           1        0          0
2           0        1          0

Lignes blanches¶

Pour séparer les blocs de code, appuyez plusieurs fois sur la touche Enter. Cependant, l’utilisation aléatoire et motivée par l’humeur de lignes blanches entraîne un code non structuré. C’est pourquoi PEP 8 auteurs fournissent également des conseils sur l’utilisation de lignes blanches:

Définition des classes surround et fonctions de haut niveau (c.-à-d. fonctions où la ligne def-line n’est pas dentelée) avec deux lignes blanches.
Méthodes surround (p. ex. fonctions dans une classe) avec une ligne vide.
Utilisez des lignes blanches dans tous les autres codes pour indiquer les sections logiques.

# blank 1 before top-level function
# blank 2 before top-level function
def top_level_function():
    pass
# blank 1 after top-level function
# blank 2 after top-level function

Blancs (espaces blancs)¶

Évitez les espaces blancs inutiles immédiatement à l’intérieur des parenthèses, des crochets ou des accoudoirs; avant les virgules, les semi-colons et les côlons ordinaires; ou entre un nom de fonction et sa liste d’arguments. Écrire function(e1, e2), (1,), a_dict = {a_key: a_value} et def fun(arg=0.0):.

Utilisez des espaces autour de l’affectation, de la comparaison et des opérateurs booléens. Pour les expressions arithmétiques, ajoutez des espaces autour des opérateurs de la plus basse priorité et utilisez le jugement pour clarifier la préséance; par exemple, hypot2 = x*x + y*y.

Paquets et modules¶

importations¶

Les importations apparaissent normalement après le module docstring et avant les modules globaux. Groupez-les dans cet ordre, avec une ligne blanche entre les groupes : bibliothèque standard, paquets tiers liés, et les importations d’applications ou de bibliothèques locales. Mettre les importations ordinaires sur des lignes séparées et éviter les importations de caractères génériques. Chaque importation devrait avoir sa propre ligne et éviter d’utiliser le signe virgule pour les importations multiples:

import os
import sys

import numpy as np

from my_package import my_module

Nommer les paquets et les scripts¶

Les nouveaux paquets ou modules personnalisés devraient avoir des noms courts et des noms minuscules, où les points forts peuvent être utilisés pour améliorer la lisibilité (découragés pour les paquets).

Commentaires¶

Bloc et commentaires en ligne¶

Les commentaires de bloc sont insérés au même niveau que le code qu’ils décrivent, et chaque ligne commence par # . Utilisez les commentaires en ligne avec parcimonie. Un commentaire en ligne apparaît sur la même ligne qu’un énoncé, est séparé de lui par au moins deux espaces, et commence par # .

Doctrines¶

Un docstring est une chaîne littérale qui se produit comme première instruction dans un module, une fonction, une classe ou une méthode. Il devient disponible via l’attribut __doc__ de l’objet. Le PEP 257 recommande trois doubles devis. Par exemple:

a_list = [1, 2]
print(a_list.__doc__)

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list.
The argument must be an iterable if specified.

Lors de l’écriture d’une fonction Python, les docstrings sont introduits immédiatement après la ligne def ... avec triple double-quotes:

def let_there_be_light(*args, **kwargs):
  """Print a sunrise message and return `True`.

  Args:
	  *args: Positional arguments accepted but not used.
	  **kwargs: Keyword arguments accepted but not used.

  Returns:
	  `True` in all cases.
  """
  print("Sunrise")
  return True

print(let_there_be_light.__doc__)


    Bright function accepting any input argument with indifferent behavior.
    :param an_input_argument: STR or anything else
    :param another_input_argument: FLOAT or anything else
    :return: True (in all cases)

Notez que les recommandations sur les docstrings sont fournies avec PEP 257 plutôt que PEP 8.

Conventions sur les noms¶

Définition des styles de dénomination¶

Les conventions de nommage utilisent les styles suivants (source: python.org):

Les classes utilisent normalement CapWords, par exemple MyClass.
Les classes d’exception définies par l’utilisateur suivent la convention de nom de classe et utilisent normalement le suffixe Error lorsqu’elles représentent une erreur, par exemple ConfigurationError.
Les fonctions, les méthodes et les variables utilisent des mots minuscules séparés par des accents au besoin pour la lisibilité.
Les constantes utilisent normalement des mots majuscules séparés par des accents, par exemple WATER_DENSITY = 1000.

Certains formats de noms variables déclenchent un comportement particulier de Python:

Les variables _single_leading_underscore indiquent une faible utilisation interne et ne seront pas importées avec from module import *
__double_leading_underscore les variables invoquent le nom mengling dans les classes (par exemple, une méthode appelée __dlu de la classe MyClass sera manggé dans _MyClass__dlu)
__double_leading_and_trailing_underscore__ variables sont magic objets ou attributs dans les espaces de noms contrôlés par l’utilisateur (par exemple, __init__ ou __call__ dans les classes)
Utilisez seulement des attributs magiques documentés et ne les inventez jamais. En savoir plus sur les méthodes magiques dans le chapitre sur Python classes.
Les variables single_trailing_underscore_ sont utilisées pour éviter les conflits avec les mots clés Python (par exemple, MyClass(class_='AnotherClass'))

Noms des objets¶

Utilisez les styles définis ci-dessus pour nommer les éléments Python comme suit :

Classes : CamelCase (CapWords) lettres seulement comme MyClass
Constantes: UPPERCASE lettres seulement, où les soulignés peuvent améliorer la lisibilité (p. ex., utiliser à un niveau de module par exemple pour attribuer la densité d’eau RHO = 1000)
Exceptions : CamelCase (CapWords) lettres seulement (les exceptions doivent être prédéfinies classes Error; généralement utiliser le suffixe Error (par exemple, TypeError)
Fonctions: lowercase lettres seulement, où les accents peuvent améliorer la lisibilité; parfois mixedCase applique pour assurer la compatibilité en arrière des styles dominants
Méthodes (fonction de classe, non-public): _lowercase lettres seulement avec un point fort, où les points forts peuvent améliorer la lisibilité
Méthodes (fonction de classe, public): lowercase lettres seulement, où les accents peuvent améliorer la lisibilité
Modules : lowercase lettres seulement, où les accents peuvent améliorer la lisibilité
Packages: lowercase lettres seulement, où les accents sont découragés
Variables: lowercase lettres seulement, où les accents peuvent améliorer la lisibilité
Variables (global): lowercase lettres seulement, où les soulignés peuvent améliorer la lisibilité; notez que “global” devrait limiter à l’utilisation variable dans un seul module.

Autres recommandations de style de code¶

Pour assurer la compatibilité du code et l’efficacité du programme, le guide de style PEP 8 fournit d’autres recommandations générales (lire la suite dans le Python docs):

Préférez une instruction def lors de la création d’une fonction nommée; n’attribuez pas une expression lambda directement à un nom. Un lambda court peut être approprié lorsqu’il est passé directement comme argument, par exemple items.sort(key=lambda item: item.name).
Lorsque des exceptions sont attendues, utilisez try - except clauses (voir la section errors and exceptions).
Assurez-vous que les méthodes et les fonctions renvoient les objets de façon uniforme, par exemple :

import numpy as np


def a_function_with_return(x):
  if x > 0:
	  return np.sqrt(x)
  return np.nan

Vérification de la réussite en apprentissage¶

Prenez le test de réussite d’apprentissage pour ce carnet Jupyter.

Unfold QR Code