skip to navigation
skip to content

Not Logged In

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: https://twitter.com/oinopion

.. image:: https://secure.travis-ci.org/oinopion/hurl.png

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

            (r'^entries/edit/$', 'edit_entry')
            (r'^entries/delete/$', 'delete_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'})

.. 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):
        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',
        }
    })
 
File Type Py Version Uploaded on Size
hurl-2.0.tar.gz (md5) Source 2012-10-08 5KB
  • Downloads (All Versions):
  • 3 downloads in the last day
  • 53 downloads in the last week
  • 293 downloads in the last month