Improve models and create SOA

code_samples/shapes.py

@@ -0,0 +1,46 @@
+
+class Shape:
+    def area(self):
+        pass
+
+class Square(Shape):
+    def __init__(self, top_left, side):
+        self.__top_left = top_left
+        self.__side = side
+
+    def area(self):
+        return self.__side * self.__side
+
+class Rectangle(Shape):
+    def __init__(self, top_left, height, width):
+        self.__top_left = top_left
+        self.__height = height
+        self.__width = width
+
+    def area(self):
+        return self.__height * self.__width
+
+class Circle(Shape):
+    def __init__(self, center, radius):
+        self.__center = center
+        self.__radius = radius
+
+    def area(self):
+        PI = 3.141592653589793
+        return PI * self.__radius**2
+
+
+class Geometry:
+
+
+    def area(self, shape):
+        if isinstance(shape, Square):
+            return shape.side * shape.side
+
+        if isinstance(shape, Rectangle):
+            return shape.height * shape.width
+
+        if isinstance(shape, Circle):
+
+
+        raise NoSuchShapeException()

source/diagrams/books-foreign-keys-example

@@ -0,0 +1 @@
+<mxfile host="Electron" modified="2021-12-29T10:58:14.673Z" agent="5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/16.0.2 Chrome/96.0.4664.55 Electron/16.0.5 Safari/537.36" etag="dMCpLJpV5Li7PZHA3tmT" version="16.0.2" type="device"><diagram id="Lilse0xzAZw1GVnBGF5J" name="Page-1">7Zlrb5swFIZ/DeqnRmAIST6mpJdJ7VQp0/bZAQesGpvZJpf9+h1zy4VW6dDaRCpVpcDrY4PP89rYYLlBurmXOEueRESYhexoY7kzCyHHsRH8GGVbKTYalkosaVRpO2FO/5A6sFJzGhF1EKiFYJpmh2IoOCehPtCwlGJ9GLYU7PCqGY5JS5iHmLXVXzTSSamO0WinPxAaJ/WVHX9SlqS4Dq56ohIcifWe5N5abiCF0OVRugkIM9mr81LWu3ujtLkxSbh+TwU9w9n46ddWUVuspGb2T+/7ddXKCrO86rCFfAbt3SzgIDYHAdZW4FrTSSwkBRR1uawDPl6BTi12WpFMva0JSZHziJhO2lC8Tqgm8wyHpnQNpgQt0SmDM6epvSJSk82beXQaOuBrIlKi5RZC6gp+WaN2tFuernfu8L0KeXLgjErElSPjpuUdNDiouP0DQ3Sa4TTCmcaaCq7MHeRmwFBeYk3xOZB+EbO4h2bx2mZx0CtmQfZHmcU9bZZ5SAkPyfUdDY1jLoPqF/GLM5mcNIwz+kzDeKcN81ROJBEtfyH0eom5xkrT31DpIih/Ef+4w0ubcIbvnnDMo4lo0x5fCgnrp949n+yeoXNp7hm33DPLOWklai8NJgEU1u+PeEHYs1C0eIa5s4XQWqQQgBmNjRBCUogEgZnIGxy+xEW+A8GELJp1l8XfXqPTqq4WJvlKS/HSbAtQo+y1YNtj+87Aa1b/5iTCKmmwQklmupFuYrOHGlChRgMK+xk1iESYp3Cb6v/gPV66Ttp4ERoM23zdj8I7aeF9QPeox9sN7+jS8Drt7eUtTGjyykz19zjtB3JH0p4/qN+j1NtQ//y023uLByyL+34GZoCop92Ftn/0wsE+P+n2puBHQsyYlgTrYmxrtdj2vDvxHnuD0dHgHp0feXsdHzCCOUiBiPqJvOOC27u4R7bfXnETBTmmPLbM2v94IzPDGl9/A3Bc0RV5NWSaZQxYVa8fe6N0McrR2s4Znt8po5ZTHg3/OVyckxzo21HxuQCnJuN8obJXd8JTzgnON70xur3wmVzcDNLesz9eYaXgn5rHhRRbzHranWh7znjwiUsDON19nyzK9j7zurd/AQ==</diagram></mxfile>

source/django/models.adoc

@@ -1,14 +0,0 @@
-== Modélisation
-
-On va aborder la modélisation des objets en elle-même, qui s'apparente à la conception de la base de données. 
-
-Django utilise un modèle https://fr.wikipedia.org/wiki/Mapping_objet-relationnel[ORM] - c'est-à-dire que chaque objet peut s'apparenter à une table SQL, mais en ajoutant une couche propre au paradigme orienté objet. Il sera ainsi possible de définir facilement des notions d'héritage (tout en restant dans une forme d'héritage simple), la possibilité d'utiliser des propriétés spécifiques, des classes intermédiaires, ... 
-
-L'avantage de tout ceci est que tout reste au niveau du code. Si l'on revient sur la méthodologie des douze facteurs, ce point concerne principalement la minimisation de la divergence entre les environnements d'exécution. Déployer une nouvelle instance de l'application pourra être réalisé directement à partir d'une seule et même commande, dans la mesure où *tout est embarqué au niveau du code*.
-
-Assez de blabla, on démarre !
-
-=== Le modèle et les validateurs
-
-
-=== 

source/glossary.adoc

@@ -5,6 +5,8 @@ http:: _HyperText Transfer Protocol_, ou plus généralement le protocole utilis
 
 IaaS:: _Infrastructure as a Service_, où un tiers vous fournit des machines (généralement virtuelles) que vous devrez ensuite gérer en bon père de famille. L'IaaS propose souvent une API, qui vous permet d'intégrer la durée de vie de chaque machine dans vos flux - en créant, augmentant, détruisant une machine lorsque cela s'avère nécessaire.
 
+MVC:: Le modèle _Model-View-Controler_ est un patron de conception autorisant un faible couplage entre la gestion des données (le _Modèle_), l'affichage et le traitement de celles (la _Vue_) et la glue entre ces deux composants (au travers du _Contrôleur_). https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller[Wikipédia]
+
 ORM:: _Object Relational Mapper_, où une instance est directement (ou à proximité) liée à un mode de persistance de données.
 
 PaaS:: _Platform as a Service_, qui consiste à proposer les composants d'une plateforme (Redis, PostgreSQL, ...) en libre service et disponibles à la demande (quoiqu'après avoir communiqué son numéro de carte de crédit...).

source/part-1-workspace/environment/_index.adoc

@@ -11,16 +11,12 @@ Et malgré ces quelques points, Python reste un langage généraliste accessible
 Il fonctionne avec un système d'améliorations basées sur des propositions: les PEP, ou "**Python Enhancement Proposal**".
 Chacune d'entre elles doit être approuvée par le http://fr.wikipedia.org/wiki/Benevolent_Dictator_for_Life[Benevolent Dictator For Life].
 
-
-
 NOTE: Le langage Python utilise un typage dynamique appelé https://fr.wikipedia.org/wiki/Duck_typing[*duck typing*]: "_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 going to assume that he is a duck_"
 Source: http://en.wikipedia.org/wiki/Duck_test[Wikipedia].
 
 Les morceaux de code que vous trouverez ci-dessous seront développés pour Python3.9+ et Django 3.2+.
 Ils nécessiteront peut-être quelques adaptations pour fonctionner sur une version antérieure.
 
-
-
 === Eléments de langage
 
 En fonction de votre niveau d'apprentissage du langage, plusieurs ressources pourraient vous aider:
@@ -31,6 +27,92 @@ A ce jour, c'est le concentré de sujets liés au langage le plus intéressant q
 
 En parallèle, si vous avez besoin d'un aide-mémoire ou d'une liste exhaustive des types et structures de données du langage, référez-vous au lien suivant: https://gto76.github.io/python-cheatsheet/[Python Cheat Sheet].
 
