docpicture

[bearophileHUGS@lycos.com]

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
textual comments.

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 "documentat ion
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... :-)

Bye,
bearophile

[Steven D'Aprano]

Re: docpicture

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 "documentat ion 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
my code.

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.


--
Steven

[skip@pobox.com]

Re: docpicture


StevenI can't imagine Python having direct syntactic support for it,
Stevenbut I don't see any reason why the standard library couldn't
Stevensome day grow a "docpicture " module, complete with a tiny (?)
StevenTkinter 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.

Skip

[skip@pobox.com]

Re: docpicture


BenjaminSo, the IDEs will support it. what happens when you run the
Benjamininterpr eter 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.

S

[Joe Strout]

Re: docpicture

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.

Best,
- Joe

[skip@pobox.com]

Re: docpicture

>Nothing. It's just a doc string containing a bunch of hex codes. Doc

>strings are ignored by the interpreter (AIUI).

BenjaminI mean what happens when you type help() into the interactive
Benjaminconsole on the command line? You will see the docstrings, and
Benjaminthere 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.

Skip

[Steven D'Aprano]

Re: docpicture

On Mon, 13 Oct 2008 16:41:58 -0500, skip wrote:

>>Nothing. It's just a doc string containing a bunch of hex codes. Doc
>>strings are ignored by the interpreter (AIUI).

>
BenjaminI mean what happens when you type help() into the
interactive Benjaminconsole on the command line? You will see the
docstrings, and Benjaminthere 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.

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 ===
1234567890ABCDE F
1234567890ABCDE F
1234567890ABCDE F
1234567890ABCDE F
=== end docpicture ===


Or similar. I'm sure people will cope, especially since it should be
relatively rare.



--
Steven

[Scott David Daniels]

Re: docpicture

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 ===
1234567890ABCDE F...
=== 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">
1234567890ABCDE F...
</docpicture>'''
A comment _not_ a docstring (only found by scanning the source).
which is easy enough to hunt for.

--Scott David Daniels
Scott.Daniels@A cm.Org

[Steven D'Aprano]

Re: docpicture

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 ===
> 1234567890ABCDE F...
> === 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">
1234567890ABCDE F...
</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.gu i(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

[bearophileHUGS@lycos.com]

Re: docpicture

Steven D'Aprano:

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" :-)

Bye,
bearophile

[=?ISO-8859-1?Q?Andr=E9?=]

Re: docpicture

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 ===
    1234567890ABCDE F...
    === 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">
       1234567890ABCDE F...
       </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 reStructuredTex t 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><hea d></head><body>%s</body>"
def docpicture_view (function):
"""
This is a test.

docpicture = reeborg_img.png

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

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

image_name_patt ern = re.compile("\s* docpicture\s*=\ s*(.+?)\s")
image_filename =
image_name_patt ern.search(func tion.__doc__).g roups()[0]
base_name, ext = image_filename. split('.')
image = base64.b64decod e(getattr(sourc e_module, base_name))

image_file = open(image_file name, "wb")
image_file.writ e(image)
image_file.clos e()

# 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_patt ern = re.compile("\s* (docpicture\s*= \s*.+?)\s")
text = docpicture_patt ern.sub("<br><i mg 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 = """\
iVBORw0KGgoAAAA NSUhEUgAAABYAAA AeCAMAAAAfOR5kA AAACXBIWXMAAA7E AAAOxAGVKw4bAAA D
AFBMVEUAAAAzMzN bW1v/AACAgICkpKTAwMD///
8AAAAS8uhyd1MAA AABD3UAADYAAAAA AFAAABkA
AAGFBJ4AAAkAADY AAAAAAFAAABkAAA AAAAAAABQAABcAA AkAAAQAAAQAAAQA AATxogDxoeQBD3U A
ADkAAAMAABMAABM BDusAAAAAACYFDp QAAAAAACaqAAD///
8V5iAV5hgS9XC1W qAS85wBDwG2L+RF
NyAAABMAABMBDut PyjgS9CC1WqC1VS hP0RYAAABPyji1W qAS9CC1RBxP7jMA AAIBD3UAADkAAAM A
ABMAABMV5iAS9Bh Bx0G1DExCx4VCx4 3LD8i1DGxFM5sS9 BhFM7JFM7oS9LRF M8QS9BgS9JjLD8j L
D8i1WqAS9DBCWLY ABAEAAAC6Z1AAAA ES9FzUhzRTBRAAB AEAAAC6Z1DLD8i6 q80AAAAS9JgS9HT U
tqPUhPzUhaQDBRo AAAEWIagWIcgABA AWX8gAAADUtik94 ZFTBRAS9SwAAAAW X8g94ZwAAAAAAAA A
BAAAABMS9RAS9Tj XBGfUiDD////UiCrUuJsAAADLD8 hTBRAABAEAAAC6Z 1B
+cqwAAAEAAAAAAA AA
AAAAAACKACEABAD V8+N+cph
+8XAAAAAAAAQAAa YAAAIABAAAABMWI cgBCJ4AAAAAAAAA AAAAAAAA
AAAAAAAAAAAS8HS AFjwAAAUAAAVI2F SAGByAGKxI2GAAb 1oS9fw97BsWX8gA AAAWIUgAAAQAAAA S
9mQ95ZgAAADXIlo AAAAS9bzUtqPUhP zUhaQDBRoAAAEAA AAWX8gWIUgDBQES 9dDUwr8S9gA90ZM D
BRo95ZgWX8jUiKY AAAAAAAIAAMgAAB MWIVAS9ijUhzRTB RAAAA8AAAAAAAA9 5Zi6q80AAAAS9mQ 9
5ZgS9pDUi9n90AA S9pDUiFoS9lDUiC oAAA895ZgS
+WgAABQAAAEAAAA AAAAAABAAAAAAAF AAAAEA
AAAAAAAS9kTxbGQ S+TjXBGfUiDD////UiCoAAAAAAADKTw NHAAAACHRSTlP/////////
AN6DvVkA
AAB6SURBVHjardC LCsAgCAXQO7P8/z
+eyVxWEgzmKNghf EEES5CoqV5E7FFb IzKOao5SjJknj0y o
Gbt2fnKfOCQJHEt +43Lkdcp8J8bbBm Eb7Jemh35cq/07axJjzhjIuJ+ds b/
2iZaSc3fO3qO88T +P
mpF5TB+YMp4bvwE GcAqR53QgIgAAAA BJRU5ErkJggg==

"""

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

[bearophileHUGS@lycos.com]

Re: docpicture

André:

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:

iVBORw0KGgoAAAA NSUhEUgAAABYAAA AeCAMAAAAfOR5kA AAABGdBTUEAAL
GPC/xhBQAAAAd0SU1FB 9gKDhAtOfvfKucA AAAYUExURf///wAAADMzM1tb
W4CAgKSkpMDAwP8 AAEQE8ZoAAAABdF JOUwBA5thmAAAAC XBIWXMAAA50AA
AOdAFrJLPWAAAAd ElEQVQoU63Q0QrA IAgFUO/U9f9/vIxqpRIMdqOXQ6l F
RHBhsgAXs4zofXP zTZujlMayRjdmaM ZDjXvtEy9FFp75z OXI/pX5n6D/lQ
v1WHnUJarTjGuRx pIxkLHtyIinx4tc y2S694Kjfzn2HDN qYM54H/wB55QF
O+Mp5mAAAAAASUV ORK5CYII=

(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("bas e64") and
str.decode("bas e64"), you don't need to import modules.

Bye,
bearophile

[=?ISO-8859-1?Q?Andr=E9?=]

Re: docpicture

On Oct 14, 1:56 pm, bearophileH...@ lycos.com wrote:

André:
>

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:
>
iVBORw0KGgoAAAA NSUhEUgAAABYAAA AeCAMAAAAfOR5kA AAABGdBTUEAAL
GPC/xhBQAAAAd0SU1FB 9gKDhAtOfvfKucA AAAYUExURf///wAAADMzM1tb
W4CAgKSkpMDAwP8 AAEQE8ZoAAAABdF JOUwBA5thmAAAAC XBIWXMAAA50AA
AOdAFrJLPWAAAAd ElEQVQoU63Q0QrA IAgFUO/U9f9/vIxqpRIMdqOXQ6l F
RHBhsgAXs4zofXP zTZujlMayRjdmaM ZDjXvtEy9FFp75z OXI/pX5n6D/lQ
v1WHnUJarTjGuRx pIxkLHtyIinx4tc y2S694Kjfzn2HDN qYM54H/wB55QF
O+Mp5mAAAAAASUV ORK5CYII=
>
(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,
this,
I believe, should be left entirely to the user. The code sample I
gave
was just a proof of concept - something people asked for on this list.

For the encoding/decoding you can use str.encode("bas e64") and
str.decode("bas e64"), you don't need to import modules.
>

Good suggestion.

Bye,
bearophile

A more complete example is now available at

http://code.activestate.com/recipes/576538/

André

(Of course, now I'll have to include this in Crunchy... ;-)

[Aaron \Castironpi\ Brady]

Re: docpicture

On Oct 14, 11:56 am, bearophileH...@ lycos.com wrote:

André:
>

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:
>
iVBORw0KGgoAAAA NSUhEUgAAABYAAA AeCAMAAAAfOR5kA AAABGdBTUEAAL
GPC/xhBQAAAAd0SU1FB 9gKDhAtOfvfKucA AAAYUExURf///wAAADMzM1tb
W4CAgKSkpMDAwP8 AAEQE8ZoAAAABdF JOUwBA5thmAAAAC XBIWXMAAA50AA
AOdAFrJLPWAAAAd ElEQVQoU63Q0QrA IAgFUO/U9f9/vIxqpRIMdqOXQ6l F
RHBhsgAXs4zofXP zTZujlMayRjdmaM ZDjXvtEy9FFp75z OXI/pX5n6D/lQ
v1WHnUJarTjGuRx pIxkLHtyIinx4tc y2S694Kjfzn2HDN qYM54H/wB55QF
O+Mp5mAAAAAASUV ORK5CYII=
>
(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("bas e64") and
str.decode("bas e64"), you don't need to import modules.
>
Bye,
bearophile

+.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.

def foo():
code code
def bar():
'''doc str'''
code code

foo.__docpic__= '''
hexhexhex
hexhexhex'''
bar.__docpic__= '''
hexhexhex'''

[bearophileHUGS@lycos.com]

Re: docpicture

André:

A more complete example is now available at
http://code.activestate.com/recipes/576538/

Nice.

>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
too :-)

Bye,
bearophile