Add @throttle_scope function based view decorator

[d-ryzhykau]

The new decorator allows to set throttle scope for function based views. The implementation was suggested in #9942.

The change includes a test for the new decorator and mention of it in the docs.

[browniebroke]

This line doesn't work for this new decorator... Can we rephrase or add another sentence?

[d-ryzhykau]

I moved the new decorator description to a separate section as it doesn't seem to fit into the "API policy decorators" group.

[browniebroke]

Is @throttle_classes required every time @throttle_scope is used? I don't think so if the scopes are defined in the project settings... Can we add a test to cover that please?

Also make sure we're aligned with CBV in terms of misconfigurations (e.g specifying an unknown scope)

[d-ryzhykau]

@throttle_classes is only required for tests, as the alternative way to enable ScopedRateThrottle - using REST_FRAMEWORK settings - is hard to setup: APIView.throttle_classes and SimpleRateThrottle.THROTTLE_RATES are set during import, so to change these attributes for the test it'd be necessary to reload the throttling, views and decorators modules. IMO, this would make the test more complicated and more brittle under refactoring.
Here's how the test would look like:

def test_throttle_scope(self):
    scope = "x"

    with override_settings(
        REST_FRAMEWORK={
            'DEFAULT_THROTTLE_CLASSES': ['rest_framework.throttling.ScopedRateThrottle'],
            'DEFAULT_THROTTLE_RATES': {scope: '1/day'}
        },
    ):
        reload_module(throttling)
        reload_module(views)
        reload_module(decorators)

        # view definitions and checks
        ...

    reload_module(throttling)
    reload_module(views)
    reload_module(decorators)

I've added extra checks to verify that FBV are aligned with CBV in terms of misconfigurations.

[browniebroke]

Fair enough, thanks for looking into it