Plongez au coeur de Python ,De débutant à expert

Si vous ne l'avez pas déjà fait,vous pouvez télécharger cet exemple ainsi que les autres exemples du livre.

def info(object, spacing=10, collapse=1): ***1*** ***2*** ***3***
    """Print methods and doc strings.
    
    Takes module, class, list, dictionary, or string."""
    methodList = [method for method in dir(object) if callable(getattr(object, method))]
    processFunc = collapse and (lambda s: " ".join(s.split())) or (lambda s: s)
    print "\n".join(["%s %s" %
                      (method.ljust(spacing),
                       processFunc(str(getattr(object, method).__doc__)))
                     for method in methodList])

if __name__ == "__main__":                ***4*** ***5***
    print info.__doc__

***1*** Ce module a une fonction, info. Selon sa déclaration de fonction, elle prend trois paramètres : object, spacing et collapse. Les deux derniers sont en fait des paramètres optionnels comme nous le verrons bientôt.
***2*** La fonction info a une doc string multi-lignes qui décrit succintement son usage. Notez qu'aucune valeur de retour n'est mentionnée, cette fonction sera employée uniquement pour son effet, pas sa valeur.
***3*** Le code à l'interieur de la fonction est indenté.
***4*** L'astuce if __name__ permet à ce programme de faire quelque chose d'utile lorsqu'il est exécuté tout seul sans intérférence avec son usage comme module pour d'autres programmes. Dans ce cas, le programme affiche simplement la doc string de la fonction info.
***5*** L'instruction if utilise == pour la comparaison et ne nécessite pas de parenthèses.

La fonction info est conçue pour être utilisée par vous, le programmeur, lorsque vous travaillez dans l'IDE Python. Elle prend n'importe quel objet qui a des fonctions ou des méthodes (comme un module, qui a des fonction, ou une liste, qui a des méthodes) et affiche les fonctions et leur doc string.

>>> from apihelper import info
>>> li = []
>>> info(li)
append     L.append(object) -- append object to end
count      L.count(value) -> integer -- return number of occurrences of value
extend     L.extend(list) -- extend list by appending list elements
index      L.index(value) -> integer -- return index of first occurrence of value
insert     L.insert(index, object) -- insert object before index
pop        L.pop([index]) -> item -- remove and return item at index (default last)
remove     L.remove(value) -- remove first occurrence of value
reverse    L.reverse() -- reverse *IN PLACE*
sort       L.sort([cmpfunc]) -- sort *IN PLACE*; if given, cmpfunc(x, y) -> -1, 0, 1

Par défaut, la sortie est formatée pour être facilement lisible. Les doc string multi-lignes sont combinées en une seule longue ligne, mais cette option peut être changée en spécifiant 0 pour l'argument collapse. Si les noms de fonction font plus de 10 caractères, vous pouvez spécifier une valeur plus grande pour l'argument spacing, pour faciliter la lecture.

info(odbchelper)                	***1***    
info(odbchelper, 12)            	***2***    
info(odbchelper, collapse=0)    	***3***    
info(spacing=15, object=odbchelper)	***4***

***1*** Avec un seul argument, spacing prend pour valeur 10 et collapse 1. ***2*** Avec deux arguments, collapse prend pour valeur 1. ***3*** Ici, vous nommez l'argument collapse explicitement et spécifiez sa valeur. spacing prend la valeur par défaut 10. ***4*** Les arguments obligatoires (comme object, qui n'a pas de valeurs par défaut) peuvent aussi être nommés et les arguments nommés peuvent apparaître dans n'importe quel ordre.

Cela a l'air confus jusqu'à que vous réalisiez que les arguments sont tout simplement un dictionnaire. La manière «normale» d'appeler les fonctions sans le nom des arguments est en fait un raccourci dans lequel Python fait correspondre les valeurs avec le nom des arguments dans l'ordre dans lequel ils sont spécifiés par la déclaration de fonction. Dans la plupart des cas, vous appellerez le fonctions de la manière «normale», mais vous aurez toujours cette souplesse pour les autres cas.

La seule chose que vous avez à faire pour appeler une fonction est de spécifier une valeur (d'une manière ou d'une autre) pour chaque argument obligatoire, la manière et l'ordre dans lequel vous le faites ne dépendent que de vous.

