# documentação Django 4.0.8.dev20220803071047

# Despachante de URL

A clean, elegant URL scheme is an important detail in a high-quality web application. Django lets you design URLs however you want, with no framework limitations.

Veja o Cool URIs don’t change, por Tim Berners-Lee criador da World Wide Web, para argumentos excelentes sobre porque URLs devem ser limpas e usáveis.

## Visão Geral

To design URLs for an app, you create a Python module informally called a URLconf (URL configuration). This module is pure Python code and is a mapping between URL path expressions to Python functions (your views).

Este mapemaneto pode ser tão curto ou tão longo quanto necessário. Pode referenciar outros mapeamentos. E, porque é código Python puro, pode ser construído dinamicamente.

O Django também fornece uma maneira de traduzir URLs de acordo com a língua ativa. Veja o documentação de internacionaliação para mais finromação.

## Como o Django processa uma requisição

Quando um usuário requisita uma página do seu site feito em Django, este é o algoritmo que o sistema segue para determinar qual código Python executar:

1. O Django determina o módulo URLConf raiz a ser usado. Ordinariamente, este é o valor da definição do `ROOT_URLCONF`, mas se o objeto `HttpRequest` que está chegando tem um atributo `urlconf` (definido pelo “middleware”), o valor definido por ele será usado no lugar da definição do `ROOT_URLCONF`.
2. Django loads that Python module and looks for the variable `urlpatterns`. This should be a sequence of `django.urls.path()` and/or `django.urls.re_path()` instances.
3. Django runs through each URL pattern, in order, and stops at the first one that matches the requested URL, matching against `path_info`.
4. Once one of the URL patterns matches, Django imports and calls the given view, which is a Python function (or a class-based view). The view gets passed the following arguments:
   - Uma instância do `HttpRequest`.
   - If the matched URL pattern contained no named groups, then the matches from the regular expression are provided as positional arguments.
   - The keyword arguments are made up of any named parts matched by the path expression that are provided, overridden by any arguments specified in the optional `kwargs` argument to `django.urls.path()` or `django.urls.re_path()`.
5. If no URL pattern matches, or if an exception is raised during any point in this process, Django invokes an appropriate error-handling view. See Error handling below.

## Exemplo

Aqui um exemplo de URLconf:

    from django.urls import path

    from . import views

    urlpatterns = [
        path('articles/2003/', views.special_case_2003),
        path('articles/<int:year>/', views.year_archive),
        path('articles/<int:year>/<int:month>/', views.month_archive),
        path('articles/<int:year>/<int:month>/<slug:slug>/', views.article_detail),
    ]

Notas:

- To capture a value from the URL, use angle brackets.
- Captured values can optionally include a converter type. For example, use `<int:name>` to capture an integer parameter. If a converter isn’t included, any string, excluding a `/` character, is matched.
- There’s no need to add a leading slash, because every URL has that. For example, it’s `articles`, not `/articles`.

Requisições de exemplo:

- A request to `/articles/2005/03/` would match the third entry in the list. Django would call the function `views.month_archive(request, year=2005, month=3)`.
- `/articles/2003/` deve combinar com o primeiro padrão de formatp na lista, não o segundo, porque os padrões são testado em ordem, e o primeiro é o que primeiro atende ao padrão. Sinta-se livre para explorar a ordem e inserir casos especiais como este. Aqui, o Django deve chamar a função `views.special_case_2003(request)`
- `/articles/2003` não deve combinar com nenhum destes padrões, porque cada padrão de formato requer que a URL termine com uma barra.
- `/articles/2003/03/building-a-django-site/` would match the final pattern. Django would call the function `views.article_detail(request, year=2003, month=3, slug="building-a-django-site")`.

## Path converters

The following path converters are available by default:

- `str` - Matches any non-empty string, excluding the path separator, `'/'`. This is the default if a converter isn’t included in the expression.
- `int` - Matches zero or any positive integer. Returns an `int`.
- `slug` - Matches any slug string consisting of ASCII letters or numbers, plus the hyphen and underscore characters. For example, `building-your-1st-django-site`.
- `uuid` - Matches a formatted UUID. To prevent multiple URLs from mapping to the same page, dashes must be included and letters must be lowercase. For example, `075194d3-6885-417e-a8a8-6c931e272f00`. Returns a `UUID` instance.
- `path` - Matches any non-empty string, including the path separator, `'/'`. This allows you to match against a complete URL path rather than a segment of a URL path as with `str`.

