Misc cleanup.

Changed lookup_page_metadata() -> lookup_current_metadata() and added
lookup_file_metadata() to allow looking up metadata in files other than
the current REQUEST_URI.

Added some comments and changed function comments into docstrings.

diff --git a/bin/cmless.py b/bin/cmless.py
index 500edb6..97b944c 100755 (executable)
--- a/bin/cmless.py
+++ b/bin/cmless.py
@@ -12,10 +12,20 @@ import config, misc, template
 def main():
     print("Content-Type: text/html;charset=utf-8\n")
 
 def main():
     print("Content-Type: text/html;charset=utf-8\n")
 

+    # Since we can't use Apache's DirectoryIndex directive due to a RewriteCond
+    # passing all non-file objects to this script, we implement equivalent
+    # functionality here.

     if os.environ['REQUEST_URI'][-1] == "/":
         os.environ['REQUEST_URI'] = os.environ['REQUEST_URI'] + config.default_page
     if os.environ['REQUEST_URI'][-1] == "/":
         os.environ['REQUEST_URI'] = os.environ['REQUEST_URI'] + config.default_page

+
+    # Since we use REQUEST_URI to navigate the filesystem we need to unquote it.
+    # In other words, replace things like '%20' with ' ' (a space character).

     os.environ['REQUEST_URI'] = urllib.parse.unquote(os.environ['REQUEST_URI'])
 
     os.environ['REQUEST_URI'] = urllib.parse.unquote(os.environ['REQUEST_URI'])
 

+    # The template engine operates like a micropass compiler with each pass
+    # handling one tag from the template.  Extensions to the template engine
+    # should be executed from here and should not have or create
+    # inter-dependencies.

     content = misc.load_file(config.site_template_prefix + "/" + config.template_file)
     content = template.page_title(content)
     content = template.site_title(content)
     content = misc.load_file(config.site_template_prefix + "/" + config.template_file)
     content = template.page_title(content)
     content = template.site_title(content)

diff --git a/bin/misc.py b/bin/misc.py
index 846ebfe..a58d5be 100644 (file)
--- a/bin/misc.py
+++ b/bin/misc.py
@@ -7,9 +7,8 @@ import os, sys, subprocess, configparser
 # CMless imports
 import debug, config, template
 
 # CMless imports
 import debug, config, template
 

-# Accepts a string containing a filesystem path to a text file.
-# Returns a string containing the contents of that file.

 def load_file(path):
 def load_file(path):

+    """Open the text file at 'path' and return the contents as a string."""

     try:
         with open(path) as f:
             contents = f.read()
     try:
         with open(path) as f:
             contents = f.read()


@@ -18,9 +17,12 @@ def load_file(path):
         sys.exit("Unable to open " + path + " for reading.")
     return contents
 
         sys.exit("Unable to open " + path + " for reading.")
     return contents
 

-# Accepts a string containing markup'ed text
-# Returns a string containing HTML'ed text

 def process_markup(text):
 def process_markup(text):

+    """Execute external markup processor and return processed 'text'.
+
+    Markup processor is specified by config.markup_processor variable
+    and should accept markup on stdin while returning HTML on stdout.
+    """

     try:
         p = subprocess.Popen(config.markup_processor,
                 stdout=subprocess.PIPE,stdin=subprocess.PIPE)
     try:
         p = subprocess.Popen(config.markup_processor,
                 stdout=subprocess.PIPE,stdin=subprocess.PIPE)


@@ -32,6 +34,7 @@ def process_markup(text):
     return(text.decode('UTF-8'))
 
 def strip_page_metadata(content):
     return(text.decode('UTF-8'))
 
 def strip_page_metadata(content):

+    """Strip metadata from the beginning of 'content' and return whatever remains."""

     keyword = template.add_delimiter("END_PAGE_METADATA")
     index = content.find(keyword)
     if index != -1:
     keyword = template.add_delimiter("END_PAGE_METADATA")
     index = content.find(keyword)
     if index != -1:


