Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

DRY way to manage url parameters associated with a model instance based on Jingo.

Project Description

# Django Model URLs

[![Build Status](](

This app makes urls usage DRYer.
It maps URL keywords to a model object instance by passing the object
instance as argument to the URL.

In short, having an `article` model instance, you can write this:

<a href="{{ url('article:detail', article) }}">View this article</a>

While you have been writing this so far:

<a href="{{ url('article:detail', year=article.year, month=article.month, slug=article.slug) }}">View this article</a>

This is for your templates as well as for your `reverse()` and preserves
other urls to work.

> Right now it is build for [Jinja2]( using the
easy-to-use [Jingo]( adapter.
> If you are using plain Django template, refer to version 0.3.1.
> A new version for plain Django should come out later on.

## Installation

Download via pip ![pip badge](

pip install django-model-urls

or get the bleeding edge version:

pip install git+

Add _model\_urls_ to your _settings_ file:


And you're done!

## How to use it

In the examples below we will consider this model:

class Article(models.Model):
slug = models.SlugField()
title = models.CharField(max_length=50)
date = models.DateField()

def year(self):

def month(self):

and this urls:

urlpatterns = patterns('',
ArticleView.as_view(), name="article_details"),

and `article` being an instance of the `Article` class.

### In a template

url('article_details', article)

#### In a view

from model_urls.urlresolvers import reverse

reverse('article_details', article)

Both will generate a url in this format:


## Extra tools

Basically you should be able to use `url()` and `reverse()` in all cases.
However, these tools are also available:

#### Template helpers

- `url(viewname, *args, **kwargs)` will try to detect an instance in arguments
and choose wheter to use _simple\_url()_ or _model\_url()_ otherwise.
- `simple_url(viewname, *args, **kwargs)` is an alias to Jingo's `url()`
helper to force using it.
- `model_url(viewname, instance, *args, **kwargs)` will generate the url from
the instance in first argument.

#### Url reversing

These functions are available in `model_urls.urlresolvers`.

- `model_reverse(viewname, instance, urlconf=None, args=None, kwargs=None,
prefix=None, current_app=None)` will generate the url based on the instance
- `reverse(viewname, *args, **kwargs)` will fallback to _model\_reverse()_ if
an instance is found in arguments or to Django's _reverse()_ otherwise.

## Configuration

An optional configuration is for your settings is:


This option will not allow the Jingo's `url()` helper to be overriden by the
one from model_urls.

In this case you should use `model_url()` to use an instance.

### Further examples

#### Use cases

A common use case is switching from pk based url to slug.
Using django-model-urls means updating the _urls.py_ file to consider slug
without altering views or template files.

#### Read tests

Refer to [](
to see more usages.

Release History

This version
History Node


History Node


Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, Size & Hash SHA256 Hash Help File Type Python Version Upload Date
(5.9 kB) Copy SHA256 Hash SHA256
Source None Nov 1, 2014

Supported By

Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Google Google Cloud Servers