Um esquema de URL elegante e limpo, é um detalhes importante em uma aplicação Web de alta quailidade, O Django deixa que você especifique URLs como queira, sem limitações do “framework”.
Não requer .php
ou .cgi
, e certamente nada de nonsense 0,2097,1-1-1928,00
.
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.
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.
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:
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
.urlpatterns
. This should be a Python list of django.urls.path()
and/or django.urls.re_path()
instances.HttpRequest
.kwargs
argument to django.urls.path()
or
django.urls.re_path()
.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:
<int:name>
to capture an integer parameter. If a converter isn’t included,
any string, excluding a /
character, is matched.articles
, not /articles
.Requisições de exemplo:
/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")
.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
just a segment of a URL path as with str
.For more complex matching requirements, you can define your own path converters.
A converter is a class that includes the following:
regex
class attribute, as a string.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.to_url(self, value)
method, which handles converting the Python type
into a string to be used in the URL.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),
...
]
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:
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.
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.
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.
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.
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.
Cada empressão regular dentro do urlpatterns
é compilada na primeira vez que é acessad. Isso torna o sistema tremendamente rápido.
urlpatterns
¶urlpatterns
should be a Python list of path()
and/or
re_path()
instances.
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
.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),
])),
]
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.
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.
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.
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:
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:
url
.reverse()
function.get_absolute_url()
.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.
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.
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.
As aplicações Django que fazem uso correto do “namespacing” da URL podem ser instaladas em produção mais de uma vez para um mesmo site. Por exemplo django.contrib.admin
tem uma classe AdminSite
a qual permite facilmente instalar mais de uma instância do admin. Em um exemplo a seguir, iremos discutir a idéia de instalar a aplicação “polls” do tutorial em dois locais diferentes de modo que podemos servir as mesmas funcionalidades para dois públicos diferentes (autores e editores).
Um nome de domínio de URL é formado por duas partes, sendo ambas do tipo strings:
'admin'
.'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'
.
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:
Primeiro, o Django procura por uma application namespace que combine (neste exemplo, 'polls'
). Isso irá produzir uma lista de instâncias daquela aplicação.
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
.
Se não há aplicação corrente, o Django procura por um instância de aplicação padrão. A instância da aplicação padrão é a instância que tem um instance namespace que combine com o application namespace (neste exemplo, uma instância de polls``chamada ``'polls'
).
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.
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.
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’).
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')),
]
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
.
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.
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'),
...
]
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.
ago 01, 2018