Как мне указать входные и выходные типы данных в комментариях Python? - PullRequest
Новая
       22

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

13 голосов
/ 28 января 2009

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

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

Ответы [ 3 ]

17 голосов
/ 28 января 2009

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

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

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 . Он может генерировать документацию в различных форматах и ​​создавать хорошие графики из ваших классов и профилей вызовов.

8 голосов
/ 28 января 2009

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

  • Epytext.

  • ReStructuredText, RST.

  • нотация JavaDoc, которая выглядит как эпитекст.

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

Пример. 

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 неправильно показывает подсказки типов

...