docpicture

Tue Oct 14 12:23:31 EDT 2008

On Oct 14, 10:58 am, Steven D'Aprano <st... at REMOVE-THIS-
cybersource.com.au> wrote:
> On Tue, 14 Oct 2008 06:12:59 -0700, Scott David Daniels wrote:
> > Steven D'Aprano wrote:
> >> And if not, it's no big deal. Your help string has a clearly labeled
> >> few lines of hex:
>
> >> Help on function spam:
>
> >> spam(...)
> >>     spam spam spam spam spam spam
> >>     spam spam spam spam with a fried egg on top
>
> >>     === begin docpicture ===
> >>     1234567890ABCDEF...
> >>     === end docpicture ===
> >> Or similar. I'm sure people will cope, especially since it should be
> >> relatively rare.
>
> > or you could even use:
> >        '''<docpicture name="fig1.png" code="base64" version="1">
> >        1234567890ABCDEF...
> >        </docpicture>'''
> > A comment _not_ a docstring (only found by scanning the source). which
> > is easy enough to hunt for.
>
> +1 for docpictures
>
> -1 for them being comments instead of docstrings. The whole point of
> having them is to allow Python tools to operate on them. I should be able
> to do this:
>
> >>> import docpicture
> >>> docpicture.gui(myfunction)
>
> and get a nice Tk window showing the picture. There's all sorts of
> functionality that you lose by making them comments and therefore
> unavailable to Python tools. (Okay, technically this hypothetical
> docpicture module could scan the source file -- assuming the source code
> is even available, which isn't always true.)
>
> But anyway, we're getting well ahead of ourselves here. Unless bearophile
> is willing to share his code, or somebody reverse engineers it, this is
> nothing more than vapourware.
>
> --
> Steven

Ok, the following is my first attempt at implementing this idea.
Of course, it could be improved by using reStructuredText in
the docstring and docutils to format it...

'''Experimental function allowing to view docstrings with embedded
images.  The images are encoded in base 64.

(c) Andre Roberge
License: Adapt as you please, but preferably give credit to original
author (and any subsequent contributor).
'''

import base64
import os
import re
import sys
import webbrowser

html_template = "<html><head></head><body>%s</body>"
def docpicture_view(function):
    """
    This is a test.

    docpicture = reeborg_img.png

    Some more explanation.
    """
    source_module = sys.modules[function.__module__]

    # extract image information from docstring, retrieve encoded data,
    # decode, and write to file

    image_name_pattern = re.compile("\s*docpicture\s*=\s*(.+?)\s")
    image_filename =
image_name_pattern.search(function.__doc__).groups()[0]
    base_name, ext = image_filename.split('.')
    image = base64.b64decode(getattr(source_module, base_name))

    image_file = open(image_filename, "wb")
    image_file.write(image)
    image_file.close()

    # replace image information in docstring by link to image file,
    # insert in an html template, create a new file that will be
displayed
    # in a browser.

    docpicture_pattern = re.compile("\s*(docpicture\s*=\s*.+?)\s")
    text = docpicture_pattern.sub("<br><img src=%s><br>" %
image_filename,
                                  function.__doc__)

    html_file = open("test.html", 'w')
    html_file.write(html_template % text)
    html_file.close()

    url = os.path.join(os.getcwd(), "test.html")
    webbrowser.open(url)

reeborg_img = """\
iVBORw0KGgoAAAANSUhEUgAAABYAAAAeCAMAAAAfOR5kAAAACXBIWXMAAA7EAAAOxAGVKw4bAAAD
AFBMVEUAAAAzMzNbW1v/AACAgICkpKTAwMD///
8AAAAS8uhyd1MAAAABD3UAADYAAAAAAFAAABkA
AAGFBJ4AAAkAADYAAAAAAFAAABkAAAAAAAAAABQAABcAAAkAAAQAAAQAAAQAAATxogDxoeQBD3UA
ADkAAAMAABMAABMBDusAAAAAACYFDpQAAAAAACaqAAD///
8V5iAV5hgS9XC1WqAS85wBDwG2L+RF
NyAAABMAABMBDutPyjgS9CC1WqC1VShP0RYAAABPyji1WqAS9CC1RBxP7jMAAAIBD3UAADkAAAMA
ABMAABMV5iAS9BhBx0G1DExCx4VCx43LD8i1DGxFM5sS9BhFM7JFM7oS9LRFM8QS9BgS9JjLD8jL
D8i1WqAS9DBCWLYABAEAAAC6Z1AAAAES9FzUhzRTBRAABAEAAAC6Z1DLD8i6q80AAAAS9JgS9HTU
tqPUhPzUhaQDBRoAAAEWIagWIcgABAAWX8gAAADUtik94ZFTBRAS9SwAAAAWX8g94ZwAAAAAAAAA
BAAAABMS9RAS9TjXBGfUiDD////UiCrUuJsAAADLD8hTBRAABAEAAAC6Z1B
+cqwAAAEAAAAAAAAA
AAAAAACKACEABADV8+N+cph
+8XAAAAAAAAQAAaYAAAIABAAAABMWIcgBCJ4AAAAAAAAAAAAAAAAA
AAAAAAAAAAAS8HSAFjwAAAUAAAVI2FSAGByAGKxI2GAAb1oS9fw97BsWX8gAAAAWIUgAAAQAAAAS
9mQ95ZgAAADXIloAAAAS9bzUtqPUhPzUhaQDBRoAAAEAAAAWX8gWIUgDBQES9dDUwr8S9gA90ZMD
BRo95ZgWX8jUiKYAAAAAAAIAAMgAABMWIVAS9ijUhzRTBRAAAA8AAAAAAAA95Zi6q80AAAAS9mQ9
5ZgS9pDUi9n90AAS9pDUiFoS9lDUiCoAAA895ZgS
+WgAABQAAAEAAAAAAAAAABAAAAAAAFAAAAEA
AAAAAAAS9kTxbGQS+TjXBGfUiDD////UiCoAAAAAAADKTwNHAAAACHRSTlP/////////
AN6DvVkA
AAB6SURBVHjardCLCsAgCAXQO7P8/z
+eyVxWEgzmKNghfEEES5CoqV5E7FFbIzKOao5SjJknj0yo
Gbt2fnKfOCQJHEt+43Lkdcp8J8bbBmEb7Jemh35cq/07axJjzhjIuJ+dsb/
2iZaSc3fO3qO88T+P
mpF5TB+YMp4bvwEGcAqR53QgIgAAAABJRU5ErkJggg==

"""

if __name__ == '__main__':
    docpicture_view(docpicture_view)