## Registering custom path converters

For more complex matching requirements, you can define your own path converters.

A converter is a class that includes the following:

- A `regex` class attribute, as a string.
- A `to_python(self, value)` method, which handles converting the matched string into the type that should be passed to the view function. It should raise `ValueError` if it can’t convert the given value. A `ValueError` is interpreted as no match and as a consequence a 404 response is sent to the user unless another URL pattern matches.
- A `to_url(self, value)` method, which handles converting the Python type into a string to be used in the URL. It should raise `ValueError` if it can’t convert the given value. A `ValueError` is interpreted as no match and as a consequence `reverse()` will raise `NoReverseMatch` unless another URL pattern matches.

Por exemplo:

    class FourDigitYearConverter:
        regex = '[0-9]{4}'

        def to_python(self, value):
            return int(value)

        def to_url(self, value):
            return '%04d' % value

Register custom converter classes in your URLconf using `register_converter()`:

    from django.urls import path, register_converter

    from . import converters, views

    register_converter(converters.FourDigitYearConverter, 'yyyy')

    urlpatterns = [
        path('articles/2003/', views.special_case_2003),
        path('articles/<yyyy:year>/', views.year_archive),
        ...
    ]

## Using regular expressions

If the paths and converters syntax isn’t sufficient for defining your URL patterns, you can also use regular expressions. To do so, use `re_path()` instead of `path()`.

In Python regular expressions, the syntax for named regular expression groups is `(?P<name>pattern)`, where `name` is the name of the group and `pattern` is some pattern to match.

Here’s the example URLconf from earlier, rewritten using regular expressions:

    from django.urls import path, re_path

    from . import views

    urlpatterns = [
        path('articles/2003/', views.special_case_2003),
        re_path(r'^articles/(?P<year>[0-9]{4})/$', views.year_archive),
        re_path(r'^articles/(?P<year>[0-9]{4})/(?P<month>[0-9]{2})/$', views.month_archive),
        re_path(r'^articles/(?P<year>[0-9]{4})/(?P<month>[0-9]{2})/(?P<slug>[\w-]+)/$', views.article_detail),
    ]

This accomplishes roughly the same thing as the previous example, except:

- The exact URLs that will match are slightly more constrained. For example, the year 10000 will no longer match since the year integers are constrained to be exactly four digits long.
- Each captured argument is sent to the view as a string, regardless of what sort of match the regular expression makes.

When switching from using `path()` to `re_path()` or vice versa, it’s particularly important to be aware that the type of the view arguments may change, and so you may need to adapt your views.

### Using unnamed regular expression groups

As well as the named group syntax, e.g. `(?P<year>[0-9]{4})`, you can also use the shorter unnamed group, e.g. `([0-9]{4})`.

This usage isn’t particularly recommended as it makes it easier to accidentally introduce errors between the intended meaning of a match and the arguments of the view.

In either case, using only one style within a given regex is recommended. When both styles are mixed, any unnamed groups are ignored and only named groups are passed to the view function.

### Argumentos aninhados

Expressões regulares permitem argumentos aninhados, e o Django irá resolvê-los e passá-los para a “view”. Quando usar o “reverse”, o Django tentará preencher todos os argumentos capturados fora, ignorando qualquer argumento aninhado capturado. Considere o seguinte padrão de URL o qual opcionalmente pega um arumento “page”:

    from django.urls import re_path

    urlpatterns = [
        re_path(r'^blog/(page-(\d+)/)?$', blog_articles),                  # bad
        re_path(r'^comments/(?:page-(?P<page_number>\d+)/)?$', comments),  # good
    ]

Ambos os padrões usam argumento aninhados e irão resolver: por exemplo, `blog/page-2/` irá resultar em na combinação com `blog_articles` com dois argumentos posicionais: `page-2/` e `2`. O segundo padrão para `comments` irá encontrar `comments/page-2/` com argumento nomeado `page_number` definido como 2. O argumento mais externo neste caso é um argumento não capturado `(?:...)`.

