revisiting decorators for actions/properties/etc.

[rwb27]

I am sure we have discussed in the past the merits of defining a View subclass for each endpoint, e.g. in an Extension. I have a nasty feeling that I probably argued strongly against using decorators because they often make life quite confusing. However, I'm coming round to the idea. My use case is this:

I'm writing some code in an extension, which includes a function to do something. For argument's sake let's say that function should be an Action but I think the same consideration applies to properties. Ideally, I'd like it to be accessible either via HTTP or via Python. Currently, what I do is:

1. Write the Python function that does what I want (and give it a helpful docstring) as a method of my Extension
2. Define another class wrapping that Python function in a way that can be called nicely from the API
3. Reference said class from within the Extension class so it appears in the AP

There are several things that are less than ideal here:

1. You end up defining your arguments in multiple places - specifically, in both the method and the View class.
2. Docstrings don't propagate from the method to the View, so the HTTP API docs are not great

I can see a few ways to make it better:

1. Be more explicit about the fact that ActionView classes are more or less always wrapping a function to do an action. This would, for example, mean that instead of writing a post method, I would supply an action function. Doing that explicitly makes it way easier to wrap the action function nicely, e.g. propagate the docstrings.
2. Provide a decorator to put the definition of the ActionView right next to the function it's wrapping. This makes it harder to miss things being out of sync, and could also eliminate the need to register views explicitly.

I think if I argued against custom decorators in the past, it was because I felt they were non-standard ways of doing things, and wouldn't make sense to someone familiar with Flask. That's true, but I think there's enough that's non-standard about e.g. the way we generate our APISpec that this battle is possibly lost anyway. Also, if we define a more "helpful" ActionView subclass, it potentially provides a point of familiarity for Flask developers - so if they understand how @action maps onto ActionViewWrapper (which is potentially quite simple), it's easier to figure out what happens once you have a View.

Also, I think when we made this decision, it was more likely that you would want control over the get/post/delete/whatever methods. Now that the WoT specification is finalised, it's pretty well defined what each HTTP method should do, and I'm in favour of providing a mapping from HTTP methods to meaningful WoT interactions. I.e. a PropertyView always reads a property with GET and writes it with PUT and may define a way to update it with POST. So probably we should, by default, define a getter, setter, and update method - not all of which must exist. Similarly, an ActionView will always run actions with POST and return status with GET, so it makes sense to simply have a function responsible for running the action (which is what's currently implemented in ActionView.post. This also means that overriding ActionView.post would allow an action to do something custom before it's spawned in a background thread, such as validating arguments and returning an HTTP error code if they're wrong.

I'm raising this issue so @jtc42 can tell me why I was dead against this in the past, or if he remembers anything important that's not reflected in the discussion above.