Malgré cela, le reformatage de code reste une tache courante, et nécessaire, mais un gâchis énorme de temps. D’abord il faut décider comment on va formater, ce qui en équipe veut dire débat sur le pire sujet qui soit: le goût. Ensuite il faut mettre en place des configurations de linter (flake8, pylint, etc), et potentiellement l’infra qui va avec (tox, hooks git, CI…).

Pour cette raison, de nombreux outils de formatage automatique ont vu le jour. Le premier a été autopep8, et plus tard yapf de Google.

Mais ces deux outils ont quelques soucis:

• Pas facile à faire marcher ou à configurer.
• Ne résout pas l’éternel débat du formatage préféré qui revient dans un meeting chaque année.
• Parfois ils ne marchent pas.
• Parfois ils changent le sens du code (arg!).
• Ils vous font des git diff bien velus.
• Ne marche pas avec toutes les versions de Python.

Le monde du langage Go a choisi une stratégie différente: la technique du “ta gueule”.

Et aussi: ta gueule

Cette technique subtile et raffinée s’est incarnée dans l’outil Gofmt, qui est fourni par défaut avec go, et n’a AUCUN réglage.

Le résultat, tout le monde a fermé sa gueule et a adopté l’outil.

Est-ce que le formatage est parfait ? Non.

Est-ce qu’il plaît à tout le monde ? Absolument pas.

Est-ce qu’il fait fermer sa putain de gueule à tout le monde afin qu’on puisse enfin retourner à des choses plus importantes comme coder ?

Yes !

Gofmt produit un formatage suffisamment clair et pragmatique, et comme il est fortement ancré dans la communauté, tout le monde est à la même enseigne. Passer d’un code à un autre est facile. Pas de temps perdu à discuter du style ou à tweaker ses linters. Tout le monde lance go fmt (aka go ferme ta …) et on passe à autre chose.

Dernièrement facebook a décidé de faire pareil, et à pondu en open source black (en référence à Henry Ford), un outil de formatage en Python, qui n’a que 2 réglages. Il suit le PEP8, mais évidemment sa propre interprétation, et ne propose rien d’autre.

Black a aussi l’avantage de fournir des diffs assez petits, et surtout, vérifie si l’AST change après un reformatage, et annule le cas échéant, garantissant que le sens de votre code n’est pas altéré.

Est-ce que j’aime toutes les règles de formatages de black ? Non.

Est-ce que regarder sa sortie me donne parfois envie de me bouffer les couilles parce que franchement, qui pense que c’est une bonne idée d’aligner les choses comme ça ? Parfois.

Mais c’est good enough.

Et du coup, l’adoption de black a été très rapide dans la communauté, et il a été appliqué à heroku, requests, tablib, envoy, clint, fabric 2 et pytest. 4000 stars sur github.

Installation

Évidemment, ça se pip install, mais uniquement sur Python 3.6. Black peut checker du code 2.7, mais il lui faut du 3.6 minimum pour exister, donc on l’installe en parallèle. Évidemment, on peut l’intégrer à ST, Vim ou VSCode. Si votre projet utilise un Python different, il faut donc dans les options faire pointer l’exécutable vers l’installation séparée.

Résultat

Dans l’esprit du lien partagé par Seb, créons un générateur de titre de film porno:

import random

subject_qualifiers = ( "shy", "mature", "busty", "hot", "horny", "ebony", "quiet", "excited", "naughty", "bad", "cheating", "beautifull", "gorgeous", "drunk", "emo", "fat", "chubby", "goth", "lingery wearing", "latex enthousiast", "placid", "energic", 'slutty', 'sweaty', 'curvy', )

subjects =(
    'teen',
    'doll',
    'brunette',
    'blonde',
    'midget',
    'milf',
    'bitch',
    'babe',
    'sister',
    'step-mom',
    'vixen',
    'secretary',
    'real estate agent',
    'teacher',
    'student',
    'schoolgirl',
    'cheer leader',
    'asian tourist',
    'babysitter',
    'ex girlfriend',
    'nurse',
    'squirtter',
    'model',
    'granny',
    'furry',
)

actions = (
        "recieves anal",
        "get busted",
        "driven to bukakke",
        "taught double penetration",
        "fucked hard",
        'gently chocked',
        'punished',
        'forced into blow job',
        'pounded',
        'creampied',
        'ass raped',
        "eaten",
        "get her pussy wet",
        "shamed",
        "get an orgasm for the first time",
        'lead to loud climax',
        'offered best sex of her life',
        'worn out',
        'cured from boredom',
        'warmed up',
        'loved in and out',
        'generously oiled',
        'shocked and impressed',
        'decieved into giving it',
        'woke up roughly',
        'get sexy massage',
        'ridden to exhaustion',
        'turned into a lavish slave',
        'never submit to torture',
        'rebels against abuses',
        'taken in every possible way',
        'enjoy the 10 inches provided',
)

actors = (
        "pawn shop owner",
    "corrupted cop",
    "dirty plumber",
    "big ass nigga",
    "sport coach"
    "her boss",
    "twisted psychiatrist",
    "ripped doctor",
    "crispy fire fighter",
    "smug playboy",
    "skinny geek",
    "eccentric millionaire",
    "airplane pilot",
    "movie star",
    'football team',
    'her big brother',
    'security guard',
    'hairy beast',
    'wasted guitard player',
    'hung indian immigrant',
    'a guy twice her size',
    '17 guys in a row',
    'her ideal man',
    'her secret prince charming',
    'weirdo albinos',
    'muscle giant',
    'the worst cook ever',
    'cable man',
    'more men that she can count',
    'two friendly brothers',
    'enrike strongsteel'
)

contexts = (
    "on the beach","in a cheap motel","in the back of a van",
    "in airplane toilets", "for hours", "to pay back her depts",
    "for a stupid mistake", "and it gets better", "and ask for more",
    "because she could", "in exchange for a favor",
    "right next to her boyfriend", "as a reward",
    "hopping to get him back", "caught on security cam", "every monday",
    "in a barn", "but that's not all", 'but she has a secret',
    "and she has a dick too", 'before inviting her friend over',
    'while her father is watching', 'with her ', "while auditing for a role",
    "to get her job back", "for an interview", "in exclusive sex tape",
    "again and again", ", begging to stop", "for a change", "for chrismas",
    "in public", 'in a back alley', "during a concert", 'on her death bed'
)

punctuation = ('','!','!!','...')

def get_title(subject_qualifiers, subjects, actions, actors, contexts) :


    qualifier = random.choice(subject_qualifiers)
    subject = random.choice(subjects)
    action = random.choice(actions)
    actor = random.choice(actors)
    context = random.choice(contexts)

    return f"{qualifier} {subject} {action} by {actor} {context}" .capitalize()


if __name__ == "__main__":
    print(get_title(subject_qualifiers = subject_qualifiers, subjects=subjects,
                    actions=actions, actors=actors, contexts=contexts))

Usage:

$ python3.6 porn_title_generator.py
Chubby model loves bukakke by skinny geek during a concert
$ python3.6 porn_title_generator.py
Busty bitch rebel against abuses by security guard but she has a secret
$ python3.6 porn_title_generator.py
Lingery wearing student creampied by weirdo albinos on the beach
$ python3.6 porn_title_generator.py
Horny bitch offered best sex of her life by hairy beast in airplane toilets
$ python3.6 porn_title_generator.py
Emo blonde punished by airplane pilot on the beach
$ python3.6 porn_title_generator.py
Quiet squirtter lead to loud climax by wasted guitard player while auditing for a role
$ python3.6 porn_title_generator.py
Emo babysitter get her pussy wet by football team caught on security cam
$ python3.6 porn_title_generator.py
Busty asian tourist taken in every possible way by muscle giant and she has a dick too
$ python3.6 porn_title_generator.py
Placid milf ass raped by muscle giant in a back alley

Je soupçonne un coup des frères Markov

On applique black, zero réglage, usage simplissime:

$ black . # appel recursif, modification in place par défaut

Le résultat.

import random