Pour en savoir plus

• Le Python Tutorial traite de manière précise de quand et comment les arguments par défaut sont évalués, ce qui est important lorsque la valeur par défaut est une liste ou une expression ayant un effet de bord.

La fonction type retourne le type de données d'un objet quelconque. Les types possibles sont répertoriés dans le module types. C'est utile pour les fonctions capables de gérer plusieurs types de données.

Exemple 4.5. Présentation de type▲

>>> type(1)           ***1***
<type 'int'>
>>> li = []
>>> type(li)          ***2***
<type 'list'>
>>> import odbchelper
>>> type(odbchelper)  ***3***
<type 'module'>
>>> import types      ***4***
>>> type(odbchelper) == types.ModuleType
True

La fonction str convertit des données en chaîne. Tous les types de données peuvent être convertis en chaîne.

Exemple 4.6. Présentation de str▲

>>> str(1)          ***1***
'1'
>>> horsemen = ['war', 'pestilence', 'famine']
>>> horsemen
['war', 'pestilence', 'famine']
>>> horsemen.append('Powerbuilder')
>>> str(horsemen)   ***2***
"['war', 'pestilence', 'famine', 'Powerbuilder']"
>>> str(odbchelper) ***3***
"<module 'odbchelper' from 'c:\\docbook\\dip\\py\\odbchelper.py'>"
>>> str(None)       ***4***
'None'

Exemple 4.7. Introducing dir▲

>>> li = []
>>> dir(li)           ***1***
['append', 'count', 'extend', 'index', 'insert',
'pop', 'remove', 'reverse', 'sort']
>>> d = {}
>>> dir(d)           ***2***
['clear', 'copy', 'get', 'has_key', 'items', 'keys', 'setdefault', 'update', 'values']
>>> import odbchelper
>>> dir(odbchelper)   ***3***
['__builtins__', '__doc__', '__file__', '__name__', 'buildConnectionString']

Exemple 4.8. Présentation de callable▲

>>> import string
>>> string.punctuation           ***1***
'!"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~'
>>> string.join                  ***2***
<function join at 00C55A7C>
>>> callable(string.punctuation) ***3***
False
>>> callable(string.join)        ***4***
True
>>> print string.join.__doc__    ***5***
join(list [,sep]) -> string

    Return a string composed of the words in list, with
    intervening occurrences of sep.  The default separator is a
    single space.

    (joinfields and join are synonymous)

type, str, dir et toutes les autres fonctions prédéfinies de Python sont regroupés dans un module spécial appelé __builtin__. (Il y a deux caractères de soulignement avant et deux après.) Pour vous aider, vous pouvez imaginer que Python exécute automatiquement from __builtin__ import * au démarrage, ce qui importe toutes les fonctions prédéfinies (built-in) dans l'espace de noms pour que vous puissiez les utiliser directement.

L'avantage d'y penser de cette manière est que vous pouvez accéder à toutes les fonctions et attributs prédéfinis de manière groupée en obtenant des informations sur le module __builtin__. Et devinez quoi, nous avons une fonction pour ça, elle s'appelle info. Essayez vous-même et parcourez la liste maintenant, nous examinerons certaines des fonctions les plus importantes plus tard (certaines des classes d'erreur prédéfinies, comme AttributeError, devraient avoir l'air familier).

Exemple 4.9. Attributs et fonctions prédéfinis▲

>>> from apihelper import info
>>> import __builtin__
>>> info(__builtin__, 20)
ArithmeticError      Base class for arithmetic errors.
AssertionError       Assertion failed.
AttributeError       Attribute not found.
EOFError             Read beyond end of file.
EnvironmentError     Base class for I/O related errors.
Exception            Common base class for all exceptions.
FloatingPointError   Floating point operation failed.
IOError              I/O operation failed.

[...snip...]

>>> li = ["Larry", "Curly"]
>>> li.pop                       ***1***
<built-in method pop of list object at 010DF884>
>>> getattr(li, "pop")           ***2***
<built-in method pop of list object at 010DF884>
>>> getattr(li, "append")("Moe") ***3***
>>> li
["Larry", "Curly", "Moe"]
>>> getattr({}, "clear")         ***4***
<built-in method clear of dictionary object at 00F113D4>
>>> getattr((), "pop")           ***5***
Traceback (innermost last):
  File "<interactive input>", line 1, in ?
