Code Documentation


This chapter covers important functions, methods and classes in Pyblosxom. When in doubt, read the code.



Pyblosxom version as a string. Conforms to PEP-386.

For example "1.5".


This is the main module for Pyblosxom functionality. Pyblosxom’s setup and default handlers are defined here.

class Pyblosxom.pyblosxom.EnvDict(request, env)

Wrapper around a dict to provide a backwards compatible way to get the form with syntax as:


instead of:

class Pyblosxom.pyblosxom.Pyblosxom(config, environ, data=None)

Main class for Pyblosxom functionality. It handles initialization, defines default behavior, and also pushes the request through all the steps until the output is rendered and we’re complete.


This cleans up Pyblosxom after a run.

This should be called when Pyblosxom has done everything it needs to do before exiting.

getRequest(*args, **kwargs)

DEPRECATED. Use get_request instead.

getResponse(*args, **kwargs)

DEPRECATED. Use get_response instead.


Returns the Request object for this Pyblosxom instance.


Returns the Response object associated with this Request.


The initialize step further initializes the Request by setting additional information in the data dict, registering plugins, and entryparsers.


This is the main loop for Pyblosxom. This method will run the handle callback to allow registered handlers to handle the request. If nothing handles the request, then we use the default_blosxom_handler.

Parameters:static – True if Pyblosxom should execute in “static rendering mode” and False otherwise.
runCallback(*args, **kwargs)

DEPRECATED. Use run_callback instead.


This method executes the start callback (initializing plugins), executes the requested callback, and then executes the end callback.

This is useful for scripts outside of Pyblosxom that need to do things inside of the Pyblosxom framework.

If you want to run a callback from a plugin, use tools.run_callback instead.

Parameters:callback – the name of the callback to execute.
Returns:the results of the callback.
run_render_one(url, headers)

Renders a single page from the blog.

  • url – the url to render–this has to be relative to the base url for this blog.
  • headers – True if you want headers to be rendered and False if not.

This will go through all possible things in the blog and statically render everything to the static_dir specified in the config file.

This figures out all the possible path_info settings and calls a bazillion times saving each file.

Parameters:incremental – Whether (True) or not (False) to incrementally render the pages. If we’re incrementally rendering pages, then we render only the ones that have changed.
class Pyblosxom.pyblosxom.PyblosxomWSGIApp(environ=None, start_response=None, configini=None)

This class is the WSGI application for Pyblosxom.

run_pyblosxom(env, start_response)

Executes a single run of Pyblosxom wrapped in the crash handler.

class Pyblosxom.pyblosxom.Request(config, environ, data)

This class holds the Pyblosxom request. It holds configuration information, HTTP/CGI information, and data that we calculate and transform over the course of execution.

There should be only one instance of this class floating around and it should get created by pyblosxom.cgi and passed into the Pyblosxom instance which will do further manipulation on the Request instance.

addConfiguration(*args, **kwargs)

DEPRECATED. Use add_configuration instead.

addData(*args, **kwargs)

DEPRECATED. Use add_data instead.

addHttp(*args, **kwargs)

DEPRECATED. Use add_http instead.


Takes in a dict and adds/overrides values in the existing configuration dict with the new values.


Takes in a dict and adds/overrides values in the existing data dict with the new values.


Takes in a dict and adds/overrides values in the existing http dict with the new values.


Buffer the input stream in a StringIO instance. This is done to have a known/consistent way of accessing incoming data. For example the input stream passed by mod_python does not offer the same functionality as sys.stdin.

getConfiguration(*args, **kwargs)

DEPRECATED. Use get_configuration instead.

getData(*args, **kwargs)

DEPRECATED. Use get_data instead.

getForm(*args, **kwargs)

DEPRECATED. Use get_form instead.

getHttp(*args, **kwargs)

DEPRECATED. Use get_http instead.

getResponse(*args, **kwargs)

DEPRECATED. Use get_response instead.


Returns the actual configuration dict. The configuration dict holds values that the user sets in their file.

Modifying the contents of the dict will affect all downstream processing.


Returns the actual data dict. Holds run-time data which is created and transformed by pyblosxom during execution.

Modifying the contents of the dict will affect all downstream processing.


Returns the form data submitted by the client. The form instance is created only when requested to prevent overhead and unnecessary consumption of the input stream.

Returns:a cgi.FieldStorage instance.

Returns the actual http dict. Holds HTTP/CGI data derived from the environment of execution.

Modifying the contents of the dict will affect all downstream processing.


Returns the Response for this request.

setResponse(*args, **kwargs)

DEPRECATED. Use set_response instead.


