# Documentation Django 6.0.7

# Tutoriel avancé : concevoir des applications réutilisables

Ce tutoriel avancé commence là où le tutoriel 8 s’est arrêté. Nous allons transformer notre application de sondage Web en un paquet Python autonome qu’il sera possible de réutiliser dans de nouveaux projets et de partager avec d’autres personnes.

Si vous n’avez pas récemment suivi les tutoriels 1–8, nous vous encourageons à les parcourir à nouveau afin que votre exemple de projet corresponde à celui qui est décrit ci-dessous.

## Importance du recyclage

C’est un gros travail de concevoir, construire, tester et maintenir une application Web. Beaucoup de projets Python et Django ont des problématiques communes. Ne serait-il pas merveilleux si nous pouvions économiser un peu de ce travail répétitif ?

Le recyclage de code est un principe de vie en Python. Le site Python Package Index (PyPI) recense une très large variété de paquets qu’il est possible d’utiliser dans ses propres programmes Python. Parcourez le site Django Packages pour trouver des applications réutilisables qu’il est possible d’intégrer dans votre projet. Django lui-même n’est qu’un paquet Python. Cela signifie que vous pouvez prendre des paquets Python ou des applications Django existantes et les composer dans votre propre projet Web. Vous n’avez plus qu’à écrire les parties qui font de votre projet un projet unique.

Disons que vous débutez un nouveau projet qui nécessite une application de sondage telle que celle sur laquelle nous avons travaillé. Comme pouvez-vous recycler cette application ? Heureusement, vous êtes déjà sur la bonne voie. Dans le tutoriel 1, nous avons vu comment découpler les sondages de la configuration d’URL de base du projet en utilisant un `include`. Dans ce tutoriel, nous irons un peu plus loin pour rendre l’application simple à utiliser dans de nouveaux projets et prête à être publiée pour que d’autres puissent l’installer et l’exploiter.

Paquet ? Application ?

Un paquet Python permet de regrouper du code Python pour qu’il puisse être facilement réutilisé. Un paquet contient un ou plusieurs fichiers de code Python (aussi connus sous le nom de « modules »).

Un paquet peut être importé avec `import foo.bar` ou `from foo import bar`. Pour qu’un répertoire (comme `polls`) constitue un paquet, il doit contenir un fichier spécial `__init__.py`, même si ce dernier est vide.

Une application Django est un paquet Python qui est spécialement prévu pour fonctionner dans un projet Django. Une application peut utiliser des conventions Django partagées, comme la présence de sous-modules `models`, `tests`, `urls` et `views`.

Par la suite, nous utilisons le terme empaquetage (packaging) pour décrire le processus de création d’un paquet Python facile à installer par tout le monde. Cela peut prêter à confusion, effectivement.

## Votre projet et votre application recyclable

Après les tutoriels précédents, notre projet devrait ressembler à ceci :

    djangotutorial/
        manage.py
        mysite/
            __init__.py
            settings.py
            urls.py
            asgi.py
            wsgi.py
        polls/
            __init__.py
            admin.py
            apps.py
            migrations/
                __init__.py
                0001_initial.py
            models.py
            static/
                polls/
                    images/
                        background.png
                    style.css
            templates/
                polls/
                    detail.html
                    index.html
                    results.html
            tests.py
            urls.py
            views.py
        templates/
            admin/
                base_site.html

Vous avez créé `djangotutorial/templates` dans le tutoriel 7 et `polls/templates` dans le tutoriel 3. Il est peut-être maintenant plus facile de comprendre pourquoi nous avons séparé les répertoires de gabarits du projet de ceux de l’application : tout ce qui fait partie de l’application de sondage se trouve dans `polls`. L’application forme un tout par elle-même et est ainsi plus facile à intégrer dans un nouveau projet.

Le répertoire `polls` pourrait maintenant être copié dans un nouveau projet Django pour être immédiatement utilisé. L’application n’est cependant pas encore tout à fait prête pour être publiée. Pour cela, il faut encore empaqueter l’application afin que d’autres puissent facilement l’installer.

## Installation de quelques prérequis

L’état actuel de la construction de paquets Python est un peu embrouillé par l’utilisation de plusieurs outils. Dans ce tutoriel, nous allons utiliser setuptools pour construire nos paquets. C’est l’outil d’empaquetage que nous recommandons (fusionné avec le dérivé `distribute`). Nous utiliserons aussi pip pour l’installer et le désinstaller. Vous devriez installer maintenant ces deux paquets. Si vous avez besoin d’aide, vous pouvez vous référer à comment installer Django avec pip. Vous pouvez installer `setuptools` de la même manière.

## Empaquetage de l’application