AttributeError: 'tuple' object has no attribute 'pop'

***1*** Ceci retourne une référence à la méthode pop de la liste. Ce n'est pas un appel à la méthode pop, un appel se ferait par li.pop(). C'est la méthode elle-même.
***2*** Ceci retourne également une référence à la méthode pop, mais cette fois ci le nom de la méthode est passé comme argument de la fonction getattr. getattr est une fonction prédéfinie extrèmement utile qui retourne n'importe quel attribut de n'importe quel objet. Ici, l'objet est une liste et l'attribut est la méthode pop.
***3*** Au cas où vous ne voyez pas à quel point c'est utile, regardez ceci : la valeur de retour de getattr est la méthode, que vous pouvez alors appeler comme si vous aviez tapé li.append("Moe") directement. Mais vous n'avez pas appelé la fonction directement, vous avez passé le nom de la fonction comme paramètre sous forme de chaîne.
***4*** getattr fonctionne aussi avec les dictionnaires.
***5*** En théorie, getattr pourrait fonctionner avec les tuples, mais les tuples n'ont pas de méthodes et getattr déclenchera une exception quel que soit le nom d'attribut que vous lui donnez.

getattr n'est pas seulement fait pour les types prédéfinis, il fonctionne aussi avec les modules.

Exemple 4.11. getattr dans apihelper.py▲

>>> import odbchelper
>>> odbchelper.buildConnectionString             ***1***
<function buildConnectionString at 00D18DD4>
>>> getattr(odbchelper, "buildConnectionString") ***2***
<function buildConnectionString at 00D18DD4>
>>> object = odbchelper
>>> method = "buildConnectionString"
>>> getattr(object, method)                      ***3***
<function buildConnectionString at 00D18DD4>
>>> type(getattr(object, method))                ***4***
<type 'function'>
>>> import types
>>> type(getattr(object, method)) == types.FunctionType
True
>>> callable(getattr(object, method))            ***5***
True

Une utilisation usuelle de getattr est dans le rôle de sélecteur. Par exemple, si vous avez un programme qui peut produire des données dans différents formats, vous pouvez définir des fonctions différentes pour chaque format de sortie et utiliser une fonction de sélection pour appeler celle qui convient.

Par exemple, imaginons un programme qui affiche des statistiques de consultations d'un site Web aux formats HTML, XML et texte simple. Le choix du format de sortie peut être spécifié depuis la ligne de commande ou stocké dans un fichier de configuration. Un module statsout définit trois fonctions, output_html, output_xml et output_text. Ensuite, le programme principal définit une fonction de sortie unique, comme ceci :

Exemple 4.12. Création d'un sélecteur avec getattr▲

import statsout

def output(data, format="text"):                              ***1***
    output_function = getattr(statsout, "output_%s" % format) ***2***
    return output_function(data)                              ***3***

Exemple 4.13. Valeurs par défaut de getattr▲

import statsout

def output(data, format="text"):
    output_function = getattr(statsout, "output_%s" % format, statsout.output_text)
    return output_function(data) ***1***

>>> li = ["a", "mpilgrim", "foo", "b", "c", "b", "d", "d"]
>>> [elem for elem in li if len(elem) > 1]       ***1***
['mpilgrim', 'foo']
>>> [elem for elem in li if elem != "b"]         ***2***
['a', 'mpilgrim', 'foo', 'c', 'd', 'd']
>>> [elem for elem in li if li.count(elem) == 1] ***3***
['a', 'mpilgrim', 'foo', 'c']

