# documentação Django 2.0.8

# Configurações do Django

Um arquivo de definições do Django contém todas as configurações da sua instalação do Django. Este documento explica como as configurações trabalham e quais definições estão disponíveis.

## O básico

Um arquivo de definições é somente um módulo Python com variáveis de módulo.

Aqui alguns exemplos de definições:

    ALLOWED_HOSTS = ['www.example.com']
    DEBUG = False
    DEFAULT_FROM_EMAIL = 'webmaster@example.com'

Nota

Se você definie o `DEBUG` para `False`, você também precisa definir a definição de `ALLOWED_HOSTS`.

Como o arquivo de definições é um módulo Python, o seguinte se aplica:

- Ele não permite erros de sintaxe Python.

- É possível assinalar definições dinamicamente usando sintaxe Python normalmente. Por exemplo:

      MY_SETTING = [str(i) for i in range(30)]

- Pode importar valores de outros arquivos de definições.

## Designando as definições

`DJANGO_SETTINGS_MODULE`

Quando você usa o Django, você deve dizer quais definições você está usando. Faça isso através da variável de ambiente chamada `DJANGO_SETTINGS_MODULE`.

O valor do `Django_SETTINGS_MODULE``deve estar na sintaxe do Python path, por exemplo ``mysite.settings`. Note que o módulo de definições deve estar no import search path do Python.

### A ferramenta `django-admin`

Quando usar django-admin, você pode definir a variável de ambiente uam vez, ou passar explicitamente no módulo de definições cada vez que você rodar a ferramenta.

Exmplo (Bash shell do Unix):

    export DJANGO_SETTINGS_MODULE=mysite.settings
    django-admin runserver

Exemplo (shell do Windows):

    set DJANGO_SETTINGS_MODULE=mysite.settings
    django-admin runserver

Use o argumento``–settings`` na linha de comando para especificar manualmente o módulo de definições:

    django-admin runserver --settings=mysite.settings

### No servidor (`mod_wsgi`)

No seu ambiente do servidor de produção , você precisará dizer à sua aplicação WSGI qual arquivo de definições utilizar. Faça isso com `os.environ`:

    import os

    os.environ['DJANGO_SETTINGS_MODULE'] = 'mysite.settings'

Leia a documentação do Django mod_wsgi para mais informações e outros elementos comuns para uma aplicação WSGI Django.

## Definições padrão

Um arquivo de definições do Django não tem que definir qualquer configuração se não for necessária. Cada definição tem um valor padrão. Estes valores padrão estão no módulo `django/conf/global_settings.py`.

Aqui está o algoritmo que o Django usa enquanto compila as definições:

- Carrega as definições do `global_settings.py`.
- Carrega as definições do arquivo de definições especificado, sobrescrevendo as definições globais quando necessário.

Note que o arquivo de definições não deve importar o `global_settings`, porque isso é redundante.

### Vendo quais definições você alterou

Existe uma maneira fácil para verificar quais das suas definições diferem das definições padrão. O comando `python anage.py diffsettings` mostra as diferenças entre o arquivo de definições atuais e as definições padrão do Django.

Para mais detalhes, veja a documentação `diffsettings`.

## Usando as definições em código Python

Nas suas apps Django, use as definições através da importação do objeto `django.conf.settings`. Exemplo:

    from django.conf import settings

    if settings.DEBUG:
        # Do something

Note que o `django.conf.settings` não é um módulo – é um objeto. Então não é possível importar definições individuais.

    from django.conf.settings import DEBUG  # This won't work.

Também note que seu código não deve importar nem o `global_settings` nem seu próprio arquivo de definições. O `django.conf.settings` torna o conceito das definições padrão abstrato bem como as definições específicas do site; ele apresenta uma única interface. Ele também desacopla o código que usa as definições da localização das suas definições.

## Alterando as definições em tempo de execução

Você não deve alterar as definições dentro de sua aplicação durante a execução. Por exemplo, não faça isso em uma “view”:

    from django.conf import settings

    settings.DEBUG = True   # Don't do this!

O único local onde você deve assinalar a definições é em um arquivo de definições.

## Segurança

Como o arquivo de definições contém informações sensíveis, tal como a senha do banco de dados, você deve fazer todas as tentativas de limitar acesso a ele. Por exemplo, alterar a permissão deste arquivo para que somente você e o usuário do servidor web possam lê-lo. Isso é especialmente importante em um ambiente de hospedagem compartilhado.

## Configurações disponíveis.

Para uma lista completa de configurações disponíveis, veja a referência de configurações.

## Criando suas próprias configurações

Não há nada que o impeça de criar suas próprias configurações, para sua própria aplicação Django. Apenas siga estas orientações:

- Nomes de definições devem estar em maiúsculo.
- Não reinvente uma configuração já existente.

Para definições que são sequências, mesmo o Django usa listas, mas isso é apenas uma convenção.

