Какой тип параметра является абстрактным именем класса в строках документации Python?

Question

РЕДАКТИРОВАНИЕ: Допустим, у меня есть некоторые классы, которые наследуются от абстрактного класса SuperFoo:

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

И документированная функция, которая принимает подкласс SuperFoo какпараметр:

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)

Что @type следует использовать в строке документации функции?Это не может быть SuperFoo, потому что это соответствует экземпляру SuperFoo, а не самому типу.

Answer 1

Простой технический ответ уже был опубликован motyzk - в вашем примере, то, что вы передаете build, являются классами, так что (плохо названный) параметр class_name имеет тип type - с ограничением, что(на основе вашего фрагмента кода) этот класс не должен ожидать какого-либо параметра, который не соответствует ни одному однозначно определенному существующему встроенному «типу».

Теперь, как уже упоминалось в комментариях, в Python

• все является объектом (и, как таковым, экземпляром класса),
• создание экземпляра класса выполняетсявызывая объект класса точно так же, как вы вызываете любую функцию,
• все вызываемые объекты возвращают объект, даже если он неявно (None тоже объект)

так что ваш *Функция 1017 * технически будет работать точно так же, как и для любого вызываемого, который не ожидает param.Например, это:

def bar():
   return

whatever = build(bar)

технически правильно.

Теперь вы упоминаете в строке документации функции (выделено мое):

Создание экземпляра класса и делать другие вещи

Поскольку ваша функция была бы просто бесполезна, как показано в фрагменте, который вы разместили, я предполагаю, что в вашем реальном кодеважная часть находится в (не показано) «делать какие-то другие вещи», и эта часть «делать какие-то другие вещи» зависит от определенного свойства передаваемого класса.

В этом случае вам следует задокументировать эти особенности либо неформально (текстуально, в самой строке документа), либо формально, используя abc модуль .Это на самом деле не решит ваш вопрос - ваша функция ожидает класс, а не экземпляр, поэтому теоретически @type должен быть type(YourABC), но тогда вы получите abc.ABCMeta.На этом этапе вам нужно либо написать собственный метакласс (наследующий от abc.ABCMeta) и указать его как правильный @type - но это не скажет ничего полезного в отношении документации, - или просто описать его как "подкласс MyABC "(это правильное описание, но его нельзя использовать для инструментария кода).

Answer 2

Тип "тип", как видно, работает так:

class Foo(object):
    def __init__(self):
        pass


def f(t):
    print(type(t)) # <class 'type'>

f(Foo)