Rework dynamic list/detail actions #5705

rpkilby · 2017-12-22T09:25:39Z

Pulling a slightly more manageable chunk out of #5605 for review. The goal is to remove logic from the router in order to make the viewsets and list/detail actions more introspectable.

Changes:

Deprecated list_route & detail_route in favor of action decorator w/ detail boolean.
Deprecated dynamic list/detail route variants in favor of DynamicRoute w/ detail boolean.
Added detail boolean argument to regular Route
A route's detail is now provided as an initkwarg to the ViewSet, similar to suffix.
Added ViewSet.get_extra_actions() to formalize extra action access.
Added url_path and url_name to action signature. These values are no longer set/altered by the router, and can be more reliably inspected by the parent viewset.
Refactored dynamic route generation, replacing protected method w/ internal instance method.

For the release notes, I've added a section to discuss the changes as a larger feature.

TODO:

Add release notes
Replace deprecated functions in tests
Update docs w/ changes

carltongibson

I think this is nicely done. Good benefits. Worth having.

@rpkilby, again, thanks for the effort. If you can tick off the TODOs lets have it. 👍

carltongibson · 2018-01-02T10:19:26Z

docs/topics/release-notes.md

+    * Merged `list_route` and `detail_route` into a single `action` decorator.
+    * Get all extra actions on a `ViewSet` with `.get_extra_actions()`.
+    * Extra actions now set the `url_name` and `url_path` on the decorated method.
+    * Enable action url reversing through `.reverse_action()` method (added in 3.6.4)


...3.7.4...

rpkilby · 2018-01-04T08:22:11Z

Okay, this should be ready to go now. The docs changes are not completely trivial and feedback would be appreciated.

carltongibson · 2018-01-04T09:01:35Z

docs/api-guide/routers.md


    class UserViewSet(ModelViewSet):
        ...

-        @detail_route(methods=['post'], permission_classes=[IsAdminOrIsSelf])
+        @action(methods=['post'], detail=True, permission_classes=[IsAdminOrIsSelf])


At this point the detail parameter is mysterious. (Worth explaining it below the example.)

Would it be sufficient to link to the viewset docs first? e.g., "go read this first, then come back here"

Yes. (I was thinking along those lines... 🙂)

Perhaps moving the note from ln124 up and into a Note: section may be worthwhile. (Who reads about Routers before ViewSets?)

Updated the docs. Integrated line 124 into the start of the section.

carltongibson · 2018-01-04T09:14:32Z

rest_framework/decorators.py

@@ -130,29 +130,45 @@ def decorator(func):
    return decorator


-def detail_route(methods=None, **kwargs):
+def action(methods=None, detail=True, url_path=None, url_name=None, **kwargs):


So, the detail parameter...:

Do we want an implied default? Or do we want to make it required, with a helpful assertion?

If implied which is the best default? i.e. Do we generate list or detail routes if you don't pass the parameter.

Do we want to document whichever we choose as not passing the parameter? @action(detail=True) and @action() in all the examples, say?

Not sure what I think there.

Do we want an implied default? Or do we want to make it required, with a helpful assertion?

I don't think a default is beneficial here. Making it a required arg seems 👍 to me.

carltongibson

OK. This looks good.

I'm just going to pause on this for now, since once it's in we're kind of committed to rolling a 3.8. (which is fine, but I just want to plan that first. 🙂) //cc @tomchristie

xordoquy · 2018-04-04T11:33:14Z

It seems that there are some regression on list_route & detail_route.
If no url_name was provided, it used to default on the url_path:

url_name = initkwargs.pop("url_name", None) or url_path

With the new code, it default to the function name:

func.url_name = url_name or func.__name__.replace('_', '-')

which breaks a couple of tests here and there.

carltongibson · 2018-04-04T11:36:39Z

Hey @xordoquy. Would you be able to put a regression test together for that?

xordoquy · 2018-04-04T11:38:08Z

need to investigate another issue and I'll do that.

rpkilby · 2018-04-04T15:25:26Z

