This chapter covers important functions, methods and classes in Pyblosxom. When in doubt, read the code.
This is the main module for Pyblosxom functionality. Pyblosxom’s setup and default handlers are defined here.
Wrapper around a dict to provide a backwards compatible way to get the form with syntax as:
request.get_http()['form']
instead of:
request.get_form()
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.
DEPRECATED. Use get_request instead.
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. |
|---|
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. |
Renders a single page from the blog.
| Parameters: |
|
|---|
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 self.run() 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. |
|---|
This class is the WSGI application for Pyblosxom.
Executes a single run of Pyblosxom wrapped in the crash handler.
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.
DEPRECATED. Use add_configuration instead.
DEPRECATED. Use add_data instead.
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.
DEPRECATED. Use get_configuration instead.
DEPRECATED. Use get_data instead.
DEPRECATED. Use get_form instead.
DEPRECATED. Use get_http instead.
DEPRECATED. Use get_response instead.
Returns the actual configuration dict. The configuration dict holds values that the user sets in their config.py 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.
DEPRECATED. Use set_response instead.
Sets the Response object.
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.
DEPRECATED. Use add_header instead.
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.
Example:
>>> 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. | |
DEPRECATED. Use get_headers instead.
Returns the headers.
Returns the status code and message of this response.
DEPRECATED. Use send_body instead.
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.
Note
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. |
|---|
DEPRECATED. Use set_status instead.
Sets the status code for this response. The status should be a valid HTTP response status.
Examples:
>>> resp = Response('some fake request')
>>> resp.set_status("200 OK")
>>> resp.set_status("404 Not Found")
| Parameters: | status – the status string. |
|---|
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 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:
Also, for backwards compatibility reasons, we convert things like:
$id_escaped
$id_urlencoded
$(id_escaped)
$(id_urlencoded)
to:
$escape(id)
$urlencode(id)
| 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.
Implements unknown_starttag. Appends a space to the buffer.
DEPRECATED. Use walk instead.
Adds a cr if it needs one.
>>> addcr("foo")
'foo\n'
>>> addcr("foo\n")
'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.
1 2 3 4 5 6 7 8 9 10 11 12 | >>> commasplit(None)
[]
>>> commasplit("")
['']
>>> commasplit("a")
['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 |
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.
| Parameters: |
|
|---|---|
| Raises IOError: | if the datadir + category directory exists, but isn’t a directory |
Takes in a string and converts:
Note: if s is None, then we return None.
1 2 3 4 5 6 7 | >>> escape_text(None)
>>> escape_text("")
''
>>> escape_text("a'b")
'a'b'
>>> escape_text('a"b')
'a"b'
|
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.
| Parameters: |
|
|---|---|
| Returns: | the filestat (tuple of 9 ints) on the given file |
DEPRECATED. Use generate_rand_str instead.
Generate a random string between minlen and maxlen characters long.
The generated string consists of letters and numbers.
| Parameters: |
|
|---|---|
| Returns: | generated string |
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 config.py 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 config.py 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. |
Safely imports modules for runtime importing.
| Parameters: |
|
|---|---|
| Returns: | 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 config.py 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:
| Parameters: | s – the string to check for “year-hood” |
|---|---|
| Returns: | True if it is a year and False otherwise. |
Logs some info about the calling function/method. Useful for debugging.
Usage:
>>> import tools
>>> tools.log_caller() # logs frame 1
>>> tools.log_caller(2)
>>> tools.log_caller(3, log_file="/path/to/file")
| Parameters: |
|
|---|
Logs an exception to the given file. Uses the system-wide log_file as defined in config.py 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 config.py property and if that’s blank, then the log_file is stderr |
|---|
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.
| Parameters: |
|
|---|---|
| Returns: | the template string with template variables expanded. |
Wraps the text and prints it.
Wraps an error message and prints it to stderr.
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.
| Parameters: |
|
|---|---|
| Returns: | a Pyblosxom Response object. |
Renders a url and saves the rendered output to the filesystem.
| Parameters: |
|
|---|
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.
| Parameters: |
|
|---|---|
| Returns: | varies |
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.
| Parameters: |
|
|---|
Calls urllib.quote on the string s.
Note: if s is None, then we return None.
1 2 3 4 5 6 7 8 9 | >>> urlencode_text(None)
>>> urlencode_text("")
''
>>> urlencode_text("a c")
'a%20c'
>>> urlencode_text("a&c")
'a%26c'
>>> urlencode_text("a=c")
'a%3Dc'
|
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:
config.py["ignore_directories"] = ["CVS", "dev/pyblosxom"]
turns into the regexp:
.*?(CVS|dev/pyblosxom)$
It will also skip all directories that start with a period.
| Parameters: |
|
|---|---|
| Returns: | a list of file paths. |
Takes in a filepath and a list of extensions and tries them all until it finds the first extension that works.
| Parameters: |
|
|---|---|
| Returns: | 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.
This is a null renderer.
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.
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 | |
DEPRECATED. Use get_content instead.
Return the content field
This is exposed for blosxom callbacks.
| Returns: | content |
|---|
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 |
|---|
DEPRECATED. Use set_content instead.
Sets the content. The content can be any of the following:
| Parameters: | content – the content to be displayed |
|---|
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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 | 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))
renderer.showHeaders()
# Write to output
renderer.write(data)
# 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.
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"]
True
DEPRECATED. Use add_to_cache instead.
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.
| Parameters: |
|
|---|
Retrieves an item from the internal dict based on the key given.
All this does is turn aroun and call __getitem__.
Warning
There’s no reason to override this–override get_data and get_metadata instead.
| Parameters: |
|
|---|---|
| Returns: | the value of get_metadata or get_data (through __getitem__) |
DEPRECATED. Use get_data instead.
DEPRECATED. Use get_from_cache instead.
DEPRECATED. Use get_id instead.
DEPRECATED. Use get_metadata instead.
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 |
|---|
Returns a given piece of metadata.
Override this.
| Parameters: |
|
|---|---|
| Returns: | 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.
Note
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.
Warning
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__.
Warning
There’s no reason to override this–override get_metadata_keys instead.
| Returns: | list of key names |
|---|
DEPRECATED. Use set_data instead.
DEPRECATED. Use set_metadata instead.
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 |
|---|
Sets a key/value pair in the metadata dict.
Override this.
| Parameters: |
|
|---|
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.
Warning
There’s no reason to override this–override set_data and set_metadata instead.
| Parameters: | newdict – the dict we’re updating this one with |
|---|
Takes a properties dict and a data string and generates a generic entry using the data you provided.
| Parameters: |
|
|---|