django-rest-framework/rest_framework/routers.py

277 lines
9.2 KiB
Python
Raw Normal View History

2013-04-25 01:40:24 +04:00
"""
Routers provide a convenient and consistent way of automatically
determining the URL conf for your API.
They are used by simply instantiating a Router class, and then registering
all the required ViewSets with that router.
For example, you might have a `urls.py` that looks something like this:
router = routers.DefaultRouter()
router.register('users', UserViewSet, 'user')
router.register('accounts', AccountViewSet, 'account')
urlpatterns = router.urls
"""
from __future__ import unicode_literals
import itertools
from collections import namedtuple
from django.core.exceptions import ImproperlyConfigured
2013-05-16 18:08:12 +04:00
from rest_framework import views
2013-05-14 13:01:05 +04:00
from rest_framework.compat import patterns, url
2013-04-25 01:40:24 +04:00
from rest_framework.response import Response
from rest_framework.reverse import reverse
from rest_framework.urlpatterns import format_suffix_patterns
2013-04-04 23:00:44 +04:00
Route = namedtuple('Route', ['url', 'mapping', 'name', 'initkwargs'])
def replace_methodname(format_string, methodname):
"""
Partially format a format_string, swapping out any
2013-04-26 18:09:55 +04:00
'{methodname}' or '{methodnamehyphen}' components.
"""
methodnamehyphen = methodname.replace('_', '-')
ret = format_string
ret = ret.replace('{methodname}', methodname)
ret = ret.replace('{methodnamehyphen}', methodnamehyphen)
return ret
def flatten(list_of_lists):
"""
Takes an iterable of iterables, returns a single iterable containing all items
"""
return itertools.chain(*list_of_lists)
2013-04-04 23:00:44 +04:00
class BaseRouter(object):
def __init__(self):
self.registry = []
def register(self, prefix, viewset, base_name=None):
if base_name is None:
base_name = self.get_default_base_name(viewset)
self.registry.append((prefix, viewset, base_name))
def get_default_base_name(self, viewset):
"""
If `base_name` is not specified, attempt to automatically determine
it from the viewset.
"""
raise NotImplemented('get_default_base_name must be overridden')
2013-04-04 23:00:44 +04:00
2013-04-25 01:40:24 +04:00
def get_urls(self):
"""
Return a list of URL patterns, given the registered viewsets.
"""
2013-04-25 01:40:24 +04:00
raise NotImplemented('get_urls must be overridden')
2013-04-04 23:00:44 +04:00
@property
2013-04-25 01:40:24 +04:00
def urls(self):
if not hasattr(self, '_urls'):
self._urls = patterns('', *self.get_urls())
return self._urls
class SimpleRouter(BaseRouter):
routes = [
# List route.
Route(
url=r'^{prefix}{trailing_slash}$',
mapping={
2013-04-25 01:40:24 +04:00
'get': 'list',
'post': 'create'
},
name='{basename}-list',
initkwargs={'suffix': 'List'}
2013-04-25 01:40:24 +04:00
),
# Detail route.
Route(
url=r'^{prefix}/{lookup}{trailing_slash}$',
mapping={
2013-04-25 01:40:24 +04:00
'get': 'retrieve',
'put': 'update',
'patch': 'partial_update',
'delete': 'destroy'
},
name='{basename}-detail',
initkwargs={'suffix': 'Instance'}
2013-04-25 01:40:24 +04:00
),
# Dynamically generated routes.
# Generated using @action or @link decorators on methods of the viewset.
Route(
url=r'^{prefix}/{lookup}/{methodname}{trailing_slash}$',
mapping={
2013-04-25 01:40:24 +04:00
'{httpmethod}': '{methodname}',
},
name='{basename}-{methodnamehyphen}',
initkwargs={}
2013-04-25 01:40:24 +04:00
),
2013-04-04 23:00:44 +04:00
]
def __init__(self, trailing_slash=True):
self.trailing_slash = trailing_slash and '/' or ''
super(SimpleRouter, self).__init__()
def get_default_base_name(self, viewset):
"""
If `base_name` is not specified, attempt to automatically determine
it from the viewset.
"""
model_cls = getattr(viewset, 'model', None)
queryset = getattr(viewset, 'queryset', None)
if model_cls is None and queryset is not None:
model_cls = queryset.model
assert model_cls, '`base_name` argument not specified, and could ' \
'not automatically determine the name from the viewset, as ' \
'it does not have a `.model` or `.queryset` attribute.'
return model_cls._meta.object_name.lower()
2013-04-25 01:40:24 +04:00
def get_routes(self, viewset):
"""
Augment `self.routes` with any dynamically generated routes.
Returns a list of the Route namedtuple.
2013-04-25 01:40:24 +04:00
"""
known_actions = flatten([route.mapping.values() for route in self.routes])
2013-04-25 01:40:24 +04:00
# Determine any `@action` or `@link` decorated methods on the viewset
dynamic_routes = []
2013-04-25 01:40:24 +04:00
for methodname in dir(viewset):
attr = getattr(viewset, methodname)
httpmethods = getattr(attr, 'bind_to_methods', None)
if httpmethods:
if methodname in known_actions:
raise ImproperlyConfigured('Cannot use @action or @link decorator on '
'method "%s" as it is an existing route' % methodname)
httpmethods = [method.lower() for method in httpmethods]
dynamic_routes.append((httpmethods, methodname))
2013-04-25 01:40:24 +04:00
2013-04-04 23:00:44 +04:00
ret = []
for route in self.routes:
if route.mapping == {'{httpmethod}': '{methodname}'}:
# Dynamic routes (@link or @action decorator)
for httpmethods, methodname in dynamic_routes:
initkwargs = route.initkwargs.copy()
initkwargs.update(getattr(viewset, methodname).kwargs)
ret.append(Route(
url=replace_methodname(route.url, methodname),
mapping=dict((httpmethod, methodname) for httpmethod in httpmethods),
name=replace_methodname(route.name, methodname),
initkwargs=initkwargs,
2013-04-25 01:40:24 +04:00
))
else:
# Standard route
ret.append(route)
2013-04-25 01:40:24 +04:00
return ret
2013-04-04 23:00:44 +04:00
2013-04-25 01:40:24 +04:00
def get_method_map(self, viewset, method_map):
"""
Given a viewset, and a mapping of http methods to actions,
return a new mapping which only includes any mappings that
are actually implemented by the viewset.
"""
bound_methods = {}
for method, action in method_map.items():
if hasattr(viewset, action):
bound_methods[method] = action
return bound_methods
def get_lookup_regex(self, viewset):
"""
Given a viewset, return the portion of URL regex that is used
to match against a single instance.
"""
if self.trailing_slash:
base_regex = '(?P<{lookup_field}>[^/]+)'
else:
# Don't consume `.json` style suffixes
base_regex = '(?P<{lookup_field}>[^/.]+)'
2013-04-25 01:40:24 +04:00
lookup_field = getattr(viewset, 'lookup_field', 'pk')
return base_regex.format(lookup_field=lookup_field)
def get_urls(self):
"""
Use the registered viewsets to generate a list of URL patterns.
"""
ret = []
2013-04-04 23:00:44 +04:00
2013-04-25 01:40:24 +04:00
for prefix, viewset, basename in self.registry:
lookup = self.get_lookup_regex(viewset)
routes = self.get_routes(viewset)
for route in routes:
2013-04-04 23:38:42 +04:00
2013-04-25 01:40:24 +04:00
# Only actions which actually exist on the viewset will be bound
mapping = self.get_method_map(viewset, route.mapping)
if not mapping:
continue
# Build the url pattern
regex = route.url.format(
prefix=prefix,
lookup=lookup,
trailing_slash=self.trailing_slash
)
view = viewset.as_view(mapping, **route.initkwargs)
name = route.name.format(basename=basename)
ret.append(url(regex, view, name=name))
2013-04-04 23:00:44 +04:00
return ret
2013-04-25 01:40:24 +04:00
class DefaultRouter(SimpleRouter):
"""
The default router extends the SimpleRouter, but also adds in a default
API root view, and adds format suffix patterns to the URLs.
"""
include_root_view = True
include_format_suffixes = True
root_view_name = 'api-root'
2013-04-25 01:40:24 +04:00
def get_api_root_view(self):
"""
Return a view to use as the API root.
"""
api_root_dict = {}
list_name = self.routes[0].name
2013-04-25 01:40:24 +04:00
for prefix, viewset, basename in self.registry:
api_root_dict[prefix] = list_name.format(basename=basename)
2013-05-16 18:08:12 +04:00
class APIRoot(views.APIView):
_ignore_model_permissions = True
2013-04-25 01:40:24 +04:00
2013-05-16 18:08:12 +04:00
def get(self, request, format=None):
ret = {}
for key, url_name in api_root_dict.items():
ret[key] = reverse(url_name, request=request, format=format)
return Response(ret)
return APIRoot.as_view()
2013-04-25 01:40:24 +04:00
def get_urls(self):
"""
Generate the list of URL patterns, including a default root view
for the API, and appending `.json` style format suffixes.
"""
urls = []
if self.include_root_view:
root_url = url(r'^$', self.get_api_root_view(), name=self.root_view_name)
2013-04-25 01:40:24 +04:00
urls.append(root_url)
default_urls = super(DefaultRouter, self).get_urls()
urls.extend(default_urls)
if self.include_format_suffixes:
urls = format_suffix_patterns(urls)
return urls