Как указать, что параметр представляет собой список определенных объектов в строках документации Python

Мне очень нравится использовать строки документации в Python для указания параметров типа, когда проекты выходят за рамки определенного размера.

У меня возникли проблемы с поиском стандарта для указания того, что параметр представляет собой список определенных объектов, например. в типах Haskell я бы использовал [String] или [A].

Текущий стандарт (распознаваемый редактором PyCharm):

def stringify(listOfObjects):
    """
    :type listOfObjects: list
    """
    return ", ".join(map(str, listOfObjects))

Что бы я предпочел:

ВАРИАНТ 1

def stringify(listOfObjects):
    """
    :type listOfObjects: list<Object>  
    """
    return ", ".join(map(str, listOfObjects))

ВАРИАНТ 2

def stringify(listOfObjects):
    """
    :type listOfObjects: [Object]
    """
    return ", ".join(map(str, listOfObjects))

Я полагаю, что это был не очень хороший пример - более подходящим вариантом использования был бы тот, где объекты в списке должны быть определенного типа.

ЛУЧШИЙ ПРИМЕР

class Food(Object):
    def __init__(self, calories):
        self.calories = calories

class Apple(Food):
    def __init__(self):
        super(self, 200)

class Person(Object):
    energy = 0
    def eat(foods):
        """
        :type foods: [Food]  # is NOT recognised by editor
        """
        for food in foods:
            energy += food.calories

Таким образом, помимо того факта, что я проголодался, этот пример иллюстрирует, что если вызвать его со списком объектов неправильного типа, код сломается. Отсюда важность документирования не только того, что ему нужен список, но и того, что ему нужен список продуктов питания.

СВЯЗАННЫЙ ВОПРОС Как я могу сообщить PyCharm, какого типа должен быть параметр? Обратите внимание, что я ищу более конкретный ответ, чем приведенный выше.


python pycharm
person Alex    schedule 24.07.2013    source источник
comment
Вы проверили PEP на веб-сайте python?   -  person Jiminion    schedule 24.07.2013
comment
Я не нашел такой, но мог пропустить   -  person Alex    schedule 24.07.2013
comment
Возможный дубликат stackoverflow.com/questions/24853923/ (где я узнал о модуле typing Python 3.5).   -  person Noumenon    schedule 13.06.2016

Ответы (4)


arrow_upward
60
arrow_downward

В разделе комментариев руководства по PyCharm есть хороший совет от разработчика:

#: :type: dict of (str, C)
#: :type: list of str

Это работает для меня довольно хорошо. Теперь мне интересно, как лучше всего документировать параметризованные классы в Python :).

person Michael Korbakov    schedule 22.10.2013
comment
Этот ответ сейчас устарел с созданием PEP 484 в конце 2014 г. , Но это был хороший ответ в то время! :-) - person Jason; 18.08.2016
comment
Примечание. Ответ устарел только для Python 3.5 и выше. - person André C. Andersen; 08.01.2017

arrow_upward
10
arrow_downward

Как указано в документах PyCharm, (устаревший, до PEP-484) способ для этого используются квадратные скобки:

list[Foo]: Список элементов Foo

dict[Foo, Bar]: Dict от Foo до Bar

list of str, как предлагается в принятом ответе, не работает в PyCharm должным образом.

Начиная с Python 3.5 и реализации PEP-484, вы также можете использовать подсказки типов, которые могут хорошо поддерживаться вашей IDE/редактором. Как это легко сделать в PyCharm, объясняется здесь.

По сути, чтобы объявить тип возвращаемого списка с помощью подсказки типа (Python ›=3.5), вы можете сделать что-то вроде этого:

from typing import List

"""
Great foo function.

:rtype: list[str]
"""
def foo() -> List[str]:
    return ['some string', 'some other string']

Здесь мы объявляем (несколько избыточно), что функция foo возвращает список строк, как в подсказке типа -> List[str], так и в строке документации :rtype: list[str].

Другие предварительно объявленные типы и дополнительную информацию можно найти в документации по Python для набора текста. .

person Hendrik    schedule 15.05.2019

arrow_upward
3
arrow_downward

в питоне

type([1,2,3]) == type(['a', 'b', 'c'])

вы также можете добавить строку в список целых чисел.

Итак, для того, чего вы пытаетесь достичь, PyCharm должен волшебным образом проверить весь ваш код на предмет того, что вы добавляете в список, прежде чем передавать его в качестве аргумента.

Вы можете взглянуть на этот вопрос Python: определите список объектов определенного типа

Однако модуль массива допускает только «базовые значения».

Единственное решение, которое я могу здесь придумать, - это создать свой собственный класс, который расширяет список python «FoodsList», который может проверять тип перед добавлением элемента.

class Food():
    def __init__(self, calories):
        self.calories = calories

class FoodsList(list):
    #you can optionally extend append method here to validate type
    pass

def eat(foods):
    """
    :type foods: FoodsList
    """
    energy = 0
    for food in foods:
        energy += food.calories
    return energy


list = FoodsList()
list.append(Food(3))
list.append(Food(4))
print eat(list)
person fsw    schedule 24.07.2013
comment
+1: это решает проблему гораздо лучше, чем я надеялся :) хорошее понимание - person Alex; 24.07.2013
comment
хотя я подозреваю, что PyCharm вполне способен «волшебным образом» проверять весь мой код, чтобы увидеть, что я добавляю в список — это то, для чего он предназначен :) - person Alex; 24.07.2013

arrow_upward
1
arrow_downward

При написании строк документации в стиле Google вы можете:

class ToDocument(object):
    """This is my Documentation.

    Args:
        typed_list (:obj:`list` of :obj:`str`): Description of typed list

    """
    ...

Это также отлично работает в sphinx в сочетании с расширением napoleon. Дополнительные примеры документации см. в документе расширения.

person Kim    schedule 27.01.2017