Le langage \href{https://www.python.org/}{Python} est un \href{https://docs.python.org/3/faq/general.html\#what-is-python}{langage de programmation} interprété, interactif, amusant, orienté objet (souvent), fonctionnel (parfois), open source, multi-plateformes, flexible, facile à apprendre et difficile à maîtriser.
A première vue, et suivants les autres langages que vous connaitriez ou auriez déjà abordé, certains concepts restent difficiles à aborder: l'indentation définit l'étendue d'un bloc (classe, fonction, méthode, boucle, condition, il n'y a pas de typage fort des variables et le compilateur n'est pas là pour assurer le filet de sécurité avant la mise en production (puisqu'il n'y a pas de compilateur).
Et malgré ces quelques points, Python reste un langage généraliste accessible et "bon partout", et de pouvoir se reposer sur un écosystème stable et fonctionnel.
Il fonctionne avec un système d'améliorations basées sur des propositions: les PEP, ou "\textbf{Python Enhancement Proposal}\index{PEP}".
Chacune d'entre elles doit être approuvée par le \href{http://fr.wikipedia.org/wiki/Benevolent_Dictator_for_Life}{Benevolent Dictator For Life\index{BDFL}}.
Le langage Python utilise un typage dynamique appelé \href{https://fr.wikipedia.org/wiki/Duck_typing}{\textbf{duck typing}}:
\begin{quote}
"\emph{When I see a bird that quacks like a duck, walks like a duck, has
feathers and webbed feet and associates with ducks --- I'm certainly
available in Python has its own protocol and operator overloading
happens by implementing the dunder methods of that protocol. Python
provides over 50 overloadable operators that can be divided into five
main groups:• Arithmetic operators • In-place assignment operators•
Comparison operators• Identity operators• Bitwise operatorsThat's a lot
of protocols so we won't discuss all of them here. We will instead take
a look at a practical example that will allow you to better understand
how to implement operator overloading on your own
The \texttt{add()} method is responsible for overloading the \texttt{+}
(plus sign) operator and here it allows us to add two matrices together.
Only matrices of the same dimensions can be added together. This is a
fairly simple operation that involves adding all matrix elements one by
one to form a new matrix.
The \texttt{sub()} method is responsible for overloading the \texttt{–}
(minus sign) operator that will be responsible for matrix subtraction.
To subtract two matrices, we use a similar technique as in the --
operator:
\begin{listing}
\begin{minted}{python}
def __sub__(self, other):
if (len(self.rows) != len(other.rows) or len(self.rows[0]) != len(other.rows[0])):
raise ValueError("Matrix dimensions don't match")
return Matrix([[a - b for a, b in zip(a_row, b_row)] for a_row, b_row in zip(self.rows, other.rows) ])
\end{minted}
\end{listing}
The last overloaded operator is the most complex one. This is the
\texttt{*} operator, which is implemented through the \texttt{mul()}
method. In linear algebra, matrices don't have the same multiplication
operation as real numbers. Two matrices can be multiplied if the first
matrix has a number of columns equal to the number of rows of the second
matrix. The result of that operation is a new matrix where each element
is a dot product of the corresponding row of the first matrix and the
corresponding column of the second matrix. Here we've built our own
implementation of the matrix to present the idea of operators
overloading. Although Python lacks a built-in type for matrices, you
don't need to build them from scratch. The NumPy package is one of the
best Python mathematical packages and among others provides native
support for matrix algebra. You can easily obtain the NumPy package from
PyPI
En fait, l'intérêt concerne surtout la représentation de nos modèles,
puisque chaque classe du modèle est représentée par la définition d'un
objet Python. Nous pouvons donc utiliser ces mêmes \textbf{dunder
methods} (\textbf{double-underscores methods}) pour étoffer les
protocoles du langage.
\section{The Zen of Python}
\begin{listing}[!ht]
\begin{verbatim}
>>> import this
The Zen of Python, by Tim Peters
Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!
\end{verbatim}
\caption{The Zen of Python}
\end{listing}
\section{Guide de style}
La première PEP qui va nous intéresser est la PEP8.
Elle spécifie comment du code Python doit être organisé ou formaté, quelles sont les conventions pour l'indentation, le nommage des variables et des classes, ...
En bref, elle décrit comment écrire du code proprement, afin que d'autres développeurs puissent le reprendre facilement, ou simplement que votre base de code ne dérive lentement vers un seuil de non-maintenabilité.
Dans cet objectif, un outil existe et listera l'ensemble des conventions qui ne sont pas correctement suivies dans votre projet: pep8. Pour l'installer, passez par pip.
Lancez ensuite la commande pep8 suivie du chemin à analyser (\texttt{.}, le nom d'un répertoire, le nom d'un fichier \texttt{.py}, \ldots\hspace{0pt}).
Si vous souhaitez uniquement avoir le nombre d'erreur de chaque type, saisissez les options \texttt{-\/-statistics\ -qq}.
\begin{listing}[!ht]
\begin{verbatim}
$ pep8 . --statistics -qq
7 E101 indentation contains mixed spaces and tabs
6 E122 continuation line missing indentation or outdented
8 E127 continuation line over-indented for visual indent
23 E128 continuation line under-indented for visual indent
3 E131 continuation line unaligned for hanging indent
12 E201 whitespace after '{'
13 E202 whitespace before '}'
86 E203 whitespace before ':'
\end{verbatim}
\caption{Une utilisation de pep8}
\end{listing}
Si vous ne voulez pas être dérangé sur votre manière de coder, et que vous voulez juste avoir un retour sur une analyse de votre code, essayez \texttt{pyflakes}: cette librairie analysera vos sources à la recherche de sources d'erreurs possibles (imports inutilisés, méthodes inconnues, etc.).
\section{Conventions de documentation}
Python étant un langage interprété fortement typé, il est plus que conseillé, au même titre que les tests unitaires que nous verrons plus bas, de documenter son code.
Cela impose une certaine rigueur, mais améliore énormément la qualité, la compréhension et la reprise du code par une tierce personne.
Cela implique aussi de \textbf{tout} documenter: les modules, les paquets, les classes, les fonctions, méthodes, ...
Ce qui peut également aller à contrecourant d'autres pratiques \cite{clean_code}{53-74} ; il y a une juste mesure à prendre entre "tout documenter" et "tout bien documenter":
Git ou tout VCS s'en sortira très bien et sera beaucoup plus efficace que n'importe quelle chaîne de caractères que vous pourriez indiquer et qui sera fausse dans six mois,
La \href{https://peps.python.org/pep-0257/#what-is-a-docstring}{PEP-257} nous donne des recommandations haut-niveau concernant la structure des docstrings: ce qu'elles doivent contenir et comment l'expliciter, sans imposer quelle que mise en forme que ce soit.
de contenu, mais pas de forme, notamment sur la manière de représenter des docstrings ne nécessitant qu'une seule ligne, nécessitant plusieurs lignes ou de gérer l'indentation.
Son objectif est d'arriver à une forme de cohérence lorsqu'un utilisateur souhaitera accéder à la propriété
Elle contient des conventions, pas des règles ou
\begin{quote}
“A universal convention supplies all of maintainability, clarity, consistency, and a foundation for good programming habits too. What it doesn’t do is insist that you follow it against your will. That’s Python!”
-- Tim Peters on comp.lang.python, 2001-06-16
\end{quote}
Ainsi, les conventions sont décrites; chaque format propose ensuite son propre balisage (ReStructuredText, Numpy, Napoleon, ...).
A priori, vous pourriez tout à fait utiliser le vôtre, sous réserve que les conventions de la PEP-257 soient respectées.
\subsection{RestructuredText}
\href{https://peps.python.org/pep-0287/}{See also ;)}
Les \href{https://google.github.io/styleguide/pyguide.html\#38-comments-and-docstrings}{conventions proposées par Google} nous semblent plus faciles à lire que du RestructuredText, mais sont parfois moins bien intégrées que les docstrings officiellement supportées (par exemple, \href{https://clize.readthedocs.io/en/stable/}{clize} ne reconnait que du RestructuredText; \href{https://docs.djangoproject.com/en/stable/ref/contrib/admin/admindocs/}{l'auto-documentation} de Django également).
L'exemple donné dans les guides de style de Google est celui-ci: