Specifications

Abstraction

Pour utiliser (appeler) une fonction, on n'a pas besoin de comprendre comment la fonction calcule son résultat, seulement de savoir quel résultat elle retourne et quels sont ses paramètres.

Celà permet d'effectuer simplement des calculs très compliqués par le biais de fonctions ecrites par d'autres programmeurs.

Python fournis un certain nombre de fonction sous forme de modules. Pour utiliser de telles fonctions, on doit dire à Python de les importer, avec la syntaxe suivante :

SyntaxeExemple

from nom_module import nom_fonction

Où nom_module est le nom d'un module, et nom_fonction le nom d'une fonction de ce module

Le module random fournit des fonctions qui permettent de générer des valeurs pseudo aléatoires¹. Entre autres, la fonction randint qui permet de générer un entier aléatoire entre une petite valeur (incluse) et une grande valeur (exclue).

from random import randint

Ecrivez l'exemple ci-dessus dans la partie éditeur, executez le script, et calculez la valeur de l'expression suivante plusieurs fois à l'aide de la console Python :

>>> randint(1, 6)

Cet appel retourne un entier aléatoire entre 1 et 6!

Vous devriez voir le résultat changer à chaque appel ou presque, par exemple :

>>> randint(1, 6)
5
>>> randint(1, 6)
1
>>> randint(1, 6)
3
>>> randint(1, 6)
6

Vous avez utilisé la fonction randint, et pourtant, vous n'avez aucune idée de comment elle produit son résultat. Son fonctionnement dépasse même largement le cadre d'un cours de math de seconde ! Ce mécanisme est ce qu'on appelle une abstraction, c'est à dire que l'on ne garde que ce qui nous intéresse (le résultat), et qu'on n'a pas besoin de s'intéresser au reste (la méthode pour obtenir le résultat).

l'abstraction est une notion centrale en programmation. Toutefois, dans ce cours, nous ne travailleront quasiment qu'avec des abstractions à l'aide de fonctions.

docstrings

Parfois, le nom d'une fonction et le nom de ses paramètres est insuffisant pour exprimer précisément ce que la fonction calcule, ou comment bien l'utiliser. Dans ce cas là, Python nous propose d'ajouter une docstring. C'est une chaîne de caractères un peu spéciale qu'on met juste sous la ligne def d'une fonction quand on la définit, et qui permet d'expliquer en français (ou en anglais) ce que la fonction fait.

SyntaxeExemple

def nom_fonction(parametres):
    """la docstring
    """
    return ici_du_code

La fonction randint pourrait avoir une docstring ressemblant à :

def randint(min, max):
    """retourne un entier pseudo aléatoire entre min (inclus) et max (inclus)
    min doit être strictement inférieur à max
    """

Exercice

EnoncéAideSolution

Proposez une docstring pour la fonction irradiance que nous avons défini au chapitre précédent.

Quelques précisions à donner : - r est en millions de kms - C'est l'irradiance solaire

Ce n'est pas la seule solution possible. En cas de doute, demandez au professeur de vérifier la vôtre.

def irradiance(r):
    """Calcule la valeur de l'irradiance solaire en watts par mètres carrés, 
    r est la distance au soleil, en millions de kilomètres
    """
    return (5535.8/r)**2

Extension (math/physique)Solution

Cette extension est facultative, a faire uniquement si vous cherchez un peu de défi ou aimez les maths et la physique.

Si on passe certaines valeurs comme paramètre r, la fonction risque de renvoyer une valeur erronnée. Précisez ces restrictions dans la docstring.

r est utilisée comme diviseur, il ne peut donc mathématiquement pas être zéro, sans quoi le calcul n'a aucun sens (on ne divise pas par zéro).
r est une distance. Or, une distance négative fait rarement sens, on veut donc préciser que cette distance est toujours positive.

def irradiance(r):
    """Calcule la valeur de l'irradiance solaire en watts par mètres carrés, 
    r est la distance au soleil, en millions de kilomètres
    r doit être strictement supérieur à 0
    """
    return (5535.8/r)**2

La docstring, le nom d'une fonction et le nom de ses paramètres constituent la spécification d'une fonction. La spécification est simplement l'explication de ce que la fonction fait, sans expliquer comment elle le fait. Le code de la fonction, qui est en quelques sortes l'opposé de la spécification, s'appelle alors l'implémentation. La spécification est plus simple à lire que le code, et permet l'usage d'une fonction même si on n'en comprends pas le code.

Remarque

Dans ce cours, la spécification d'une fonction se limitera aux trois éléments mentionnés plus haut. Dans la pratique elle peut prendre de nombreuses formes : ce peut être un texte en français à part du code, des schémas, des images, un texte dans un langage spécial, ...

Tests