+==== Protocoles de langage
+
+(((dunder)))
+
+Le modèle de données du langage spécifie un ensemble de méthodes qui peuvent être surchargées.
+Ces méthodes suivent une convention de nommage et leur nom est toujours encadré par un double tiret souligné; d'où leur nom de "_dunder methods_" ou "_double-underscore methods_".
+La méthode la plus couramment utilisée est la méthode `__init__()`, qui permet de surcharger l'initialisation d'une instance de classe.
+
+[source,python]
+----
+class CustomUserClass:
+    def __init__(self, initiatization_argument):
+        ...
+----
+
+cite:{expert_python, 142-144}
+
+Ces méthodes, utilisées seules ou selon des combinaisons spécifiques, constituent les _protocoles de langage_.
+Une liste complètement des _dunder methods_ peut être trouvée dans la section `Data Model` de https://docs.python.org/3/reference/datamodel.html[la documentation du langage Python].
+
+All operators are also exposed as ordinary functions in the operators module.
+The documentation of that module gives a good overview of Python operators.
+It can be found at https://docs.python.org/3.9/library/operator.html
+
+
+If we say that an object implements a specific language protocol, it means that it is compatible with a specific part of the Python language syntax.
+
+The following is a table of the most common protocols within the Python language.
+
+Protocol nameMethodsDescriptionCallable protocol__call__()Allows objects to be called with parentheses:instance()Descriptor protocols__set__(), __get__(), and __del__()Allows us to manipulate the attribute access pattern of classes (see the Descriptors section)Container protocol__contains__()Allows us to test whether or not an object contains some value using the in keyword:value in instance
+
+Python in Comparison with Other LanguagesIterable protocol__iter__()Allows objects to be iterated using the forkeyword:for value in instance:    ...Sequence protocol__getitem__(),__len__()Allows objects to be indexed with square bracket syntax and queried for length using a built-in function:item = instance[index]length = len(instance)Each operator 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 `__add__()` method is responsible for overloading the `+` (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 `__sub__()` method is responsible for overloading the `–` (minus sign) operator that will be responsible for matrix subtraction.
+To subtract two matrices, we use a similar technique as in the – operator:
+
+[source,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)    ])
+----
+
+And the following is the last method we add to our class:
+
+[source,python]
+----
+def __mul__(self, other):
+    if not isinstance(other, Matrix):
+        raise TypeError(f"Don't know how to multiply {type(other)} with Matrix")
+
+    if len(self.rows[0]) != len(other.rows):
+        raise ValueError("Matrix dimensions don't match")
+
+    rows = [[0 for _ in other.rows[0]]  for _ in self.rows]
+
+    for i in range(len (self.rows)):
+        for j in range(len (other.rows[0])):
+            for k in range(len (other.rows)):
+                rows[i][j] += self.rows[i][k] * other.rows[k][j]
+
+    return Matrix(rows)
+----
+
+The last overloaded operator is the most complex one.
+This is the `*` operator, which is implemented through the `__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 *dunder methods* (*double-underscores methods*) pour étoffer les protocoles du langage.
 
 === The Zen of Python
 
@@ -94,11 +176,15 @@ Si vous ne voulez pas être dérangé sur votre manière de coder, et que vous v
 === PEP257 - Docstring Conventions
 
 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é (et la reprise) du code par une tierce personne.
+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 **tout** documenter: les modules, les paquets, les classes, les fonctions, méthodes, ...
-Tout doit avoir un *docstring* associé :-).
+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":
 
-WARNING: Documentation: be obsessed!
+* Inutile d'ajouter des watermarks, auteurs, ... 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,
+* Inutile de décrire quelque chose qui est évident; documenter la méthode `get_age()` d'une personne n'aura pas beaucoup d'intérêt
+* S'il est nécessaire de décrire un comportement au sein-même d'une fonction, c'est que ce comportement pourrait être extrait dans une nouvelle fonction (qui, elle, pourra être documentée)
+
+WARNING: Documentation: be obsessed! Mais *le code reste la référence*
 
 Il existe plusieurs types de conventions de documentation:
 
@@ -107,8 +193,8 @@ Il existe plusieurs types de conventions de documentation:
 . Google Style (parfois connue sous l'intitulé `Napoleon`)
 . ...
 
-Les 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 (typiquement, par exemple par https://clize.readthedocs.io/en/stable/[clize] qui ne reconnait que du RestructuredText).
-L'exemple donné dans les styleguide est celui-ci:
+Les 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, https://clize.readthedocs.io/en/stable/[clize] ne reconnait que du RestructuredText; 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:
 
 [source,python]
 ----
@@ -150,18 +236,75 @@ C'est-à-dire:
 
 . Une courte ligne d'introduction, descriptive, indiquant ce que la fonction ou la méthode réalise. Attention, la documentation ne doit pas indiquer _comment_ la fonction/méthode est implémentée, mais ce qu'elle fait concrètement (et succintement).
 . Une ligne vide
-. Une description plus complète et plus verbeuse
+. Une description plus complète et plus verbeuse, si vous le jugez nécessaire
 . Une ligne vide
-. La description des arguments et paramètres, des valeurs de retour (+ exemples) et les exceptions qui peuvent être levées.
+. La description des arguments et paramètres, des valeurs de retour, des exemples et les exceptions qui peuvent être levées.
 
 Un exemple (encore) plus complet peut être trouvé https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html#example-google[dans le dépôt sphinxcontrib-napoleon].
+Et ici, nous tombons peut-être dans l'excès de zèle:
+
+[source,python]
+----
+def module_level_function(param1, param2=None, *args, **kwargs):
+    """This is an example of a module level function.
+
+    Function parameters should be documented in the ``Args`` section. The name
+    of each parameter is required. The type and description of each parameter
+    is optional, but should be included if not obvious.
+
+    If \*args or \*\*kwargs are accepted,
+    they should be listed as ``*args`` and ``**kwargs``.
+
+    The format for a parameter is::
+
+        name (type): description
+            The description may span multiple lines. Following
+            lines should be indented. The "(type)" is optional.
+
+            Multiple paragraphs are supported in parameter
+            descriptions.
+
+    Args:
+        param1 (int): The first parameter.
+        param2 (:obj:`str`, optional): The second parameter. Defaults to None.
+            Second line of description should be indented.
+        *args: Variable length argument list.
+        **kwargs: Arbitrary keyword arguments.
+
+    Returns:
+        bool: True if successful, False otherwise.
+
+        The return type is optional and may be specified at the beginning of
+        the ``Returns`` section followed by a colon.
+
+        The ``Returns`` section may span multiple lines and paragraphs.
+        Following lines should be indented to match the first line.
+
+        The ``Returns`` section supports any reStructuredText formatting,
+        including literal blocks::
+
+            {
+                'param1': param1,
+                'param2': param2
+            }
+
+    Raises:
+        AttributeError: The ``Raises`` section is a list of all exceptions
+            that are relevant to the interface.
+        ValueError: If `param2` is equal to `param1`.
+
+    """
+    if param1 == param2:
+        raise ValueError('param1 may not be equal to param2')
+    return True
+----
 
 Pour ceux que cela pourrait intéresser, il existe https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring[une extension pour Codium], comme nous le verrons juste après, qui permet de générer automatiquement le squelette de documentation d'un bloc de code:
 
 .autodocstring
 image::images/environment/python-docstring-vscode.png[]
 
-NOTE: Nous le verrons plus loin, Django permet de rendre la documentation immédiatement accessible depuis son interface d'administration.
+NOTE: Nous le verrons plus loin, Django permet de rendre la documentation immédiatement accessible depuis son interface d'administration. Toute information pertinente peut donc lier le code à un cas d'utilisation concret.
 
 ==== Linters
 

source/part-1-workspace/maintainable-applications/_index.adoc

@@ -14,8 +14,6 @@ include::12-factors.adoc[]
 include::maintainable-applications.adoc[]
 include::mccabe.adoc[]
 
-=== Robustesse et flexibilité
-
 include::solid.adoc[]
 
 === Intégrées

source/part-1-workspace/maintainable-applications/solid.adoc

@@ -1,71 +1,134 @@
-. SRP - Single responsibility principle
+=== Robustesse et flexibilité
+
+> Un code mal pensé entraîne nécessairement une perte d'énergie et de temps.
+> Il est plus simple de réfléchir, au moment de la conception du programme, à une architecture permettant une meilleure maintenabilité que de devoir corriger un code "sale" _a posteriori_.
+> C'est pour aider les développeurs à rester dans le droit chemin que les principes SOLID ont été énumérés. GNU/Linux Magazine HS 104 cite:{gnu_linux_mag_hs_104, 26-44}
+
+Les principes SOLID, introduit par Robert C. Martin dans les années 2000 sont les suivants:
+
+. SRP - Single responsibility principle - Principe de Responsabilité Unique
 . OCP - Open-closed principle
 . LSP - Liskov Substitution
 . ISP - Interface ségrégation principle
-. DIP - Dependency Inversion Principle 
+. DIP - Dependency Inversion Principle
 
-En plus de ces principes de développement, il faut ajouter des principes architecturaux au niveau des composants: 
+En plus de ces principes de développement, il faut ajouter des principes au niveau des composants, puis un niveau plus haut, au niveau, au niveau architectural :
 
-. Reuse/release équivalence principle, 
-. Common Closure Principle, 
-. Common Reuse Principle. 
+. Reuse/release équivalence principle,
+. Common Closure Principle,
+. Common Reuse Principle.
 
-La même réflexion sera appliquée au niveau architectural, et se basera sur ces mêmes primitives. 
 
 ==== Single Responsibility Principle
 
-Le principe de responsabilité unique définit que chaque concept ou domaine d'activité ne s'occupe que d'une et d'une seule chose. 
-Traduit autrement, SRP nous dit qu’une classe ne devrait pas contenir plus d’une raison de changer. 
-Traduit encore autrement, «  for software systems to be easy to change, they must be designed to allow the behavior to change 
-by adding new code instead of changing existing code. 
+Le principe de responsabilité unique conseille de disposer de concepts ou domaines d'activité qui ne s'occupent chacun que d'une et une seule chose.
+Ceci rejoint un peu la https://en.wikipedia.org/wiki/Unix_philosophy[Philosophie Unix], documentée par Doug McIlroy et qui demande de "_faire une seule chose, mais le faire bien_" cite:{unix_philosophy}.
+Une classe ou un élément de programmtion ne doit donc pas avoir plus d'une raison de changer.
 
-Aussi : A module should be responsible to one and only one actor 
+Il est également possible d'étendre ce principe en fonction d'acteurs:
 
-Le principe de responsabilité unique diffère d’une vue logique qui tendrait intuitivement à centraliser le maximum de code. 
-A l’inverse, il faut plutôt penser à différencier les acteurs. 
-Un exemple donné consiste à identifier le CFO, CTO et COO qui ont tous besoin de données et informations relatives à une même 
-base de données des membres du personnel, mais ils ont chacun besoin de données différents 
-(ou en tout cas, d’une représentation différente de ces données). 
-Nous sommes d’accord qu’il s’agit à chaque fois de données liées aux employés, mais elles vont un cran plus loin et 
-pourraient nécessiter des ajustements spécifiques en fonction de l’acteur concerné. 
+> A module should be responsible to one and only one actor cite:{clean_architecture}
 
-L’idée sous-jacente est simplement d’identifier dès maintenant les différents acteurs, en vue de 
-prévoir une modification qui pourrait être demandée par l’un d’entre eux et qui pourrait avoir un 
-impact sur les données utilisées par les autres. 
+Plutôt que de centraliser le maximum de code à un seul endroit ou dans une seule classe par convenance ou commodité footnote:[Aussi appelé _God-Like object_], le principe de responsabilité unique suggère que chaque classe soit responsable d'un et un seul concept.
+Une autre manière de voir les choses consiste à différencier les acteurs ou les intervenants: imaginez avoir une classe représentant des données de membres du personnel.
+Ces données pourraient être demandées par trois acteurs, le CFO, le CTO et le COO: ceux-ci ont tous besoin de données et d'informations relatives à une même base de données centralisées, mais ont chacun besoin d'une représentation différente ou de traitements distincts. cite:{clean_architecture}
+Nous sommes d’accord qu’il s’agit à chaque fois de données liées aux employés, mais elles vont un cran plus loin et pourraient nécessiter des ajustements spécifiques en fonction de l’acteur concerné.
+L’idée sous-jacente est simplement d’identifier dès que possible les différents acteurs, en vue de prévoir une modification qui pourrait être demandée par l’un d’entre eux.
+Dans le cas d'un élément de code centralisé, une modification induite par un des acteurs pourrait ainsi avoir un impact sur les données utilisées par les autres.
 
-En prenant l'exemple d'une méthode qui communique avec une base de données, 
-ce ne sera pas à cette méthode à gérer l'inscription d'une exception à un emplacement quelconque. 
-Cette action doit être prise en compte par une autre classe (ou un autre concept), qui s'occupera elle de définir 
-l'emplacement où l'évènement sera enregistré (dans une base de données, une instance Graylog, un fichier, ...).
+[source,python]
+----
+class Document:
+    def __init__(self, title, content, published_at):
+        self.title = title
+        self.content = content
+        self.published_at = published_at
 
-Cette manière d'organiser le code ajoute une couche de flemmardise 
-(ie. Une fonction ou une méthode doit pouvoir se dire "_I don't care_" et s'occuper uniquement de ses propres oignons) 
-sur certains concepts. 
-Ceci permet de centraliser la configuration d'un type d'évènement à un seul endroit, ce qui augmente la testabilité du code.
+    def render(self, format_type):
+        if format_type == "XML":
+            return """<?xml version = "1.0"?>
+            <document>
+                <title>{}</title>
+                <content>{}</content>
+                <publication_date>{}</publication_date>
+            </document>""".format(
+                self.title,
+                self.content,
+                self.published_at.isoformat()
+            )
 
-Au niveau des composants, le SRP deviendra le CCP.
-Au niveau architectural, ce sera la définition des frontières (boundaries). 
+        if format_type == "Markdown":
+            import markdown
+            return markdown.markdown(self.content)
+
+        raise ValueError("Format type '{}' is not known".format(format_type))
+----
+
+Lorsque nous devrons ajouter un nouveau rendu (Atom, OpenXML, ...), nous devrons modifier la classe `Document`, ce qui n'est pas vraiment intuitif.
+Une bonne pratique consisterait à créer une classe de rendu par type de format à gérer:
+
+[source,python]
+----
+class Document:
+    def __init__(self, title, content, published_at):
+        self.title = title
+        self.content = content
+        self.published_at = published_at
+
+class DocumentRenderer:
+    def render(self, document):
+        if format_type == "XML":
+            return """<?xml version = "1.0"?>
+            <document>
+                <title>{}</title>
+                <content>{}</content>
+                <publication_date>{}</publication_date>
+            </document>""".format(
+                self.title,
+                self.content,
+                self.published_at.isoformat()
+            )
+
+        if format_type == "Markdown":
+            import markdown
+            return markdown.markdown(self.content)
+
+        raise ValueError("Format type '{}' is not known".format(format_type))
+----
+
+A présent, lorsque nous devrons ajouter un nouveau format de prise en charge, nous irons modifier la classe `DocumentRenderer`, sans que la classe `Document` ne soit impactée.
+En même temps, le jour où une instance de type `Document` sera liée à un champ `author`, rien ne dit que le rendu devra en tenir compte; nous modifierons donc notre classe pour y ajouter le nouveau champ sans que cela n'impacte nos différentes manières d'effectuer un rendu.
+
+En prenant l'exemple d'une méthode qui communique avec une base de données, ce ne sera pas à cette méthode à gérer l'inscription d'une exception à un emplacement quelconque.
+Cette action doit être prise en compte par une autre classe (ou un autre concept), qui s'occupera elle de définir l'emplacement où l'évènement sera enregistré (dans une base de données, une instance Graylog, un fichier, ...).
+
+Cette manière de structurer le code permet de centraliser la configuration d'un type d'évènement à un seul endroit, ce qui augmente ainsi la testabilité globale du projet.
+
+Lorsque nous verrons les composants, le SRP deviendra le CCP.
+Au niveau architectural, ce sera la définition des frontières (boundaries).
 
 ==== Open Closed
 
-L’objectif est de rendre le système facile à étendre, en évitant que l’impact d’une modification ne soit trop grand. 
+> For software systems to be easy to change, they must be designed to allow the behavior to change by adding new code instead of changing existing code.
 
-Les exemples parlent d’eux-mêmes: des données doivent être présentées dans une page web. 
-Et demain, ce seras dans un document PDF. 
-Et après demain, ce sera dans un tableur Excel. 
-La source de ces données restent la même (au travers d’une couche de présentation), mais la mise en forme diffère à chaque fois. 
+L’objectif est de rendre le système facile à étendre, en évitant que l’impact d’une modification ne soit trop grand.
 
-L’application n’a pas à connaître les détails d’implémentation: elle doit juste permettre une forme d’extension, 
-sans avoir à appliquer une modification (ou une grosse modification) sur son cœur. 
+Les exemples parlent d’eux-mêmes: des données doivent être présentées dans une page web.
+Et demain, ce seras dans un document PDF.
+Et après demain, ce sera dans un tableur Excel.
+La source de ces données restent la même (au travers d’une couche de présentation), mais la mise en forme diffère à chaque fois.
 
-Un des principes essentiels en programmation orientée objets concerne l'héritage de classes et la surcharge de méthodes: plutôt que de partir sur une série de comparaisons pour définir le comportement d'une instance, il est parfois préférable de définir une nouvelle sous-classe, qui surcharge une méthode bien précise. 
+L’application n’a pas à connaître les détails d’implémentation: elle doit juste permettre une forme d’extension,
+sans avoir à appliquer une modification (ou une grosse modification) sur son cœur.
+
+Un des principes essentiels en programmation orientée objets concerne l'héritage de classes et la surcharge de méthodes: plutôt que de partir sur une série de comparaisons pour définir le comportement d'une instance, il est parfois préférable de définir une nouvelle sous-classe, qui surcharge une méthode bien précise.
 Pour l'exemple, on pourrait ainsi définir trois classes:
 
 * Une classe `Customer`, pour laquelle la méthode `GetDiscount` ne renvoit rien;
 * Une classe `SilverCustomer`, pour laquelle la méthode revoit une réduction de 10%;
 * Une classe `GoldCustomer`, pour laquelle la même méthode renvoit une réduction de 20%.
 
-Si nous rencontrons un nouveau type de client, il suffit de créer une nouvelle sous-classe. 
+Si nous rencontrons un nouveau type de client, il suffit de créer une nouvelle sous-classe.
 Cela évite d'avoir à gérer un ensemble conséquent de conditions dans la méthode initiale, en fonction d'une autre variable (ici, le type de client).
 
 Nous passerions ainsi de:
@@ -98,7 +161,7 @@ class Customer():
     def get_discount(self) -> int:
         return 0
 
-    
+
 class SilverCustomer(Customer):
     def get_discount(self) -> int:
         return 10
@@ -114,48 +177,95 @@ class GoldCustomer(Customer):
 10
 ----
 
-En anglais, dans le texte : "Putting in simple words, the “Customer” class is now closed for any new modification 
-but it’s open for extensions when new customer types are added to the project.". 
-En résumé: nous fermons la classe `Customer` à toute modification, mais nous ouvrons la possibilité de 
-créer de nouvelles extensions en ajoutant de nouveaux types [héritant de `Customer`].
+En anglais, dans le texte : "_Putting in simple words, the “Customer” class is now closed for any new modification but it’s open for extensions when new customer types are added to the project._".
 
-De cette manière, nous simplifions également la maintenance de la méthode `get_discount`, 
-dans la mesure où elle dépend directement du type dans lequel elle est implémentée.
+*En résumé*: nous fermons la classe `Customer` à toute modification, mais nous ouvrons la possibilité de créer de nouvelles extensions en ajoutant de nouveaux types [héritant de `Customer`].
+
+De cette manière, nous simplifions également la maintenance de la méthode `get_discount`, dans la mesure où elle dépend directement du type dans lequel elle est implémentée.
+
+Nous pouvons également appliquer ceci à notre exemple sur les rendus de document, où le code suivant
+
+[source,python]
+----
+class DocumentRenderer:
+    def render(self, document):
+        if format_type == "XML":
+            return """<?xml version = "1.0"?>
+            <document>
+                <title>{}</title>
+                <content>{}</content>
+                <publication_date>{}</publication_date>
+            </document>""".format(
+                document.title,
+                document.content,
+                document.published_at.isoformat()
+            )
+
+        if format_type == "Markdown":
+            import markdown
+            return markdown.markdown(document.content)
+
+        raise ValueError("Format type '{}' is not known".format(format_type))
+----
+
+devient le suivant:
+
+[source,python]
+----
+class Renderer:
+    def render(self, document):
+        raise NotImplementedError
+
+class XmlRenderer(Renderer):
+    def render(self, document)
+        return """<?xml version = "1.0"?>
+            <document>
+                <title>{}</title>
+                <content>{}</content>
+                <publication_date>{}</publication_date>
+            </document>""".format(
+                document.title,
+                document.content,
+                document.published_at.isoformat()
+            )
+
+class MarkdownRenderer(Renderer):
+    def render(self, document):
+        import markdown
+        return markdown.markdown(document.content)
+----
+
+Lorsque nous ajouterons notre nouveau type de rendu, nous ajouterons simplement une nouvelle classe de rendu qui héritera de `Renderer`.
 
 Ce point sera très utile lorsque nous aborderons les https://docs.djangoproject.com/en/3.1/topics/db/models/#proxy-models[modèles proxy].
 
 ==== Liskov Substitution
 
 NOTE: Dans Clean Architecture, ce chapitre ci (le 9) est sans doute celui qui est le moins complet.
-Je suis d’accord avec les exemples donnés, dans la mesure où la définition concrète d’une classe doit dépendre 
-d’une interface correctement définie (et que donc, faire hériter un carré d’un rectangle, n’est pas adéquat 
-dans le mesure où cela induit l’utilisateur en erreur), mais il y est aussi question de la définition d'un 
-style architectural pour une interface REST, mais sans donner de solution…
+Je suis d’accord avec les exemples donnés, dans la mesure où la définition concrète d’une classe doit dépendre d’une interface correctement définie (et que donc, faire hériter un carré d’un rectangle, n’est pas adéquat dans le mesure où cela induit l’utilisateur en erreur), mais il y est aussi question de la définition d'un style architectural pour une interface REST, mais sans donner de solution...
 
-Le principe de substitution fait qu'une classe héritant d'une autre classe doit se comporter de la même manière que cette dernière. 
+Le principe de substitution fait qu'une classe héritant d'une autre classe doit se comporter de la même manière que cette dernière.
 Il n'est pas question que la sous-classe n'implémente pas certaines méthodes, alors que celles-ci sont disponibles sa classe parente.
 
 > [...] if S is a subtype of T, then objects of type T in a computer program may be replaced with objects of type S (i.e., objects of type S may be substituted for objects of type T), without altering any of the desirable properties of that program (correctness, task performed, etc.). (Source: http://en.wikipedia.org/wiki/Liskov_substitution_principle[Wikipédia]).
 
 > Let q(x) be a property provable about objects x of type T. Then q(y) should be provable for objects y of type S, where S is a subtype of T. (Source: http://en.wikipedia.org/wiki/Liskov_substitution_principle[Wikipédia aussi])
 
-Ce n'est donc pas parce qu'une classe **a besoin d'une méthode définie dans une autre classe** qu'elle doit forcément en hériter. 
+Ce n'est donc pas parce qu'une classe **a besoin d'une méthode définie dans une autre classe** qu'elle doit forcément en hériter.
 Cela bousillerait le principe de substitution, dans la mesure où une instance de cette classe pourra toujours être considérée comme étant du type de son parent.
 
-Petit exemple pratique: si nous définissons une méthode `walk` et une méthode `eat` sur une classe `Duck`, 
-et qu'une réflexion avancée (et sans doute un peu alcoolisée) nous dit que 
-"Puisqu'un `Lion` marche aussi, faisons le hériter de notre classe `Canard`":
+Petit exemple pratique: si nous définissons une méthode `walk` et une méthode `eat` sur une classe `Duck`, et qu'une réflexion avancée (et sans doute un peu alcoolisée) nous dit que "_Puisqu'un `Lion` marche aussi, faisons le hériter de notre classe `Canard`"_, nous allons nous retrouver avec ceci:
 
 [source,python]
 ----
-class Duck():
+class Duck:
     def walk(self):
         print("Kwak")
 
     def eat(self, thing):
         if thing in ("plant", "insect", "seed", "seaweed", "fish"):
             return "Yummy!"
-        
+
         raise IndigestionError("Arrrh")
 
 class Lion(Duck):
@@ -164,27 +274,75 @@ class Lion(Duck):
 
 ----
 
+Le principe de substitution de Liskov suggère qu'une classe doit toujours pouvoir être considérée comme une instance de sa classe parent, et *doit pouvoir s'y substituer*.
+Dans notre exemple, cela signifie que nous pourrons tout à fait accepter qu'un lion se comporte comme un canard et adore manger des plantes, insectes, graines, algues et du poisson. Miam !
 Nous vous laissons tester la structure ci-dessus en glissant une antilope dans la boite à goûter du lion, ce qui nous donnera quelques trucs bizarres (et un lion atteint de botulisme).
 
+Pour revenir à nos exemples de rendus de documents, nous aurions pu faire hériter notre `MarkdownRenderer` de la classe `XmlRenderer`:
 
-==== Interface Segregation
+[source,python]
+----
+class XmlRenderer:
+    def render(self, document)
+        return """<?xml version = "1.0"?>
+            <document>
+                <title>{}</title>
+                <content>{}</content>
+                <publication_date>{}</publication_date>
+            </document>""".format(
+                document.title,
+                document.content,
+                document.published_at.isoformat()
+            )
 
-L’objectif est de limiter la nécessité de compilation en n’exposant que les opérations nécessaires 
-à l’exécution d’une classe, et pour éviter d’avoir à redéployer l’ensemble d’une application.
-En Python, c’est inféré lors de l’exécution, et donc pas vraiment d’application pour notre contexte d'étude.
-De manière générale, les langages dynamiques sont plus flexibles et moins couples que les langages statiquement 
-typés, pour lesquels il serait possible de mettre à jour une DLL ou un JAR sans que cela n’ait d’impact sur le 
-reste de l’application.
+class MarkdownRenderer(XmlRenderer):
+    def render(self, document):
+        import markdown
+        return markdown.markdown(document.content)
+----
+
+Mais lorsque nous ajouterons une fonction d'entête, notre rendu en Markdown héritera irrémédiablement de cette même méthode:
+
+[source,python]
+----
+class XmlRenderer:
+    def header(self):
+        return """<?xml version = "1.0"?>"""
+
+    def render(self, document)
+        return """{}
+            <document>
+                <title>{}</title>
+                <content>{}</content>
+                <publication_date>{}</publication_date>
+            </document>""".format(
+                self.header(),
+                document.title,
+                document.content,
+                document.published_at.isoformat()
+            )
+
+class MarkdownRenderer(XmlRenderer):
+    def render(self, document):
+        import markdown
+        return markdown.markdown(document.content)
+----
+
+A nouveau, lorsque nous invoquerons la méthode `header()` sur une instance de type `MarkdownRenderer`, nous obtiendrons un bloc de déclaration XML (`<?xml version = "1.0"?>`) pour un fichier Markdown.
+
+
+==== Interface Segregation Principle
+
+Le principe de ségrégation d'interface suggère de limiter la nécessité de recompiler un module, en n’exposant que les opérations nécessaires à l’exécution d’une classe.
+Ceci évite d’avoir à redéployer l’ensemble d’une application.
 
 > The lesson here is that depending on something that carries baggage that you don’t need can cause you troubles that you didn’t except.
 
-Ce principe stipule qu'un client ne peut en aucun cas dépendre d'une méthode dont il n'a pas besoin. 
-Plus simplement, plutôt que de dépendre d'une seule et même (grosse) interface présentant un ensemble conséquent de méthodes, 
-il est proposé d'exploser cette interface en plusieurs (plus petites) interfaces. 
-Ceci permet aux différents consommateurs de n'utiliser qu'un sous-ensemble précis d'interfaces, 
-répondant chacune à un besoin précis.
+Ce principe stipule qu'un client ne peut en aucun cas dépendre d'une méthode dont il n'a pas besoin.
+Plus simplement, plutôt que de dépendre d'une seule et même (grosse) interface présentant un ensemble conséquent de méthodes, il est proposé d'exploser cette interface en plusieurs (plus petites) interfaces.
+Ceci permet aux différents consommateurs de n'utiliser qu'un sous-ensemble précis d'interfaces, répondant chacune à un besoin précis.
 
-Un exemple est d'avoir une interface permettant d'accéder à des éléments. 
+Un exemple est d'avoir une interface permettant d'accéder à des éléments.
 Modifier cette interface pour permettre l'écriture impliquerait que toutes les applications ayant déjà accès à la première, obtiendraient (par défaut) un accès en écriture, ce qui n'est pas souhaité/souhaitable.
 
 Pour contrer ceci, on aurait alors une première interface permettant la lecture, tandis qu'une deuxième (héritant de la première) permettrait l'écriture. On aurait alors le schéma suivant :
@@ -192,30 +350,32 @@ Pour contrer ceci, on aurait alors une première interface permettant la lecture
 * A : lecture
 * B (héritant de A) : lecture (par A) et écriture.
 
-Mais ceci s'applique finalement à n'importe quel composant: votre système d'exploitation, les librairies et dépendances tierces, 
-les variables déclarées, ... 
+Mais ceci s'applique finalement à n'importe quel composant: votre système d'exploitation, les librairies et dépendances tierces,
+les variables déclarées, ...
+
+En Python, ce comportement est inféré lors de l’exécution, et donc pas vraiment d’application pour notre contexte d'étude: de manière plus générale, les langages dynamiques sont plus flexibles et moins couplés que les langages statiquement typés, pour lesquels l'application de ce principe-ci permettrait de mettre à jour une DLL ou un JAR sans que cela n’ait d’impact sur le reste de l’application.
 
 ==== Dependency inversion Principle
 
-Dans une architecture conventionnelle, les composants de haut-niveau dépendent directement des composants de bas-niveau. 
+Dans une architecture conventionnelle, les composants de haut-niveau dépendent directement des composants de bas-niveau.
 L'inversion de dépendances stipule que c'est le composant de haut-niveau qui possède la définition de l'interface dont il a besoin, et le composant de bas-niveau qui l'implémente.
 
-> The dependency inversion principle tells us that the most flexible systems are those in which source code dependencies 
+> The dependency inversion principle tells us that the most flexible systems are those in which source code dependencies
 refer only to abstractions, not to concretions.
 
-L’objectif est que les interfaces soient stables, et de réduire au maximum les modifications qui pourraient y être appliquées. 
+L’objectif est que les interfaces soient stables, et de réduire au maximum les modifications qui pourraient y être appliquées.
 De la meme manière, il convient d’éviter de surcharger des fonctions ou des classes concrètes (= non abstraites).
 
-En termes architecturaux, ce principe définira les frontières dont il a déjà été question, 
-en demandant à ce qu’une délimitation ne se base que sur une dépendance qui soit … 
-cela permet notamment une séparation claire au niveau des frontières, en inversant le flux de dépendance et en faisant en sorte (par exemple) que les règles métiers n’aient aucune connaissance des interfaces graphiques qui les exploitent. Ces interfaces pouvant être desktop, web, … cela n’a pas vraiment d’importance. Cela autorise une for.e d’immunité entre les composants. 
+En termes architecturaux, ce principe définira les frontières dont il a déjà été question,
+en demandant à ce qu’une délimitation ne se base que sur une dépendance qui soit …
+cela permet notamment une séparation claire au niveau des frontières, en inversant le flux de dépendance et en faisant en sorte (par exemple) que les règles métiers n’aient aucune connaissance des interfaces graphiques qui les exploitent. Ces interfaces pouvant être desktop, web, … cela n’a pas vraiment d’importance. Cela autorise une for.e d’immunité entre les composants.
 
-Ne pas oublier qu’écrire du nouveau code est toujours plus facile que de modifier du code existant. 
+Ne pas oublier qu’écrire du nouveau code est toujours plus facile que de modifier du code existant.
 
 > The database is really nothing more than a big bucket of bits where we store our data on a long term basis (the database is a detail, chap 30, page 281)
 D’un point de vue architectural, nous ne devons pas nous soucier de la manière dont les données sont stockées, s’il s’agit d’un disque magnétique, de ram, … en fait, on ne devrait même pas savoir s’il y a un disque du tout.
 
-Le composant de haut-niveau peut définir qu'il s'attend à avoir un `Publisher`, afin de publier du contenu vers un emplacement particulier. 
+Le composant de haut-niveau peut définir qu'il s'attend à avoir un `Publisher`, afin de publier du contenu vers un emplacement particulier.
 Plusieurs implémentation de cette interface peuvent alors être mise en place:
 
  * Une publication par SSH
@@ -235,24 +395,24 @@ L'injection de dépendances est un patron de programmation qui suit le principe
 
 === au niveau des composants
 
-De la même manière que pour les principes définis ci-dessus, 
-Mais toujours en faisant attention qu’une fois que les frontières sont implémentés, elles sont coûteuses à maintenir. 
-Cependant, il ne s’agit pas une décision à réaliser une seule fois, puisque cela peut être réévalué. 
+De la même manière que pour les principes définis ci-dessus,
+Mais toujours en faisant attention qu’une fois que les frontières sont implémentés, elles sont coûteuses à maintenir.
+Cependant, il ne s’agit pas une décision à réaliser une seule fois, puisque cela peut être réévalué.
 
-Et de la même manière que nous devons délayer au maximum les choix architecturaux et techniques, 
+Et de la même manière que nous devons délayer au maximum les choix architecturaux et techniques,
 
-> but this is not a one time decision. You don’t simply decide at the start of a project which boundaries to implémentent and which to ignore. Rather, you watch. You pay attention as the system evolves. You note where boundaries may be required, and then carefully watch for the first inkling of friction because those boundaries don’t exist. 
-> at that point, you weight the costs of implementing those boundaries versus the cost of ignoring them and you review that decision frequently. Your goal is to implement the boundaries right at the inflection point where the cost of implementing becomes less than the cost of ignoring. 
+> but this is not a one time decision. You don’t simply decide at the start of a project which boundaries to implémentent and which to ignore. Rather, you watch. You pay attention as the system evolves. You note where boundaries may be required, and then carefully watch for the first inkling of friction because those boundaries don’t exist.
+> at that point, you weight the costs of implementing those boundaries versus the cost of ignoring them and you review that decision frequently. Your goal is to implement the boundaries right at the inflection point where the cost of implementing becomes less than the cost of ignoring.
 
-En gros, il faut projeter sur la capacité à s’adapter en minimisant la maintenance. 
+En gros, il faut projeter sur la capacité à s’adapter en minimisant la maintenance.
 Le problème est qu’elle ne permettait aucune adaptation, et qu’à la première demande, l’architecture se plante complètement sans aucune malléabilité.
 
 
-==== Reuse/release equivalence principle 
+==== Reuse/release equivalence principle
 
 [quote]
 ----
-Classes and modules that are grouped together into a component should be releasable together 
+Classes and modules that are grouped together into a component should be releasable together
 -- (Chapitre 13, Component Cohesion, page 105)
 ----
 
@@ -260,13 +420,13 @@ Classes and modules that are grouped together into a component should be releasa
 
 (= l’équivalent du SRP, mais pour les composants)
 
-> If two classes are so tightly bound, either physically or conceptually, that they always change together, then they belong in the same component 
+> If two classes are so tightly bound, either physically or conceptually, that they always change together, then they belong in the same component
 
 Il y a peut-être aussi un lien à faire avec « Your code as a crime scene » 🤟
 
  La définition exacte devient celle-ci: « gather together those things that change at the same times and for the same reasons. Separate those things that change at different times or for different reasons ».
 
- ==== CRP 
+ ==== CRP
 
  … que l’on résumera ainsi: « don’t depend on things you don’t need » 😘
 Au niveau des composants, au niveau architectural, mais également à d’autres niveaux.
@@ -274,11 +434,11 @@ Au niveau des composants, au niveau architectural, mais également à d’autres
 ==== SDP
 
 (Stable dependency principle) qui définit une formule de stabilité pour les composants, en fonction de sa faculté à être modifié et des composants qui dépendent de lui: au plus un composant est nécessaire, au plus il sera stable (dans la mesure où il lui sera difficile de changer). En C++, cela correspond aux mots clés #include.
-Pour faciliter cette stabilité, il convient de passer par des interfaces (donc, rarement modifiées, par définition).  
+Pour faciliter cette stabilité, il convient de passer par des interfaces (donc, rarement modifiées, par définition).
 
-En Python, ce ratio pourrait être calculé au travers des import, via les AST. 
+En Python, ce ratio pourrait être calculé au travers des import, via les AST.
 
 ==== SAP
 
-(= Stable abstraction principle) pour la définition des politiques de haut niveau vs les composants plus concrets. 
-SAP est juste une modélisation du OCP pour les composants: nous plaçons ceux qui ne changent pas ou pratiquement pas le plus haut possible dans l’organigramme (ou le diagramme), et ceux qui changent souvent plus bas, dans le sens de stabilité du flux. Les composants les plus bas sont considérés comme volatiles 
+(= Stable abstraction principle) pour la définition des politiques de haut niveau vs les composants plus concrets.
+SAP est juste une modélisation du OCP pour les composants: nous plaçons ceux qui ne changent pas ou pratiquement pas le plus haut possible dans l’organigramme (ou le diagramme), et ceux qui changent souvent plus bas, dans le sens de stabilité du flux. Les composants les plus bas sont considérés comme volatiles

source/part-3-data-model/_index.adoc

@@ -1,12 +1,12 @@
-= (meta)Data Model
+= Principes fondamentaux
 
-Dans ce chapitre, nous allons parler de plusieurs concepts utiles au développement rapide d'une application.
+Dans ce chapitre, nous allons parler de plusieurs concepts fondamentaux au développement rapide d'une application.
 Nous parlerons de modélisation, de métamodèle, de migrations, d'administration auto-générée, de traductions et de cycle de vie des données.
 
-Django est un framework Web proposant une très bonne intégration des composants et une flexibilité bien pensée: chacun des composants permet de définir son contenu de manière poussée, en respectant des contraintes logiques et faciles à retenir.
-Pour un néophyte, la courbe d'apprentissage sera relativement ardue; à côté de concepts clés de Django, il conviendra également d'assimiler correctement les structures de données du langage Python, le cycle de vie d'une requête HTTP
+Django est un framework Web qui propose une très bonne intégration des composants et une flexibilité bien pensée: chacun des composants permet de définir son contenu de manière poussée, en respectant des contraintes logiques et faciles à retenir, et en gérant ses dépendances de manière autonome.
+Pour un néophyte, la courbe d'apprentissage sera relativement ardue: à côté de concepts clés de Django, il conviendra également d'assimiler correctement les structures de données du langage Python, le cycle de vie des requêtes HTTP et le B.A-BA des principes de sécurité.
 
-En restant dans les sentiers battus, votre projet suivra un dérivé du patron de conception `MVC` (Modèle-Vue-Controleur), où la variante concerne les termes utilisés: Django les nomme respectivement Modèle-Template-Vue et leur contexte d'utilisation.
+En restant dans les sentiers battus, votre projet suivra un patron de conception dérivé du modèle `MVC` (Modèle-Vue-Controleur), où la variante concerne les termes utilisés: Django les nomme respectivement Modèle-Template-Vue et leur contexte d'utilisation.
 Dans un *pattern* MVC classique, la traduction immédiate du **contrôleur** est une **vue**.
 Et comme on le verra par la suite, la **vue** est en fait le **template**.
 

source/part-3-data-model/admin.adoc

@@ -265,3 +265,13 @@ if rows_updated = 0:
 else:
 	self.message_user(request, "{} élément(s) mis à jour".format(rows_updated))
 ----
+
+=== La documentation
+
+Nous l'avons dit plus haut, l'administration de Django a également la possibilité de rendre accessible la documentation associée à un modèle de données.
+Pour cela, il suffit de suivre les bonnes pratiques, puis https://docs.djangoproject.com/en/stable/ref/contrib/admin/admindocs/[d'activer la documentation à partir des URLs]:
+
+[source,python]
+----
+
+----

source/part-3-data-model/models.adoc

@@ -1,29 +1,29 @@
 == Modélisation
 
 Ce chapitre aborde la modélisation des objets et les options qui y sont liées.
-Avec Django, la modélisation est en lien direct avec la conception et le stockage de la base de données relationnelle, et la manière dont ces données s'agencent et communiquent entre elles.
+Avec Django, la modélisation est en lien direct avec la conception et le stockage, sous forme d'une base de données relationnelle, et la manière dont ces données s'agencent et communiquent entre elles.
 
-Django utilise un paradigme de type https://fr.wikipedia.org/wiki/Mapping_objet-relationnel[ORM] - c'est-à-dire que chaque type d'objet manipulé peut s'apparenter à une table SQL, tout en ajoutant une couche propre à la programmation orientée object.
+Django utilise un paradigme de persistence des données de type https://fr.wikipedia.org/wiki/Mapping_objet-relationnel[ORM] - c'est-à-dire que chaque type d'objet manipulé peut s'apparenter à une table SQL, tout en respectant une approche propre à la programmation orientée object.
 Plus spécifiquement, l'ORM de Django suit le patron de conception https://en.wikipedia.org/wiki/Active_record_pattern[Active Records], comme le font par exemple https://rubyonrails.org/[Rails] pour Ruby ou https://docs.microsoft.com/fr-fr/ef/[EntityFramework] pour .Net.
 
 Le modèle de données de Django est sans doute la (seule ?) partie qui soit tellement couplée au framework qu'un changement à ce niveau nécessitera une refonte complète de beaucoup d'autres briques de vos applications; là où un pattern de type https://www.martinfowler.com/eaaCatalog/repository.html[Repository] permettrait justement de découpler le modèle des données de l'accès à ces mêmes données, un pattern Active Record lie de manière extrêmement forte le modèle à sa persistence.
+Architecturalement, c'est sans doute la plus grosse faiblesse de Django, à tel point que *ne pas utiliser cette brique de fonctionnalités* peut remettre en question le choix du framework.
+Conceptuellement, c'est pourtant la manière de faire qui permettra d'avoir quelque chose à présenter très rapidement: à partir du moment où vous aurez un modèle de données, vous aurez accès, grâce à cet ORM à:
 
-Architecturalement, c'est sans doute la plus grosse faiblesse de Django.
-Conceptuellement, c'est pourtant la manière de faire qui permettra d'avoir quelque chose à présenter très rapidement: à partir du moment où vous aurez un modèle de données, vous aurez accès, grâce à Django:
-
-1. Aux migrations de données,
-2. A un découplage complet entre le moteur de données relationnel et le modèle de données,
-3. A une interface d'administration auto-générée
-4. A un mécanisme de formulaires HTML qui soit complet, pratique à utiliser, orienté objet et facile à faire évoluer,
-5. De définir des notions d'héritage (tout en restant dans une forme d'héritage simple).
+1. Des migrations de données,
+2. Un découplage complet entre le moteur de données relationnel et le modèle de données,
+3. Une interface d'administration auto-générée
+4. Un mécanisme de formulaires HTML qui soit complet, pratique à utiliser, orienté objet et facile à faire évoluer,
+5. Une définition des notions d'héritage (tout en restant dans une forme d'héritage simple).
 
 Comme tout ceci reste au niveau du code, cela suit également la méthodologie des douze facteurs, concernant la minimisation des divergences entre environnements d'exécution: comme tout se trouve au niveau du code, il n'est plus nécessaire d'avoir un DBA qui doive démarrer un script sur un serveur au moment de la mise à jour, de recevoir une release note de 512 pages en PDF reprenant les modifications ou de nécessiter l'intervention de trois équipes différentes lors d'une modification majeure du code.
 Déployer une nouvelle instance de l'application pourra être réalisé directement à partir d'une seule et même commande.
 
-_A contrario_, ces avantages sont balancés au travers d'un couplage extrêmement fort entre la modélisation et le reste du framework - à tel point que *ne pas utiliser cette brique de fonctionnalités* peut remettre en question le choix du framework.
-En plus de ceci, l'implémentation d'Active Records reste une forme hybride entre une structure de données brutes et une classe: là où une classe va exposer ses données derrière une forme d'abstraction et n'exposer que les fonctions qui opèrent sur ces données, une structure de données ne va exposer que ses champs et propriétés, et ne va pas avoir de functions significatives.
+=== Active Records
 
-L'exemple ci-dessous (en Java) présente trois structure de données, qui exposent chacune ses propres champs:
+Il faut noter que l'implémentation d'Active Records reste une forme hybride entre une structure de données brutes et une classe: là où une classe va exposer ses données derrière une forme d'abstraction et n'exposer que les fonctions qui opèrent sur ces données, une structure de données ne va exposer que ses champs et propriétés, et ne va pas avoir de functions significatives.
+
+L'exemple ci-dessous présente trois structure de données, qui exposent chacune leurs propres champs:
 
 [source,python]
 ----
@@ -105,24 +105,27 @@ class Circle(Shape):
 ----
 
 On le voit: une structure brute peut être rendue abstraite au travers des notions de programmation orientée objet.
-Dans l'exemple géométrique ci-dessus, repris de cite:[clean_code, 95-97], l'accessibilité des champs devient restreinte, tandis que la fonction `area()` bascule comme méthode d'instance plutôt qu'isolée au niveau d'un visiteur.
+Dans l'exemple géométrique ci-dessus, repris de cite:[clean_code, 95-97], l'accessibilité des champs devient restreinte, tandis que la fonction `area()` bascule comme méthode d'instance plutôt que de l'isoler au niveau d'un visiteur.
 Nous ajoutons une abstraction au niveau des formes grâce à un héritage sur la classe `Shape`; indépendamment de ce que nous manipulerons, nous aurons la possibilité de calculer son aire.
 
 Une structure de données permet de facilement gérer des champs et des propriétés, tandis qu'une classe gère et facilite l'ajout de fonctions et de méthodes.
 
-Le problème d'Active Records est que chaque classe s'apparente à une table SQL et revient donc à gérer des _DTO_ ou _Data Transfer Object_, c'est-à-dire des objets de correspondance pure et simple les champs de la base de données et les propriétés de la programmation orientée objet, c'est-à-dire également des classes sans fonctions.
-Or, chaque classe a également la possibilité d'exposer des possibilités d'interactions au niveau de la persistence, en https://docs.djangoproject.com/en/stable/ref/models/instances/#django.db.models.Model.save[enregistrant ses propres données] ou en en autorisant la https://docs.djangoproject.com/en/stable/ref/models/instances/#deleting-objects[suppression].
-Nous arrivons alors à un modèle hybride, mélangeant des structures de données et des classes d'abstraction, ce qui restera parfaitement viable tant que l'on garde ces principes en tête et que l'on se prépare à une éventuelle réécriture ultérieure.
+Le problème d'Active Records est que chaque classe s'apparente à une table SQL et revient donc à gérer des _DTO_ ou _Data Transfer Object_, c'est-à-dire des objets de correspondance pure et simple entre les champs de la base de données et les propriétés de la programmation orientée objet, c'est-à-dire également des classes sans fonctions.
+Or, chaque classe a également la possibilité d'exposer des possibilités d'interactions au niveau de la persistence, en https://docs.djangoproject.com/en/stable/ref/models/instances/#django.db.models.Model.save[enregistrant ses propres données] ou en en autorisant leur https://docs.djangoproject.com/en/stable/ref/models/instances/#deleting-objects[suppression].
+Nous arrivons alors à un modèle hybride, mélangeant des structures de données et des classes d'abstraction, ce qui restera parfaitement viable tant que l'on garde ces principes en tête et que l'on se prépare à une éventuelle réécriture du code.
 
 Lors de l'analyse d'une classe de modèle, nous pouvons voir que Django exige un héritage de la classe `django.db.models.Model`.
 Nous pouvons regarder les propriétés définies dans cette classe en analysant le fichier `lib\site-packages\django\models\base.py`.
 Outre que `models.Model` hérite de `ModelBase` au travers de https://pypi.python.org/pypi/six[six] pour la rétrocompatibilité vers Python 2.7, cet héritage apporte notamment les fonctions `save()`, `clean()`, `delete()`, ...
-En résumé, toutes les méthodes qui font qu'une instance est sait **comment** interagir avec la base de données.
+En résumé, toutes les méthodes qui font qu'une instance sait **comment** interagir avec la base de données.
 
-=== Types de champs, clés étrangères et relations
+=== Types de champs
+
+
+=== Relations et clés étrangères
 
 Nous l'avons vu plus tôt, Python est un langage dynamique et fortement typé.
-Django, de son côté, ajoute une couche de typage statique exigé par le lien avec le moteur de base de données relationnelle sous-jacent.
+Django, de son côté, ajoute une couche de typage statique exigé par le lien sous-jacent avec le moteur de base de données relationnelle.
 Dans le domaine des bases de données relationnelles, un point d'attention est de toujours disposer d'une clé primaire pour nos enregistrements.
 Si aucune clé primaire n'est spécifiée, Django s'occupera d'en ajouter une automatiquement et la nommera (par convention) `id`.
 Elle sera ainsi accessible autant par cette propriété que par la propriété `pk`.
@@ -137,24 +140,60 @@ class Category(models.Model):
     name = models.CharField(max_length=255)
 
 class Book(models.Model):
-    author = models.CharField(max_length=255)
     title = models.CharField(max_length=255)
     category = models.ForeignKey(Category, on_delete=models.CASCADE)
 ----
 
+Par défaut, et si aucune propriété ne dispose d'un attribut `primary_key=True`, Django s'occupera d'ajouter un champ `id` grâce à son héritage de la classe `models.Model`.
+Les autres champs nous permettent d'identifier une catégorie (`Category`) par un nom, tandis qu'un livre (`Book`) le sera par ses propriétés `title` et une clé de relation vers une catégorie.
+Un livre est donc lié à une catégorie, tandis qu'une catégorie est associée à plusieurs livres.
 
+image::diagrams/books-foreign-keys-example.drawio.png[]
 
-. ForeignKey
-. ManyToManyField
-. OneToOneField
+En termes de code d'initialisation, cela revient écrire ceci:
 
-Dans les examples ci-dessus, nous avons vu les relations multiples (1-N), représentées par des clés étrangères (**ForeignKey**) d'une classe A vers une classe B.
-Pour représenter d'autres types de relations, il existe également les champs de type *ManyToManyField*, afin de représenter une relation N-N. Les champs de type *OneToOneField*, pour représenter une relation 1-1.
+[source,python]
+----
+from library.models import Book, Category
 
-Dans notre modèle ci-dessus, nous n'avons jusqu'à présent eu besoin que des relations 1-N:
+movies = Category.objects.create(name="Adaptations au cinéma")
+medieval = Category.objects.create(name="Médiéval-Fantastique")
+science_fiction = Category.objects.create(name="Sciences-fiction")
+computers = Category.objects.create(name="Sciences Informatiques")
 
-. La première entre les listes de souhaits et les souhaits;
-. La seconde entre les souhaits et les parts.
+books = {
+    "Harry Potter": movies,
+    "The Great Gatsby": movies,
+    "Dune": science_fiction,
+    "H2G2": science_fiction,
+    "Ender's Game": science_fiction,
+    "Le seigneur des anneaux": medieval,
+    "L'Assassin Royal", medieval,
+    "Clean code": computers,
+    "Designing Data-Intensive Applications": computers
+}
+
+for book_title, category in books.items:
+    Book.objects.create(name=book_title, category=category)
+----
+
+Nous nous rendons rapidement compte qu'un livre peut appartenir à plusieurs catégories: _Dune_ a été adapté au cinéma en 1973 et en 2021, de même que _Le Seigneur des Anneaux_, _The Great Gatsby_, et sans doute que nous pourrons étoffer notre bibliothèque avec une catégorie spéciale "Baguettes magiques et trucs phalliques", à laquelle nous pourrons associer la saga _Harry Potter_.
+En clair, notre modèle n'est pas adapté, et nous devons le modifier pour que notre clé étrangère accepte plusieurs valeurs.
+Ceci peut être fait au travers d'un champ de type `ManyToMany`, c'est-à-dire qu'un livre peut être lié à plusieurs catégories, et qu'une catégorie peut être liée à plusieurs livres.
+
+[source,python,highlight=6]
+----
+class Category(models.Model):
+    name = models.CharField(max_length=255)
+
+class Book(models.Model):
+    title = models.CharField(max_length=255)
+    category = models.ManyManyField(Category, on_delete=models.CASCADE)
+----
+
+Notre code d'initialisation reste par contre identique: Django s'occupe parfaitement de gérer la transition.
+
+==== Accès aux relations
 
 [source,python]
 ----
@@ -172,6 +211,7 @@ Depuis le code, à partir de l'instance de la classe `Item`, on peut donc accéd
 
 Lorsque vous déclarez une relation 1-1, 1-N ou N-N entre deux classes, vous pouvez ajouter l'attribut `related_name` afin de nommer la relation inverse.
 
+
 [source,python]
 ----
 # wish/models.py
@@ -186,8 +226,7 @@ class Item(models.Model):
 
 NOTE: Si, dans une classe A, plusieurs relations sont liées à une classe B, Django ne saura pas à quoi correspondra la relation inverse.
 Pour palier à ce problème, nous fixons une valeur à l'attribut `related_name`.
-Par facilité (et pas conventions), prenez l'habitude de toujours ajouter cet attribut.
-Votre modèle gagnera en cohérence et en lisibilité.
+Par facilité (et par conventions), prenez l'habitude de toujours ajouter cet attribut: votre modèle gagnera en cohérence et en lisibilité.
 Si cette relation inverse n'est pas nécessaire, il est possible de l'indiquer (par convention) au travers de l'attribut `related_name="+"`.
 
 A partir de maintenant, nous pouvons accéder à nos propriétés de la manière suivante:
@@ -207,16 +246,28 @@ A partir de maintenant, nous pouvons accéder à nos propriétés de la manière
 [<Item: Item object>]
 ----
 
+==== N+1 Queries
+
+
+=== Unicité
+
+
+=== Indices
+
+
+==== Conclusions
+
+Dans les examples ci-dessus, nous avons vu les relations multiples (1-N), représentées par des clés étrangères (**ForeignKey**) d'une classe A vers une classe B.
+Pour représenter d'autres types de relations, il existe également les champs de type *ManyToManyField*, afin de représenter une relation N-N.
+Il existe également un type de champ spécial pour les clés étrangères, qui est le Les champs de type *OneToOneField*, pour représenter une relation 1-1.
 
 ==== Metamodèle et introspection
 
-
-
-D'autre part, chaque classe héritant de `models.Model` possède une propriété `objects`. Comme on l'a vu dans la section **Jouons un peu avec la console**, cette propriété permet d'accéder aux objects persistants dans la base de données, au travers d'un `ModelManager`.
+Comme chaque classe héritant de `models.Model` possède une propriété `objects`. Comme on l'a vu dans la section **Jouons un peu avec la console**, cette propriété permet d'accéder aux objects persistants dans la base de données, au travers d'un `ModelManager`.
 
 En plus de cela, il faut bien tenir compte des propriétés `Meta` de la classe: si elle contient déjà un ordre par défaut, celui-ci sera pris en compte pour l'ensemble des requêtes effectuées sur cette classe.
 
-[source,python]
+[source,python,highlight=5]
 ----
 class Wish(models.Model):
     name = models.CharField(max_length=255)
@@ -224,7 +275,7 @@ class Wish(models.Model):
     class Meta:
         ordering = ('name',) <1>
 ----
-<1> On définit un ordre par défaut, directement au niveau du modèle. Cela ne signifie pas qu'il ne sera pas possible de modifier cet ordre (la méthode `order_by` existe et peut être chaînée à n'importe quel queryset). D'où l'intérêt de tester ce type de comportement, dans la mesure où un `top 1` dans votre code pourrait être modifié simplement par cette petite information.
+<1> Nous définissons un ordre par défaut, directement au niveau du modèle. Cela ne signifie pas qu'il ne sera pas possible de modifier cet ordre (la méthode `order_by` existe et peut être chaînée à n'importe quel _queryset_). D'où l'intérêt de tester ce type de comportement, dans la mesure où un `top 1` dans votre code pourrait être modifié simplement par cette petite information.
 
 Pour sélectionner un objet au pif : `return Category.objects.order_by("?").first()`
 
@@ -269,85 +320,7 @@ class Runner(models.Model):
 
 
 
-==== Protocoles de langage (*dunder methods*)
 
-The Python data model specifies a lot of specially named methods that can be overridden in your custom classes to provide
-them with additional syntax capabilities.
-You can recognize these methods by their specific naming conventions that wrap the method name with double underscores.
-Because of this, they are sometimes referred to as dunder methods.
-It is simply shorthand for double underscores.The most common and obvious example of such dunder methods is __init__(),
-which is used for class instance initialization:
-
-[source,python]
-----
-class CustomUserClass:
-    def __init__(self, initiatization_argument):
-        ...
-----
-
-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 *dunder methods* (*double-underscores methods*) pour étoffer les protocoles du langage.
-
-These methods, either alone or when defined in a specific combination, constitute the so-called language protocols.
-If we say that an object implements a specific language protocol, it means that it is compatible with a specific part of the Python language syntax. The following is a table of the most common protocols within the Python language.Protocol nameMethodsDescriptionCallable protocol__call__()Allows objects to be called with parentheses:instance()Descriptor protocols__set__(), __get__(), and __del__()Allows us to manipulate the attribute access pattern of classes (see the Descriptors section)Container protocol__contains__()Allows us to test whether or not an object contains some value using the in keyword:value in instance
-Python in Comparison with Other LanguagesIterable protocol__iter__()Allows objects to be iterated using the forkeyword:for value in instance:    ...Sequence protocol__getitem__(),__len__()Allows objects to be indexed with square bracket syntax and queried for length using a built-in function:item = instance[index]length = len(instance)Each operator 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
-
-A full list of available dunder methods can be found in the Data model section of the official Python documentation available
-at https://docs.python.org/3/reference/datamodel.html.
-All operators are also exposed as ordinary functions in the operators module.
-The documentation of that module gives a good overview of Python operators.
-It can be found at https://docs.python.org/3.9/library/operator.html
-
-The `__add__()` method is responsible for overloading the `+` (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 `__sub__()` method is responsible for overloading the `–` (minus sign) operator that will be responsible for matrix subtraction.
-To subtract two matrices, we use a similar technique as in the – operator:
-
-[source,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)    ])
-----
-
-And the following is the last method we add to our class:
-
-[source,python]
-----
-def __mul__(self, other):
-    if not isinstance(other, Matrix):
-        raise TypeError(f"Don't know how to multiply {type(other)} with Matrix")
-
-    if len(self.rows[0]) != len(other.rows):
-        raise ValueError("Matrix dimensions don't match")
-
-    rows = [[0 for _ in other.rows[0]]  for _ in self.rows]
-
-    for i in range(len (self.rows)):
-        for j in range(len (other.rows[0])):
-            for k in range(len (other.rows)):
-                rows[i][j] += self.rows[i][k] * other.rows[k][j]
-
-    return Matrix(rows)
-----
-
-The last overloaded operator is the most complex one.
-This is the `*` operator, which is implemented through the `__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
-
-(Voir Expert Python Programming, 4th Edition, page 142-144)
 
 ==== Constructeurs
 