A “view” `blog_articles` precisa do argumento mais externo para que seja possível acessá-la de maneira reversa, neste caso `page-2/` ou nenhum argumento , enquanto ue `comments` pode ser acessado reversamente com argumento nenhum ou com um valor para `page_number`.

Argumentos aninhados criam um acomplamento forte entre os argumentos da “view” e sua URL como ilustrado pelo `blog_articles`: a “view” recebe parte da URL (``page-2/”) ao invés de somente o valor que a “view” está interessada. Este acoplamento é ainda mais evidente quando acessando reversamente, já que para acessá-la reversamente precisa passar uma parte da URL ao invés de somente o número da página.

Como regra geral, apenas capturar os valores que a “view” precisa para funcionar e usar argumentos não capturáveis quando a expressão regurlar precisar de um argumento mas que a “view” o ignora.

## Onde e o que o URLconf procura

O URLconf procura na URL requisitada, como uma string Python normal. Isso não inclui parâmetros GET ou POST, ou o nome do domínio.

Por exemplo em uma requisição para `https://www.example.com/myapp/`, o URLconf irá olhar para `myapp/`.

Em uma requisição para `https://www.example.com/myapp/?page=3`, o URLconf irá olhar para `myapp/`.

O URLconf nÃo olha para o método da requisição. Em outras palavras, todas os métodos de requisições – `POST`, `GET`, `HEAD`, etc. – serão roteados para a mesma função para a mesma URL.

## Especificando agumentos padrão para “view”

Uma truque conveniente é especificar parâmetros padrão para seus argumentos de “views”. Aqui um exemplo de URLconf e “view”:

    # URLconf
    from django.urls import path

    from . import views

    urlpatterns = [
        path('blog/', views.page),
        path('blog/page<int:num>/', views.page),
    ]

    # View (in blog/views.py)
    def page(request, num=1):
        # Output the appropriate page of blog entries, according to num.
        ...

In the above example, both URL patterns point to the same view – `views.page` – but the first pattern doesn’t capture anything from the URL. If the first pattern matches, the `page()` function will use its default argument for `num`, `1`. If the second pattern matches, `page()` will use whatever `num` value was captured.

## Performance

Cada empressão regular dentro do `urlpatterns` é compilada na primeira vez que é acessad. Isso torna o sistema tremendamente rápido.

## Sintaxe da variável `urlpatterns`

`urlpatterns` should be a sequence of `path()` and/or `re_path()` instances.

## Manipulação de erros

When Django can’t find a match for the requested URL, or when an exception is raised, Django invokes an error-handling view.

As “views” para usar nestes casos são especificadas por quatro variáveis. O valor padrão destas variáveis deve bastar para a maioria dos projetos, mas uma maior persoanlização é possível sobrescrevendo seus valores padrão.

Veja a documentação em Personalizando “views” de erros para detalhes completos.

Tais valores podem ser definidos dentro do sey URLconf raiz. Definir estes valores em qualquer outro URLconf não irá ter nenhum efeito.

Os valores devm ser “executáveis”, ou strings que representam o caminho Python completo para a “view” que deve ser chamada para lidar com o condição de erro.

As variáveis são:

- `handler400` – Veja `django.conf.urls.handler400`.
- `handler403` – Veja `django.conf.urls.handler403`.
- `handler404` – Veja `django.conf.urls.handler404`.
- `handler500` – Veja `django.conf.urls.handler500`.

## Incluindo outros URLconfs

Em qualquer ponto, seus ``urlpatterns``podem “inluir” outros módulos URLconf. Isso essencialmente enraiza um conjunto de URLs embaixo de outros.

Por exemplo, aqui um enxerto de URLconf para o próprio Django website. Isso inclui várias outras URLconfs:

    from django.urls import include, path

    urlpatterns = [
        # ... snip ...
        path('community/', include('aggregator.urls')),
        path('contact/', include('contact.urls')),
        # ... snip ...
    ]

Whenever Django encounters `include()`, it chops off whatever part of the URL matched up to that point and sends the remaining string to the included URLconf for further processing.