subject_qualifiers = (
    "shy",
    "mature",
    "busty",
    "hot",
    "horny",
    "ebony",
    "quiet",
    "excited",
    "naughty",
    "bad",
    "cheating",
    "beautifull",
    "gorgeous",
    "drunk",
    "emo",
    "fat",
    "chubby",
    "goth",
    "lingery wearing",
    "latex enthousiast",
    "placid",
    "energic",
    "slutty",
    "sweaty",
    "curvy",
)

subjects = (
    "teen",
    "doll",
    "brunette",
    "blonde",
    "midget",
    "milf",
    "bitch",
    "babe",
    "sister",
    "step-mom",
    "vixen",
    "secretary",
    "real estate agent",
    "teacher",
    "student",
    "schoolgirl",
    "cheer leader",
    "asian tourist",
    "babysitter",
    "ex girlfriend",
    "nurse",
    "squirtter",
    "model",
    "granny",
    "furry",
)

actions = (
    "recieves anal",
    "get busted",
    "driven to bukakke",
    "taught double penetration",
    "fucked hard",
    "gently chocked",
    "punished",
    "forced into blow job",
    "pounded",
    "creampied",
    "ass raped",
    "eaten",
    "get her pussy wet",
    "shamed",
    "get an orgasm for the first time",
    "lead to loud climax",
    "offered best sex of her life",
    "worn out",
    "cured from boredom",
    "warmed up",
    "loved in and out",
    "generously oiled",
    "shocked and impressed",
    "decieved into giving it",
    "woke up roughly",
    "get sexy massage",
    "ridden to exhaustion",
    "turned into a lavish slave",
    "never submit to torture",
    "rebels against abuses",
    "taken in every possible way",
    "enjoy the 10 inches provided",
)

actors = (
    "pawn shop owner",
    "corrupted cop",
    "dirty plumber",
    "big ass nigga",
    "sport coach" "her boss",
    "twisted psychiatrist",
    "ripped doctor",
    "crispy fire fighter",
    "smug playboy",
    "skinny geek",
    "eccentric millionaire",
    "airplane pilot",
    "movie star",
    "football team",
    "her big brother",
    "security guard",
    "hairy beast",
    "wasted guitard player",
    "hung indian immigrant",
    "a guy twice her size",
    "17 guys in a row",
    "her ideal man",
    "her secret prince charming",
    "weirdo albinos",
    "muscle giant",
    "the worst cook ever",
    "cable man",
    "more men that she can count",
    "two friendly brothers",
    "enrike strongsteel",
)

contexts = (
    "on the beach",
    "in a cheap motel",
    "in the back of a van",
    "in airplane toilets",
    "for hours",
    "to pay back her depts",
    "for a stupid mistake",
    "and it gets better",
    "and ask for more",
    "because she could",
    "in exchange for a favor",
    "right next to her boyfriend",
    "as a reward",
    "hopping to get him back",
    "caught on security cam",
    "every monday",
    "in a barn",
    "but that's not all",
    "but she has a secret",
    "and she has a dick too",
    "before inviting her friend over",
    "while her father is watching",
    "with her ",
    "while auditing for a role",
    "to get her job back",
    "for an interview",
    "in exclusive sex tape",
    "again and again",
    ", begging to stop",
    "for a change",
    "for chrismas",
    "in public",
    "in a back alley",
    "during a concert",
    "on her death bed",
)

punctuation = ("", "!", "!!", "...")


def get_title(subject_qualifiers, subjects, actions, actors, contexts):

    qualifier = random.choice(subject_qualifiers)
    subject = random.choice(subjects)
    action = random.choice(actions)
    actor = random.choice(actors)
    context = random.choice(contexts)

    return f"{qualifier} {subject} {action} by {actor} {context}".capitalize()


if __name__ == "__main__":
    print(
        get_title(
            subject_qualifiers=subject_qualifiers,
            subjects=subjects,
            actions=actions,
            actors=actors,
            contexts=contexts,
        )
    )

L’indentation est revue et normalisée vers 4 espaces, les espacements et sauts de ligne sont rééquilibrés (limite de caractères à 88 ), les quotes deviennent toutes ‘”‘. C’est lisible. Le code marche toujours.

Problem solved.

Du coup, un petit post pour me donner l’impression de ne pas être inutile à l’humanité.

De toutes les recommandations du PEP8, garder des lignes courtes, souvent moins de 80 caractères, est celle qui fait le plus râler.

On rétorque parfois que c’est une règle qui n’a pas de sens de nos jours avec nos grands écrans HD.

Sauf que:

• L’œil humain fonctionne par micro sauts, et peut donc bien plus efficacement scanner de longues colonnes que de longues lignes.
• Il est très courant de pouvoir mettre du code côte à côte sur un même écran pour comparer, merger ou avoir plusieurs vues sur un fichier.
• Vous ne savez pas sur quoi sera lu votre code. Au bureau vous avez peut être un setup à triple écran 4K, mais les autres n’ont peut être pas cette chance. Les chats, les pastebins, les blogs posts, un slide show, un remote ssh, des comments, des tickets, ou un retro projecteur basse résolution sont autant de supports sur lesquels votre code finira probablement. Et ils ne sont pas larges.
• Un diff sur de longues lignes c’est dégueulasse.
• Le debug pas à pas qui s’arrête sur une ligne de 3km ça donne des envies de meurtre.

D’une manière générale, garder des lignes courtes est une bonne habitude et incitera à écrire un code sain. Le processus de réduire la taille des lignes passe par l’expressivité, la clarté, le refactoring, etc. Au final, c’est excellent pour la santé du projet.

N’oubliez pas non plus que le PEP8 indique clairement qu’il ne faut jamais suivre une règle de manière rigide. Si votre ligne est absolument plus adéquate sur une ligne, alors mettez la sur une ligne.

Maintenant qu’on a expliqué le pourquoi, parlons du comment. En effet beaucoup de bonnes pratiques ne sont pas appliquées parce qu’on ne sait pas faire. Faire des lignes courtes demande une certaine connaissance, et un peu de pratique.

Voici quelques pistes pour vous aider dans vos prochaines sessions.

Python est fait pour ça

Python force à indenter, et c’est une de ses meilleures caractéristiques. Jamais vous ne vous retrouverez comme dans d’autres langages face au code de votre collègue, ce gros porc, qui aligne ses accolades avec le groin.

Mais pour garder des lignes courtes, l’indentation joue contre vous.

Python vient heureusement avec tout un tas d’outils pour rendre votre code court, rapide et peu gourmand on mémoire. C’est tout bénef.

itertools, all(), any(), filter(), map(), collections, les listes en intension, functools et les générateurs sont tous d’excellents moyens de créer un code plus beau, plus court, et plus efficace. Apprenez à les utilisez ! Vous serez un meilleur programmeur, plus productif, et les lignes seront naturellement plus courtes.

Exemples…

Le module itertools permet de faire un tas de choses, comme remplacer les boucles imbriquées.

Remplaçons :

>>> for lettre in "abc":
...     for chiffre in (1, 2, 3):
...         print(lettre, chiffre)
...
a 1
a 2
a 3
b 1
b 2
b 3
c 1
c 2
c 3

Par :

>>> from itertools import product
>>> products = product("abc", (1, 2, 3))
>>> for lettre, chiffre in products:
...     print(lettre, chiffre)

Les built-ins ont un tas d’outils pour pour manipuler les données.

Si vous avez des collections dont vous voulez vérifier tout le contenu:

>>> from random import randint
>>> data = [randint(0, 10) for x in range(0, randint(0, 10))]
>>> max(data)  # pas besoin de boucler pour trouver le max
9
>>> if any(x > 3 for x in data): # any est un super "or"
...    print('Un élément est supérieur à 3')

Le module collections possède d’ailleurs tout un tas d’outils pour faire le travail à votre place :

>>> from collections import Counter
>>> Counter("aaaaaaaaabbbbbbccccc")
Counter({'a': 9, 'b': 6, 'c': 5})

On peut éviter un tas de try/except avec les helpers qui retournent une valeur par défaut:

>>> {"foo": 1}.get('bar', 3)  # et next, iter, setdefault... 
3

Sans parler de l’unpacking, le slicing, le paramétrage dynamique, etc.

Bref, si votre ligne est trop longue, c’est peut être parce que vous être en train de sous-utiliser Python.

De même, apprenez les libs les plus célèbres en Python.

