Escrevendo comandos do Django Admin
personalizados¶
Os aplicativos podem registrar suas próprias ações com manage.py
. Por exemplo, você pode querer adicionar uma ação manage.py
para uma aplicação Django que você está distribuindo. Neste documento, construiremos um comando customizado closepoll
para a aplicação polls
do tutorial.
Pra tal, adicione um diretório management/commands
a sua aplicação. O Django irá registrar um comando manage.py
para cada módulo Python dentro deste diretório, cujo o nome não inicie com underscore. Por exemplo:
polls/
__init__.py
models.py
management/
__init__.py
commands/
__init__.py
_private.py
closepoll.py
tests.py
views.py
Em Python 2, tenha certeza de incluir arquivo __init__.py
em ambos os diretórios management
e management/commands
como feito acima ou seus comandos não serão detectados.
Neste exemplo, o comando closepoll
estará disponível a qualquer projeto que inclui a aplicativo polls
em :setting: INSTALLED_APPS.
O módulo _private.py
não estará disponível como um “management command”
O módulo closepoll.py
tem apenas uma exigência – deve definir uma classe Command
que se extende BaseCommand
ou um dos seus subclasses.
scripts autônomos
“Management-comands” customizados, são especialmente úteis para a execução de scripts independentes ou para scripts que são periodicamente executadas a partir do crontab do UNIX ou do painel de controle de tarefas agendadas do Windows.
Para implementar o comando, edite polls/management/command/closepoll.py
para que fique assim:
from django.core.management.base import BaseCommand, CommandError
from polls.models import Question as Poll
class Command(BaseCommand):
help = 'Closes the specified poll for voting'
def add_arguments(self, parser):
parser.add_argument('poll_id', nargs='+', type=int)
def handle(self, *args, **options):
for poll_id in options['poll_id']:
try:
poll = Poll.objects.get(pk=poll_id)
except Poll.DoesNotExist:
raise CommandError('Poll "%s" does not exist' % poll_id)
poll.opened = False
poll.save()
self.stdout.write(self.style.SUCCESS('Successfully closed poll "%s"' % poll_id))
Antes de Django 1.8, comandos de gerenciamento foram baseados no módulo optparse
e argumentos posicionais eram passados em *args
enquanto argumentos opcionais eram passados em **options
. Agora que os comandos de gerenciamento usam argparse
para fazer o parser dos argumentos, todos os argumentos são passados em **options
por padrão, a menos que argumentos posicionais sejam nomeados para args
(modo de compatibilidade). Encorajamos a usar exclusivamente **options
para novos comandos.
Nota
Quando estiver usando comandos de gerenciamento e desejar enviar a saída para console, deve se escrever para o `` self.stdout`` e self.stderr
, em vez de imprimir para o stdout
e stderr
diretamente. Ao usar esses proxies, torna-se muito mais fácil para testar o seu comando personalizado. Observe também que você não precisa terminar mensagens com um caractere de nova linha, este será adicionado automaticamente, a menos que você especifique o parâmetro ending
:
self.stdout.write("Unterminated line", ending='')
O novo comando personalizado pode ser chamado usando python manage.py closepoll <poll_id>
.
The handle()
method takes one or more poll_ids
and sets poll.opened
to False
for each one. If the user referenced any nonexistent polls, a
CommandError
is raised. The poll.opened
attribute does not exist in
the tutorial and was added to
polls.models.Question
for this example.
Aceitando argumentos opcionais¶
O mesmo closepoll
poderia ser facilmente modificado para excluir uma determinada “poll”, ao invés de fechá-lo, aceitando as opções de linha de comando adicionais. Estas opções personalizadas podem ser adicionadas no método add_arguments()
como este:
class Command(BaseCommand):
def add_arguments(self, parser):
# Positional arguments
parser.add_argument('poll_id', nargs='+', type=int)
# Named (optional) arguments
parser.add_argument(
'--delete',
action='store_true',
dest='delete',
default=False,
help='Delete poll instead of closing it',
)
def handle(self, *args, **options):
# ...
if options['delete']:
poll.delete()
# ...
Anteriormente, somente a biblioteca padrão optparse
era aceita e era necessário “extender” a variável do comando option_list
com` optparse.make_option()`.
A opção ( delete
no nosso exemplo) está disponível no parâmetro dict das opções do método “hanfle()”. Veja argparse
na documentaçao do Python para saber mais sobre o uso do add_argument
.
Além de ser capaz de adicionar opções de linha de comando personalizada, todos comandos de gereciamento aceitam algumas opções padrão, tais como :opção:`–verbosity` e :opção:`–traceback`.
Comandos de Gerenciamento e localidades¶
Por padrão, o método BaseCommand.execute()
desativa traduções porque alguns comandos internos do Django executam várias tarefas (por exemplo, renderização de conteúdo voltado ao usuário e popular o banco de dados) que exigem uma língua neutra no projeto.
Nas versões anteriores, o Django forçou a localização para “en-us” ao invés de desativar traduções.
Se por algum motivo, o seu comando personalizado de gerenciamento precisar usar um local fixo, é necessário que o suporte a “locale” seja ativar e desativado manualmente no método handle()
usando as funções fornecidas pelo código de apoio I18N:
from django.core.management.base import BaseCommand, CommandError
from django.utils import translation
class Command(BaseCommand):
...
can_import_settings = True
def handle(self, *args, **options):
# Activate a fixed locale, e.g. Russian
translation.activate('ru')
# Or you can activate the LANGUAGE_CODE # chosen in the settings:
from django.conf import settings
translation.activate(settings.LANGUAGE_CODE)
# Your command logic here
...
translation.deactivate()
Outra necessidade pode ser que o seu comando simplesmente deva utilizar a definição de “locale” definido no “settings” e o Django deve ser mantido sem desativá-lo. Você pode fazer isso usando a opção BaseCommand.leave_locale_alone
.
Ao trabalhar nos cenários descritos acima, porém, considere que comandos de gerenciamento de sistemas em tipicamente que ser muito cuidadosos sobre o funcionamento em locais não-uniformes, de modo que você pode precisar:
Verifique se o
USE_I18N
é sempreTrue
ao executar o comando (este é um bom exemplo dos potenciais problemas decorrentes de um ambiente de execução dinâmico que comandos do Django evitam desativando traduções).Rever o código do seu comando e o código que este chama para diferenças de comportamento quando os locais são alteradas e avaliar o seu impacto sobre o comportamento previsível de seu comando.
Testando¶
Informações sobre como testar comandos de gerenciamento personalizado pode ser encontrada no documentação de teste.
Objetos Command¶
-
class
BaseCommand
[código fonte]¶
A classe base a partir da qual todos os comandos de gestão, em última análise derivam.
Use esta classe se você quer acesso a todos os mecanismos que realizam o parse dos argumentos da linha de comando e verificar que código chamar em resposta; se você não precisa mudar nada deste comportamento, considere usar um desses subclasses.
Subclasssing a classe BaseCommand
requer que você implemente o método handle()
.
Atributos¶
Todos os atributos podem ser definidos em sua classe derivada e pode ser usado nas subclasses de BaseCommand
-
BaseCommand.
args
¶ A string que lista os argumentos aceitos pelo comando, adequado para o uso em mensagens de ajuda; ex., um comando que tem uma lista de nomes de aplicativos pode definir isso como ‘<app_label app_label ...>’.
Obsoleto desde a versão 1.8: Isto deve ser feito agora no método
add_arguments()
, chamando o métodoparser.add_argument()
. Veja o exemploclosepoll
acima.
-
BaseCommand.
can_import_settings
¶ Um booleano que indica se o comando precisa ser capaz de importar configurações do Django; Se
True
,execute()
irá verificar se isso é possível antes de prosseguir. O valor padrão éTrue
.
-
BaseCommand.
help
¶ Uma breve descrição do comando, que será impresso na mensagem de ajuda quando o usuário executar o comando
python manage.py help <command>
.
-
BaseCommand.
missing_args_message
¶ - New in Django 1.8.
Se o seu comando define argumentos posicionais obrigatórios, você pode personalizar a mensagem de erro devolvida em caso de falta de argumentos. O padrão é a saída por
argparse
(“poucos argumentos”).
-
BaseCommand.
option_list
¶ Esta é a lista de opções do
optparse
que serão alimentados no comando doOptionParser
para análise.Obsoleto desde a versão 1.8: Deve-se agora sobrescrever o método
add_arguments()
para adicionar os argumentos personalizados aceitos pelo seu comando. Veja o exemplo acima.
-
BaseCommand.
output_transaction
¶ Um booleano que indica como os comandos retornam SQL “statements”; Se
True
, a saída será automaticamente envolvido comBEGIN;
eCOMMIT;
. O valor padrão éFalse
.
-
BaseCommand.
requires_system_checks
¶ Um booleano; Se
True
, todo o projeto Django será verificado sobre potenciais problemas antes de executar o comando. O valor padrão éTrue
.
-
BaseCommand.
leave_locale_alone
¶ Um booleano que indica se o local definido nas configurações devem se preservado durante a execução do comando em vez de ser forçosamente definido como ‘en-us’.
O valor padrão é
False
.Verifique se sabe o que você está fazendo se decidir mudar o valor dessa opção em seu comando personalizado se ele cria conteúdo de banco de dados que é sensível ao local e tal conteúdo não deve conter quaisquer traduções (como acontece por exemplo com permissões em django.contrib.auth) fazendo com que o o local diferente do padrão de fato ‘en-us’ pode causar efeitos indesejados. Veja a seção comandos de gestão e locales acima para mais detalhes.
Esta opção não pode ser
False
quando a opçãocan_import_settings
está definido comoFalse
também porque a tentativa de definir a localidade precisa de acesso às configurações. Esta condição irá gerar umCommandError
.
-
BaseCommand.
style
¶ Um atributo de instância que ajuda a criar uma saída colorida quando se escreve no
stdout
oustderr
. Por exemplo:self.stdout.write(self.style.SUCCESS('...'))
Veja sintaxe-coloring para aprender como modificar a paleta de cores e ver os estilos disponíveis (use caixa-alta das versões das opções descritas nessa seção).
Se você passar a opção
--no-color
ao executar o seu comando, todas as chamadasself.style()
retornarão a string original sem colorir.
Métodos¶
BaseCommand
tem alguns métodos que podem ser sobrescritos mas apenas o método handle()
deve ser implementado.
Implementando um construtor em uma subclasse
Se você implementar __init__
em sua subclasse de BaseCommand
, você deve chamar: o __init__
do class:` BaseCommand`:
class Command(BaseCommand):
def __init__(self, *args, **kwargs):
super(Command, self).__init__(*args, **kwargs)
# ...
-
BaseCommand.
add_arguments
(parser)[código fonte]¶ - New in Django 1.8.
Ponto de entrada que recebe argumentos do “parser” para manipular comandos passados pela linha de comando. Comandos personalizados devem sobrescrever este método para adicionar ambos argumentos posicionais ou opicionais que sejam aceitos pelo comando. Não é necessário chamar o
super()
quando for uma subclasse deBaseCommand
.
-
BaseCommand.
get_version
()[código fonte]¶ Retorna a versão do Django, que deve estar correto para todos os comandos internos do Django. É possível sobrescrever este método para que comandos fornecidos pelo usuário possam retornar a sua própria versão.
-
BaseCommand.
execute
(*args, **options)[código fonte]¶ Tenta executar este comando, realizando verificações de sistemas se necessário (como controlado pelo atributo
requires_system_checks
). Se o comando gerar umCommandError
, este é interceptado e impresso no stderr.
Chamando um comando de gestão dentro do seu código
execute()
não deve ser chamado diretamente do seu código para executar um comando. Ao invés disso, use call_command()
.
-
BaseCommand.
handle
(*args, **options)[código fonte]¶ A lógica real do comando. Subclasses devem implementar este método.
Ele pode retornar uma string Unicode que será impresso para
stdout
(envolvido porBEGIN;
e `` COMMIT; `` seoutput_transaction
forTrue
).
-
BaseCommand.
check
(app_configs=None, tags=None, display_num_errors=False)[código fonte]¶ Usa a estrutura de verificação do sistema para inspecionar todo o projeto Django para os potenciais problemas. Graves problemas são levantados como
CommandError
; avisos são enviados para stderr; notificações menos importantes são enviados para stdout.Se ambos
app_configs
etags
foremNone
, todas as verificações do sistema são realizadas. `` Tags`` pode ser uma lista tags de checagem, comocompatibility
oumodels
.
Subclasses de BaseCommand
¶
-
class
AppCommand
¶
Um comando de gestão que recebe como argumento um ou mais “labels” de aplicações instaladas, e faz alguma coisa com cada um deles.
Melhor que implementar handle()
, as subclasses devem implementar :meth:` ~AppCommand.handle_app_config`, que será chamado uma vez para cada aplicação.
-
AppCommand.
handle_app_config
(app_config, **options)¶ Executar ações do comando para
app_config
, o qual será uma instância deAppConfig
correspondente a um label do aplicativo informado na linha de comando.
-
class
LabelCommand
¶
Um comando de gestão que recebe um ou mais argumentos arbitrários (“labels”) na linha de comando, e faz alguma coisa com cada um deles.
Em vez de implementar handle()
, subclasses devem implementar handle_label()
, que será chamado uma vez para cada etiqueta.
-
LabelCommand.
handle_label
(label, **options)¶ Executar ações do comando para
label
, que será a string como informada na linha de comando.
-
class
NoArgsCommand
¶
Obsoleto desde a versão 1.8: Use BaseCommand
no lugar, que por padrão não tem argumentos.
Um comando que não recebe argumentos da linha de comando
Ao invés de implementar o handle()
, subclasses devem implementar handle_noargs()
; handle()
que será sobrescrito para ter certeza que nenhum argumento foi passado do comando
-
NoArgsCommand.
handle_noargs
(**options)¶ Executar ações deste comando
Exceções de comando¶
-
exception
CommandError
[código fonte]¶
A classe de exceção indica um problema ao executar um comando de gestão.
Se esta exceção é gerada durante a execução de um comando de gerenciamento chamado do console da linha de comando, ele será capturado e transformado em uma mensagem de erro devidamente impresso para a saída apropriada (isto é, stderr); como resultado, gerar essa exceção (com uma descrição sensata do erro) é a maneira preferida para indicar que algo deu errado na execução de um comando.
Se um comando de gestão é chamado do código através do call_command()
, cabe a você capturar a exceção quando necessário.