<commit_before># vim: tabstop=4 shiftwidth=4
"""
This module holds a series of connectors that plugins can replace
(in the case of callbacks) or add themselves to (in the case of
callback chains and callback handlers).

Callbacks allow us to override pyblosxom behavior by adding in a 
plugin module.

Callback chains allow us to add onto pyblosxom behavior and the
behavior of other plugin modules where each link in the chain
takes a given input, modifies it, and then passes it to the
next link in the chain as input.

Because pyblosxom is a CGI process, these mechanisms are designed 
to reduce the build cost as well as the run-time cost required.

This module defines a series of callbacks and callbackchains and
what they're used for.<commit_msg>Updated documentation to be epidoc compliant<commit_after># vim: tabstop=4 shiftwidth=4
"""
This module holds a series of connectors that plugins can replace
(in the case of callbacks) or add themselves to (in the case of
callback chains and callback handlers).

Callbacks allow us to override pyblosxom behavior by adding in a 
plugin module.

Callback chains allow us to add onto pyblosxom behavior and the
behavior of other plugin modules where each link in the chain
takes a given input, modifies it, and then passes it to the
next link in the chain as input.

Because pyblosxom is a CGI process, these mechanisms are designed 
to reduce the build cost as well as the run-time cost required.

This module defines a series of callbacks and callbackchains and
what they're used for.

@var filestat: CallbackChain to generate a os.stat tuple about a given
	file.  call filestat.executeTransform(filename) and get back a
	os.stat like tuple with all the pieces worked out.

	Data dict:
	   - "filename": filename (string)
	   - "mtime": tuple (from os.stat)

@var logRequest:  CallbackChain to do a final logging based on a log
	plugin

	Data dict:
		- "filename": filename to log to (string)
		- "return_code": error code to log (string)

@var fileListHandler:  CallbackChain to generate file list based on a
	plugin
 
	Data dict:
		- "request": the request object

	Output:
		- the list of entries

@var prepareChain: CallbackChain to notify all the plugins of the
	completed request and the entry list.  This allows plugins to modify
	the entry list and add variables to the runtime data dict prior to
	rendering.

	Data dict:
		- "request": Request

@var FIRST: Constant to signify the start of the chain
@var MIDDLE: Constant to signify the middle of the chain
@var LAST: Constant to signify the last part of the chain
@var HANDLED: Constant to signify that a Callback is in fact handled
{'fraction_non_alphanumeric': 0.04234404536862004, 'fraction_numerical': 0.0015122873345935729, 'mean_word_length': 4.188235294117647, 'pattern_counts': {'":': 6, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2789003', 'n_tokens_mistral': 736, 'n_tokens_neox': 704, 'n_words': 417}