Another possibility is to include additional URL patterns by using a list of `path()` instances. For example, consider this URLconf:

    from django.urls import include, path

    from apps.main import views as main_views
    from credit import views as credit_views

    extra_patterns = [
        path('reports/', credit_views.report),
        path('reports/<int:id>/', credit_views.report),
        path('charge/', credit_views.charge),
    ]

    urlpatterns = [
        path('', main_views.homepage),
        path('help/', include('apps.help.urls')),
        path('credit/', include(extra_patterns)),
    ]

Neste exemplo, a URL `/credit/reports/` será manipulada pela view Django `credit_views.report()`.

Isso pode ser usado para remover redundâncias de URLconf onde um único prefixo de padrão é usado repetidamente. Por exemplo, considere o URLconf:

    from django.urls import path
    from . import views

    urlpatterns = [
        path('<page_slug>-<page_id>/history/', views.history),
        path('<page_slug>-<page_id>/edit/', views.edit),
        path('<page_slug>-<page_id>/discuss/', views.discuss),
        path('<page_slug>-<page_id>/permissions/', views.permissions),
    ]

Podemos melhorar isso começando o caminho comum com um prefixo e agrupando os sufixos que diferem:

    from django.urls import include, path
    from . import views

    urlpatterns = [
        path('<page_slug>-<page_id>/', include([
            path('history/', views.history),
            path('edit/', views.edit),
            path('discuss/', views.discuss),
            path('permissions/', views.permissions),
        ])),
    ]

### Parâmetros capturados

Um URLconf que foi inluído recebe qualquer parâmetro capturado vindos dos URLconfs pais, logo o seguinte exemplo é válido:

    # In settings/urls/main.py
    from django.urls import include, path

    urlpatterns = [
        path('<username>/blog/', include('foo.urls.blog')),
    ]

    # In foo/urls/blog.py
    from django.urls import path
    from . import views

    urlpatterns = [
        path('', views.blog.index),
        path('archive/', views.blog.archive),
    ]

No exemplo acima, a variável `"username"` é capturada e passada para o URLconf incluído, como esperado.

## Passando opções extras para função “view”

URLconfs tem um gancho que deixa você passar argumentos extra par suas funções “view”, como um dicionário Python.

The `path()` function can take an optional third argument which should be a dictionary of extra keyword arguments to pass to the view function.

Por exemplo:

    from django.urls import path
    from . import views

    urlpatterns = [
        path('blog/<int:year>/', views.year_archive, {'foo': 'bar'}),
    ]

In this example, for a request to `/blog/2005/`, Django will call `views.year_archive(request, year=2005, foo='bar')`.

Esta técnica é usada no syndication framework para passar metadados e opções para as “views”.

Lidando com conflitos

É possível ter um padrão de formato de URL o qual captura argumentos nominados, e também passa argumentos com os mesmos nomes neste dicionário de argumentos extras. Quando isso acontece, o argumento no dicionário serão usados no lugar dos argumentos capturados na URL.

### Passando opções extra para o `include()`

Similarly, you can pass extra options to `include()` and each line in the included URLconf will be passed the extra options.

Por exemplo, estas duas definições de URLconf são funcionamente idênticas:

Definição um:

    # main.py
    from django.urls import include, path

    urlpatterns = [
        path('blog/', include('inner'), {'blog_id': 3}),
    ]

    # inner.py
    from django.urls import path
    from mysite import views

    urlpatterns = [
        path('archive/', views.archive),
        path('about/', views.about),
    ]

Definição dois:

    # main.py
    from django.urls import include, path
    from mysite import views

    urlpatterns = [
        path('blog/', include('inner')),
    ]

    # inner.py
    from django.urls import path

    urlpatterns = [
        path('archive/', views.archive, {'blog_id': 3}),
        path('about/', views.about, {'blog_id': 3}),
    ]

Note que as opções extra serão sempre passadas para cada linha do URLconf incluído, independente se a “view” aceita estas opções como válidas. Por esta razão, essa técnica é somente útil se você estiver certo que cada “view” no URLconf incluído aceita as opções extras que estão sendo passadas.

## A resolução reversa de URLs

