python - Manually define function signature in documentation

Question

I'm writing a function whose parameters are not necessarily known to me. How can I declare the parameters shown in documentation without hard coding parameters in the method definition?

Specifically, I use **kwargs to compensate for not knowing the inputs:

# mymodule.py

class Wrapper():

    def wrapped_method(self, **kwargs):
        known = kwargs.get('known')

        print(f'I know that {known} is needed, so I check for it explicitly.')
        print('Anything else gets ignored.  This allows me to cope with unknown parameters.')
        print('It allows me to easily add/remove parameters.')

This works great except that documentation readers (e.g. Pycharm's View > Quick Documentation or Elpy's elpy-doc) return:

Documentation for mymodule.Wrapper.wrapped_method:

wrapped_method(self, **kwargs)

It would be nice to be able to display known in the signature rather than the meaningless **kwargs. Of course I can write in the docstring which kwargs are accepted, but I hope that I can communicate to users more directly.

Here's an example of what I mean. In Emacs Lisp you can use fn(...) to manually define the signature displayed in documentation:

(defun my-func (msg &rest args)
  "Display MSG.

(fn MSG)"
  ;; ARGS is an internal parameter the user doesn't need to care
  ;; about.  It can be hidden from the user by declaring the signature
  ;; displayed within the help system with \(fn MSG)
  (message "%s" msg))

The documentation shows:

my-func is a Lisp function.

(my-func MSG)

Display MSG.

Perhaps I can do something similar in Python?

question from:https://stackoverflow.com/questions/65925949/manually-define-function-signature-in-documentation

Answer 1

Waitting for answers