## Usando as configurações sem definir `DJANGO_SETTINGS_MODULE`

Em alguns casos, você talvez queira ignorar a variável de ambiente `DJANGO_SETTINGS_MODULE`. Por exemplo, se você está usando somente o sistema de templates, você talvez gostaria de não definir uma variável de ambiente apontando para o módulo de definições.

Nestes casos, você pode configurar manualmente as definições. Faça isso através da chamada:

`django.conf.settings.``configure`(default_settings, **settings)

Exemplo

    from django.conf import settings

    settings.configure(DEBUG=True)

Passe ao `configure()` quantos argumentos nomeados você quiser, com cada argumento representando uma configuração e seu valor. Cada nome de argumento deve ser todo em maiúsculo, com o mesmo nome da configuração descrita acima. Se uma definição em particular não for passada para o `configure()` e e for necessária em algum ponto a diante, o Django irá usar o valor padrão para aquela configuração.

Configurando o Django desta maneira é sobretudo necessário – e, realmente, recomendado quando você está usando uma parte do framework dentro de uma aplicação maior.

Consequentemente, quando configurado através do `settings.configure()`, o Django não irá fazer qualquer modificação nas variáveis de ambiente do processo (veja a documentação do `TIME_ZONE` para o porque disso não ocorrer normalmente). Ele assume que você já está com todo o controle do seu ambiente nestes casos.

### Definições padrão personalizadas

Se você quer que os valores padrão venham de algum outro lugar que não o `django.conf.global_settings`, você pode passar em um módulo ou classe que forneça as definições padrão como o argumento `default_settings` (ou como o primeiro argumento opcional) na chamada do `configure()`.

Neste exemplo, definições padrão são pegas do `myapp_defaults`, e a definição de `DEBUG` é definida como `True`, apesar de 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 seguinte, o qual usa `myapp_defaults` como um argumento posicional, é equivalente:

    settings.configure(myapp_defaults, DEBUG=True)

Normalmente , você não precisa sobrescrever os padrões desta maneira. Os padrões do Django são suficientemente administráveis de modo que você pode usá-los tranquilamente. Esteja ciente que se você passar um novo módulo padrão, este irá substituir totalmente os padrões do Django, de modo que você precisa especificar um valor para cada definição existente que talvez seja usado no código que estiver importando. Verifique em `django.conf.settings.global_settings` a lista completa.

### É requerido o `configure()` ou o `DJANGO_SETTINGS_MODULE`.

Se você não definir a variável de ambiente `DJANGO_SETTINGS_MODULE`, você deve chamar a `configure()` em algum ponto usando qualquer código que leia as definições.

Se você não definir o `DJANGO_SETTINGS_MODULE` e não chamar a `configure()`, o Django irá emitir uma excessão `ImportError` na primeira vez que uma das definições for acessada.

Se for definido o `DJANGO_SETTINGS_MODULE`, acessar as definições de alguma maneira, e então chamar a `configure()`, o Django irá emitir um `RuntimeError` indicando que as definições já foram configuradas. Existe uma propriedade somente para este propósito:

Por exemplo:

    from django.conf import settings
    if not settings.configured:
        settings.configure(myapp_defaults, DEBUG=True)

E mais, é um erro chamar o `configure()` mais de uma vez, ou chamar o `configure()` depois que qualquer definição tenha sido acessada.

Isso nos traz: use exatamente um das opções, ou o `configure()` ou o `DJANGO_SETTINGS_MODULE`. Não ambos, e não nenhuma delas.

### É mandatório chamar o `django.setup()` para o usar o Django de modo “standalone”

Se você está usando componentes do Django de modo “standalone” – por exemplo, escreveu um script Python o qual carrega alguns templates Django e os renderiza, ou usa o ORM para ler alguns dados – existe mais um passo que é necessário além de configurar as definições.

Depois de definir ou o `DJANGO_SETTINGS_MODULE` ou chamado `configure()`, precisará chamar `django.setup()` para carregar suas definições e popular o registro da aplicação Django. Por exemplo:

    import django
    from django.conf import settings
    from myapp import myapp_defaults

    settings.configure(default_settings=myapp_defaults, DEBUG=True)
    django.setup()

    # Now this script or any imported module can use any part of Django it needs.
    from myapp import models

Repare que só é necessário chamar `django.setup()` se o seu código é realmente “standalone”. Quando chamado pelo seu servidor web, ou através do django-admin, o Django irá fazer isso por você.

`django.setup()` deve ser chamado uma única vez.

Portanto, evite colocar lógica de aplicação reutilizável em scripts “standalone” de modo que tenha que importar o script em algum lugar da aplicação. Se você não puder evitar isso, coloque a chamada do `django.setup()` dentro de um bloco `if`:

    if __name__ == '__main__':
        import django
        django.setup()

Ver também

A referência sobre configurações
  Contém uma lista completa das configurações do “core” e das aplicações do “contrib”.