@@ -39,16 +42,27 @@ def strip_page_metadata(content):
     else:
         return content
 
     else:
         return content
 

-def lookup_page_metadata(key):
-    page_file = load_file(config.site_data_prefix + os.environ['REQUEST_URI'] +
-            config.markup_file_extension)
+def lookup_current_metadata(key):
+    """Wrapper for lookup_file_metadata() supplying the current REQUEST_URI as 'file'."""
+    file = config.site_data_prefix + os.environ['REQUEST_URI'] + config.markup_file_extension
+    return lookup_file_metadata(key,file)
+
+def lookup_file_metadata(key,file):
+    """Read 'key' metadata in 'file' and return corresponding value.
+
+    Assumes key is contained in the [DEFAULT] category.
+    Returns empty string if key is not present.
+    """
+    page_file = load_file(file)

 
 

+    # Extract just the metadata block so we can pass it to ConfigParser.

     keyword_begin = template.add_delimiter("BEGIN_PAGE_METADATA")
     keyword_end = template.add_delimiter("END_PAGE_METADATA")
     index = page_file.find(keyword_end)
     if index != -1:
         page_file = page_file[len(keyword_begin):index]
     else:
     keyword_begin = template.add_delimiter("BEGIN_PAGE_METADATA")
     keyword_end = template.add_delimiter("END_PAGE_METADATA")
     index = page_file.find(keyword_end)
     if index != -1:
         page_file = page_file[len(keyword_begin):index]
     else:

+        # ConfigParser will accept an empty string so use that as fallback.

         page_file = ""
 
     page_metadata = configparser.ConfigParser()
         page_file = ""
 
     page_metadata = configparser.ConfigParser()


@@ -57,4 +71,8 @@ def lookup_page_metadata(key):
     if 'DEFAULT' in page_metadata and key in page_metadata['DEFAULT']:
         return page_metadata['DEFAULT'][key]
     else:
     if 'DEFAULT' in page_metadata and key in page_metadata['DEFAULT']:
         return page_metadata['DEFAULT'][key]
     else:

+        # An empty string is technically a valid value for a key but we will
+        # overload it as also indicating 'key' wasn't present since a key
+        # without a value is functionally equivalent to no key at all for our
+        # purposes.

         return ""
         return ""

diff --git a/bin/template.py b/bin/template.py
index cdc7fe7..fc8886f 100644 (file)
--- a/bin/template.py
+++ b/bin/template.py
@@ -12,15 +12,18 @@ def add_delimiter(keyword):
 
 def head_meta_description(template):
     keyword = add_delimiter("meta_description")
 
 def head_meta_description(template):
     keyword = add_delimiter("meta_description")

-    return template.replace(keyword,'<meta name="description" content="' + misc.lookup_page_metadata("meta_description") + '">')
+    return template.replace(keyword,'<meta name="description" content="' +
+            misc.lookup_current_metadata("meta_description") + '">')

 
 def head_meta_keywords(template):
     keyword = add_delimiter("meta_keywords")
 
 def head_meta_keywords(template):
     keyword = add_delimiter("meta_keywords")

-    return template.replace(keyword,'<meta name="keywords" content="' + misc.lookup_page_metadata("meta_keywords") + '">')
+    return template.replace(keyword,'<meta name="keywords" content="' +
+            misc.lookup_current_metadata("meta_keywords") + '">')

 
 def page_title(template):
     keyword = add_delimiter("page_title")
 
 def page_title(template):
     keyword = add_delimiter("page_title")

-    return template.replace(keyword, config.site_name + " - " + misc.lookup_page_metadata("page_title"))
+    return template.replace(keyword, config.site_name + " - " +
+            misc.lookup_current_metadata("page_title"))

 
 def site_title(template):
     keyword = add_delimiter("site_title")
 
 def site_title(template):
     keyword = add_delimiter("site_title")