Écrire un script Python durable

Vincent Bernat

Py­thon est un ex­cellent lan­gage pour écrire ra­pi­de­ment un script entre une di­zaine et quelques cen­taines de lignes de code. Une fois ter­miné, vous pou­vez l’ou­blier et vous concen­trer sur votre pro­chaine mission.

Six mois plus tard, un col­lègue vous de­mande pour­quoi ce script échoue et vous n’en avez au­cune idée : pas de do­cu­men­ta­tion, pa­ra­mètres co­dés en dur, au­cune trace pen­dant l’exé­cu­tion et au­cuns tests pour vous éclairer.

Trans­for­mer un script Py­thon « vite fait » en une ver­sion du­rable, fa­cile à uti­li­ser, à com­prendre et à mo­di­fier par vos col­lègues et votre fu­tur al­ter ego, ne de­mande qu’un ef­fort mo­déré. À titre d’illus­tra­tion, com­men­çons par le script sui­vant pour ré­soudre le test clas­sique « Fizz-Buzz » :

import sys
for n in range(int(sys.argv[1]), int(sys.argv[2])):
    if n % 3 == 0 and n % 5 == 0:
        print("fizzbuzz")
    elif n % 3 == 0:
        print("fizz")
    elif n % 5 == 0:
        print("buzz")
    else:
        print(n)

Documentation#

Je trouve utile d’écrire de la do­cu­men­ta­tion avant même d’écrire la pre­mière ligne de code : cela fa­ci­lite la concep­tion et m’as­sure de ne pas re­por­ter cette tâche in­dé­fi­ni­ment. La do­cu­men­ta­tion peut être pla­cée en haut du script1 :

#!/usr/bin/env python3

"""Simple fizzbuzz generator.

This script prints out a sequence of numbers from a provided range
with the following restrictions:

 - if the number is divisble by 3, then print out "fizz,"
 - if the number is divisible by 5, then print out "buzz,"
 - if the number is divisible by 3 and 5, then print out "fizzbuzz."
"""

La pre­mière ligne est un bref ré­sumé du but du script. Les autres pa­ra­graphes contiennent des dé­tails sup­plé­men­taires sur son action.

Arguments en ligne de commande#

La deuxième étape consiste à trans­for­mer les pa­ra­mètres co­dés en dur en va­leurs do­cu­men­tées et confi­gu­rables à l’aide d’ar­gu­ments en ligne de com­mande, via le mo­dule argparse. Dans notre exemple, nous de­man­dons à l’uti­li­sa­teur de spé­ci­fier une plage et nous lui per­met­tons de mo­di­fier les va­leurs mo­dulo pour « fizz » et « buzz ».

import argparse
import sys


class CustomFormatter(argparse.RawDescriptionHelpFormatter,
                      argparse.ArgumentDefaultsHelpFormatter):
    pass


def parse_args(args=sys.argv[1:]):
    """Parse arguments."""
    parser = argparse.ArgumentParser(
        description=sys.modules[__name__].__doc__,
        formatter_class=CustomFormatter)

    g = parser.add_argument_group("fizzbuzz settings")
    g.add_argument("--fizz", metavar="N",
                   default=3,
                   type=int,
                   help="Modulo value for fizz")
    g.add_argument("--buzz", metavar="N",
                   default=5,
                   type=int,
                   help="Modulo value for buzz")

    parser.add_argument("start", type=int, help="Start value")
    parser.add_argument("end", type=int, help="End value")

    return parser.parse_args(args)


options = parse_args()
for n in range(options.start, options.end + 1):
    # ...

La va­leur ajou­tée de cette mo­di­fi­ca­tion est consi­dé­rable : les pa­ra­mètres sont main­te­nant cor­rec­te­ment do­cu­men­tés et peuvent être dé­cou­verts grâce à l’op­tion --help. De plus, la do­cu­men­ta­tion que nous avons écrite dans la sec­tion pré­cé­dente est éga­le­ment affichée :

$ ./fizzbuzz.py --help
usage: fizzbuzz.py [-h] [--fizz N] [--buzz N] start end

Simple fizzbuzz generator.

This script prints out a sequence of numbers from a provided range
with the following restrictions:

 - if the number is divisble by 3, then print out "fizz,"
 - if the number is divisible by 5, then print out "buzz,"
 - if the number is divisible by 3 and 5, then print out "fizzbuzz."