***1*** L'expression de mutation est ici très simple (elle retourne juste la valeur de chaque élément), observez plutôt attentivement l'expression de filtrage. Au fur et à mesure que Python parcours la liste, il soumet chaque élément à l'expression de filtrage, si l'expression s'évalue à vrai, l'élément passe par l'expression de mutation et le résultat est inclu dans la liste de résultat. Ici, on filtre toutes les chaînes d'un seul caractère, il ne reste donc que les chaînes plus longues.
***2*** Ici, on filtre une valeur spécifique : b. Notez que cela filtre toutes les occurences de b, puisqu'à chaque fois qu'il apparaît, l'expression de filtrage s'évaluera à faux.
***3*** count est une méthode de listes qui retourne le nombre d'occurences d'une valeur dans la liste. On pourrait penser que ce filtre élimine les doublons de la liste, retournant une liste contenant seulement un exemplaire de chaque valeur. Mais en fait, les valeurs qui apparaissent deux fois dans la liste initiale (ici b et d) sont totalement éliminées. Il y a des moyens de supprimer les doublons d'une liste mais le filtrage n'est pas la solution.

Revenons à cette ligne de apihelper.py:

    methodList = [method for method in dir(object) if callable(getattr(object, method))]

Cela à l'air complexe et ça l'est, mais la structure de base est la même. L'expression complète renvoie une liste qui est assignée à la variable methodList. La première moitié de l'expression est la mutation de liste. L'expression de mutation est une expression d'identité, elle retourne la valeur de chaque élément. dir(object) retourne une liste des attributs et méthodes de object, c'est à cette liste que vous appliquez la mutation. La seule nouveauté est l'expression après le if.

L'expression de filtrage à l'air impressionant, mais elle n'est pas si terrible. Vous connaissez déjà callable, getattr et in. Comme vous l'avez vu dans la section précédente, l'expression getattr(object, method) retourne un objet fonction si object est un module et si method est le nom d'une fonction de ce module.

Donc, cette expression prend un objet, appelé object, obtient une liste des noms de ses attributs, méthodes, fonctions et quelques autres choses, puis filtre cette liste pour éliminer ce qui ne nous intéresse pas. Cette élimination se fait en prenant le nom de chaque attribut/méthode/fonction et en obtenant une référence vers l'objet véritable, grâce à la fonction getattr. On vérifie alors si cet objet est appelable, ce qui sera le cas pour toutes les méthodes et fonctions prédéfinies (comme la méthode pop d'une liste) ou définies par l'utilisateur ( comme la fonction buildConnectionString du module odbchelper). Nous ne nous intéressons pas aux autres attributs, comme l'attribut __name__ qui existe pour tout module.

Pour en savoir plus sur le filtrage de liste

• Le Python Tutorial traite d'une autre manière de filtrer les listes en utilisant la fonction prédéfinie filter.

>>> 'a' and 'b'         ***1***
'b'
>>> '' and 'b'          ***2***
''
>>> 'a' and 'b' and 'c' ***3***
'c'

***1*** Lorsqu'on utilise and les valeurs sont évaluées dans un contexte booléen de gauche à droite. 0, '', [], (), {} et None valent faux dans ce contexte, tout le reste vaut vrai. (1) [1]Si toutes les valeurs valent vrai dans un contexte booléen, and retourne la dernière valeur. Ici and évalue 'a', qui vaut vrai, puis 'b', qui vaut vrai et retourne 'b'.
***2*** Si une des valeurs vaut faux and retourne la première valeur fausse. Ici '' est la première valeur fausse.
***3*** Toutes les valeurs sont vrai, donc and retourne la dernière valeur, 'c'.

>>> 'a' or 'b'          ***1***
'a'
>>> '' or 'b'           ***2***
'b'
>>> '' or [] or {}      ***3***
{}
>>> def sidefx():
...     print "in sidefx()"
...     return 1
>>> 'a' or sidefx()     ***4***
'a'

***1*** Lorsqu'on utilise or, les valeurs sont évaluées dans un contexte booléen de gauche à droite, comme pour and. Si une des valeurs vaut vrai, or la retourne immédiatement. Dans ce cas 'a' est la première valeur vraie. ***2*** or évalue '', qui vaut faux, puis 'b', qui vaut vrai et retourne 'b'. ***3*** Si toutes les valeurs valent faux, or retourne la dernière valeur. or évalue '', qui vaut faux, puis [], qui vaut faux, puis {}, qui vaut faux et retourne {}. ***4*** Notez que or continue l'évaluation seulement jusqu'à ce qu'il trouve une valeur vraie, le reste est ignoré. C'est important si certaines valeurs peuvent avoir un effet de bord. Ici, la fonction sidefx n'est jamais appelée, car or évalue 'a', qui vaut vrai et retourne 'a' immédiatement.

