Ersetzen Python Docstrings

Question

Ich habe einen epytext zu reST Markup-Konverter geschrieben, und jetzt möchte ich alle Docstrings in meiner gesamten Bibliothek von Epytext in ReST-Format konvertieren.

Gibt es eine intelligente Möglichkeit, alle Docstrings in einem Modul zu lesen und die Ersetzungen zurückzuschreiben?

ps: ast modul vielleicht?

Answer 1

Wahrscheinlich die einfachste, es auf die altmodische Weise zu tun. Hier ist ein erster Code, der Sie zum Laufen bringt. Es könnte wohl schöner sein, sollte aber die Grundidee geben:

def is_docstr_bound(line): 
    return "'''" in line or '"""' in line 

# XXX: output using the same name to some other folder 
output = open('output.py', 'w') 

docstr_found = False 
docstr = list() 
with open('input.py') as f: 
    for line in f.readlines(): 
     if docstr_found: 
      if is_docstr_bound(line): 
       # XXX: do conversion now 
       # ... 

       # and write to output 
       output.write(''.join(docstr)) 

       output.write(line) 

       docstr = list() 
       docstr_found = False 
      else: 
       docstr.append(line) 
     else: 
      if is_docstr_bound(line): 
       docstr_found = True 

      output.write(line) 

output.close() 

Um es wirklich funktionierenden Sie es mit einem Datei-Finder und geben die Dateien in ein anderes Verzeichnis Haken müssen auf. Überprüfen Sie das os.path Modul als Referenz.

Ich weiß, dass die Docstring gebundene Prüfung potenziell sehr schwach ist. Es ist wahrscheinlich eine gute Idee, es ein wenig aufzurüsten (strip line und überprüfen, ob es beginnt oder endet mit einem Docstring gebunden).

Hoffentlich gibt das eine Idee, wie man möglicherweise fortfahren kann. Vielleicht gibt es eine elegantere Art, mit dem Problem umzugehen. :)

Answer 2

Ich wundere mich über eine Kombination von Introspektion und Quellenverarbeitung. Hier einige ungetestete Pseudo-Code:

import foo #where foo is your module 

with open('foo.py',r) as f: 
    src = f.readlines() 

for pything in dir(foo): #probably better ways to do this... 
    try: 
     docstring = pything.__doc__ 
    except AttributeError: 
     #no docstring here 
     pass 

    #modify the docstring 
    new_docstring = my_format_changer(docstring) 

    #now replace it in the source 
    src = src.replace(docstring, new_docstring) 

#When done, write it out 
with open('new_foo.py','w') as fout: 
    fout.write(src) 

Offensichtlich würden Sie etwas Klugheit im Code setzen müssen, die das Modul für Objekte suchen quert die Docstrings haben, so wäre es Rekursion, aber das gibt Ihnen die allgemeine Idee.

Answer 3

Es könnte ein Overkill für diese einfache Verwendung sein, aber ich würde in die Verwendung der Maschinerie von 2to3, um die Bearbeitung zu tun. Sie müssen nur einen benutzerdefinierten Fixer schreiben. Es ist nicht gut dokumentiert, aber Entwicklerhandbuch zu Python 3.0: Python 2.6 und Migration von 2 bis 3: More about 2to3 und Implement Custom Fixers gibt detailliert genug, um loszulegen ...

Epydoc scheint ein to_rst() Verfahren zu enthalten, die helfen könnten Sie übersetzen tatsächlich die Docstrings. Weiß nicht, ob es gut ist ...

Answer 4

Pyment ist ein Werkzeug, das Python-Docstrings konvertieren und fehlende Skelette erstellen kann. Es kann Google, Epydoc (javadoc-Stil), Numpydoc, reStructuredText (reST, Sphinx Standard) docstring Formate verwalten.

Es akzeptiert eine einzelne Datei oder einen Ordner (Erkundung auch Unterordner). Für jede Datei erkennt sie jedes Docstring-Format und konvertiert es in das gewünschte Format. Am Ende wird ein Patch erstellt, der auf die Datei angewendet wird.

Ihr Projekt konvertieren:

• Pyment installieren

Geben Sie den folgenden (Sie virtualenv verwenden):

$ git clone https://github.com/dadadel/pyment.git 
$ cd pyment 
$ python setup.py install 

• convert von Epydoc zu Sphinx

Sie können Ihr Projekt Sphinx-Format (reST) umwandeln, die das Standardausgabeformat ist, indem:

$ pyment /my/folder/project