||10/13/08 8:34 AM
In Python code that processes some geometrical data I want to explain
what each variable like w1, w2, h2, h3, etc, means in the geometrical
objects. In such situation I don't use longer and more clear variable
names because in geometry I'm used to use short vertex/line/length
names, finding them more readable in the various formulas. Complex
formulas full of long names become huge and not much readable anyway.
To explain what those w1, w2, h2, h3 mean I can use text, or sometimes
ASCII art. But ASCII art is very low-resolution, so I have found that
a single little image can explain the meaning of lot of variables (and
other details) in a short space. Leaving the explanations to normal
So in this situation I have sometimes created a quite small image (1
bit/pixel) that encoded in png image format may require just few
hundred bytes. With Python I encode is binary data string in base64,
and I paste that as a string into the Python souce code. It probably
takes only 4-7 lines or so. With one or two more lines of Python I can
decode that string it and save as png again (usually this image
decoding line is commented out or executed only if a debugging global
variable is true). So far I have never used SVG vector images for such
purpose, but they are another possibility (the SVG ones may need to be
bzipped2 before the base64 encoding).
This way there's no risk of losing the essential image, because it's
embedded into the Python code.
Have you ever done this? Do you think such "documentation
picture" (analogous to a docstring) is an acceptable practice? I don't
need to do that often enough, so I think it doesn't deserve to become
supported by Python itself. While I presume emacs and similar
"advanced" editors can be programmed to recognize such string pictures
and show them inlined... :-)
||10/13/08 9:46 AM
On Mon, 13 Oct 2008 08:34:03 -0700, bearophileHUGS wrote:
> So in this situation I have sometimes created a quite small image (1
> bit/pixel) that encoded in png image format may require just few hundred
> bytes. With Python I encode is binary data string in base64, and I paste
> that as a string into the Python souce code. It probably takes only 4-7
> lines or so.
> Have you ever done this? Do you think such "documentation picture"
> (analogous to a docstring) is an acceptable practice?
I've never done it, but I've often wished to be able to store diagrams in
> I don't need to do
> that often enough, so I think it doesn't deserve to become supported by
> Python itself.
I can't imagine Python having direct syntactic support for it, but I
don't see any reason why the standard library couldn't some day grow a
"docpicture" module, complete with a tiny (?) Tkinter app to display the
diagram when requested.
I think this would be useful. If you choose to share your code under an
appropriate licence, I would like to experiment with it.
||10/13/08 10:43 AM
Steven> I can't imagine Python having direct syntactic support for it,
Steven> but I don't see any reason why the standard library couldn't
Steven> some day grow a "docpicture" module, complete with a tiny (?)
Steven> Tkinter app to display the diagram when requested.
Heck, if you go to the point of including a docpicture module, might as well
just support the feature in IDLE... Other IDEs would probably pick up the
feature as well.
||10/13/08 11:51 AM
Benjamin> So, the IDEs will support it. what happens when you run the
Benjamin> interpreter from the command line?
Probably get ignored. What else would you propose? It's not executable
code anyway, just a special comment or portion of a docstring.
||10/13/08 1:55 PM
On Oct 13, 2008, at 2:43 PM, Benjamin Kaplan wrote:
> I mean what happens when you type help() into the interactive
> console on the command line? You will see the docstrings, and there
> will be a whole bunch of random hex characters there.
Good point. It might be better put in a specially-tagged comment,
rather than in the docstring.
I still think it's a nifty idea though.
||10/13/08 2:41 PM
>> Nothing. It's just a doc string containing a bunch of hex codes. Doc
>> strings are ignored by the interpreter (AIUI).
Benjamin> I mean what happens when you type help() into the interactive
Benjamin> console on the command line? You will see the docstrings, and
Benjamin> there will be a whole bunch of random hex characters there.
If an IDE can be trained to recognize and display such a picture I sorta
assume help() can be trained to recognize and ignore it.
||10/13/08 3:20 PM
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 with a fried egg on top
=== begin docpicture ===
=== end docpicture ===
Or similar. I'm sure people will cope, especially since it should be
||Scott David Daniels
||10/14/08 6:12 AM
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 with a fried egg on top
> === begin docpicture ===
> === 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">
A comment _not_ a docstring (only found by scanning the source).
which is easy enough to hunt for.
--Scott David Daniels
||10/14/08 6:58 AM
+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
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.
||10/14/08 8:43 AM
> Unless bearophile is willing to share his code,
There's no code: all I do is written in my post, and so far I have
done it "manually" :-)
||10/14/08 9:23 AM
On Oct 14, 10:58 am, Steven D'Aprano <st...@REMOVE-THIS-
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).
html_template = "<html><head></head><body>%s</body>"
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")
base_name, ext = image_filename.split('.')
image = base64.b64decode(getattr(source_module, base_name))
image_file = open(image_filename, "wb")
# replace image information in docstring by link to image file,
# insert in an html template, create a new file that will be
# in a browser.
docpicture_pattern = re.compile("\s*(docpicture\s*=\s*.+?)\s")
text = docpicture_pattern.sub("<br><img src=%s><br>" %
html_file = open("test.html", 'w')
html_file.write(html_template % text)
url = os.path.join(os.getcwd(), "test.html")
reeborg_img = """\
if __name__ == '__main__':
||10/14/08 9:56 AM
> Ok, the following is my first attempt at implementing this idea.
I suggest you to change the program you use to encode your images,
because it's 1000 bytes, while with my program the same 256 colors
image needs just 278 bytes:
(and it contains just 8 colors, so it can be saved as a 4 bit PNG,
saving even more bytes). Generally I suggest to use as few bits/pixel
as possible, just 1 if possible.
For the encoding/decoding you can use str.encode("base64") and
str.decode("base64"), you don't need to import modules.
||10/14/08 6:31 PM
On Oct 14, 1:56 pm, bearophileH...@lycos.com wrote:
> > Ok, the following is my first attempt at implementing this idea.
> I suggest you to change the program you use to encode your images,
> because it's 1000 bytes, while with my program the same 256 colors
> image needs just 278 bytes:
> (and it contains just 8 colors, so it can be saved as a 4 bit PNG,
> saving even more bytes). Generally I suggest to use as few bits/pixel
> as possible, just 1 if possible.
While I agree that embedded images should be as small as possible,
I believe, should be left entirely to the user. The code sample I
was just a proof of concept - something people asked for on this list.
> For the encoding/decoding you can use str.encode("base64") and
> str.decode("base64"), you don't need to import modules.
A more complete example is now available at
(Of course, now I'll have to include this in Crunchy... ;-)
||Aaron "Castironpi" Brady
||10/14/08 8:17 PM
+.5 docpicture. For encoding, it might read in from a file, try
multiple different formats, including SVG, and uses whichever one is
shortest. It might be nice, if they take too many lines, to store
them at the end of the file, and make sure docpicture looks for them
there. It could be more hassle (maybe less, actually), to store them
as attributes of the objects they're accompanying, and still locate
them at the bottom-- sort of like an appendix or something.
||10/14/08 8:54 PM
> A more complete example is now available at
>The idea for this recipe was mentioned on the Python mailing list as something desirable and apparently done by someone<
That someone has a nickname you can use, I am known in the cookbook
||10/15/08 8:06 AM
Scott David Daniels <Scott.Daniels@Acm.Org> writes:
> or you could even use:
> '''<docpicture name="fig1.png" code="base64" version="1">
> A comment _not_ a docstring (only found by scanning the source).
> which is easy enough to hunt for.
-1 for XML based syntax, we should instead look to reST. It already
has image and figure directives. The docs say that image takes a URI
argument and some options. So an external file should work now.
Maybe someone would like to play with the data URL scheme (RFC 2397)
to meet the OP's desire to embed the image. AFAIK a downside is that
MS are only starting to support that in IE8.
Pete Forman -./\.- Disclaimer: This post is originated
WesternGeco -./\.- by myself and does not represent
pete....@westerngeco.com -./\.- the opinion of Schlumberger or
http://petef.22web.net -./\.- WesternGeco.
||10/17/08 12:53 AM
In message <y70pki...@wgmail2.gatwick.eur.slb.com>, Pete Forman wrote:
> Maybe someone would like to play with the data URL scheme (RFC 2397)
> to meet the OP's desire to embed the image. AFAIK a downside is that
> MS are only starting to support that in IE8.
Firefox, Konqueror and Safari already support it. So it's not as though
users of all major platforms cannot access it.