django-admin personnaliséesLien vers cette rubrique#Les applications peuvent inscrire leurs propres actions auprès de manage.py. Par exemple, il pourrait être utile d’ajouter une action manage.py pour une application Django que vous distribuez. Dans ce document, nous allons créer un commande personnalisée closepoll pour l’application polls écrite dans le tutoriel.
Pour cela, ajoutons simplement un répertoire management/commands dans l’application. Django inscrit une commande manage.py pour chaque module Python dans ce répertoire dont le nom ne commence pas par un soulignement. Par exemple :
polls/\n __init__.py\n models.py\n management/\n __init__.py\n commands/\n __init__.py\n _private.py\n closepoll.py\n tests.py\n views.py\nAvec Python 2, assurez-vous d’inclure des fichiers __init__.py dans les répertoires management et management/commands comme cela est fait ci-dessus, sinon votre commande ne sera pas détectée.
Dans cet exemple, la commande closepoll sera disponible dans tout projet qui inclut l’application polls dans son réglage INSTALLED_APPS.
Le module _private.py ne sera pas disponible en tant que commande de gestion.
Le module closepoll.py n’a qu’une seule exigence : il doit définir une classe Command comme sous-classe de BaseCommand ou l’une de ses sous-classes.
Pour implémenter la commande, modifiez polls/management/commands/closepoll.py comme ceci :
from django.core.management.base import BaseCommand, CommandError\nfrom polls.models import Question as Poll\n\nclass Command(BaseCommand):\n help = 'Closes the specified poll for voting'\n\n def add_arguments(self, parser):\n parser.add_argument('poll_id', nargs='+', type=int)\n\n def handle(self, *args, **options):\n for poll_id in options['poll_id']:\n try:\n poll = Poll.objects.get(pk=poll_id)\n except Poll.DoesNotExist:\n raise CommandError('Poll "%s" does not exist' % poll_id)\n\n poll.opened = False\n poll.save()\n\n self.stdout.write(self.style.SUCCESS('Successfully closed poll "%s"' % poll_id))\nLa nouvelle commande personnalisée peut être appelée en utilisant python manage.py closepoll <poll_id>.
La méthode handle() reçoit une ou plusieurs poll_ids et définit poll.opened à False pour chacun d’eux. Si l’utilisateur indique des identifiants qui n’existent pas, une erreur CommandError est levée. L’attribut poll.opened n’existe pas dans le tutoriel, elle a été ajoutée à polls.models.Question pour cet exemple.
La même commande closepoll pourrait aisément être modifiée afin de supprimer un sondage donné au lieu de le fermer, en acceptant des options supplémentaires en ligne de commande. Ces options personnalisées peuvent être ajoutées dans la méthode add_arguments de cette façon :
class Command(BaseCommand):\n def add_arguments(self, parser):\n # Positional arguments\n parser.add_argument('poll_id', nargs='+', type=int)\n\n # Named (optional) arguments\n parser.add_argument(\n '--delete',\n action='store_true',\n dest='delete',\n default=False,\n help='Delete poll instead of closing it',\n )\n\n def handle(self, *args, **options):\n # ...\n if options['delete']:\n poll.delete()\n # ...\nL’option (delete dans notre exemple) est disponible dans le paramètre dictionnaire options de la méthode handle(). Consultez la documentation Python de argparse pour en savoir plus sur l’utilisation de add_argument.
En plus de pouvoir ajouter des options de ligne de commande personnalisées, toutes les commandes de gestion acceptent certaines options par défaut, telles que --verbosity et --traceback.
Par défaut, la méthode BaseCommand.execute() désactive les traductions car certaines commandes fournies par Django effectuent plusieurs tâches qui exigent une langue de projet neutre, par exemple le rendu de contenu utilisateur ou le remplissage de la base de données.
Si pour une raison ou une autre votre commande de gestion a besoin d’utiliser une locale bien précise, c’est à vous de l’activer et de la désactiver manuellement dans votre méthode handle() en utilisant les fonctions offertes par le code de prise en charge de l’internationalisation :
from django.core.management.base import BaseCommand, CommandError\nfrom django.utils import translation\n\nclass Command(BaseCommand):\n ...\n can_import_settings = True\n\n def handle(self, *args, **options):\n\n # Activate a fixed locale, e.g. Russian\n translation.activate('ru')\n\n # Or you can activate the LANGUAGE_CODE # chosen in the settings:\n from django.conf import settings\n translation.activate(settings.LANGUAGE_CODE)\n\n # Your command logic here\n ...\n\n translation.deactivate()\nUn autre besoin pourrait être que votre commande doive simplement utiliser la langue définie dans les réglages et que Django soit empêché de la désactiver. Vous pouvez faire cela en indiquant l’option BaseCommand.leave_locale_alone.
En travaillant sur la base des scénarios décrits ci-dessus, soyez toutefois conscient que les commandes de gestion système doivent être très prudentes quand elles sont lancées avec des locales changeantes, soyez donc attentif aux points suivants :
\nAssurez-vous que le réglage USE_I18N est toujours True lorsque la commande fonctionne (c’est un bon exemple des problèmes possibles dus à un environnement d’exécution dynamique, ce que les commandes Django évitent en désactivant les traductions).
Passez en revue le code de votre commande et le code qu’elle appelle quant à des différences de comportement lorsque les locales sont modifiées et évaluez l’impact potentiel sur le comportement prévisible de votre commande.
Des informations sur la manière de tester des commandes d’administration personnalisées peuvent être consultées dans la documentation sur les tests.
\nLa classe de base dont toutes les autres commandes de gestion héritent.
\nUtilisez cette classe si vous souhaitez accéder à tous les mécanismes qui analysent les paramètres de ligne de commande et qui aiguillent sur le code à appeler en conséquence. Si vous n’avez pas besoin de modifier ce comportement, considérez l’utilisation de l’une de ses sous-classes.
\nL’héritage direct de la classe BaseCommand exige que vous implémentiez la méthode handle().
Tous les attributs peuvent être définis dans votre sous-classe et peuvent être utilisés dans les sous-classes de BaseCommand.
Une valeur booléenne indiquant si la commande doit pouvoir importer les réglages Django. Si True, execute() vérifiera que c’est bel et bien possible avant de continuer. La valeur par défaut est True.
Une brève description de la commande, qui sera affichée dans le message d’aide lorsque l’utilisateur lance la commande python manage.py help <commande>.
Si votre commande définit des paramètres positionnels obligatoires, vous pouvez personnaliser le message d’erreur renvoyé au cas où le paramètre serait absent. Le message par défaut est produit par argparse (« too few arguments » (trop peu de paramètres)).
Une valeur booléenne indiquant si la commande affiche des commandes SQL ; si True, le contenu en sortie est automatiquement entouré des instructions BEGIN; et COMMIT;. La valeur par défaut est False.
Valeur booléenne ; si True, la commande affiche un avertissement si le jeu de migrations sur disque ne correspond pas aux migrations dans la base de données. Un avertissement n’empêche pas la commande de s’exécuter. La valeur par défaut est False.
Valeur booléenne ; si True, le projet Django entier est contrôlé à la recherche de problèmes potentiels avant l’exécution de la commande. La valeur par défaut est True.
Une valeur booléenne indiquant si la langue définie dans les réglages doit être préservée durant l’exécution de la commande pour empêcher d’être forcée à « en-us ».
\nLa valeur par défaut est False.
Soyez sûr de savoir ce que vous faites si vous décidez de changer la valeur de cette option pour votre propre commande et que celle-ci crée du contenu de base de données variant en fonction de la langue et que ce contenu ne doit pas être traduit (comme cela se passe avec les permissions de django.contrib.auth), car si la langue active est différente de la valeur « en-us » par défaut, vous pourriez rencontrer des problèmes inattendus. Consultez la section Commandes de gestion et langues ci-dessus pour des détails plus complets.
Cette option en peut pas être False lorsque l’option can_import_settings est aussi définie à False parce que le processus de changement de langue a besoin d’accéder aux réglages. Cette condition provoque une erreur CommandError.
Un attribut d’instance aidant à colorer le contenu envoyé aux sorties stdout ou stderr. Par exemple :
self.stdout.write(self.style.SUCCESS('...'))\nVoir Syntaxe colorée pour savoir comment modifier la palette de couleurs et pour connaître les styles disponibles (utilisez les versions en majuscules des « rôles » décrits dans cette section).
\nSi vous passez l’option --no-color lors du lancement de la commande, tous les appels à self.style() renverront la chaîne originale sans couleur.
BaseCommand contient quelques méthodes qui peuvent être surchargées, mais seule la méthode handle() doit absolument être implémentée.
Point d’entrée pour ajouter des paramètres acceptés lors du traitement des paramètres passés en ligne de commande. Les commandes personnalisées doivent surcharger cette méthode pour ajouter les paramètres, qu’ils soient positionnels ou nommés, que cette commande va accepter. L’appel de super() n’est pas nécessaire lorsqu’on hérite directement de BaseCommand.
Renvoie la version de Django, qui devrait être correcte pour toutes les commandes intégrées de Django. Les commandes fournies par les applications non Django peuvent surcharger cette méthode pour retourner leur propre version.
\nEssaie d’exécuter cette commande en procédant aux contrôles systèmes au besoin (selon la valeur de l’attribut requires_system_checks). Si la commande génère une erreur CommandError, celle-ci est interceptée et affichée sur stderr.
Le corps de la logique de votre commande. Les sous-classes doivent implémenter cette méthode.
\nElle peut renvoyer une chaîne Unicode qui sera envoyée vers stdout (encadrée par BEGIN; et COMMIT; si output_transaction vaut True).
Utilise l’infrastructure de vérification système pour inspecter l’ensemble du projet Django à la recherche de problèmes potentiels. Les problèmes graves génèrent des exceptions de type CommandError; les avertissements sont émis sur la sortie d’erreur (stderr) ; les notifications mineures sont émises sur la sortie standard (stdout).
Si app_configs et tags valent tous deux None, tous les contrôles système sont effectués. tags peut être une liste d’étiquettes de contrôle, comme compatibility ou models.
BaseCommandLien vers cette rubrique#Une commande de gestion qui accepte en paramètre une ou plusieurs étiquettes d’applications installées, et applique un traitement à chacune d’elles.
\nPlutôt que d’implémenter handle(), les sous-classes doivent implémenter handle_app_config(), qui sera appelée une seule fois pour chaque application.
Effectue les actions de la commande pour app_config, qui sera une instance de AppConfig correspondant à une étiquette d’application passée via la ligne de commande.
Une commande de gestion qui accepte un ou plusieurs paramètres arbitraires (labels) en ligne de commande et effectue une opération pour chacun d’eux.
\nPlutôt que d’implémenter handle(), les sous-classes doivent implémenter handle_label() qui sera appelée une fois pour chaque paramètre (label).
Une chaîne indiquant les paramètres arbitraires transmis à la commande. La chaîne est utilisée dans le texte d’aide et dans les messages d’erreur de la commande. Contient label par défaut.
Effectue les actions de la commande pour label, qui sera la chaîne telle que passée à la ligne de commande.
Classe d’exception indiquant qu’un problème est survenu lors de l’exécution d’une commande de gestion.
\nSi cette exception est levée durant l’exécution d’une commande de gestion à partir de la console en ligne de commande, elle sera interceptée et transformée en un message d’erreur proprement affiché à destination du flux de sortie approprié (par ex. stderr). En conséquence, le déclenchement de cette exception (accompagné d’une description significative de l’erreur) est la manière privilégiée de signaler que quelque chose s’est mal passé durant l’exécution d’une commande.
\nSi une commande de gestion est appelée depuis du code par l’intermédiaire de call_command(), c’est alors à vous d’intercepter cette exception si nécessaire.