Hi @xordoquy - this was an intentional change, as the url_path is not always a suitable default for the name. eg, when the path contains URL parameters.

Also, sorry for being afk lately - life has been pretty busy the last couple of months.

xordoquy · 2018-04-04T15:34:25Z

that's ok, but this should be added to the breaking changes since it requires changes on detail_route and list_route.

rpkilby · 2018-04-04T15:37:45Z

Maybe the path forward is for action to have this new behavior, with list_route and detail_route maintaining the old behavior.

carltongibson · 2018-04-04T16:08:40Z

I need to have a look at exactly what’s going on here but could we not handle the change in the shim?

carltongibson · 2018-04-04T16:10:35Z

@rpkilby you must not apologise for life. Contribution to Open Source needs to be scoped. There is no problem with that. Ever. The only problem is with the opposite. 🙂

rpkilby · 2018-04-04T16:11:55Z

Thanks - just letting you know I'm still around.

xordoquy · 2018-04-04T16:18:02Z

Maybe the path forward is for action to have this new behavior, with list_route and detail_route maintaining the old behavior.

sounds sensible to me.

Also, sorry for being afk lately

Didn't react but seconding @carltongibson on that point, you don't need to apologize for that. You did a lot of work so far, and for that we owe you one.

carltongibson · 2018-04-04T19:22:21Z