Sets the Response object.

class Pyblosxom.pyblosxom.Response(request)

Response class to handle all output related tasks in one place.

This class is basically a wrapper arround a StringIO instance. It also provides methods for managing http headers.

addHeader(*args, **kwargs)

DEPRECATED. Use add_header instead.

add_header(key, value)

Populates the HTTP header with lines of text. Sets the status code on this response object if the given argument list contains a ‘Status’ header.


>>> resp = Response('some fake request')
>>> resp.add_header("Content-type", "text/plain")
>>> resp.add_header("Content-Length", "10500")
Raises ValueError:
 This happens when the parameters are not correct.
getHeaders(*args, **kwargs)

DEPRECATED. Use get_headers instead.


Returns the headers.


Returns the status code and message of this response.

sendBody(*args, **kwargs)

DEPRECATED. Use send_body instead.

sendHeaders(*args, **kwargs)

DEPRECATED. Use send_headers instead.


Send the response body to the given output stream.

Parameters:out – the file-like object to print the body to.

Send HTTP Headers to the given output stream.


This prints the headers and then the \n\n that separates headers from the body.

Parameters:out – The file-like object to print headers to.
setStatus(*args, **kwargs)

DEPRECATED. Use set_status instead.


Sets the status code for this response. The status should be a valid HTTP response status.


>>> resp = Response('some fake request')
>>> resp.set_status("200 OK")
>>> resp.set_status("404 Not Found")
Parameters:status – the status string.
Pyblosxom.pyblosxom.pyblosxom_app_factory(global_config, **local_config)

App factory for paste.

Returns:WSGI application

Executes Pyblosxom either as a commandline script or CGI script.

Utility module for functions that are useful to Pyblosxom and plugins.


Thrown when convert_configini_values encounters a syntax error.


Filters out messages from log-channels that are not listed in the log_filter config variable.

class, encoding, var_dict)

Class for replacing variables in a template

This class is a utility class used to provide a bound method to the re.sub() function. Originally from OPAGCGI.


This is passed a match object by re.sub() which represents a template variable without the $. parse manipulates the variable and returns the expansion of that variable using the following rules:

  1. if the variable v is an identifier, but not in the variable dict, then we return the empty string, or
  2. if the variable v is an identifier in the variable dict, then we return var_dict[v], or
  3. if the variable v is a function call where the function is an identifier in the variable dict, then
    • if v has no passed arguments and the function takes no arguments we return var_dict[v]() (this is the old behavior
    • if v has no passed arguments and the function takes two arguments we return var_dict[v](request, vd)
    • if v has passed arguments, we return var_dict[v](request, vd, *args) after some mild processing of the arguments

Also, for backwards compatibility reasons, we convert things like:



Parameters:matchobj – the regular expression match object
Returns:the substituted string

SGMLParser that removes HTML formatting code.


Returns the buffer.


Implements handle_data. Appends data to the buffer.


Implements unknown_endtag. Appends a space to the buffer.

unknown_starttag(tag, attrs)

Implements unknown_starttag. Appends a space to the buffer.*args, **kwargs)

DEPRECATED. Use walk instead.

Adds a cr if it needs one.

>>> addcr("foo")
>>> addcr("foo\n")
Returns:string with n at the end

Splits a string that contains strings by comma. This is more involved than just an s.split(",") because this handles commas in strings correctly.

Note: commasplit doesn’t remove extranneous spaces.

>>> commasplit(None)
>>> commasplit("")
>>> commasplit("a")
>>> commasplit("a, b, c")
['a', ' b', ' c']
>>> commasplit("'a', 'b, c'")
["'a'", " 'b, c'"]
>>> commasplit("'a', \"b, c\"")
["'a'", ' "b, c"']
Parameters:s – the string to split
Returns:list of strings

Takes a dict containing config.ini style keys and values, converts the values, and returns a new config dict.

Parameters:confini – dict containing the config.ini style keys and values
Raises ConfigSyntaxErrorException:
 when there’s a syntax error
Returns:new config dict, category, filename, mtime, title, metadata, body)

Creates a new entry in the blog.

This is primarily used by the testing system, but it could be used by scripts and other tools.

  • datadir – the datadir
  • category – the category the entry should go in
  • filename – the name of the blog entry (filename and extension–no directory)
  • mtime – the mtime (float) for the entry in seconds since the epoch
  • title – the title for the entry
  • metadata – dict of key/value metadata pairs
  • body – the body of the entry
Raises IOError:

if the datadir + category directory exists, but isn’t a directory

