On Oct 14, 10:58*am, Steven D'Aprano <st...@REMOVE-THIS-
cybersource.com.auwrote:
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 = """\
iVBORw0KGgoAAAANSUhEUgAAABYAAAAeCAMAAAAfOR5kAAAACX BIWXMAAA7EAAAOxAGVKw4bAAAD
AFBMVEUAAAAzMzNbW1v/AACAgICkpKTAwMD///
8AAAAS8uhyd1MAAAABD3UAADYAAAAAAFAAABkA
AAGFBJ4AAAkAADYAAAAAAFAAABkAAAAAAAAAABQAABcAAAkAAA QAAAQAAAQAAATxogDxoeQBD3UA
ADkAAAMAABMAABMBDusAAAAAACYFDpQAAAAAACaqAAD///
8V5iAV5hgS9XC1WqAS85wBDwG2L+RF
NyAAABMAABMBDutPyjgS9CC1WqC1VShP0RYAAABPyji1WqAS9C C1RBxP7jMAAAIBD3UAADkAAAMA
ABMAABMV5iAS9BhBx0G1DExCx4VCx43LD8i1DGxFM5sS9BhFM7 JFM7oS9LRFM8QS9BgS9JjLD8jL
D8i1WqAS9DBCWLYABAEAAAC6Z1AAAAES9FzUhzRTBRAABAEAAA C6Z1DLD8i6q80AAAAS9JgS9HTU
tqPUhPzUhaQDBRoAAAEWIagWIcgABAAWX8gAAADUtik94ZFTBR AS9SwAAAAWX8g94ZwAAAAAAAAA
BAAAABMS9RAS9TjXBGfUiDD////UiCrUuJsAAADLD8hTBRAABAEAAAC6Z1B
+cqwAAAEAAAAAAAAA
AAAAAACKACEABADV8+N+cph
+8XAAAAAAAAQAAaYAAAIABAAAABMWIcgBCJ4AAAAAAAAAAAAAA AAA
AAAAAAAAAAAS8HSAFjwAAAUAAAVI2FSAGByAGKxI2GAAb1oS9f w97BsWX8gAAAAWIUgAAAQAAAAS
9mQ95ZgAAADXIloAAAAS9bzUtqPUhPzUhaQDBRoAAAEAAAAWX8 gWIUgDBQES9dDUwr8S9gA90ZMD
BRo95ZgWX8jUiKYAAAAAAAIAAMgAABMWIVAS9ijUhzRTBRAAAA 8AAAAAAAA95Zi6q80AAAAS9mQ9
5ZgS9pDUi9n90AAS9pDUiFoS9lDUiCoAAA895ZgS
+WgAABQAAAEAAAAAAAAAABAAAAAAAFAAAAEA
AAAAAAAS9kTxbGQS+TjXBGfUiDD////UiCoAAAAAAADKTwNHAAAACHRSTlP/////////
AN6DvVkA
AAB6SURBVHjardCLCsAgCAXQO7P8/z
+eyVxWEgzmKNghfEEES5CoqV5E7FFbIzKOao5SjJknj0yo
Gbt2fnKfOCQJHEt+43Lkdcp8J8bbBmEb7Jemh35cq/07axJjzhjIuJ+dsb/
2iZaSc3fO3qO88T+P
mpF5TB+YMp4bvwEGcAqR53QgIgAAAABJRU5ErkJggg==
"""
if __name__ == '__main__':
docpicture_view(docpicture_view)