Si vous êtes un programmeur C, vous êtes certainement familier de l'expression ternaire bool ? a : b, qui s'évalue à a si bool vaut vrai et à b dans le cas contraire. Le fonctionnement de and et or en Python vous permet d'accomplir la même chose.

>>> a = "first"
>>> b = "second"
>>> 1 and a or b ***1***
'first'
>>> 0 and a or b ***2***
'second'

***1*** Cette syntaxe ressemble à celle de l'expression ternaire bool ? a : b de C. L'expression est évaluée de gauche à droite, donc le and est évalué en premier. 1 and 'first' s'évalue à 'first', puis 'first' or 'second' s'évalue à 'first'. ***2*** 0 and 'first' s'évalue à 0, puis 0 or 'second' s'évalue à 'second'.

Cependant, puisque cette expression en Python est simplement de la logique booléenne et non un dispositif spécial du langage, il y a une différence très, très importante entre l'astuce and-or en Python et la syntaxe bool ? a : b en C. Si a vaut faux, l'expression ne fonctionnera pas comme vous vous y attendez. (Vous devinez que cela m'a déjà joué des tours. Et plus d'une fois !)

Exemple 4.18. Quand l'astuce and-or échoue ▲

>>> a = ""
>>> b = "second"
>>> 1 and a or b         ***1***
'second'

Exemple 4.19. L'astuce and-or en toute sécurité ▲

>>> a = ""
>>> b = "second"
>>> (1 and [a] or [b])[0] ***1***
''

>>> def f(x):
...     return x*2
...     
>>> f(3)
6
>>> g = lambda x: x*2  ***1***
>>> g(3)
6
>>> (lambda x: x*2)(3) ***2***
6

