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

Я видел несколько стандартов для написания комментариев о том, какие данные функция рассчитывает и возвращает в Python. Существует ли консенсус в отношении того, какая из них является наилучшей практикой?

новая функциональность в http://www.python.org/dev/peps/pep-3107/ что-то, что я должен начать использовать для этого?

13
comments documentation python types

3 ответов

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

инструменты могут быть написаны для извлечения информации из аннотаций и делать все, что вы хотите, включая проверку типов или создание документации. Но сам 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"}

предложения варианта использования, предоставляемые ОПТОСОЗ:

  • предоставление информации о наборе текста
    • тип проверки
    • пусть IDEs показывает, какие типы функция ожидает и возвращает
    • перегрузка функций / общие функции
    • на иностранных языках мосты!--17-->
    • адаптация
    • логические функции предиката
    • отображение запросов к базе данных
    • маршалинг параметров 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's 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. Он может создавать документацию в различных форматах и создавать хорошие графики из ваших классов и профилей вызовов.

17

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

  • Epytext.

  • ReStructuredText, RST.

  • javadoc нотация, которая выглядит немного как epytext.

Я рекомендую сначала, потому что он хорошо работает с сфинкс для создания общего пакета документации, который включает ссылки на API. Первая разметка определена здесь. Различные поля 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
7

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, но это обновление языка дает официальный канонический способ, который, вероятно, будет преобладать.

2