Передача docstrings для определенных функций python

Question

У меня есть общий формат docstrings, который я пытаюсь выполнить, когда я выполняю функции. Я даю краткое описание того, что функция выполняет за короткое объяснение того, какой класс требуется для ввода и какого класса он выводит.

def cuberoot4u(number): 
    """Returns the cube root of number. 

    cuberoot4u(float) -> float 

    """ 
    return pow(number, 1/3) 

В этом случае cuberoot4u принимает поплавок для ввода и возвращает поплавок для вывода.

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

def getText(filename): 
    """Reads the file filename and returns the content. 

    getText(?????) -> str 
    """ 
    fd = open(filename) 
    text = fd.read() 
    fd.close() 
    return text 

Было бы лучше сказать getText(filename.txt) -> str или есть определенное имя класса для этого так же, как струны «ул» и целое число «INT»?

Кроме того, что о для функций, выходы которых четко не определены как в этом примере:

def commandmenu(): 
    """Begin some random menu which does stuff. 

    commandmenu() -> ?????? 
    """ 


    while 1: 
     someuserinput = input("Enter a command: ") 
     if someuserinput == 'this': 
      pass 
     elif someuserinput == 'that': 
      pass 
     else: 
      print('u suck') 
    return None 

Таким образом, в этом случае нет начальных выходного от входа в функции, поскольку это приводит к входу от пользователя прежде чем он что-то сделает. Что лучше всего подойдет ??? если такая функция становится все более и более подобной и может привести к нескольким различным выходам в зависимости от подсказок пользователю и т. д.?

Answer 1

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

Рассмотрит функцию, аналогичную вашей первый, но вычисление квадратного корня:

def squareroot4u(number): 
    """Returns the cube root of number. 

    squareroot4u(float) -> float 

    """ 
    return pow(number, 1/2) 

Очевидно, что тип возвращаемого значение float только если number неотрицательно, в противном случае она должна быть complex. Python (в отличие от некоторых научно-ориентированных языков) не имеет отдельного типа для неотрицательных чисел, так что вы должны дополнительно указать contract, что претворяет его:

def squareroot4u(number): 
    """Returns the cube root of number. 

    squareroot4u(number: float) -> float 

    precondition: number >= 0 
    raises ValueError otherwise 
    """ 
    return pow(number, 1/2) 

Я лично использую Sphinx для документирования и в его формат это будет выглядеть

def squareroot4u(number): 
    """Returns the cube root of number. 

    :param number: a non-negative number, raises ``ValueError`` otherwise 
    :type number: ``float`` 
    :return: square root of the input 
    :rtype: ``float`` 
    """ 
    return pow(number, 1/2) 

Для вашей второй функции:

def getText(filename): 
    """Reads the file filename and returns the content. 

    :param filename: a path to a text file 
        (raises ``WhateverError``/blows ups the monitor otherwise) 
    :type filename: ``str`` 
    :returns: file contents 
    :rtype: ``str`` 
    """ 

Обратите внимание, что типы в Python docstrings часто опускаются, когда их можно вывести из контекста (например, что еще кроме str может filename быть?)

Теперь с третьей функции, в дополнение к типам и контрактов, у вас есть побочные эффекты. Они должны быть задокументированы в общем описании функции (если они являются основным моментом для запуска этой функции) или в примечании/предупреждении (если это что-то, что нужно иметь в виду).Так, например (с использованием синтаксиса Sphinx снова):

def commandmenu(): 
    """Begin some random menu which does stuff. 
    Shows an input prompt and awaits user input. 

    .. warning:: 

     May or may not randomly format your hard drive during full moon. 
    """ 

на других языках (например, в Haskell), некоторые побочные эффекты могут быть представлены в виде типов (монады) и статический проверяются. Например, есть аналогичная функция для вашего getText в стандартной библиотеке, которая имеет типа

readFile :: FilePath -> IO String 

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