Strumento per controllare automaticamente lo stile docstring in base a PEP257

Question

Strumenti come pep8 possono controllare lo stile del codice sorgente, ma non controllano se le didascalie sono formattate in base a pep257, pep287. Ci sono questi strumenti?

Aggiornamento

ho deciso di implementare un tale strumento di analisi statica per conto mio, vedi:

https://github.com/GreenSteam/pep257

In questo momento, la maggior parte di pep257 è coperto. Il design è stato fortemente influenzato dallo strumento pep8 menzionato.

Answer 1

Non conosco alcuno strumento di analisi statica per le stringhe di Python doc. In realtà ho iniziato a crearne uno poco dopo aver iniziato con PyLint, ma presto ho rinunciato.

PyLint ha un sistema di plugin e un plugin di stringa doc è fattibile se si desidera inserire il lavoro per rendere eseguibile il PEP.

I "plug-in" PyLint sono chiamati checker e sono disponibili in due forme: quelli che lavorano con il file di origine come documento di testo non elaborato e quelli che lavorano con esso come AST. Ho fatto il mio tentativo partendo dall'AST. Questo potrebbe essere stato un errore in retrospettiva.

Ecco quello che avevo:

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)) 

Se non ricordo male questo sistema non ha grandi documenti (che potrebbe essere cambiato nel corso dell'anno passato). Questo almeno ti dà qualcosa per iniziare a fare hacking su/codice veramente semplice al posto dei documenti.

Answer 2

Non credo che convalidi alcun PEP, ma Epydoc controllerà che tutti i parametri e gli oggetti di riferimento in docstrmap siano validi per parametri e oggetti.