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.

Answer 1

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.