Python. Можно ли записать строку документации? Это кажется - PullRequest
Новая
       21

Python. Можно ли записать строку документации? Это кажется

1 голос
/ 08 апреля 2020

TL; DR Является ли строка документа предполагаемой доступной для записи так же просто, как 

x.__doc__ = 'string' ?

Кажется, работает в 3.5.2.

Я написал функцию для взятия и проверки GUI клавиатурных вводов. Это здесь на Code Review, если кому-то нужны подробности.

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

Это пример, 'пара из функции проверки поплавков, кодирование подсказок помощи в строку документации довольно очевидно. 

def float_pair(in_str):
    """[f,f] Two floats separated by a comma
    [end_help]
    in_str     input string which should represent float, float
    raise      ValueError if that's not true
    return     a list of the two values
    """
    fields = in_str.split(',')
    if len(fields) != 2:
        raise ValueError('need two floats separated by one comma')
    output = [float(f) for f in fields]  
    return output

Теперь я хочу добавить возможность проверять, находится ли поплавок в определенном диапазоне, в идеале, проходя этот диапазон. на проверку функции фабрики. В идеале строка документации возвращаемой функции должна содержать диапазон, так что помощь, которую дает GUI, актуальна. Поэтому мне нужно установить строку документации во время выполнения.

Множество поисков привели меня в замешательство относительно того, должна ли строка документации быть доступной для записи или нет. Я видел этот вопрос. К сожалению, я всего лишь физик, ставший программистом, а не опытный метапрограммист, поэтому я не понимаю тонкостей.

Так что я попробовал это самым простым способом, и, кажется, работает, по крайней мере, на python 3.5.2. Я собираюсь обновить версию в конце концов, если не больше, чем f строк. Меня беспокоит, будет ли он продолжать работать в будущих выпусках или будет «исправлено» только для чтения. 

def float_range_factory(x, y):
    def float_range(z):
        fz = float(z)
        if x<=fz<y:
            return fz
        raise ValueError('input {} must be in the interval [{}, {}]'.format(z, x, y))
    float_range.__doc__ = '[f range] Return float in the interval [{}, {}]'.format(x, y)
    return float_range

1 Ответ

2 голосов
/ 08 апреля 2020

Модуль functools в стандартной библиотеке предоставляет пример прямого присвоения __doc__: 

class cached_property:
    def __init__(self, func):
        self.func = func
        self.attrname = None
        <b>self.__doc__ = func.__doc__</b>
        self.lock = RLock()

    [...]

Обратите внимание, что атрибут __doc__ явно устанавливается только из строки документации во время компиляции; Я пробовал что-то вроде 

def foo(x):
    def bar():
        f"""Return {x}"""
        return x
    return bar

, но foo(3).__doc__ - это None, как будто в определении bar.

не было строки документации.
...