¿Cómo puedo hacer objeto de documento Python / Sphinx solamente atributos declarados en __init__?
-
08-10-2019 - |
Pregunta
Tengo clases de Python con atributos de los objetos que se declaran sólo como parte de la ejecución del constructor, así:
class Foo(object):
def __init__(self, base):
self.basepath = base
temp = []
for run in os.listdir(self.basepath):
if self.foo(run):
temp.append(run)
self.availableruns = tuple(sorted(temp))
Si ahora el uso de cualquiera help(Foo)
o intento de documentar Foo
en Sphinx, los atributos y self.basepath
self.availableruns
no se muestran. Eso es un problema para los usuarios de nuestra API.
He intentado buscar una forma estándar para asegurar que estos atributos declarados "dinámica" se pueden encontrar (y preferiblemente docstring'd) por el analizador, pero sin suerte hasta ahora. ¿Alguna sugerencia? Gracias.
Solución
Se podría definir una variable de clase con el mismo nombre que la variable de instancia. Esa variable de clase será entonces ensombrecido por la variable de instancia cuando la coloque. Por ejemplo:
class Foo(object):
#: Doc comment for availableruns
availableruns = ()
def __init__(self, base):
...
self.availableruns = tuple(sorted(temp))
En efecto, si la variable de instancia tiene una utilidad inmutable valor por defecto (por ejemplo Ninguno o la tupla vacío), entonces se puede ahorrar un poco de memoria por no establecer la variable si debe tener su valor por defecto . Por supuesto, este método no funcionará si estamos hablando de una variable de instancia que es posible que desee eliminar (por ejemplo, del foo.availableruns
) -. Pero me parece que no es un caso muy común
Si está utilizando esfinge, y han establecido "autoattribute", entonces esto debe conseguir documentado apropiadamente. O, dependiendo del contexto de lo que está haciendo, usted podría utilizar directamente la Directiva .. py:attribute::
Esfinge.
Otros consejos
He intentado buscar una forma estándar para asegurar que estos atributos declarados "dinámica" se pueden encontrar (y preferiblemente docstring'd) por el analizador, pero sin suerte hasta ahora. ¿Alguna sugerencia?
No pueden nunca ser "detectado" por cualquier analizador.
Python tiene setattr
. El conjunto completo de atributos no es "detectable", en ningún sentido de la palabra.
Es absolutamente necesario describirlos en la cadena de documentación.
[A menos que usted quiere hacer un montón de meta-programación para generar cadenas de documentación de cosas que se reunieron a partir inspect
o algo así. Incluso entonces, su "solución" no estaría completo tan pronto como empezar a usar setattr
.]
class Foo(object):
"""
:ivar basepath:
:ivar availableruns:
"""
def __init__(self, base):