Pic wsgi module for embedded picture references

Many years ago, I read a lot of interesting stuff on Photo.net (sadly I don't recognize the site these days).

I remember an article that discussed how they handled references to pictures in web pages. They used indirection (anything can be solved with sufficient levels of indirection), a reference like /Pic/image-name/thm would embed a small thumbnail image in the page. A service running on the web server mapped that image-name to the actual location of that image. This allowed a lot of site re-organization over time without breaking links in old pages.

This seems like a great idea, and was something I planned to implement for ages until I finally got around to it.

At first I thought a content management system like Plone was needed, but these all sucked at handling content they way I like to. Ie pages in a SCM (CVS, SVN, Git, Mercurial etc). All the content management systems I've looked at are an all or nothing deal - so not interested.

Python and WSGI were the enablers. Thus pic.wsgi came to be.


When a html page includes a reference to /Pic/20220401001/thm, the /Pic bit is stripped before the rest is passed to pic.wsgi for processing. The relevant apache config section would contiain somthing like:

WSGIScriptAlias /Pic "/httpd/wsgi/pic.wsgi"

The last component (thm) indicates the size of the image to be returned. The rest is the name of the image. The supported size indicators are:

returns a thumbnail image which is often used to embed a link to the corresponding slide page typically 168x168 or smaller.
returns a larger version of the image optimized for efficient web viewing, typically 800x800.
returns a html page containing the web image and any associated description. The image may act as a link to src.
returns the original image file if available.

The image name can be anything but I name mine using YYYYmmddNNN or YYYYmmddNNNii (where ii is the initials if someone other than me took the photo) and organize them in a directory per day. So the original 20220401001 image would be in /pics/2022/04/01/.

This makes the task of pic.wsgi much simpler. To support random meaningful names I'd likely need a database to map image names to their location. This way the filesystem is the database.

So all images can be found under /pics/ as described above, but they are not visible to the world.

The tree /pics/public/ contains links to images that are to be visible to all. This collection is organized by year only as there are not many images per year.

The tree /pics/pub/ contains links to images that are viewable by people with a login to the web server. Like public/ it is organized by year.

There are other collections with more specialized purpose, but the above is enough to help explain the setup.

When the web page containing the Pic url is from the same host, pic.wsgi can relax some of those restrictions, which allows pics to be referenced in documents without also making them world browsable.

Thus when looking for picname, we parse the appropriate year, month and day from the url and then for each top-level directory we look for:


until we find the image or give up.

The above also allows for picname to be specified as a sub-path which can be handy when just the basename might be ambiguous.

The url can also have key/value pairs appended to the end. While rarely needed this can be useful:

/Pic/other/user/event/20230902004/thm/copyright_owner="User Name",copyright_url=""

will find /pics/other/user/event/20230902004 (assuming /pics/ is in the list of search locations) and set copyright_owner and copyright_url in its config dictionary so that when we display the slide we get the expected result.

If the image is found the result is cached to save repeating the search.


pic.wsgi will read config from pic.wsgi.rc from the same dir if it exists. This can set variables like:


list of networks to consider local.


list of public directories to search for pics.


list of directories to add to pic_dirs if requestor is authenticated.


list of private directories to add to pic_dirs when requestor is suitable authorized.


This script is very handy, it allows for trivial syntax in text files to make use of pic.wsgi:


is all that is needed to produce:

.. image:: /Pic/20230401001/thm
        :align: left
        :height: 126
        :target: /Pic/20230401001/slide
        :width: 168

which (apart from target) are the defaults. Each of align (left, center, right) height, width and target as well as alt (for alternate text) can be specified.

In addition portrait and landscape can be used as shorthand to set height and width appropriately.

The keywords can be skipped when no confusion would be caused. Just:

pic=20230401007 portrait right

gives us:

.. image:: /Pic/20230401007/thm
        :align: right
        :height: 168
        :target: /Pic/20230401007/slide
        :width: 126

We can also take kwa as a list of comma separate key/value pairs which will be appended to the image line as shown earlier. The only caveat is that none of the values can contain spaces.

Author: sjg@crufty.net /* imagine something very witty here */