Takes in a string and converts:

  • & to &
  • > to >
  • < to &lt;
  • " to &quot;
  • ' to &#x27;
  • / to &#x2F;

Note: if s is None, then we return None.

>>> escape_text(None)
>>> escape_text("")
>>> escape_text("a'b")
>>> escape_text('a"b')
'a&quot;b', filename)

Returns the filestat on a given file. We store the filestat in case we’ve already retrieved it during this Pyblosxom request.

This returns the mtime of the file (same as returned by time.localtime()) – tuple of 9 ints.

  • request – the Request object
  • filename – the file name of the file to stat

the filestat (tuple of 9 ints) on the given file*args, **kwargs)

DEPRECATED. Use generate_rand_str instead., maxlen=10)

Generate a random string between minlen and maxlen characters long.

The generated string consists of letters and numbers.

  • minlen – the minimum length of the generated random string
  • maxlen – the maximum length of the generated random string

generated string*args, **kwargs)

DEPRECATED. Use get_logger instead.

Retrieves the cache from the request or fetches a new CacheDriver instance.

Parameters:request – the Request object
Returns:a BlosxomCache object

Creates and returns a log channel.

If no log_file is given the system-wide logfile as defined in is used. If a log_file is given that’s where the created logger logs to.

Parameters:log_file – the file to log to. defaults to None which causes Pyblosxom to check for the log_file property and if that’s blank, then the log_file is stderr
Returns:a log channel (logger instance) which you can call error, warning, debug, info, ... on., name)

Safely imports modules for runtime importing.

  • module_name – the package name of the module to import from
  • name – the name of the module to import

the module object or None if there were problems importing.

Initializes the tools module.

This gives the module a chance to use configuration from the pyblosxom file.

This should be called from Pyblosxom.pyblosxom.Pyblosxom.initialize.

Checks to see if the string is likely to be a year or not. In order to be considered to be a year, it must pass the following criteria:

  1. four digits
  2. first two digits are either 19 or 20.
Parameters:s – the string to check for “year-hood”
Returns:True if it is a year and False otherwise., log_file=None)

Logs some info about the calling function/method. Useful for debugging.


>>> import tools
>>> tools.log_caller()     # logs frame 1
>>> tools.log_caller(2)
>>> tools.log_caller(3, log_file="/path/to/file")
  • frame_num – the index of the frame to log; defaults to 1
  • log_file – the file to log to. defaults to None which causes Pyblosxom to check for the log_file property and if that’s blank, then the log_file is stderr

Logs an exception to the given file. Uses the system-wide log_file as defined in if none is given here.

Parameters:log_file – the file to log to. defaults to None which causes Pyblosxom to check for the log_file property and if that’s blank, then the log_file is stderr, var_dict, template)

This method parses the template passed in using Replacer to expand template variables using values in the var_dict.

Originally based on OPAGCGI, but mostly re-written.

  • request – the Request object
  • var_dict – the dict holding name/value pair variable replacements
  • template – the string template we’re expanding variables in.

the template string with template variables expanded.

Wraps the text and prints it.

Wraps an error message and prints it to stderr., pathinfo, querystring='')

Takes a url and a querystring and renders the page that corresponds with that by creating a Request and a Pyblosxom object and passing it through. It then returns the resulting Response.

  • cdict – the dict
  • pathinfo – the PATH_INFO string; example: /dev/pyblosxom/firstpost.html
  • querystring – the querystring (if any); example: debug=yes

a Pyblosxom Response object., url, querystring)

Renders a url and saves the rendered output to the filesystem.

  • cdict – config dict
  • url – url to render
  • querystring – querystring of the url to render or “”, input, mappingfunc=<function <lambda> at 0x240f500>, donefunc=<function <lambda> at 0x240f578>, defaultfunc=None)

Executes a callback chain on a given piece of data. passed in is a dict of name/value pairs. Consult the documentation for the specific callback chain you’re executing.

Callback chains should conform to their documented behavior. This function allows us to do transforms on data, handling data, and also callbacks.

The difference in behavior is affected by the mappingfunc passed in which converts the output of a given function in the chain to the input for the next function.

If this is confusing, read through the code for this function.

Returns the transformed input dict.

  • chain – the name of the callback chain to run
  • input – dict with name/value pairs that gets passed as the args dict to all callback functions
  • mappingfunc – the function that maps output arguments to input arguments for the next iteration. It must take two arguments: the original dict and the return from the previous function. It defaults to returning the original dict.
  • donefunc – this function tests whether we’re done doing what we’re doing. This function takes as input the output of the most recent iteration. If this function returns True then we’ll drop out of the loop. For example, if you wanted a callback to stop running when one of the registered functions returned a 1, then you would pass in: donefunc=lambda x: x .
  • defaultfunc – if this is set and we finish going through all the functions in the chain and none of them have returned something that satisfies the donefunc, then we’ll execute the defaultfunc with the latest version of the input dict.

