Compare commits

...

99 Commits

Author SHA1 Message Date
Fred Pauchet 32517aa7b1 Starting references to Release It by Michael T Nygard 2023-04-14 21:51:29 +02:00
Fred Pauchet ae881a52fe Update notes 2023-02-17 10:46:18 +01:00
Fred Pauchet 17b3d7336a Switch from Svelte to NextJS 2022-12-16 22:46:35 +01:00
Fred Pauchet 8ddd800da6 Describe a simple CI pipeline 2022-12-16 22:46:16 +01:00
Fred Pauchet 71b4c7a7fd Improve Python chapter with introspection 2022-12-06 16:12:53 +01:00
Fred Pauchet a439c57757 Include a part about dictionaries 2022-12-06 16:05:35 +01:00
Fred Pauchet 7aef6eebd7 Siren's call (cats on trees :-)) 2022-12-06 15:59:01 +01:00
Fred Pauchet 0c9a3fc59d Describe a simple tree diagram 2022-10-23 22:03:30 +02:00
Fred Pauchet 450f0cee18 Reorder sections 2022-10-23 11:31:57 +02:00
Fred Pauchet e926ca4373 Change permissions on files 2022-10-23 11:27:38 +02:00
Fred Pauchet c8ec00c7ba Need to fill OData section 2022-10-23 11:27:09 +02:00
Fred Pauchet dc1d8bed30 Fix LaTeX build 2022-10-23 11:26:14 +02:00
Fred Pauchet 14fbb68952 Add links to htmx 2022-09-18 19:09:17 +02:00
Fred Pauchet a5210a8353 Rework sentences in architecture.tex 2022-09-11 21:51:16 +02:00
Fred Pauchet a14e622318 Switch graphics to new environment 2022-09-11 20:11:33 +02:00
Fred Pauchet 52c6916a6b Convert includegraphic to graphic environment 2022-09-11 16:46:49 +02:00
Fred Pauchet a238fd4eed Create a new environment to include strechted graphics 2022-09-11 16:46:30 +02:00
Fred Pauchet 8a839b2d7b Add descriptive links for Git 2022-09-11 12:05:35 +02:00
Fred Pauchet 745291ac99 Quit PDF generation on first encountered error 2022-09-10 17:14:53 +02:00
Fred Pauchet 43590682bc Delete old asciidoc sources 2022-09-10 17:12:16 +02:00
Fred Pauchet 1a97286bb0 Implement color boxes
That can be used for advices, dangers or memorization
2022-09-10 17:11:20 +02:00
Fred Pauchet 564c8d2264 Delete ASCIIDOC docker compilation 2022-09-10 14:28:37 +02:00
Fred Pauchet a64032fd48 Changing files permissions (due to ... ?) 2022-09-10 14:26:47 +02:00
Fred Pauchet db8bafa349 Fix docker file to correctly build image 2022-09-10 14:26:00 +02:00
Fred Pauchet af8b7c41b0 Add link to Conventional Commits
continuous-integration/drone/push Build is passing Details
2022-06-18 15:16:03 +02:00
Fred Pauchet f6821ff222 Resize images on chapter 2
continuous-integration/drone/push Build is passing Details
2022-06-18 14:54:33 +02:00
Fred Pauchet 0578564c37 Resize images to fit page layout
continuous-integration/drone/push Build is passing Details
2022-06-17 21:31:50 +02:00
Fred Pauchet 862d2d01f6 Rework introduction
continuous-integration/drone/push Build is passing Details
2022-06-12 17:09:19 +02:00
Fred Pauchet e7b66702dc Finalize integration of Roads and Bridges
continuous-integration/drone/push Build is passing Details
2022-06-11 19:52:24 +02:00
Fred Pauchet 9847f652a1 Itemize several sentences
continuous-integration/drone/push Build is passing Details
2022-06-09 21:55:16 +02:00
Fred Pauchet e2ea706de3 Complete introduction on Python
continuous-integration/drone/push Build is passing Details
2022-06-09 20:50:33 +02:00
Fred Pauchet 81da4e3069 Add references to Roads and Bridges
continuous-integration/drone/push Build is passing Details
2022-06-09 20:40:42 +02:00
Fred Pauchet de1e298225 About dependencies...
continuous-integration/drone/push Build is passing Details
2022-06-09 18:53:00 +02:00
Fred Pauchet 804ada2bea PEP Review
continuous-integration/drone/push Build is passing Details
2022-06-08 19:52:39 +02:00
Fred Pauchet 0158ba537b API + Models services
continuous-integration/drone/push Build is passing Details
2022-06-05 22:01:19 +02:00
Fred Pauchet a41d71d0a8 Structure Discord GDPR page content
continuous-integration/drone/push Build is running Details
2022-06-05 22:00:27 +02:00
Fred Pauchet 224ed5a0c2 Services...
continuous-integration/drone/push Build is passing Details
2022-06-03 21:10:05 +02:00
Fred Pauchet 09a1cd0506 Continuing Alex Krupp's work review
continuous-integration/drone/push Build is passing Details
2022-06-03 20:50:18 +02:00
Fred Pauchet dde67920d6 Continue GDPR description from Discord analysis
continuous-integration/drone/push Build is passing Details
2022-06-02 22:23:59 +02:00
Fred Pauchet 16f522d5ea Add the construct_change_message description 2022-06-02 22:23:42 +02:00
Fred Pauchet e8547083c5 Copy output file to Nextcloud :p
continuous-integration/drone/push Build is passing Details
2022-06-01 22:17:03 +02:00
Fred Pauchet e1c7f7ce46 Annexes, new chapters and typo fixes
continuous-integration/drone/push Build is passing Details
2022-06-01 22:16:48 +02:00
Fred Pauchet 31b8c1dc7d Add a note on Fly.io
continuous-integration/drone/push Build is passing Details
2022-05-31 21:57:21 +02:00
Fred Pauchet 0c2aeee91e Add appendices
continuous-integration/drone/push Build is passing Details
2022-05-31 20:39:48 +02:00
Fred Pauchet 9e8b04ef5e Corrections de texte, ajouts minimes, ... Et Intégration de Calvin & Hobbes !
continuous-integration/drone/push Build is failing Details
2022-05-18 21:52:38 +02:00
Fred Pauchet 8ad6e92bc5 Fix Heroku notes
continuous-integration/drone/push Build is failing Details
2022-05-13 11:26:09 +02:00
Fred Pauchet f901628255 Working on Debian/Ubuntu
continuous-integration/drone/push Build is failing Details
2022-05-11 21:49:21 +02:00
Fred Pauchet f5ae5cdac4 Work on Debian/Ubuntu deployments methods
continuous-integration/drone/push Build is failing Details
2022-05-11 21:36:42 +02:00
Fred Pauchet ad625a1b40 ... to \ldots
continuous-integration/drone/push Build is failing Details
2022-05-11 20:01:39 +02:00
Fred Pauchet bc7c7f74d4 Télémétrie et composants
continuous-integration/drone/push Build is failing Details
2022-05-11 19:35:11 +02:00
Fred Pauchet 9e0ef60e44 Integration de morceaux du DevOps Handbook
continuous-integration/drone/push Build is failing Details
2022-05-11 18:55:41 +02:00
Gregory Trullemans 4f1afe7678 Reformatage de fichier, de code. Je mets de pour des commentaires à l'intérieur des fichiers.
continuous-integration/drone/push Build is failing Details
2022-05-11 16:01:31 +02:00
Gregory Trullemans a88f1854a0 Code review and rewriting 2022-05-11 15:58:18 +02:00
Fred Pauchet c15e05349d Writing, again and again 2022-05-11 15:43:09 +02:00
Fred Pauchet 2f4718c002 Rephrase peripheral components
continuous-integration/drone/push Build is failing Details
2022-05-05 21:44:18 +02:00
Fred Pauchet 10ec49c302 Add a lot of things :D
continuous-integration/drone/push Build is failing Details
2022-05-04 22:01:55 +02:00
Fred Pauchet 5de564b21f Including templates into LaTeX document
continuous-integration/drone/push Build is failing Details
2022-05-03 22:10:58 +02:00
Fred Pauchet 6f868de04b Ignore minted module temporary files
continuous-integration/drone/push Build is failing Details
2022-05-02 21:55:21 +02:00
Fred Pauchet a23dfec354 Retrieve architecture image from data intensive apps
continuous-integration/drone/push Build is failing Details
2022-05-02 20:10:45 +02:00
Fred Pauchet b39fcf9bf7 Move deployment on part 2
continuous-integration/drone/push Build is failing Details
2022-05-01 20:10:26 +02:00
Fred Pauchet f995792784 Easter notes on administration 2022-05-01 20:10:15 +02:00
Fred Pauchet 39f05bd5c3 Easter notes for context processors
continuous-integration/drone/push Build is failing Details
2022-05-01 19:15:52 +02:00
Fred Pauchet e0b0a862cd Easter notes for authentication 2022-05-01 19:13:19 +02:00
Fred Pauchet 7d81286462 Easter notes on administration ,forms, migrations and models 2022-05-01 19:05:58 +02:00
Fred Pauchet c8f88779ff Complete models.tex based on easter notes
continuous-integration/drone/push Build is failing Details
2022-05-01 10:54:22 +02:00
Fred Pauchet 63f2cf23f4 Fix models.tex
continuous-integration/drone/push Build is failing Details
2022-04-30 21:05:17 +02:00
Fred Pauchet f577872744 Review Easter holidays notes (part 2)
continuous-integration/drone/push Build is failing Details
2022-04-30 20:53:42 +02:00
Fred Pauchet e5012f7066 Review from Easter holidays 2022-04-30 19:49:52 +02:00
Fred Pauchet 50310ea9f0 Finalize switch to latex
continuous-integration/drone/push Build is failing Details
2022-04-30 19:05:06 +02:00
Fred Pauchet 6d7b03e59f Include David Revoy latest picture
continuous-integration/drone/push Build is failing Details
2022-04-27 20:08:46 +02:00
Fred Pauchet bc92b559b3 Migrate SOA
continuous-integration/drone/push Build is failing Details
2022-04-27 19:33:47 +02:00
Fred Pauchet 373a39a22b Integrate Debian, forms, ...
continuous-integration/drone/push Build is failing Details
2022-04-26 22:26:00 +02:00
Fred Pauchet b154a4b302 Add forms
continuous-integration/drone/push Build is failing Details
2022-04-25 20:50:14 +02:00
Fred Pauchet ee76783f86 Working a little bit on migrations, models, etc.
continuous-integration/drone/push Build is failing Details
2022-04-25 19:12:16 +02:00
Fred Pauchet 208ea90e2f Working on environment isolation
continuous-integration/drone/push Build is failing Details
2022-04-24 19:00:11 +02:00
Fred Pauchet 9cd685bddd Write down useful tools
continuous-integration/drone/push Build is failing Details
2022-04-22 19:39:38 +02:00
Fred Pauchet 083069d812 Create external tools
continuous-integration/drone/push Build is failing Details
2022-04-21 21:07:42 +02:00
Fred Pauchet 2fd26218da Start new project
continuous-integration/drone/push Build is failing Details
2022-04-20 20:09:48 +02:00
Fred Pauchet c4a7d94926 Rework structure
continuous-integration/drone/push Build is failing Details
2022-04-16 20:53:08 +02:00
Fred Pauchet 9c051318d4 Just finished SOLID
continuous-integration/drone/push Build is failing Details
2022-04-15 22:25:44 +02:00
Fred Pauchet 33e950334a SRP, Open-Closed & Liskov Substitution
continuous-integration/drone/push Build is failing Details
2022-04-14 20:56:45 +02:00
Fred Pauchet b45386ef48 Fix citations references
continuous-integration/drone/push Build is failing Details
2022-04-13 20:06:18 +02:00
Fred Pauchet 261fa2c7c8 12 factors are on the run!
continuous-integration/drone/push Build is failing Details
2022-04-13 20:00:10 +02:00
Fred Pauchet 02930bd52f Structure 12 factors
continuous-integration/drone/push Build is failing Details
2022-04-12 19:56:25 +02:00
Fred Pauchet 7e6ea730de Conclude first chapter
continuous-integration/drone/push Build is failing Details
2022-04-12 19:48:27 +02:00
Fred Pauchet c4ebdaa48b Fix references & complete Python chapter
continuous-integration/drone/push Build is failing Details
2022-04-12 19:18:05 +02:00
Fred Pauchet 32e8fc9ada Continue switch to latex
continuous-integration/drone/push Build is failing Details
2022-03-28 21:27:00 +02:00
Fred Pauchet 80b6ccb26f Move images to the root folder
continuous-integration/drone/push Build is failing Details
2022-03-24 19:40:48 +01:00
Fred Pauchet bd31267ff4 Switching to LaTeX
continuous-integration/drone/push Build is passing Details
2022-03-24 18:56:29 +01:00
Fred Pauchet e4839e2048 Switching to latex (definitively)
continuous-integration/drone/push Build is passing Details
2022-03-23 22:35:04 +01:00
Fred Pauchet b65a23c66b Add automatic LaTeX conversion
continuous-integration/drone/push Build is passing Details
2022-03-23 09:06:22 +01:00
Fred Pauchet a6290ae866 Add LaTeX source folder 2022-03-23 09:05:33 +01:00
Fred Pauchet ac78de067c Change subsection level of linters 2022-03-23 09:05:05 +01:00
Fred Pauchet 64045b66a2 Add a docker-start sh to run latex 2022-03-23 09:02:11 +01:00
Fred Pauchet 44a819ce01 Convert text to docbook 2022-03-23 09:00:15 +01:00
Fred Pauchet 2d4ef253f5 Sphinx is not needed anymore.
It's not like we switched to AsciiDoctor months ago...
2022-03-15 19:07:15 +01:00
Fred Pauchet e8dda4c60d Talk about squashing migrations :)
continuous-integration/drone/push Build is passing Details
continuous-integration/drone/tag Build is passing Details
2022-03-15 19:04:43 +01:00
Fred Pauchet 850c0381aa Add the dependency graph within migrations
continuous-integration/drone/push Build is passing Details
2022-03-13 19:24:19 +01:00
Fred Pauchet 3370f5b20c Update SOA, ideas, chapters, ...
continuous-integration/drone/push Build is passing Details
2022-03-10 18:36:01 +01:00
241 changed files with 11236 additions and 7610 deletions