pytest, pendulum, request, pandas…

Dès qu’un usage particulier intervient, elles seront généralement plus efficaces que la stdlib. Moins de code !

Refactorisez

Un bloc de code qui commence à être long sera avantageusement déplacé dans une méthode ou une fonction. Avec un joli nom bien explicite qui va naturellement rendre votre code mieux documenté, et testable.

Tant qu’on y est, faites usages des variables intermédiaires.

res = [foo for foo in objet.attribut['cle'] if foo > wololo]

Gagnera à devenir:

nom_explicite = objet.attribut['cle']
res = [foo for foo in nom_explicite if foo > wololo]

Les parenthèses pour les sauts de ligne

Les parenthèses en Python, c’est magique.

Avant :

from module_de_la_mort_qui_tue import foo, bar, et, toute, la, clique

Après

from module_de_la_mort_qui_tue import (
	foo, 
	bar, 
	et, 
	toute, 
	la, 
	clique
)

Ca marche partout, dans les appels de fonctions, l’accès des attributs, les chaînes de caractères…

On part de :

queryset = ModelDeDjango.objects.filter(attribut=val).first()

Et bim :

queryset = (ModelDeDjango.objects
                         .filter(attribut=val)
                         .first())

Si des parenthèses sont déjà là, inutile d’en rajouter:

Aller :

raise OverkillError("Arrrrrrrrrrrrrrrrrrrrrrrrrrrrggggggg")

Hop :

raise OverkillError(
	"Arrrrrrrrrrrrrrrrr"
	"rrrrrrrrrrrggggggg"
)

Aidez-vous de l’environnement

Vous outils sont là pour vous faciliter la vie. Votre éditeur par exemple, a certainement un moyen d’afficher un indicateur vertical pour symboliser la limite de 80 caractères.

Les bons IDES et les linters vous signalerons le dépassement. Ça vaut le coup d’investir dedans. Si votre éditeur ne le supporte pas par défaut, il a peut-être un plugin pour utiliser un linter.

VSCode et Sublime Text ont tous deux des plugins pour Python qui permettent cela. Notamment ils peuvent exploiter l’excellent linter flake8, qui sinon peut s’utiliser à la main.

Pour certaines lignes, vous allez dépasser. Ce n’est pas la mer à boire tant que c’est un choix conscient et pas de la flemme.

Par exemple, les commentaires avec des URLs dedans dépassent souvent. Beaucoup de linters ont un réglage pour les autoriser (ou un pattern au choix), activez-le.

Si vous avez une ligne qui dépasse et que le signalement de votre IDE/linter vous casse les couilles, il est souvent possible de le désactiver en ajoutant en fin de ligne le commentaire:

# noqa

Qui signifie tantôt “no question asked” ou “no quality assessment”.

Rappelez-vous toujours que des recommandations stylistiques sont essentiellement arbitraires. Elles servent à avoir une base commune, et il n’y en pas de meilleures.

On recommande les espaces au lieu des tabs. Les tabs sont sémantiquement plus adaptés et plus flexibles. Les espaces permettent d’avoir un seul type de caractères non imprimables dans son code et autorise un alignement fin d’une expression divisée en plusieurs lignes. Il n’y a pas de meilleur choix. Juste un choix tranché pour passer à autre chose de plus productif, comme coder.

On recommande par contre une limite de 80 caractères pour les lignes. Cela permet à l’œil, qui scanne par micro-sauts, de parser plus facilement le code. Mais aussi de faciliter le multi-fenêtrage. Néanmoins cette limite peut être brisée ponctuellement si le coût pour la lisibilité du code est trop important. Tout est une question d’équilibre.

Ready ? Oh yeah !

L’espacement

def  foo (bar = 'test'):
   if bar=='test' : # this is a test
      bar={1:2 , 3 : 4*4}

Devient:

def foo(bar='test'):
    if bar == 'test':  # this is a test
        bar = {1: 2, 3: 4*4}

On ne double pas les espaces. On n’a pas d’espace avant le ‘:’ ou le ‘,’ mais un après. Les opérateurs sont entourés d’espaces, sauf le ‘=’ quand il est utilisé dans la signature de la fonction ou pour les opérations mathématiques (pour ces dernières, les deux sont tolérés).

Un commentaire inline est précédé de 2 espaces, une indentation est 4 espaces.

Les sauts de lignes aussi sont importants:

import stuff

def foo():
    pass

def bar():
    pass

Devient:

import stuff


def foo():
    pass


def bar():
    pass

Les déclarations à la racine du fichier sont séparées de 2 lignes. Pas plus, pas moins.

Mais à l’intérieur d’une classe, on sépare les méthodes d’une seule ligne.

class Foo:


    def bar1():
        pass


    def bar2():
        pass

Devient:

class Foo:

    def bar1():
        pass

    def bar2():
        pass

Tout cela contribue à donner un rythme régulier et familier au code. Le cerveau humain adore les motifs, et une fois qu’il est ancré, il est facile à reconnaître et demande peu d’effort à traiter.

Les espaces servent aussi à grouper les choses qui sont liées, et à séparer les choses qui ne le sont pas.

Le style de saut de ligne à l’intérieur d’une fonction ou méthode est libre, mais évitez de sauter deux lignes d’un coup.

Le nom des variables

Si on s’en tient au PEP8, on fait du snake case:

def pasUnTrucCommeCa():
    niCommeCa = True

def mais_un_truc_comme_ca():
    ou_comme_ca = True

Sauf pour les classes:

class UnTrucCommeCaEstBon:

Et si on a un acronyme:

def lower_case_lol_ptdr():
    ...

class UpperCaseLOLPTDR:
    ...

Malgré la possibilité d’utiliser des caractères non ASCII dans les noms en Python 3, ce n’est pas recommandé. Même si c’est tentant de faire:

>>> Σ = lambda *x: sum(x)
>>> Σ(1, 2, 3)
6

Néanmoins c’est l’arbre qui cache la forêt. Il y a plus important : donner un contexte à son code.

Si on a:

numbers = (random.randint(100) for _ in range(100))
group = lambda x: sum(map(int, str(x)))
numbers = (math.sqrt(x) for x in numbers if group(x) == 9)

Le contexte du code donne peu d’informations et il faut lire toutes les instructions pour bien comprendre ce qui se passe. On peut faire mieux:

def digits_sum(number):
    """ Take a number xyz and return x + y + z """
    return sum(map(int, str(number)))

rand_sample = (random.randint(100) for _ in range(100))
sqrt_sample = (math.sqrt(x) for x in rand_sample if digits_sum(x) == 9)

Ici, en utilisant un meilleur nommage et en rajoutant du contexte, on rend son code bien plus facile à lire, même si il est plus long.

Le PEP8 n’est donc que le début. Un bon code est un code qui s’auto-documente.

Notez que certains variables sont longues, et d’autres n’ont qu’une seule lettre. C’est parce qu’il existe une sorte de convention informelle sur certains noms dans la communauté :

i et j sont utilisés dans pour tout ce qui est incrément:

for i, stuff in enumerate(foo):

x, y et z sont utilisés pour contenir les éléments des boucles:

for x in foo:
    for y in bar:

_ est utilisé soit comme alias de gettext:

from gettext import gettext as _

Soit comme variable inutilisée:

(random.randint(100) for _ in range(100))

_ a aussi un sens particulier dans le shell Python : elle contient la dernière chose affichée automatiquement.

f pour un fichier dans un bloc with:

with open(stuff) as f:

Si vous avez deux fichiers, nommez les:

with open(foo) as foo_file, open(bar) as bar_file:

*args et **kwargs pour toute collection d’arguments hétérogènes :

def foo(a, b, **kwarg):

Mais attention, si les arguments sont homogènes, on les nomme:

def merge_files(*paths):

Et bien entendu self pour l’instance en cours, ou cls pour la classe en cours:

class Foo:

    def bar(self):
        ...

    @classmethod
    def barbar(cls):
        ...

Dans tous les cas, évitez les noms qui sont utilisés par les built-ins :

