Как указать типы ввода и вывода в комментариях python?

Ответ 1

Аннотации функций не предназначены для конкретного использования, они могут быть использованы для чего угодно.

Инструменты могут быть записаны для извлечения информации из аннотаций и делать все, что угодно, включая проверку типов или создание документации. Но сам python ничего не делает с информацией. Вы можете использовать совершенно другую цель, то есть предоставить функцию, которая будет вызываться по параметру, или объявить строку возможных возвращаемых значений.

Аннотации могут быть любыми объектами:

def somefunc(param1: "string annotation", 
             param2: 151631,  
             param3: any_object): -> "some information here":

и вы можете получить объекты, используя:

print (somefunc.func_annotations)
{'param1': "string annotation", 
 'param2': 151631,  
 'param3': <object any_object>,
 'return': "some information here"}

Использовать варианты предложений, предоставленные PEP:

• Предоставление информации о наборе текста
  • Проверка типов
  • Пусть IDE показывают, какие типы функция ожидает и возвращает
  • Перегрузка функций/общие функции
  • Мосты на иностранных языках
  • Адаптация
  • Предикатные логические функции
  • Отображение запросов базы данных
  • Маршрутизация параметров RPC
• Другая информация
  • Документация для параметров и возвращаемых значений

Поскольку синтаксис синтаксиса функции слишком велик, он действительно не используется для каких-либо производственных инструментов.

Я предлагаю использовать другие методы для документирования этого. Я использую epydoc для создания моей документации, и он может считывать информацию ввода параметров из docstrings:

def x_intercept(m, b):
    """
    Return the x intercept of the line M{y=m*x+b}.  The X{x intercept}
    of a line is the point at which it crosses the x axis (M{y=0}).

    This function can be used in conjuction with L{z_transform} to
    find an arbitrary function zeros.

    @type  m: number
    @param m: The slope of the line.
    @type  b: number
    @param b: The y intercept of the line.  The X{y intercept} of a
              line is the point at which it crosses the y axis (M{x=0}).
    @rtype:   number
    @return:  the x intercept of the line M{y=m*x+b}.
    """
    return -b/m

Этот пример из сайта epydoc. Он может генерировать документацию в различных форматах и ​​может генерировать хорошие графики из ваших классов и профили вызовов.

Ответ 2

Если вы используете epydoc для создания документации по API, у вас есть три варианта.

• Epytext.

• ReStructuredText, RST.

• Обозначение JavaDoc, которое немного напоминает epytext.

Я рекомендую RST, потому что он хорошо работает с sphinx для создания общего набора документации, который включает ссылки API. Разметка RST определена здесь. Различные поля epydoc, которые вы можете указать, определены здесь.

Пример.

def someFunction( arg1, arg2 ):
    """Returns the average of *two* (and only two) arguments.

    :param arg1: a numeric value
    :type arg1: **any** numeric type

    :param arg2: another numeric value
    :type arg2: **any** numeric type

    :return: mid-point (or arithmetic mean) between two values 
    :rtype: numeric type compatible with the args.
    """
    return (arg1+arg2)/2

Ответ 3

Python 3.5 официальный typing

https://docs.python.org/3/library/typing.html

Это обновление делает типы актуальной частью языка.

Пример:

#!/usr/bin/env python3

from typing import List

def f(x: int, ys: List[float]) -> str:
    return "abc"

# Good.
f(1, [2.0, 3.0])

# Bad.
f("abc", {}) # line 12

x = 1
x = "a" # line 15

y = [] # type: List[int]
y.append("a") # line 18

Этот код работает нормально: Python 3.5 по умолчанию не вводит типизацию.

Однако он может использоваться статическими линтерами для диагностики проблем, например:

sudo pip3 install mypy
mypy a.py

дает:

a.py:12: error: Argument 1 to "f" has incompatible type "str"; expected "int"
a.py:12: error: Argument 2 to "f" has incompatible type Dict[<nothing>, <nothing>]; expected List[float]
a.py:15: error: Incompatible types in assignment (expression has type "str", variable has type "int")
a.py:18: error: Argument 1 to "append" of "list" has incompatible type "str"; expected "int"

Существующие статические анализаторы, такие как Pycharm, уже могут анализировать типы документации Sphinx, но это обновление языка дает официальный канонический способ, который, вероятно, будет преобладать.

Sphinx 1.8.2, похоже, пока не поддерживает его, но это только вопрос времени: Python 3: Sphinx неправильно показывает подсказки типов