gallery.py: Use Python-3-compatible exception syntax
[blog.git] / posts / gallery / gallery.py
index b84a0cda00357ad35f86a46c156831aa90788e21..1a3c958753c0093460e7e561c67c59227cfc88d5 100755 (executable)
@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 #
-# Copyright (C) 2010-2011 W. Trevor King <wking@drexel.edu>
+# Copyright (C) 2010-2013 W. Trevor King <wking@tremily.us>
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -12,9 +12,8 @@
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 # GNU General Public License for more details.
 #
-# You should have received a copy of the GNU General Public License along
-# with this program; if not, write to the Free Software Foundation, Inc.,
-# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 """
 CGI gallery server for a picture directory organized along::
@@ -32,69 +31,77 @@ CGI gallery server for a picture directory organized along::
 
 With::
 
-  pics$ gallery.py some_directory another_directory
+  pics$ gallery.py
 
 Note that you can store a caption for ``<PICTURE>`` as plain text in
 ``<PICTURE>.txt``.
 
 See RFC 3875 for more details on the the Common Gateway Interface.
-"""
-
-# import logging first so we can timestamp other module imports
-import logging
-
-
-LOG = logging.getLogger('gallery')
-_ch = logging.StreamHandler()
-_ch.setLevel(logging.DEBUG)
-_formatter = logging.Formatter(
-    '%(asctime)s - %(name)s - %(levelname)s - %(message)s')
-_ch.setFormatter(_formatter)
-LOG.addHandler(_ch)
-#LOG.setLevel(logging.DEBUG)
-LOG.setLevel(logging.WARNING)
 
-LOG.debug('importing math')
-import math
-LOG.debug('importing os')
-import os
-LOG.debug('importing os.path')
-import os.path
-LOG.debug('importing random')
-import random
-LOG.debug('importing re')
-import re
-LOG.debug('importing subprocess')
-from subprocess import Popen, PIPE
-LOG.debug('importing sys')
-import sys
+This script can also be run as a Simple Common Gateway Interface
+(SCGI) with the ``--scgi`` option.
+"""
 
+import logging as _logging
+import logging.handlers as _logging_handlers
+import math as _math
+import mimetypes as _mimetypes
+import os as _os
+import os.path as _os_path
+import random as _random
+import re as _re
+import subprocess as _subprocess
+import urlparse as _urlparse
+import xml.sax.saxutils as _xml_sax_saxutils
 
-LOG.debug('parsing class')
 
+__version__ = '0.5'
 
-__version__ = '0.4'
 
 IMAGE_EXTENSIONS = ['.jpg', '.jpeg', '.tif', '.tiff', '.png', '.gif']
 VIDEO_EXTENSIONS = ['.mov', '.mp4', '.ogv']
+STREAMING_TYPES = ['video/ogg']
 RESPONSES = {  # httplib takes half a second to load
     200: 'OK',
     404: 'Not Found',
     }
 