L”empaquetage Python se réfère à la préparation d’une application dans un format spécifique qui peut être facilement installé et utilisé. Django lui-même est empaqueté de manière très semblable. Pour une petite application comme la nôtre, ce processus n’est pas trop difficile.

1. Premièrement, créez un répertoire parent pour le paquet, en dehors de votre projet Django. Nommez ce répertoire `django-polls`.

   Choix d’un nom pour votre application

   Lors du choix d’un nom de paquet, vérifiez sur PyPI pour éviter des conflits de nommage avec des paquets existants. Nous recommandons d’utiliser un préfixe `django-` pour les noms de paquets, pour clarifier le fait que votre paquet est spécifique à Django, ainsi qu’un préfixe `django_` pour le nom du module. Par exemple, le paquet `django-ratelimit` contient le module `django_ratelimit`.

   Les étiquettes d’applications (c’est-à-dire la partie finale du chemin pointé vers le paquet de l’application) figurant dans `INSTALLED_APPS` doivent être uniques. Évitez d’utiliser la même étiquette que l’une des applications contribuées de Django, par exemple `auth`, `admin` ou `messages`.

2. Déplacez le répertoire `polls` dans le répertoire `django-polls` et renommez-le en `django_polls`.

3. Modifiez `django_polls/apps.py` afin que `name` se réfère au nouveau nom de module, ajoutez `label` pour donner un nom court à l’application, puis définissez `default_auto_field` pour vous assurer que vos migrations ne sont pas touchées par les modifications à `DEFAULT_AUTO_FIELD` effectuées par les utilisateurs de votre application réutilisable :

   `django-polls/django_polls/apps.py`

       from django.apps import AppConfig

       class PollsConfig(AppConfig):
           default_auto_field = "django.db.models.BigAutoField"
           name = "django_polls"
           label = "polls"

4. Créez un fichier `django-polls/README.rst` contenant ceci :

   `django-polls/README.rst`

       ============
       django-polls
       ============

       django-polls is a Django app to conduct web-based polls. For each
       question, visitors can choose between a fixed number of answers.

       Detailed documentation is in the "docs" directory.

       Quick start
       -----------

       1. Add "polls" to your INSTALLED_APPS setting like this::

           INSTALLED_APPS = [
               ...,
               "django_polls",
           ]

       2. Include the polls URLconf in your project urls.py like this::

           path("polls/", include("django_polls.urls")),

       3. Run ``python manage.py migrate`` to create the models.

       4. Start the development server and visit the admin to create a poll.

       5. Visit the ``/polls/`` URL to participate in the poll.

5. Créez un fichier `django-polls/LICENSE`. Le choix d’une licence n’est pas dans le thème de ce tutoriel, mais nous vous rendons attentif au fait que du code publié sans licence est inutile. Django et de nombreuses applications compatibles Django sont distribués sous licence BSD ; vous êtes bien sûr libre d’utiliser la licence de votre choix. Sachez seulement que le choix de la licence a un impact sur la quantité d’utilisateurs potentiels de votre code.

6. Ensuite, nous allons créer le fichier `pyproject.toml` pour donner des détails sur la façon de construire et d’installer l’application. Nous ne nous lancerons pas dans une explication détaillée de ce fichier, mais vous trouverez plus d’informations dans le guide Packaging Python. Créez le fichier `django-polls/pyproject.toml` avec le contenu suivant :

   `django-polls/pyproject.toml`

       [build-system]
       requires = ["setuptools>83"]
       build-backend = "setuptools.build_meta"

       [project]
       name = "django-polls"
       version = "0.1"
       dependencies = [
           "django>=X.Y",  # Replace "X.Y" as appropriate
       ]
       description = "A Django app to conduct web-based polls."
       readme = "README.rst"
       license = "BSD-3-Clause"
       requires-python = ">= 3.12"
       authors = [
           {name = "Your Name", email = "yourname@example.com"},
       ]
       classifiers = [
           "Environment :: Web Environment",
           "Framework :: Django",
           "Framework :: Django :: X.Y",  # Replace "X.Y" as appropriate
           "Intended Audience :: Developers",
           "Operating System :: OS Independent",
           "Programming Language :: Python",
           "Programming Language :: Python :: 3",
           "Programming Language :: Python :: 3 :: Only",
           "Programming Language :: Python :: 3.12",
           "Programming Language :: Python :: 3.13",
           "Programming Language :: Python :: 3.14",
           "Topic :: Internet :: WWW/HTTP",
           "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
       ]

       [project.urls]
       Homepage = "https://www.example.com/"

