Utiliser de la syntaxe Python pour les prototypes de fonction

Dans la doc de Python, la syntaxe utilisée pour les arguments optionnels fait mal aux yeux des débutants, n’est pas de la syntaxe Python, et se mélange avec la syntaxe des listes, par exemple :

complex([real[, imag]])

Je propose de convertir ça en syntaxe Python :

complex(real=0, imag=0)
complex(string, /)

En faisant d’une pierre trois coups :

  • C’est de la syntaxe Python, donc les “débutants” découvrent que / c’est valide, sans pour autant découvrir ce que ça veut dire.
  • Ça permet de documenter les valeurs par défaut lorsqu’il y en a.
  • Parfois, comme pour complex j’en profite pour rajouter les constructeurs alternatifs manquants à la doc, comme le fait que complex accepte aussi une chaîne.

C’est dans cette PR :

Et je me demande encore si c’est plus lisible avant ou après, j’aimerai l’avis de la communauté :relaxed:

3 « J'aime »

Je trouve que c’est beaucoup plus lisible comme ça. Quand je donne des cours, cette syntaxe est parfois problématique, surtout pour les personnes qui apprennent à programmer.

J’aime beaucoup le fait d’avoir de la vraie syntaxe Python tout en affichant les valeurs par défaut. Pareil pour les constructeurs alternatifs (j’adore par exemple le changement sur super()).

La seule chose dont je ne suis pas fan est l’ajout du / quand il est à la fin des fonctions. Je comprends la volonté derrière (et on gagnerait en précision) mais je trouve que ça ajoute une complexité un peu trop élevée par rapport au gain.

Voilà, c’était juste mon avis :grin:. En tout cas, merci de prendre soin de la doc :purple_heart:.

C’est ce qui m’inquiète en effet.

Je trouve cela super d’utiliser de la syntaxe Python, c’est bien plus lisible (merci !).

Est-ce qu’il y a une guide de bonnes pratiques pour documenter les fonctions ? Il me semble avoir vu les deux syntaxes mélangées dans un même fichier.

Je trouve cela super d’utiliser de la syntaxe Python, c’est bien plus lisible (merci !).

Aller hop je merge alors.

Est-ce qu’il y a une guide de bonnes pratiques pour documenter les fonctions ? Il me semble avoir vu les deux syntaxes mélangées dans un même fichier.

Il y a bien un guide, mais il ne parle pas des prototypes des fonctions.

Si cette expérience survit j’essayerai d’en convertir d’autres et d’ajouter ça au guide de style.