>>> dir(__builtins__)
['ArithmeticError', 'AssertionError', 'AttributeError', 'BaseException', 'BlockingIOError', 'BrokenPipeError', 'BufferError', 'BytesWarning', 'ChildProcessError', 'ConnectionAbortedError', 'ConnectionError', 'ConnectionRefusedError', 'ConnectionResetError', 'DeprecationWarning', 'EOFError', 'Ellipsis', 'EnvironmentError', 'Exception', 'False', 'FileExistsError', 'FileNotFoundError', 'FloatingPointError', 'FutureWarning', 'GeneratorExit', 'IOError', 'ImportError', 'ImportWarning', 'IndentationError', 'IndexError', 'InterruptedError', 'IsADirectoryError', 'KeyError', 'KeyboardInterrupt', 'LookupError', 'MemoryError', 'NameError', 'None', 'NotADirectoryError', 'NotImplemented', 'NotImplementedError', 'OSError', 'OverflowError', 'PendingDeprecationWarning', 'PermissionError', 'ProcessLookupError', 'RecursionError', 'ReferenceError', 'ResourceWarning', 'RuntimeError', 'RuntimeWarning', 'StopAsyncIteration', 'StopIteration', 'SyntaxError', 'SyntaxWarning', 'SystemError', 'SystemExit', 'TabError', 'TimeoutError', 'True', 'TypeError', 'UnboundLocalError', 'UnicodeDecodeError', 'UnicodeEncodeError', 'UnicodeError', 'UnicodeTranslateError', 'UnicodeWarning', 'UserWarning', 'ValueError', 'Warning', 'ZeroDivisionError', '_', '__build_class__', '__debug__', '__doc__', '__import__', '__loader__', '__name__', '__package__', '__spec__', 'abs', 'all', 'any', 'ascii', 'bin', 'bool', 'bytearray', 'bytes', 'callable', 'chr', 'classmethod', 'compile', 'complex', 'copyright', 'credits', 'delattr', 'dict', 'dir', 'divmod', 'enumerate', 'eval', 'exec', 'exit', 'filter', 'float', 'format', 'frozenset', 'getattr', 'globals', 'hasattr', 'hash', 'help', 'hex', 'id', 'input', 'int', 'isinstance', 'issubclass', 'iter', 'len', 'license', 'list', 'locals', 'map', 'max', 'memoryview', 'min', 'next', 'object', 'oct', 'open', 'ord', 'pow', 'print', 'property', 'quit', 'range', 'repr', 'reversed', 'round', 'set', 'setattr', 'slice', 'sorted', 'staticmethod', 'str', 'sum', 'super', 'tuple', 'type', 'vars', 'zip']

Les erreurs les plus communes : list, dict, min, max, next, file, id, input et str.

La longueur des lignes

C’est le point le plus sujet à polémique. Quelques astuces pour se faciliter la vie.

L’indentation est votre amie.

dico = {0: None, 1: None, 2: None, 3: None, 4: None, 5: None, 6: None, 7: None, 8: None, 9: None}
tpl = ('jaune', 'bleu', 'rouge', 'noir', 'octarine')
res = arcpy.FeatureClassToGeodatabase_conversion(['file1.shp', 'file2.shp' ], '/path/to/file.gdb')

Devient:

dico {
    0: None,
    1: None,
    2: None,
    3: None,
    4: None,
    5: None,
    6: None,
    7: None,
    8: None,
    9: None
}

tpl = (
    'jaune',
    'bleu',
    'rouge',
    'noir',
    'octarine'
)

res = arcpy.FeatureClassToGeodatabase_conversion([
        'file1.shp',
        'file2.shp'
    ],
    '/path/to/file.gdb'
)

Les parenthèses permettent des choses merveilleuses.

from module import package1, package2, package3, package4, package5, package6, package7
query = db.query(MyTableName).filter_by(MyTableName.the_column_name == the_variable, MyTableName.second_attribute > other_stuff).first())
string = "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat."

from module import (package1, package2, package3, package4,
                    package5, package6, package7)
query = (db.query(MyTableName)
           .filter_by(MyTableName.the_column_name == the_variable,
                      MyTableName.second_attribute > other_stuff)
           .first())
string = ("Lorem ipsum dolor sit amet, consectetur adipisicing elit, "
          "sed do eiusmod tempor incididunt ut labore et dolore magna "
          "aliqua. Ut enim ad minim veniam, quis nostrud exercitation "
          "ullamco laboris nisi ut aliquip ex ea commodo consequat.")

Les variables intermédiaires documentent le code:

sqrt_sample = (math.sqrt(x) for x in (random.randint(100) for _ in range(100)) if sum(map(int, str(number))) == 9)

Devient bien plus clair avec :

def digits_sum(number):
    """ Take a number xyz and return x + y + z """
    return sum(map(int, str(number)))

rand_sample = (random.randint(100) for _ in range(100))
sqrt_sample = (math.sqrt(x) for x in rand_sample if digits_sum(x) == 9)

return, break et continue permettent de limiter l’indentation:

def foo():
    if bar:
        rand_sample = (random.randint(100) for _ in range(100))
        return (math.sqrt(x) for x in rand_sample if digits_sum(x) == 9)

    return None

Est plus élégant écrit ainsi:

def foo():
    if not bar:
        return None

    rand_sample = (random.randint(100) for _ in range(100))
    return (math.sqrt(x) for x in rand_sample if digits_sum(x) == 9)

any, all et itertools.product évident pas mal de blocs:

for x in foo:
    if barbarbarbarbarbarbar(x):
        meh()
        break 

for x in foo:
    for y in bar:
        meh(y, y)

Devient:

is_bar = (barbarbarbarbarbarbar(x) for x in foo)
if any(is_bar):
   meh()

import itertools
for x, y in itertools.product(foo, bar):
    meh(y, y)

Le fait est que Python est bourré d’outils très expressifs. Oui, il arrivera parfois que vous deviez briser la limite des 80 charactères. Je le fais souvent pour mettre des URLs en commentaire par exemple. Mais ce n’est pas le cas typique si vous utilisez le langage tel qu’il a été prévu.

Passer en mode pro

Le PEP8, c’est un point de départ. Quand on a un script et qu’il grandit sous la forme d’une bibliothèque, il faut plus que le reformatter.

A partir d’un certain point, on voudra coiffer son code et lui mettre un costume. Reprenons :

def digits_sum(number):
    """ Take a number xyz and return x + y + z """
    return sum(map(int, str(number)))

rand_sample = (random.randint(100) for _ in range(100))
sqrt_sample = (math.sqrt(x) for x in rand_sample if digits_sum(x) == 9)

On lui fait un relooking pour son entretien d’embauche :

def digits_sum(number):
    """ Take a number xyz and return x + y + z

        Arguments:
            number (int): the number with digits to sum.
                            It can't be a float.abs

        Returns:
            An int, the sum of all digits of the number.

        Example:
            >>> digits_sum(123)
            6
    """
    return sum(map(int, str(number)))

def gen_squareroot_sample(size=100, randstart=0, randstop=100, filter_on=9):
    """ Generate a sample of random numbers square root

        Take `size` number between `randstart` and `randstop`,
        sum it's digits. If the resulting value is equal to `filter_on`,
        yield it.

        Arguments:
            size (int): the size of the pool to draw the numbers from
            randstart (int): the lower boundary to generate a number
            randstop (int): the upper boundary to generate a number
            filter_on (int): the value to compare to the digits_sum

        Returns:
            Generator[float]

        Example:
            >>> list(gen_squareroot_sample(10, 0, 100, filter_on=5))
            [5.291502622129181, 6.708203932499369, 7.280109889280518]

    """
    for x in range(size):
        dsum = digits_sum(random.randint(randstart, randstop))
        if dsum == filter_on:
            yield math.sqrt(x)

Et dans un autre fichier :

sqrt_sample = gen_squareroot_sample()

L’important ici:

• Le code devient modulable car on en fait des fonctions.
• Les fonctions ont des paramètres avec des valeurs par défaut pour faciliter la vie.
• On utilise les docstrings pour documenter le code.
• Des noms bien choisis complètent cette documentation. Le code devient aussi plus verbeux pour laisser la place à la modularité, mais aussi la facilité d’édition.

Il ne faut pas laisser le PEP8 vous limiter à la vision de la syntaxe. La qualité du code est importante : sa capacité à être lu, compris, utilisé facilement et modifié.