source/part-4-services-oriented-applications/_main.adoc

@@ -13,6 +13,10 @@ include::querysets.adoc[]
 
 include::urls.adoc[]
 
+include::rest.adoc[]
+
+include::trees.adoc[]
+
 == Conclusions
 
 De part son pattern `MVT`, Django ne fait pas comme les autres frameworks.

source/part-4-services-oriented-applications/querysets.adoc

@@ -4,67 +4,67 @@
 * https://docs.djangoproject.com/en/1.9/ref/models/querysets/#django.db.models.query.QuerySet.iterator
 * http://blog.etianen.com/blog/2013/06/08/django-querysets/
 
-L'ORM de Django (et donc, chacune des classes qui composent votre modèle) propose par défaut deux objets hyper importants: 
+L'ORM de Django (et donc, chacune des classes qui composent votre modèle) propose par défaut deux objets hyper importants:
 
-* Les managers, qui consistent en un point d'entrée pour accéder aux objets persistants
-* Les querysets, qui permettent de filtrer des ensembles ou sous-ensemble d'objets. Les querysets peuvent s'imbriquer, pour ajouter
-d'autres filtres à des filtres existants.
+* Les `managers`, qui consistent en un point d'entrée pour accéder aux objets persistants
+* Les `querysets`, qui permettent de filtrer des ensembles ou sous-ensemble d'objets. Les querysets peuvent s'imbriquer, pour ajouter
+d'autres filtres à des filtres existants, et fonctionnent comme un super jeu d'abstraction pour accéder à nos données (persistentes).
 
