python - nomenclatura - Herramienta para comprobar automáticamente el estilo de la cadena de documentos según PEP257

python 3 docstring example

Question

Las herramientas como pep8 pueden verificar el estilo del código fuente, pero no comprueban si las cadenas de documentación están configuradas de acuerdo con pep257 , pep287 . ¿Hay tales herramientas?

Actualizar

Decidí implementar una herramienta de análisis estático por mi cuenta, ver:

https://github.com/GreenSteam/pep257

En este momento, la mayor parte de pep257 está cubierta. El diseño fue fuertemente influenciado por la mencionada herramienta pep8 .

Answer 1

No conozco ninguna herramienta de análisis estático para cadenas de documentos de Python. De hecho, empecé a construir uno poco después de comenzar con PyLint, pero me di por vencido rápidamente.

PyLint tiene un sistema de complementos y un complemento de cadena de documentos es factible si desea poner el trabajo para hacer que los PEP sean ejecutables.

Los "complementos" de PyLint se denominan comprobadores y vienen en dos formas: los que trabajan con el archivo fuente como un documento de texto sin formato y los que trabajan con él como un AST. Hice mi intento a partir de la AST. Esto puede haber sido un error en retrospectiva.

Esto es lo que tuve:

class DocStringChecker(BaseChecker):
    """
    PyLint AST based checker to eval compliance with PEP 257-ish conventions.
    """
    __implements__ = IASTNGChecker

    name = ''doc_string_checker''
    priority = -1
    msgs = {''W9001'': (''One line doc string on >1 lines'',
                     (''Used when a short doc string is on multiple lines'')),
            ''W9002'': (''Doc string does not end with "." period'',
                     (''Used when a doc string does not end with a period'')),
            ''W9003'': (''Not all args mentioned in doc string'',
                     (''Used when not all arguments are in the doc string '')),
            ''W9004'': (''triple quotes'',
                     (''Used when doc string does not use """'')),
           }
    options = ()

    def visit_function(self, node):
        if node.doc: self._check_doc_string(node)

    def visit_module(self, node):
        if node.doc: self._check_doc_string(node)

    def visit_class(self, node):
        if node.doc: self._check_doc_string(node)

    def _check_doc_string(self, node):
        self.one_line_one_one_line(node)
        self.has_period(node)
        self.all_args_in_doc(node)

    def one_line_one_one_line(self,node):
        """One line docs (len < 80) are on one line"""
        doc = node.doc
        if len(doc) > 80: return True
        elif sum(doc.find(nl) for nl in (''/n'', ''/r'', ''/n/r'')) == -3: return True
        else:
            self.add_message(''W9001'', node=node, line=node.tolineno)

    def has_period(self,node):
        """Doc ends in a period"""
        if not node.doc.strip().endswith(''.''):
            self.add_message(''W9002'', node=node, line=node.tolineno)

    def all_args_in_doc(self,node):
        """All function arguments are mentioned in doc"""
        if not hasattr(node, ''argnames''): return True
        for arg in node.argnames:
            if arg != ''self'' and arg in node.doc: continue
            else: break
        else: return True
        self.add_message(''W9003'', node=node, line=node.tolineno)

    def triple_quotes(self,node): #This would need a raw checker to work b/c the AST doesn''t use """
        """Doc string uses tripple quotes"""
        doc = node.doc.strip()
        if doc.endswith(''"""'') and doc.startswith(''"""''): return True
        else: self.add_message(''W9004'', node=node, line=node.tolineno)


def register(linter):
    """required method to auto register this checker"""
    linter.register_checker(DocStringChecker(linter))

Como recuerdo, este sistema no tiene grandes documentos (que pueden haber cambiado en el último año). Esto al menos le da algo para comenzar a piratear código realmente simple en lugar de documentos.

Answer 2

No creo que se esté validando con ningún PEP, pero Epydoc comprobará que todos los parámetros y objetos a los que se hace referencia en docstrmap tengan parámetros y objetos válidos.