varies, entry_filename)

This is a utility function that allows plugins to easily update statically rendered entries without going through all the rigmarole.

First we figure out whether this blog is set up for static rendering. If not, then we return–no harm done.

If we are, then we call render_url for each static_flavour of the entry and then for each static_flavour of the index page.

  • cdict – the dict
  • entry_filename – the url path of the entry to be updated; example: /movies/xmen2

Calls urllib.quote on the string s.

Note: if s is None, then we return None.

>>> urlencode_text(None)
>>> urlencode_text("")
>>> urlencode_text("a c")
>>> urlencode_text("a&c")
>>> urlencode_text("a=c")
'a%3Dc', root='.', recurse=0, pattern='', return_folders=0)

This function walks a directory tree starting at a specified root folder, and returns a list of all of the files (and optionally folders) that match our pattern(s). Taken from the online Python Cookbook and modified to own needs.

It will look at the config “ignore_directories” for a list of directories to ignore. It uses a regexp that joins all the things you list. So the following:["ignore_directories"] = ["CVS", "dev/pyblosxom"]

turns into the regexp:


It will also skip all directories that start with a period.

  • request – the Request object
  • root – the root directory to walk
  • recurse – the depth of recursion; defaults to 0 which goes all the way down
  • pattern – the regexp object for matching files; defaults to ‘’ which causes Pyblosxom to return files with file extensions that match those the entryparsers handle
  • return_folders – True if you want only folders, False if you want files AND folders

a list of file paths., filepath)

Takes in a filepath and a list of extensions and tries them all until it finds the first extension that works.

  • extensions – the list of extensions to test
  • filepath – the complete file path (minus the extension) to test and find the extension for

the extension (string) of the file or None.


The is the base renderer module. If you were to dislike the blosxom renderer and wanted to build a renderer that used a different templating system, you would extend the RendererBase class and implement the functionality required by the other rendering system.

For examples, look at the BlosxomRenderer and the Renderer in the debug module.

class Pyblosxom.renderers.base.Renderer(request, stdoutput=<open file '<stdout>', mode 'w' at 0x2b478906d150>)

This is a null renderer.

class Pyblosxom.renderers.base.RendererBase(request, stdoutput=<open file '<stdout>', mode 'w' at 0x2b478906d150>)

Pyblosxom core handles the Input and Process of the system and passes the result of the process to the Renderers for output. All renderers are child classes of RendererBase. RenderBase will contain the public interfaces for all Renderer object.

addHeader(*args, **kwargs)

DEPRECATED. Use add_header instead.


Populates the HTTP header with lines of text

Parameters:args – Paired list of headers
Raises ValueError:
 This happens when the parameters are not correct
getContent(*args, **kwargs)

DEPRECATED. Use get_content instead.


Return the content field

This is exposed for blosxom callbacks.

needsContentType(*args, **kwargs)

DEPRECATED. Use needs_content_type instead.


Use the renderer to determine ‘Content-Type: x/x’ default is to use the renderer for Content-Type, set flag to None to indicate no Content-Type generation.

Parameters:flag – True of false value

Do final rendering.

Parameters:header – whether (True) or not (False) to show the headers
setContent(*args, **kwargs)

DEPRECATED. Use set_content instead.


Sets the content. The content can be any of the following:

  • dict
  • list of entries
Parameters:content – the content to be displayed
showHeaders(*args, **kwargs)

DEPRECATED. Use show_headers instead.


Updated the headers of the Response<Pyblosxom.pyblosxom.Response> instance.

This is here for backwards compatibility.


Convenience method for programs to use instead of accessing self._out.write()

Other classes can override this if there is a unique way to write out data, for example, a two stream output, e.g. one output stream and one output log stream.

Another use for this could be a plugin that writes out binary files, but because renderers and other frameworks may probably not want you to write to stdout directly, this method assists you nicely. For example:

def cb_start(args):
    req = args['request']
    renderer = req['renderer']

    if reqIsGif and gifFileExists(theGifFile):
        # Read the file
        data = open(theGifFile).read()

        # Modify header
        renderer.addHeader('Content-type', 'image/gif')
        renderer.addHeader('Content-Length', len(data))

        # Write to output

        # Tell pyblosxom not to render anymore as data is
        # processed already
        renderer.rendered = 1

