A source extractor for lightweight literate programming

This function takes three arguments:

# - - -   p r o c e s s E l t

def processElt ( fileMap, outName, elt ):
    """Process one element that may be literate.

      [ (fileMap is a dictionary whose keys are file names and
        each corresponding value is a writeable file handle
        for that file) and
        (outName is a file name as a string) and
        (elt is an etree.Element) ->
          if fileMap has a key (outName) ->
            fileMap[outName]  +:=  text of elt
          else if outName can be opened new for writing ->
            fileMap[outName]  :=  that file, so opened
            that file  :=  text of elt
          else ->
            sys.stderr  +:=  error message(s) ]
    """

First we check to see if this is a new output file. If so, we try to open it for writing. This can fail, in which case we'll need to send an error message to the standard error stream, and return prematurely.

    #-- 1 --
    # [ if outName is a key of fileMap ->
    #     I
    #   else if outName can be opened new for writing ->
    #     fileMap[outName]  :=  that file, so opened
    #   else ->
    #     sys.stderr  +:=  error message(s)
    #     return ]
    if  not fileMap.has_key(outName):
        try:
            fileMap[outName]  =  open ( outName, "w" )
        except IOError, detail:
            print >>sys.stderr, ( "*** Can't open '%s': %s" %
                                  (outName, detail) )
            return

At this point we have a destination file handle, fileMap[outName]. We use another XPath expression to find all the text descendants of elt. In this expression, the “descendant-or-self::” part is an axis specifier that selects elt, its children, its children's children, and so forth all the way to the leaves of the document tree. The XPath “text()” function selects only text nodes (as opposed to element nodes).

    #-- 2 --
    # [ textList  :=  a list of all text descendants of elt ]
    textList  =  elt.xpath ( "descendant-or-self::text()" )

    #-- 3 --
    # [ fileMap[outName]  +:=  elements of textList, concatenated ]
    fileMap[outName].write ( "".join ( textList ) )