René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"revisiting decorators for actions/properties/etc.","articleBody":"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:\r\n\r\nI'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:\r\n\r\n1. Write the Python function that does what I want (and give it a helpful docstring) as a method of my Extension\r\n2. Define another class wrapping that Python function in a way that can be called nicely from the API\r\n3. Reference said class from within the Extension class so it appears in the AP\r\n\r\nThere are several things that are less than ideal here:\r\n\r\n1. You end up defining your arguments in multiple places - specifically, in both the method and the View class.\r\n2. Docstrings don't propagate from the method to the View, so the HTTP API docs are not great\r\n\r\nI can see a few ways to make it better: \r\n1. 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.\r\n2. 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.\r\n\r\nI 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`.\r\n\r\nAlso, 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.\r\n\r\nI'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.","author":{"url":"https://github.com/rwb27","@type":"Person","name":"rwb27"},"datePublished":"2021-06-30T09:32:41.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":3},"url":"https://github.com/237/python-labthings/issues/237"}