@wraps decorator to expose underlying method documentation

[hsvlz]

Hi Miguel,

adding a @wraps decorator to expose underlying method documentation for every socketio.on event

[miguelgrinberg]

@hsvlz the decorator does not wrap the original function, it returns the original function. Did you see a situation in which the documentation of the original function was lost?

[hsvlz]

When iterating over socketio.server.handlers.items() in my function generating the documentation:

for namespace, rules in socketio.server.handlers.items():
       for rule, func in rules.items():

func ends up always being _handler with no access to func_name or func_docs. By adding this @wraps, I can access the underlying function information of a function using the decorator @socketio.on(...)

[miguelgrinberg]

Are you aware that socketio.server is undocumented in Flask-SocketIO, and that server.handlers is undocumented in python-socketio, right? Those can change without deprecation or even notice, because applications are not supposed to use them.

[hsvlz]

Is there an alternative public way to iterate over function handlers, the same way it is safe to iterate over current_app.url_map.iter_rules() in flask? Otherwise, what do you propose in order to create auto-generated documentation of all socketio endpoints in realtime for a /documentation endpoint?

[miguelgrinberg]

No, there is currently no official way to iterate over the handlers. You could use a custom decorator to mark functions as needing documentation to avoid using the private attributes.

[hsvlz]

The issue with adding custom decorators for documentation is:

• decorator hell (functions could end up with quite a few decorators and you need to repeat it for every single method)
• unnecessary decorators are applied - for instance in production, documentation will be turned off, and therefore maintaining unnecessary data-structures and code for documentation will be executed regardless

@socketio.on() is guaranteed to be a decorator, therefore adding @wraps should not affect your implementation. I agree that your underlying implementation could evolve, and that both socketio.server and server.handlers are undocumented - I am using them at my own peril and should the implementation change, I would adapt.

[miguelgrinberg]

I'll think about this. It may make more sense to provide an iterator that can give you the actual functions, not the internal wrapper.

[hsvlz]

That would work for me! Thank you Miguel.

[bpengu1n]

@miguelgrinberg Has there been any progress on adding an iterator for handler functions? If not, would you be open to a pull request submission for it? I'm writing a sphinx plugin to generate documentation for Flask_SocketIO API endpoints, and it's proving to be impractical without a way to get at those original references.

[miguelgrinberg]

@bpengu1n I haven't done any work on this issue. Open to accept a contribution for it. Thanks!