0
.drone.yml Normal file → Executable file
View File

2
.gitignore vendored Normal file → Executable file
View File

@ -7,3 +7,5 @@ build
*.log
*.vscode/
*.asciidoctor/
*.aux
_minted-main/

1
CONTRIBUTING.md Normal file → Executable file
View File

@ -33,3 +33,4 @@ Les images de ce livre sont générées en utilisant [Draw.io](draw.io).
## Traductions
Il n'y en a pas pour le moment 😉.

14
Dockerfile Executable file
View File

@ -0,0 +1,14 @@
FROM miktex/miktex
LABEL Description="Docker container from MiKTeX, Ubuntu 20.04, with Pygments" Version="1.0"
RUN rm /etc/apt/sources.list.d/miktex.list
RUN apt-get update
RUN apt-get install python3-pip -y
RUN pip install pygments
WORKDIR /miktex/work
CMD ["bash"]

0
Makefile Normal file → Executable file
View File

29
README.md Normal file → Executable file
View File

@ -2,30 +2,13 @@
[![Build Status](https://drone.grimbox.be/api/badges/fred/gwift-book/status.svg)](https://drone.grimbox.be/fred/gwift-book)
Ce livre peut être compilé avec [AsciiDoctor](https://asciidoctor.org/).
Ce livre peut être compilé avec une image Docker personnalisée, basée sur Miktex.
Pygments est également installé.
Elle peut être compilée avec Docker ou Podman, grâce à l'une des commandes suivantes:
* `docker build -t miktex-pygments .`
## Dépendances
Pour compiler le manuel en PDF:
```bash
$ gem install asciidoctor-pdf --pre
$ gem install asciidoctor-bibtex
$ gem install rouge
```
* `./docker-miktex.sh`
## Conversion en PDF
```bash
asciidoctor -a rouge-style=monokai -a pdf-themesdir=resources/themes -a pdf-theme=gwift main.adoc -t -r asciidoctor-diagram
asciidoctor-pdf -a pdf-themesdir=resources/themes -a pdf-theme=gwift main.adoc -t -r asciidoctor-diagram
```
## Image Docker
L'image Docker utilisée par Drone est [celle-ci](https://github.com/asciidoctor/docker-asciidoctor).
Elle convient tout ce qu'il faut pour compiler correctement le document en PDF (asciidoctor-pdf, asciidoctor-bibtex, ...).
## Erreurs connues
Si `asciidoctor` n'est pas dans le PATH malgré son installation, on peut le trouver grâce à la commande `gem env`, puis à réutiliser (ou à modifier le fichier `.bash_profile` ou `.profile`).

55
annexes/gilded-roses.tex Normal file
View File

@ -0,0 +1,55 @@
\chapter{Gilded Roses}
\url{https://github.com/emilybache/GildedRose-Refactoring-Kata}
\begin{listing}[H]
\begin{minted}[tabsize=4]{python}
# -*- coding: utf-8 -*-
class GildedRose(object):
def __init__(self, items):
self.items = items
def update_quality(self):
for item in self.items:
if item.name != "Aged Brie" and item.name != "Backstage passes to a TAFKAL80ETC concert":
if item.quality > 0:
if item.name != "Sulfuras, Hand of Ragnaros":
item.quality = item.quality - 1
else:
if item.quality < 50:
item.quality = item.quality + 1
if item.name == "Backstage passes to a TAFKAL80ETC concert":
if item.sell_in < 11:
if item.quality < 50:
item.quality = item.quality + 1
if item.sell_in < 6:
if item.quality < 50:
item.quality = item.quality + 1
if item.name != "Sulfuras, Hand of Ragnaros":
item.sell_in = item.sell_in - 1
if item.sell_in < 0:
if item.name != "Aged Brie":
if item.name != "Backstage passes to a TAFKAL80ETC concert":
if item.quality > 0:
if item.name != "Sulfuras, Hand of Ragnaros":
item.quality = item.quality - 1
else:
item.quality = item.quality - item.quality
else:
if item.quality < 50:
item.quality = item.quality + 1
class Item:
def __init__(self, name, sell_in, quality):
self.name = name
self.sell_in = sell_in
self.quality = quality
def __repr__(self):
return "%s, %s, %s" % (self.name, self.sell_in, self.quality)
\end{minted}
\end{listing}

71
annexes/grafana.tex Executable file
View File

@ -0,0 +1,71 @@
\chapter{Monitoring Stack}
InfluxDB ? https://www.influxdata.com/
\section{Visualisation}
\begin{quote}
Grafana allows you to query, visualize, alert on and understand your metrics no matter where they are stored.
Create, explore, and share beautiful dashboards with your team and foster a data driven culture.
\end{quote}
\section{Métriques}
\begin{quote}
Graphite is an enterprise-ready monitoring tool that runs equally well on cheap hardware or Cloud infrastructure.
Teams use Graphite to track the performance of their websites, applications, business services, and networked servers.
It marked the start of a new generation of monitoring tools, making it easier than ever to store, retrieve, share, and visualize time-series data.
Graphite was originally designed and written by Chris Davis at Orbitz in 2006 as side project that ultimately grew to be their foundational monitoring tool.
In 2008, Orbitz allowed Graphite to be released under the open source Apache 2.0 license.
Numerous large companies have deployed Graphite to production where it helps them to monitor their production e-commerce services and plan for growth.
\end{quote}
Graphite does two things:
\begin{enumerate}
\item
Store numeric time-series data
\item
Render graphs of this data on demand
\end{enumerate}
What Graphite does not do is collect data for you, however there are some tools out there that know how to send data to graphite. Even though it often requires a little code, sending data to Graphite is very simple.
Graphite consists of 3 software components:
\begin{enumerate}
\item
\textbf{carbon} - a Twisted daemon that listens for time-series data
\item
\textbf{whisper} - a simple database library for storing time-series data (similar in design to RRD)
\item
\textbf{graphite webapp} - A Django webapp that renders graphs on-demand using Cairo
\end{enumerate}
Feeding in your data is pretty easy, typically most of the effort is in collecting the data to begin with. As you send datapoints to Carbon, they become immediately available for graphing in the webapp. The webapp offers several ways to create and display graphs including a simple URL API for rendering that makes it easy to embed graphs in other webpages.
\section{Logs}
\begin{quote}
Loki brings together logs from all your applications and infrastructure in a single place.
By using the exact same service discovery and label model as Prometheus, Grafana Logs can systematically guarantee your logs have consistent metadata with your metrics, making it easy to move from one to the other.
\end{quote}
Loki est l'équivalent (développé directement par Grafana) de Prometheus.
Il sera donc toujours nécessaire d'accumuler des logs au travers d'exporters.
\begin{quote}
Loki se comporte comme Prometheus : c'est un logiciel que vous allez installer sur votre machine qui sert pour le monitoring de votre infrastructure et le laisser vivre sa vie. Comme son mentor, ou presque, il va falloir lui associer des exporters pour le gaver de données : Promtail.
-- https://www.dadall.info/article698/loki-jouer-avec-ses-logs-dans-grafana
\end{quote}
\section{Traces}
Unlike other tracing tools, Grafana Traces does not index the traces which makes it possible to store orders of magnitude more trace data for the same cost, and removes the need for sampling.
Stores orders of magnitude more trace data for the same cost, and removes the need for sampling.
Reduces the TCO by an order of magnitude and makes the system overall much easier to use.
Grafana Traces is available as a containerized application, and you can run it on any orchestration engine like Kubernetes, Mesos, etc. The various services can be horizontally scaled depending on the workload on the ingest/query path. You can also use cloud native object storage, such as Google Cloud Storage, Amazon S3, or Azure Blob Storage.

5
annexes/snippets.tex Executable file
View File

@ -0,0 +1,5 @@
\chapter{Snippets}
\section{Nettoyage de chaînes de caractères}
Basically, NFC is how you normalize text that's meant to be displayed to a user on the web, and NFKC is how you normalize text that's used to for searching and guaranteeing uniqueness. \cite{django_for_startup_founders}

2
annexes/sonar.tex Executable file
View File

@ -0,0 +1,2 @@
\chapter{SonarQube}

View File

316
chapters/administration.tex Executable file
View File

@ -0,0 +1,316 @@
\chapter{Administration}
Cette partie est tellement puissante et performante, qu'elle pourrait laisser penser qu'il est possible de réaliser une application complète rien qu'en configurant l'administration.
C'est faux.
L'administration est une sorte de tour de contrôle évoluée, un \emph{back office} sans transpirer; elle se base sur le modèle de données programmé et construit dynamiquement les formulaires qui lui est associé.
Elle joue avec les clés primaires, étrangères, les champs et types de champs par \href{https://fr.wikipedia.org/wiki/Introspection}{introspection}, et présente tout ce qu'il faut pour avoir du \href{https://fr.wikipedia.org/wiki/CRUD}{CRUD} \index{CRUD} \footnote{\emph{Create-Read-Update-Delete}, c'est-à-dire le fonctionnement par défaut de beaucoup d'applications}, c'est-à-dire tout ce qu'il faut pour ajouter, lister, modifier ou supprimer des informations.
Son problème est qu'elle présente une courbe d'apprentissage asymptotique.
Il est \textbf{très} facile d'arriver rapidement à un bon résultat, au travers d'un périmètre de configuration relativement restreint.
Quoi que vous fassiez, il y a un moment où la courbe de paramétrage sera tellement ardue que vous aurez plus facile à développer ce que vous souhaitez ajouter en utilisant les autres concepts de Django.
Cette interface doit rester dans les mains d'administrateurs ou de gestionnaires, et dans leurs mains à eux uniquement: il n'est pas question de donner des droits aux utilisateurs finaux (même si c'est extrêment tentant durant les premiers tours de roues).
Indépendamment de la manière dont vous allez l'utiliser et la configurer, vous finirez par devoir développer une "vraie" application, destinée aux utilisateurs classiques, et répondant à leurs besoins uniquement.
Une bonne idée consiste à développer l'administration dans un premier temps, en \textbf{gardant en tête qu'il sera nécessaire de développer des concepts spécifiques}.
Dans cet objectif, l'administration est un outil exceptionel, qui permet de valider un modèle, de créer des objets rapidement et de valider les liens qui existent entre eux.
C'est aussi un excellent outil de prototypage et de preuve de concept.
Elle se base sur plusieurs couches que l'on a déjà (ou on va bientôt) aborder (suivant le sens de lecture que vous préférez):
\begin{enumerate}
\item
Le modèle de données
\item
Les validateurs
\item
Les formulaires
\item
Les widgets
\end{enumerate}
\section{Le modèle de données}
Comme expliqué ci-dessus, le modèle de données est constité d'un ensemble de champs typés et de relations.
L'administration permet de décrire les données qui peuvent être modifiées, en y associant un ensemble (basique) de permissions.
Si vous vous rappelez de l'application que nous avions créée dans la première partie, les URLs reprenaient déjà la partie suivante:
\begin{minted}[tabsize=4]{python}
from django.contrib import admin
from django.urls import path
from gwift.views import wish_details
urlpatterns = [
path('admin/', admin.site.urls),
[...]
]
\end{minted}
Cette URL signifie que la partie \texttt{admin} est déjà active et accessible à l'URL \texttt{\textless{}mon\_site\textgreater{}/admin}.
C'est le seul prérequis pour cette partie.
Chaque application nouvellement créée contient par défaut un fichier \texttt{admin.py}, dans lequel il est possible de déclarer les ensembles de données seront accessibles ou éditables.
Ainsi, si nous partons du modèle basique que nous avions détaillé plus tôt, avec des souhaits et des listes de souhaits:
\begin{minted}[tabsize=4]{python}
# gwift/wish/models.py
from django.db import models
class WishList(models.Model):
name = models.CharField(max_length=255)
class Item(models.Model):
name = models.CharField(max_length=255)
wishlist = models.ForeignKey(WishList, on_delete=models.CASCADE)
\end{minted}
Nous pouvons facilement arriver au résultat suivant, en ajoutant
quelques lignes de configuration dans ce fichier \texttt{admin.py}:
\begin{minted}[tabsize=4]{python}
from django.contrib import admin
from .models import Item, WishList
admin.site.register(Item)
admin.site.register(WishList)
\end{minted}
\begin{itemize}
\item
Nous importons les modèles que nous souhaitons gérer dans l'admin
\item
Et nous les déclarons comme gérables. Cette dernière ligne implique aussi qu'un modèle pourrait ne pas être disponible du tout, ce qui n'activera simplement aucune opération de lecture ou modification.
\end{itemize}
Il nous reste une seule étape à réaliser: créer un nouvel utilisateur.
Pour cet exemple, notre gestion va se limiter à une gestion manuelle; nous aurons donc besoin d'un \emph{super-utilisateur}, que nous pouvons créer grâce à la commande \texttt{python\ manage.py\ createsuperuser}.
\begin{verbatim}
$ python manage.py createsuperuser
Username (leave blank to use 'fred'): fred
Email address: fred@root.org
Password: ******
Password (again): ******
Superuser created successfully.
\end{verbatim}
\begin{figure}[H]
\centering
\includegraphics{images/django/django-site-admin.png}
\caption{Connexion au site d'administration}
\end{figure}
\begin{figure}[H]
\centering
\includegraphics{images/django/django-site-admin-after-connection.png}
\caption{Administration}
\end{figure}
Ceci nous permet déjà d'ajouter des éléments (Items), des listes de souhaits, de visualiser les actions récentes, voire de gérer les autorisations attribuées aux utilisateurs, comme les membres du staff ou les administrateurs.
\section{Quelques conseils de base}
\begin{enumerate}
\item
Surchargez la méthode \texttt{str(self)} pour chaque classe que vous aurez définie dans le modèle.
Cela permettra de construire une représentation textuelle pour chaque instance de votre classe.
Cette information sera utilisée un peu partout dans le code, et donnera une meilleure idée de ce que l'on manipule.
En plus, cette méthode est également appelée lorsque l'administration historisera une action (et comme cette étape sera inaltérable, autant qu'elle soit fixée dans le début).
\item
La méthode \texttt{get\_absolute\_url(self)} retourne l'URL à laquelle on peut accéder pour obtenir les détails d'une instance. Par exemple:
\end{enumerate}
\begin{minted}[tabsize=4]{python}
def get_absolute_url(self):
return reverse('myapp.views.details', args=[self.id])
\end{minted}
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\item
Les attributs \texttt{Meta}:
\end{enumerate}
\begin{minted}[tabsize=4]{python}
class Meta:
ordering = ['-field1', 'field2']
verbose_name = 'my class in singular'
verbose_name_plural = 'my class when is in a list!'
\end{minted}
\begin{enumerate}
\item
Le titre:
\begin{itemize}
\item
Soit en modifiant le template de l'administration
\item
Soit en ajoutant l'assignation suivante dans le fichier \texttt{urls.py} : \texttt{admin.site.site\_header\ =\ "SuperBook\ Secret\ Area}.
\end{itemize}
\item
Prefetch
\end{enumerate}
\url{https://hackernoon.com/all-you-need-to-know-about-prefetching-in-django-f9068ebe1e60?gi=7da7b9d3ad64}
\url{https://medium.com/@hakibenita/things-you-must-know-about-django-admin-as-your-app-gets-bigger-6be0b0ee9614}
En gros, le problème de l'admin est que si on fait des requêtes imbriquées, on va flinguer l'application et le chargement de la page.
La solution consiste à utiliser la propriété \texttt{list\_select\_related} de la classe d'Admin, afin d'appliquer une jointure par défaut et et gagner en performances.
\subsection{admin.ModelAdmin}
La classe \texttt{admin.ModelAdmin} que l'on retrouvera principalement dans le fichier \texttt{admin.py} de chaque application contiendra la définition de ce que l'on souhaite faire avec nos données dans l'administration. Cette classe (et sa partie Meta)
\subsection{L'affichage}
Comme l'interface d'administration fonctionne (en trèèèès) gros comme un CRUD auto-généré, on trouve par défaut la possibilité de :
\begin{enumerate}
\item
Créer de nouveaux éléments
\item
Lister les éléments existants
\item
Modifier des éléments existants
\item
Supprimer un élément en particulier.
\end{enumerate}
Les affichages sont donc de deux types: en liste et au détail.
Pour les affichages en liste, le plus simple consiste à jouer sur la propriété \texttt{list\_display}.
Par défaut, la première colonne va accueillir le lien vers le formulaire d'édition.
On peut donc modifier ceci, voire créer de nouveaux liens vers d'autres éléments en construisant des URLs dynamiquement.
Voir aussi comment personnaliser le fil d'Ariane ?
\section{Filtres}
Chaque liste permet de spécifier des filtres spécifiques; ceux-ci peuvent être:
\begin{enumerate}
\item \textbf{Appliqués à la liste} (\texttt{list\_filter})
\item \textbf{Horizontaux} (\texttt{filter\_horizontal})
\item \textbf{Verticaux} (\texttt{filter\_vertical})
\item \textbf{Temporels} (\texttt{date\_hierarchy}
\end{enumerate}
\subsection{Appliqués à la liste}
\subsection{Horizontaux}
\subsection{Verticaux}
\subsection{Temporels}
\section{Permissions}
On l'a dit plus haut, il vaut mieux éviter de proposer un accès à l'administration à vos utilisateurs.
Il est cependant possible de configurer des permissions spécifiques pour certains groupes, en leur autorisant certaines actions de visualisation/ajout/édition ou suppression.
Cela se joue au niveau du \texttt{ModelAdmin}, en implémentant les méthodes suivantes:
\begin{minted}[tabsize=4]{python}
def has_add_permission(self, request):
return True
def has_delete_permission(self, request):
return True
def has_change_permission(self, request):
return True
\end{minted}
On peut accéder aux informations de l'utilisateur actuellement connecté au travers de l'objet \texttt{request.user}.
\section{Relations}
\subsection{Relations 1-N}
Les relations 1-n sont implémentées au travers de formsets (que l'on a normalement déjà décrits plus haut). L'administration permet de les définir d'une manière extrêmement simple, grâce à quelques propriétés.
L'implémentation consiste tout d'abord à définir le comportement du type d'objet référencé (la relation -N), puis à inclure cette définition au niveau du type d'objet référençant (la relation 1-).
\begin{minted}[tabsize=4]{python}
class WishInline(TabularInline):
model = Wish
class Wishlist(admin.ModelAdmin):
...
inlines = [WishInline]
...
\end{minted}
Et voilà : l'administration d'une liste de souhaits (\emph{Wishlist}) pourra directement gérer des relations multiples vers des souhaits.
\subsection{Autocomplétion}
Parler de l'intégration de select2.
\section{Forms}
\section{Présentation}
Parler ici des \texttt{fieldsets} et montrer comment on peut regrouper des champs dans des groupes, ajouter un peu de JavaScript, ...
\section{Actions sur des sélections}
Les actions permettent de partir d'une liste d'éléments, et autorisent
un utilisateur à appliquer une action sur une sélection d'éléments. Par
défaut, il existe déjà une action de \textbf{suppression}.
Les paramètres d'entrée sont :
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\item
L'instance de classe
\item
La requête entrante
\item
Le queryset correspondant à la sélection.
\end{enumerate}
\begin{minted}[tabsize=4]{python}
def double_quantity(self, request, queryset):
for obj in queryset.all():
obj.field += 1
obj.save()
double_quantity.short_description = "Doubler la quantité des souhaits."
\end{minted}
Et pour informer l'utilisateur de ce qui a été réalisé, on peut aussi
lui passer un petit message:
\begin{minted}[tabsize=4]{python}
if rows_updated = 0:
self.message_user(request, "Aucun élément n'a été impacté.")
else:
self.message_user(request, "{} élément(s) mis à jour".format(rows_updated))
\end{minted}
\section{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 \href{https://docs.djangoproject.com/en/stable/ref/contrib/admin/admindocs/}{d'activer la documentation à partir des URLs}:

396
chapters/api.tex Executable file
View File

@ -0,0 +1,396 @@
\chapter{Application Programming Interface}
\url{https://news.ycombinator.com/item?id=30221016\&utm_term=comment} vs
Django Rest Framework vs Marshmallow
Expliquer pourquoi une API est intéressante/primordiale/la première chose à réaliser/le cadet de nos soucis:
\begin{itemize}
\item
Intéressante: ouverture
\item
Primordiale: services
\item
La première chose à réaliser: mobile-first
\item
Le cadet de nos soucis: monolithique (cf. Rework)
\end{itemize}
Voir peut-être aussi
\url{https://christophergs.com/python/2021/12/04/fastapi-ultimate-tutorial/}
Remarque : quatre statuts = le minimum syndical. \cite[p. 297]{restful_web_apis} :
\begin{enumerate}
\item
\textbf{200 (OK)}.
Tout va bien.
Le document qui se trouve dans le corps de la réponse, s'il y en a un, est la représentation d'une ressource.
\item
\textbf{301 (Moved Permanently)}.
Reçu lorsque la ressource n'est plus disponible à cette URI.
\item
\textbf{400 (Bad Request)}.
Indique qu'il y a eu un problème côté client.
Le document qui se trouve dans le corps de la réponse, s'il existe, est un message d'erreur.
Avec un peu de chance, le client a la possibilité d'interpréter ce message d'erreur, afin de corriger le problème.
\item
\textbf{500 (Internal Server Error)}.
Il y a un problème côté serveur. Le document présent dans le corps de la réponse, toujours s'il existe, indique le problème.
Comme celui-ci se situe au niveau du serveur, le client ne pourra rien faire pour le résoudre.
\end{enumerate}
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:
\begin{minted}{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
)
\end{minted}
\includegraphics{images/rest/models.png}
\section{Mise en place}
La configuration des points de terminaison de notre API peut être relativement touffue.
Pour cette raison, il convient de s'infliger à suivre une structure qui soit similaire pour chaque point de terminaison \cite[Predictability, Rule \#1]{django_for_startup_founders}.
Il convient de:
\begin{enumerate}
\item
\textbf{Spécifier les permissions}
\item
\textbf{Copier et assainir les éléments communiqués en entrée vers des variables locales}
\item
\textbf{Valider les données d'entrée}
\item
\textbf{Enforce business requirements}
\item
\textbf{Perform busines logic}
\item
\textbf{Retourner une réponse HTTP}
\end{enumerate}
-> Répartir les responsabilités selon les composants ci-dessous
\begin{enumerate}
\item
Configurer les sérialiseurs, càd. les champs que nous souhaitons exposer au travers de l'API,
\item
Configurer les vues, càd le comportement de chacun des points de terminaison,
\item
Configurer les points de terminaison eux-mêmes, càd les URLs permettant d'accéder aux ressources.
\item
Et finalement ajouter quelques paramètres au niveau de notre application.
\end{enumerate}
\section{Django Rest Framework}
\subsection{Serialiseurs}
Les sérialiseurs agissent litérallement comme des \texttt{forms}, mais au niveau de l'API.
Ils se basent sur un modèle, définit au niveau de la \texttt{class Meta}, permettent de choisir les champs qui seront sérialisés, définissent différentes méthodes d'accès à des propriétés spécifiques et des méthodes de validation.
Tout comme les forms.
Par exemple, avec Django Rest Framework:
\begin{minted}{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",)
\end{minted}
\subsection{Vues}
\begin{minted}{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]
\end{minted}
\subsection{URLs}
\begin{minted}{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),
]
\end{minted}
\begin{minted}{python}
# settings.py
INSTALLED_APPS = [
...
"rest_framework",
...
]
...
REST_FRAMEWORK = {
'DEFAULT_PAGINATION_CLASS':
'rest_framework.pagination.PageNumberPagination',
'PAGE_SIZE': 10
}
\end{minted}
\subsection{Résultat}
En nous rendant sur l'URL \texttt{http://localhost:8000/api/v1}, nous obtiendrons ceci:
\includegraphics{images/rest/api-first-example.png}
\subsection{Modéles et relations}
Plus haut, nous avons utilisé une relation de type \texttt{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
\url{https://www.django-rest-framework.org/api-guide/relations/}:
\begin{enumerate}
\item Soit \textbf{via} un hyperlien, comme ci-dessus,
\item Soit en utilisant les clés primaires, soit en utilisant l'URL canonique permettant d'accéder à la ressource.
\end{enumerate}
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):
\begin{minted}{js}
{
"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/"
]
}
]
}
\end{minted}
à ceci:
\begin{minted}{js}
{
"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/"
}
]
}
]
}
\end{minted}
La modification se limite à \textbf{surcharger} la propriété, pour
indiquer qu'elle consiste en une instance d'un des sérialiseurs
existants. Nous passons ainsi de ceci
\begin{minted}{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")
\end{minted}
à ceci:
\begin{minted}{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")
\end{minted}
Nous ne faisons donc bien que redéfinir la propriété \texttt{contract\_set} et indiquons qu'il s'agit à présent d'une instance de \texttt{ContractSerializer}, et qu'il est possible d'en avoir plusieurs. C'est tout.
\subsection{Conclusions}
Django-Rest-Framework est une librarie complète qui ajoute énormément de possibilités.
Cependant \cite{django_for_startup_founders}:
\begin{enumerate}
\item
La documentation est \textbf{réellement} compliquée.
Tout nouveau développeur doit appréhender, comprendre et assimiler cette documentation et tous les concepts sous-jacents.
Ceci inclut notamment le fait que tous les verbes HTTP ont été "traduits" (GET -> retrieve, POST -> create, ...).
Ceci a du sens par rapport à la définition d'une interface REST-compliant, mais ajoute une complexité mentale relativement lourde.
\item
Certains concepts de réutilisation sont tellement compliqués qu'ils prennent plus de temps à mettre en place qu'à écrire une ligne de code Python classique
\item
Les sérialiseurs peuvent rapidement devenir difficiles à lire ou relire, spécifiquement lorsque nous utilisons des \textit{nested serializers} ou lorsque les concepts de désérialisation sont abordés.
\end{enumerate}
\section{Marshmallow}
\textit{Marshmallow} est une alternative plus légère à Django-Rest-Framework, et qui présente une interface plus claire, ainsi qu'une documentation plus concise et facile à comprendre.
Une solution plus facile que les sérializeurs de DRF consistera à
\begin{enumerate}
\item
Gérer la validation de données en utilisant Marshmallow
\item
Sérialiser les données en utilisant du code Python \cite{django_for_startup_founders}.
\end{enumerate}
\section{Ninja}
...
\section{OData}
...
\section{Bonnes pratiques}
\subsection{Authentification}
\subsection{Validation des données}
\subsection{Utilisation d'une API Gateway}
\subsection{Rate limiting}
\subsection{Partage des données nécessaires uniquement}

957
chapters/architecture.tex Executable file
View File

@ -0,0 +1,957 @@
\chapter{Eléments d'architecture}
\begin{quote}
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" \emph{a posteriori}.
C'est pour aider les développeurs à rester dans le droit chemin que les principes SOLID ont été énumérés. \cite{gnu_linux_mag_hs_104}
\end{quote}
Les principes SOLID, introduit par Robert C. Martin dans les années 2000 pour orienter le développement de modules, sont les suivants:
\begin{enumerate}
\item
\textbf{SRP} - Single responsibility principle - Principe de Responsabilité Unique
\item
\textbf{OCP} - Open-closed principle
\item
\textbf{LSP} - Liskov Substitution
\item
\textbf{ISP} - Interface ségrégation principle
\item
\textbf{DIP} - Dependency Inversion Principle
\end{enumerate}
Des équivalents à ces directives existent au niveau des composants, puis au niveau architectural:
\begin{enumerate}
\item
Reuse/release équivalence principle,
\item
\textbf{CCP} - Common Closure Principle,
\item
\textbf{CRP} - Common Reuse Principle.
\end{enumerate}
\begin{figure}[H]
\centering
\scalebox{1.0}{\includegraphics[max size={\textwidth}{\textheight}]{images/arch-comp-modules.png}}
\end{figure}
\section{Modules}
\subsection{Single Responsility Principle} \label{SRP}
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 \href{https://en.wikipedia.org/wiki/Unix_philosophy}{Philosophie Unix}, documentée par Doug McIlroy et qui demande de "\emph{faire une seule chose, mais de le faire bien}" \cite{unix_philosophy}.
Selon ce principe, une classe ou un élément de programmation ne doit donc pas avoir plus d'une seule raison de changer.
Plutôt que de centraliser le maximum de code à un seul endroit ou dans une seule classe par convenance ou commodité \footnote{Aussi appelé \emph{God-Like object}}, le principe de responsabilité unique suggère que chaque classe soit responsable d'un et un seul concept.
Une manière de voir les choses consiste à différencier les acteurs ou les intervenants: imaginez disposer d'une classe représentant des données de membres du personnel; ces données pourraient être demandées par trois acteurs:
\begin{enumerate}
\item Le CFO (Chief Financial Officer)
\item Le CTO (Chief Technical Officer)
\item Le COO (Chief Operating Officer)
\end{enumerate}
Chacun d'entre eux aura besoin de données et d'informations relatives à ces membres du personnel, et provenant donc d'une même source de données centralisée.
Mais chacun d'entre eux également 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; celles-ci vont cependant un cran plus loin et pourraient nécessiter des ajustements spécifiques en fonction de l'acteur concerné et de la manière dont il souhaite disposer des données.
Dès que possible, identifiez les différents acteurs et demandeurs, en vue de prévoir les modifications qui pourraient être demandées 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.
Vous trouverez ci-dessous une classe \texttt{Document}, dont chaque instance est représentée par trois propriétés: son titre, son contenu et sa date de publication.
Une méthode \texttt{render} permet également de proposer (très grossièrement) un type de sortie et un format de contenu: \texttt{XML} ou \texttt{Markdown}.
\begin{listing}[H]
\begin{minted}[tabsize=4]{Python}
class Document:
def __init__(self, title, content, published_at):
self.title = title
self.content = content
self.published_at = published_at
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()
)
if format_type == "Markdown":
import markdown
return markdown.markdown(self.content)
raise ValueError(
"Format type '{}' is not known".format(format_type)
)
\end{minted}
\caption{Un convertisseur de document un peu bateau}
\end{listing}
Lorsque nous devrons ajouter un nouveau rendu (Atom, OpenXML, \ldots) il sera nécessaire de modifier la classe \texttt{Document}.
Ceci n'est:
\begin{enumerate}
\item Ni intuitif: \emph{ce n'est pas le document qui doit savoir dans quels formats il peut être converti}
\item Ni conseillé: \emph{lorsque nous aurons quinze formats différents à gérer, il sera nécessaire d'avoir autant de conditions dans cette méthode}.
\end{enumerate}
En suivant le principe de responsabilité unique, une bonne pratique consiste à créer une nouvelle classe de rendu pour chaque type de format à gérer:
\begin{listing}[H]
\begin{minted}[tabsize=4]{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
)
)
\end{minted}
\caption{Isolation du rendu d'un document par rapport à sa modélisation}
\end{listing}
A présent, lorsque nous devrons ajouter un nouveau format de prise en charge, il nous suffira de modifier la classe \texttt{DocumentRenderer}, sans que la classe \texttt{Document} ne soit impactée.
En parallèle, le jour où nous ajouterons un champ champ \texttt{author} à une instance de type \texttt{Document}, 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.
Un autre exemple consiterait à faire communiquer une méthode avec une base de données: ce ne sera pas à cette méthode à gérer l'inscription d'une exception à un emplacement spécifique (emplacement sur un disque, \ldots): cette action doit être prise en compte par une autre classe (ou un autre concept ou composant), qui s'occupera de définir elle-même l'emplacement où l'évènement sera enregistré, que ce soit dans une base de données, une instance Graylog ou 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.
L'équivalent du principe de responsabilité unique au niveau des composants sera le \texttt{Common Closure Principle} \index{CCP}.
Au niveau architectural, cet équivalent correspondra aux frontières.
\subsection{Open-Closed}
\begin{quote}
\textit{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.}
\end{quote}
L'objectif est de rendre le système facile à étendre, en limitant l'impact qu'une modification puisse avoir.
Reprendre notre exemple de modélisation de documents parle de lui-même:
\begin{enumerate}
\item Des données que nous avons converties dans un format spécifique pourraient à présent devoir être présentées dans une page web.
\item Et demain, ce sera dans un document PDF.
\item Et après demain, dans un tableur Excel.
\end{enumerate}
La source de ces données reste la même (au travers d'une couche de présentation): c'est leur mise en forme qui diffère à chaque fois.
L'application n'a pas à connaître les détails d'implémentation: elle doit juste permettre une forme d'extension, sans avoir à appliquer quelconque modification en 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 comme nous l'avons initisée plus tôt 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 prendre un nouvel exemple, nous pourrions ainsi définir trois classes:
\begin{itemize}
\item
Une classe \texttt{Customer}, pour laquelle la méthode \texttt{GetDiscount} ne renvoit rien;
\item
Une classe \texttt{SilverCustomer}, pour laquelle la méthode revoit une réduction de 10\%;
\item
Une classe \texttt{GoldCustomer}, pour laquelle la même méthode renvoit une réduction de 20\%.
\end{itemize}
Si nous devions rencontrer un nouveau type de client, il nous suffira de créer une nouvelle sous-classe, implémentant la réduction que nous souhaitons lui offrir.
Ceci évite d'avoir à gérer un ensemble conséquent de conditions dans la méthode initiale, en fonction d'une variable ou d'un paramètre - ici, le type de client.
Nous passerions ainsi de ceci:
\begin{listing}[H]
\begin{minted}[tabsize=4]{python}
class Customer():
def __init__(self, customer_type: str):
self.customer_type = customer_type
def get_discount(customer: Customer) -> int:
if customer.customer_type == "Silver":
return 10
elif customer.customer_type == "Gold":
return 20
return 0
>>> jack = Customer("Silver")
>>> jack.get_discount()
10
\end{minted}
\end{listing}
A ceci:
\begin{listing}[H]
\begin{minted}[tabsize=4]{python}
class Customer():
def get_discount(self) -> int:
return 0
class SilverCustomer(Customer):
def get_discount(self) -> int:
return 10
class GoldCustomer(Customer):
def get_discount(self) -> int:
return 20
>>> jack = SilverCustomer()
>>> jack.get_discount()
10
\end{minted}
\end{listing}
En anglais, dans le texte : "\emph{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.}".
\textbf{En résumé}: nous fermons la classe \texttt{Customer} à toute modification, mais nous ouvrons la possibilité de créer de nouvelles extensions en ajoutant de nouveaux types héritant de \texttt{Customer}.
De cette manière, nous simplifions également la maintenance de la méthode \texttt{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:
\begin{listing}[H]
\begin{minted}[tabsize=4]{python}
class Document:
def __init__(self, title, content, published_at):
self.title = title
self.content = content
self.published_at = published_at
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()
)
if format_type == "Markdown":
import markdown
return markdown.markdown(self.content)
raise ValueError(
"Format type '{}' is not known".format(format_type)
)
\end{minted}
\end{listing}
devient le suivant:
\begin{listing}[H]
\begin{minted}[tabsize=4]{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):