positional arguments:
  start         Start value
  end           End value

optional arguments:
  -h, --help    show this help message and exit

fizzbuzz settings:
  --fizz N      Modulo value for fizz (default: 3)
  --buzz N      Modulo value for buzz (default: 5)

Le mo­dule argparse est as­sez puis­sant. S’il ne vous est pas fa­mi­lier, un sur­vol de sa do­cu­men­ta­tion est utile. J’aime par­ti­cu­liè­re­ment la pos­si­bi­lité de dé­fi­nir des sous-com­mandes et de grou­per des options.

Traces#

La troi­sième étape est d’af­fi­cher des in­for­ma­tions du­rant l’exé­cu­tion. Le mo­dule logging convient par­fai­te­ment à cet ef­fet. Tout d’abord, nous dé­fi­nis­sons le « logger » :

import logging
import logging.handlers
import os
import sys

logger = logging.getLogger(os.path.splitext(os.path.basename(sys.argv[0]))[0])

En­suite, nous ren­dons sa ver­bo­sité confi­gu­rable : logger.​debug() ne de­vrait af­fi­cher quelque chose que lorsqu’un uti­li­sa­teur uti­lise le dra­peau --debug. --silent de­vrait cou­per les traces sauf si une condi­tion ex­cep­tion­nelle se pro­duit. Pour cela, nous ajou­tons le code sui­vant dans parse_args() :

# In parse_args()
g = parser.add_mutually_exclusive_group()
g.add_argument("--debug", "-d", action="store_true",
               default=False,
               help="enable debugging")
g.add_argument("--silent", "-s", action="store_true",
               default=False,
               help="don't log to console")

Cette fonc­tion per­met alors de confi­gu­rer les traces :

def setup_logging(options):
    """Configure logging."""
    root = logging.getLogger("")
    root.setLevel(logging.WARNING)
    logger.setLevel(options.debug and logging.DEBUG or logging.INFO)
    if not options.silent:
        ch = logging.StreamHandler()
        ch.setFormatter(logging.Formatter(
            "%(levelname)s[%(name)s] %(message)s"))
        root.addHandler(ch)

Le corps de notre script de­vient ceci :

if __name__ == "__main__":
    options = parse_args()
    setup_logging(options)

    try:
        logger.debug("compute fizzbuzz from {} to {}".format(options.start,
                                                             options.end))
        for n in range(options.start, options.end + 1):
            # ...
    except Exception as e:
        logger.exception("%s", e)
        sys.exit(1)
    sys.exit(0)

Si le script peut être exé­cuté non in­ter­ac­ti­ve­ment, par exemple de­puis une cron­tab, il est pos­sible d’en­voyer les traces vers syslog2 :

def setup_logging(options):
    """Configure logging."""
    root = logging.getLogger("")
    root.setLevel(logging.WARNING)
    logger.setLevel(options.debug and logging.DEBUG or logging.INFO)
    if not options.silent:
        if not sys.stderr.isatty():
            facility = logging.handlers.SysLogHandler.LOG_DAEMON
            sh = logging.handlers.SysLogHandler(address='/dev/log',
                                                facility=facility)
            sh.setFormatter(logging.Formatter(
                "{0}[{1}]: %(message)s".format(
                    logger.name, os.getpid())))
            root.addHandler(sh)
        else:
            ch = logging.StreamHandler()
            ch.setFormatter(logging.Formatter(
                "%(levelname)s[%(name)s] %(message)s"))
            root.addHandler(ch)

Pour cet exemple, cela re­pré­sente beau­coup de code pour un seul ap­pel à logger.​debug(), mais en si­tua­tion réelle, cela est très utile pour ai­der un uti­li­sa­teur à com­prendre le dé­rou­le­ment du script.

$ ./fizzbuzz.py --debug 1 3
DEBUG[fizzbuzz] compute fizzbuzz from 1 to 3
1
2
fizz

Tests#

Les tests uni­taires sont très utiles pour s’as­su­rer qu’une ap­pli­ca­tion se com­porte comme prévu. Il n’est pas cou­rant de les uti­li­ser dans des scripts, mais en écrire quelques-uns amé­liore gran­de­ment la qua­lité. Trans­for­mons le code contenu dans la boucle en une fonc­tion avec quelques exemples in­ter­ac­tifs d’uti­li­sa­tion dans sa do­cu­mentation :