v.3.8.1 restores the old behaviour (via #5915). It's on PyPI now.

jaap3 · 2018-04-05T09:05:53Z

Thanks you for the fix and the prompt release of v3.8.1

This is needed to avoid deprecation warnigs on recent versions, see encode/django-rest-framework#5705 Signed-off-by: Michal Čihař <michal@cihar.com>

carltongibson · 2018-04-23T14:07:08Z

@Allan-Nava Please direct usage questions to Stack Overflow or the mailing list. (Again, the issue tracker is for bug reports.) Thanks.

* Merge list/detail route decorators into 'action' * Merge dynamic routes, add 'detail' attribute * Add 'ViewSet.get_extra_actions()' * Refactor dynamic route checking & collection * Refactor dynamic route generation * Add 'ViewSet.detail' initkwarg * Fixup schema test * Add release notes for dynamic action changes * Replace list/detail route decorators in tests * Convert tabs to spaces in router docs * Update docs * Make 'detail' a required argument of 'action' * Improve router docs

Ryan P Kilby added 6 commits December 22, 2017 01:18

Merge list/detail route decorators into 'action'

f79cd59

Merge dynamic routes, add 'detail' attribute

e090ba2

Add 'ViewSet.get_extra_actions()'

72b7379

Refactor dynamic route checking & collection

c2476fc

Refactor dynamic route generation

034f8d0

Add 'ViewSet.detail' initkwarg

fed7616

rpkilby added this to the 3.8 Release milestone Dec 22, 2017

rpkilby force-pushed the action-decorator branch from ec92bc3 to 046bf8a Compare December 22, 2017 17:36

Fixup schema test

23447b0

rpkilby force-pushed the action-decorator branch from 87ba917 to 23bf8cc Compare December 22, 2017 17:49

Add release notes for dynamic action changes

a591e16

carltongibson reviewed Jan 2, 2018

View reviewed changes

rpkilby force-pushed the action-decorator branch 2 times, most recently from 96b3531 to a591e16 Compare January 3, 2018 23:15

Replace list/detail route decorators in tests

151c0c9

rpkilby force-pushed the action-decorator branch 2 times, most recently from 01f568f to 151c0c9 Compare January 3, 2018 23:49

Ryan P Kilby added 2 commits January 4, 2018 02:55

Convert tabs to spaces in router docs

b69efe0

Update docs

2112a58

carltongibson reviewed Jan 4, 2018

View reviewed changes

Ryan P Kilby added 2 commits January 8, 2018 07:30

Make 'detail' a required argument of 'action'

40ab128

Improve router docs

4f6190d

carltongibson approved these changes Jan 19, 2018

View reviewed changes

carltongibson merged commit 73203e6 into encode:master Jan 25, 2018

rpkilby deleted the action-decorator branch January 25, 2018 08:41

rpkilby mentioned this pull request Jan 25, 2018

Improvements to ViewSet extra actions #5605

Merged

7 tasks

carltongibson mentioned this pull request Feb 15, 2018

ImportError: cannot import name 'action' #5830

Closed

6 tasks

rpkilby mentioned this pull request Apr 4, 2018

Use old url_name behavior in route decorators #5915

Merged

ding1992 mentioned this pull request Apr 5, 2018

Incompatibility with drf 3.8.1 chibisov/drf-extensions#211

Closed

michael-k mentioned this pull request Apr 5, 2018

docs: Add missing argument 'detail' to Route #5920

Merged

rpkilby mentioned this pull request Apr 12, 2018

Fix router compatibility with DRF 3.8 chibisov/drf-extensions#214

Merged

nijel added a commit to WeblateOrg/weblate that referenced this pull request Apr 18, 2018

Raise rest_framework dependency to 3.8

907e397

This is needed to avoid deprecation warnigs on recent versions, see encode/django-rest-framework#5705 Signed-off-by: Michal Čihař <michal@cihar.com>

This comment has been minimized.

Sign in to view

Stefs-2142 mentioned this pull request Dec 26, 2020

changed deprecated decorator @detail_route to actual @action ilyachch/django-rest-framework-rusdoc#21

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Rework dynamic list/detail actions #5705

Rework dynamic list/detail actions #5705

rpkilby commented Dec 22, 2017 •

edited

carltongibson left a comment

carltongibson Jan 2, 2018

rpkilby commented Jan 4, 2018

carltongibson Jan 4, 2018 •

edited

rpkilby Jan 4, 2018

carltongibson Jan 4, 2018

rpkilby Jan 8, 2018

carltongibson Jan 4, 2018

rpkilby Jan 8, 2018

carltongibson left a comment

xordoquy commented Apr 4, 2018

carltongibson commented Apr 4, 2018

xordoquy commented Apr 4, 2018

rpkilby commented Apr 4, 2018

xordoquy commented Apr 4, 2018

rpkilby commented Apr 4, 2018

carltongibson commented Apr 4, 2018

carltongibson commented Apr 4, 2018

rpkilby commented Apr 4, 2018

xordoquy commented Apr 4, 2018 •

edited

carltongibson commented Apr 4, 2018

jaap3 commented Apr 5, 2018

This comment has been minimized.

carltongibson commented Apr 23, 2018

Rework dynamic list/detail actions #5705

Rework dynamic list/detail actions #5705

Conversation

rpkilby commented Dec 22, 2017 • edited

carltongibson left a comment

Choose a reason for hiding this comment

carltongibson Jan 2, 2018

Choose a reason for hiding this comment

rpkilby commented Jan 4, 2018

carltongibson Jan 4, 2018 • edited

Choose a reason for hiding this comment

rpkilby Jan 4, 2018

Choose a reason for hiding this comment

carltongibson Jan 4, 2018

Choose a reason for hiding this comment

rpkilby Jan 8, 2018

Choose a reason for hiding this comment

carltongibson Jan 4, 2018

Choose a reason for hiding this comment

rpkilby Jan 8, 2018

Choose a reason for hiding this comment

carltongibson left a comment

Choose a reason for hiding this comment

xordoquy commented Apr 4, 2018

carltongibson commented Apr 4, 2018

xordoquy commented Apr 4, 2018

rpkilby commented Apr 4, 2018

xordoquy commented Apr 4, 2018

rpkilby commented Apr 4, 2018

carltongibson commented Apr 4, 2018

carltongibson commented Apr 4, 2018

rpkilby commented Apr 4, 2018

xordoquy commented Apr 4, 2018 • edited

carltongibson commented Apr 4, 2018

jaap3 commented Apr 5, 2018

This comment has been minimized.

carltongibson commented Apr 23, 2018

rpkilby commented Dec 22, 2017 •

edited

carltongibson Jan 4, 2018 •

edited

xordoquy commented Apr 4, 2018 •

edited