Uma necessidade comum quando trabalhando com um projeto Django é a possibilidade de obter URLs na sua forma final, seja para adicioná-lo em um conteúdo gerado (“views” e ativos de URLs, URLs a serem mostradas para o usuário, etc.) ou para lidar com o fluxo de navegação no lado do servidor (redirecionamentos, etc).

É altamente desejável evitar escrever URLs diretamente no código (uma estratégia trabalhosa, não-escalável e propensa a erros). Igualmente perigoso é conceber mecânismos pontuais para gerar URLs que sejam paralelos as especificações descritas no URLconf, o que pode resultar na produção de URLs que se tornem desatualizadas ao passar do tempo.

Em outras palavras, o que é preciso é um mecênismo enxuto (“DRY”). Entre outras vantagens isso permitiria a evolução da definição de URL sem ter que passar por todo o código do projeto para procurar e substituir URLs desatualizadas.

O primeiro pedaço de infomação que temos disponível para chegar a uma URL é uma identificação (ex.: o nome) da “view” responsável por lidar com ela. Outras partes de informação que necessariamente deve participar da busca pela URL correta são os tipos (posicional, nomeado) e valores dos argumentos da “view”.

O Django fornece uma solução tal que o mapeador de URL é o único reposritório de definição de URL. Você o alimenta com seu URLconf e então este pode ser usado em ambas as direções:

- Começando com uma URL requisitada pelo usuário/navegador Web, ele chama a “view” Django correta fornecendo quaisquer argumentos que esta necessite e com os valores extraídos da URL.
- Começando com a identificação da “view” Django correspondente mais os valores dos argumentos que poderiam ser passados a ela, obten-se a URL associada.

O primeiro caso é o uso que estivemos discutindo na seção anterior. O segundo é o que é conhecido como resolução reversa de URLs, combinação reversa de URL, filtro reverso de URL, ou simplesmente URL reversa.

O Django fornece ferramentas para realizar a reversão de URL que vá de encontro com as diferentes camadas onde URLs são necessárias:

- Em “templates”: usando a tag de template `url`.
- In Python code: Using the `reverse()` function.
- EM código de nível mais alto relacionado à manipulação de URLs de instâncias de modelos Django: o método `get_absolute_url()`.

### Exemplos

Considere novamente essa entrada do URLconf:

    from django.urls import path

    from . import views

    urlpatterns = [
        #...
        path('articles/<int:year>/', views.year_archive, name='news-year-archive'),
        #...
    ]

According to this design, the URL for the archive corresponding to year nnnn is `/articles/<nnnn>/`.