def fizzbuzz(n, fizz, buzz):
    """Compute fizzbuzz nth item given modulo values for fizz and buzz.

    >>> fizzbuzz(5, fizz=3, buzz=5)
    'buzz'
    >>> fizzbuzz(3, fizz=3, buzz=5)
    'fizz'
    >>> fizzbuzz(15, fizz=3, buzz=5)
    'fizzbuzz'
    >>> fizzbuzz(4, fizz=3, buzz=5)
    4
    >>> fizzbuzz(4, fizz=4, buzz=6)
    'fizz'

    """
    if n % fizz == 0 and n % buzz == 0:
        return "fizzbuzz"
    if n % fizz == 0:
        return "fizz"
    if n % buzz == 0:
        return "buzz"
    return n

py­test per­met de s’as­su­rer que les ré­sul­tats sont corrects3 :

$ python3 -m pytest -v --log-level=debug --doctest-modules ./fizzbuzz.py
============================ test session starts =============================
platform linux -- Python 3.7.4, pytest-3.10.1, py-1.8.0, pluggy-0.8.0 -- /usr/bin/python3
cachedir: .pytest_cache
rootdir: /home/bernat/code/perso/python-script, inifile:
plugins: xdist-1.26.1, timeout-1.3.3, forked-1.0.2, cov-2.6.0
collected 1 item

fizzbuzz.py::fizzbuzz.fizzbuzz PASSED                                  [100%]

========================== 1 passed in 0.05 seconds ==========================

En cas d’er­reur, py­test af­fiche un mes­sage dé­cri­vant la lo­ca­li­sa­tion et la na­ture du problème :

$ python3 -m pytest -v --log-level=debug --doctest-modules ./fizzbuzz.py -k fizzbuzz.fizzbuzz
============================ test session starts =============================
platform linux -- Python 3.7.4, pytest-3.10.1, py-1.8.0, pluggy-0.8.0 -- /usr/bin/python3
cachedir: .pytest_cache
rootdir: /home/bernat/code/perso/python-script, inifile:
plugins: xdist-1.26.1, timeout-1.3.3, forked-1.0.2, cov-2.6.0
collected 1 item

fizzbuzz.py::fizzbuzz.fizzbuzz FAILED                                  [100%]

================================== FAILURES ==================================
________________________ [doctest] fizzbuzz.fizzbuzz _________________________
100
101     >>> fizzbuzz(5, fizz=3, buzz=5)
102     'buzz'
103     >>> fizzbuzz(3, fizz=3, buzz=5)
104     'fizz'
105     >>> fizzbuzz(15, fizz=3, buzz=5)
106     'fizzbuzz'
107     >>> fizzbuzz(4, fizz=3, buzz=5)
108     4
109     >>> fizzbuzz(4, fizz=4, buzz=6)
Expected:
    fizz
Got:
    4

/home/bernat/code/perso/python-script/fizzbuzz.py:109: DocTestFailure
========================== 1 failed in 0.02 seconds ==========================

Nous pou­vons éga­le­ment écrire des tests uni­taires sous forme de code. Sup­po­sons que nous vou­lions tes­ter la fonc­tion suivante :

def main(options):
    """Compute a fizzbuzz set of strings and return them as an array."""
    logger.debug("compute fizzbuzz from {} to {}".format(options.start,
                                                         options.end))
    return [str(fizzbuzz(i, options.fizz, options.buzz))
            for i in range(options.start, options.end+1)]

À la fin du script4, nous ajou­tons quelques tests uni­taires uti­li­sant les tests pa­ra­mé­trés de pytest :

# Unit tests
import pytest                   # noqa: E402
import shlex                    # noqa: E402


@pytest.mark.parametrize("args, expected", [
    ("0 0", ["fizzbuzz"]),
    ("3 5", ["fizz", "4", "buzz"]),
    ("9 12", ["fizz", "buzz", "11", "fizz"]),
    ("14 17", ["14", "fizzbuzz", "16", "17"]),
    ("14 17 --fizz=2", ["fizz", "buzz", "fizz", "17"]),
    ("17 20 --buzz=10", ["17", "fizz", "19", "buzz"]),
])
def test_main(args, expected):
    options = parse_args(shlex.split(args))
    assert main(options) == expected