Souvent, quand on écrit la spécification d'une fonction, on veut vérifier que son implémentation corresponds. Pour ça, on va souvent écrire des tests automatiques. Le principe est d'écrire des sortes de petits programmes qui vont tester si une fonction marche, et on va donc laisser l'ordinateur faire le test.

Il existe de nombreux outils pour tester des fonctions en Python. Nous allons utiliser la plus directe, les doctests. C'est un module qui permet d'écrire dans la docstring du code comme si on l'écrivait en console, et aussi l'affichage correspondant, et le module executera les exemples automatiquement et vérifiera leur sortie.

SyntaxeExemple

Se met dans la docstring, séparé du dessus et dessous par des lignes vides.

"""
>>> expression 1
resultat attendu 1

>>> expression 2
resultat attendu 2
"""

Chaque bloc expression - attendu est un test.

def carre(x):
    """ x int ou float
    retourne le carré de x

    >>> carre(4)
    16

    >>> carre(-10)
    100

    >>> carre(0)
    0
    """
    return x * x

Pour activer les tests automatiques, copiez-collez l'exemple précédent dans la partie éditeur et ajoutez les lignes suivantes en bas :

if __name__ == "__main__":
    import doctest
    doctest.testmod()

Nous verrons plus loin dans le cours ce qu'elles veulent dire. Executez. Et ... rien ne se passe...

C'est normal : la fonction carre est correcte, et donc elle passe tous les tests.

Un test pour une fonction est généralement très simple. On donne des valeurs à la fonction, et on vérifie que le résultat est le bon.

Modifions-la pour la "casser":

Changez la ligne

return x*x

en

return x

Re-executez. Vous devriez voir apparaître le rapport de tests:

**********************************************************************
File "__main__", line 5, in __main__.carre
Failed example:
    carre(4)
Expected:
    16
Got:
    4
**********************************************************************
File "__main__", line 8, in __main__.carre
Failed example:
    carre(-10)
Expected:
    100
Got:
    -10
**********************************************************************
1 items had failures:
   2 of   3 in __main__.carre
***Test Failed*** 2 failures.

Les lignes 18, 19 et 20 sont un résumé :

18
19
20

1 items had failures:
   2 of   3 in __main__.carre
***Test Failed*** 2 failures.

Qui nous apprends que 2 tests sur 3 ont échoués.

Les blocs au dessus, séparés par des lignes de *, sont chacun un rapport d'échec d'un test. Par exemple :

File "__main__", line 6, in __main__.carre
Failed example:
    carre(4)
Expected:
    16
Got:oo
    4

Etudions ce rapport :

2	`File "__main__", line 5, in __main__.carre`

Indique que le test qui a échoué est ligne 5 du fichier.

3 4	`Failed example: carre(4)`

Rappelle l'expression qui a été testée. Ici, carre(4).

5 6	`Expected: 16`

Rappelle la valeur que l'on attendait de l'appel de la fonction. Ici, 16.

7
8

Got:
    4

Rappelle la valeur réellement obtenu. Ici, 4.

Ecrire un test pour une fonction est simple. On l'appelle avec des valeurs choisies, et on vérifie que la valeur retournée est la bonne.

Exercice

EnoncéSolution

Ecrivez quelques doctests pour la fonction suivante, puis executez-les. Modifiez la fonction de manière à faire rater les tests :

def addition(a,b):
    """a et b deux entiers
    retourne a + b
    """
    return a + b

Si vous n'avez pas tous les cas de tests ci dessous, pas de panique, l'important est d'avoir écrit quelques tests.

def addition(a,b):
    """a et b deux entiers
    retourne a + b

    >>> addition(10,20)
    30

    >>> addition(-1, -2)
    -3

    >>> addition(55, -49)
    6

    >>> addition(49, -55)
    -6

    >>> addition(49, 0)
    49

    >>> addition(77, -77)
    0
    """
    return a + b

On peut écrire les tests à deux moments :

Après avoir implémenté la fonction et vérifié manuellement qu'elle est correcte. On peut alors copier-coller directement des lignes de la console Python. Les tests serviront alors à vérifier que la fonction ne sera pas "cassée" par des modifications future.
Avant d'implémentater la fonction. Les tests sont alors plus compliqués à écrire, puisqu'il faut faire les calculs à la main, mais ils serviront aussi à vérifier que la fonction a été bien implémentée.

Exercice

EnoncéSolution

Ecrivez quelques tests pour la fonction irradiance.

def irradiance(r):
    """Calcule la valeur de l'irradiance solaire en watts par mètres carrés, 
    r est la distance au soleil, en millions de kilomètres

    >>> irradiance(20)
    76612.70410000002

    >>> irradiance(150)
    1362.0036284444443

    >>> irradiance(120)
    2128.1306694444447

    >>> irradiance(0.5)
    122580326.56
    """
    return (5535.8/r)**2

On parle de pseudo aleatoire, parce que les valeurs générées ressemblent à des valeurs aléatoires, mais ne le sont pas à proprement parler. ↩