Você pode obtê-la no código de template usando:

    <a href="{% url 'news-year-archive' 2012 %}">2012 Archive</a>
    {# Or with the year in a template context variable: #}
    <ul>
    {% for yearvar in year_list %}
    <li><a href="{% url 'news-year-archive' yearvar %}">{{ yearvar }} Archive</a></li>
    {% endfor %}
    </ul>

Ou em código Python:

    from django.http import HttpResponseRedirect
    from django.urls import reverse

    def redirect_to_year(request):
        # ...
        year = 2006
        # ...
        return HttpResponseRedirect(reverse('news-year-archive', args=(year,)))

Se, por algum motivo, foi decidido que a URL onde conteúdo de arquivos de artigos anuais são publicados deve ser alterados, então é deve-se alterar somente a entrada no URLconf.

Em alguns cenários onde “views” são de natureza genérica, talvez exista um relacionamento muitos-para-um entre URLs e “views”. Para estes casos o nome da “view” não é um identificador bom o suficiente para identificá-los quando chega a hora de usar a URL reversa. Leia a próxima seção para conhecer a solução que o Django fornece pra isso.

## Nomeando padrões de formato de URL

De modo a realizar uma URL reversa, é necessário usar **padrões de URL nominadas* como feito no exemplo acima. A string usada para o nome da URL pode conter qualquer caracter que queira. Você não está restrito a nomes válidos em Python.

When naming URL patterns, choose names that are unlikely to clash with other applications’ choice of names. If you call your URL pattern `comment` and another application does the same thing, the URL that `reverse()` finds depends on whichever pattern is last in your project’s `urlpatterns` list.

Putting a prefix on your URL names, perhaps derived from the application name (such as `myapp-comment` instead of `comment`), decreases the chance of collision.

You can deliberately choose the same URL name as another application if you want to override a view. For example, a common use case is to override the `LoginView`. Parts of Django and most third-party apps assume that this view has a URL pattern with the name `login`. If you have a custom login view and give its URL the name `login`, `reverse()` will find your custom view as long as it’s in `urlpatterns` after `django.contrib.auth.urls` is included (if that’s included at all).

You may also use the same name for multiple URL patterns if they differ in their arguments. In addition to the URL name, `reverse()` matches the number of arguments and the names of the keyword arguments. Path converters can also raise `ValueError` to indicate no match, see Registering custom path converters for details.

## Domínio de nomes de URL

### Introdução

Nomes de domínios de URL possibilitam a você exclusividade ao reverter os padrões de formato de URL nominados, mesmo que uma aplicação diferente use os mesmos nomes para URL. É uma boa prática para aplicações de terceiros sempre usar URLs dentro de um nome de domínio (como fizemos no tutorial). De mpodo similar, isso também permite a você usar o mode reverso de URLs se múltiplas intâncias de uma aplicação for implantada. Em outras palavras, se múltiplas instâncias de uma única aplicação irá compartilhar URLs nominada, os nomes de domínios fornecem uma maneira de manter essas URLs nominadas separadas.

Django applications that make proper use of URL namespacing can be deployed more than once for a particular site. For example `django.contrib.admin` has an `AdminSite` class which allows you to deploy more than one instance of the admin. In a later example, we’ll discuss the idea of deploying the polls application from the tutorial in two different locations so we can serve the same functionality to two different audiences (authors and publishers).

Um nome de domínio de URL é formado por duas partes, sendo ambas do tipo strings:

Nome de domínio da aplicação
  Este descreve o nome da aplicação que está sendo implantada. Cada instância de uma única aplicação terá o mesmo nome de domínio de apliacação. Por exemlo, a aplicação de administração do Django tem previsivelmente seu nome de domínio de aplicação como sendo `'admin'`.
Nome de domínio de instância
  Isso identifica uma instância específica de uma aplicação. Nomes de domínio de instância devem ser únicos dentro de todo o seu projeto. Contudo, um nome de domínio de uma intância pode ser o mesmo que o nome de domínio da sua aplicação. Isso é usado para especificar uma instância padrão da aplicação. Por exemplo, a instância padrão do administrador do Django tem `'admin'` como seu nome de domínio de instância.

Nome de domínios de URLs são especificados usando o operador `':'`. Por exemplo, a página principal da aplicação “admin” é referenciada usando `'admin:index'`. Isso indica um nome de domínio do `'admin'`, e uma URL moninada de `'índice'`.

Nomes de domínio podem ser aninhados. A URL nominada `'sports:polls:index'` poderia procurar por um padrão de formato chamado `'index'` no nome de domínio `'polls'` que é ele próprio definido dentro do nome de domínio de nível superior `'sports'`.

### Revertendo URLs com nomes de domínios

Quando dada uma URL com nome de domínio (ex.: `'polls:index'`) para resolver, o Django divide em partes o nome totalmente qualificado e então trás o seguinte filtro:

1. Primeiro, o Django procura por uma application namespace que combine (neste exemplo, `'polls'`). Isso irá produzir uma lista de instâncias daquela aplicação.

2. If there is a current application defined, Django finds and returns the URL resolver for that instance. The current application can be specified with the `current_app` argument to the `reverse()` function.

   A tag de template `url` usa o nome de domínio da view corrente resolvida como a aplicação corrente em uma `RequestContext`. Você pode sobrescrever seu padrão definindo a aplicação corrente no atributo `request.current_app`.

3. If there is no current application, Django looks for a default application instance. The default application instance is the instance that has an instance namespace matching the application namespace (in this example, an instance of `polls` called `'polls'`).

4. Se não uma instância padrão de aplicação, o Django irá usar a última instância instalada da aplicação, não importando qual seja o nome desta instância.

5. Se o nome de domínio não combina com application namespace no passo 1, o Django irá tentar um filtro direto do nome de domínio como um instance namespace.

Se há nomes de domínios aninhados, estes passos são repetidos para cada parte do nome de domínio até que somente o nome da “view” esteja não resolvido. O nome da “view” será então resolvido em uma URL dentro do nome de domínio no qual foi encontrado.

#### Exemplo

Para mostrar essa estratégia de resolução em ação, considere um exemplo de duas instâncias da aplicação `polls` do tutorial: uma chamada `'authors-polls'` e uma chamada `'publisher-poll'`. Assuma que tenhamos melhorado esta aplicação de modo que ela leve em consideração o nome de domínio da instância quando criar e mostrar as enquetes (‘polls’).

`urls.py`

    from django.urls import include, path

    urlpatterns = [
        path('author-polls/', include('polls.urls', namespace='author-polls')),
        path('publisher-polls/', include('polls.urls', namespace='publisher-polls')),
    ]

`polls/urls.py`

    from django.urls import path

    from . import views

    app_name = 'polls'
    urlpatterns = [
        path('', views.IndexView.as_view(), name='index'),
        path('<int:pk>/', views.DetailView.as_view(), name='detail'),
        ...
    ]

Usando esta definição, os seguintes filtros são possíveis:

- Se uma das intâncias é a corrente - digamos, se estivermos renderizando a página de detalhes da instância `'author-polls'` - `'polls:index'` será resolvido para a página de índice da instância `'author-polls'`; isto é, ambos os seguintes irão resultar em `"/author-polls/"`.

  No método de uma “view” baseada em classe:

      reverse('polls:index', current_app=self.request.resolver_match.namespace)

  e no “template”:

      {% url 'polls:index' %}

- Se não houver uma instância corrente - digamos, se estivermos renderizando uma págna el algum outro lugar do site - `'polls:index'` será resolvido para a última instância registrada de `polls`. Desde que não haja uma instância padrão (nome de domínio de instância `'polls'`), a última instância de `polls` registrada será usada. Essa deve ser `'publisher-polls'` já que foi declarada por último no `urlpatterns`.

- `'author-polls:index'` sempre irá resolver para a página de índice da instância `'author-polls'` (da mesma forma para `'publisher-polls'`) .

Se havia também uma instância padrão - isto é, uma instância nominada `'polls'` - a única mudança do exemplo acima seria no caso onde não há intância corrente (o segundo item na lista acima). Neste caso `'polls:index'` seria resolvido para a página de índice da intância padrão ao invés da instância declarada por último no `urlpatterns`.

### Domínios de nomes de URL e URLconfs incluídos

o Domínio dos nomes de aplicação de URLconfs cinludídos podem ser especificados de dois modos.

Firstly, you can set an `app_name` attribute in the included URLconf module, at the same level as the `urlpatterns` attribute. You have to pass the actual module, or a string reference to the module, to `include()`, not the list of `urlpatterns` itself.

`polls/urls.py`

    from django.urls import path

    from . import views

    app_name = 'polls'
    urlpatterns = [
        path('', views.IndexView.as_view(), name='index'),
        path('<int:pk>/', views.DetailView.as_view(), name='detail'),
        ...
    ]

`urls.py`

    from django.urls import include, path

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

As URLs definidas em `polls.urls` terão um nome de domínio como `polls`.

Secondly, you can include an object that contains embedded namespace data. If you `include()` a list of `path()` or `re_path()` instances, the URLs contained in that object will be added to the global namespace. However, you can also `include()` a 2-tuple containing:

    (<list of path()/re_path() instances>, <application namespace>)

Por exemplo:

    from django.urls import include, path

    from . import views

    polls_patterns = ([
        path('', views.IndexView.as_view(), name='index'),
        path('<int:pk>/', views.DetailView.as_view(), name='detail'),
    ], 'polls')

    urlpatterns = [
        path('polls/', include(polls_patterns)),
    ]

Isso irá incluir o nome do padrão de formato de URL nomeado dentro do nome de domínio da dada aplicação.

The instance namespace can be specified using the `namespace` argument to `include()`. If the instance namespace is not specified, it will default to the included URLconf’s application namespace. This means it will also be the default instance for that namespace.