Merge branch 'master' of https://git.framasoft.org/Grimbox/gwift-book
This commit is contained in:
Fred Pauchet
commit
b9afc321a4
|
|
@ -2,12 +2,14 @@
|
|||
Introduction
|
||||
============
|
||||
|
||||
Django se présente comme un `Framework Web pour perfectionnistes ayant des deadlines <https://www.djangoproject.com/>`_. `Django suit quelques principes <https://docs.djangoproject.com/en/dev/misc/design-philosophies/>`_:
|
||||
Django se présente comme un `Framework Web pour perfectionnistes ayant des deadlines <https://www.djangoproject.com/>`_.
|
||||
|
||||
`Django suit quelques principes <https://docs.djangoproject.com/en/dev/misc/design-philosophies/>`_:
|
||||
|
||||
* Faible couplage et forte cohésion, pour que chaque composant ait son indépendance.
|
||||
* Moins de code, plus de fonctionnalités.
|
||||
* `Don't repeat yourself <https://fr.wikipedia.org/wiki/Sec>`_: ne pas se répéter!
|
||||
* Rapidié du développement.
|
||||
* Rapidité du développement.
|
||||
|
||||
.. include:: intro/01-prerequisites.rst
|
||||
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ Avant de démarrer le développement, il est nécessaire de passer un peu de tem
|
|||
|
||||
Les morceaux de code seront développés pour Python3.4+ et Django 1.8+. Ils nécessiteront peut-être quelques adaptations pour fonctionner sur une version antérieure.
|
||||
|
||||
**Remarque** : les commandes qui seront exécutés dans ce livre le seront depuis un shell sous GNU/Linux. Certaines devrons donc être adaptées si vous êtes dans un autre environnemnet.
|
||||
**Remarque** : les commandes qui seront exécutés dans ce livre le seront depuis un shell sous GNU/Linux. Certaines devront donc être adaptées si vous êtes dans un autre environnemnet.
|
||||
|
||||
Virtualenv
|
||||
==========
|
||||
|
|
@ -53,9 +53,9 @@ Nous pouvons ensuite l'activer grâce à la commande ``workon gwift-env``.
|
|||
(gwift-env)$ which python
|
||||
(gwift-env)$ /home/jaguarondi/.virtualenv/gwift-env/bin/python
|
||||
|
||||
Le shell signal que nous sommes bien dans l'environnement gwift-env en l'affichant avant le $. Par la suite, nous considérerons que l'environnement virtuel est toujours activé, même si gwift-env n'est pas présent devant chaque $.
|
||||
Le *shell* signale que nous sommes bien dans l'environnement ``gwift-env`` en l'affichant avant le ``$``. Par la suite, nous considérerons que l'environnement virtuel est toujours activé, même si ``gwift-env`` n'est pas présent devant chaque ``$``.
|
||||
|
||||
A présent, tous les binaires présents dans cet environnement prendront le pas sur les binaires du système. De la même manière, une variable ``PATH`` propre est définie et utilisée, afin que les librairies Python y soient stockées. C'est donc dans cet environnement virutel que nous retrouverons le code-source de Django, ainsi que des librairies externes pour python une fois que nous les aurons installées.
|
||||
A présent, tous les binaires de cet environnement prendront le pas sur les binaires du système. De la même manière, une variable ``PATH`` propre est définie et utilisée, afin que les librairies Python y soient stockées. C'est donc dans cet environnement virtuel que nous retrouverons le code source de Django, ainsi que des librairies externes pour Python une fois que nous les aurons installées.
|
||||
|
||||
Pour désactiver l'environnement virtuel, il suffira d'utiliser la commande ``deactivate``
|
||||
|
||||
|
|
@ -113,6 +113,20 @@ Cette action a pour effet de créer un nouveau dossier ``gwift``, dans lequel on
|
|||
│ └── wsgi.py
|
||||
└── manage.py
|
||||
|
||||
Si vous le souhaitez, et pour plus de clarté, renommez le premier dossier ``gwift`` en ``src``, par exemple: cela évitera d'avoir une structure hiérarchique type ``gwift-project/gwift/gwift``, mais plutôt quelque chose comme ``gwift-project/src/gwift``, sur le modèle ``{projet}/{sources}/{application}``. On a à présent:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
$ tree src
|
||||
src
|
||||
├── gwift
|
||||
│ ├── __init__.py
|
||||
│ ├── settings.py
|
||||
│ ├── urls.py
|
||||
│ └── wsgi.py
|
||||
└── manage.py
|
||||
|
||||
|
||||
Chacun de ces fichiers sert à:
|
||||
|
||||
* ``settings.py`` contient tous les paramètres globaux à notre projet.
|
||||
|
|
@ -123,7 +137,7 @@ Chacun de ces fichiers sert à:
|
|||
Gestion des dépendances
|
||||
=======================
|
||||
|
||||
Comme nous venons d'ajouter une dépendance à notre projet, nous allons créer un fichier reprenant tous les dépendances de notre projet. Ceux-ci sont placés normalement dans un fichier ``requirements.txt``. Dans un premier temps, ce fichier peut être placé directement à la racine du projet, mais on préférera rapidement le déplacer dans un sous-répertoire spécifique (``requirements``), afin de grouper les dépendances en fonction de leur utilité:
|
||||
Comme nous venons d'ajouter une dépendance à notre projet, nous allons créer un fichier reprenant tous les dépendances de notre projet. Celles-ci sont normalement placées dans un fichier ``requirements.txt``. Dans un premier temps, ce fichier peut être placé directement à la racine du projet, mais on préférera rapidement le déplacer dans un sous-répertoire spécifique (``requirements``), afin de grouper les dépendances en fonction de leur utilité:
|
||||
|
||||
* ``base.txt``
|
||||
* ``dev.txt``
|
||||
|
|
@ -147,7 +161,7 @@ Nous avons donc la strucutre finale pour notre environnement de travail:
|
|||
gwift-project/
|
||||
├── docs
|
||||
│ └── README.md
|
||||
├── gwift
|
||||
├── src
|
||||
│ ├── gwift
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── settings.py
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
Une application Django
|
||||
**********************
|
||||
|
||||
Comme on l'a vu ci-dessus, ``django-admin`` permet de créer un nouveau projet. Django fait une distinction entre un **projet** et une **application**:
|
||||
Comme on l'a vu ci-dessus, ``django-admin`` permet de créer un nouveau projet. On fait ici une distinction entre un **projet** et une **application**:
|
||||
|
||||
* **Projet**: ensemble des applications, paramètres, pages HTML, middlwares, dépendances, etc., qui font que votre code fait ce qu'il est sensé faire.
|
||||
* **Application**: *contexte* éventuellement indépendant, permettant d'effectuer une partie isolée de ce que l'on veut faire.
|
||||
|
|
@ -20,7 +20,7 @@ Comme expliqué un peu plus haut, le fichier ``manage.py`` est un *wrapper* sur
|
|||
* ``manage.py runserver`` pour lancer un serveur de développement
|
||||
* ``manage.py test`` pour découvrir les tests unitaires disponibles et les lancer.
|
||||
|
||||
La liste complète peut être affichée avec ``manage.py help``. Vous remarquerez que ces commandes sont groupées:
|
||||
La liste complète peut être affichée avec ``manage.py help``. Vous remarquerez que ces commandes sont groupées selon différentes catégories:
|
||||
|
||||
* **auth**: création d'un nouveau super-utilisateur, changer le mot de passe pour un utilisateur existant.
|
||||
* **django**: vérifier la *compliance* du projet, lancer un *shell*, *dumper* les données de la base, effectuer une migration du schéma, ...
|
||||
|
|
@ -38,7 +38,7 @@ Cette application servira à structurer les listes de souhaits, les éléments q
|
|||
|
||||
.. code-block:: shell
|
||||
|
||||
$ cd gwift
|
||||
$ cd src
|
||||
$ python manage.py startapp wish
|
||||
|
||||
Résultat? Django nous a créé un répertoire ``wish``, dans lequel on trouve les fichiers suivants:
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ Avant d'aller plus loin, donc, un petit point sur les conventions, les tests (un
|
|||
PEP8
|
||||
====
|
||||
|
||||
Le langage Python 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 `Benevolent Dictator For Life <http://fr.wikipedia.org/wiki/Benevolent_Dictator_for_Life>`_.
|
||||
Le langage Python 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 `Benevolent Dictator For Life <http://fr.wikipedia.org/wiki/Benevolent_Dictator_for_Life>`_.
|
||||
|
||||
La PEP qui nous intéresse plus particulièrement pour la suite est la `PEP-8 <https://www.python.org/dev/peps/pep-0008/>`_, ou "Style Guide for Python Code". Elle spécifie des conventions d'organisation et de formatage de code Python, quelles sont les conventions pour l'indentation, le nommage des variables et des classes, etc. En bref, elle décrit comment écrire du code proprement pour que d'autres développeurs puissent le reprendre facilement, ou simplement que votre base de code ne dérive lentement vers un seuil de non-maintenabilité.
|
||||
|
||||
|
|
@ -107,7 +107,7 @@ Complexité de McCabe
|
|||
|
||||
La `complexité cyclomatique <https://fr.wikipedia.org/wiki/Nombre_cyclomatique>`_ (ou complexité de McCabe) peut s'apparenter à une [...]
|
||||
|
||||
A nouveau, un greffon pour ``flake8`` existe et donnera une estimation de la complexité de McCabe pour les fonctions trop complexes. Installez-le avec `pip install mccabe`, et activez-le avec le paramètre `--max-complexity`. Toute fonction dans la complexité est supérieure à 10 est considérée comme trop complexe.
|
||||
A nouveau, un greffon pour ``flake8`` existe et donnera une estimation de la complexité de McCabe pour les fonctions trop complexes. Installez-le avec `pip install mccabe`, et activez-le avec le paramètre ``--max-complexity``. Toute fonction dans la complexité est supérieure à 10 est considérée comme trop complexe.
|
||||
|
||||
// TODO
|
||||
|
||||
|
|
@ -116,29 +116,29 @@ Documentation
|
|||
|
||||
Il existe plusieurs manières de générer la documentation d'un projet. Les plus connues sont `Sphinx <http://sphinx-doc.org/>`_ et `MkDocs <http://www.mkdocs.org/>`_. Le premier a l'avantage d'être plus reconnu dans la communauté Python que l'autre, de pouvoir *parser* le code pour en extraire la documentation et de pouvoir lancer des `tests orientés documentation <https://duckduckgo.com/?q=documentation+driven+development&t=ffsb>`_. A contrario, votre syntaxe devra respecter `ReStructuredText <https://en.wikipedia.org/wiki/ReStructuredText>`_. Le second a l'avantage d'avoir une syntaxe plus simple à apprendre et à comprendre, mais est plus limité dans son résultat.
|
||||
|
||||
Dans l'immédiat, nous nous contenterons d'avoir des modules documentés (quelle que soit la méthode Sphinx/MkDocs/...). Dans la continuié de `Flake8`, il existe un greffon qui vérifie la présence de commentaires au niveau des méthodes et modules développés.
|
||||
Dans l'immédiat, nous nous contenterons d'avoir des modules documentés (quelle que soit la méthode Sphinx/MkDocs/...). Dans la continuié de ``Flake8``, il existe un greffon qui vérifie la présence de commentaires au niveau des méthodes et modules développés.
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
$ pip install flake8_docstrings
|
||||
|
||||
Lancez ensuite `flake8` avec la commande `flake8 . --exclude="migrations"`. Sur notre projet (presque) vide, le résultat sera le suivant:
|
||||
Lancez ensuite `flake8` avec la commande ``flake8 . --exclude="migrations"``. Sur notre projet (presque) vide, le résultat sera le suivant:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
$ flake8 . --exclude="migrations"
|
||||
.\gwift\manage.py:1:1: D100 Missing docstring in public module
|
||||
.\gwift\gwift\__init__.py:1:1: D100 Missing docstring in public module
|
||||
.\gwift\gwift\urls.py:1:1: D400 First line should end with a period (not 'n')
|
||||
.\gwift\wish\__init__.py:1:1: D100 Missing docstring in public module
|
||||
.\gwift\wish\admin.py:1:1: D100 Missing docstring in public module
|
||||
.\gwift\wish\admin.py:1:1: F401 'admin' imported but unused
|
||||
.\gwift\wish\models.py:1:1: D100 Missing docstring in public module
|
||||
.\gwift\wish\models.py:1:1: F401 'models' imported but unused
|
||||
.\gwift\wish\tests.py:1:1: D100 Missing docstring in public module
|
||||
.\gwift\wish\tests.py:1:1: F401 'TestCase' imported but unused
|
||||
.\gwift\wish\views.py:1:1: D100 Missing docstring in public module
|
||||
.\gwift\wish\views.py:1:1: F401 'render' imported but unused
|
||||
.\src\manage.py:1:1: D100 Missing docstring in public module
|
||||
.\src\gwift\__init__.py:1:1: D100 Missing docstring in public module
|
||||
.\src\gwift\urls.py:1:1: D400 First line should end with a period (not 'n')
|
||||
.\src\wish\__init__.py:1:1: D100 Missing docstring in public module
|
||||
.\src\wish\admin.py:1:1: D100 Missing docstring in public module
|
||||
.\src\wish\admin.py:1:1: F401 'admin' imported but unused
|
||||
.\src\wish\models.py:1:1: D100 Missing docstring in public module
|
||||
.\src\wish\models.py:1:1: F401 'models' imported but unused
|
||||
.\src\wish\tests.py:1:1: D100 Missing docstring in public module
|
||||
.\src\wish\tests.py:1:1: F401 'TestCase' imported but unused
|
||||
.\src\wish\views.py:1:1: D100 Missing docstring in public module
|
||||
.\src\wish\views.py:1:1: F401 'render' imported but unused
|
||||
|
||||
|
||||
Bref, on le voit: nous n'avons que très peu de modules, et aucun d'eux n'est commenté.
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ Gwift
|
|||
|
||||
Pour commencer, nous allons nous concentrer sur la création d'un site ne contenant qu'une seule application, même si en pratique le site contiendra déjà plusieurs applications fournies pas django, comme nous le verrons plus loin.
|
||||
|
||||
Pour prendre un exemple concret, nous allons créer un site permettant de gérer des listes de souhaits, que nous appellerons `gwift` (pour `GiFTs and WIshlisTs` :)).
|
||||
Pour prendre un exemple concret, nous allons créer un site permettant de gérer des listes de souhaits, que nous appellerons ``gwift`` (pour ``GiFTs and WIshlisTs`` :)).
|
||||
|
||||
La première chose à faire est de définir nos besoins du point de vue de l'utilisateur, c'est-à-dire ce que nous souhaitons qu'un utilisateur puisse faire avec l'application.
|
||||
|
||||
|
|
|
|||
|
|
@ -10,13 +10,14 @@ Il sera nécessaire de s'authentifier pour :
|
|||
* Ajouter un nouvel élément à une liste
|
||||
|
||||
Il ne sera pas nécessaire de s'authentifier pour :
|
||||
|
||||
* Faire une promesse d'offre pour un élément appartenant à une liste, associée à un utilisateur.
|
||||
|
||||
L'utilisateur ayant créé une liste pourra envoyer un email directement depuis le site aux personnes avec qui il souhaite partager sa liste, cet email contenant un lien permettant d'accéder à cette liste.
|
||||
|
||||
A chaque souhait, on pourrait de manière facultative ajouter un prix. Dans ce cas, le souhait pourrait aussi être subdivisé en plusieurs parts, de manière à ce que plusieurs personnes puissent participer à sa réalisation.
|
||||
A chaque souhait, on pourrait de manière facultative ajouter un prix. Dans ce cas, le souhait pourrait aussi être subdivisé en plusieurs parties, de manière à ce que plusieurs personnes puissent participer à sa réalisation.
|
||||
|
||||
Un souhait pourrait aussi être réalisé plusieurs fois.
|
||||
Un souhait pourrait aussi être réalisé plusieurs fois. Ceci revient à dupliquer le souhait en question.
|
||||
|
||||
********************
|
||||
Besoins fonctionnels
|
||||
|
|
|
|||
Loading…
Reference in New Issue