7. De nombreux fichiers courants, ainsi que les modules et paquets Python sont inclus par défaut dans le paquet. Pour ajouter des fichiers supplémentaires, il faudra créer un fichier `MANIFEST.in`. Pour inclure les gabarits et les fichiers statiques, créez un fichier `django-polls/MANIFEST.in` avec le contenu suivant :

   `django-polls/MANIFEST.in`

       recursive-include django_polls/static *
       recursive-include django_polls/templates *

8. Il est facultatif, mais recommandé, d’inclure de la documentation détaillée dans votre application. Créez un répertoire vide `django-polls/docs` en prévision du futur contenu documentaire.

   Notez que le répertoire `docs` ne sera pas inclus dans votre paquet tant que vous n’y ajoutez pas de fichier. Beaucoup d’applications Django offrent aussi un version en ligne de leur documentation par le moyen de sites comme readthedocs.org.

   Beaucoup de projets Python, y compris Django et Python lui-même, utilisent Sphinx pour construire leur documentation. Si vous choisissez d’utiliser Sphinx, vous pouvez créer des liens vers la documentation de Django en configurant Intersphinx et en incluant une valeur pour Django dans la valeur `intersphinx_mapping` de votre projet :

       intersphinx_mapping = {
           # ...
           "django": (
               "https://docs.djangoproject.com/en/stable/",
               None,
           ),
       }

   Avec cette configuration, vous pouvez ajouter des références croisées vers des entrées spécifiques, de la même manière que dans la documentation de Django, comme par exemple « `:attr:`django.test.TransactionTestCase.databases`` ».

9. Vérifiez que le paquet build est installé (`python -m pip install build`) et testez la construction du paquet en lançant `python -m build` dans `django-polls`. Ceci va créer un répertoire nommé `dist` et y créer le nouveau paquet dans les formats source et binaire, `django_polls-0.1.tar.gz` et `django_polls-0.1-py3-none-any.whl`.

Pour plus d’informations sur l’empaquetage, consultez (en anglais) le Tutoriel sur l’empaquetage et la distribution de projets.

## Utilisation de son propre paquet

Comme nous avons déplacé le répertoire `polls` hors du projet, celui-ci ne fonctionne plus. Nous allons maintenant corriger ça en installant notre nouveau paquet `django-polls`.

Installation en tant que bibliothèque utilisateur

Les étapes suivantes installent `django-polls` comme une bibliothèque utilisateur. Les installations « utilisateur » comportent bien des avantages sur l’installation de paquets au niveau système, comme de pouvoir être utilisables sur des systèmes dont vous n’êtes pas administrateur ou pour éviter que le paquet ne perturbe des services du système ou d’autres utilisateurs de la machine.

Notez que les installations « utilisateur » peuvent tout de même influencer le comportement d’outils système qui tournent sous l’identité de cet utilisateur, il est donc plus robuste d’utiliser un environnement virtuel (voir ci-dessous).

1. Pour installer le paquet, utilisez pip (vous l’avez déjà installé, n’est-ce pas ?) :

       python -m pip install --user django-polls/dist/django_polls-0.1.tar.gz

2. Mettez à jour `mysite/settings.py` pour pointer vers le nouveau nom de module :

       INSTALLED_APPS = [
           "django_polls.apps.PollsConfig",
           ...,
       ]

3. Mettez à jour `mysite/urls.py` pour pointer vers le nouveau nom de module :

       urlpatterns = [
           path("polls/", include("django_polls.urls")),
           ...,
       ]

4. Lancez le serveur de développement pour confirmer que le projet fonctionne toujours.

## Publication de l’application

Après avoir empaqueté et testé `django-polls`, il est prêt à être partagé avec le monde entier ! Si ce n’était pas qu’un exemple, vous pourriez maintenant :

- Envoyer le paquet à un ami par courriel.

- Envoyer le paquet sur votre site Web.

- Publier le paquet dans un dépôt public, tel que le Python Package Index (PyPI). Il existe un bon tuto (en anglais) qui explique comment faire cela.

## Installation de paquets Python avec un environnement virtuel

Précédemment, nous avons installé `django-polls` comme bibliothèque utilisateur. Cela comporte quelques désavantages :

- La modification de bibliothèques utilisateurs peut influencer d’autres logiciels Python sur votre système.

- Vous ne pourrez pas faire fonctionner plusieurs versions de ce paquet en parallèle (ou avec d’autres portant le même nom).

Typiquement, ces situations ne se produisent que lorsque vous maintenez plusieurs projets Django. Dans ces cas, la meilleure solution est d’utiliser venv. Cet outil permet de maintenir plusieurs environnements Python isolés les uns des autres, ayant chacun leur propre copie des bibliothèques et de l’espace de nom des paquets.