skip to navigation
skip to content

hurl 2.0

Latest Version: 2.1

Django Happy Urls

This is early work. Expect very weird errors.
Comments/feedback is very welcome, use issues or twitter:

.. image::

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

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 urls::

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

Url fragment may include multiple parameters in format::


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


This is the default matcher.





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'})

.. note::

When defining custom matchers use the 'patterns' method of your instance,
rather than function provided by module.

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):

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'),


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

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',
File Type Py Version Uploaded on Size
hurl-2.0.tar.gz (md5) Source 2012-10-08 5KB