Estoy escribiendo una clase ligera cuyos atributos están destinados a ser de acceso público y solo a veces se anulan en instancias específicas. No hay ninguna disposición en el lenguaje Python para crear cadenas de documentos para atributos de clase, o cualquier tipo de atributos, para el caso. ¿Cuál es la forma esperada y admitida, debería haber una, de documentar estos atributos? Actualmente estoy haciendo este tipo de cosas:
class Albatross(object):
"""A bird with a flight speed exceeding that of an unladen swallow.
Attributes:
"""
flight_speed = 691
__doc__ += """
flight_speed (691)
The maximum speed that such a bird can attain.
"""
nesting_grounds = "Raymond Luxury-Yacht"
__doc__ += """
nesting_grounds ("Raymond Luxury-Yacht")
The locale where these birds congregate to reproduce.
"""
def __init__(self, **keyargs):
"""Initialize the Albatross from the keyword arguments."""
self.__dict__.update(keyargs)
Esto dará como resultado que el docstring de la clase contenga la sección de docstring estándar inicial, así como las líneas agregadas para cada atributo mediante una asignación aumentada a __doc__
.
Aunque este estilo no parece estar expresamente prohibido en las pautas de estilo de la cadena de documentos , tampoco se menciona como una opción. La ventaja aquí es que proporciona una forma de documentar atributos junto con sus definiciones, al mismo tiempo que crea una cadena de documentos de clase presentable y evita tener que escribir comentarios que reiteran la información de la cadena de documentos. Todavía estoy un poco molesto por tener que escribir los atributos dos veces; Estoy considerando usar las representaciones de cadena de los valores en la cadena de documentos para al menos evitar la duplicación de los valores predeterminados.
¿Es esta una violación atroz de las convenciones comunitarias ad hoc? ¿Está bien? ¿Existe una forma mejor? Por ejemplo, es posible crear un diccionario que contenga valores y cadenas de documentos para los atributos y luego agregar el contenido a la clase __dict__
y la cadena de documentos hacia el final de la declaración de la clase; esto aliviaría la necesidad de escribir dos veces los nombres y valores de los atributos. editar : esta última idea, creo, no es realmente posible, al menos no sin construir dinámicamente toda la clase a partir de datos, lo que parece una muy mala idea a menos que haya alguna otra razón para hacerlo.
Soy bastante nuevo en Python y todavía estoy trabajando en los detalles del estilo de codificación, por lo que las críticas no relacionadas también son bienvenidas.
attribute doc string
mencionado en PEP 257 que no es muy conocido y parece difícil de encontrar que pueda responder a la pregunta de los OP, y es compatible con algunas herramientas de origen. Esta no es una opinión. Es un hecho, y parte del lenguaje, y casi exactamente lo que quiere el OP.