Pour cette même raison, il faut travailler ses APIS.

Si vous avez :

class DataSource:

    def open(self):
        ...

    def close(self):
        ...

    def getTopic(self, topic):
       ...

Et que ça s’utilise comme ça:

ds = DataSource()
ds.open()
data = ds.getTopic('foo')
ds.close()

Vous pouvez raler sur le getTopic. Mais si vous vous limitez à ça, vous ratez l’essentiel : cette API n’est pas idiomatique.

Une version plus proche de la philosophie du langage serait:

class DataSource:

    def open(self):
        ...

    def close(self):
        ...

    def get_topic(self, topic):
       ...

    def __getitem__(self, index):
        return self.get_topic(index)

    def __enter__(self):
        self.open()
        return self

    def __exit__(self, *args, **kwargs):
        self.close()

Et que ça s’utilise comme ça:

with DataSource() as ds:
    data = ds['foo']

Le style d’un langage va bien au-delà des règles de la syntaxe.

Les docstrings

Je suis beaucoup plus relaxe sur le style des docstrings. Il y a pourtant bien le PEP 257 pour elles.

Simplement ne pas le respecter parfaitement n’affecte pas autant leur lisibilité car c’est du texte libre.

Quelques conseils tout de même.

• Si elle peut tenir sur une ligne, mettez tout sur une ligne, y compris les """.
• Utilisez """, pas '''. La majorité des gens le font, et ça fera très bizarre de mélanger.
• Choisissez une convention de documentation et tenez-vous y. Les plus populaires sont celles de sphinx, numpy et Google. J’ai une préférence pour la dernière.
• N’hésitez pas à la faire longue, avec un exemple. Il n’est pas rare que la docstring soit plus longue que le code qu’elle documente.
• Une bonne docstring et une fonction gardée courte et avec une signature bien nommée a rarement besoin de commentaires.
• Les docstests sont un enfer à maintenir.

En bonus

flake8 est un excellent linter qui vérifiera votre style de code. Il existe en ligne de commande ou en plugin pour la plupart des éditeurs.

Dans le même genre, mccabe vérifira la complexité de votre code et vous dira si vous êtes en train de fumer en vous attributant un score. Il existe aussi intégré comme plugin de flake8 et activable via une option.

Tox vous permet d’orchestrer tout ça, en plus de vos tests unittaires. Je ferai un article dessus un de ces 4.

Si vous voyez des commentaires comme # noqa ou # xxx: ignore ou # xxx: disable=YYY, ce sont des commentaires pour ponctuellement dire à ces outils de ne pas prendre en considération ces lignes.

Car souvenez-vous, ces règles sont là pour vous aider. Si à un moment précis elles cessent d’etre utiles, vous avez tous les droits de pouvoir les ignorer.

Mais ces règles communes font de Python un langage à l’écosystème exceptionnel. Elles facilitent énormément le travail en équipe, le partage et la productivité. Une fois habitué à cela, travailler dans d’autres conditions vous paraitra un poids inutile.

pip install yapf

Yapf est un reformateur de code, vous lui filez un fichier (ou un dossier à parcourir récursivement), et il reformate le code pour qu’il soit plus lisible, et plus proche du PEP8.

On en parle en ce moment car le code appartient à Google et que le projet est comparé à gofmt le formatteur intégré à la stack Goland dont les Golois nous ventent les mérites avec moult regards condescendant vers tous les autres langages depuis qu’ils l’ont.

Yapf est loin des features de gofmt pour le moment, mais c’est cool d’avoir un point de départ, car c’est vrai que ça manquait. Non pas que ça n’existait pas déjà, mais les tentatives précédentes n’avaient soulevé aucun enthousiasme, et donc pas beaucoup de contrib. Il a fallut, comme d’hab, qu’un concours de celui qui a la plus grosse motive tout ça à coup d’éGOs, si vous voyez ce que je veux dire. On a bien eu pip intégré à Python parce que les codeurs JS se foutaient de notre gueule avec npm installé par défaut.

Bref, pour le moment yapf s’occupe surtout des espaces et de l’indentation, mais il le fait bien.

Soit le programme suivant :

from __future__ import (unicode_literals, absolute_import, print_function,
    division)

    def yolo(a,b =None) :
        print ( "Ca fait mal aux yeux hein ?")

        a= 1

        if a==b :
            return(b)

        if True and      False:# c'est chiant n'est-il pas ?
          return "bob"



    WOLOLO = {
        [1, 2, 3, 4],
        [5, 6, 7, 8],
        [9, 10, 11, 12]
    }

    OYOOYO = {
        [1, 2, 3, 4],
        [5, 6, 7, 8],
        [9, 10, 11, 12]
    }  # yapf: disable

Un petit coup de :

yapf programme.py

Et pouf, il vous sort :

from __future__ import (unicode_literals, absolute_import, print_function,
                        division)


def yolo(a, b=None):
  print("Ca fait mal aux yeux hein ?")

  a = 1

  if a == b:
    return (b)

  if True and False:  # c'est chiant n'est-il pas ?
    return "bob"


WOLOLO = {[1, 2, 3, 4], [5, 6, 7, 8], [9, 10, 11, 12]}

OYOOYO = {
    [1, 2, 3, 4],
    [5, 6, 7, 8],
    [9, 10, 11, 12]
}  # yapf: disable

Yapf existe en ligne de commande, mais peut être utilisé comme une lib. En prime, avec -i, il peut modifier le fichier sur place au lieu de juste faire l’output dans le terminal.

J’espère vraiment qu’il va gagner en traction histoire de pouvoir mettre ça dans tous mes hook git et oublier une bonne fois pour toute les guéguerres de formatage, on a d’autres chattes à coder.

There are only two hard things in Computer Science: cache invalidation and naming things.

Phil Karlton

Utiliser des bons noms est le geste de documentation le plus important d’un code. Je ne parle pas de bien formater le nom des variables. Pour ça, il y a le PEP8 et ce qu’il recommande tient en 3 lignes :

• Le nom des classes en CamelCase
• Les (pseudo) constantes en UPPER_CASE
• Le reste en snake_case

C’est tout.

Non, je parle de choisir un nom adapté et descriptif.

Le post est long, et vous savez que quand le post est long, je vous mets une musique d’attente.

Explicit is better than implicit

En Python, il n’y a pas de déclaration de type. Le nom d’une variable a donc d’autant plus d’importance pour expliquer ce qu’il y a dedans.

Prenez cet exemple :

best = []
for k, v in data.items():
    if v > top:
        best.append(k)

Quand on lit ce bout de code, on se demande :

• Best ? Mais best en quoi ?
• Que contient data ?
• Quel est la nature de top ?

Maintenant, avec des noms explicites :

best_players = []
for player, score in data.items():
    if score > top_score :
        best_players.append(player)

On comprend tout de suite de quoi il est question. L’algo n’a pas changé, seul le nommage a changé.

Et si on passe à une écriture plus compacte, le gain est encore plus net :

best = [k for k, v in data.items() if k > top]

VS

best_players = [player for player, score in data.items() if score > top_score]

Parfois, on veut la concision, mais faute de nommage, on doit se retourner vers les commentaires :

# Get players with the best scores
best = [k for k, v in data.items() if k > top]

Néanmoins, si on doit faire le choix entre commenter et bien nommer, le nommage doit avoir priorité. Le commentaire est important, mais c’est le dernier recours d’un code qui n’est pas explicite. Avoir un code clair doit être l’objectif premier. Ensuite, seulement, on le commente (abondamment toutefois, faut pas être radin).

Si vous avez suivi, je nomme mes variables en fonction de leur nature, pas leur type. On peut utiliser les règles de l’orthographe pour encore plus de précision, par exemple le pluriel.

fruits = ["kiwi", "banane", 'poire']
for fruit in fruits:
    print(fruit)

J’utilise le pluriel pour une liste de données, qui va donc potentiellement contenir plusieurs fruits. Mais j’utilise un singulier dans la boucle pour le fruit en court.

L’utilisation d’adjectifs est aussi bienvenue :

fruits peut devenir, après un traitement filtered_fruits, indiquant que la liste a subi un filtrage. Les mots en “ed” en anglais aident beaucoup à la qualification.

On évite au maximum les variables courtes. Certains cas sont néanmoins tolérés. Le premier est l’utilisation de i, x, yet z pour des indices.

for i, fruit in enumerate(fruits):
    # faire un truc

Les indices sont quelque chose de tellement courant en informatique qu’on ne va pas se gaver à l’appeler “indice” à chaque fois.

Le second est dans le cadre scientifique. On a souvent des variables pour un algo, des coordonnées, des valeurs géométriques ou mathématiques, qui n’ont pas de dénomination. Dans ce cas, inutile d’essayer d’inventer une nomenclature tordue. Exemple typique, l’algo pour pondre un MD5. Mais il faut compenser par des commentaires, sinon on s’y perd.

Il ne faut pas avoir peur des noms longs. Si, j’ai un jeu de données, que je filtre plusieurs fois, il est de bon ton de distinguer les différents jeux avec des noms détaillés :

sample = range(10)
squares = [x * x for x in sample]
even_squares = [x for x in squares if x % 2 == 0]
even_squares_tail = even_squares[-3:]

Faire des noms de plus de 10 caractères n’est pas sale. On est pas sur un tableau des scores d’une borne d’arcade des années 80.

J’utilise bien entendu des noms en anglais, ce qui est toujours préférable, mais si vous devez en mettre en fr, évitez à tout prix les accents malgré la possibilité de les utiliser en Python 3.

Conventions

Il existe quelques noms qui sont toujours utilisés de la même façon en Python.

self et cls sont les plus connus, en j’en parle déjà dans le dossier sur la POO.

Il y a args et kwargs, qu’on utilise avec l’opérateur splat, dont je parle ici.

Et puis il y en a de plus discrets.

_ est utilisé pour une variable qu’on ignore. Certaines opérations, comme l’unpacking, supposent la création de plusieurs variables. Si on n’est pas intéressé par l’une d’elles, on peut le signaler. Par exemple, l’ORM django permet d’obtenir un objet, et si il n’existe pas, de le créer. Cette fonction retourne un tuble (objet, bool), l’élément indiquant si l’objet a été créé ou non. Si cette information nous intéresse :

user, created = User.objects.get_or_create(username="sam")

Si cette information ne nous intéresse pas :

user, _ = User.objects.get_or_create(username="sam")

Ainsi le lecteur saura qu’il peut ignorer cette variable quand il parcourt le code.

Il y a aussi les alias. On ne peut pas utiliser certains noms comme list ou id qui sont des fonctions existantes en Python.

On s’arrange généralement en trouvant un synonyme, mais si ce n’est pas pratique, on change une lettre. list devient lst (rappelez vous que list est un nom déjà assez pourri, nommez plutôt le contenu), class devient klass, dict devient dct, etc.

Si on ne peut pas le faire, la convention est de rajouter un underscore à la fin du nom : id devient id_, max devient max_… Mais faites l’effort, avant, de chercher un synonyme. Je vois trop souvent des from_/to alors que certains contextes permettent parfaitement de les nommer start/end ou source/destination.

A ne pas confondre avec l’underscore AVANT le nom, qui est une convention pour dire qu’une variable ne fait pas partie de l’API publique.

Ce sont des béquilles, le choix d’un nom judicieux et clair est toujours préférable, mais ce sont des béquilles utiles.

Savoir quand nommer

Au-delà de donner un bon nom, il y a le fait de choisir quand il faut nommer, et quand il faut éviter de le faire.

Si seul le résultat final d’un traitement m’intéresse, alors, il vaut mieux utiliser une seule variable et mettre le nouveau résultat dedans à chaque fois :

fstab = [line.strip() for line in open('/etc/fstab') if line]
fstab = [line.lower() for line in fstab if not line.startswith('#')]
fstab = [line.split()[:3] for line in fstab]

il faut aussi savoir quand ne pas du tout créer une variable :

row = line.strip().split()
for col in row:
    # do something

ici, la variable intermédiaire est inutile :

for col in line.strip().split():
    # do something

L’inverse est aussi vrai :

for col in [int(x) for x in line.strip().split()]:
    # do something

La ligne devient beaucoup trop complexe, et ajouter une variable intermédiaire avec un bon nom va améliorer la lisibilité du programme :

numeric_col = [int(x) for x in line.strip().split()]
for col in numeric_col:
    # do something

On pourrait croire que je précise le type ici en utilisant “numeric”, mais je n’ai pas utilisé integer ou float. J’ai précisé la nature : des colonnes numériques. Il se trouve que pour des données aussi brutes, la nature se rapproche du type.

Si vous êtes du genre à utiliser des lambdas, cela s’applique aussi à vous.

Pour quelque chose de simple, une lambda inline est très lisible :

sorted(scores.items(), key=lambda score: score[1])

Mais pour quelque chose de complexe, une fonction complète est bien plus adaptée :

def calculate_rank(score):
    return sum(goals for sort, goal in score[1] if sort == 'A')

sorted(scores.items(), key=calculate_rank)

Plutôt qu’un horrible :

sorted(scores.items(), key=lambda x: sum(g for s, g in x[1] if s == 'A'))

Pourquoi je parle de lambda alors qu’on est sur du nommage ? Parce qu’une lambda est anonyme, alors qu’une fonction normale a un nom. Et ce nom exprime l’action de la fonction. Il documente.

Habitudes stylistiques

Ces règles là ne sont pas officielles, mais j’ai pu les constater dans nombre de bons codes.

La nom d’une fonction/méthode est aussi important, sinon plus, que le nom d’une variable. Il n’est pas rare que j’écrive des fonctions avec des noms bien dodus comme :

def get_last_downloaded_shemale_vids()

Si on oublie la docstring, on a déjà une bonne idée de ce que cette fonction fait. Cela n’empêche pas de docstringuer quand même pour annoncer des subtilités sur les types, les potentiels side effects, des choses à savoir sur le temps d’exécution, le format, les perfs, etc.

Mais il arrive souvent qu’une fonction ne fasse pas quelque chose d’aussi concret. Prenez par exemple une fonction dont le but est de sluggifier les strings d’une list.

Si la fonction transforme la liste, on va utiliser un verbe dans le nom :

slugify_items(data)

Si par contre la fonction retourne une liste avec les éléments modifiés, on va utiliser le participe passé :

data = slugified_items(data)

C’est subtil, mais la sémantique est différente. Dans le premier cas, on s’attend à un effet de bord. Dans le second cas, on s’attend à une nouvelle liste, ou comme souvent en Python, à un générateur.

Quand on a affaire à une méthode en Python, on utilise rarement le préfixe get_. Personnellement je l’utilise parfois pour des actions complexes, ou des méthodes de classe.

Mais généralement, on préférera utiliser directement le nom de ce qu’on veut récupérer. Exemple :

comments = blog_post.get_comments(spam=False) # NON
comments = blog_post.comments(spam=False) # Oui

Si on n’a pas besoin de passer de paramètre, alors une property est plus appropriée :

comments = blog_post.comments # Ouiiiiiiiiiiiiiii

J’en profite pour faire remarquer qu’il est très classe de prononcer plusieurs fois très vite “sans paramètre, une propriété est plus appropriée”.

Enfin, il arrive qu’on ait besoin de spécifier des rôles techniques et des interactions entre plusieurs bouts de code : hiérarchie, composition, dépendances, etc. Ce sont les choses les plus compliquées à comprendre quand on lit du code : voir le tableau au complet, ce qui lie les différents blocs.

Il ne faut pas hésiter à nommer ses éléments pour cela. Apprendre le nom des design patterns aide beaucoup, mais même si on n’est pas top moumoute niveau vocabulaire, on peut faire des choses aussi simple que :

class BaseAuthenticator(object):
    #...

class PwdAuthenticator(BaseAuthenticator):
    #...

class KeyAuthenticator(BaseAuthenticator):
    #...

Si vous lisez BaseAuthentificator, vous n’avez pas besoin de voir qu’elle est parente d’autres classes plus bas pour savoir que ce n’est probablement pas une classe instanciable, mais sans doute une classe interface ou une classe abstraite. De quoi se faciliter une lecture en diagonale.

FAIL

Voici quelques exemples de noms qui ratent complètement l’objectif de documentation :

def do_query_database():
    # ...

def query_database():
    # ...
    do_query_database()
    # ...

J’en croise dans le code source de Django, et ça me fait hurler. Sérieux ça veut dire quoi ? Qu’est-ce qui a été extrait ? Dans quel but ? On a plus de question APRÈS avoir lu le nom qu’avant, c’est encore pire qu’un mauvais nom, c’est un nom méchant.

Dans ce cas, il faut essayer d’expliquer au maximum ce que l’appendice – qui va me faire choper une péritonite – que vous avez mis de côté fait :

def excute_and_send_query():
    # ...

def query_database():
    # ...
    excute_and_send_query()
    # ...

Un truc également exaspérant, c’est l’usage d’un vocabulaire ambigu :

def make_best_player_list():
    # ...

On sait ce que ça fait, ça fabrique une liste des meilleurs joueurs. Le contexte nous permet d’évaluer le résultat le plus probable. Maintenant un cas beaucoup moins clair :

def make_query():
    # ...

Ca envoie la requête, ça construit la requête ou les deux ? Make est un mot qui peut vouloir dire fabriquer ou exécuter. Ici il vaut mieux utiliser un vocabulaire plus explicite comme :

def build_sql_query():
    # ...

ou

def send_db_query():
    # ...

Là on sait qui fait quoi. Quitte à faire :

def db_query():
    build_sql_query()
    send_db_query()

Et oui, diviser le travail en plusieurs sous unités bien nommées, puis les regrouper dans un bloc plus général est aussi une forme de documentation. Créer des fonctions n’est pas qu’une question de maintenance ou de perf.

Savoir bien nommer les choses vient avec de l’entraînement. Au début, il faut prendre le temps de le faire. Il faut s’arrêter, et se mettre à la place d’un autre dev qui n’a pas encore eu son café.

Allez, détendez-vous, ce blog est plein de code qui ne suit pas les conseils de cet article. Faites juste au mieux ok ?

Ce texte liste les règles stylistiques recommandées, invitant toute la communauté Python à écrire un code de la même façon.

Je vais également y ajouter des éléments de style qui ne sont pas dedans, mais que j’ai pu constater comme étant les choix les plus courants dans les sources que j’ai pu lire.

Espaces

Les opérateurs doivent être entourés d’espaces.

Il faut faire ceci :

variable = 'valeur'

ceci == cela

1 + 2

Et non:

variable='valeur'

ceci==cela

1+2

Il y a deux exceptions notables.

La première étant qu’on groupe les opérateurs mathématiques ayant la priorité la plus haute pour distinguer les groupes :

a = x*2 - 1
b = x*x + y*y
c = (a+b) * (a-b)

La seconde est le signe = dans la déclaration d’arguments et le passage de paramètres :

def fonction(arg='valeur'): #  ça c'est ok
    pass

resultat = fonction(arg='valeur') #  ça aussi

On ne met pas d’espace à l’intérieur des parenthèses, crochets ou accolades.

Oui :

2 * (3 + 4)

def fonction(arg='valeur'):

{str(x): x for x in range(10)}

val = dico['key']

Non :

2 * ( 3 + 4 )

def fonction( arg='valeur' ):

{ str(x): x for x in range(10) }

val = dico[ 'key' ]

On ne met pas d’espace avant les deux points et les virgules, mais après oui.

Oui :

def fonction(arg1='valeur', arg2=None):

dico = {'a': 1}

Non :

def fonction(arg='valeur' , arg2=None) :

dico = {'a' : 1}

Lignes

Une ligne doit se limiter à 79 charactères. Cette limite, héritée des écrans touts petits, est toujours en vigeur car il est plus facile de scanner un code sur une courte colonne qu’en faisant des aller-retours constant.

Si une ligne est trop longue, il existe plusieurs manières de la racourcir :

foo = la_chose_au_nom_si_long_quelle_ne_tient_pas_sur(
          une, 
          carte, 
          de, 
          munchkin)

Ici l’indentation entre le nom de la fonction et des paramètres est légèrement différente pour mettre en avant la distinction.

Une variante :

foo = la_chose_au_nom_si_long_quelle(ne, tient, pas, sur, carte 
                                     une, de, munchkin)

Si c’est un appel chainé, on peut utiliser \ pour mettre à la ligne :

queryset = ModelDjangoALaNoix.objects\
                             .filter(banzai=True)\
                             .exclude(chawarma=False)

Si c’est une structure de données, on peut se la jouer langage fonctionel de la vibes du flex :

chiffres = [
    1, 2, 3,
    4, 5, 6,
]

contacts = {
    'Cleo': (),
    'Ramses': (
        ('maman', '0248163264'),
        ('papa', '01234567890'),
        ('mamie', '55555555'),
        ('momie', '066642424269')
    )
}

Séparer les fonctions et les classes à la racine d’un module par 2 lignes vides. Les méthodes par 1 ligne vide. Parfois je triche et je fais 3 et 2 au lieu de 2 et 1.

Les imports de plusieurs modules doivent être sur plusieurs lignes :

import sys
import os

Et non :

import sys, os

Bien sûr, ce n’est pas valable pour from x import z.

Souvenez-vous qu’on peut utiliser les parenthèses pour diviser de longues lignes. Par exemple :

from minibelt import (dmerge, get, iget, normalize, 
                      chunks, window, skip_duplicates, flatten)

Idem pour les chaînes très longues :

s = ("Les chaînes Python sont automatiquement"
     "concaténées par la VM si elles sont "
     "uniquement séparées par des espaces "
     "ou sauts de lignes.")

Pour en revenir aux lignes d’import, on doit les ordonner ainsi :

• Import de module > import du contenu du module
• Import de la lib standard > import de libs tierces parties > import de votre projet

Exemple :

import os  # import module de la lib standard
import sys # on groupe car même type 

from itertools import islice  # import du contenu du module
from collections import namedtuple # import groupe car même type

import requests # import lib tierce partie
import arrow # on groupe car même type

from django.conf import settings # tierce partie, contenu du module
from django.shortcuts import redirect # on groupe car même type

from mon_projet.mon_module import ma_bite # mon projet

Format du fichier

Indentation : 4 espaces. Pas de tab. C’est tout. Ce n’est pas du PEP8, c’est juste que les codes qui utilisent les tabs sont en (très très très très très très très très) grande minorité dans la communauté Python. Donc faites pas chier. Sinon on vous attend à la sortie de l’école. Tous.

Encoding : UTF8 ou ASCII (ce qui est de l’UTF8 de toute façon).

Docstrings

(c.f. PEP257)

On utilise toujours des triples quotes :

def fonction_avec_docstring_courte():
    """Résumé en une ligne."""
    pass

Si la docstring est longue (elle peut être très très très longue si vous le souhaitez) :

def fonction():
    """Résumé en une ligne suivi d'une line vide.

    Description longue de la fonction qui 
    se termine par une ligne vide puis une
    triple quotes sur sa propre ligne.

    """

Noms de variables

Lettres seules, en minuscule : pour les boucles et les indices.

Exemple :

for x in range(10):
    print(x)

i = get_index() + 12
print(ma_liste[i])

Lettres minuscules + underscores : pour les modules, variables, fonctions et méthodes.

une_variable = 10

def une_fonction():
    return locals() or {}

class UneClasse:
    def une_methode_comme_une_autre(self):
        return globals()

Lettres majuscules + underscores : pour les (pseudo) constantes.

MAX_SIZE = 100000  # à mettre après les imports

Camel case : nom de classe.

class CeciEstUneClasse:
    def methodiquement(self):
        pass

Si le nom contient un acronyme, on fait une entorse à la règle :

class HTMLParserCQFDDDTCCMB:
    def methodiquement(self):
        pass

On n’utilise PAS le mixedCase.

D’abord, les techniques habituelles de substitutions de lettres par leurs codes ASCII sont toujours valables. Le fameux easter egg import this en fait d’ailleurs usage; si vous ouvrez le fichier dont le chemin est contenu dans this.__file__, vous trouverez :

s = """Gur Mra bs Clguba, ol Gvz Crgref

Ornhgvshy vf orggre guna htyl.
Rkcyvpvg vf orggre guna vzcyvpvg.
Fvzcyr vf orggre guna pbzcyrk.
Pbzcyrk vf orggre guna pbzcyvpngrq.
Syng vf orggre guna arfgrq.
Fcnefr vf orggre guna qrafr.
Ernqnovyvgl pbhagf.
Fcrpvny pnfrf nera'g fcrpvny rabhtu gb oernx gur ehyrf.
Nygubhtu cenpgvpnyvgl orngf chevgl.
Reebef fubhyq arire cnff fvyragyl.
Hayrff rkcyvpvgyl fvyraprq.
Va gur snpr bs nzovthvgl, ershfr gur grzcgngvba gb thrff.
Gurer fubhyq or bar-- naq cersrenoyl bayl bar --boivbhf jnl gb qb vg.
Nygubhtu gung jnl znl abg or boivbhf ng svefg hayrff lbh'er Qhgpu.
Abj vf orggre guna arire.
Nygubhtu arire vf bsgra orggre guna *evtug* abj.
Vs gur vzcyrzragngvba vf uneq gb rkcynva, vg'f n onq vqrn.
Vs gur vzcyrzragngvba vf rnfl gb rkcynva, vg znl or n tbbq vqrn.
Anzrfcnprf ner bar ubaxvat terng vqrn -- yrg'f qb zber bs gubfr!"""

d = {}
for c in (65, 97):
    for i in range(26):
        d[chr(i+c)] = chr((i+13) % 26 + c)

print "".join([d.get(c, c) for c in s])

Ensuite, il y a le fait qu’il est possible de spécifier (en Python 2.7, mais plus Python 3), l’encoding du module en ROT13, base64 ou même zip. Au lieux de mettre # -*- coding: utf8 -*-, vous pouvez faire :

# -*- coding: rot13 -*-

cevag h'Fnz rg Znk, cnepr dhr obver frhy rfg zbvaf qebyr dhr pbqre n cyhfvrhef'

Mais au dela de ces petites astuces, il y a bien entendu la véritable offuscation, celle qui utilise des imbrications d’instructions capilotractées avec de multiples niveaux de nesting dans des onliners qui s’étendent sur des kilomètres en incluant des noms de variables alambiqués le tout organisé dans des structures syntaxiques volontairement obscures en détournant des capacités du langage pour en faire une indigeste bouillie immonde dont la lecture provoquera des saignement durant la phrase de vomi. Comme cette phrase.

Généralement ça passe par un usage massif des features que Guido déteste comme les lambdas ou les ;.

Il y a les classiques onliners à base de map / reduce, par exemples les 1000 premiers nombres … premiers :

print filter(None,map(lambda y:y*reduce(lambda x,y:x*y!=0, map(lambda x,y=y:y%x,range(2,int(pow(y,0.5)+1))),1),range(2,1000)))

Ensuite il y a ceux qui aiment se la jouer “mes variables ont des noms de code Fortran” :

print (lambda Ru,Ro,Iu,Io,IM,Sx,Sy:reduce(lambda x,y:x+y,map(lambda y,
Iu=Iu,Io=Io,Ru=Ru,Ro=Ro,Sy=Sy,L=lambda yc,Iu=Iu,Io=Io,Ru=Ru,Ro=Ro,i=IM,
Sx=Sx,Sy=Sy:reduce(lambda x,y:x+y,map(lambda x,xc=Ru,yc=yc,Ru=Ru,Ro=Ro,
i=i,Sx=Sx,F=lambda xc,yc,x,y,k,f=lambda xc,yc,x,y,k,f:(k<=0)or (x*x+y*y
>=4.0) or 1+f(xc,yc,x*x-y*y+xc,2.0*x*y+yc,k-1,f):f(xc,yc,x,y,k,f):chr(
64+F(Ru+x*(Ro-Ru)/Sx,yc,0,0,i)),range(Sx))):L(Iu+y*(Io-Iu)/Sy),range(Sy
))))(-2.1, 0.7, -1.2, 1.2, 30, 80, 24)

Ce qui va afficher cette belle composition de Mandelbrot (si votre terminal fait 80 colonnes de large) :

La génération procédurale : ou comment faire de Zolies choZes avec 1ko de code.

D’ailleurs, pour l’offuscation, on adore les trucs de maths parce que ça donne l’air intelligent et compliqué, et Mandelbrot est un truc très prisé puisqu’avec peu de lignes on peut outputer du Dali Période Guimauve automatiquement :

_                                      =   (
                                        255,
                                      lambda
                               V       ,B,c
                             :c   and Y(V*V+B,B,  c
                               -1)if(abs(V)<6)else
               (              2+c-4*abs(V)**-0.4)/i
                 )  ;v,      x=1500,1000;C=range(v*x
                  );import  struct;P=struct.pack;M,\
            j  ='
Notez cette fois que le code, en plus d'être particulièrement imbuvable, a été gentiment indenté pour ressembler à la figure qu'il va lui même pondre dans le fichier M.bmp que voici :

Mais bien entendu il y a des gens qui arrivent à faire des trucs moches sans entrainement. Par exemple des codeurs JS qui vous font ça:
if "longue chaine".find('chaine') != -1:
Au lieu de :
if 'chaine' in 'longue chaine':
Ou alors les programmeurs C qui font :
for x in range(0, len(ma_list)):
    print ma_list[x]
Alors qu'on a :
for x in ma_list:
    print x
Et au besoin:
for i, x in enumerate(ma_list):
    print i, x
Et à peu près la moitié des programmeurs d'autres langages qui font :
if truc == True:
    if not len(ma_list):
Alors que:
if truc:
     if not ma_list:
Marche très bien.
Je vous passe les isintance() que nous font les programmeurs Java, les check au lieu des gestions des exceptions et les gens qui écrivent les variables en camelCase. Des gens très compétents font du code horrible.
Certains trouvent que le créateur du langage a été un nazi pour avoir forcé les gens à utiliser l'indentation et les sauts de ligne ou pour avoir limité les lambdas. Quand je lis le code de certains, j'ai tendance au contraire à trouver la politique actuelle proche de l'anarchisme hippie. Interdisons les tabs. Les ";" plus de 3 fois d'affilé. Les nombres de saut de ligne qui ne sont pas standard face au PEP8. En fait faisons des syntax errors sur le PEP8. Et les syntaxes errors déclencheront des chocs électriques via le clavier.
Et on enverra tous ceux qui sont pas d'accord dans des camps d’entraînement pour qu'ils puissent tous se concentrer un peu plus sur leur code.
Sinon à quoi ça sert d'être un BDFL ?
]]>
			http://sametmax.com/obfuscating-python/feed/
		16
	4381	
		
		
		http://sametmax.com/typeerror-error-when-calling-the-metaclass-bases-function-argument-1-must-be-code-not-str/
		http://sametmax.com/typeerror-error-when-calling-the-metaclass-bases-function-argument-1-must-be-code-not-str/#comments
		Wed, 16 Jan 2013 12:16:23 +0000
		
				
		
		
		
		
		

		http://sametmax.com/?p=4150
		
				Cette erreur est souvent déclenchée quand on essaye d’hériter d’une fonction au lieu d’une classe. Cela peut arriver par erreur avec des fonctions qui sont nommées en CamelCase, en dépit du PEP8.

Par exemple:
class Truc(threading.Condition):
    pass

class Machine(tempfile.NamedTemporaryFile):
    pass
Lèveront l’exception :
TypeError: Error when calling the metaclass bases 
    function() argument 1 must be code, not str
Car:
>>> import threading, tempfile
>>> type(threading.Condition)

>>> type(tempfile.NamedTemporaryFile)

Malgré leurs noms en majuscule.
Le message d’erreur est lui-même complètement obscure. Bref, le genre de truc qui est 100% lié à des erreurs d’autres personnes que vous aller payer par une après-midi de debug si on ne vous donne pas la solution. 
Mais bon, la queue de celui qui n’a jamais pourri l’après-midi d’un autre codeur avec son travail merdique jette le premier parpaing.
]]>
			http://sametmax.com/typeerror-error-when-calling-the-metaclass-bases-function-argument-1-must-be-code-not-str/feed/
		7
	4150