-Ces deux propriétés vont de paire; par défaut, chaque classe de votre modèle propose un attribut `objects`, qui correspond 
-  à un manager (ou un gestionnaire, si vous préférez). 
+Ces deux propriétés vont de paire; par défaut, chaque classe de votre modèle propose un attribut `objects`, qui correspond
+  à un manager (ou un gestionnaire, si vous préférez).
   Ce gestionnaire constitue l'interface par laquelle vous accéderez à la base de données. Mais pour cela, vous aurez aussi besoin d'appliquer certains requêtes ou filtres. Et pour cela, vous aurez besoin des `querysets`, qui consistent en des ... ensembles de requêtes :-).
 
 Si on veut connaître la requête SQL sous-jacente à l'exécution du queryset, il suffit d'appeler la fonction str() sur la propriété `query`:
-  
+
 [source,python]
 ----
 queryset = Wishlist.objects.all()
-  
+
 print(queryset.query)
 ----
-  
+
 Conditions AND et OR sur un queryset
-  
+
   Pour un `AND`, il suffit de chaîner les conditions. ** trouver un exemple ici ** :-)
-  
+
   Mais en gros : bidule.objects.filter(condition1, condition2)
-  
+
   Il existe deux autres options : combiner deux querysets avec l'opérateur `&` ou combiner des Q objects avec ce même opérateur.
