Improvements to ViewSet extra actions #5605

rpkilby · 2017-11-17T22:06:05Z

Resolves #2062, #2934, #3271, #5755
Fixes #4920

This will obviously require more extensive testing and documentation updates, but I'd like to hammer out the implementation details first. But first, here's a preview of the changes to the browsable API:

The above changes include:

Breadcrumb and page title support custom names/titles for actions instead of just "User instance".
The method docstring is now used as the action's description.
A dropdown of "Extra Actions" (appropriately filtered to detail/non-detail actions).
Also, note that custom serializer classes were already supported.

To implement this, it was necessary to change how routers and viewsets interact. At a higher level:

Views more explicitly customize their display name and description.
ViewSets are provided more context/configuration from the router. For example, it can now determine if the current request is operation on a list or detail action.

In more detail detail:

Note that these changes build off of Add '.basename' and '.reverse_action()' to ViewSet #5648 and Rework dynamic list/detail actions #5705, which were spun out of this PR.
Views now accept name and description via the initkwargs.
- This provides a general hook for customizing their display on the browsable API.
- This is necessary to allow action methods to specify they're own name/description.
get_view_name and get_view_description now expect the View instance instead of a class.
get_view_name and get_view_description respect the new View name and description.
ViewSets consider name and suffix to be mutually exclusive.
The action decorator now allows users to specify the name, uses the docstring as the description.
Adds ViewSet.get_extra_action_url_map for rendering extra actions.
Adds renderer/template code for both the browsable and admin APIs.

Adds method mapping to ViewSet actions. Multiple ViewSet methods can handle different HTTP methods of an action. ex:

class MyViewSet(ViewSet):

    @action(detail=False)
    def example(self, request, **kwargs):
        ...

    @example.mapping.post
    def create_example(self, request, **kwargs):
        ...

TODO:

Look into: Mark extra actions which corresponds to the same URL #4920, ~~AutoSchema fails when set on detail_route #5630~~
Add tests for new functionality
Add actions list to browsable API
Add actions list to admin API
Fix action title/description display in browsable API
Update docs, changelog
~~Rename/deprecate base_name to basename for consistency.~~

auvipy

I like the naming of action rater then detail/list route.

how many routable actions will be possible on a single viewset?

rpkilby · 2017-11-18T05:11:09Z

I like the naming of action rater then detail/list route.

Agreed @auvipy. It's not so much that I'm in favor of action, more that I've never particularly liked list_route/detail_route.

how many routable actions will be possible on a single viewset?

There isn't any limit, as there wasn't any limit to list/detail routes.

SIde note: more commits incoming

auvipy · 2017-11-18T05:29:47Z

It would be great to see some good example as part of this pr. thanks for the great work!

rpkilby · 2017-11-18T05:38:42Z

@auvipy, right now, there's a screenshot in the original comment, which should demonstrate the practical changes to the browsable API. As far as code goes, it's pretty much just:

class MyViewSet(...):
    @action(methods=['get'], detail=True, name='Custom name'
            serializer_class=ThingySerializer)
    def do_a_thing(self, request, pk, *args, **kwargs):
        """
        # Docstrings are now used as descriptions!
        """

auvipy · 2017-11-18T07:15:30Z

How this change would affect this #5551?

rpkilby · 2017-11-18T17:31:44Z

These changes aren't directly related to #5551.

merwok · 2017-11-18T20:40:01Z

rest_framework/decorators.py

