les-infos-des-méthodes.md

@@ -11,21 +11,30 @@ Comment déchiffrer la doc ?
 La méthode **plot** est la plus commune des méthodes de tracé : plt.plot(vecteur_des_x, vecteur_des_t) tracera une ligne reliant les points (x,y) pris 2 à 2 dans les listes (ou tuples, ou vecteurs...). **vecteur_des_x**, **vecteur_des_t** sont donc les **arguments** à passer à la méthode, mais ce ne sont pas les seuls arguments possibles.
 Comment en savoir plus sur la méthode ?
 
-La doc de la **version 3.5** décrit la méthode comme ceci :
-
-#### Axes.plot(*args, scalex=True, scaley=True, data=None, **kwargs)
-Description : "Plot y versus x as lines and/or markers."
-
 ### **classe** à laquelle s'applique la méthode
 il s'agit de **Axes**
-En toute rigueur, la syntaxe est don **mon_ax**.plot(), mais on explique par ailleurs dans ces pages que plt.plot() est une méthode de plt qui va chercher l'axe courant (**gca** : get current Axes) soit plt.**gca()**.plot()
+En toute rigueur, la syntaxe est donc **mon_ax**.plot(), mais on explique par ailleurs dans ces pages que plt.plot() est une méthode de plt qui va chercher l'axe courant (**gca** : get current Axes) soit plt.**gca()**.plot()
 
 ### **arguments** à fournir à la méthode
 
