docs: def locally_cache_remote_file(href, dir):
      """ Locally cache a remote resource using a predictable file name
          and awareness of modification date. Assume that files are "normal"
          which is to say they have filenames with extensions.
      """
      scheme, host, remote_path, params, query, fragment = urlparse(href)
      
      assert scheme in ('http','https'), 'Scheme must be either http or https, not "%s" (for %s)' % (scheme,href)
  
      head, ext = posixpath.splitext(posixpath.basename(remote_path))
      head = sub(r'[^\w\-_]', '', head)
      hash = md5(href).hexdigest()[:8]
      
      local_path = '%(dir)s/%(host)s-%(hash)s-%(head)s%(ext)s' % locals()
  
      headers = {}
      if posixpath.exists(local_path):
          msg('Found local file: %s' % local_path )
          t = localtime(os.stat(local_path).st_mtime)
          headers['If-Modified-Since'] = strftime('%a, %d %b %Y %H:%M:%S %Z', t)
      
      if scheme == 'https':
          conn = HTTPSConnection(host, timeout=5)
      else:
          conn = HTTPConnection(host, timeout=5)
  
      if query:
          remote_path += '?%s' % query
  
      conn.request('GET', remote_path, headers=headers)
      resp = conn.getresponse()
          
      if resp.status in range(200, 210):
          # hurrah, it worked
          f = open(un_posix(local_path), 'wb')
          msg('Reading from remote: %s' % remote_path)
          f.write(resp.read())
          f.close()
  
      elif resp.status in (301, 302, 303) and resp.getheader('location', False):
          # follow a redirect, totally untested.
          redirected_href = urljoin(href, resp.getheader('location'))
          redirected_path = locally_cache_remote_file(redirected_href, dir)
          os.rename(redirected_path, local_path)
      
      elif resp.status == 304:
          # hurrah, it's cached
          msg('Reading directly from local cache')
          pass
  
      else:
          raise Exception("Failed to get remote resource %s: %s" % (href, resp.status))
      
      return local_path