Improvements to ViewSet extra actions

[rpkilby]

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]

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]

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

[rpkilby]

@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]

How this change would affect this #5551?

[rpkilby]

These changes aren't directly related to #5551.

[merwok]

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]

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.

[rpkilby]

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]

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

[rpkilby]

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.

[rpkilby]

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]

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]

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]

@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.

[gabn88]

@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?