O arquivo settings do Django contém toda configuração de sua instalação do Django. Este documento explica como o settings funciona e quais configurações estão disponíveis.
Um arquivo settings é só um módulo Python com variáveis a nível de módulo.
Aqui tem um exemplo de configurações:
DEBUG = False
DEFAULT_FROM_EMAIL = 'webmaster@example.com'
TEMPLATE_DIRS = ('/home/templates/mike', '/home/templates/john')
Because a settings file is a Python module, the following apply:
Pelo arquivo settings ser um módulo Python, o seguinte se aplica:
Ele não permite erros de syntaxe do Python.
Ele pode atribuir configurações dinâmicamente usando a sintaxe normal do Python. Por exemplo:
MY_SETTING = [str(i) for i in range(30)]
Ele pode importar valores de outros arquivos settings.
Quando você usa o Django, você tem de informá-lo quais configurações você está usando. Faça isso usando uma variável de ambiente, DJANGO_SETTINGS_MODULE.
O valor do DJANGO_SETTINGS_MODULE deve ser na sintaxe de caminhos do Python, e.g. mysite.settings. Note que o módulo settings deve estar no caminho de import do Python.
Quando estiver usando o django-admin.py, você pode setar ambos, variável de ambiente, ou explicitamente passar o módulo settings toda que você rodar o utilitário.
Exemplo (Unix Bash shell):
export DJANGO_SETTINGS_MODULE=mysite.settings
django-admin.py runserver
Exemplo (Windows shell):
set DJANGO_SETTINGS_MODULE=mysite.settings
django-admin.py runserver
Use o argumento de linha de comando --settings para especificar o settings manualmente:
django-admin.py runserver --settings=mysite.settings
No seu ambiente de servidor, você precisará dizer ao Apache/mod_python qual arquivo settings usar. Faça isso com SetEnv:
<Location "/mysite/">
SetHandler python-program
PythonHandler django.core.handlers.modpython
SetEnv DJANGO_SETTINGS_MODULE mysite.settings
</Location>
Leia a documentação do mod_python do Django para mais informações.
Um arquivo settings do Django não tem que definir quaisquer configurações se não for necessário. Cada configuração tem um valor padrão. Estes valores padrão ficam no módulo django/conf/global_settings.py.
Aqui tem o algorítimo que o Django usa ao compilar o settings:
Note que o arquivo settings não deve importar o global_settings, porquê isto é redundante.
Há uma forma fácil de ver quais das suas configurações desviam do padrão. O comando python manage.py diffsettings mostra as diferenças entre as configurações atuais e do arquivo de configuração padrão do Django.
Para mais, veja a documentação do diffsettings.
Em suas aplicações Django, use o settings importando o objeto django.conf.settings. Exemplo:
from django.conf import settings
- if settings.DEBUG:
- # Faça algo
Note que o django.conf.settings não é um módulo -- ele é um objeto. Então importar uma configuração individual não é possível:
from django.conf.settings import DEBUG # Isto não funcionará.
Também perceba que seu código não deve importar o global_settings ou o seu próprio arquivo settings. O django.conf.settings abstrai o conceito de configurações globais e específicas do site; ele apresenta em uma única interface. Ele também dissocia o código que utiliza as definições a partir da localização do seu settings.
Você não deve alterar o settings nas suas aplicação em tempo de execução. Por exemplo, não faça isso em um view:
from django.conf import settings
settings.DEBUG = True # Não faça isso!
O único lugar onde você deve modificar as configurações é no arquivos settings.
Por um arquivo settings conter informações sensíveis, como a senha do banco de dados, você deve fazer de tudo para evitar o limite de acesso a ele. Por exemplo, mude suas permissões de arquivo de forma que só você e seu usuário do servidor Web poderão lê-lo. Isso é excencialmente importante e um ambiente de hospedagem compartilhada.
Para uma lista completa das configurações disponíveis, veja a referência do settings.
Não há nada que impeça você de criar seu próprio settings, para sua aplicação Django. Só siga estas convenções:
Para configurações sequênciais, o próprio Django utiliza tuplas, no lugar de listas, mas esta é somente uma convenção.
Em alguns casos, você pode querer não passa a variável de ambiente DJANGO_SETTINGS_MODULE. Por exemplo, se você estiver usado o sistema de template somente, você provavelmente não vai querer ter que configurar uma variável de ambiente apontando apra o módulo settings.
Nestes casos, você pode configurar o settings do Django manualmente. Faça isso chamando:
Exemplo:
from django.conf import settings
settings.configure(DEBUG=True, TEMPLATE_DEBUG=True,
TEMPLATE_DIRS=('/home/web-apps/myapp', '/home/web-apps/base'))
Passe ao configure() tantos argumentos quantos você quiser, com cada argumento nomeado representando uma configuração e seu valor. Cada nome de argumento deve ser todo em maiúsculo, com o mesmo nome como descrito acima. Se uma configuração particular não for passada para o configure() e ela for necessária em algum ponto mais a frente, o Django usará o valor padrão.
Configurar o Django deste jeito é sobre tudo necessário -- e, realmente, recomendado -- quando você estiver usando uma parte do framework dentro de uma aplicação maior.
Consequentemente, quando configurado via settings.configure(), o Django não fará quaisquer modificações nas variáveis de ambiente do processo (veja a documentação do TIME_ZONE para saber porque isso normalmente ocorre). Ele assume que você já está no controle total do seu ambiente nestes casos.
Se você gostaria de valores padrão de outros lugares além do django.conf.global_settings, você pode passar num módulo ou classe que fornece as configurações padrão como o argumento default_settings (ou como o primeiro argumento posicional) na chamada do configure().
Neste exemplo, configurações padrão são recebidas do myapp_defaults, e a configuração DEBUG é setada para True, indiferente do seu valor em myapp_defaults:
from django.conf import settings
from myapp import myapp_defaults
settings.configure(default_settings=myapp_defaults, DEBUG=True)
O exemplo a seguir, usa o myapp_defaults como um agumento posicional:
settings.configure(myapp_defaults, DEBUG = True)
Normalmente, você não precisará sobrescrever os valores padrão. O padrões do Django são suficientemente fáceis de lidar, e você pode seguramente utilizá-los. Seja cuidadoso se você for passar um novo módulo padrão, e ele substituir inteiramente os valores padrão do Django, então você deve especificar um valor para toda configuração possível que poderia ser utilizada pelo código que você está importanto. Confira a lista completa no django.conf.settings.global_settings.
Se você não configurar a variável de ambiente DJANGO_SETTINGS_MODULE, você deve chamar configure() no mesmo ponto antes de usar qualquer código que leia configurações.
Se você não setar o DJANGO_SETTINGS_MODULE e não chamar o configure(), o Django lançará uma exceção ImportError na primeira vez que uma configuração for acessada.
Se você setar o DJANGO_SETTINGS_MODULE, acessar valores do settings de alguma maneira, e então chamar o configure(), o Django lançará um erro RuntimeError indicando que as configurações já foram carregadas.
Também, é um erro chamar o configure() mais de uma vez, ou chamar configure() depois que qualquer configuração fora acessada.
Em resumo é isto: Use exatamente um dos dois, configure() ou DJANGO_SETTINGS_MODULE. Não os dois, nem nenhum.
Dec 26, 2011