- 5.1 Introduction
- 5.2 The Purpose of Views and URL Configurations
- 5.3 Step-by-Step Examination of Django's Use of Views and URL Configurations
- 5.4 Building Tag Detail Webpage
- 5.5 Generating 404 Errors for Invalid Queries
- 5.6 Shortening the Development Process with Django View Shortcuts
- 5.7 URL Configuration Internals: Adhering to App Encapsulation
- 5.8 Implementing the Views and URL Configurations to the Rest of the Site
- 5.9 Class-Based Views
- 5.10 Redirecting the Homepage
- 5.11 Putting It All Together
This chapter is from the book
This chapter is from the book
This chapter is from the book
5.7 URL Configuration Internals: Adhering to App Encapsulation
We currently have two function views, now masterfully shortened, and two URL patterns, creating two webpages. However, our URL configuration is in direct violation of app encapsulation in Django. The URL patterns that direct users to the two webpages generated by the organizer app exist in a file that is for the project: the URLs are in a file under suorganizer/, as opposed to a file within the organizer/ directory.
The practical goal of this section is to refactor our URL configuration so that our Django website adheres to the app encapsulation standard. However, to do so, we must learn much more about the URL configuration. The instructional goal of this section is to teach you exactly how URL patterns are used and built in Django.
5.7.1 Introspecting URL Patterns
We’ve discovered that a URL configuration is a list of URL patterns, stored by convention in a variable named urlpatterns. What I (and others) casually refer to as a URL pattern is actually a RegexURLPattern object. Each call to url() instantiates a RegexURLPattern; a URL configuration is thus a list of RegexURLPattern objects stored in a variable named urlpatterns.
Each RegexURLPattern is instantiated by a call to url() (see Example 5.32), which takes as mandatory arguments (1) a regular expression pattern and (2) a reference to a view. As an optional argument, it’s possible to pass (3) a Python dictionary, where each key value is passed to the view as keyword arguments. We will see this in action before the end of the chapter and then again in Chapter 19. Finally, url() will accept (4) a named argument name, where we can specify the name of the RegexURLPattern. We’ve named our second URL pattern organizer_tag_detail, but the utility of names won’t be clear until Chapter 6.
Example 5.32: Python Code
url(regular_expression,
view,
optional_dictionary_of_extra_values,
name=a_name)Django uses the ROOT_URLCONF setting in settings.py to find the URL configuration for the project. It does so as soon as the server starts (along with settings). This makes Django fast, as the entire regular expression pattern-matching scheme is stored in memory once, but it also means that if you change the URL configuration or any settings, you must restart the Django server (unless you’re running the development server, which anticipates changes).
Because a URL configuration is a list, the order of URL patterns matters, particularly when the URLs matched by regular expression patterns overlap. In Chapter 6, we will see an example of overlapping URLs and how order comes into play.
While we now understand the basics of URL patterns and configurations, we’re still missing a key concept: how to connect different URL configurations.
5.7.2 Using include to Create a Hierarchy of URL Configurations
The second argument passed to url() need not point at a view: it can point at another URL configuration, thanks to the include() function. This capability allows us to create a separate URL configuration in each Django app and have a URL pattern in the site-wide URL configuration point to each one. In effect, the full URL configuration is not a simple list but is actually a tree, where the leaves of the tree are webpages (see Figure 5.6).
)
Figure 5.6: URL Configuration Tree
When a URL pattern points to a URL configuration, the regular expression pattern acts as a URI prefix. For instance, if the path r'^blog/' points to a URL configuration, then all of the URL patterns in that URL configuration will effectively have that URI prefixed to their own regular expression.
This functionality comes with an important pitfall: regular expression patterns in URL patterns that point to URL configurations must be treated as partial regular expression patterns: we cannot use the $ character to close the pattern, or it will prevent the use of the ensuing patterns. If a URL pattern with the regular expression pattern r'^first/$' points to a URL configuration with the regular expression pattern r'^second/$', Django will effectively (but not actually, as we’ll discuss shortly) combine them for the result of r'^first/$second/$'. Instead of matching /first/second/ as desired, Django will only match /first/. To properly build this URL pattern, the first regular expression must remove the $, reading r'^first/', so that the combination results in r'^first/second/$', as in Example 5.37.
Example 5.37: Python Code
# app/urls.py
urlpatterns = patterns(
url(r'^second/$',
a_view),
)
# project/urls.py
import app.urls as app_url_config
urlpatterns = patterns(
url(r'^first/', # there is no '$' here!
include(app_url_config)),
)Django is not actually combining regular expressions but rather truncating the URL path it receives. For this reason, the ^ can still be used in r'^second/$'. When a user requests /first/second/, Django removes the first /, resulting in a request for first/second/. Django then uses regular expression pattern r'^first/' to match first/second/. This explains why we cannot use the $: r'^first/' will match first/second/, but r'^first/$' will not. Once Django has selected this URL pattern, it uses the regular expression pattern r'^first/' to truncate the path from first/second/ to second/, allowing the regular expression pattern r'^second/$' to match this new path.
Given Django’s behavior, a second pitfall is the omission of slashes in intermediate paths. Django only removes the root slash of any URL path. If we use a regular expression pattern r'^first' (no slash or $) to point a URL pattern to a URL configuration containing a URL pattern with a regular expression pattern r'^second/$', it will match not /first/second/ but instead /firstsecond/, which is probably not desirable.
What’s more, the behavior described above provides us with the reason to always use the ^ regular expression character at the beginning of every regular expression pattern. Without it, we stand to erroneously match URL paths. If we are now using r'^first/' and r'second/$' (no ^), it will validly match /first/whoops/second/, which is probably not what we want either.
We don’t actually apply most of this information until we build our blog URL configuration. For our organizer app, we don’t want to prefix our path with anything yet. (We will in Chapter 11: Bending the Rules: The Contact Us Webpage when we want the path /tag/ and /startup/, not /organizer/tag/ or /organizer/startup/.) The prefix we use now is therefore empty.
Start by creating a new file, /organizer/urls.py. In it, we create a new URL configuration. We import the url() function to create RegexURLPattern objects. We then create a urlpatterns list to allow Django to find our URL configuration. We can then call url() with the same parameters as the ones currently in /suorganizer/urls.py. We end up with a /organizer/urls.py file which reads as in Example 5.38.
Example 5.38: Project Code
organizer/urls.py in 18f1a2d3bc
1 from django.conf.urls import url
2
3 from .views import homepage, tag_detail
4
5 urlpatterns = [
6 url(r'^$', homepage),
7 url(r'^tag/(?P<slug>[\w\-]+)/$',
8 tag_detail,
9 name='organizer_tag_detail'),
10 ]To direct Django to this new URL configuration, we need to point our root URL configuration file to this new file using the include() function, already included in the Python imports. To start, we need to import the URLs from our organizer app. To avoid name-space clashes, we use the as keyword to rename the urls module organizer_urls. We can then simply point include() to this Python reference. We do this by using the ^ regular expression pattern character, shown in Example 5.39.
Example 5.39: Project Code
suorganizer/urls.py in 18f1a2d3bc
16 from django.conf.urls import include, url
17 from django.contrib import admin
18
19 from organizer import urls as organizer_urls
20
21 urlpatterns = [
22 url(r'^admin/', include(admin.site.urls)),
23 url(r'^', include(organizer_urls)),
24 ]If you are still running the development server, it will automatically detect the changes made and reload your URL configuration. If not, restart it by invoking runserver on the command line, as shown in Example 5.40.
Example 5.40: Shell Code
$ ./manage.py runserverWith the development server running, you can now browse to 127.0.0.1:8000 to see our homepage() view and 127.0.0.1:8000/tag/mobile/ to demonstrate our tag_detail() view. Consider that while our URL configuration has changed, the URLs we are able to use have not. We have refactored code, not added new behavior.