Django Happy Urls

Comments/feedback is very welcome, use issues or twitter: https://twitter.com/oinopion

Django has nice routing, but it's too low level. Regexps are powerful, but have cryptic syntax. This library strives to make writing DRY urls a breeze.

Consider a standard urls.py:

urlpatterns = patterns('blog.entries.views',
    url(r'^$', 'recent_entries', name='entries_recent_entries'),
    url(r'^new/$', 'new_entry', name='entries_new_entry'),
    url(r'^(?P<entry_slug>[\w-]+)/$', 'show_entry', name='entries_show_entry'),
    url(r'^(?P<entry_slug>[\w-]+)/edit/$', 'edit_entry', name='entries_edit_entry'),
    url(r'^(?P<entry_slug>[\w-]+)/delete/$', 'delete_entry', name='entries_delete_entry'),
    url(r'^(?P<entry_slug>[\w-]+)/comments/$', 'comments_list', name='entries_comments_list'),
    url(r'^(?P<entry_slug>[\w-]+)/comments/(\d+)/$', 'comment_details', name='entries_comment_detail'),
)

It has many issues:

• you need to remember about the '^' and the '$'
• you repeat the entry_slug url
• you need to remember arcane named group syntax
• you repeat the [\w-]+ group
• you associate name with urls conf

Better way of writing urls would be:

urlpatterns = hurl.patterns('blog.entries.views', [
    ('', 'recent_entries'),
    ('new', 'new_entry'),
    ('<entry_slug>', [
        ('', 'show_entry'),
        ('edit', 'edit_entry'),
        ('delete', 'delete_entry'),
        ('comments', 'comments_list'),
        ('comments/<:int>', 'comment_detail'),
    ]),
])

It conveys url structure more clearly, is much more readable and avoids repetition. If your views don't rely on order, you can also use dictionary like this:

urlpatterns = hurl.patterns('blog.entries.views', {
    'show': 'show_entry',
    'edit': 'edit_entry',
    'delete': 'delete_entry',
})

How to use it

patterns (prefix, url_conf)

• prefix is same as in django.conf.url.patterns

• url_conf is either a dictionary or a list of 2-tuples

  The key (in dict) or first element (tuple) is a url fragment, value/second element can be one of: another url_conf, a string, an instance of ViewSpec:

  {
      'show': 'blog.views.show_entry',
  }
  

  is equivalent to:

  [
      ('show', 'blog.views.show_entry'),
  ]
  

  URL conf creates a tree of url fragments and generates a list by joining each fragment with the "/":

  {
      'entries': {
          'edit': 'edit_entry',
          'delete': 'delete_entry',
      }
  }
  

  This will generate these urls:

  (r'^entries/edit/$', 'edit_entry', name='edit_entry')
  (r'^entries/delete/$', 'delete_entry', name='edit_entry')
  

  Url fragment may include multiple parameters in format:

  '<parameter_name:parameter_type>'
  

  parameter_name can be any python identifier parameter_type must be one of default or defined matchers

  If you have parameter_type same as parameter_name, you can skip duplication and use shorter form:

  '<int:int>' -> '<int>'
  

  If you want to use default matcher also use shortcut:

  '<blog_slug:slug>' -> '<blog_slug>'
  

  If you don't want to define parameter name, leave it empty:

  '<:int>' # will generate r'(\d+)'
  

Default Matchers

slug:	r'[\w-]+' This is the default matcher.
int:	r'\d+'
str:	r'[^/]+'

Custom Matchers

You can define your own matchers. Just instantiate Hurl and set:

import hurl
h = hurl.Hurl()
h.matchers['year'] = r'\d{4}'

urlpatterns = h.patterns('', {'<year>': 'year_archive'})

Names generation

Hurl will automatically generate view names for you. When provided with view as string ('blog.views.show_entry') it will take last part after the dot. When provided with function it will take the func_name of it:

def some_view(req):
    pass

urlpatterns = hurl.patterns('', {
    'show': 'blog.views.show_entry', # generates 'show_entry' name
    'some': some_view, # generates 'some_view' name
})

You can also want to change the name use the 'v' function:

import hurl
urlpatterns = hurl.patterns('', {
    'show': hurl.v('show_view', name='show'),
})

Includes

If you want to include some other urlpatterns, use the include method:

import hurl
urlpatterns = hurl.patterns('', {
    'shop': hurl.include('shop.urls'),
    'blog': hurl.include('blog.urls'),
})

Mixing with pure Django urls

Hurl doesn't do anything special, it just generates plain old Django urls. You can easily mix two APIs:

from django.conf.urls import url, include, patterns
import hurl

urlpatterns = patterns('', # plain Django
    url(r'^hello/$
)

More examples

Django tutorial:

# original:
urlpatterns = patterns('',
    (r'^articles/2003/$', 'news.views.special_case_2003', {}, 'news_special_case_2003'),
    (r'^articles/(?P<year>\d{4})/$', 'news.views.year_archive', {}, 'news_year_archive'),
    (r'^articles/(?P<year>\d{4})/(?P<month>\d{2})/$', 'news.views.month_archive', {}, 'news_month_archive'),
    (r'^articles/(?P<year>\d{4})/(?P<month>\d{2})/(?P<day>\d{2})/$', 'news.views.article_detail', {}, 'news_article_detail'),
)

# hurled:
hurl = Hurl(name_prefix='news')
hurl.matchers['year'] = r'\d{4}'
hurl.matchers['month'] = r'\d{2}'
hurl.matchers['day'] = r'\d{2}'

urlpatterns = hurl.patterns('news.views', {
    'articles': {
        '2003': 'special_case_2003',
        '<year>': 'year_archive',
        '<year>/<month>': 'month_archive',
        '<year>/<month>/<day>': 'article_detail',
    }
})