Properly document a constructor passed as parameter

Question

I'm trying to figure out what is the properly way to document a function that receives a class constructor as parameter . I'm using Google style docstring.

Example:

class MyClass:
    def __init__(self):
        ...

def my_func(param1, class_constructor):
"""Example function.

Args:
    param1 (int): ...
    class_constructor (???): My class constructor.
"""
    class_instance = class_constructor()
    ...

my_func(12, MyClass)

What's a "class constructor" in this context? Isn't it just a class? — Daniel Roseman, Oct 25 '17 at 14:17
Actually this should probably accept just any callable - no reason to restrict it to a `class` object (unless something else in the code requires it to be a class but that doesn't seem to be the case in the snippet). — bruno desthuilliers, Oct 25 '17 at 14:57

score 0 · Answer 1 · answered Oct 25 '17 at 14:38

0

If I understand correctly, you want to know with what to replace ??? in your example. As pointed out in the comments of the original question, your class_constructor argument should in fact be a class, so the appropriate type would be type (ignoring old style classes).

answered Oct 25 '17 at 14:38

Jens Petersen

349
1
4

1

Since the same code would work with just any callable and using either a plain function as a factory or a classmethod as an alternate constructor are common patterns, I'd document it as "a callable returning an object". – bruno desthuilliers Oct 25 '17 at 14:56
Any object with a `__call__` method is callable. There is a builtin called `callable` that checks for the existence of this method, but there is no overall type of that kind (correct me if I'm wrong). Callable objects can be functions, class instances and probably others I'm not thinking of right now. – Jens Petersen Oct 25 '17 at 15:58

Properly document a constructor passed as parameter

1 Answers1