-  
+
 Soit encore combiner des filtres:
-  
+
 [source,python]
 ----
 from core.models import Wish
 
-Wish.objects <1> 
+Wish.objects <1>
 Wish.objects.filter(name__icontains="test").filter(name__icontains="too") <2>
 ----
-<1> Ca, c'est notre manager. 
-<2> Et là, on chaîne les requêtes pour composer une recherche sur tous les souhaits dont le nom contient (avec une casse insensible) la chaîne "test" et dont le nom contient la chaîne "too". 
-  
-Pour un 'OR', on a deux options : 
-  
+<1> Ca, c'est notre manager.
+<2> Et là, on chaîne les requêtes pour composer une recherche sur tous les souhaits dont le nom contient (avec une casse insensible) la chaîne "test" et dont le nom contient la chaîne "too".
+
+Pour un 'OR', on a deux options :
+
   . Soit passer par deux querysets, typiuqment `queryset1 | queryset2`
   . Soit passer par des `Q objects`, que l'on trouve dans le namespace `django.db.models`.
-  
+
 [source,python]
 ----
 from django.db.models import Q
-  
+
 condition1 = Q(...)
 condition2 = Q(...)
-  
+
 bidule.objects.filter(condition1 | condition2)
 ----
 
 L'opérateur inverse (_NOT_)