***1*** Voici une fonction lambda qui fait la même chose que la fonction ordinaire précédente. Notez la syntaxe condensée : il n'y a pas de parenthèses autour de la liste d'arguments et le mot-clé return est manquant (il est implicite, la fonction complète ne pouvant être qu'une seule expression). Remarquez aussi que la fonction n'a pas de nom, mais qu'elle peut être appelée à travers la variable à laquelle elle est assignée. ***2*** Vous pouvez utiliser une fonction lambda sans l'assigner à une variable. Ce n'est pas forcément très utile, mais cela démontre qu'une fonction lambda est simplement une fonction en ligne.

Plus généralement, une fonction lambda est une fonction qui prend un nombre quelconque d'arguments (y compris des arguments optionnels) et retourne la valeur d'une expression unique. Les fonctions lambda ne peuvent pas contenir de commandes et elles ne peuvent contenir plus d'une expression. N'essayez pas de mettre trop de choses dans une fonction lambda, si vous avez besoin de quelque chose de complexe, définissez plutôt une fonction normale et faites la aussi longue que vous voulez.

Les fonctions lambda sont une question de style. Les utiliser n'est jamais une nécessité, partout où vous pouvez les utiliser, vous pouvez utiliser une fonction ordinaire. Je les utilise là où je veux incorporer du code spécifique et non réutilisable sans encombrer mon code de multiples fonctions d'une seule ligne.

Voici les fonctions lambda dans apihelper.py:

    processFunc = collapse and (lambda s: " ".join(s.split())) or (lambda s: s)

Il y a plusieurs chose à noter ici. D'abord, nous utilisons la forme simple de l'astuce and-or, ce qui est sûr car une fonction lambda vaut toujours vrai dans un contexte booléen. (Cela ne veut pas dire qu'une fonction lambda ne peut retourner faux. La fonction est toujours vrai, sa valeur de retour peut être vrai ou fausse.)

Ensuite, nous utilisons la fonction split sans arguments. Vous l'avez déjà vu employée avec un ou deux arguments, sans arguments elle utilise les espaces comme séparateur.

Exemple 4.21. split sans arguments ▲

>>> s = "this   is\na\ttest"  ***1***
>>> print s
this   is
a	test
>>> print s.split()           ***2***
['this', 'is', 'a', 'test']
>>> print " ".join(s.split()) ***3***
'this is a test'

    processFunc = collapse and (lambda s: " ".join(s.split())) or (lambda s: s)

>>> import odbchelper
>>> object = odbchelper                   ***1***
>>> method = 'buildConnectionString'      ***2***
>>> getattr(object, method)               ***3***
<function buildConnectionString at 010D6D74>
>>> print getattr(object, method).__doc__ ***4***
Build a connection string from a dictionary of parameters.

    Returns string.

***1*** Dans la fonction info, object est l'objet pour lequel nous demandons de l'aide, passé en argument.
***2*** Pendant que nous parcourons la methodList, method est le nom de la méthode en cours.
***3*** En utlisant la fonction getattr, nous obtenons une référence à la fonction method du module object.
***4*** Maintenant, afficher la doc string de la méthode est facile.

La pièce suivante du puzzle est l'utilisation de str sur la doc string. Comme vous vous rappelez peut-être, str est une fonction prédéfinie pour convertir des données en chaîne. Mais une doc string est toujours une chaîne, alors pourquoi utiliser str ? La réponse est que toutes les fonctions n'ont pas de doc string, et que l'attribut __doc__ de celles qui n'en ont pas renvoi None.

>>> >>> def foo(): print 2
>>> >>> foo()
2
>>> >>> foo.__doc__     ***1***
>>> foo.__doc__ == None ***2***
True
>>> str(foo.__doc__)    ***3***
'None'

***1*** Nous pouvons facilement définir une fonction qui n'a pas de doc string, sont attribut __doc__ est None. Attention, si vous évaluez directement l'attribut __doc__, l'IDE Python n'affiche rien du tout, ce qui est logique si vous y réflechissez mais n'est pas très utile. ***2*** Vous pouvez vérifier que la valeur de l'attribut __doc__ est bien None en faisant directement la comparaison. ***3*** Lorsque l'on utilise la fonction str, elle prend la valeur nulle et en retourne une représentation en chaîne, 'None'.

En SQL, vous devez utiliser IS NULLmethod au lieu de = NULL pour la comparaison d'une valeur nulle. En Python, vous pouvez utiliser aussi bien == None que is None, mais is None est plus rapide.

Maintenant que nous sommes sûrs d'obtenir une chaîne, nous pouvons passer la chaîne à processFunc, que nous avons déjà défini comme une fonction qui replie ou non les espace. Maintenant vous voyez qu'il était important d'utiliser str pour convertir une valeur None en une représentation en chaîne. processFunc attend une chaîne comme argument et appelle sa méthode split, ce qui échouerait si nous passions None, car None n'a pas de méthode split.

En remontant en arrière encore plus loin, nous voyons que nous utilisons encore le formatage de chaîne pour concaténer la valeur de retour de processFunc avec celle de la méthode ljust de method. C'est une nouvelle méthode de chaîne que nous n'avons pas encore rencontré.

>>> s = 'buildConnectionString'
>>> s.ljust(30) ***1***
'buildConnectionString         '
>>> s.ljust(20) ***2***
'buildConnectionString'

***1*** ljust complète la chaîne avec des espaces jusqu'à la longueur donnée. La fonction info l'utilise pour afficher sur deux colonnes et aligner les doc string de la seconde colonne.
***2*** Si la longueur donnée est plus petite que la longueur de la chaîne, ljust retourne simplement la chaîne sans la changer. Elle ne tronque jamais la chaîne.

Nous avons presque terminé. Ayant obtenu le nom de méthode complété d'espaces de la méthode ljust et la doc string (éventuellement repliée sur une ligne) de l'appel à processFunc, nous concaténons les deux pour obtenir une seule chaîne. Comme nous faisons une mutation de methodList, nous obtenons une liste de chaînes. En utlisant la méthode join de la chaîne "\n", nous joignons cette liste en une chaîne unique, avec chaque élément sur une ligne et affichons le résultat..

>>> li = ['a', 'b', 'c']
>>> print "\n".join(li) ***1***
a
b
c

***1*** C'est aussi une astuce de débogage utile lorsque vous travaillez avec des liste. Et en Python, vous travaillez toujours avec des listes.

C'est la dernière pièce du puzzle. Le code devrait maintenant être parfaitement compréhensible.

 print "\n".join(["%s %s" %
                      (method.ljust(spacing),
                       processFunc(str(getattr(object, method).__doc__)))
                     for method in methodList])