Supongamos que tengo una función con una cadena de documentación donde declaro el tipo de retorno como una tupla con dos cadenas:

def foo():
    """
    Returns:
        Tuple[str, str]: Tuple of first name and last name
    """

¿Se supone que debo importar Tuple desde typing si no lo uso en ningún lugar excepto en las cadenas de documentos?

3
damd 16 oct. 2018 a las 15:43

2 respuestas

La mejor respuesta

El soporte de docstring de PyCharm para sugerencias de tipo en realidad no utiliza typing. No necesita importar el módulo.

El módulo typing solo está ahí para respaldar el hecho de que las anotaciones se ejecutan en tiempo de ejecución; para una declaración que comience con def foo() -> Tuple[str, str]:, Python realmente evaluará la expresión Tuple[str, str], por lo que espera poder resolver los nombres. (A partir de Python 3.7 puede deshabilitar (o más bien, posponer ) la evaluación con from __future__ import annotations).

Pero una cadena de documentación no se evalúa, normalmente, y no se espera que pueda contener código Python ejecutable.

A menos que tenga un requisito difícil de poner la información de tipo en la cadena de documentación, me quedaré con anotaciones reales :

from typing import Tuple


# type aliases
firstname = str
lastname = str


def foo() -> Tuple[firstname, lastname]:
    """Descriptive line documenting this function's purpose"""
    # ...
1
Martijn Pieters 16 oct. 2018 a las 13:41

Usted no Las cadenas de documentos son solo comentarios. Son ignorados por el intérprete. Por lo tanto, no lo importe, de lo contrario, las herramientas de comprobación de código (por ejemplo, pylint) se quejarán de las importaciones no utilizadas.

Sin embargo, probablemente sería mejor usar backticks dentro de su cadena de documentación para las partes que son código real. p.ej

"""
Returns:
    `Tuple[str, str]`: Tuple of first name and last name
"""

De esa manera, las herramientas de generación de documentos saben que es un código real y pueden formatearlo correctamente.

0
blue_note 16 oct. 2018 a las 12:50