-  
+
 Idem que ci-dessus : soit on utilise la méthode `exclude` sur le queryset, soit l'opérateur `~` sur un Q object;
-  
-  
-Ajouter les sujets suivants : 
-  
+
+
+Ajouter les sujets suivants :
+
   . Prefetch
   . select_related
 
@@ -90,28 +90,28 @@ Cette propriété a une double utilité:
 ==== Requêtes
 
 DANGER: Les requêtes sont sensibles à la casse, **même** si le moteur de base de données ne l'est pas.
-C'est notamment le cas pour Microsoft SQL Server; faire une recherche directement via les outils de Microsoft ne retournera pas 
+C'est notamment le cas pour Microsoft SQL Server; faire une recherche directement via les outils de Microsoft ne retournera pas
 obligatoirement les mêmes résultats que les managers, qui seront beaucoup plus tatillons sur la qualité des recherches par
 rapport aux filtres paramétrés en entrée.
 
 ==== Jointures
 
 Pour appliquer une jointure sur un modèle, nous pouvons passer par les méthodes `select_related` et `prefetch_related`.
-Il faut cependant faire **très** attention au prefetch related, qui fonctionne en fait comme une grosse requête dans laquelle 
-nous trouvons un `IN (...)`. 
-Càd que Django va récupérer tous les objets demandés initialement par le queryset, pour ensuite prendre toutes les clés primaires, 
-pour finalement faire une deuxième requête et récupérer les relations externes. 
+Il faut cependant faire **très** attention au prefetch related, qui fonctionne en fait comme une grosse requête dans laquelle
+nous trouvons un `IN (...)`.
+Càd que Django va récupérer tous les objets demandés initialement par le queryset, pour ensuite prendre toutes les clés primaires,
+pour finalement faire une deuxième requête et récupérer les relations externes.
 
 Au final, si votre premier queryset est relativement grand (nous parlons de 1000 à 2000 éléments, en fonction du moteur de base de données),
 la seconde requête va planter et vous obtiendrez une exception de type `django.db.utils.OperationalError: too many SQL variables`.
 