-La formule *_args_ signifie que vous "déballez" avec * un tuple nommé par convention _args__ ("unpacking de tuple"), ce qui signifie qu'on peut passer une série de un ou plusieurs arguments. 
-Certains arguments sont obligatoires (il faut au minimum une série à tracer...), et d'autres facultatifs, mais l' **ordre** est important sinon l'interpréteur ne saura pas qui fait quoi.
+Quelques rappels. (:map: [plus de détails dans le rappel des bases](A_quelques bases) ; sur les notations 'splat' _*_, *args et **kwargs voir aussi les références rappelées tout en bas de cette page)
+
+En tête se trouvent les arguments **obligatoires** (il faut au minimum une série à tracer...), et d'autres facultatifs (car ils ont une valeur par défaut). Il est possible de ne pas nommer les arguments,  mais alors la **position** est importante sinon l'interpréteur ne saura pas qui fait quoi.
+La formule *_args_ signifie que vous "déballez" avec * un tuple de longueur indéterminée, nommé par convention _args__ ("unpacking de tuple"), ce qui signifie qu'on peut passer une série de un ou plusieurs arguments.
+En fin de liste se trouvent les **kwargs. 
+
+La doc de matplotlib décrit la méthode en détail ; utilisez la doc de la version que vous utilisez :
+
+:three: :four: doc de la [**version 3.4.2**](https://matplotlib.org/3.4.2/api/_as_gen/matplotlib.axes.Axes.plot.html?highlight=plot#matplotlib.axes.Axes.plot)
+:three: :five:  doc de la [**version 5.0](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.plot.html)
 
-La ligne "call signatures" détaille un peu plus les arguments :
+Dans les 2 cas, l'article est très long, avec des variantes !
+On va commenter le cas le plus général.
+
+#### Axes.plot(*args, scalex=True, scaley=True, data=None, **kwargs)
+Description : "Plot y versus x as lines and/or markers."
+
+La ligne "call signatures" détaille un peu plus les arguments de **plot** :
 
 ``` python
 # Call signatures:
@@ -33,20 +42,21 @@ plot([x], y, [fmt], *, data=None, **kwargs)
 plot([x], y, [fmt], [x2], y2, [fmt2], ..., **kwargs)
 ```
 
-Première ligne :
+Interprétation de la première ligne, avant l'étoile (_splat_) :
 [x] = argument facultatif ; eh oui, x est facultatif ! Ici, il y a une valeur de x "par défaut", qui est range(0, len(y))
 y = argument obligatoire
 [fmt] = argument facultatif : description condensée du format de la courbe (voir ci-dessous)
-* = séparateur d'arguments, ceux suivant l'étoile seront obligatoirement nommés dans les appels (
+* = séparateur d'arguments, appelé parfois _splat_ ; ceux placés après seront des arguments par mot-clé, donc avec dans les appels une notation explicite   _mot_cle=valeur_.
  
-Deuxième ligne :
+Deuxième ligne, avant l'étoile (_splat_)  :
 On passe plusieurs séries (x,y) à la suite, avec un format **fmt** pour **[x],y** et un autre **fmt2** pour **[x2],y2**
+On n'utilisera pas ce cas de figure ici, ni les autres cas plus compliqués encore.
 
-### *args : tuple d'arguments
-On remarque dans la liste des arguments un séparateur d'arguments(...,*,...)  
-Avant le séparateur '*' on passe des arguments sans rappeler leur nom, et même on ne *peut pas* les nommer car on  a placé cette étoile. (on n'en dira pas plus ici, voir tutographie à la fin)
+On sait que pour les arguments obligatoires, passés en tête de liste, on n'est pas obligés d'indiquer le nom des arguments lors des appels, à condition de respecter l'**ordre** sinon l'interpréteur ne saura pas qui est quoi.
+Ici, en particulier, on n'a d'ailleurs pas le droit, dans le détail des arguments qui suit(_Parameters_ en anglais), on lit :_These arguments cannot be passed as keywords._  
+
+Essayez l'instruction plt.plot(x=[1,23,52], y=[1,23,30]) ; avec la version 3.4.2 j'ai une **TypeError: plot got an unexpected keyword argument 'x'**
 
-*args permet donc de faire passer un nombre non précisé d'arguments, l'interpréteur se débrouillera avec. Par contre, quand ils ne sont pas nommés (et ici c'est d'ailleurs interdit)  il faudra respecter l'**ordre** sinon il ne saura pas qui est quoi.
 
 ``` python
 plot(un_vecteur)           # (1 = y seul) : plot **un_vecteur vs x** par défaut =  index des réels 0 à len(y)-1)
@@ -65,34 +75,45 @@ C'est bien pratique... quand on a l'habitude :
  `'bo' = color='**b**lack', marker='**o**' `
  `'r+' = color='**r**ed', marker='**+**' `
 
+A noter que fmt n'est pas un argument de type **args, ce n'est pas un tuple mais une chaîne de caractères qui va être décomposée dans la méthode.
+
+### * : et splat !
+On remarque dans la liste des arguments un séparateur d'arguments(...,*,...)  
+On n'a pas ici d'argument de type *args. Cependant, pour bien marquer la frontière entre les arguments "classiques" et les **kwargs, on place juste le "splat", _*_ 
 
-###  arguments nommés, après le séparateur d'arguments(...,*,...)  
-Après le séparateur '*' on passe forcément à des arguments nommés. 
+###  arguments après le séparateur d'arguments(...,*,...)  : keyword arguments, **kwargs
+Après le séparateur '*' on passe forcément à des arguments **par mots-clefs**, les _**kwargs_. 
 Il faut donc rappeler le nom de l'argument : "nom_argument = variable_que_je_passe"
 Comme on précise le nom, la position n'a pas d'importance.
 
-Les arguments nommés sont optionnels s'ils ont une valeur par défaut.
-Ainsi,  **data=None** signifie que si on ne passe pas explicitement d'argument **data**, ce sera comme si on avait déclaré data=None.
+**data=None** signifie que si on ne passe pas explicitement d'argument **data**, ce sera comme si on avait déclaré data=None.
+
+``` python
+# Exemples d'arguments par mots-clés, ajoutés en nombre indéfini à la fin : 
+plot(x, y, 'go--', linewidth=2, markersize=12)
+plot(x, y, color='green', marker='o', linestyle='dashed', linewidth=2, markersize=12)
+```
+
+###  notion de properties
+
+La doc vous précise que les **kwargs correspondent à des **properties** de Line2D
+
+**kwargsLine2D properties, optional
 
-## :warning: vérifications en cours ! ! diff argument nommé vs kwargs ???
-###  keyword arguments
+    kwargs are used to specify properties like a line label (for auto legends), linewidth, antialiasing, marker face color.
 
-La syntaxe **kwargs précise qu'il existe des arguments définis par un dictionnaire. Comme pour les *args, le nombre n'est pas fixe, on peut en mettre un ou plusieurs.
-Dit autrement, pour les autres réglages (linewidth, markersize...) il existe un **dictionnaire** qui fait une correspondance entre l'argument passé, pris comme clé, et sa valeur.
+Sans entrer dans les détails, cette info nous apprend deux choses: 
+- on va pouvoir décrire la ligne 2D, à sa création, avec comme arguments des descripteurs bien connus, communs à beaucoup d'autres objets ; leurs noms sont explicites si on connaît un tant soit peu l'anglais technique de base...
 
-Exemple :
+Exemple lu dans la doc :
 ``` python
   lineStyles = {'': '_draw_nothing', ' ': '_draw_nothing', '-': '_draw_solid', '--': '_draw_dashed', '-.': '_draw_dash_dot', ':': '_draw_dotted', 'None': '_draw_nothing'}
 ``` 
+- ce sont des _properties_ : on ne va pas pouvoir en modifier les valeurs directement après leur création, il faudra passer par des **setters** et des **getters** comme c'est la règle en Java par exemple.
+    Voir ci-dessous "comment modifier l'objet créé".
 
-Ces noms sont explicites si on connaît un tant soit peu l'anglais technique de base...
+:warning: 'None' figure dans les mots-clefs, c'est à dire que si vous passez linestyle=**'**None**'** l'interpréteur va se reporter à la valeur correspondante ('_draw_nothing') mais si vous passez None sans les cotes il considèrera que vous n'avez pas passé d'arguments. Dans certains cas cela reviendra au même, alors que dans d'autres non : color='None' => je ne veux pas de couleur ; color=None => je ne précise pas la couleur, celle par défaut utilisée...
 
-``` python
-# Arguments nommés, ajoutés à la suite des arguments situés avant le '*' : 
-plot(x, y, 'go--', **linewidth**=2, **markersize**=12)
-plot(x, y, **color**='green', **marker**='o', **linestyle**='dashed',
-     linewidth=2, markersize=12)
-```
 
 ### ce que **retourne** la méthode
 :bell: c'est très important, et peut être un peu caché dans la doc de la version 3.5.
@@ -125,12 +146,9 @@ premier_element,  = plot(x, y, **color**='green')
 ```
 Nous avons donc nommé l'objet, ici une instance de **Line2D**, ce qui nous permettra de le modifier au besoin.
 
-
-
-
 #### comment modifier l'objet créé
 Les arguments sont ce que vous **passez** à la méthode.
-Ce ne sont pas forcément directement les mêmes noms que les **attributs** de la classe, et vous n'avez pas toujours la permission de modifier ces attributs.
+Ce ne sont pas forcément directement les mêmes noms que les **attributs** de la classe de l'objet créé, et vous n'avez pas toujours la permission de modifier ces attributs.
 
 Il faut au préalable connaître la nature de l'objet, et vérifier comment modifier les attributs : à la volée ou le plus souvent avec des **setters**. 
 
@@ -148,5 +166,7 @@ On utilisera ces méthodes dans les graphiques interactifs de l'[atelier widgets
 
 
 ## Pour en savoir plus sur les *args et **kwargs
-
-[un tuto}(https://realpython.com/python-kwargs-and-args/)
\ No newline at end of file
+[Le petit topo sur les bases utiles vous présente les différents arguments d'une fonction](A_quelques bases).
+Vous y trouverez deux références consultables sur Internet que l'on rappelle ici:
+:flag_fr: [un tuto de Sam et Max](https://sametmax.oprax.fr/operateur-splat-ou-etoile-en-python/index.html)
+:flag_us: [un tuto de Real Python](https://realpython.com/python-kwargs-and-args/)