+LOG = _logging.getLogger('gallery.py')
+LOG.addHandler(_logging.StreamHandler())
+#LOG.addHandler(_logging_handlers.SysLogHandler())
+LOG.handlers[0].setFormatter(
+    _logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s'))
+LOG.setLevel(_logging.DEBUG)
+#LOG.setLevel(_logging.WARNING)
+
 
 class CommandError(Exception):
     def __init__(self, command, status, stdout=None, stderr=None):
         strerror = ['Command failed (%d):\n  %s\n' % (status, stderr),
                     'while executing\n  %s' % str(command)]
-        Exception.__init__(self, '\n'.join(strerror))
+        super(CommandError, self).__init__('\n'.join(strerror))
         self.command = command
         self.status = status
         self.stdout = stdout
         self.stderr = stderr
 
-def invoke(args, stdin=None, stdout=PIPE, stderr=PIPE, expect=(0,),
-           cwd=None, encoding=None):
+
+class HTTPError(Exception):
+    def __init__(self, status, message=None, content=None):
+        if message is None:
+            message = RESPONSES[status]
+        super(HTTPError, self).__init__('{} {}'.format(status, message))
+        self.status = status
+        self.message = message
+        self.content = content
+
+
+class ProcessingComplete(Exception):
+    pass
+
+
+def invoke(args, stdin=None, stdout=_subprocess.PIPE, stderr=_subprocess.PIPE,
+           expect=(0,), cwd=None, encoding=None):
     """
     expect should be a tuple of allowed exit codes.  cwd should be
     the directory from which the command will be executed.  When
@@ -105,8 +112,9 @@ def invoke(args, stdin=None, stdout=PIPE, stderr=PIPE, expect=(0,),
         cwd = '.'
     LOG.debug('{}$ {}'.format(cwd, ' '.join(args)))
     try :
-        q = Popen(args, stdin=PIPE, stdout=stdout, stderr=stderr, cwd=cwd)
-    except OSError, e:
+        q = _subprocess.Popen(args, stdin=_subprocess.PIPE, stdout=stdout,
+                              stderr=stderr, cwd=cwd)
+    except OSError as e:
         raise CommandError(args, status=e.args[0], stderr=e)
     stdout,stderr = q.communicate(input=stdin)
     status = q.wait()
@@ -115,7 +123,13 @@ def invoke(args, stdin=None, stdout=PIPE, stderr=PIPE, expect=(0,),
         raise CommandError(args, status, stdout, stderr)
     return status, stdout, stderr
 
-def is_picture(filename):
+def is_image(filename):
+    for extension in IMAGE_EXTENSIONS:
+        if filename.lower().endswith(extension):
+            return True
+    return False
+
+def is_video(filename):
     for extension in IMAGE_EXTENSIONS:
         if filename.lower().endswith(extension):
             return True
@@ -128,13 +142,15 @@ def image_base(filename):
 
 
 class CGIGalleryServer (object):
-    def __init__(self, base_path='/var/www/localhost/htdocs/gallery/',
-                 base_url='/cgi-bin/gallery.py',
-                 cache_path='/tmp/gallery-cache/'):
-        self._base_path = base_path
+    def __init__(self, base_path='.',
+                 base_url='/',
+                 cache_path='/tmp/gallery-cache/',
+                 serve_originals=True):
+        self._base_path = _os_path.abspath(base_path)
         self._base_url = base_url
         self._cache_path = cache_path
-        self._url_regexp = re.compile('^[a-z0-9._/-]*$')
+        self._serve_originals = serve_originals
+        self._url_regexp = _re.compile('^[a-zA-Z0-9._/-]*$')
         self._rows = 3
         self._columns = 3
         self.header = []
@@ -150,35 +166,39 @@ class CGIGalleryServer (object):
         header.append('Content-type: {}{}'.format(mime, charset))
         return '\n'.join(header)
 
-    def _response(self, header=None, content='<h1>It works!</h1>'):
+    def _response(self, header=None, content='<h1>It works!</h1>',
+                  stream=None):
         if header is None:
             header = self._http_header()
-        sys.stdout.write(header)
-        sys.stdout.write('\n\n')
-        sys.stdout.write(content)
-        sys.exit(0)
+        stream.write(header)
+        stream.write('\n\n')
+        stream.write(content)
+        raise ProcessingComplete()
 
-    def _response_stream(self, header=None, content=None, chunk_size=1024):
+    def _response_stream(self, header=None, content=None, stream=None,
+                         chunk_size=1024):
         LOG.debug('streaming response')
         if header is None:
             header = self._http_header()
-        sys.stdout.write(header)
-        sys.stdout.write('\n\n')
-        sys.stdout.flush()  # flush headers
+        stream.write(header)
+        stream.write('\n\n')
+        stream.flush()  # flush headers
         while True:
             chunk = content.read(chunk_size)
             if not chunk:
                 break
-            sys.stdout.write(chunk)
-        sys.exit(0)
+            stream.write(chunk)
+        raise ProcessingComplete()
 
-    def _error(self, status=404, content=None):
+    def _error(self, status=404, content=None, stream=None):
         header = self._http_header(status=status)
         if content is None:
             content = RESPONSES[status]
-        self._response(header=header, content=content)
+        self._response(header=header, content=content, stream=stream)
 
-    def validate_url(self, url):
+    def validate_url(self, url, exists=True, directory=False):
+        LOG.debug('validating {} (exists={}, directory={})'.format(
+                repr(url), exists, directory))
         if url is None:
             return
         elif (not self._url_regexp.match(url) or
@@ -186,31 +206,72 @@ class CGIGalleryServer (object):
             '..' in url
             ):
             LOG.error('invalid url')
-            self._error(404)
-        path = os.path.join(self._base_path, url)
-        if os.path.exists(path) and not os.path.isdir(path):
-            LOG.error('nonexstand directory')
-            self._error(404)
+            raise HTTPError(404)
+        if exists:
+            path = _os_path.join(self._base_path, url)
+            if directory:
+                if not _os_path.isdir(path):
+                    LOG.error('nonexistent directory')
+                    raise HTTPError(404)
+            else:
+                if not _os_path.isfile(path):
+                    raise HTTPError(404, 'nonexistent file')
 
-    def serve(self, url, page=0):
+    def serve(self, url=None, page=0, stream=None):
         LOG.info('serving url {} (page {})'.format(url, page))
+        try:
+            try:
+                if url is None:
+                    self.index(stream=stream)
+                elif url.endswith('random'):
+                    self.random(
+                        url=url, stream=stream, max_width=500, max_height=500)
+                elif self.is_cacheable(url=url):
+                    self.validate_url(url=url, exists=False)
+                    self.cached(url=url, stream=stream)
+                else:
+                    self.validate_url(url=url, exists=False, directory=True)
+                    self.page(url=url, page=page, stream=stream)
+                raise HTTPError(404, 'unexpected URL type')
+            except HTTPError as e:
+                LOG.error(e.message)
+                self._error(e.status, content=e.content, stream=stream)
+        except ProcessingComplete:
+            pass
+
+    def page_from_query(self, query=None, query_string=None):
+        """Extract the requested page from a query string
+
+        This is a helper method for CGIGalleryServer consumers.
+        Specify either query or query_string, but not both.
+        """
+        if query is None:
+            query = _urlparse.parse_qs(query_string)
+        page = 0
+        if 'pp' in query:
+            pp = query['pp']
+            if isinstance(pp, list):
+                pp = pp[0]
+            try:
+                page = int(pp) - 1
+            except ValueError:
+                pass
+        return page
+
+    def relative_url(self, url):
         if url is None:
-            self.index()
-        elif url.endswith('random'):
-            self.random(url=url, max_width=500, max_height=500)
-        elif self.is_cached(url=url):
-            self.cached(url=url)
-        elif url.endswith('.png'):
-            self.thumb(url=url)
-        else:
-            self.page(url=url, page=page)
-            self.validate_url(url=url)
-        LOG.error('unexpected url type')
-        self._error(404)
+            return url
+        if not url.startswith(self._base_url):
+            message = 'cannot convert {} to a relative URL of {}'.format(
+                url, self._base_url)
+            raise HTTPError(404, message)
+        if url == self._base_url:
+            return None
+        return url[len(self._base_url):]
 
     def _url(self, path):
-        relpath = os.path.relpath(
-            os.path.join(self._base_path, path), self._base_path)
+        relpath = _os_path.relpath(
+            _os_path.join(self._base_path, path), self._base_path)
         if relpath == '.':
             relpath = ''
         elif path.endswith('/'):
@@ -218,9 +279,9 @@ class CGIGalleryServer (object):
         return '{}{}'.format(self._base_url, relpath)
 
     def _label(self, path):
-        dirname,base = os.path.split(path)
+        dirname,base = _os_path.split(path)
         if not base:  # directory path ending with '/'
-            dirname,base = os.path.split(dirname)
+            dirname,base = _os_path.split(dirname)
         return base.replace('_', ' ').title()
 
     def _link(self, path, text=None):
@@ -231,72 +292,100 @@ class CGIGalleryServer (object):
     def _subdirs(self, path):
         try:
             order = [d.strip() for d in
-                     open(os.path.join(path, '_order')).readlines()]
+                     open(_os_path.join(path, '_order')).readlines()]
         except IOError:
             order = []
-        dirs = sorted(os.listdir(path))
+        dirs = sorted(_os.listdir(path))
         start = []
         for d in order:
             if d in dirs:
                 start.append(d)
                 dirs.remove(d)
         for d in start + dirs:
-            dirpath = os.path.join(path, d)
-            if os.path.isdir(dirpath):
+            dirpath = _os_path.join(path, d)
+            if _os_path.isdir(dirpath):
                 yield dirpath
 
     def _images(self, path):
-        for p in sorted(os.listdir(path)):
+        for p in sorted(_os.listdir(path)):
             if p.startswith('.') or p.endswith('~'):
                 continue
-            picture_path = os.path.join(path, p)
-            if is_picture(picture_path):
+            picture_path = _os_path.join(path, p)
+            if is_image(picture_path):
                 yield picture_path
 
-    def index(self):
+    def index(self, stream=None):
         LOG.debug('index page')
-        return self._directory(self._base_path)
+        return self._directory(self._base_path, stream=stream)
+
+    def _original_url(self, url):
+        """Reverse thumbnail URL mapping
+
+        Returns (original_url, generating_callback, callback_kwargs).
+        """
+        base,extension = _os_path.splitext(url)
+        if extension in ['.png']:
+            try:
+                root,width,height = base.rsplit('-', 2)
+            except ValueError:
+                raise HTTPError(404, 'missing width/height in {}'.format(base))
+            try:
+                width = int(width)
+                height = int(height)
+            except ValueError as e:
+                raise HTTPError(404, 'invalid width/height: {}'.format(e))
+            return (
+                root + '.jpg',
+                self._thumb, 
+                {'max_width': width,
+                 'max_height': height},
+                )
+        elif extension in VIDEO_EXTENSIONS:
+            return (
+                base + '.mov',
+                getattr(self, '_{}'.format(extension), None),
+                {},
+                )
+        raise HTTPError(404, 'no original URL for {}'.format(url))
 
     def _thumb(self, image, max_width=None, max_height=None):
-        if not os.path.exists(self._cache_path):
-            os.makedirs(self._cache_path)
-        dirname,filename = os.path.split(image)
-        reldir = os.path.relpath(dirname, self._base_path)
-        cache_dir = os.path.join(self._cache_path, reldir)
-        if not os.path.isdir(cache_dir):
-            os.makedirs(cache_dir)
+        if not _os_path.exists(self._cache_path):
+            _os.makedirs(self._cache_path)
+        dirname,filename = _os_path.split(image)
+        reldir = _os_path.relpath(dirname, self._base_path)
+        cache_dir = _os_path.join(self._cache_path, reldir)
+        if not _os_path.isdir(cache_dir):
+            _os.makedirs(cache_dir)
         extension = '-{:d}-{:d}.png'.format(max_width, max_height)
         thumb_filename = image_base(filename)+extension
-        thumb_url = os.path.join(dirname, thumb_filename)
-        thumb_path = os.path.join(cache_dir, thumb_filename)
-        image_path = os.path.join(self._base_path, image)
-        if not os.path.isfile(image_path):
-            LOG.error('image path for thumbnail does not exist')
-            return self._error(404)
-        if (not os.path.isfile(thumb_path)
-            or os.path.getmtime(image_path) > os.path.getmtime(thumb_path)):
+        thumb_url = _os_path.join(dirname, thumb_filename)
+        thumb_path = _os_path.join(cache_dir, thumb_filename)
+        image_path = _os_path.join(self._base_path, image)
+        if not _os_path.isfile(image_path):
+            raise HTTPError(404, 'image path for thumbnail does not exist')
+        if (not _os_path.isfile(thumb_path)
+            or _os_path.getmtime(image_path) > _os_path.getmtime(thumb_path)):
             invoke(['convert', '-format', 'png', '-strip', '-quality', '95',
                     image_path,
                     '-thumbnail', '{:d}x{:d}'.format(max_width, max_height),
                     thumb_path])
-        return thumb_url
+        return (thumb_path, self._url(thumb_url))
 
     def _mp4(self, video, *args):
         if not video.endswith('.mov'):
-            LOG.error("can't translate {} to MPEGv4".format(video))
-        dirname,filename = os.path.split(video)
+            raise HTTPError(404, "can't translate {} to MPEGv4".format(video))
+        dirname,filename = _os_path.split(video)
         mp4_filename = image_base(filename) + '.mp4'
-        reldir = os.path.relpath(dirname, self._base_path)
-        cache_dir = os.path.join(self._cache_path, reldir)
-        if not os.path.isdir(cache_dir):
-            os.makedirs(cache_dir)
-        mp4_url = os.path.join(dirname, mp4_filename)
-        mp4_path = os.path.join(cache_dir, mp4_filename)
-        if not os.path.isfile(video):
-            LOG.error('source video path does not exist')
-            return self._error(404)
-        if (not os.path.isfile(mp4_path)
-            or os.path.getmtime(video) > os.path.getmtime(mp4_path)):
+        reldir = _os_path.relpath(dirname, self._base_path)
+        cache_dir = _os_path.join(self._cache_path, reldir)
+        if not _os_path.isdir(cache_dir):
+            _os.makedirs(cache_dir)
+        mp4_url = _os_path.join(dirname, mp4_filename)
+        mp4_path = _os_path.join(cache_dir, mp4_filename)
+        if not _os_path.isfile(video):
+            raise HTTPError(404, 'source video path does not exist')
+        if (not _os_path.isfile(mp4_path)
+            or _os_path.getmtime(video) > _os_path.getmtime(mp4_path)):
             arg = ['ffmpeg', '-i', video, '-acodec', 'libfaac', '-aq', '200',
                    '-ac', '1', '-s', '640x480', '-vcodec', 'libx264',
                    '-preset', 'slower', '-vpre', 'ipod640', '-b', '800k',
@@ -304,29 +393,28 @@ class CGIGalleryServer (object):
             arg.extend(args)
             arg.append(mp4_path)
             invoke(arg)
-        return self._url(mp4_url)
+        return (mp4_path, self._url(mp4_url))
 
     def _ogv(self, video, *args):
         if not video.endswith('.mov'):
             LOG.error("can't translate {} to Ogg Video".format(video))
-        dirname,filename = os.path.split(video)
+        dirname,filename = _os_path.split(video)
         ogv_filename = image_base(filename) + '.ogv'
-        reldir = os.path.relpath(dirname, self._base_path)
-        cache_dir = os.path.join(self._cache_path, reldir)
-        if not os.path.isdir(cache_dir):
-            os.makedirs(cache_dir)
-        ogv_url = os.path.join(dirname, ogv_filename)
-        ogv_path = os.path.join(cache_dir, ogv_filename)
-        if not os.path.isfile(video):
+        reldir = _os_path.relpath(dirname, self._base_path)
+        cache_dir = _os_path.join(self._cache_path, reldir)
+        if not _os_path.isdir(cache_dir):
+            _os.makedirs(cache_dir)
+        ogv_url = _os_path.join(dirname, ogv_filename)
+        ogv_path = _os_path.join(cache_dir, ogv_filename)
+        if not _os_path.isfile(video):
             LOG.error('source video path does not exist')
-            return self._error(404)
-        if (not os.path.isfile(ogv_path)
-            or os.path.getmtime(video) > os.path.getmtime(ogv_path)):
+        if (not _os_path.isfile(ogv_path)
+            or _os_path.getmtime(video) > _os_path.getmtime(ogv_path)):
             arg = ['ffmpeg2theora', '--optimize']
             arg.extend(args)
             arg.extend(['--output', ogv_path, video])
             invoke(arg)
-        return self._url(ogv_url)
+        return (ogv_path, self._url(ogv_url))
 
     def _get_image_caption(self, path):
         caption_path = path + '.txt'
@@ -339,7 +427,7 @@ class CGIGalleryServer (object):
         base_path = image_base(path)
         for extension in VIDEO_EXTENSIONS:
             video_path = base_path + extension
-            if os.path.isfile(video_path):
+            if _os_path.isfile(video_path):
                 return self._video(video_path, fallback=fallback)
         return None
 
@@ -358,6 +446,7 @@ class CGIGalleryServer (object):
         else:
             content.append(img)
         if caption:
+            caption = _xml_sax_saxutils.escape(caption)
             content.append('<p>{}</p>'.format(caption))
         return content
 
@@ -369,107 +458,127 @@ class CGIGalleryServer (object):
                 '</p>',
                 ]
         fallback = ['    '+line for line in fallback]
-        ogv = self._ogv(video)
-        mp4 = self._mp4(video)
+        ogv_path,ogv_url = self._ogv(video)
+        mp4_path,mp4_url = self._mp4(video)
         return [
             '<p>',
             ('  <video preloads="none" controls="controls" '
              'width="640" height="480">'),
-            '    <source src="{}"'.format(mp4),
+            '    <source src="{}"'.format(mp4_url),
             ('''            type='video/mp4; '''
              '''codecs="avc1.42E01E, mp4a.40.2"' />'''),
-            '    <source src="{}"'.format(ogv),
+            '    <source src="{}"'.format(ogv_url),
             '''            type='video/ogg; codecs="theora,vorbis"' />''',
             ] + fallback + [
             '  </video>',
             '</p>',
             '<p>Download as',
-            '  <a href="{}">Ogg/Theora/Vorbis</a> or'.format(ogv),
+            '  <a href="{}">Ogg/Theora/Vorbis</a> or'.format(ogv_url),
             ('  <a href="{}">Mpeg4/H.264(ConstrainedBaselineProfile)/AAC</a>.'
-             ).format(mp4),
+             ).format(mp4_url),
             '<p>',
             ]
 
     def _image(self, image, **kwargs):
         if kwargs:
-            image = self._thumb(image, **kwargs)
-        return '<img src="{}" />'.format(self._url(image))
+            image_path,image_url = self._thumb(image, **kwargs)
+        else:
+            image_url = image
+        sections = ['<img src="{}"'.format(image_url)]
+        caption = self._get_image_caption(path=image)
+        if caption:
+            caption = _xml_sax_saxutils.quoteattr(
+                caption.replace('\n', ' ').strip())
+            sections.extend([
+                    'title={}'.format(caption),
+                    'alt={}'.format(caption),
+                    ])
+        sections.append('/>')
+        return ' '.join(sections)
 
     def _image_page(self, image):
         return image_base(image) + '/'
 
-    def random(self, url=None, **kwargs):
+    def random(self, url=None, stream=None, **kwargs):
         LOG.debug('random image')
         if url.endswith('/random'):
-            base_dir = os.path.join(
-                self._base_path, url[:(-len('/random'))])
+            url = url[:(-len('/random'))]
+            self.validate_url(url=url, directory=True, stream=stream)
+            base_dir = _os_path.join(self._base_path, url)
         elif url == 'random':
             base_dir = self._base_path
         else:
-            self._error(404)
+            raise HTTPError(404)
         images = []
-        for dirpath,dirnames,filenames in os.walk(base_dir):
+        for dirpath,dirnames,filenames in _os.walk(base_dir):
             for filename in filenames:
-                if is_picture(filename):
-                    images.append(os.path.join(dirpath, filename))
+                if is_image(filename):
+                    images.append(_os_path.join(dirpath, filename))
         if not images:
-            self._response(content='<p>no images to choose from</p>')
-        image = random.choice(images)
+            self._response(content='<p>no images to choose from</p>',
+                           stream=stream)
+        image = _random.choice(images)
         LOG.debug('selected random image {}'.format(image))
         page = self._image_page(image)
         content = self._captioned_video(path=image, href=page)
-        self._response(content='\n'.join(content))
-
-    def is_cached(self, url):
-        for extension in ['.png', '.mp4', '.ogv']:
-            if url.endswith(extension):
-                return True
-        return False
-
-    def cached(self, url):
-        LOG.debug('retrieving cached item')
-        if url.endswith('.png'):
-            mime = 'image/png'
-        elif url.endswith('.ogv'):
-            mime = 'video/ogg'
-        elif url.endswith('.mp4'):
-            mime = 'video/mp4'
+        self._response(content='\n'.join(content), stream=stream)
+
+    def is_cacheable(self, url):
+        return is_image(url) or is_video(url)
+
+    def cached(self, url, stream=None):
+        LOG.debug('retrieving possibly cached item')
+        mime = _mimetypes.guess_type(url)[0]
+        if mime is None:
+            raise HTTPError(404, 'unknown mime type for {}'.format(url))
+        cache_path = _os_path.join(self._cache_path, url)
+        original_path = _os_path.join(self._base_path, url)
+        path = None
+        if _os_path.isfile(cache_path):
+            LOG.debug('return cached item {}'.format(cache_path))
+            path = cache_path
+        elif self._serve_originals and _os_path.isfile(original_path):
+            LOG.debug('return original item {}'.format(original_path))
+            path = original_path
         else:
-            raise NotImplementedError()
-        header = self._http_header(mime=mime)
-        cache_path = os.path.join(self._cache_path, url)
+            LOG.debug('possibly create cached item {}'.format(cache_path))
+            original_url,callback,kwargs = self._original_url(url)
+            original_path = _os_path.join(self._base_path, original_url)
+            if callback and _os_path.isfile(original_path):
+                path,cache_url = callback(original_path, **kwargs)
+        if not path:
+            raise HTTPError(404)
         try:
-            stream = open(cache_path, 'rb')
-        except IOError, e:
-            LOG.error('invalid url')
+            content = open(path, 'rb')
+        except IOError as e:
             LOG.error(e)
-            self._error(404)
-        if mime in ['video/ogg']:
-            self._response_stream(header=header, content=stream)
-        content = stream.read()
-        self._response(header=header, content=content)
-
-    def page(self, url, page=0):
-        LOG.debug('HTML page')
+            raise HTTPError(404, 'item not found {}'.format(url))
+        header = self._http_header(mime=mime)
+        if mime in STREAMING_TYPES:
+            self._response_stream(
+                header=header, content=content, stream=stream)
+        content = content.read()
+        self._response(header=header, content=content, stream=stream)
+
+    def page(self, url, page=0, stream=None):
+        LOG.debug('HTML page {} {}'.format(url, page))
         if not url.endswith('/'):
-            LOG.error('HTML page URLs must end with a slash')
-            self._error(404)
-        abspath = os.path.join(self._base_path, url)
-        if os.path.isdir(abspath):
-            self._directory(path=abspath, page=page)
+            raise HTTPError(404, 'HTML page URLs must end with a slash')
+        abspath = _os_path.join(self._base_path, url)
+        if _os_path.isdir(abspath):
+            self._directory(path=abspath, page=page, stream=stream)
         for extension in IMAGE_EXTENSIONS:
             file_path = abspath[:-1] + extension
-            if os.path.isfile(file_path):
-                self._page(path=file_path)
-        LOG.debug('unknown HTML page')
-        self._error(404)
+            if _os_path.isfile(file_path):
+                self._page(path=file_path, stream=stream)
+        raise HTTPError(404, 'unknown HTML page {}'.format(url))
 
     def _directory_header(self, path):
-        relpath = os.path.relpath(path, self._base_path)
+        relpath = _os_path.relpath(path, self._base_path)
         crumbs = []
         dirname = relpath
         while dirname:
-            dirname,base = os.path.split(dirname)
+            dirname,base = _os_path.split(dirname)
             if base != '.':
                 crumbs.insert(0, base)
         crumbs.insert(0, '')
@@ -480,7 +589,7 @@ class CGIGalleryServer (object):
                     links[i] = self._link(self._base_path, 'Gallery')
                 else:
                     relpath = '/'.join(crumbs[1:i+1]) + '/'
-                    fullpath = os.path.join(self._base_path, relpath)
+                    fullpath = _os_path.join(self._base_path, relpath)
                     links[i] = self._link(path=fullpath)
             else:
                 if i == 0:
@@ -539,16 +648,16 @@ class CGIGalleryServer (object):
         content.append('</table>')
         return content
 
-    def _directory(self, path, page=0):
-        LOG.debug('directory page')
+    def _directory(self, path, page=0, stream=None):
+        LOG.debug('directory page {} {}'.format(path, page))
         images = list(self._images(path))
         images_per_page = self._rows * self._columns
-        pages = int(math.ceil(float(len(images)) / images_per_page)) or 1
+        pages = int(_math.ceil(float(len(images)) / images_per_page)) or 1
         if page < 0 or page >= pages:
-            LOG.error(
+            raise HTTPError(
+                404,
                 'page out of bounds for this gallery 0 <= {:d} < {:d}'.format(
                     page, pages))
-            self._error(404)
         first_image = images_per_page * page
         images = images[first_image:first_image+images_per_page]
         content = []
@@ -560,11 +669,11 @@ class CGIGalleryServer (object):
         content.extend(self._directory_images(path, images=images))
         content.extend(nav)
         content.extend(self.footer)
-        self._response(content='\n'.join(content))
+        self._response(content='\n'.join(content), stream=stream)
 
-    def _page(self, path):
-        LOG.debug('image page')
-        gallery = os.path.dirname(path)
+    def _page(self, path, stream=None):
+        LOG.debug('image page {}'.format(path))
+        gallery = _os_path.dirname(path)
         images = list(self._images(gallery))
         images_per_page = self._rows * self._columns
         i = images.index(path)
@@ -585,49 +694,91 @@ class CGIGalleryServer (object):
         content.extend(self._captioned_video(path))
         content.append('</div>')
         content.extend(self.footer)
-        self._response(content='\n'.join(content))
+        self._response(content='\n'.join(content), stream=stream)
 
 
-if __name__ == '__main__':
-    LOG.debug('entering __main__ loop')
-
-    LOG.debug('importing cgi')
+def serve_cgi(server):
     import cgi
-    LOG.debug('importing cgitb')
     import cgitb
-
-    LOG.debug('parsing arguments')
-
-    url = None
-    page = 0
-    if '--url' in sys.argv:
-        i = sys.argv.index('--url')
-        try:
-            url = sys.argv[i+1]
-        except IndexError:
-            pass
-        if '--page' in sys.argv:
-            i = sys.argv.index('--page')
-            page = int(sys.argv[i+1])
-    else:
-        cgitb.enable()
-        #cgitb.enable(display=0, logdir="/tmp/")
-        data = cgi.FieldStorage()
-        if 'p' in data:
-            p = data['p']
-            if isinstance(p, list):
-                p = p[0]
-            url = p.value
-        if 'pp' in data:
+    import sys
+
+    url=None
+    cgitb.enable()
+    #cgitb.enable(display=0, logdir="/tmp/")
+    data = cgi.FieldStorage()
+    page = server.page_from_query(
+        query={key: data[key].getlist() for key in data.keys()})
+    if 'p' in data:
+        p = data['p']
+        if isinstance(p, list):
+            p = p[0]
+        url = p.value
+    server.serve(url=url, page=page, stream=sys.stdout)
+
+def serve_scgi(server, host='localhost', port=4000):
+    import scgi
+    import scgi.scgi_server
+
+    class GalleryHandler(scgi.scgi_server.SCGIHandler):
+        def produce(self, env, bodysize, input, output):
+            #LOG.info(HTTP_USER_AGENT REQUEST_METHOD REMOTE_ADDR REQUEST_URI
+            url = env.get('DOCUMENT_URI', None)
+            page = server.page_from_query(
+                query_string=env.get('QUERY_STRING', ''))
             try:
-                page = int(data['pp'].value) - 1
-            except ValueError:
+                try:
+                    url = server.relative_url(url=url)
+                except HTTPError as e:
+                    LOG.error(e.message)
+                    server._error(e.status, content=e.content, stream=output)
+            except ProcessingComplete:
                 pass
+            else:
+                server.serve(url=url, page=page, stream=output)
+
+    s = scgi.scgi_server.SCGIServer(
+        handler_class=GalleryHandler, host=host, port=port)
+    LOG.info('serving SCGI on {}:{}'.format(host, port))
+    s.serve()
+
+
+if __name__ == '__main__':
+    import argparse as _argparse
+
+    parser = _argparse.ArgumentParser(
+        description=__doc__, version=__version__,
+        formatter_class=_argparse.RawDescriptionHelpFormatter)
+    parser.add_argument(
+        '--scgi', default=False, action='store_const', const=True,
+        help='Run as a SCGI server (vs. serving a single CGI call)')
+    parser.add_argument(
+        '--port', default=4000, type=int,
+        help='Port to listen to (if runing as a SCGI server)')
+    parser.add_argument(
+        '--base-path', default='.',
+        help='Path to the root gallery source')
+    parser.add_argument(
+        '--base-url', default='/',
+        help='URL for the root gallery source')
+    parser.add_argument(
+        '--shared-path', default=None,
+        help=('Optional path to the shared directory containing '
+              '`header.shtml` and `footer.shtml`'))
+    parser.add_argument(
+        '--cache-path', default='/tmp/gallery-cache',
+        help='Path to the thumbnail and movie cache directory')
+
+    args = parser.parse_args()
 
     s = CGIGalleryServer(
-        base_path='/var/www/localhost/htdocs/gallery/',
-        base_url='/gallery/')
-    shared = '/var/www/localhost/htdocs/shared/'
-    s.header = [open(os.path.join(shared, 'header.shtml'), 'r').read()]
-    s.footer = [open(os.path.join(shared, 'footer.shtml'), 'r').read()]
-    s.serve(url=url, page=page)
+        base_path=args.base_path, base_url=args.base_url,
+        cache_path=args.cache_path)
+    if args.shared_path:
+        shared = args.shared_path
+        s.header = [open(_os_path.join(shared, 'header.shtml'), 'r').read()]
+        s.footer = [open(_os_path.join(shared, 'footer.shtml'), 'r').read()]
+
+    if args.scgi:
+        serve_scgi(server=s, port=args.port)
+    else:
+        serve_cgi(server=s)