How to document kwargs using epytext for the auto completion hinting in PyCharm?

Question

Is is possible to get an additional hint for kwargs, which will give you examples of predefined possible keyword arguments? Maybe epytext is not supporting it?

class Person():
    def __init__(self, **kwargs):
        """
        @param name: Name
        @type name: str
        @param age: Age
        @type age: int
        @param connections: Connections to other persons
        @type connections: [Person]
        .
        .
        . # I know this is not working
        """
        self.name = kwargs[name] if name in kwargs
        self.age  = kwargs[age] if age in kwargs
        # and so on ...

Would be great if I'll get something like this in the completion hint (sorry I had to remove the pictures):

> self,name,age,connections

Whith a Quick Doku looking like this:

No image*

I really like to have global classes with common classes as parents. That makes it much easier for reuse. So here is a little snippet example:

class common():
    PERSON_DETAILS = dict( name       = ' ',
                           age        = 1,
                           connection = []  )

With a bit different defined class of Person:

class Person(common):

    def setDetail(self, **kwargs):
        """
        Set some detail information about the person.
        """
        argErrors = []
        for arg, value in kwargs.iteritems():
            if arg in self.PERSON_DETAILS:
                if type(value)==type(self.PERSON_DETAILS[arg]):
                    self.doSomething() # I don't want to go deeper here
                else:
                    raise ValueError("setDetails(%s) the type of '%s' needs to be %s, %s found" % (arg,arg,type(self.PERSON_DETAILS[arg]),type(value)))
            else:
                raise TypeError("setDetails() got an unexpected keyword argument '%s'" %arg )



person = Person()
person.setDetails()

The following (picture removed) shows what I get as completion hint (which is totally right), but it would be great to have a rolled out argument list from kwargs (like in the first example):

> self,**kwargs

I know that the docstring implementation for definitions and auto completion hints are limited, but maybe someone knows a different way to get what I want in PyCharm.

The whole point of `**kwargs` is that you can pass *any arbitrary keyword arguments*. AFAIK you can only hint `@param kwargs` as a whole in `epytext`, otherwise it doesn't know what parameters you're referring to. — jonrsharpe, Dec 09 '14 at 15:28

score 4 · Accepted Answer · edited Mar 27 '18 at 16:29

4

According to the Epytext documentation, you will be able to achieve this by using @keyword.

@param fields should be used to document any explicit parameter (including the keyword parameter). @keywordfields should only be used for non-explicit keyword parameters:

Also, @kwarg p: ... and @kwparam p: ... are synonyms.

edited Mar 27 '18 at 16:29

Stevoisiak

23,794
27
122
225

answered Dec 18 '14 at 08:49

Azman0101

56
2

"You need configured Python 2 SDK to render Epydoc docstrings" Isn't there a standard way? I even tried copying docstrings from some classes but I'm not getting hints when I apply the docstring to my class methods – TheRealChx101 Aug 12 '19 at 23:10

How to document kwargs using epytext for the auto completion hinting in PyCharm?

1 Answers1