This simple piece of pseudo-code explains what you could do with this method, though I highly don’t recommend this, unless pyblosxom is running continuously.

Parameters:data – Piece of string you want printed


This module contains the base class for all the Entry classes. The EntryBase class is essentially the API for entries in Pyblosxom. Reading through the comments for this class will walk you through building your own EntryBase derivatives.

This module also holds a generic generate_entry function which will generate a BaseEntry with data that you provide for it.

class Pyblosxom.entries.base.EntryBase(request)

EntryBase is the base class for all the Entry classes. Each instance of an Entry class represents a single entry in the weblog, whether it came from a file, or a database, or even somewhere off the InterWeeb.

EntryBase derivatives are dict-like except for one key difference: when doing __getitem__ on a nonexistent key, it returns None by default. For example:

>>> entry = EntryBase('some fake request')
>>> None == entry["some_nonexistent_key"]
addToCache(*args, **kwargs)

DEPRECATED. Use add_to_cache instead.

add_to_cache(entryid, data)

Over-writes the cached dict for key entryid with the data dict.

This is a helper method–call this to add data to the cache. Do not override it.

  • entryid – a unique key for the information you’re storing
  • data – the data to store–this should probably be a dict
get(key, default=None)

Retrieves an item from the internal dict based on the key given.

All this does is turn aroun and call __getitem__.


There’s no reason to override this–override get_data and get_metadata instead.

  • key – the key being sought
  • default – the default to return if the key does not exist

the value of get_metadata or get_data (through __getitem__)

getData(*args, **kwargs)

DEPRECATED. Use get_data instead.

getFromCache(*args, **kwargs)

DEPRECATED. Use get_from_cache instead.

getId(*args, **kwargs)

DEPRECATED. Use get_id instead.

getMetadata(*args, **kwargs)

DEPRECATED. Use get_metadata instead.

getMetadataKeys(*args, **kwargs)

DEPRECATED. Use get_metadata_keys instead.


Returns the data string. This method should be overridden to provide from pulling the data from other places.

Override this.

Returns:the data as a string

Retrieves information from the cache that pertains to this specific entryid.

This is a helper method–call this to get data from the cache. Do not override it.

Parameters:entryid – a unique key for the information you’re retrieving
Returns:dict with the values or None if there’s nothing for that entryid

This should return an id that’s unique enough for caching purposes.

Override this.

Returns:string id
get_metadata(key, default=None)

Returns a given piece of metadata.

Override this.

  • key – the key being sought
  • default – the default to return if the key does not exist

either the default (if the key did not exist) or the value of the key in the metadata dict


Returns the list of keys for which we have values in our stored metadata.


This list gets modified later downstream. If you cache your list of metadata keys, then this method should return a copy of that list and not the list itself lest it get adjusted.

Override this.

Returns:list of metadata keys

Returns whether a given key is in the metadata dict. If the key is the CONTENT_KEY, then we automatically return true.


There’s no reason to override this–override get_metadata instead.

Parameters:key – the key to check in the metadata dict for
Returns:whether (True) or not (False) the key exists

Returns a list of the keys that can be accessed through __getitem__.


There’s no reason to override this–override get_metadata_keys instead.

Returns:list of key names
setData(*args, **kwargs)

DEPRECATED. Use set_data instead.

setMetadata(*args, **kwargs)

DEPRECATED. Use set_metadata instead.

setTime(*args, **kwargs)

DEPRECATED. Use set_time instead.


Sets the data content for this entry. If you are not creating the entry, then you have no right to set the data of the entry. Doing so could be hazardous depending on what EntryBase subclass you’re dealing with.

Override this.

Parameters:data – the data
set_metadata(key, value)

Sets a key/value pair in the metadata dict.

Override this.

  • key – the key string
  • value – the value string

This takes in a given time tuple and sets all the magic metadata variables we have according to the items in the time tuple.

Parameters:timetuple – the timetuple to use to set the data with–this is the same thing as the mtime/atime portions of an os.stat. This time is expected to be local time, not UTC.

Updates the contents in this entry with the contents in the dict. It does so by calling set_data and set_metadata.


There’s no reason to override this–override set_data and set_metadata instead.

Parameters:newdict – the dict we’re updating this one with
Pyblosxom.entries.base.generate_entry(request, properties, data, mtime=None)

Takes a properties dict and a data string and generates a generic entry using the data you provided.

  • request – the Request object
  • properties – the dict of properties for the entry
  • data – the data content for the entry
  • mtime – the mtime tuple (as given by time.localtime()). if you pass in None, then we’ll use localtime.

Table Of Contents

Previous topic

Writing Plugins

Next topic


This Page