+    warnings.warn(
+        "`detail_route` has been deprecated in favor of `action`, which accepts a "
+        "`detail` boolean. Use `@action(['GET'], detail=True)` instead.",
+        PendingDeprecationWarning


I think this needs a stacklevel parameter so that the source code in the traceback points to the file using detail_route, not this file.

carltongibson

OK. Interesting.

Initial thought is 😱 breaking change but with the deprecation it's not a big issue I think.

I need to sit down with the implementation details but cool. 👍

carltongibson · 2017-11-20T08:16:28Z

rest_framework/decorators.py

+    Used to mark a method on a ViewSet that should be routed for detail requests.
+    """
+    warnings.warn(
+        "`detail_route` has been deprecated in favor of `action`, which accepts a "


This is quite a big change for users. I think I'd like to see the message here saying, "pending deprecation" and "will be removed in 3.10" so that it's mega-clear what sort of timescale users have.

This will require updating these messages for 3.9 (unless we're clever with the wording) but I think we need to be extra helpful here.

I think this also merits a beginning on the release notes.

Agreed. My main consideration right now is to determine if this is the path we ultimately want to move toward, and then work backwards from that w/ deprecations and whatnot.

Right now, the state of the PR is more exploratory. For example, I also want to try and fix #4920, which will require more modifications to the dynamic route generation.

carltongibson

Hey @rpkilby. This is pay off from #5705. Fancy re-doing from that as a base? (If it's not too much faff.)

carltongibson · 2018-03-26T08:54:46Z

Hey @rpkilby. Any appetite for pushing this over the line? It looks like it just needs docs and a few test cases

rpkilby · 2018-05-16T14:06:10Z

Hi all - the PR is largely done and ready for review (documentation not withstanding). In addition to tests, the updates implements #4920 and copies the "Extra Actions" dropdown from the Browsable API to the Admin API template.

carltongibson

Hey @rpkilby.

Sorry for the slow review here.

Great stuff.

I'm expecting to see some docs here. 🙂

ViewSets may now provide their `name` and `description` attributes directly, instead of relying on view introspection to derive them. These attributes may also be provided with the view's initkwargs. The ViewSet `name` and `suffix` initkwargs are mutually exclusive. The `action` decorator now provides the `name` and `description` to the view's initkwargs. By default, these values are derived from the method name and its docstring. The `name` may be overridden by providing it as an argument to the decorator. The `get_view_name` and `get_view_description` hooks now provide the view instance to the handler, instead of the view class. The default implementations of these handlers now respect the `name`/`description`.

Removed old test logic around link/action decorators from `v2.3`. Also simplified the test by making the results explicit instead of computed.

rpkilby · 2018-06-25T19:51:43Z

Okay, added some documentation. This includes:

Updated the VIEW_NAME_FUNCTION/VIEW_DESCRIPTION_FUNCTION docs to the new signature, and documented the relevant ViewSet optional arguments (name, suffix, detail, description).
Document the new method mapping enhancement for the action decorator.

noisy · 2018-07-14T22:58:48Z

I just found this pull request, because I tried to make my actions visible in browsable api. Thank you for this work.

Right now I am developing my project installing DRF directly from git. @carltongibson - do you know when we can expect a new version of DRF with this feature included?

rpkilby · 2018-07-14T23:02:11Z

Brief aside: I know there is a little more work that needs to be done before a 3.9 release can be shipped, but one minor blocker is #6081, which fixes a flaw in this pull request. I should have time to work on it this weekend.

carltongibson · 2018-07-15T06:27:20Z

@noisy we’re working on the 3.9 release now. I would think a few weeks. Pip’s VCS support is first class. There’s no reason why you can’t use the version from master.

related encode/django-rest-framework#5605

* View suffix already set by initializer * Add 'name' and 'description' attributes to ViewSet ViewSets may now provide their `name` and `description` attributes directly, instead of relying on view introspection to derive them. These attributes may also be provided with the view's initkwargs. The ViewSet `name` and `suffix` initkwargs are mutually exclusive. The `action` decorator now provides the `name` and `description` to the view's initkwargs. By default, these values are derived from the method name and its docstring. The `name` may be overridden by providing it as an argument to the decorator. The `get_view_name` and `get_view_description` hooks now provide the view instance to the handler, instead of the view class. The default implementations of these handlers now respect the `name`/`description`. * Add 'extra actions' to ViewSet & browsable APIs * Update simple router tests Removed old test logic around link/action decorators from `v2.3`. Also simplified the test by making the results explicit instead of computed. * Add method mapping to ViewSet actions * Document extra action method mapping

gabn88 · 2021-03-22T14:16:00Z

@carltongibson @rpkilby
Great work with this addition!
I was wondering for almost a year why I couldn't get the "extra actions" button on my production site. In tests it worked, but on my live site I just couldn't get it working.
Until I saw: #7500 which fixed it right away.
Would it be possible to incorporate this?

rpkilby added this to the v3.8 milestone Nov 17, 2017

rpkilby force-pushed the viewset-actions branch 2 times, most recently from 27a2e93 to 7bac555 Compare November 18, 2017 02:39

auvipy reviewed Nov 18, 2017

View reviewed changes

rpkilby force-pushed the viewset-actions branch from 6ef27c6 to eafe0cc Compare November 18, 2017 05:14

rpkilby mentioned this pull request Nov 18, 2017

Support "extra actions" for routing in the HTML forms for the browsable API #2062

Closed

merwok reviewed Nov 18, 2017

View reviewed changes

carltongibson added the Needs further review label Nov 20, 2017

carltongibson reviewed Nov 20, 2017

View reviewed changes

rpkilby mentioned this pull request Dec 4, 2017

Add '.basename' and '.reverse_action()' to ViewSet #5648

Merged

rpkilby force-pushed the viewset-actions branch from a8dff35 to c028686 Compare December 4, 2017 11:15

rpkilby mentioned this pull request Dec 22, 2017

Rework dynamic list/detail actions #5705

Merged

3 tasks

carltongibson reviewed Jan 19, 2018

View reviewed changes

carltongibson added Enhancement and removed Needs further review labels Jan 19, 2018

rpkilby force-pushed the viewset-actions branch from c028686 to 5207a3f Compare January 25, 2018 13:21

carltongibson removed this from the 3.8 Release milestone Apr 3, 2018

rpkilby force-pushed the viewset-actions branch 2 times, most recently from 144c55d to b4d3eab Compare May 16, 2018 09:26

rpkilby changed the title ~~[wip] Viewset extra actions~~ Improvements to ViewSet extra actions May 16, 2018

rpkilby added this to the 3.9 Release milestone May 16, 2018

rpkilby mentioned this pull request May 16, 2018

Mark extra actions which corresponds to the same URL #4920

Closed

rpkilby force-pushed the viewset-actions branch from 98397c9 to 4bb5de5 Compare May 16, 2018 14:16

carltongibson reviewed Jun 22, 2018

View reviewed changes

View suffix already set by initializer

06265b6

rpkilby force-pushed the viewset-actions branch from 4bb5de5 to 90ae57c Compare June 24, 2018 22:00

rpkilby force-pushed the viewset-actions branch 4 times, most recently from 597415d to c604380 Compare June 25, 2018 17:29

Ryan P Kilby added 2 commits June 25, 2018 13:39

Add 'extra actions' to ViewSet & browsable APIs

3c60b4b

Update simple router tests

9b64818

Removed old test logic around link/action decorators from `v2.3`. Also simplified the test by making the results explicit instead of computed.

rpkilby force-pushed the viewset-actions branch from c604380 to deb0477 Compare June 25, 2018 17:40

Add method mapping to ViewSet actions

f323989

rpkilby force-pushed the viewset-actions branch from deb0477 to f323989 Compare June 25, 2018 17:50

Document extra action method mapping

d1676f9

rpkilby mentioned this pull request Jun 26, 2018

Feature/action docs sections #6060

Merged

carltongibson approved these changes Jul 6, 2018

View reviewed changes

carltongibson merged commit 0148a9f into encode:master Jul 6, 2018

rpkilby deleted the viewset-actions branch July 6, 2018 14:26

rpkilby mentioned this pull request Jul 10, 2018

Fix action support for ViewSet suffixes #6081

Merged

3 tasks

axnsan12 mentioned this pull request Aug 6, 2018

drf-yasg does not work with DRF 3.9 action mappings axnsan12/drf-yasg#177

Closed

OskarPersson mentioned this pull request Oct 19, 2018

Add support for Django Rest Framework 3.9 tuffnatty/drf-proxy-pagination#4

Merged

soerface mentioned this pull request Jan 18, 2019

Improve documentation regarding serializer class on extra actions. #6410

Closed

shanemcd pushed a commit to shanemcd/awx that referenced this pull request Jun 18, 2019

Update get_view_description to conform to changes in DRF's version

53d7ac9

related encode/django-rest-framework#5605

nlgotz mentioned this pull request Apr 24, 2024

fix: API get_view_name display the proper name for actions nautobot/nautobot#5600

Merged

7 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improvements to ViewSet extra actions #5605

Improvements to ViewSet extra actions #5605

rpkilby commented Nov 17, 2017 •

edited

Loading

auvipy left a comment

rpkilby commented Nov 18, 2017

auvipy commented Nov 18, 2017

rpkilby commented Nov 18, 2017

auvipy commented Nov 18, 2017

rpkilby commented Nov 18, 2017

merwok Nov 18, 2017

carltongibson left a comment

carltongibson Nov 20, 2017

rpkilby Nov 21, 2017 •

edited

Loading

carltongibson left a comment

carltongibson commented Mar 26, 2018

rpkilby commented May 16, 2018

carltongibson left a comment

rpkilby commented Jun 25, 2018

noisy commented Jul 14, 2018

rpkilby commented Jul 14, 2018

carltongibson commented Jul 15, 2018

gabn88 commented Mar 22, 2021 •

edited

Loading

Improvements to ViewSet extra actions #5605

Improvements to ViewSet extra actions #5605

Conversation

rpkilby commented Nov 17, 2017 • edited Loading

auvipy left a comment

Choose a reason for hiding this comment

rpkilby commented Nov 18, 2017

auvipy commented Nov 18, 2017

rpkilby commented Nov 18, 2017

auvipy commented Nov 18, 2017

rpkilby commented Nov 18, 2017

merwok Nov 18, 2017

Choose a reason for hiding this comment

carltongibson left a comment

Choose a reason for hiding this comment

carltongibson Nov 20, 2017

Choose a reason for hiding this comment

rpkilby Nov 21, 2017 • edited Loading

Choose a reason for hiding this comment

carltongibson left a comment

Choose a reason for hiding this comment

carltongibson commented Mar 26, 2018

rpkilby commented May 16, 2018

carltongibson left a comment

Choose a reason for hiding this comment

rpkilby commented Jun 25, 2018

noisy commented Jul 14, 2018

rpkilby commented Jul 14, 2018

carltongibson commented Jul 15, 2018

gabn88 commented Mar 22, 2021 • edited Loading

rpkilby commented Nov 17, 2017 •

edited

Loading

rpkilby Nov 21, 2017 •

edited

Loading

gabn88 commented Mar 22, 2021 •

edited

Loading