Bdtjtk

EDITED: Let's say I have some classes that inherit from the SuperFoo abstract class:

from abc import ABCMeta, abstractmethod



class SuperFoo(object):

    __metaclass__ = ABCMeta



    @abstractmethod

    def do_something():

        pass



class Foo(SuperFoo):

    def __init__(self):

        pass



    def do_something():

        pass



class Bar(SuperFoo):

    def __init__(self):

        pass



    def do_something():

        pass

And a documented function that takes in a subclass of SuperFoo as a parameter:

def build(super_foo):

    """

    Instantiate a SuperFoo class and do some other stuff.

    @param super_foo: The subclass whose constructor will be called

    @type super_foo: ??? <--- What to use here?

    @return: An instance of a SuperFoo subclass

    @rtype: SuperFoo

    """

    # Do some stuff



    instance = class_name()  # Instantiate class

    return instance



foo = build(Foo)

bar = build(Bar)

What @type should I use in the function's docstring? It cannot be SuperFoo because that would correspond to an instance of SuperFoo and not to the type itself.

The simple technical answer has already been posted by motyzk - in your example, what you pass to build are classes so the the (ill-named) class_name param is of type type - with the restriction that (based on your code snippet) this class shouldn't expect any parameter, which doesn't correspond to any unambigous well-defined existing builtin "type".

Now as mentionned in comments, in Python

• everything is an object (and as such an instance of a class),


• instanciating a class is done by calling the class object just like you'd call any function,


• all callables DO return an object, even if implicitely (None is an object too)

so your build function would technically work just the same with just any callable that doesn't expect a param. As an example, this:

def bar():

   return



whatever = build(bar)

is technically correct.

Now you mention in the function's docstring (emphasis is mine):

Instantiate a class and do some other stuff

Since your function would just be totally useless as shown in the snippet you posted, I assume that in your real code the important part is in the (not shown) "do some other stuff", and that this "do some other stuff" part relies on some specific property of the class being passed.

In this case, you should document those specificities, either informally (textually, in the docstring itself) or formally using the abc module. This won't solve your question actually - your function expects a class, not instance, so theoritically @type should be type(YourABC), but then what you get is abc.ABCMeta. At this point, you either have to write a custom metaclass (inherithing from abc.ABCMeta) and specify it as the proper @type - but this won't say anything useful as far as documentation is concerned - or just textually describe it as "a MyABC subclass" (which is the correct description but not usable for code instrumentation).

The type is "type", as can be seen, running this:

class Foo(object):

    def __init__(self):

        pass





def f(t):

    print(type(t)) # <class 'type'>



f(Foo)