9

I have a python file that has raw strings as the docstrings.

def a():
    '\n\tthis\n\tis\n\tthe docstring.\n\t'
    print 'hello world'

how would I rewrite the docstring to look like

def a():
    """
    this
    is
    the docstring.
    """
    print 'hello world'
Tom Zych
  • 13,329
  • 9
  • 36
  • 53
baallezx
  • 471
  • 3
  • 14
  • 10
    This makes me wonder how the docstring got written like that in the first place. It seems that it would be better to fix this at the source (as I don't know any humans who write docstrings that way ;-) – mgilson Jul 15 '14 at 20:42
  • 2
    after an `ast.NodeTransform` and I can't get the code generator to write it in the pretty format without rewriting all strings. – baallezx Jul 15 '14 at 20:45
  • 1
    What exactly do you mean by pretty print? Obviously interpret escape sequences, but also indentation, word wrapping, conformance to [PEP 257](http://legacy.python.org/dev/peps/pep-0257/), ...? If so, please *list* your requirements for that transformation explicitely. – Lukas Graf Jul 15 '14 at 20:46
  • 7
    @baallezx if you have code, provide a [minimal example](http://stackoverflow.com/help/mcve) and the output – jonrsharpe Jul 15 '14 at 20:47
  • Which python version are you using? My *guess* is that in python2 you probably want `the_docstring.decode('string-escape')` and you want `the_docstring.encode('utf-8').decode('unicode-escape')` in python3. – Bakuriu Jul 15 '14 at 21:01
  • @jonrsharpe - do you mean a minimal example of the the codegenerator or the ast.NodeTransformer? Because if you mean a minimal example of what my code looks like after the transform and code generation the first example above is a good example for the output file I am getting. Plus the code generator I am using is from the `astor` library with the codegen.to_source(curr_ast) call. – baallezx Jul 15 '14 at 21:03
  • Is there nothing available to the NodeTransformer that gives you the original string style? – user2357112 Jul 15 '14 at 22:21
  • @user2357112 the `ast` has Str nodes that contain the string for the node. But it does not have an option for an original string style. Unless I am missing something. – baallezx Jul 15 '14 at 22:39
  • Does [`ast.get_docstring()`](https://docs.python.org/2/library/ast.html#ast.get_docstring) help? – user2357112 Jul 15 '14 at 22:44
  • @user2357112 - it really doesn't specifically help this is more of a code generator issue. But at least I can use that function to differentiate the strings from the docstrings. – baallezx Jul 15 '14 at 22:58
  • Looks like you've already submitted an issue on Github. I hope it gets addressed. If you end up writing something to do it, you might want to submit a pull request. – user2357112 Jul 15 '14 at 23:00

3 Answers3

2

Here's an example using the inspect.getsoucelines and some regex:

import inspect
import re

def update_doc(func, indent='    '):
    sourcelines = inspect.getsourcelines(func)[0]
    doc = func.__doc__
    if doc is not None:
        ind = [line.decode('string_escape').strip()[1:-1] 
                                                 for line in sourcelines].index(doc)
        sourcelines[ind] = '{}"""{}"""\n'.format(indent, 
                                           re.sub(r'\n([ \t]+)', r'\n'+indent, doc))
    return ''.join(sourcelines)

Demo:

def a():
    '\n\tthis\n\tis\n\tthe docstring.\n\t'
    print 'hello world'
print update_doc(a)

def b():
    '\n    This is\n    not so lengthy\n    docstring\n    '
    print 'hmm...'
print update_doc(b)

Output:

def a():
    """
    this
    is
    the docstring.
    """
    print 'hello world'

def b():
    """
    This is
    not so lengthy
    docstring
    """
    print 'hmm...'

P.S: I have not tested it thoroughly yet, but this should get you started.

Ashwini Chaudhary
  • 244,495
  • 58
  • 464
  • 504
  • But how could I use this to actually rewrite a file? Add this function to every file and call this method after each function, then use something like sed to capture the output and save it to a new file. – baallezx Jul 15 '14 at 22:35
1

Pyment allows to create, harmonize and convert docstrings.

It can't currently propose to expand raw description as \n, but it could be easy to add this functionality. You can open an issue to request it.

daouzli
  • 15,288
  • 1
  • 18
  • 17
1

I was searching google but it turns out you can just call the vanilla print function to print some docs like my sklearn support vector classifier, like this: print doc pretty

siminsimin
  • 301
  • 2
  • 6