La fonc­tion de test s’exé­cute une fois pour cha­cun des pa­ra­mètres four­nis. La par­tie args est uti­li­sée comme en­trée pour la fonc­tion parse_​args() afin d’ob­te­nir les op­tions à pas­ser à la fonc­tion main(). La par­tie expected est com­pa­rée au ré­sul­tat de la fonc­tion main(). Quand tout fonc­tionne comme prévu, py­test affiche :

python3 -m pytest -v --log-level=debug --doctest-modules ./fizzbuzz.py
============================ test session starts =============================
platform linux -- Python 3.7.4, pytest-3.10.1, py-1.8.0, pluggy-0.8.0 -- /usr/bin/python3
cachedir: .pytest_cache
rootdir: /home/bernat/code/perso/python-script, inifile:
plugins: xdist-1.26.1, timeout-1.3.3, forked-1.0.2, cov-2.6.0
collected 7 items

fizzbuzz.py::fizzbuzz.fizzbuzz PASSED                                  [ 14%]
fizzbuzz.py::test_main[0 0-expected0] PASSED                           [ 28%]
fizzbuzz.py::test_main[3 5-expected1] PASSED                           [ 42%]
fizzbuzz.py::test_main[9 12-expected2] PASSED                          [ 57%]
fizzbuzz.py::test_main[14 17-expected3] PASSED                         [ 71%]
fizzbuzz.py::test_main[14 17 --fizz=2-expected4] PASSED                [ 85%]
fizzbuzz.py::test_main[17 20 --buzz=10-expected5] PASSED               [100%]

========================== 7 passed in 0.03 seconds ==========================

Quand une er­reur sur­vient, py­test four­nit une éva­lua­tion de la si­tuation :

$ python3 -m pytest -v --log-level=debug --doctest-modules ./fizzbuzz.py
[…]
================================== FAILURES ==================================
__________________________ test_main[0 0-expected0] __________________________

args = '0 0', expected = ['0']

    @pytest.mark.parametrize("args, expected", [
        ("0 0", ["0"]),
        ("3 5", ["fizz", "4", "buzz"]),
        ("9 12", ["fizz", "buzz", "11", "fizz"]),
        ("14 17", ["14", "fizzbuzz", "16", "17"]),
        ("14 17 --fizz=2", ["fizz", "buzz", "fizz", "17"]),
        ("17 20 --buzz=10", ["17", "fizz", "19", "buzz"]),
    ])
    def test_main(args, expected):
        options = parse_args(shlex.split(args))
>       assert main(options) == expected
E       AssertionError: assert ['fizzbuzz'] == ['0']
E         At index 0 diff: 'fizzbuzz' != '0'
E         Full diff:
E         - ['fizzbuzz']
E         + ['0']

fizzbuzz.py:160: AssertionError
----------------------------- Captured log call ------------------------------
fizzbuzz.py                125 DEBUG    compute fizzbuzz from 0 to 0
===================== 1 failed, 6 passed in 0.05 seconds =====================

L’ap­pel à logger.​debug() est in­clus dans la sor­tie. C’est une autre bonne rai­son d’émettre des traces ! Si vous vou­lez en sa­voir plus sur les fonc­tion­na­li­tés de py­test, je­tez un coup d’œil sur « Test d’un ap­pli­ca­tif ré­seau avec py­test et les es­paces de noms Linux ».


En ré­sumé, les quatre mo­di­fi­ca­tions à ap­por­ter pour rendre un script Py­thon plus du­rable sont :

  1. ajou­ter de la do­cu­men­ta­tion en haut du script,
  2. uti­li­ser le mo­dule argparse pour do­cu­men­ter les dif­fé­rents pa­ramètres,
  3. uti­li­ser le mo­dule logging pour en­re­gis­trer les dé­tails sur l’exécution,
  4. ajou­ter quelques tests unitaires.

L’exemple com­plet est dis­po­nible sur GitHub et peut être uti­lisé comme modèle !

Mise à jour (06.2019)

Cet ar­ticle a été briè­ve­ment dis­cuté sur Lobs­ters et Red­dit. L’ajout de do­cu­men­ta­tion et des ar­gu­ments en ligne de com­mande semble bien ac­cueilli, mais les traces et les tests sont par­fois ju­gés trop ver­beux. Dan Connolly a écrit « Prac­ti­cal pro­duc­tion py­thon scripts » en ré­ponse à cet article.