Url regular expressions

Regular expressions provide a powerful approach in all programming languages to determine patterns. However, with power also comes complexity, to the point there are entire books written on the topic of regular expressions^[1].

Although most Django urls will never exceed a fraction of the complexity illustrated in many regular expression books, it's important that you understand some of the underlying behaviors and most common patterns of regular expressions in Django urls.

Precedence rule: Granular urls first, broad urls last

Django urls need to follow a certain order and syntax to work correctly. Broad url regular expressions should be declared last and only after more granular url regular expressions.

This is because Django url regular expression matching doesn't use short-circuiting behavior, like a nested conditional statement (e.g. if/elif/elif/elif/else) were as soon as one condition is met, the remaining options are ignored. In Django urls if there's more than one matching regular expression for an incoming url request, it will be the top-most one's action that gets triggered. Precedence for matching url regular expressions is given from top (i.e. first declared) to bottom (i.e. last declared).

You shouldn't underestimate how easy it can be to introduce two url regular expressions that match the same pattern, particularly if you've never done regular expressions since the syntax can be cryptic. Listing 2-1 illustrates the right way to declare Django urls, with more granular regular expressions toward the top and broad regular expressions toward the bottom.

Listing 2-1. Correct precedence for Django url regular expressions

from django.views.generic import TemplateVieww
urlpatterns = [
    url(r'^about/index/',TemplateView.as_view(template_name='index.html')),
    url(r'^about/',TemplateView.as_view(template_name='about.html')),
]

Based on listing 2-1, lets walk through what happens if Django receives a request for the url /about/index/. Initially Django matches the last regular expression, which says 'match ^about/'. Next, Django continues upward inspecting the regular expressions and reaches 'match ^about/index/' which is an exact match to the request url /about/index/ and therefore triggers this action to send control to the index.html template.

Now let's walk through a request for the url /about/. Initially Django matches the last regular expression which says 'match ^about/'. Next, Django continues upward inspecting the regular expressions for a potential match. Because no match is found -- since 'match ^about/index/' is a more granular regular expression -- Django triggers the first action to send control to the about.html template which was the only regular expression match.

As you can see, listing 2-1 produces what can be said to be expected behavior. But now let's invert the order of the url regular expressions, as shown in listing 2-2, and break down why declaring more granular regular expressions toward the bottom is the wrong way to declare Django url regular expressions.

Listing 2-2. Wrong precedence for Django url regular expressions

from django.views.generic import TemplateVieww
urlpatterns = [
    url(r'^about/',TemplateView.as_view(template_name='about.html')),
    url(r'^about/index/',TemplateView.as_view(template_name='index.html')),
]

The issue in listing 2-2 comes when a request is made for the url /about/index/. Initially Django matches the last regular expression, which says 'match ^about/index/'. However, Django continues inspecting the regular expressions and reaches 'match ^about/' which is a broader match to the request url /about/index/, but nevertheless a match! Therefore Django triggers this action and sends control to the about.html template, instead of what was likely expected to be the index.html template from the first match.

Exact url patterns: Forgoing broad matching

In the past section, I intentionally used regular expressions that allowed broad url matching. In my experience, as a Django project grows you'll eventually face the need to use this type of url regular expressions -- but more on why this is so, shortly.

As it turns out, it's possible to use exact url regular expressions. Exact url regular expressions remove any ambiguity introduced by the order in which Django url regular expression are declared.

Lets rework the url regular expressions from listing 2-2 and make them exact regular expressions so their order doesn't matter. Listing 2-3 illustrates exact regular expressions on basis of those in listing 2-2.

Listing 2-3. Exact regular expressions, where url order doesn't matter.

from django.views.generic import TemplateVieww
urlpatterns = [
    url(r'^about/$',TemplateView.as_view(template_name='about.html')),
    url(r'^about/index/$',TemplateView.as_view(template_name='index.html')),
]

Notice the regular expressions in listing 2-3 end with the $ character. This is the regular expression symbol for end of line, which means the regular expression urls only match an exact pattern.

For example, if Django receives a request for the url /about/index/ it will only match the last regular expression in listing 2-3 which says 'match ^about/index/$'. However, it won't match the higher-up ^/about/$ regular expression because this regular expression says match about/ exactly with nothing else after, since the $ indicates the end of the pattern.

However, as useful as the $ character is to make stricter url regular expressions, it's important you analyze its behavior. If you plan to use url Search Engine Optimization (SEO), A/B testing techniques or simply want to allow multiple urls to run the same action, stricter regular expression with $ eventually require more work.

For example, if you start to use urls like /about/index/, /about/email/,/about/address/ and they all use the same template or view for processing, exact regular expressions just make the amount of urls you declare larger. Similarly, if you use A/B testing or SEO where lengthier variations of the same url are processed in the same way (e.g. /about/landing/a/, /about/landing/b/, /about/the+coffeehouse+in+san+diego/) broad url matching is much simper than declaring exact url patterns.

In the end, whether you opt to use exact url regular expression ending in $, I would still recommend you maintain the practice of keeping finer grained url regular at the top and broader ones at the bottom, as this avoids the unexpected behaviors described in listing 2-2 when more than one regular expression matches a url request.

Common url patterns

Although url regular expressions can have limitless variations -- making it next to impossible to describe each possibility -- I'll provide examples on some of the most common url patterns you're more likely to use. Table 2-1 shows individual regular expression characters for Django urls and table 2-2 shows a series of more concrete examples with url patterns.

Table 2-1. Regular expression syntax for Django urls: Symbol (Meaning)

Table 2-2. Common Django url patterns and their regular expressions, with samples

http://127.0.0.1/

http://127.0.0.1/stores/
http://127.0.0.1/stores/long+string+with+12345

http://127.0.0.1/about/contact/

http://127.0.0.1/about/

http://127.0.0.1/stores/2/
http://127.0.0.1/stores/34/

http://127.0.0.1/stores/downtown/

http://127.0.0.1/drinks/mocha/

http://127.0.0.1/drinks/324/

http://127.0.0.1/drinks/mocha/
http://127.0.0.1/drinks/mochaccino/
http://127.0.0.1/drinks/espresso/

http://127.0.0.1/drinks/soda/

http://127.0.0.1/drinks/mocha/

http://127.0.0.1/drinks/mochaccino/

http://127.0.0.1/drinks/espresso/

http://127.0.0.1/drinks/espressomacchiato/

http://127.0.0.1/stores/sandiego/
http://127.0.0.1/stores/LA/
http://127.0.0.1/stores/1/

http://127.0.0.1/san-diego/

http://127.0.0.1/san-diego/

http://127.0.0.1/CA/

http://127.0.0.1/Ca/

1. http://www.apress.com/la/book/9781590594414    ↑