-Nous pourrions penser qu'utiliser un itérateur permettrait de combiner les deux, mais ce n'est pas le cas... 
+Nous pourrions penser qu'utiliser un itérateur permettrait de combiner les deux, mais ce n'est pas le cas...
 
 Comme l'indique la documentation:
 
 	Note that if you use iterator() to run the query, prefetch_related() calls will be ignored since these two optimizations do not make sense together.
 
-Ajouter un itérateur va en fait forcer le code à parcourir chaque élément de la liste, pour l'évaluer. 
+Ajouter un itérateur va en fait forcer le code à parcourir chaque élément de la liste, pour l'évaluer.
 Il y aura donc (à nouveau) autant de requêtes qu'il y a d'éléments, ce que nous cherchons à éviter.
 
 [source,python]
@@ -125,5 +125,5 @@ informations = (
 ----
 
 === Aggregate vs. Annotate
-  
+
 https://docs.djangoproject.com/en/3.1/topics/db/aggregation/

source/part-4-services-oriented-applications/rest.adoc

@@ -0,0 +1,378 @@
+== Application Programming Interface
+
+Au niveau du modèle, nous allons partir de quelque chose de très simple: des personnes, des contrats, des types de contrats, et un service d'affectation.
+Quelque chose comme ceci:
+
+[source,python]
+----
+# models.py
+
+from django.db import models
+
+
+class People(models.Model):
+    CIVILITY_CHOICES = (
+        ("M", "Monsieur"),
+        ("Mme", "Madame"),
+        ("Dr", "Docteur"),
+        ("Pr", "Professeur"),
+        ("", "")
+    )
+
+    last_name = models.CharField(max_length=255)
+    first_name = models.CharField(max_length=255)
+    civility = models.CharField(
+        max_length=3,
+        choices=CIVILITY_CHOICES,
+        default=""
+    )
+
+    def __str__(self):
+        return "{}, {}".format(self.last_name, self.first_name)
+
+
+class Service(models.Model):
+    label = models.CharField(max_length=255)
+
+    def __str__(self):
+        return self.label
+
+
+class ContractType(models.Model):
+    label = models.CharField(max_length=255)
+    short_label = models.CharField(max_length=50)
+
+    def __str__(self):
+        return self.short_label
+
+
+class Contract(models.Model):
+    people = models.ForeignKey(People, on_delete=models.CASCADE)
+    date_begin = models.DateField()
+    date_end = models.DateField(blank=True, null=True)
+    contract_type = models.ForeignKey(ContractType, on_delete=models.CASCADE)
+    service = models.ForeignKey(Service, on_delete=models.CASCADE)
+
+    def __str__(self):
+        if self.date_end is not None:
+            return "A partir du {}, jusqu'au {}, dans le service {} ({})".format(
+                self.date_begin,
+                self.date_end,
+                self.service,
+                self.contract_type
+            )
+
+        return "A partir du {}, à durée indéterminée, dans le service {} ({})".format(
+                self.date_begin,
+                self.service,
+                self.contract_type
+            )
+----
+
+image::images/rest/models.png[]
+
+## Configuration
+
+La configuration des points de terminaison de notre API est relativement touffue.
+Il convient de:
+
+1. Configurer les sérialiseurs, càd. les champs que nous souhaitons exposer au travers de l'API,
+2. Configurer les vues, càd le comportement de chacun des points de terminaison,
+3. Configurer les points de terminaison eux-mêmes, càd les URLs permettant d'accéder aux ressources.
+4. Et finalement ajouter quelques paramètres au niveau de notre application.
+
+### Sérialiseurs
+
+```python
+# serializers.py
+
+from django.contrib.auth.models import User, Group
+from rest_framework import serializers
+
+from .models import People, Contract, Service
+
+
+class PeopleSerializer(serializers.HyperlinkedModelSerializer):
+    class Meta:
+        model = People
+        fields = ("last_name", "first_name", "contract_set")
+
+
+class ContractSerializer(serializers.HyperlinkedModelSerializer):
+    class Meta:
+        model = Contract
+        fields = ("date_begin", "date_end", "service")
+
+
+class ServiceSerializer(serializers.HyperlinkedModelSerializer):
+    class Meta:
+        model = Service
+        fields = ("name",)
+
+```
+
+### Vues
+
+```python
+# views.py
+
+from django.contrib.auth.models import User, Group
+from rest_framework import viewsets
+from rest_framework import permissions
+
+from .models import People, Contract, Service
+from .serializers import PeopleSerializer, ContractSerializer, ServiceSerializer
+
+
+class PeopleViewSet(viewsets.ModelViewSet):
+    queryset = People.objects.all()
+    serializer_class = PeopleSerializer
+    permission_class = [permissions.IsAuthenticated]
+
+
+class ContractViewSet(viewsets.ModelViewSet):
+    queryset = Contract.objects.all()
+    serializer_class = ContractSerializer
+    permission_class = [permissions.IsAuthenticated]
+
+
+class ServiceViewSet(viewsets.ModelViewSet):
+    queryset = Service.objects.all()
+    serializer_class = ServiceSerializer
+    permission_class = [permissions.IsAuthenticated]
+
+```
+
+### URLs
+
+```python
+# urls.py
+
+from django.contrib import admin
+from django.urls import path, include
+
+from rest_framework import routers
+
+from core import views
+
+
+router = routers.DefaultRouter()
+router.register(r"people", views.PeopleViewSet)
+router.register(r"contracts", views.ContractViewSet)
+router.register(r"services", views.ServiceViewSet)
+
+urlpatterns = [
+    path("api/v1/", include(router.urls)),
+    path('admin/', admin.site.urls),
+]
+```
+
+### Paramètres
+
+```python
+# settings.py
+
+INSTALLED_APPS = [
+    ...
+    "rest_framework",
+    ...
+]
+
+...
+
+REST_FRAMEWORK = {
+    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
+    'PAGE_SIZE': 10
+}
+
+```
+
+A ce stade, en nous rendant sur l'URL `http://localhost:8000/api/v1`, nous obtiendrons ceci:
+
+image::images/rest/api-first-example.png[]
+
+
+## Modèles et relations
+
+Plus haut, nous avons utilisé une relation de type `HyperlinkedModelSerializer`.
+C'est une bonne manière pour autoriser des relations entre vos instances à partir de l'API, mais il faut reconnaître que cela reste assez limité.
+Pour palier à ceci, il existe [plusieurs manières de représenter ces relations](https://www.django-rest-framework.org/api-guide/relations/): soit *via* un hyperlien, comme ci-dessus, soit en utilisant les clés primaires, soit en utilisant l'URL canonique permettant d'accéder à la ressource.
+La solution la plus complète consiste à intégrer la relation directement au niveau des données sérialisées, ce qui nous permet de passer de ceci (au niveau des contrats):
+
+```json
+{
+    "count": 1,
+    "next": null,
+    "previous": null,
+    "results": [
+        {
+            "last_name": "Bond",
+            "first_name": "James",
+            "contract_set": [
+                "http://localhost:8000/api/v1/contracts/1/",
+                "http://localhost:8000/api/v1/contracts/2/"
+            ]
+        }
+    ]
+}
+```
+
+à ceci:
+
+```json
+{
+    "count": 1,
+    "next": null,
+    "previous": null,
+    "results": [
+        {
+            "last_name": "Bond",
+            "first_name": "James",
+            "contract_set": [
+                {
+                    "date_begin": "2019-01-01",
+                    "date_end": null,
+                    "service": "http://localhost:8000/api/v1/services/1/"
+                },
+                {
+                    "date_begin": "2009-01-01",
+                    "date_end": "2021-01-01",
+                    "service": "http://localhost:8000/api/v1/services/1/"
+                }
+            ]
+        }
+    ]
+}
+```
+
+La modification se limite à **surcharger** la propriété, pour indiquer qu'elle consiste en une instance d'un des sérialiseurs existants.
+Nous passons ainsi de ceci
+
+```python
+class ContractSerializer(serializers.HyperlinkedModelSerializer):
+    class Meta:
+        model = Contract
+        fields = ("date_begin", "date_end", "service")
+
+
+class PeopleSerializer(serializers.HyperlinkedModelSerializer):
+
+    class Meta:
+        model = People
+        fields = ("last_name", "first_name", "contract_set")
+```
+
+à ceci:
+
+```python
+class ContractSerializer(serializers.HyperlinkedModelSerializer):
+    class Meta:
+        model = Contract
+        fields = ("date_begin", "date_end", "service")
+
+
+class PeopleSerializer(serializers.HyperlinkedModelSerializer):
+    contract_set = ContractSerializer(many=True, read_only=True)
+
+    class Meta:
+        model = People
+        fields = ("last_name", "first_name", "contract_set")
+```
+
+Nous ne faisons donc bien que redéfinir la propriété `contract_set` et indiquons qu'il s'agit à présent d'une instance de `ContractSerializer`, et qu'il est possible d'en avoir plusieurs.
+C'est tout.
+
+## Filtres et recherches
+
+A ce stade, nous pouvons juste récupérer des informations présentes dans notre base de données, mais à part les parcourir, il est difficile d'en faire quelque chose.
+
+Il est possible de jouer avec les URLs en définissant une nouvelle route ou avec les paramètres de l'URL, ce qui demanderait alors de programmer chaque cas possible - sans que le consommateur ne puisse les déduire lui-même. Une solution élégante consiste à autoriser le consommateur à filtrer les données, directement au niveau de l'API.
+Ceci peut être fait. Il existe deux manières de restreindre l'ensemble des résultats retournés:
+
+1. Soit au travers d'une recherche, qui permet d'effectuer une recherche textuelle, globale et par ensemble à un ensemble de champs,
+2. Soit au travers d'un filtre, ce qui permet de spécifier une valeur précise à rechercher.
+
+Dans notre exemple, la première possibilité sera utile pour rechercher une personne répondant à un ensemble de critères. Typiquement, `/api/v1/people/?search=raymond bond` ne nous donnera aucun résultat, alors que `/api/v1/people/?search=james bond` nous donnera le célèbre agent secret (qui a bien entendu un contrat chez nous...).
+
+Le second cas permettra par contre de préciser que nous souhaitons disposer de toutes les personnes dont le contrat est ultérieur à une date particulière.
+
+Utiliser ces deux mécanismes permet, pour Django-Rest-Framework, de proposer immédiatement les champs, et donc d'informer le consommateur des possibilités:
+
+image::images/rest/drf-filters-and-searches.png[]
+
+
+### Recherches
+
+La fonction de recherche est déjà implémentée au niveau de Django-Rest-Framework, et aucune dépendance supplémentaire n'est nécessaire.
+Au niveau du `viewset`, il suffit d'ajouter deux informations:
+
+```python
+...
+from rest_framework import filters, viewsets
+...
+
+class PeopleViewSet(viewsets.ModelViewSet):
+    ...
+    filter_backends = [filters.SearchFilter]
+    search_fields = ["last_name", "first_name"]
+    ...
+```
+
+### Filtres
+
+Nous commençons par installer [le paquet `django-filter`](https://www.django-rest-framework.org/api-guide/filtering/#djangofilterbackend) et nous l'ajoutons parmi les applications installées:
+
+```bash
+λ pip install django-filter
+Collecting django-filter
+  Downloading django_filter-2.4.0-py3-none-any.whl (73 kB)
+     |████████████████████████████████| 73 kB 2.6 MB/s
+Requirement already satisfied: Django>=2.2 in c:\users\fred\sources\.venvs\rps\lib\site-packages (from django-filter) (3.1.7)
+Requirement already satisfied: asgiref<4,>=3.2.10 in c:\users\fred\sources\.venvs\rps\lib\site-packages (from Django>=2.2->django-filter) (3.3.1)
+Requirement already satisfied: sqlparse>=0.2.2 in c:\users\fred\sources\.venvs\rps\lib\site-packages (from Django>=2.2->django-filter) (0.4.1)
+Requirement already satisfied: pytz in c:\users\fred\sources\.venvs\rps\lib\site-packages (from Django>=2.2->django-filter) (2021.1)
+Installing collected packages: django-filter
+Successfully installed django-filter-2.4.0
+```
+
+Une fois l'installée réalisée, il reste deux choses à faire:
+
+1. Ajouter `django_filters` parmi les applications installées:
+2. Configurer la clé `DEFAULT_FILTER_BACKENDS` à la valeur `['django_filters.rest_framework.DjangoFilterBackend']`.
+
+Vous avez suivi les étapes ci-dessus, il suffit d'adapter le fichier `settings.py` de la manière suivante:
+
+```python
+REST_FRAMEWORK = {
+    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
+    'PAGE_SIZE': 10,
+    'DEFAULT_FILTER_BACKENDS': ['django_filters.rest_framework.DjangoFilterBackend']
+}
+```
+
+Au niveau du viewset, il convient d'ajouter ceci:
+
+```python
+...
+from django_filters.rest_framework import DjangoFilterBackend
+from rest_framework import viewsets
+...
+
+class PeopleViewSet(viewsets.ModelViewSet):
+    ...
+    filter_backends = [DjangoFilterBackend]
+    filterset_fields = ('last_name',)
+    ...
+```
+
+A ce stade, nous avons deux problèmes:
+
+1. Le champ que nous avons défini au niveau de la propriété `filterset_fields` exige une correspondance exacte. Ainsi, `/api/v1/people/?last_name=Bon` ne retourne rien, alors que `/api/v1/people/?last_name=Bond` nous donnera notre agent secret préféré.
+2. Il n'est pas possible d'aller appliquer un critère de sélection sur la propriété d'une relation. Notre exemple proposant rechercher uniquement les relations dans le futur (ou dans le passé) tombe à l'eau.
+
+Pour ces deux points, nous allons définir un nouveau filtre, en surchargeant une nouvelle classe dont la classe mère serait de type `django_filters.FilterSet`.
+
+TO BE CONTINUED.
+
+A noter qu'il existe un paquet [Django-Rest-Framework-filters](https://github.com/philipn/django-rest-framework-filters), mais il est déprécié depuis Django 3.0, puisqu'il se base sur `django.utils.six` qui n'existe à présent plus. Il faut donc le faire à la main (ou patcher le paquet...).
+

source/references.bib

@@ -58,6 +58,22 @@
    year = {2015},
    publisher = {Packt Publishing}
 }
+@book{unix_philosophy,
+   author = {Eric S. Raymond},
+   year = {2004},
+   title = {Basics of the Unix Philosophy, The Art of Unix Programming},
+   publisher = {Addison-Wesley Professional},
+   isbn = {0-13-142901-9},
+}
+@book{data_intensive,
+   title = {Designing Data Intensive Applications},
+   booktitle = {The Big Ideas Behind Reliable, Scalable and Maintainable Systems},
+   year = {2017},
+   author = {Martin Kleppmann},
+   publisher = {O'Reilly},
+   isbn = {978-1-449-37332-0},
+   release = {Fifteenth release - 2021-03-26}
+}
 @misc{agiliq_admin,
    title = {Django Admin Cookbook, How to do things with Django admin},
    year = {2018},
@@ -74,4 +90,9 @@
    year = {2017},
    note = {Last visited in 2021},
    url = {https://simpleisbetterthancomplex.com/series/beginners-guide/1.11/}
+}
+@misc{gnu_linux_mag_hs_104,
+   title = {Les cinq règles pour écrire du code maintenable}
+   year = {2019},
+   url = {https://boutique.ed-diamond.com/les-hors-series/1402-gnulinux-magazine-hs-104.html}
 }