around it - append the paragraph bits directly
# onto parent_elem
el = parent_elem
else:
# Otherwise make a "p" element
el = self.doc.createElement("p")
parent_elem.appendChild(el)
for item in list:
el.appendChild(item)
def _processUList(self, parent_elem, lines, inList):
self._processList(parent_elem, lines, inList,
listexpr='ul', tag = 'ul')
def _processOList(self, parent_elem, lines, inList):
self._processList(parent_elem, lines, inList,
listexpr='ol', tag = 'ol')
def _processList(self, parent_elem, lines, inList, listexpr, tag):
"""Given a list of document lines starting with a list item,
finds the end of the list, breaks it up, and recursively
processes each list item and the remainder of the text file.
@param parent_elem: A dom element to which the content will be added
@param lines: a list of lines
@param inList: a level
@returns: None"""
ul = self.doc.createElement(tag) # ul might actually be '
'
parent_elem.appendChild(ul)
looseList = 0
# Make a list of list items
items = []
item = -1
i = 0 # a counter to keep track of where we are
for line in lines:
loose = 0
if not line.strip():
# If we see a blank line, this _might_ be the end of the list
i += 1
loose = 1
# Find the next non-blank line
for j in range(i, len(lines)):
if lines[j].strip():
next = lines[j]
break
else:
# There is no more text => end of the list
break
# Check if the next non-blank line is still a part of the list
if ( RE.regExp['ul'].match(next) or
RE.regExp['ol'].match(next) or
RE.regExp['tabbed'].match(next) ):
# get rid of any white space in the line
items[item].append(line.strip())
looseList = loose or looseList
continue
else:
break # found end of the list
# Now we need to detect list items (at the current level)
# while also detabing child elements if necessary
for expr in ['ul', 'ol', 'tabbed']:
m = RE.regExp[expr].match(line)
if m:
if expr in ['ul', 'ol']: # We are looking at a new item
#if m.group(1) :
# Removed the check to allow for a blank line
# at the beginning of the list item
items.append([m.group(1)])
item += 1
elif expr == 'tabbed': # This line needs to be detabbed
items[item].append(m.group(4)) #after the 'tab'
i += 1
break
else:
items[item].append(line) # Just regular continuation
i += 1 # added on 2006.02.25
else:
i += 1
# Add the dom elements
for item in items:
li = self.doc.createElement("li")
ul.appendChild(li)
self._processSection(li, item, inList + 1, looseList = looseList)
# Process the remaining part of the section
self._processSection(parent_elem, lines[i:], inList)
def _linesUntil(self, lines, condition):
""" A utility function to break a list of lines upon the
first line that satisfied a condition. The condition
argument should be a predicate function.
"""
i = -1
for line in lines:
i += 1
if condition(line): break
else:
i += 1
return lines[:i], lines[i:]
def _processQuote(self, parent_elem, lines, inList):
"""Given a list of document lines starting with a quote finds
the end of the quote, unindents it and recursively
processes the body of the quote and the remainder of the
text file.
@param parent_elem: DOM element to which the content will be added
@param lines: a list of lines
@param inList: a level
@returns: None """
dequoted = []
i = 0
blank_line = False # allow one blank line between paragraphs
for line in lines:
m = RE.regExp['quoted'].match(line)
if m:
dequoted.append(m.group(1))
i += 1
blank_line = False
elif not blank_line and line.strip() != '':
dequoted.append(line)
i += 1
elif not blank_line and line.strip() == '':
dequoted.append(line)
i += 1
blank_line = True
else:
break
blockquote = self.doc.createElement('blockquote')
parent_elem.appendChild(blockquote)
self._processSection(blockquote, dequoted, inList)
self._processSection(parent_elem, lines[i:], inList)
def _processCodeBlock(self, parent_elem, lines, inList):
"""Given a list of document lines starting with a code block
finds the end of the block, puts it into the dom verbatim
wrapped in ("") and recursively processes the
the remainder of the text file.
@param parent_elem: DOM element to which the content will be added
@param lines: a list of lines
@param inList: a level
@returns: None"""
detabbed, theRest = self.blockGuru.detectTabbed(lines)
pre = self.doc.createElement('pre')
code = self.doc.createElement('code')
parent_elem.appendChild(pre)
pre.appendChild(code)
text = "\n".join(detabbed).rstrip()+"\n"
#text = text.replace("&", "&")
code.appendChild(self.doc.createTextNode(text))
self._processSection(parent_elem, theRest, inList)
def _handleInline (self, line, patternIndex=0):
"""Transform a Markdown line with inline elements to an XHTML
fragment.
This function uses auxiliary objects called inline patterns.
See notes on inline patterns above.
@param line: A line of Markdown text
@param patternIndex: The index of the inlinePattern to start with
@return: A list of NanoDom nodes """
parts = [line]
while patternIndex < len(self.inlinePatterns):
i = 0
while i < len(parts):
x = parts[i]
if isinstance(x, (str, unicode)):
result = self._applyPattern(x, \
self.inlinePatterns[patternIndex], \
patternIndex)
if result:
i -= 1
parts.remove(x)
for y in result:
parts.insert(i+1,y)
i += 1
patternIndex += 1
for i in range(len(parts)):
x = parts[i]
if isinstance(x, (str, unicode)):
parts[i] = self.doc.createTextNode(x)
return parts
def _applyPattern(self, line, pattern, patternIndex):
""" Given a pattern name, this function checks if the line
fits the pattern, creates the necessary elements, and returns
back a list consisting of NanoDom elements and/or strings.
@param line: the text to be processed
@param pattern: the pattern to be checked
@returns: the appropriate newly created NanoDom element if the
pattern matches, None otherwise.
"""
# match the line to pattern's pre-compiled reg exp.
# if no match, move on.
m = pattern.getCompiledRegExp().match(line)
if not m:
return None
# if we got a match let the pattern make us a NanoDom node
# if it doesn't, move on
node = pattern.handleMatch(m, self.doc)
# check if any of this nodes have children that need processing
if isinstance(node, Element):
if not node.nodeName in ["code", "pre"]:
for child in node.childNodes:
if isinstance(child, TextNode):
result = self._handleInline(child.value, patternIndex+1)
if result:
if result == [child]:
continue
result.reverse()
#to make insertion easier
position = node.childNodes.index(child)
node.removeChild(child)
for item in result:
if isinstance(item, (str, unicode)):
if len(item) > 0:
node.insertChild(position,
self.doc.createTextNode(item))
else:
node.insertChild(position, item)
if node:
# Those are in the reverse order!
return ( m.groups()[-1], # the string to the left
node, # the new node
m.group(1)) # the string to the right of the match
else:
return None
def convert (self, source = None):
"""Return the document in XHTML format.
@returns: A serialized XHTML body."""
if source is not None: #Allow blank string
self.source = source
if not self.source:
return u""
try:
self.source = unicode(self.source)
except UnicodeDecodeError:
message(CRITICAL, 'UnicodeDecodeError: Markdown only accepts unicode or ascii input.')
return u""
for pp in self.textPreprocessors:
self.source = pp.run(self.source)
doc = self._transform()
xml = doc.toxml()
# Return everything but the top level tag
if self.stripTopLevelTags:
xml = xml.strip()[23:-7] + "\n"
for pp in self.textPostprocessors:
xml = pp.run(xml)
return (self.docType + xml).strip()
def __str__(self):
''' Report info about instance. Markdown always returns unicode. '''
if self.source is None:
status = 'in which no source text has been assinged.'
else:
status = 'which contains %d chars and %d line(s) of source.'%\
(len(self.source), self.source.count('\n')+1)
return 'An instance of "%s" %s'% (self.__class__, status)
__unicode__ = convert # markdown should always return a unicode string
# ====================================================================
def markdownFromFile(input = None,
output = None,
extensions = [],
encoding = None,
message_threshold = CRITICAL,
safe = False):
global console_hndlr
console_hndlr.setLevel(message_threshold)
message(DEBUG, "input file: %s" % input)
if not encoding:
encoding = "utf-8"
input_file = codecs.open(input, mode="r", encoding=encoding)
text = input_file.read()
input_file.close()
text = removeBOM(text, encoding)
new_text = markdown(text, extensions, safe_mode = safe)
if output:
output_file = codecs.open(output, "w", encoding=encoding)
output_file.write(new_text)
output_file.close()
else:
sys.stdout.write(new_text.encode(encoding))
def markdown(text,
extensions = [],
safe_mode = False):
message(DEBUG, "in markdown.markdown(), received text:\n%s" % text)
extension_names = []
extension_configs = {}
for ext in extensions:
pos = ext.find("(")
if pos == -1:
extension_names.append(ext)
else:
name = ext[:pos]
extension_names.append(name)
pairs = [x.split("=") for x in ext[pos+1:-1].split(",")]
configs = [(x.strip(), y.strip()) for (x, y) in pairs]
extension_configs[name] = configs
md = Markdown(extensions=extension_names,
extension_configs=extension_configs,
safe_mode = safe_mode)
return md.convert(text)
class Extension:
def __init__(self, configs = {}):
self.config = configs
def getConfig(self, key):
if self.config.has_key(key):
return self.config[key][0]
else:
return ""
def getConfigInfo(self):
return [(key, self.config[key][1]) for key in self.config.keys()]
def setConfig(self, key, value):
self.config[key][0] = value
OPTPARSE_WARNING = """
Python 2.3 or higher required for advanced command line options.
For lower versions of Python use:
%s INPUT_FILE > OUTPUT_FILE
""" % EXECUTABLE_NAME_FOR_USAGE
def parse_options():
try:
optparse = __import__("optparse")
except:
if len(sys.argv) == 2:
return {'input': sys.argv[1],
'output': None,
'message_threshold': CRITICAL,
'safe': False,
'extensions': [],
'encoding': None }
else:
print OPTPARSE_WARNING
return None
parser = optparse.OptionParser(usage="%prog INPUTFILE [options]")
parser.add_option("-f", "--file", dest="filename",
help="write output to OUTPUT_FILE",
metavar="OUTPUT_FILE")
parser.add_option("-e", "--encoding", dest="encoding",
help="encoding for input and output files",)
parser.add_option("-q", "--quiet", default = CRITICAL,
action="store_const", const=60, dest="verbose",
help="suppress all messages")
parser.add_option("-v", "--verbose",
action="store_const", const=INFO, dest="verbose",
help="print info messages")
parser.add_option("-s", "--safe", dest="safe", default=False,
metavar="SAFE_MODE",
help="same mode ('replace', 'remove' or 'escape' user's HTML tag)")
parser.add_option("--noisy",
action="store_const", const=DEBUG, dest="verbose",
help="print debug messages")
parser.add_option("-x", "--extension", action="append", dest="extensions",
help = "load extension EXTENSION", metavar="EXTENSION")
(options, args) = parser.parse_args()
if not len(args) == 1:
parser.print_help()
return None
else:
input_file = args[0]
if not options.extensions:
options.extensions = []
return {'input': input_file,
'output': options.filename,
'message_threshold': options.verbose,
'safe': options.safe,
'extensions': options.extensions,
'encoding': options.encoding }
if __name__ == '__main__':
""" Run Markdown from the command line. """
options = parse_options()
#if os.access(inFile, os.R_OK):
if not options:
sys.exit(0)
markdownFromFile(**options)
WebHelpers-1.3/webhelpers/text.py 0000664 0001750 0001750 00000031717 11471126331 016507 0 ustar sluggo sluggo # coding: utf-8
"""Functions that output text (not HTML).
Helpers for filtering, formatting, and transforming strings.
"""
import re
import textwrap
import urllib
from webhelpers.html.tools import strip_tags
try:
from unidecode import unidecode
except ImportError:
unidecode = None
__all__ = [
"chop_at",
"collapse",
"convert_accented_entities",
#"convert_misc_characters", # DISABLED
"convert_misc_entities",
"excerpt",
"lchop",
"plural",
"rchop",
"remove_formatting",
"replace_whitespace",
"series",
"strip_leading_whitespace",
"truncate",
"urlify",
"wrap_paragraphs",
]
def truncate(text, length=30, indicator='...', whole_word=False):
"""Truncate ``text`` with replacement characters.
``length``
The maximum length of ``text`` before replacement
``indicator``
If ``text`` exceeds the ``length``, this string will replace
the end of the string
``whole_word``
If true, shorten the string further to avoid breaking a word in the
middle. A word is defined as any string not containing whitespace.
If the entire text before the break is a single word, it will have to
be broken.
Example::
>>> truncate('Once upon a time in a world far far away', 14)
'Once upon a...'
"""
if not text:
return ""
if len(text) <= length:
return text
short_length = length - len(indicator)
if not whole_word:
return text[:short_length] + indicator
# Go back to end of previous word.
i = short_length
while i >= 0 and not text[i].isspace():
i -= 1
while i >= 0 and text[i].isspace():
i -= 1
#if i < short_length:
# i += 1 # Set to one after the last char we want to keep.
if i <= 0:
# Entire text before break is one word, or we miscalculated.
return text[:short_length] + indicator
return text[:i+1] + indicator
def excerpt(text, phrase, radius=100, excerpt_string="..."):
"""Extract an excerpt from the ``text``, or '' if the phrase isn't
found.
``phrase``
Phrase to excerpt from ``text``
``radius``
How many surrounding characters to include
``excerpt_string``
Characters surrounding entire excerpt
Example::
>>> excerpt("hello my world", "my", 3)
'...lo my wo...'
"""
if not text or not phrase:
return text
pat = re.compile('(.{0,%s}%s.{0,%s})' % (radius, re.escape(phrase),
radius), re.I)
match = pat.search(text)
if not match:
return ""
excerpt = match.expand(r'\1')
if match.start(1) > 0:
excerpt = excerpt_string + excerpt
if match.end(1) < len(text):
excerpt = excerpt + excerpt_string
if hasattr(text, '__html__'):
return literal(excertp)
else:
return excerpt
def plural(n, singular, plural, with_number=True):
"""Return the singular or plural form of a word, according to the number.
If ``with_number`` is true (default), the return value will be the number
followed by the word. Otherwise the word alone will be returned.
Usage:
>>> plural(2, "ox", "oxen")
'2 oxen'
>>> plural(2, "ox", "oxen", False)
'oxen'
"""
if n == 1:
form = singular
else:
form = plural
if with_number:
return "%s %s" % (n, form)
else:
return form
def chop_at(s, sub, inclusive=False):
"""Truncate string ``s`` at the first occurrence of ``sub``.
If ``inclusive`` is true, truncate just after ``sub`` rather than at it.
>>> chop_at("plutocratic brats", "rat")
'plutoc'
>>> chop_at("plutocratic brats", "rat", True)
'plutocrat'
"""
pos = s.find(sub)
if pos == -1:
return s
if inclusive:
return s[:pos+len(sub)]
return s[:pos]
def lchop(s, sub):
"""Chop ``sub`` off the front of ``s`` if present.
>>> lchop("##This is a comment.##", "##")
'This is a comment.##'
The difference between ``lchop`` and ``s.lstrip`` is that ``lchop`` strips
only the exact prefix, while ``s.lstrip`` treats the argument as a set of
leading characters to delete regardless of order.
"""
if s.startswith(sub):
s = s[len(sub):]
return s
def rchop(s, sub):
"""Chop ``sub`` off the end of ``s`` if present.
>>> rchop("##This is a comment.##", "##")
'##This is a comment.'
The difference between ``rchop`` and ``s.rstrip`` is that ``rchop`` strips
only the exact suffix, while ``s.rstrip`` treats the argument as a set of
trailing characters to delete regardless of order.
"""
if s.endswith(sub):
s = s[:-len(sub)]
return s
def strip_leading_whitespace(s):
"""Strip the leading whitespace in all lines in ``s``.
This deletes *all* leading whitespace. ``textwrap.dedent`` deletes only
the whitespace common to all lines.
"""
ret = [x.lstrip() for x in s.splitlines(True)]
return "".join(ret)
def wrap_paragraphs(text, width=72):
"""Wrap all paragraphs in a text string to the specified width.
``width`` may be an int or a ``textwrap.TextWrapper`` instance.
The latter allows you to set other options besides the width, and is more
efficient when wrapping many texts.
"""
if isinstance(width, textwrap.TextWrapper):
wrapper = width
else:
wrapper = textwrap.TextWrapper(width=width)
result = []
lines = text.splitlines(True)
lines_len = len(lines)
start = 0
end = None
while start < lines_len:
# Leave short lines as-is.
if len(lines[start]) <= width:
result.append(lines[start])
start += 1
continue
# Found a long line, peek forward to end of paragraph.
end = start + 1
while end < lines_len and not lines[end].isspace():
end += 1
# 'end' is one higher than last long lone.
paragraph = ''.join(lines[start:end])
paragraph = wrapper.fill(paragraph) + "\n"
result.append(paragraph)
start = end
end = None
return "".join(result)
def series(items, conjunction="and", strict_commas=True):
"""Join strings using commas and a conjunction such as "and" or "or".
Examples:
>>> series(["A", "B", "C"])
'A, B, and C'
>>> series(["A", "B", "C"], "or")
'A, B, or C'
>>> series(["A", "B", "C"], strict_commas=False)
'A, B and C'
>>> series(["A", "B"])
'A and B'
>>> series(["A"])
'A'
>>> series([])
''
"""
items = list(items)
length = len(items)
if length == 0:
return ""
if length == 1:
return items[0]
if length == 2:
strict_commas = False
nonlast = ", ".join(items[:-1])
last = items[-1]
comma = strict_commas and "," or ""
return "%s%s %s %s" % (nonlast, comma, conjunction, last)
def urlify(string):
"""Create a URI-friendly representation of the string
Can be called manually in order to generate an URI-friendly version
of any string.
If the ``unidecode`` package is installed, it will also transliterate
non-ASCII Unicode characters to their nearest pronounciation equivalent in
ASCII.
Examples::
>>> urlify("Mighty Mighty Bosstones")
'mighty-mighty-bosstones'
Based on Ruby's stringex package
(http://github.com/rsl/stringex/tree/master)
Changed in WebHelpers 1.2: urlecode the result in case it contains special
characters like "?".
"""
s = remove_formatting(string).lower()
s = replace_whitespace(s, '-')
s = collapse(s, '-')
return urllib.quote(s)
def remove_formatting(string):
"""Simplify HTML text by removing tags and several kinds of formatting.
If the ``unidecode`` package is installed, it will also transliterate
non-ASCII Unicode characters to their nearest pronunciation equivalent in
ASCII.
Based on Ruby's stringex package
(http://github.com/rsl/stringex/tree/master)
"""
s = strip_tags(string)
s = convert_accented_entities(s)
s = convert_misc_entities(s)
#s = convert_misc_characters(s)
if unidecode:
s = unidecode(s)
return collapse(s)
def convert_accented_entities(string):
"""Converts HTML entities into the respective non-accented letters.
Examples::
>>> convert_accented_entities("á")
'a'
>>> convert_accented_entities("ç")
'c'
>>> convert_accented_entities("è")
'e'
>>> convert_accented_entities("î")
'i'
>>> convert_accented_entities("ø")
'o'
>>> convert_accented_entities("ü")
'u'
Note: This does not do any conversion of Unicode/ASCII
accented-characters. For that functionality please use unidecode.
Based on Ruby's stringex package
(http://github.com/rsl/stringex/tree/master)
"""
return re.sub(r'\&([A-Za-z])(grave|acute|circ|tilde|uml|ring|cedil|slash);',
r'\1', string)
def convert_misc_entities(string):
"""Converts HTML entities (taken from common Textile formattings)
into plain text formats
Note: This isn't an attempt at complete conversion of HTML
entities, just those most likely to be generated by Textile.
Based on Ruby's stringex package
(http://github.com/rsl/stringex/tree/master)
"""
replace_dict = {
"#822[01]": "\"",
"#821[67]": "'",
"#8230": "...",
"#8211": "-",
"#8212": "--",
"#215": "x",
"gt": ">",
"lt": "<",
"(#8482|trade)": "(tm)",
"(#174|reg)": "(r)",
"(#169|copy)": "(c)",
"(#38|amp)": "and",
"nbsp": " ",
"(#162|cent)": " cent",
"(#163|pound)": " pound",
"(#188|frac14)": "one fourth",
"(#189|frac12)": "half",
"(#190|frac34)": "three fourths",
"(#176|deg)": " degrees"
}
for textiled, normal in replace_dict.items():
string = re.sub(r'\&%s;' % textiled, normal, string)
return re.sub(r'\&[^;]+;', '', string)
'''*** DISABLED convert_misc_characters: fails doc tests.
Confirming what behavior should be.
def convert_misc_characters(string):
"""Converts various common plaintext characters to a more
URI-friendly representation
Examples::
>>> convert_misc_characters("foo & bar")
'foo and bar'
>>> convert_misc_characters("Chanel #9")
'Chanel number nine'
>>> convert_misc_characters("user@host")
'user at host'
>>> convert_misc_characters("google.com")
'google dot com'
>>> convert_misc_characters("$10")
'10 dollars'
>>> convert_misc_characters("*69")
'star 69'
>>> convert_misc_characters("100%")
'100 percent'
>>> convert_misc_characters("windows/mac/linux")
'windows slash mac slash linux'
Note: Because this method will convert any '&' symbols to the string
"and", you should run any methods which convert HTML entities
(convert_html_entities and convert_misc_entities) before running
this method.
Based on Ruby's stringex package
(http://github.com/rsl/stringex/tree/master)
"""
s = re.sub(r'\.{3,}', " dot dot dot ", string)
# Special rules for money
money_replace = {
r'(\s|^)\$(\d+)\.(\d+)(\s|\$)?': r'\2 dollars \3 cents',
r'(\s|^)£(\d+)\.(\d+)(\s|\$)?': r'\2 pounds \3 pence',
}
for repl, subst in money_replace.items():
s = re.sub(repl, r' %s ' % subst, s)
# Back to normal rules
repls = {
r'\s*&\s*': "and",
r'\s*#': "number",
r'\s*@\s*': "at",
r'(\S|^)\.(\S)': r'\1 dot \2',
r'(\s|^)\$(\d*)(\s|$)': r'\2 dollars',
r'(\s|^)£(\d*)(\s|$)': r'\2 pounds',
r'(\s|^)¥(\d*)(\s|$)': r'\2 yen',
r'\s*\*\s*': "star",
r'\s*%\s*': "percent",
r'\s*(\\|\/)\s*': "slash",
}
for repl, subst in repls.items():
s = re.sub(repl, r' %s ' % subst, s)
s = re.sub(r"(^|\w)'(\w|$)", r'\1\2', s)
return re.sub(r"[\.\,\:\;\(\)\[\]\/\?\!\^'\"_]", " ", s)
'''
def replace_whitespace(string, replace=" "):
"""Replace runs of whitespace in string
Defaults to a single space but any replacement string may be
specified as an argument. Examples::
>>> replace_whitespace("Foo bar")
'Foo bar'
>>> replace_whitespace("Foo bar", "-")
'Foo-bar'
Based on Ruby's stringex package
(http://github.com/rsl/stringex/tree/master)
"""
return re.sub(r'\s+', replace, string)
def collapse(string, character=" "):
"""Removes specified character from the beginning and/or end of the
string and then condenses runs of the character within the string.
Based on Ruby's stringex package
(http://github.com/rsl/stringex/tree/master)
"""
reg = re.compile('(%s){2,}' % character)
return re.sub(reg, character, string.strip(character))
WebHelpers-1.3/webhelpers/public/ 0000775 0001750 0001750 00000000000 11542603374 016424 5 ustar sluggo sluggo WebHelpers-1.3/webhelpers/public/stylesheets/ 0000775 0001750 0001750 00000000000 11542603374 021000 5 ustar sluggo sluggo WebHelpers-1.3/webhelpers/public/stylesheets/grid.css 0000664 0001750 0001750 00000004163 11373653355 022451 0 ustar sluggo sluggo /******************* tables ****************/
table.stylized {
background-color: #ffffff;
border-collapse: separate;
border-spacing: 1px;
border-bottom: 2px solid #666666;
margin: 1px 5px 5px 5px;
-moz-border-radius: 5px;
-webkit-border-radius: 5px;
width: 100%;
border-collapse: collapse;
}
table.stylized caption {
color: #ffffff;
background-color: #444466;
padding: 5px;
font-size: 1.3em;
font-weight: bold;
margin: 5px 0px 0px 0px;
-moz-border-radius: 5px;
-webkit-border-radius: 5px;
}
table.stylized caption a:link,table.stylized caption a:visited {
color: #ffffff;
text-decoration: none;
font-weight: bold;
}
table.stylized caption a:link,table.stylized caption a:hover {
color: #ffcc00;
text-decoration: none;
font-weight: bold;
}
table.stylized thead {
background-color: #ffffff;
}
table.stylized tbody {
background-color: #ffffff;
}
table.stylized tfooter {
background-color: #ffffff;
}
table.stylized th {
text-align: center;
}
table.stylized tr.header {
text-align: center;
}
table.stylized tr.header td, table.stylized th {
text-align: center;
color: #ffffff;
background-color: #444466;
}
table.stylized td {
padding: 5px 5px 5px 5px;
border: 1px solid #dcdcdc;
}
table.stylized tr.odd td {
border-top: 1px solid #999 !important;
background-color: #ffffff;
}
table.stylized tr.even td {
border-top: 1px solid #999 !important;
background-color: #f6f6f6;
}
table.stylized .no {
width: 30px;
}
table.stylized td.ordering{
background-color: #666666 !important;
padding-right: 20px;
}
table.stylized td.ordering.dsc .marker {
height: 20px;
width: 20px;
display: block;
float: right;
margin: 0px -18px;
/* background-image for neutral marker here */
}
table.stylized td.ordering.dsc .marker {
/* background-image for dsc marker here */
}
table.stylized td.ordering.asc .marker {
/* background-image for asc marker here */
}
table.stylized .header a:link,table.stylized .header a:visited {
color: #ffffff;
text-decoration: none;
font-weight: bold;
}
table.stylized td.ordering a:link,table.stylized td.ordering a:visited {
color: #ffcc00;
text-decoration: none;
font-weight: bold;
}
WebHelpers-1.3/webhelpers/public/stylesheets/webhelpers.css 0000644 0001750 0001750 00000002306 11373653355 023657 0 ustar sluggo sluggo /* Sample stylesheet for WebHelpers */
/* === STYLES FOR webhelpers.html.tags === */
/* Display the required symbol "*" in red.
* Used by title() and required_legend().
*/
span.required-symbol {
color: red;
}
/* Display the title for required fields in boldface.
* Used by title() and required_legend().
*/
span.required {
font-weight: bold;
}
/* Display the title for non-required fields in normal type.
* (Some sites may prefer to set this to boldface too.)
* Used by title().
*/
span.not-required {
}
/* === EXTRA STYLES (not currently produced by any helpers) === */
/* Make field error messages highly visible:
* big and red on a light red background.
* 'error-message' is the default class used by ``formencode.htmlfill``
* and by any future field helper.
*/
.error-message {
color: #cc0000;
background-color: #ffeeee;
font-size: large;
font-weight: bold;
font-style: italic;
}
/* Make field help text green italic. */
.hint {
color: #006400;
font-style: italic;
}
/* Standard forms have a distinct background and space around them. */
form.standard {
background-color: #F2F2F2;
margin: 1em 0;
padding: 0.5em 1em 1em 1em;
}
WebHelpers-1.3/webhelpers/number.py 0000664 0001750 0001750 00000034107 11535740723 017017 0 ustar sluggo sluggo """Number formatting, numeric helpers, and numeric statistics."""
import math
import re
#### Calculations ####
def percent_of(part, whole):
"""What percent of ``whole`` is ``part``?
>>> percent_of(5, 100)
5.0
>>> percent_of(13, 26)
50.0
"""
# Use float to force true division.
return float(part * 100) / whole
#### Statistics ####
def mean(r):
"""Return the mean (i.e., average) of a sequence of numbers.
>>> mean([5, 10])
7.5
"""
try:
return float(sum(r)) / len(r)
except ZeroDivisionError:
raise ValueError("can't calculate mean of empty collection")
average = mean
def median(r):
"""Return the median of an iterable of numbers.
The median is the point at which half the numbers are lower than it and
half the numbers are higher. This gives a better sense of the majority
level than the mean (average) does, because the mean can be skewed by a few
extreme numbers at either end. For instance, say you want to calculate
the typical household income in a community and you've sampled four
households:
>>> incomes = [18000] # Fast food crew
>>> incomes.append(24000) # Janitor
>>> incomes.append(32000) # Journeyman
>>> incomes.append(44000) # Experienced journeyman
>>> incomes.append(67000) # Manager
>>> incomes.append(9999999) # Bill Gates
>>> median(incomes)
49500.0
>>> mean(incomes)
1697499.8333333333
The median here is somewhat close to the majority of incomes, while the
mean is far from anybody's income.
This implementation makes a temporary list of all numbers in memory.
"""
s = list(r)
s_len = len(s)
if s_len == 0:
raise ValueError("can't calculate mean of empty collection")
s.sort()
center = s_len // 2
is_odd = s_len % 2
if is_odd:
return s[center] # Return the center element.
# Return the average of the two elements nearest the center.
low = s[center-1]
high = s[center+1]
return mean([low, high])
def standard_deviation(r, sample=True):
"""Standard deviation.
`From the Python Cookbook
`_.
Population mode contributed by Lorenzo Catucci.
Standard deviation shows the variability within a sequence of numbers.
A small standard deviation means the numbers are close to each other. A
large standard deviation shows they are widely different. In fact it
shows how far the numbers tend to deviate from the average. This can be
used to detect whether the average has been skewed by a few extremely high
or extremely low values.
Most natural and random phenomena follow the normal distribution (aka the
bell curve), which says that most values are close to average but a few are
extreme. E.g., most people are close to 5'9" tall but a few are very tall
or very short. If the data does follow the bell curve, 68% of the values
will be within 1 standard deviation (stdev) of the average, and 95% will be
within 2 standard deviations. So a university professor grading exams on a
curve might give a "C" (mediocre) grade to students within 1 stdev of the
average score, "B" (better than average) to those within 2 stdevs above,
and "A" (perfect) to the 0.25% higher than 2 stdevs. Those between 1 and 2
stdevs below get a "D" (poor), and those below 2 stdevs... we won't talk
about them.
By default the helper computes the unbiased estimate
for the population standard deviation, by applying an unbiasing
factor of sqrt(N/(N-1)).
If you'd rather have the function compute the population standard
deviation, pass ``sample=False``.
The following examples are taken from Wikipedia.
http://en.wikipedia.org/wiki/Standard_deviation
>>> standard_deviation([0, 0, 14, 14]) # doctest: +ELLIPSIS
8.082903768654761...
>>> standard_deviation([0, 6, 8, 14]) # doctest: +ELLIPSIS
5.773502691896258...
>>> standard_deviation([6, 6, 8, 8])
1.1547005383792515
>>> standard_deviation([0, 0, 14, 14], sample=False)
7.0
>>> standard_deviation([0, 6, 8, 14], sample=False)
5.0
>>> standard_deviation([6, 6, 8, 8], sample=False)
1.0
(The results reported in Wikipedia are those expected for whole
population statistics and therefore are equal to the ones we get
by setting ``sample=False`` in the later tests.)
.. code-block:: pycon
# Fictitious average monthly temperatures in Southern California.
# Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec
>>> standard_deviation([70, 70, 70, 75, 80, 85, 90, 95, 90, 80, 75, 70]) # doctest: +ELLIPSIS
9.003366373785...
>>> standard_deviation([70, 70, 70, 75, 80, 85, 90, 95, 90, 80, 75, 70], sample=False) # doctest: +ELLIPSIS
8.620067027323...
# Fictitious average monthly temperatures in Montana.
# Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec
>>> standard_deviation([-32, -10, 20, 30, 60, 90, 100, 80, 60, 30, 10, -32]) # doctest: +ELLIPSIS
45.1378360405574...
>>> standard_deviation([-32, -10, 20, 30, 60, 90, 100, 80, 60, 30, 10, -32], sample=False) # doctest: +ELLIPSIS
43.2161878106906...
"""
avg = average(r)
sdsq = sum([(i - avg) ** 2 for i in r])
if sample:
normal_denom=len(r) - 1 or 1
else:
normal_denom=len(r)
return (sdsq / normal_denom) ** 0.5
class SimpleStats(object):
"""Calculate a few simple statistics on data.
This class calculates the minimum, maximum, and count of all the values
given to it. The values are not saved in the object. Usage::
>>> stats = SimpleStats()
>>> stats(2) # Add one data value.
>>> stats.extend([6, 4]) # Add several data values at once.
The statistics are available as instance attributes::
>>> stats.count
3
>>> stats.min
2
>>> stats.max
6
Non-numeric data is also allowed:
>>> stats2 = SimpleStats()
>>> stats2("foo")
>>> stats2("bar")
>>> stats2.count
2
>>> stats2.min
'bar'
>>> stats2.max
'foo'
``.min`` and ``.max`` are ``None`` until the first data value is
registered.
Subclasses can override ``._init_stats`` and ``._update_stats`` to add
additional statistics.
The constructor accepts one optional argument, ``numeric``. If true, the
instance accepts only values that are ``int``, ``long``, or ``float``.
The default is false, which accepts any value. This is meant for instances
or subclasses that don't want non-numeric values.
"""
__version__ = 1
def __init__(self, numeric=False):
self.numeric = numeric
self.count = 0
self.min = None
self.max = None
self._init_stats()
def __nonzero__(self):
"""The instance is true if it has seen any data."""
return bool(self.count)
def __call__(self, value):
"""Add a data value."""
if self.numeric:
value + 0 # Raises TypeError if value is not numeric.
if self.count == 0:
self.min = self.max = value
else:
self.min = min(self.min, value)
self.max = max(self.max, value)
self.count += 1
self._update_stats(value)
def extend(self, values):
"""Add several data values at once, akin to ``list.extend``."""
for value in values:
self(value)
### Hooks for subclasses
def _init_stats(self):
"""Initialize state data used by subclass statistics."""
pass
def _update_stats(self, value):
"""Add a value to the subclass statistics."""
pass
class Stats(SimpleStats):
"""A container for data and statistics.
This class extends ``SimpleStats`` by calculating additional statistics,
and by storing all data seen. All values must be numeric (``int``,
``long``, and/or ``float``), and you must call ``.finish()`` to generate
the additional statistics. That's because the statistics here cannot be
calculated incrementally, but only after all data is known.
>>> stats = Stats()
>>> stats.extend([5, 10, 10])
>>> stats.count
3
>>> stats.finish()
>>> stats.mean # doctest: +ELLIPSIS
8.33333333333333...
>>> stats.median
10
>>> stats.standard_deviation
2.8867513459481287
All data is stored in a list and a set for later use::
>>> stats.list
[5, 10, 10]
>> stats.set
set([5, 10])
(The double prompt ">>" is used to hide the example from doctest.)
The stat attributes are ``None`` until you call ``.finish()``. It's
permissible -- though not recommended -- to add data after calling
``.finish()`` and then call ``.finish()`` again. This recalculates the
stats over the entire data set.
In addition to the hook methods provided by ``SimpleStats``, subclasses
can override ``._finish-stats`` to provide additional statistics.
"""
__version__ = 1
def __init__(self):
SimpleStats.__init__(self, numeric=True)
self.list = []
self.set = set()
self.mean = None
self.median = None
self.standard_deviation = None
self._init_stats()
def __call__(self, value):
"""Add a data value."""
if self.count == 0:
self.min = self.max = value
else:
self.min = min(self.min, value)
self.max = max(self.max, value)
self.count += 1
self._update_stats(value)
self.list.append(value)
self.set.add(value)
def finish(self):
"""Finish calculations. (Call after adding all data values.)
Call this after adding all data values, or the results will be
incomplete.
"""
self.mean = mean(self.list)
self.median = median(self.list)
self.standard_deviation = standard_deviation(self.list)
self._finish_stats()
### Hooks for subclasses.
def _finish_stats(self):
"""Finish the subclass statistics now that all data are known."""
pass
#### Number formatting ####
def format_number(n, thousands=",", decimal="."):
"""Format a number with a thousands separator and decimal delimiter.
``n`` may be an int, long, float, or numeric string.
``thousands`` is a separator to put after each thousand.
``decimal`` is the delimiter to put before the fractional portion if any.
The default style has a thousands comma and decimal point per American
usage:
>>> format_number(1234567.89)
'1,234,567.89'
>>> format_number(123456)
'123,456'
>>> format_number(-123)
'-123'
Various European and international styles are also possible:
>>> format_number(1234567.89, " ")
'1 234 567.89'
>>> format_number(1234567.89, " ", ",")
'1 234 567,89'
>>> format_number(1234567.89, ".", ",")
'1.234.567,89'
"""
parts = str(n).split(".")
parts[0] = re.sub(
R"(\d)(?=(\d\d\d)+(?!\d))",
R"\1%s" % thousands,
parts[0])
return decimal.join(parts)
def format_data_size(size, unit, precision=1, binary=False, full_name=False):
"""Format a number using SI units (kilo, mega, etc.).
``size``: The number as a float or int.
``unit``: The unit name in plural form. Examples: "bytes", "B".
``precision``: How many digits to the right of the decimal point. Default
is 1. 0 suppresses the decimal point.
``binary``: If false, use base-10 decimal prefixes (kilo = K = 1000).
If true, use base-2 binary prefixes (kibi = Ki = 1024).
``full_name``: If false (default), use the prefix abbreviation ("k" or
"Ki"). If true, use the full prefix ("kilo" or "kibi"). If false,
use abbreviation ("k" or "Ki").
Examples:
>>> format_data_size(1024, "B")
'1.0 kB'
>>> format_data_size(1024, "B", 2)
'1.02 kB'
>>> format_data_size(1024, "B", 2, binary=True)
'1.00 KiB'
>>> format_data_size(54000, "Wh", 0)
'54 kWh'
>>> format_data_size(85000, "m/h", 0)
'85 km/h'
>>> format_data_size(85000, "m/h", 0).replace("km/h", "klicks")
'85 klicks'
"""
# Contributed by Wojciech Malinowski
if full_name is None:
full_name = len(unit) > 1
if not binary:
base = 1000
if full_name:
multiples = ('', 'kilo', 'mega', 'giga', 'tera', 'peta', 'exa', 'zetta', 'yotta')
else:
multiples = ('', 'k', 'M', 'G', 'T', 'P', 'E', 'Z', 'Y')
else:
base = 1024
if full_name:
multiples = ('', 'kibi', 'mebi', 'gibi', 'tebi', 'pebi', 'exbi', 'zebi', 'yobi')
else:
multiples = ('', 'Ki', 'Mi', 'Gi', 'Ti', 'Pi', 'Ei', 'Zi', 'Yi')
if size <= 0:
m = 0
else:
m = int(math.log(size) / math.log(base))
if m > 8:
m = 8
if m == 0:
precision = '%.0f'
else:
precision = '%%.%df' % precision
size = precision % (size / math.pow(base, m))
return '%s %s%s' % (size.strip(), multiples[m], unit)
def format_byte_size(size, precision=1, binary=False, full_name=False):
"""Same as ``format_data_size`` but specifically for bytes.
Examples:
>>> format_byte_size(2048)
'2.0 kB'
>>> format_byte_size(2048, full_name=True)
'2.0 kilobytes'
"""
if full_name:
return format_data_size(size, "bytes", precision, binary, True)
else:
return format_data_size(size, "B", precision, binary, False)
def format_bit_size(size, precision=1, binary=False, full_name=False):
"""Same as ``format_data_size`` but specifically for bits.
Examples:
>>> format_bit_size(2048)
'2.0 kb'
>>> format_bit_size(2048, full_name=True)
'2.0 kilobits'
"""
if full_name:
return format_data_size(size, "bits", precision, binary, True)
else:
return format_data_size(size, "b", precision, binary, False)
if __name__ == "__main__":
import doctest
doctest.testmod()
WebHelpers-1.3/webhelpers/__init__.py 0000664 0001750 0001750 00000000161 11445174513 017255 0 ustar sluggo sluggo """WebHelpers is wide variety of functions for web applications and other
applications.
"""
__version__ = "1.3"
WebHelpers-1.3/webhelpers/containers.py 0000664 0001750 0001750 00000044174 11471126331 017671 0 ustar sluggo sluggo """Container objects, and helpers for lists and dicts.
This would have been called this "collections" except that Python 2 can't
import a top-level module that's the same name as a module in the current
package.
"""
import sys
from webhelpers.misc import NotGiven
try:
from collections import defaultdict
except ImportError: # Python < 2.5
class defaultdict(dict):
"""Backport of Python 2.5's ``defaultdict``.
From the Python Cookbook. Written by Jason Kirtland.
http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/523034
"""
def __init__(self, default_factory=None, *a, **kw):
if (default_factory is not None and
not hasattr(default_factory, '__call__')):
raise TypeError('first argument must be callable')
dict.__init__(self, *a, **kw)
self.default_factory = default_factory
def __getitem__(self, key):
try:
return dict.__getitem__(self, key)
except KeyError:
return self.__missing__(key)
def __missing__(self, key):
if self.default_factory is None:
raise KeyError(key)
self[key] = value = self.default_factory()
return value
def __reduce__(self):
if self.default_factory is None:
args = tuple()
else:
args = self.default_factory,
return type(self), args, None, None, self.items()
def copy(self):
return self.__copy__()
def __copy__(self):
return type(self)(self.default_factory, self)
def __deepcopy__(self, memo):
import copy
return type(self)(self.default_factory,
copy.deepcopy(self.items()))
def __repr__(self):
return 'defaultdict(%s, %s)' % (self.default_factory,
dict.__repr__(self))
class DumbObject(object):
"""A container for arbitrary attributes.
Usage::
>>> do = DumbObject(a=1, b=2)
>>> do.b
2
Alternatives to this class include ``collections.namedtuple`` in Python
2.6, and ``formencode.declarative.Declarative`` in Ian Bicking's FormEncode
package. Both alternatives offer more features, but ``DumbObject``
shines in its simplicity and lack of dependencies.
"""
def __init__(self, **kw):
self.__dict__.update(kw)
class Counter(object):
"""I count the number of occurrences of each value registered with me.
Call the instance to register a value. The result is available as the
``.result`` attribute. Example::
>>> counter = Counter()
>>> counter("foo")
>>> counter("bar")
>>> counter("foo")
>>> sorted(counter.result.items())
[('bar', 1), ('foo', 2)]
>> counter.result
{'foo': 2, 'bar': 1}
To see the most frequently-occurring items in order::
>>> counter.get_popular(1)
[(2, 'foo')]
>>> counter.get_popular()
[(2, 'foo'), (1, 'bar')]
Or if you prefer the list in item order::
>>> counter.get_sorted_items()
[('bar', 1), ('foo', 2)]
"""
def __init__(self):
self.result = defaultdict(int)
self.total = 0 # Number of times instance has been called.
def __call__(self, item):
"""Register an item with the counter."""
self.result[item] += 1
self.total += 1
def get_popular(self, max_items=None):
"""Return the results as as a list of ``(count, item)`` pairs, with the
most frequently occurring items first.
If ``max_items`` is provided, return no more than that many items.
"""
data = [(x[1], x[0]) for x in self.result.iteritems()]
data.sort(key=lambda x: (sys.maxint - x[0], x[1]))
if max_items:
return data[:max_items]
else:
return data
def get_sorted_items(self):
"""Return the result as a list of ``(item, count)`` pairs sorted by item.
"""
data = self.result.items()
data.sort()
return data
def correlate(class_, iterable):
"""Build a Counter from an iterable in one step.
This is the same as adding each item individually.
::
>>> counter = Counter.correlate(["A", "B", "A"])
>>> counter.result["A"]
2
>>> counter.result["B"]
1
"""
counter = class_()
for elm in iterable:
counter(elm)
return counter
correlate = classmethod(correlate)
class Accumulator(object):
"""Accumulate a dict of all values for each key.
Call the instance to register a value. The result is available as the
``.result`` attribute. Example::
>>> bowling_scores = Accumulator()
>>> bowling_scores("Fred", 0)
>>> bowling_scores("Barney", 10)
>>> bowling_scores("Fred", 1)
>>> bowling_scores("Barney", 9)
>>> sorted(bowling_scores.result.items())
[('Barney', [10, 9]), ('Fred', [0, 1])]
>> bowling_scores.result
{'Fred': [0, 1], 'Barney': [10, 9]}
The values are stored in the order they're registered.
Alternatives to this class include ``paste.util. multidict.MultiDict``
in Ian Bicking's Paste package.
"""
def __init__(self):
self.result = defaultdict(list)
def __call__(self, key, value):
"""Register a key-value pair."""
self.result[key].append(value)
def correlate(class_, iterable, key):
"""Create an Accumulator based on several related values.
``key`` is a function to calculate the key for each item, akin to
``list.sort(key=)``.
This is the same as adding each item individually.
"""
accumulator = class_()
for v in iterable:
k = key(v)
accumulator(k, v)
return accumulator
correlate = classmethod(correlate)
class UniqueAccumulator(object):
"""Accumulate a dict of unique values for each key.
The values are stored in an unordered set.
Call the instance to register a value. The result is available as the
``.result`` attribute.
"""
def __init__(self):
self.result = defaultdict(set)
def __call__(self, key, value):
"""Register a key-value pair."""
self.result[key].add(value)
def unique(it):
"""Return a list of unique elements in the iterable, preserving the order.
Usage::
>>> unique([None, "spam", 2, "spam", "A", "spam", "spam", "eggs", "spam"])
[None, 'spam', 2, 'A', 'eggs']
"""
seen = set()
ret = []
for elm in it:
if elm not in seen:
ret.append(elm)
seen.add(elm)
return ret
def only_some_keys(dic, keys):
"""Return a copy of the dict with only the specified keys present.
``dic`` may be any mapping. The return value is always a Python dict.
::
>> only_some_keys({"A": 1, "B": 2, "C": 3}, ["A", "C"])
>>> sorted(only_some_keys({"A": 1, "B": 2, "C": 3}, ["A", "C"]).items())
[('A', 1), ('C', 3)]
"""
ret = {}
for key in keys:
ret[key] = dic[key] # Raises KeyError.
return ret
def except_keys(dic, keys):
"""Return a copy of the dict without the specified keys.
::
>>> except_keys({"A": 1, "B": 2, "C": 3}, ["A", "C"])
{'B': 2}
"""
ret = dic.copy()
for key in keys:
try:
del ret[key]
except KeyError:
pass
return ret
def extract_keys(dic, keys):
"""Return two copies of the dict. The first has only the keys specified.
The second has all the *other* keys from the original dict.
::
>> extract_keys({"From": "F", "To": "T", "Received", R"}, ["To", "From"])
({"From": "F", "To": "T"}, {"Received": "R"})
>>> regular, extra = extract_keys({"From": "F", "To": "T", "Received": "R"}, ["To", "From"])
>>> sorted(regular.keys())
['From', 'To']
>>> sorted(extra.keys())
['Received']
"""
for k in keys:
if k not in dic:
raise KeyError("key %r is not in original mapping" % k)
r1 = {}
r2 = {}
for k, v in dic.items():
if k in keys:
r1[k] = v
else:
r2[k] = v
return r1, r2
def ordered_items(dic, key_order, other_keys=True, default=NotGiven):
"""Like ``dict.iteritems()`` but with a specified key order.
Arguments:
* ``dic`` is any mapping.
* ``key_order`` is a list of keys. Items will be yielded in this order.
* ``other_keys`` is a boolean.
* ``default`` is a value returned if the key is not in the dict.
This yields the items listed in ``key_order``. If a key does not exist
in the dict, yield the default value if specified, otherwise skip the
missing key. Afterwards, if ``other_keys`` is true, yield the remaining
items in an arbitrary order.
Usage::
>>> dic = {"To": "you", "From": "me", "Date": "2008/1/4", "Subject": "X"}
>>> dic["received"] = "..."
>>> order = ["From", "To", "Subject"]
>>> list(ordered_items(dic, order, False))
[('From', 'me'), ('To', 'you'), ('Subject', 'X')]
"""
d = dict(dic)
for key in key_order:
if key in d:
yield key, d.pop(key)
elif default is not NotGiven:
yield key, default
if other_keys:
for key, value in d.iteritems():
yield key, value
def get_many(d, required=None, optional=None, one_of=None):
"""Extract values from a dict for unpacking into simple variables.
``d`` is a dict.
``required`` is a list of keys that must be in the dict. The corresponding
values will be the first elements in the return list. Raise KeyError if any
of the keys are missing.
``optional`` is a list of optional keys. The corresponding values will be
appended to the return list, substituting None for missing keys.
``one_of`` is a list of alternative keys. Take the first key that exists
and append its value to the list. Raise KeyError if none of the keys exist.
This argument will append exactly one value if specified, or will do
nothing if not specified.
Example::
uid, action, limit, offset = get_many(request.params,
required=['uid', 'action'], optional=['limit', 'offset'])
Contributed by Shazow.
"""
r = []
if required:
for k in required:
r.append(d[k])
if optional:
for k in optional:
r.append(d.get(k))
if one_of:
for k in one_of:
if k in d:
r.append(d[k])
break
else:
raise KeyError("none of these keys found: %s" % one_of)
return r
def del_quiet(dic, keys):
"""Delete several keys from a dict, ignoring those that don't exist.
This modifies the dict in place.
::
>>> d ={"A": 1, "B": 2, "C": 3}
>>> del_quiet(d, ["A", "C"])
>>> d
{'B': 2}
"""
for key in keys:
try:
del dic[key]
except KeyError:
pass
def correlate_dicts(dicts, key):
"""Correlate several dicts under one superdict.
If you have several dicts each with a 'name' key, this
puts them in a container dict keyed by name.
::
>>> d1 = {"name": "Fred", "age": 41}
>>> d2 = {"name": "Barney", "age": 31}
>>> flintstones = correlate_dicts([d1, d2], "name")
>>> sorted(flintstones.keys())
['Barney', 'Fred']
>>> flintstones["Fred"]["age"]
41
If you're having trouble spelling this method correctly, remember:
"relate" has one 'l'. The 'r' is doubled because it occurs after a prefix.
Thus "correlate".
"""
ret = {}
i = 0
for d in dicts:
try:
my_key = d[key]
except KeyError:
msg = "'dicts' element %d contains no key '%s'"
tup = i, key
raise KeyError(msg % tup)
ret[my_key] = d
i += 1
return ret
def correlate_objects(objects, attr):
"""Correlate several objects under one dict.
If you have several objects each with a 'name' attribute, this
puts them in a dict keyed by name.
::
>>> class Flintstone(DumbObject):
... pass
...
>>> fred = Flintstone(name="Fred", age=41)
>>> barney = Flintstone(name="Barney", age=31)
>>> flintstones = correlate_objects([fred, barney], "name")
>>> sorted(flintstones.keys())
['Barney', 'Fred']
>>> flintstones["Barney"].age
31
If you're having trouble spelling this method correctly, remember:
"relate" has one 'l'. The 'r' is doubled because it occurs after a prefix.
Thus "correlate".
"""
ret = {}
i = 0
for obj in objects:
try:
my_key = getattr(obj, attr)
except AttributeError:
msg = "'%s' object at 'objects[%d]' contains no attribute '%s'"
tup = type(obj).__name__, i, attr
raise AttributeError(msg % tup)
ret[my_key] = obj
i += 1
return ret
def distribute(lis, columns, direction, fill=None):
"""Distribute a list into a N-column table (list of lists).
``lis`` is a list of values to distribute.
``columns`` is an int greater than 1, specifying the number of columns in
the table.
``direction`` is a string beginning with "H" (horizontal) or "V"
(vertical), case insensitive. This affects how values are distributed in
the table, as described below.
``fill`` is a value that will be placed in any remaining cells if the data
runs out before the last row or column is completed. This must be an
immutable value such as ``None`` , ``""``, 0, " ", etc. If you
use a mutable value like ``[]`` and later change any cell containing the
fill value, all other cells containing the fill value will also be changed.
The return value is a list of lists, where each sublist represents a row in
the table.
``table[0]`` is the first row.
``table[0][0]`` is the first column in the first row.
``table[0][1]`` is the second column in the first row.
This can be displayed in an HTML table via the following Mako template:
.. code-block:: html+mako
% for row in table:
% for cell in row:
| ${cell} |
% endfor cell
% endfor row
In a horizontal table, each row is filled before going on to the next row.
This is the same as dividing the list into chunks::
>>> distribute([1, 2, 3, 4, 5, 6, 7, 8], 3, "H")
[[1, 2, 3], [4, 5, 6], [7, 8, None]]
In a vertical table, the first element of each sublist is filled before
going on to the second element. This is useful for displaying an
alphabetical list in columns, or when the entire column will be placed in
a single with a
between each element::
>>> food = ["apple", "banana", "carrot", "daikon", "egg", "fish", "gelato", "honey"]
>>> table = distribute(food, 3, "V", "")
>>> table
[['apple', 'daikon', 'gelato'], ['banana', 'egg', 'honey'], ['carrot', 'fish', '']]
>>> for row in table:
... for item in row:
... print "%-9s" % item,
... print "." # To show where the line ends.
...
apple daikon gelato .
banana egg honey .
carrot fish .
Alternatives to this function include a NumPy matrix of objects.
"""
if columns < 1:
raise ValueError("arg 'columns' must be >= 1")
dir = direction[0].upper()
if dir == "H": # Horizontal table (row-wise)
table = []
for i in range(0, len(lis), columns):
row = lis[i:i+columns]
row_len = len(row)
if row_len < columns:
extra = [fill] * (columns - row_len)
row.extend(extra)
table.append(row)
return table
elif dir == "V": # Vertical table (column-wise)
total = len(lis)
rows, remainder = divmod(total, columns)
if remainder:
rows += 1
table = [[fill] * columns for x in range(rows)]
#print table
for i, elm in enumerate(lis):
col, row = divmod(i, rows)
#print "i=%d, row=%d, col=%d, element=%r" % (i, row, col, elm)
table[row][col] = elm
return table
else:
raise ValueError("arg ``direction`` must start with 'H' or 'V'")
def transpose(array):
"""Turn a list of lists sideways, making columns into rows and vice-versa.
``array`` must be rectangular; i.e., all elements must be the same
length. Otherwise the behavior is undefined: you may get ``IndexError``
or missing items.
Examples::
>>> transpose([["A", "B", "C"], ["D", "E", "F"]])
[['A', 'D'], ['B', 'E'], ['C', 'F']]
>>> transpose([["A", "B"], ["C", "D"], ["E", "F"]])
[['A', 'C', 'E'], ['B', 'D', 'F']]
>>> transpose([])
[]
Here's a pictoral view of the first example::
A B C => A D
D E F B E
C F
This can be used to turn an HTML table into a group of div columns. An HTML
table is row major: it consists of several | rows, each containing
several cells. But a layout consists of only one row, each
containing an entire subarray. The s have style "float:left", which
makes them appear horizontally. The items within each are placed in
their own 's or separated by , which makes them appear
vertically. The point is that an HTML table is row major (``array[0]`` is
the first row), while a group of div columns is column major (``array[0]``
is the first column). ``transpose()`` can be used to switch between the
two.
"""
if not array:
return []
ret = []
for c in range(len(array[0])):
col = [row[c] for row in array]
ret.append(col)
return ret
if __name__ == "__main__":
import doctest
doctest.testmod()
WebHelpers-1.3/webhelpers/mimehelper.py 0000664 0001750 0001750 00000011317 11471126331 017644 0 ustar sluggo sluggo """MIME Type helpers
This helper depends on the WebOb package, and has optional Pylons support.
"""
import mimetypes
class MIMETypes(object):
"""MIMETypes registration mapping
The MIMETypes object class provides a single point to hold onto all
the registered mimetypes, and their association extensions. It's
used by the mimetypes method to determine the appropriate content
type to return to a client.
"""
aliases = {}
def init(cls):
"""Loads a default mapping of extensions and mimetypes
These are suitable for most web applications by default.
Additional types can be added by using the mimetypes module.
"""
mimetypes.init()
init = classmethod(init)
def add_alias(cls, alias, mimetype):
"""Create a MIMEType alias to a full mimetype.
Examples:
- ``add_alias('html', 'text/html')``
- ``add_alias('xml', 'application/xml')``
An ``alias`` may not contain the ``/`` character.
"""
if '/' in alias:
raise ValueError("MIMEType aliases may not contain '/'")
cls.aliases[alias] = mimetype
add_alias = classmethod(add_alias)
def __init__(self, environ):
"""``environ`` is the WSGI environment of the current request."""
self.env = environ
def _set_response_content_type(self, mimetype):
if 'pylons.pylons' in self.env:
self.env['pylons.pylons'].response.content_type = mimetype
return mimetype
def mimetype(self, content_type):
"""Check the PATH_INFO of the current request and client's HTTP Accept
to attempt to use the appropriate mime-type.
If a content-type is matched, return the appropriate response
content type, and if running under Pylons, set the response content
type directly. If a content-type is not matched, return ``False``.
This works best with URLs that end in extensions that differentiate
content-type. Examples: ``http://example.com/example``,
``http://example.com/example.xml``, ``http://example.com/example.csv``
Since browsers generally allow for any content-type, but should be
sent HTML when possible, the html mimetype check should always come
first, as shown in the example below.
Example::
# some code likely in environment.py
MIMETypes.init()
MIMETypes.add_alias('html', 'text/html')
MIMETypes.add_alias('xml', 'application/xml')
MIMETypes.add_alias('csv', 'text/csv')
# code in a Pylons controller
def someaction(self):
# prepare a bunch of data
# ......
# prepare MIMETypes object
m = MIMETypes(request.environ)
if m.mimetype('html'):
return render('/some/template.html')
elif m.mimetype('atom'):
return render('/some/xml_template.xml')
elif m.mimetype('csv'):
# write the data to a csv file
return csvfile
else:
abort(404)
# Code in a non-Pylons controller.
m = MIMETypes(environ)
response_type = m.mimetype('html')
# ``response_type`` is a MIME type or ``False``.
"""
import webob
if content_type in MIMETypes.aliases:
content_type = MIMETypes.aliases[content_type]
path = self.env['PATH_INFO']
guess_from_url = mimetypes.guess_type(path)[0]
possible_from_accept_header = None
has_extension = False
if len(path.split('/')) > 1:
last_part = path.split('/')[-1]
if '.' in last_part:
has_extension = True
if 'HTTP_ACCEPT' in self.env:
possible_from_accept_header = webob.acceptparse.MIMEAccept('ACCEPT',
self.env['HTTP_ACCEPT'])
if has_extension == False:
if possible_from_accept_header is None:
return self._set_response_content_type(content_type)
elif content_type in possible_from_accept_header:
return self._set_response_content_type(content_type)
else:
return False
if content_type == guess_from_url:
# Guessed same mimetype
return self._set_response_content_type(content_type)
elif guess_from_url is None and content_type in possible_from_accept_header:
return self._set_response_content_type(content_type)
else:
return False
WebHelpers-1.3/webhelpers/util.py 0000664 0001750 0001750 00000025102 11445174513 016475 0 ustar sluggo sluggo """Utility functions used by various web helpers.
This module contains support functions used by other helpers, and functions for
URL manipulation. Most of these helpers predate the 0.6 reorganization; they
would have been put in other subpackages if they have been created later.
"""
import cgi
import copy
import sys
import urllib
import urlparse
from UserDict import DictMixin
from xml.sax.saxutils import XMLGenerator
try:
from urlparse import parse_qs
except ImportError: # Python < 2.6
from cgi import parse_qs
def update_params(_url, _debug=False, **params):
"""Update query parameters in a URL.
``_url`` is any URL, with or without a query string.
``\*\*params`` are query parameters to add or replace. Each value may be a
string, a list of strings, or None. Passing a list generates multiple
values for the same parameter. Passing None deletes the corresponding
parameter if present.
Return the new URL.
*Debug mode:* if a pseudo-parameter ``_debug=True`` is passed,
return a tuple: ``[0]`` is the URL without query string or fragment,
``[1]`` is the final query parameters as a dict, and ``[2]`` is the
fragment part of the original URL or the empty string.
Usage:
>>> update_params("foo", new1="NEW1")
'foo?new1=NEW1'
>>> update_params("foo?p=1", p="2")
'foo?p=2'
>>> update_params("foo?p=1", p=None)
'foo'
>>> update_params("http://example.com/foo?new1=OLD1#myfrag", new1="NEW1")
'http://example.com/foo?new1=NEW1#myfrag'
>>> update_params("http://example.com/foo?new1=OLD1#myfrag", new1="NEW1", _debug=True)
('http://example.com/foo', {'new1': 'NEW1'}, 'myfrag')
>>> update_params("http://www.mau.de?foo=2", brrr=3)
'http://www.mau.de?foo=2&brrr=3'
>>> update_params("http://www.mau.de?foo=A&foo=B", foo=["C", "D"])
'http://www.mau.de?foo=C&foo=D'
"""
url, fragment = urlparse.urldefrag(_url)
if "?" in url:
url, qs = url.split("?", 1)
query = parse_qs(qs)
else:
query = {}
for key, value in params.iteritems():
if value is not None:
query[key] = value
elif key in query:
del query[key]
if _debug:
return url, query, fragment
qs = urllib.urlencode(query, True)
if qs:
qs = "?" + qs
if fragment:
fragment = "#" + fragment
return "%s%s%s" % (url, qs, fragment)
def cgi_escape(s, quote=False):
"""Replace special characters '&', '<' and '>' by SGML entities.
This is a slightly more efficient version of the cgi.escape by
using 'in' membership to test if the replace is needed.
This function returns a plain string. Programs using the HTML builder
should call ``webhelpers.html.builder.escape()`` instead of this to prevent
double-escaping.
Changed in WebHelpers 1.2: escape single-quote as well as double-quote.
"""
if '&' in s:
s = s.replace("&", "&") # Must be done first!
if '<' in s:
s = s.replace("<", "<")
if '>' in s:
s = s.replace(">", ">")
if quote:
s = s.replace('"', """)
s = s.replace("'", "'")
return s
def html_escape(s):
"""HTML-escape a string or object.
This converts any non-string objects passed into it to strings
(actually, using ``unicode()``). All values returned are
non-unicode strings (using ``&#num;`` entities for all non-ASCII
characters).
None is treated specially, and returns the empty string.
This function returns a plain string. Programs using the HTML builder
should wrap the result in ``literal()`` to prevent double-escaping.
"""
if s is None:
return ''
if not isinstance(s, basestring):
if hasattr(s, '__unicode__'):
s = unicode(s)
else:
s = str(s)
s = cgi_escape(s, True)
if isinstance(s, unicode):
s = s.encode('ascii', 'xmlcharrefreplace')
return s
def iri_to_uri(iri):
"""
Convert an IRI portion to a URI portion suitable for inclusion in a URL.
(An IRI is an Internationalized Resource Identifier.)
This is the algorithm from section 3.1 of RFC 3987. However, since
we are assuming input is either UTF-8 or unicode already, we can
simplify things a little from the full method.
Returns an ASCII string containing the encoded result.
"""
# Called by webhelpers.feedgenerator
#
# The list of safe characters here is constructed from the printable ASCII
# characters that are not explicitly excluded by the list at the end of
# section 3.1 of RFC 3987.
if iri is None:
return iri
return urllib.quote(iri, safe='/#%[]=:;$&()+,!?')
class Partial(object):
"""
A partial function object.
Equivalent to functools.partial, which was introduced in Python 2.5.
"""
def __init__(*args, **kw):
self = args[0]
self.fn, self.args, self.kw = (args[1], args[2:], kw)
def __call__(self, *args, **kw):
if kw and self.kw:
d = self.kw.copy()
d.update(kw)
else:
d = kw or self.kw
return self.fn(*(self.args + args), **d)
class SimplerXMLGenerator(XMLGenerator):
"""A subclass of Python's SAX XMLGenerator."""
# Used by webhelpers.feedgenerator
def addQuickElement(self, name, contents=None, attrs=None):
"""Add an element with no children."""
if attrs is None:
attrs = {}
self.startElement(name, attrs)
if contents is not None:
self.characters(contents)
self.endElement(name)
class UnicodeMultiDict(DictMixin):
"""
A MultiDict wrapper that decodes returned values to unicode on the fly.
Decoding is not applied to assigned values.
The key/value contents are assumed to be ``str``/``strs`` or
``str``/``FieldStorages`` (as is returned by the :func:`paste.request.parse`
functions).
Can optionally also decode keys when the ``decode_keys`` argument is
True.
``FieldStorage`` instances are cloned, and the clone's ``filename``
variable is decoded. Its ``name`` variable is decoded when ``decode_keys``
is enabled.
"""
def __init__(self, multi=None, encoding=None, errors='strict',
decode_keys=False):
self.multi = multi
if encoding is None:
encoding = sys.getdefaultencoding()
self.encoding = encoding
self.errors = errors
self.decode_keys = decode_keys
def _decode_key(self, key):
if self.decode_keys:
key = key.decode(self.encoding, self.errors)
return key
def _decode_value(self, value):
"""
Decode the specified (``str`` or `FieldStorage``) value to unicode.
``FieldStorage`` objects are specially handled.
"""
if isinstance(value, cgi.FieldStorage):
# decode FieldStorage's field name and filename
value = copy.copy(value)
if self.decode_keys:
value.name = value.name.decode(self.encoding, self.errors)
value.filename = value.filename.decode(self.encoding, self.errors)
else:
try:
value = value.decode(self.encoding, self.errors)
except AttributeError:
pass
return value
def __getitem__(self, key):
return self._decode_value(self.multi.__getitem__(key))
def __setitem__(self, key, value):
self.multi.__setitem__(key, value)
def add(self, key, value):
"""Add the key and value, not overwriting any previous value."""
self.multi.add(key, value)
def getall(self, key):
"""Return list of all values matching the key (may be an empty list)."""
return [self._decode_value(v) for v in self.multi.getall(key)]
def getone(self, key):
"""Return one value matching key. Raise KeyError if multiple matches."""
return self._decode_value(self.multi.getone(key))
def mixed(self):
"""Return dict where values are single values or a list of values.
The value is a single value if key appears just once. It is
a list of values when a key/value appears more than once in this
dictionary. This is similar to the kind of dictionary often
used to represent the variables in a web request.
"""
unicode_mixed = {}
for key, value in self.multi.mixed().iteritems():
if isinstance(value, list):
value = [self._decode_value(value) for value in value]
else:
value = self._decode_value(value)
unicode_mixed[self._decode_key(key)] = value
return unicode_mixed
def dict_of_lists(self):
"""Return dict where each key is associated with a list of values."""
unicode_dict = {}
for key, value in self.multi.dict_of_lists().iteritems():
value = [self._decode_value(value) for value in value]
unicode_dict[self._decode_key(key)] = value
return unicode_dict
def __delitem__(self, key):
self.multi.__delitem__(key)
def __contains__(self, key):
return self.multi.__contains__(key)
has_key = __contains__
def clear(self):
self.multi.clear()
def copy(self):
return UnicodeMultiDict(self.multi.copy(), self.encoding, self.errors)
def setdefault(self, key, default=None):
return self._decode_value(self.multi.setdefault(key, default))
def pop(self, key, *args):
return self._decode_value(self.multi.pop(key, *args))
def popitem(self):
k, v = self.multi.popitem()
return (self._decode_key(k), self._decode_value(v))
def __repr__(self):
items = ', '.join(['(%r, %r)' % v for v in self.items()])
return '%s([%s])' % (self.__class__.__name__, items)
def __len__(self):
return self.multi.__len__()
##
## All the iteration:
##
def keys(self):
return [self._decode_key(k) for k in self.multi.iterkeys()]
def iterkeys(self):
for k in self.multi.iterkeys():
yield self._decode_key(k)
__iter__ = iterkeys
def items(self):
return [(self._decode_key(k), self._decode_value(v)) for \
k, v in self.multi.iteritems()]
def iteritems(self):
for k, v in self.multi.iteritems():
yield (self._decode_key(k), self._decode_value(v))
def values(self):
return [self._decode_value(v) for v in self.multi.itervalues()]
def itervalues(self):
for v in self.multi.itervalues():
yield self._decode_value(v)
WebHelpers-1.3/webhelpers/paginate.py 0000664 0001750 0001750 00000107613 11542303225 017310 0 ustar sluggo sluggo """
paginate: a module to help split up lists or results from ORM queries
=======================================================================
What is pagination?
---------------------
This module helps dividing large lists of items into pages. The user
is shown one page at a time and can navigate to other pages. Imagine you
are offering a company phonebook and let the user search the entries. If
the search result contains 23 entries but you may want to display no
more than 10 entries at once. The first page contains entries 1-10, the
second 11-20 and the third 21-23. See the documentation of the "Page"
class for more information.
How do I use it?
------------------
One page of items is represented by the *Page* object. A *Page* gets
initialized with at least two arguments and usually three:
- The collection of items to pick a range from.
- The page number we want to display. (Default is 1: the first page.)
- A URL generator callback. (This tells what the URLs to other pages are.
It's required if using the ``pager()`` method, although it may be omitted
under Pylons for backward compatibility. It is required for Pyramid.)
Here's an interactive example.
First we'll create a URL generator using the basic ``PageURL`` class, which
works with all frameworks and has no dependencies. It creates URLs by
overriding the 'page' query parameter. ::
# Instantiate the URL generator, and call it to see what it does.
>>> url_for_page = PageURL("/articles/2013", {"page": "3"})
>>> url_for_page(page=2)
'/articles/2013?page=2'
Now we can create a collection and instantiate the Page::
# Create a sample collection of 1000 items
>>> my_collection = range(1000)
# Create a Page object for the 3rd page (20 items per page is the default)
>>> my_page = Page(my_collection, page=3, url=url_for_page)
# The page object can be printed directly to get its details
>>> my_page
Page:
Collection type:
(Current) page: 3
First item: 41
Last item: 60
First page: 1
Last page: 50
Previous page: 2
Next page: 4
Items per page: 20
Number of items: 1000
Number of pages: 50
# Print a list of items on the current page
>>> my_page.items
[40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59]
# The *Page* object can be used as an iterator:
>>> for my_item in my_page: print my_item,
40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59
# The .pager() method returns an HTML fragment with links to surrounding
# pages.
# [The ">>" prompt is to hide untestable examples from doctest.]
>> my_page.pager()
1 2 [3] 4 5 .. 50 (this is actually HTML)
# The pager can be customized:
>> my_page.pager('$link_previous ~3~ $link_next (Page $page of $page_count)')
1 2 [3] 4 5 6 .. 50 > (Page 3 of 50)
There are many parameters that customize the Page's behavor. See the
documentation on ``Page`` and ``Page.pager()``.
URL generator
-------------
The constructor's ``url`` argument is a callback that returns URLs to other
pages. It's required when using the ``Page.pager()`` method except under
Pylons, where it will fall back to ``pylons.url.current`` (Pylons 1) and then
``routes.url_for`` (Pylons 0.9.7). If none of these are available, you'll get
an exception "NotImplementedError: no URL generator available".
WebHelpers 1.3 introduces a few URL generators for convenience. **PageURL** is
described above. **PageURL_WebOb** takes a ``webobb.Request`` object, and is
suitable for Pyramid, Pylons, TurboGears, and other frameworks that have a
WebOb-compatible Request object. Both of these classes assume that the page
number is in the 'page' query parameter.
Here's an example for Pyramid and other WebOb-compatible frameworks::
# Assume ``request`` is the current request.
import webhelpers.paginate as paginate
current_page = int(request.params["page"])
q = SOME_SQLALCHEMY_QUERY
page_url = paginate.PageURL_WebOb(request)
records = paginate.Page(q, current_page, url=page_url)
If the page number is in the URL path, you'll have to use a framework-specific
URL generator. For instance, in Pyramid if the current route is
"/articles/{id}/page/{page}" and the current URL is
"/articles/ABC/page/3?print=1", you can use Pyramid's "current_route_url"
function as follows::
# Assume ``request`` is the current request.
import webhelpers.paginate as paginate
from pyramid.url import current_route_url
def page_url(page):
return current_route_url(request, page=page, _query=request.GET)
q = SOME_SQLALCHEMY_QUERY
current_page = int(request.matchdict["page"])
records = Page(q, current_page, url=page_url)
This overrides the 'page' path variable, while leaving the 'id' variable and
the query string intact.
The callback API is simple.
1. It must accept an integer argument 'page', which will be passed by name.
2. It should return the URL for that page.
3. If you're using AJAX 'partial' functionality described in the ``Page.pager``
docstring, the callback should also accept a 'partial' argument and, if
true, set a query parameter 'partial=1'.
4. If you use the 'page_param' or 'partial_param' argument to ``Page.pager``,
the 'page' and 'partial' arguments will be renamed to whatever you specify.
In this case, the callback would also have to expect these other argument
names.
The supplied classes adhere to this API in their
``.__call__`` method, all except the fourth condition. So you can use their
instances as callbacks as long as you don't use 'page_param' or 'partial_param'.
For convenience in writing callbacks that update the 'page' query parameter, a
``make_page_url`` function is available that assembles the pieces into a
complete URL. Other callbacks may find ``webhelpers.utl.update_params`` useful,
which overrides query parameters on a more general basis.
Can I use AJAX / AJAH?
------------------------
Yes. See *partial_param* and *onclick* in ``Page.pager()``.
Notes
-------
Page numbers and item numbers start at 1. This concept has been used
because users expect that the first page has number 1 and the first item
on a page also has number 1. So if you want to use the page's items by
their index number please note that you have to subtract 1.
This module is the successor to the obsolete ``webhelpers.pagination``
module. It is **NOT** API compatible.
This module is based on the code from
http://workaround.org/cgi-bin/hg-paginate that is known at the
"Paginate" module on PyPI. It was written by Christoph Haas
, and modified by Christoph Haas and Mike Orr for
WebHelpers. (c) 2007-2011.
"""
import re
from string import Template
import urllib
import warnings
from webhelpers.html import literal, HTML
INCOMPATIBLE_COLLECTION_TYPE = """\
Sorry, your collection type is not supported by the paginate module. You can
provide a list, a tuple, a SQLAlchemy " "select object or a SQLAlchemy
ORM-query object."""
# import SQLAlchemy if available
try:
import sqlalchemy
import sqlalchemy.orm # Some users report errors if this is not imported.
except:
sqlalchemy_available = False
sqlalchemy_version = None
else:
sqlalchemy_available = True
sqlalchemy_version = sqlalchemy.__version__
def get_wrapper(obj, sqlalchemy_session=None):
"""
Auto-detect the kind of object and return a list/tuple
to access items from the collection.
"""
# If the collection is a sequence we can use it directly
if isinstance(obj, (list, tuple)):
return obj
# Is SQLAlchemy 0.4 or better available? (0.3 is not supported - sorry)
# Note: SQLAlchemy objects aren't sliceable, so this has to be before
# the next if-stanza
if sqlalchemy_available and sqlalchemy_version[:3] != '0.3':
# Is the collection a query?
if isinstance(obj, sqlalchemy.orm.query.Query):
return _SQLAlchemyQuery(obj)
# Is the collection an SQLAlchemy select object?
if isinstance(obj, sqlalchemy.sql.expression.CompoundSelect) \
or isinstance(obj, sqlalchemy.sql.expression.Select):
return _SQLAlchemySelect(obj, sqlalchemy_session)
# If object is iterable we can use it. (This is not true if it's
# non-sliceable but there doesn't appear to be a way to test for that. We'd
# have to call .__getitem__ with a slice and guess what the exception
# means, and calling it may cause side effects.)
required_methods = ["__iter__", "__len__", "__getitem__"]
for meth in required_methods:
if not hasattr(obj, meth):
break
else:
return obj
raise TypeError(INCOMPATIBLE_COLLECTION_TYPE)
class _SQLAlchemySelect(object):
"""
Iterable that allows to get slices from an SQLAlchemy Select object
"""
def __init__(self, obj, sqlalchemy_session=None):
session_types = (
sqlalchemy.orm.scoping.ScopedSession,
sqlalchemy.orm.Session)
if not isinstance(sqlalchemy_session, session_types):
raise TypeError("If you want to page an SQLAlchemy 'select' object then you "
"have to provide a 'sqlalchemy_session' argument. See also: "
"http://www.sqlalchemy.org/docs/04/session.html")
self.sqlalchemy_session = sqlalchemy_session
self.obj = obj
def __getitem__(self, range):
if not isinstance(range, slice):
raise Exception, "__getitem__ without slicing not supported"
offset = range.start
limit = range.stop - range.start
select = self.obj.offset(offset).limit(limit)
return self.sqlalchemy_session.execute(select).fetchall()
def __len__(self):
return self.sqlalchemy_session.execute(self.obj).rowcount
class _SQLAlchemyQuery(object):
"""
Iterable that allows to get slices from an SQLAlchemy Query object
"""
def __init__(self, obj):
self.obj = obj
def __getitem__(self, range):
if not isinstance(range, slice):
raise Exception, "__getitem__ without slicing not supported"
return self.obj[range]
def __len__(self):
return self.obj.count()
# Since the items on a page are mainly a list we subclass the "list" type
class Page(list):
"""A list/iterator of items representing one page in a larger
collection.
An instance of the "Page" class is created from a collection of things.
The instance works as an iterator running from the first item to the
last item on the given page. The collection can be:
- a sequence
- an SQLAlchemy query - e.g.: Session.query(MyModel)
- an SQLAlchemy select - e.g.: sqlalchemy.select([my_table])
A "Page" instance maintains pagination logic associated with each
page, where it begins, what the first/last item on the page is, etc.
The pager() method creates a link list allowing the user to go to
other pages.
**WARNING:** Unless you pass in an item_count, a count will be
performed on the collection every time a Page instance is created.
If using an ORM, it's advised to pass in the number of items in the
collection if that number is known.
Instance attributes:
original_collection
Points to the collection object being paged through
item_count
Number of items in the collection
page
Number of the current page
items_per_page
Maximal number of items displayed on a page
first_page
Number of the first page - starts with 1
last_page
Number of the last page
page_count
Number of pages
items
Sequence/iterator of items on the current page
first_item
Index of first item on the current page - starts with 1
last_item
Index of last item on the current page
"""
def __init__(self, collection, page=1, items_per_page=20,
item_count=None, sqlalchemy_session=None, presliced_list=False,
url=None, **kwargs):
"""Create a "Page" instance.
Parameters:
collection
Sequence, SQLAlchemy select object or SQLAlchemy ORM-query
representing the collection of items to page through.
page
The requested page number - starts with 1. Default: 1.
items_per_page
The maximal number of items to be displayed per page.
Default: 20.
item_count (optional)
The total number of items in the collection - if known.
If this parameter is not given then the paginator will count
the number of elements in the collection every time a "Page"
is created. Giving this parameter will speed up things.
presliced_list (optional)
Indicates whether the collection, when a list, has already
been sliced for the current viewing page, and thus should
*not* be sliced again.
sqlalchemy_session (optional)
If you want to use an SQLAlchemy (0.4) select object as a
collection then you need to provide an SQLAlchemy session object.
Select objects do not have a database connection attached so it
would not be able to execute the SELECT query.
url (optional)
A URL generator function. See module docstring for details.
This is used only by ``.pager()``.
Further keyword arguments are used as link arguments in the pager().
"""
self._url_generator = url
# 'page_nr' is deprecated.
if 'page_nr' in kwargs:
warnings.warn("'page_nr' is deprecated. Please use 'page' instead.")
page = kwargs['page_nr']
del kwargs['page_nr']
# 'current_page' is also deprecated.
if 'current_page' in kwargs:
warnings.warn("'current_page' is deprecated. Please use 'page' instead.")
page = kwargs['current_page']
del kwargs['current_page']
# Safe the kwargs class-wide so they can be used in the pager() method
self.kwargs = kwargs
# Save a reference to the collection
self.original_collection = collection
# Decorate the ORM/sequence object with __getitem__ and __len__
# functions to be able to get slices.
if collection is not None:
# Determine the type of collection and use a wrapper for ORMs
self.collection = get_wrapper(collection, sqlalchemy_session)
else:
self.collection = []
# The self.page is the number of the current page.
# The first page has the number 1!
try:
self.page = int(page) # make it int() if we get it as a string
except (ValueError, TypeError):
self.page = 1
self.items_per_page = items_per_page
# Unless the user tells us how many items the collections has
# we calculate that ourselves.
if item_count is not None:
self.item_count = item_count
else:
self.item_count = len(self.collection)
# Compute the number of the first and last available page
if self.item_count > 0:
self.first_page = 1
self.page_count = ((self.item_count - 1) / self.items_per_page) + 1
self.last_page = self.first_page + self.page_count - 1
# Make sure that the requested page number is the range of valid pages
if self.page > self.last_page:
self.page = self.last_page
elif self.page < self.first_page:
self.page = self.first_page
# Note: the number of items on this page can be less than
# items_per_page if the last page is not full
self.first_item = (self.page - 1) * items_per_page + 1
self.last_item = min(self.first_item + items_per_page - 1, self.item_count)
# We subclassed "list" so we need to call its init() method
# and fill the new list with the items to be displayed on the page.
# We use list() so that the items on the current page are retrieved
# only once. Otherwise it would run the actual SQL query everytime
# .items would be accessed.
if presliced_list:
self.items = self.collection
else:
try:
first = self.first_item - 1
last = self.last_item
self.items = list(self.collection[first:last])
except TypeError, e:
if str(e) == "unhashable type":
# Assume this means collection is unsliceable.
raise TypeError(INCOMPATIBLE_COLLECTION_TYPE)
raise
# Links to previous and next page
if self.page > self.first_page:
self.previous_page = self.page-1
else:
self.previous_page = None
if self.page < self.last_page:
self.next_page = self.page+1
else:
self.next_page = None
# No items available
else:
self.first_page = None
self.page_count = 0
self.last_page = None
self.first_item = None
self.last_item = None
self.previous_page = None
self.next_page = None
self.items = []
# This is a subclass of the 'list' type. Initialise the list now.
list.__init__(self, self.items)
def __repr__(self):
return ("Page:\n"
"Collection type: %(type)s\n"
"(Current) page: %(page)s\n"
"First item: %(first_item)s\n"
"Last item: %(last_item)s\n"
"First page: %(first_page)s\n"
"Last page: %(last_page)s\n"
"Previous page: %(previous_page)s\n"
"Next page: %(next_page)s\n"
"Items per page: %(items_per_page)s\n"
"Number of items: %(item_count)s\n"
"Number of pages: %(page_count)s\n"
% {
'type':type(self.collection),
'page':self.page,
'first_item':self.first_item,
'last_item':self.last_item,
'first_page':self.first_page,
'last_page':self.last_page,
'previous_page':self.previous_page,
'next_page':self.next_page,
'items_per_page':self.items_per_page,
'item_count':self.item_count,
'page_count':self.page_count,
})
def pager(self, format='~2~', page_param='page', partial_param='partial',
show_if_single_page=False, separator=' ', onclick=None,
symbol_first='<<', symbol_last='>>',
symbol_previous='<', symbol_next='>',
link_attr={'class':'pager_link'}, curpage_attr={'class':'pager_curpage'},
dotdot_attr={'class':'pager_dotdot'}, **kwargs):
"""
Return string with links to other pages (e.g. "1 2 [3] 4 5 6 7").
format:
Format string that defines how the pager is rendered. The string
can contain the following $-tokens that are substituted by the
string.Template module:
- $first_page: number of first reachable page
- $last_page: number of last reachable page
- $page: number of currently selected page
- $page_count: number of reachable pages
- $items_per_page: maximal number of items per page
- $first_item: index of first item on the current page
- $last_item: index of last item on the current page
- $item_count: total number of items
- $link_first: link to first page (unless this is first page)
- $link_last: link to last page (unless this is last page)
- $link_previous: link to previous page (unless this is first page)
- $link_next: link to next page (unless this is last page)
To render a range of pages the token '~3~' can be used. The
number sets the radius of pages around the current page.
Example for a range with radius 3:
'1 .. 5 6 7 [8] 9 10 11 .. 500'
Default: '~2~'
symbol_first
String to be displayed as the text for the %(link_first)s
link above.
Default: '<<'
symbol_last
String to be displayed as the text for the %(link_last)s
link above.
Default: '>>'
symbol_previous
String to be displayed as the text for the %(link_previous)s
link above.
Default: '<'
symbol_next
String to be displayed as the text for the %(link_next)s
link above.
Default: '>'
separator:
String that is used to separate page links/numbers in the
above range of pages.
Default: ' '
page_param:
The name of the parameter that will carry the number of the
page the user just clicked on. The parameter will be passed
to a url_for() call so if you stay with the default
':controller/:action/:id' routing and set page_param='id' then
the :id part of the URL will be changed. If you set
page_param='page' then url_for() will make it an extra
parameters like ':controller/:action/:id?page=1'.
You need the page_param in your action to determine the page
number the user wants to see. If you do not specify anything
else the default will be a parameter called 'page'.
Note: If you set this argument and are using a URL generator
callback, the callback must accept this name as an argument instead
of 'page'.
callback, becaust the callback requires its argument to be 'page'.
Instead the callback itself can return any URL necessary.
partial_param:
When using AJAX/AJAH to do partial updates of the page area the
application has to know whether a partial update (only the
area to be replaced) or a full update (reloading the whole
page) is required. So this parameter is the name of the URL
parameter that gets set to 1 if the 'onclick' parameter is
used. So if the user requests a new page through a Javascript
action (onclick) then this parameter gets set and the application
is supposed to return a partial content. And without
Javascript this parameter is not set. The application thus has
to check for the existence of this parameter to determine
whether only a partial or a full page needs to be returned.
See also the examples in this modules docstring.
Default: 'partial'
Note: If you set this argument and are using a URL generator
callback, the callback must accept this name as an argument instead
of 'partial'.
show_if_single_page:
if True the navigator will be shown even if there is only
one page
Default: False
link_attr (optional)
A dictionary of attributes that get added to A-HREF links
pointing to other pages. Can be used to define a CSS style
or class to customize the look of links.
Example: { 'style':'border: 1px solid green' }
Default: { 'class':'pager_link' }
curpage_attr (optional)
A dictionary of attributes that get added to the current
page number in the pager (which is obviously not a link).
If this dictionary is not empty then the elements
will be wrapped in a SPAN tag with the given attributes.
Example: { 'style':'border: 3px solid blue' }
Default: { 'class':'pager_curpage' }
dotdot_attr (optional)
A dictionary of attributes that get added to the '..' string
in the pager (which is obviously not a link). If this
dictionary is not empty then the elements will be wrapped in
a SPAN tag with the given attributes.
Example: { 'style':'color: #808080' }
Default: { 'class':'pager_dotdot' }
onclick (optional)
This paramter is a string containing optional Javascript code
that will be used as the 'onclick' action of each pager link.
It can be used to enhance your pager with AJAX actions loading another
page into a DOM object.
In this string the variable '$partial_url' will be replaced by
the URL linking to the desired page with an added 'partial=1'
parameter (or whatever you set 'partial_param' to).
In addition the '$page' variable gets replaced by the
respective page number.
Note that the URL to the destination page contains a 'partial_param'
parameter so that you can distinguish between AJAX requests (just
refreshing the paginated area of your page) and full requests (loading
the whole new page).
[Backward compatibility: you can use '%s' instead of '$partial_url']
jQuery example:
"$('#my-page-area').load('$partial_url'); return false;"
Yahoo UI example:
"YAHOO.util.Connect.asyncRequest('GET','$partial_url',{
success:function(o){YAHOO.util.Dom.get('#my-page-area').innerHTML=o.responseText;}
},null); return false;"
scriptaculous example:
"new Ajax.Updater('#my-page-area', '$partial_url',
{asynchronous:true, evalScripts:true}); return false;"
ExtJS example:
"Ext.get('#my-page-area').load({url:'$partial_url'}); return false;"
Custom example:
"my_load_page($page)"
Additional keyword arguments are used as arguments in the links.
Otherwise the link will be created with url_for() which points
to the page you are currently displaying.
"""
self.curpage_attr = curpage_attr
self.separator = separator
self.pager_kwargs = kwargs
self.page_param = page_param
self.partial_param = partial_param
self.onclick = onclick
self.link_attr = link_attr
self.dotdot_attr = dotdot_attr
# Don't show navigator if there is no more than one page
if self.page_count == 0 or (self.page_count == 1 and not show_if_single_page):
return ''
# Replace ~...~ in token format by range of pages
result = re.sub(r'~(\d+)~', self._range, format)
# Interpolate '%' variables
result = Template(result).safe_substitute({
'first_page': self.first_page,
'last_page': self.last_page,
'page': self.page,
'page_count': self.page_count,
'items_per_page': self.items_per_page,
'first_item': self.first_item,
'last_item': self.last_item,
'item_count': self.item_count,
'link_first': self.page>self.first_page and \
self._pagerlink(self.first_page, symbol_first) or '',
'link_last': self.page leftmost_page = 5
# -> rightmost_page = 9
leftmost_page = max(self.first_page, (self.page-radius))
rightmost_page = min(self.last_page, (self.page+radius))
nav_items = []
# Create a link to the first page (unless we are on the first page
# or there would be no need to insert '..' spacers)
if self.page != self.first_page and self.first_page < leftmost_page:
nav_items.append( self._pagerlink(self.first_page, self.first_page) )
# Insert dots if there are pages between the first page
# and the currently displayed page range
if leftmost_page - self.first_page > 1:
# Wrap in a SPAN tag if nolink_attr is set
text = '..'
if self.dotdot_attr:
text = HTML.span(c=text, **self.dotdot_attr)
nav_items.append(text)
for thispage in xrange(leftmost_page, rightmost_page+1):
# Hilight the current page number and do not use a link
if thispage == self.page:
text = '%s' % (thispage,)
# Wrap in a SPAN tag if nolink_attr is set
if self.curpage_attr:
text = HTML.span(c=text, **self.curpage_attr)
nav_items.append(text)
# Otherwise create just a link to that page
else:
text = '%s' % (thispage,)
nav_items.append( self._pagerlink(thispage, text) )
# Insert dots if there are pages between the displayed
# page numbers and the end of the page range
if self.last_page - rightmost_page > 1:
text = '..'
# Wrap in a SPAN tag if nolink_attr is set
if self.dotdot_attr:
text = HTML.span(c=text, **self.dotdot_attr)
nav_items.append(text)
# Create a link to the very last page (unless we are on the last
# page or there would be no need to insert '..' spacers)
if self.page != self.last_page and rightmost_page < self.last_page:
nav_items.append( self._pagerlink(self.last_page, self.last_page) )
return self.separator.join(nav_items)
def _pagerlink(self, page, text):
"""
Create a URL that links to another page using url_for().
Parameters:
page
Number of the page that the link points to
text
Text to be printed in the A-HREF tag
"""
# Let the url_for() from webhelpers create a new link and set
# the variable called 'page_param'. Example:
# You are in '/foo/bar' (controller='foo', action='bar')
# and you want to add a parameter 'page'. Then you
# call the navigator method with page_param='page' and
# the url_for() call will create a link '/foo/bar?page=...'
# with the respective page number added.
link_params = {}
# Use the instance kwargs from Page.__init__ as URL parameters
link_params.update(self.kwargs)
# Add keyword arguments from pager() to the link as parameters
link_params.update(self.pager_kwargs)
link_params[self.page_param] = page
# Get the URL generator
if self._url_generator is not None:
url_generator = self._url_generator
else:
try:
import pylons
url_generator = pylons.url.current
except (ImportError, AttributeError):
try:
import routes
url_generator = routes.url_for
config = routes.request_config()
except (ImportError, AttributeError):
raise NotImplementedError("no URL generator available")
else:
# if the Mapper is configured with explicit=True we have to fetch
# the controller and action manually
if config.mapper.explicit:
if hasattr(config, 'mapper_dict'):
for k, v in config.mapper_dict.items():
if k != self.page_param:
link_params[k] = v
# Create the URL to load a certain page
link_url = url_generator(**link_params)
if self.onclick: # create link with onclick action for AJAX
# Create the URL to load the page area part of a certain page (AJAX
# updates)
link_params[self.partial_param] = 1
partial_url = url_generator(**link_params)
try: # if '%s' is used in the 'onclick' parameter (backwards compatibility)
onclick_action = self.onclick % (partial_url,)
except TypeError:
onclick_action = Template(self.onclick).safe_substitute({
"partial_url": partial_url,
"page": page
})
return HTML.a(text, href=link_url, onclick=onclick_action, **self.link_attr)
else: # return static link
return HTML.a(text, href=link_url, **self.link_attr)
#### URL GENERATOR CLASSES
def make_page_url(path, params, page, partial=False, sort=True):
"""A helper function for URL generators.
I assemble a URL from its parts. I assume that a link to a certain page is
done by overriding the 'page' query parameter.
``path`` is the current URL path, with or without a "scheme://host" prefix.
``params`` is the current query parameters as a dict or dict-like object.
``page`` is the target page number.
If ``partial`` is true, set query param 'partial=1'. This is to for AJAX
calls requesting a partial page.
If ``sort`` is true (default), the parameters will be sorted. Otherwise
they'll be in whatever order the dict iterates them.
"""
params = params.copy()
params["page"] = page
if partial:
params["partial"] = "1"
if sort:
params = params.items()
params.sort()
qs = urllib.urlencode(params, True)
return "%s?%s" % (path, qs)
class PageURL(object):
"""A simple page URL generator for any framework."""
def __init__(self, path, params):
"""
``path`` is the current URL path, with or without a "scheme://host"
prefix.
``params`` is the current URL's query parameters as a dict or dict-like
object.
"""
self.path = path
self.params = params
def __call__(self, page, partial=False):
"""Generate a URL for the specified page."""
return make_page_url(self.path, self.params, page, partial)
class PageURL_WebOb(object):
"""A page URL generator for WebOb-compatible Request objects.
I derive new URLs based on the current URL but overriding the 'page'
query parameter.
I'm suitable for Pyramid, Pylons, and TurboGears, as well as any other
framework whose Request object has 'application_url', 'path', and 'GET'
attributes that behave the same way as ``webob.Request``'s.
"""
def __init__(self, request, qualified=False):
"""
``request`` is a WebOb-compatible ``Request`` object.
If ``qualified`` is false (default), generated URLs will have just the
path and query string. If true, the "scheme://host" prefix will be
included. The default is false to match traditional usage, and to avoid
generating unuseable URLs behind reverse proxies (e.g., Apache's
mod_proxy).
"""
self.request = request
self.qualified = qualified
def __call__(self, page, partial=False):
"""Generate a URL for the specified page."""
if self.qualified:
path = self.request.application_url
else:
path = self.request.path
return make_page_url(path, self.request.GET, page, partial)
WebHelpers-1.3/webhelpers/media.py 0000664 0001750 0001750 00000010542 11373653355 016607 0 ustar sluggo sluggo """Multimedia helpers for images, etc."""
import logging
import os
import struct
import sys
__all__ = ["choose_height", "get_dimensions_pil", "get_dimensions"]
def choose_height(new_width, width, height):
"""Return the height corresponding to ``new_width`` that's proportional
to the original size (``width`` x ``height``).
"""
proportion = float(height) / float(width)
return int(new_width * proportion)
def get_dimensions_pil(path, default=(None, None)):
"""Get an image's size using the Python Imaging Library (PIL).
``path`` is the path of the image file.
``default`` is returned if the size could not be ascertained. This
usually means the file does not exist or is not in a format recognized by
PIL.
The normal return value is a tuple: ``(width, height)``.
Depends on the `Python Imaging Library
`_. If your application is not
otherwise using PIL, see the ``get_dimensions()`` function, which does
not have external dependencies.
"""
import Image
try:
im = Image.open(path)
except Exception:
return default
return im.size
def get_dimensions(path, default=(None, None)):
"""Get an image's size using only the Python standard library.
``path`` is the path of the image file.
``default`` is returned if the size could not be ascertained. This
usually means the file does not exist or is not in a recognized format.
PIL. Only JPG, PNG, GIF, and BMP are supported at this time.
The normal return value is a tuple: ``(width, height)``.
The algorithms are based on a `PyCode recipe
`_ by
Perenzo/Welch/Ray.
This helper recognizes fewer image formats and is potentially less
accurate than ``get_dimensions_pil()``.
Running this module as a script tests this helper. It will print the
size of each image file specified on the command line.
"""
apath = os.path.abspath(path)
try:
f = open(path, "rb")
except IOError:
return default
try:
header = f.read(1024)
# JPG
if header.startswith("\xFF\xD8"):
width = height = None
f.seek(2)
while True:
length = 4
buf = f.read(length)
try:
marker, code, length = struct.unpack("!ccH", buf)
except Exception:
break
if marker != "\xff":
break
if 0xc0 <= ord(code) <= 0xc3:
length = 5
buf = f.read(length)
height, width = struct.unpack("!xHH", buf)
else:
f.read(length-2)
return width, height
# PNG
elif header.startswith("\x89PNG\x0d\x0a\x1a\x0a") or \
header.startswith("\x8aMNG\x0d\x0a\x1a\x0a"):
f.seek(12)
control = f.read(4)
if control in ["IHDR", "MHDR"]:
buf = f.read(8)
width, height = struct.unpack("!II", buf)
return width, height
# GIF
elif header.startswith("GIF87a") or header.startswith("GIF89a"):
f.seek(6)
buf = f.read(7)
width, height, flags, bci, par = struct.unpack(" 1:
return str(delta) + " " + _pluralize_granularity(granularity)
def _is_leap_year(year):
if year % 4 == 0 and year % 400 != 0:
return True
return False
def distance_of_time_in_words(from_time, to_time=0, granularity="second",
round=False):
"""
Return the absolute time-distance string for two datetime objects,
ints or any combination you can dream of.
If times are integers, they are interpreted as seconds from now.
``granularity`` dictates where the string calculation is stopped.
If set to seconds (default) you will receive the full string. If
another accuracy is supplied you will receive an approximation.
Available granularities are:
'century', 'decade', 'year', 'month', 'day', 'hour', 'minute',
'second'
Setting ``round`` to true will increase the result by 1 if the fractional
value is greater than 50% of the granularity unit.
Examples:
>>> distance_of_time_in_words(86399, round=True, granularity='day')
'1 day'
>>> distance_of_time_in_words(86399, granularity='day')
'less than 1 day'
>>> distance_of_time_in_words(86399)
'23 hours, 59 minutes and 59 seconds'
>>> distance_of_time_in_words(datetime(2008,3,21, 16,34),
... datetime(2008,2,6,9,45))
'1 month, 15 days, 6 hours and 49 minutes'
>>> distance_of_time_in_words(datetime(2008,3,21, 16,34),
... datetime(2008,2,6,9,45), granularity='decade')
'less than 1 decade'
>>> distance_of_time_in_words(datetime(2008,3,21, 16,34),
... datetime(2008,2,6,9,45), granularity='second')
'1 month, 15 days, 6 hours and 49 minutes'
"""
granularities = ['century', 'decade', 'year', 'month', 'day', 'hour',
'minute', 'second']
# 15 days in the month is a gross approximation, but this
# value is only used if rounding to the nearest month
granularity_size = {'century': 10, 'decade': 10, 'year': 10, 'month': 12,
'day': 15, 'hour': 24, 'minute': 60, 'second': 60 }
if granularity not in granularities:
raise ValueError("Please provide a valid granularity: %s" %
(granularities))
# Get everything into datetimes
if isinstance(from_time, int):
from_time = datetime.fromtimestamp(time.time()+from_time)
if isinstance(to_time, int):
to_time = datetime.fromtimestamp(time.time()+to_time)
# Ensure that the to_time is the larger
if from_time > to_time:
s = from_time
from_time = to_time
to_time = s
# Stop if the tiems are equal
elif from_time == to_time:
return "0 " + _pluralize_granularity(granularity)
# Collect up all the differences
deltas = {'century': 0, 'decade': 0, 'year': 0, 'month': 0, 'day': 0,
'hour': 0, 'minute': 0, 'second' : 0}
# Collect the easy deltas
for field in ['month', 'hour', 'day', 'minute', 'second']:
deltas[field] = getattr(to_time,field) - getattr(from_time,field)
# deal with year, century and decade
delta_year = to_time.year - from_time.year
if delta_year >= 100:
deltas['century'] = delta_year // 100
if delta_year % 100 >= 10:
deltas['decade'] = delta_year // 10 - deltas['century'] * 10
if delta_year % 10:
deltas['year'] = delta_year % 10
# Now we need to deal with the negative deltas, as we move from
# the smallest granularity to the largest when we encounter a negative
# we will 'borrow' from the next highest value. Because to_time is
# the larger of the two,
carry_over = [('second', 'minute', granularity_size['second']),
('minute', 'hour', granularity_size['minute']),
('hour', 'day', granularity_size['hour'])]
_process_carryover(deltas, carry_over)
# Day is its own special animal. We need to deal with negative days
# differently depending on what months we are spanning across. We need to
# look up the from_time.month value in order to bring the number of days
# to the end of the month.
month_carry = [None, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]
if deltas['day'] < 0:
deltas['month'] -= 1
# Deal with leap years
if (from_time.month) == 2 and _is_leap_year(from_time.year):
deltas['day'] += 29
else:
deltas['day'] += month_carry[from_time.month]
carry_over = [('month', 'year', granularity_size['month']),
('year', 'decade', granularity_size['year']),
('decade', 'century', granularity_size['decade'])]
_process_carryover(deltas, carry_over)
# Display the differences we care about, at this point we should only have
# positive deltas
return_strings = []
for g in granularities:
delta = deltas[g]
# This is the finest granularity we will display
if g == granularity:
# We can only use rounding if the granularity is higher than
# seconds
if round and g != 'second':
i = granularities.index(g)
# Get the next finest granularity and it's delta
g_p = granularities[i + 1]
delta_p = deltas[g_p]
# Determine if we should round up
if delta_p > granularity_size[g_p] / 2:
delta += 1
if delta != 0:
return_strings.append(_delta_string(delta, g))
if not return_strings:
return "less than 1 " + granularity
break
else:
if delta != 0:
return_strings.append(_delta_string(delta, g))
# We're not rounding, check to see if we have encountered
# any deltas to display, if not our time difference
# is less than our finest granularity
if not return_strings:
return "less than 1 " + granularity
break
# Read the value and continue
else:
if delta != 0:
return_strings.append(_delta_string(delta, g))
if len(return_strings) == 1:
return return_strings[0]
return ", ".join(return_strings[:-1]) + " and " + return_strings[-1]
def time_ago_in_words(from_time, granularity="second", round=False):
"""
Return approximate-time-distance string for ``from_time`` till now.
Same as ``distance_of_time_in_words`` but the endpoint is now.
"""
return distance_of_time_in_words(from_time, datetime.now(),
granularity, round)
WebHelpers-1.3/webhelpers/textile.py 0000644 0001750 0001750 00000341122 11373653355 017205 0 ustar sluggo sluggo #!/usr/bin/env python
# _*_ coding: iso-8859-1 _*_
"""This is Textile
A Humane Web Text Generator
TODO:
* Make it work with Python 2.1.
* Make it work with Python 1.5.2? Or that's too optimistic?
---
To get an overview of all PyTextile's features, simply
type 'tell me about textile.' in a single line.
"""
__authors__ = ["Roberto A. F. De Almeida (roberto@dealmeida.net)",
"Mark Pilgrim (f8dy@diveintomark.org)"]
__version__ = "2.0.10"
__date__ = "2004/10/06"
__copyright__ = """
Copyright (c) 2004, Roberto A. F. De Almeida, http://dealmeida.net/
Copyright (c) 2003, Mark Pilgrim, http://diveintomark.org/
All rights reserved.
Original PHP version:
Version 1.0
21 Feb, 2003
Copyright (c) 2003, Dean Allen, www.textism.com
All rights reserved.
Parts of the documentation and some of the regular expressions are (c) Brad
Choate, http://bradchoate.com/. Thanks, Brad!
"""
__license__ = """
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
* Neither the name Textile nor the names of its contributors may be used to
endorse or promote products derived from this software without specific
prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
"""
__history__ = """
1.0 - 2003/03/19 - MAP - initial release
1.01 - 2003/03/19 - MAP - don't strip whitespace within tags;
map high-bit ASCII to HTML numeric entities
1.02 - 2003/03/19 - MAP - changed hyperlink qtag expression to only
match valid URL characters (per RFC 2396); fixed preg_replace to
not match across line breaks (solves lots of problems with
mistakenly matching overlapping inline markup); fixed whitespace
stripping to only strip whitespace from beginning and end of lines,
not immediately before and after HTML tags.
1.03 - 2003/03/20 - MAP - changed hyperlink qtag again to more
closely match original Textile (fixes problems with links
immediately followed by punctuation -- somewhere Dean is
grinning right now); handle curly apostrophe with "ve"
contraction; clean up empty titles at end.
1.04 - 2003/03/23 - MAP - lstrip input to deal with extra spaces at
beginning of first line; tweaked list loop to handle consecutive lists
1.1 - 2003/06/06 - MAP - created initial test suite for links and images,
and fixed a bunch of related bugs to pass them
1.11 - 2003/07/20 - CL - don't demoronise unicode strings; handle
"they're" properly
1.12 - 2003/07/23 - GW - print debug messages to stderr; handle bq(cite).
1.13 - 2003/07/23 - MAP - wrap bq. text in ...
2 - 2004/03/26 - RAFA - rewritten from (almost) scratch to include
all features from Textile 2 and a little bit more.
2.0.1 - 2004/04/02 - RAFA - Fixed validating function that uses uTidyLib.
2.0.2 - 2004/04/02 - RAFA - Fixed problem with caps letters in URLs.
2.0.3 - 2004/04/19 - RAFA - Multiple classes are allowed, thanks to Dave
Anderson. The "lang" attribute is now removed from , to be valid
XHTML. Fixed UCAS problem.
2.0.4 - 2004/05/20 - RAFA, CLB - Added inline formatting to table cells.
Curt Bergmann fixed a bug with the colspan formatting. Added Amazon
Associated id.
2.0.5 - 2004/06/01 - CL - Applied patch from Chris Lawrence to (1) fix
that Amazon associates ID was being added to all search URIs, (2)
customize the Amazon site used with the AMAZON variable, and (3) added
an "isbn" URI type that links directly to an Amazon product by ISBN or
Amazon ASIN.
2.0.6 - 2004/06/02 - RAFA - Fixed CAPS problem, again. I hope this is
the last time.
2.0.7 - 2004/06/04 - RAFA, MW - Fixed bullet macro, thanks to Adam
Messinger. Added patch from Michal Wallace changing {}.pop() for
compatibility with Python 2.2.x.
2.0.8 - 2004/06/25 - RAFA - Strip tags when adding the content from a
footnote to the reference link. Escaped '<' and '>' in the self-
generated documentation.
2.0.9 - 2004/10/04 - RAFA - In images, if ALT is not defined, add an
empty attribute. Added "LaTeX" style open/close quotes. Fixed a bug
where the acronym definition was being formatted with inline rules.
Handle "broken" lines correctly, removing the
from inside
split HTML tags.
2.0.10 - 2004/10/06 - RAFA, LO - Escape all non-escaped ampersands.
Applied "trivial patch" from Ludvig Omholt to remove newline right
after the tag.
"""
# Set your encoding here.
ENCODING = 'latin-1'
# Output? Non-ASCII characters will be automatically
# converted to XML entities if you choose ASCII.
OUTPUT = 'ascii'
# PyTextile can optionally validate the generated
# XHTML code. We can use either mxTidy or uTidyLib.
# You can change the default behaviour here.
VALIDATE = 0
# If you want h1. to be translated to something other
# than , change this offset. You can also pass it
# as an argument to textile().
HEAD_OFFSET = 0
# If you want to use itex2mml, specify the full path
# to the binary here. You can download it from here:
# http://golem.ph.utexas.edu/~distler/blog/files/itexToMML.tar.gz
itex2mml = None
#itex2mml = '/usr/local/bin/itex2MML'
#itex2mml = '/usr/people/almeida/bin/itex2MML'
# PyTextile can optionally sanitize the generated XHTML,
# which is good for weblog comments or if you don't trust
# yourself.
SANITIZE = 0
# Turn debug on?
DEBUGLEVEL = 0
# Amazon associate for links: "keywords":amazon
# If you don't have one, please consider leaving mine here as
# a small compensation for writing PyTextile. It's commented
# off as default.
#amazon_associate_id = 'bomtempo-21'
amazon_associate_id = None
#AMAZON = 'www.amazon.co.uk'
AMAZON = 'www.amazon.com'
import re
import sys
import os
import sgmllib
try:
import unicodedata
except ImportError:
unicodedata = None
def _in_tag(text, tag):
"""Extracts text from inside a tag.
This function extracts the text from inside a given tag.
It's useful to get the text between or
when using the validators or the colorizer.
"""
if text.count('<%s' % tag):
text = text.split('<%s' % tag, 1)[1]
if text.count('>'):
text = text.split('>', 1)[1]
if text.count(' from input.
code = _in_tag(code_out.getvalue(), 'pre')
# Fix newlines.
code = code.replace('\n', '\n')
return code
except ImportError:
htmlizer = None
# PyTextile can optionally validate the generated
# XHTML code using either mxTidy or uTidyLib.
try:
# This is mxTidy.
from mx.Tidy import Tidy
def _tidy1(text):
"""mxTidy's XHTML validator.
This function is a wrapper to mxTidy's validator.
"""
nerrors, nwarnings, text, errortext = Tidy.tidy(text, output_xhtml=1, numeric_entities=1, wrap=0)
return _in_tag(text, 'body')
_tidy = _tidy1
except ImportError:
try:
# This is uTidyLib.
import tidy
def _tidy2(text):
"""uTidyLib's XHTML validator.
This function is a wrapper to uTidyLib's validator.
"""
text = tidy.parseString(text, output_xhtml=1, add_xml_decl=0, indent=0, tidy_mark=0)
return _in_tag(str(text), 'body')
_tidy = _tidy2
except ImportError:
_tidy = None
# This is good for debugging.
def _debug(s, level=1):
"""Outputs debug information to sys.stderr.
This function outputs debug information if DEBUGLEVEL is
higher than a given treshold.
"""
if DEBUGLEVEL >= level: print >> sys.stderr, s
#############################
# Useful regular expressions.
parameters = {
# Horizontal alignment.
'align': r'''(?:(?:<>|[<>=]) # Either '<>', '<', '>' or '='
(?![^\s]*(?:<>|[<>=]))) # Look-ahead to ensure it happens once
''',
# Horizontal padding.
'padding': r'''(?:[\(\)]+) # Any number of '(' and/or ')'
''',
# Class and/or id.
'classid': r'''( #
(?:\(\#[\w]+\)) # (#id)
| #
(?:\((?:[\w]+(?:\s[\w]+)*) #
(?:\#[\w]+)?\)) # (class1 class2 ... classn#id) or (class1 class2 ... classn)
) #
(?![^\s]*(?:\([\w#]+\))) # must happen once
''',
# Language.
'lang': r'''(?:\[[\w-]+\]) # [lang]
(?![^\s]*(?:\[.*?\])) # must happen once
''',
# Style.
'style': r'''(?:{[^\}]+}) # {style}
(?![^\s]*(?:{.*?})) # must happen once
''',
}
res = {
# Punctuation.
'punct': r'''[\!"#\$%&'()\*\+,\-\./:;<=>\?@\[\\\]\^_`{\|}\~]''',
# URL regular expression.
'url': r'''(?=[a-zA-Z0-9./#]) # Must start correctly
(?: # Match the leading part (proto://hostname, or just hostname)
(?:ftp|https?|telnet|nntp) # protocol
:// # ://
(?: # Optional 'username:password@'
\w+ # username
(?::\w+)? # optional :password
@ # @
)? #
[-\w]+(?:\.\w[-\w]*)+ # hostname (sub.example.com)
| #
(?:mailto:)? # Optional mailto:
[-\+\w]+ # username
\@ # at
[-\w]+(?:\.\w[-\w]*)+ # hostname
| #
(?:[a-z0-9](?:[-a-z0-9]*[a-z0-9])?\.)+ # domain without protocol
(?:com\b # TLD
| edu\b #
| biz\b #
| gov\b #
| in(?:t|fo)\b # .int or .info
| mil\b #
| net\b #
| org\b #
| museum\b #
| aero\b #
| coop\b #
| name\b #
| pro\b #
| [a-z][a-z]\b # two-letter country codes
) #
)? #
(?::\d+)? # Optional port number
(?: # Rest of the URL, optional
/? # Start with '/'
[^.!,?;:"'<>()\[\]{}\s\x7F-\xFF]* # Can't start with these
(?: #
[.!,?;:]+ # One or more of these
[^.!,?;:"'<>()\[\]{}\s\x7F-\xFF]+ # Can't finish with these
#'" # # or ' or "
)* #
)? #
''',
# Block attributes.
'battr': r'''(?P #
(?: %(align)s # alignment
| %(classid)s # class and/or id
| %(padding)s # padding tags
| %(lang)s # [lang]
| %(style)s # {style}
)+ #
)? #
''' % parameters,
# (Un)ordered list attributes.
'olattr': r'''(?P #
(?: %(align)s # alignment
| ((?:\(\#[\w]+\)) # (#id)
| #
(?:\((?:[\w]+(?:\s[\w]+)*) #
(?:\#[\w]+)?\)) # (class1 class2 ... classn#id) or (class1 class2 ... classn)
) #
| %(padding)s # padding tags
| %(lang)s # [lang]
| %(style)s # {style}
)+ #
)? #
''' % parameters,
# List item attributes.
'liattr': r'''(?P #
(?: %(align)s # alignment
| %(classid)s # class and/or id
| %(padding)s # padding tags
| %(lang)s # [lang]
| %(style)s # {style}
)+ #
)? #
''' % parameters,
# Qtag attributes.
'qattr': r'''(?P #
(?: %(classid)s # class and/or id
| %(lang)s # [lang]
| %(style)s # {style}
)+ #
)? #
''' % parameters,
# Link attributes.
'lattr': r'''(?P # Links attributes
(?: %(align)s # alignment
| %(classid)s # class and/or id
| %(lang)s # [lang]
| %(style)s # {style}
)+ #
)? #
''' % parameters,
# Image attributes.
'iattr': r'''(?P #
(?: #
(?: [<>]+ # horizontal alignment tags
(?![^\s]*(?:[<>]))) # (must happen once)
| #
(?: [\-\^~]+ # vertical alignment tags
(?![^\s]*(?:[\-\^~]))) # (must happen once)
| %(classid)s # class and/or id
| %(padding)s # padding tags
| %(style)s # {style}
)+ #
)? #
''' % parameters,
# Resize attributes.
'resize': r'''(?: #
(?:([\d]+%?)x([\d]+%?)) # 20x10
| #
(?: # or
(?:([\d]+)%?w\s([\d]+)%?h) # 10h 20w
| # or
(?:([\d]+)%?h\s([\d]+)%?w) # 20w 10h
) #
)? #
''',
# Table attributes.
'tattr': r'''(?P #
(?: #
(?: [\^~] # vertical alignment
(?![^\s]*(?:[\^~]))) # (must happen once)
| %(align)s # alignment
| %(lang)s # [lang]
| %(style)s # {style}
| %(classid)s # class and/or id
| %(padding)s # padding
| _ # is this a header row/cell?
| \\\d+ # colspan
| /\d+ # rowspan
)+ #
)? #
''' % parameters,
}
def preg_replace(pattern, replacement, text):
"""Alternative re.sub that handles empty groups.
This acts like re.sub, except it replaces empty groups with ''
instead of raising an exception.
"""
def replacement_func(matchobj):
counter = 1
rc = replacement
_debug(matchobj.groups())
for matchitem in matchobj.groups():
if not matchitem:
matchitem = ''
rc = rc.replace(r'\%s' % counter, matchitem)
counter += 1
return rc
p = re.compile(pattern)
_debug(pattern)
return p.sub(replacement_func, text)
def html_replace(pattern, replacement, text):
"""Replacement outside HTML tags.
Does a preg_replace only outside HTML tags.
"""
# If there is no html, do a simple search and replace.
if not re.search(r'''<.*>''', text):
return preg_replace(pattern, replacement, text)
else:
lines = []
# Else split the text into an array at <>.
for line in re.split('(<.*?>)', text):
if not re.match('<.*?>', line):
line = preg_replace(pattern, replacement, line)
lines.append(line)
return ''.join(lines)
# PyTextile can optionally sanitize the generated XHTML,
# which is good for weblog comments. This code is from
# Mark Pilgrim's feedparser.
class _BaseHTMLProcessor(sgmllib.SGMLParser):
elements_no_end_tag = ['area', 'base', 'basefont', 'br', 'col', 'frame', 'hr',
'img', 'input', 'isindex', 'link', 'meta', 'param']
def __init__(self):
sgmllib.SGMLParser.__init__(self)
def reset(self):
self.pieces = []
sgmllib.SGMLParser.reset(self)
def normalize_attrs(self, attrs):
# utility method to be called by descendants
attrs = [(k.lower(), sgmllib.charref.sub(lambda m: unichr(int(m.groups()[0])), v).strip()) for k, v in attrs]
attrs = [(k, k in ('rel', 'type') and v.lower() or v) for k, v in attrs]
return attrs
def unknown_starttag(self, tag, attrs):
# called for each start tag
# attrs is a list of (attr, value) tuples
# e.g. for , tag="pre", attrs=[("class", "screen")]
strattrs = "".join([' %s="%s"' % (key, value) for key, value in attrs])
if tag in self.elements_no_end_tag:
self.pieces.append("<%(tag)s%(strattrs)s />" % locals())
else:
self.pieces.append("<%(tag)s%(strattrs)s>" % locals())
def unknown_endtag(self, tag):
# called for each end tag, e.g. for , tag will be "pre"
# Reconstruct the original end tag.
if tag not in self.elements_no_end_tag:
self.pieces.append("" % locals())
def handle_charref(self, ref):
# called for each character reference, e.g. for " ", ref will be "160"
# Reconstruct the original character reference.
self.pieces.append("&#%(ref)s;" % locals())
def handle_entityref(self, ref):
# called for each entity reference, e.g. for "©", ref will be "copy"
# Reconstruct the original entity reference.
self.pieces.append("&%(ref)s;" % locals())
def handle_data(self, text):
# called for each block of plain text, i.e. outside of any tag and
# not containing any character or entity references
# Store the original text verbatim.
self.pieces.append(text)
def handle_comment(self, text):
# called for each HTML comment, e.g.
# Reconstruct the original comment.
self.pieces.append("" % locals())
def handle_pi(self, text):
# called for each processing instruction, e.g.
# Reconstruct original processing instruction.
self.pieces.append("" % locals())
def handle_decl(self, text):
# called for the DOCTYPE, if present, e.g.
#
# Reconstruct original DOCTYPE
self.pieces.append("" % locals())
def output(self):
"""Return processed HTML as a single string"""
return "".join(self.pieces)
class _HTMLSanitizer(_BaseHTMLProcessor):
acceptable_elements = ['a', 'abbr', 'acronym', 'address', 'area', 'b', 'big',
'blockquote', 'br', 'button', 'caption', 'center', 'cite', 'code', 'col',
'colgroup', 'dd', 'del', 'dfn', 'dir', 'div', 'dl', 'dt', 'em', 'fieldset',
'font', 'form', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'hr', 'i', 'img', 'input',
'ins', 'kbd', 'label', 'legend', 'li', 'map', 'menu', 'ol', 'optgroup',
'option', 'p', 'pre', 'q', 's', 'samp', 'select', 'small', 'span', 'strike',
'strong', 'sub', 'sup', 'table', 'tbody', 'td', 'textarea', 'tfoot', 'th',
'thead', 'tr', 'tt', 'u', 'ul', 'var']
acceptable_attributes = ['abbr', 'accept', 'accept-charset', 'accesskey',
'action', 'align', 'alt', 'axis', 'border', 'cellpadding', 'cellspacing',
'char', 'charoff', 'charset', 'checked', 'cite', 'class', 'clear', 'cols',
'colspan', 'color', 'compact', 'coords', 'datetime', 'dir', 'disabled',
'enctype', 'for', 'frame', 'headers', 'height', 'href', 'hreflang', 'hspace',
'id', 'ismap', 'label', 'lang', 'longdesc', 'maxlength', 'media', 'method',
'multiple', 'name', 'nohref', 'noshade', 'nowrap', 'prompt', 'readonly',
'rel', 'rev', 'rows', 'rowspan', 'rules', 'scope', 'selected', 'shape', 'size',
'span', 'src', 'start', 'summary', 'tabindex', 'target', 'title', 'type',
'usemap', 'valign', 'value', 'vspace', 'width']
unacceptable_elements_with_end_tag = ['script', 'applet']
# This if for MathML.
mathml_elements = ['math', 'mi', 'mn', 'mo', 'mrow', 'msup']
mathml_attributes = ['mode', 'xmlns']
acceptable_elements = acceptable_elements + mathml_elements
acceptable_attributes = acceptable_attributes + mathml_attributes
def reset(self):
_BaseHTMLProcessor.reset(self)
self.unacceptablestack = 0
def unknown_starttag(self, tag, attrs):
if not tag in self.acceptable_elements:
if tag in self.unacceptable_elements_with_end_tag:
self.unacceptablestack += 1
return
attrs = self.normalize_attrs(attrs)
attrs = [(key, value) for key, value in attrs if key in self.acceptable_attributes]
_BaseHTMLProcessor.unknown_starttag(self, tag, attrs)
def unknown_endtag(self, tag):
if not tag in self.acceptable_elements:
if tag in self.unacceptable_elements_with_end_tag:
self.unacceptablestack -= 1
return
_BaseHTMLProcessor.unknown_endtag(self, tag)
def handle_pi(self, text):
pass
def handle_decl(self, text):
pass
def handle_data(self, text):
if not self.unacceptablestack:
_BaseHTMLProcessor.handle_data(self, text)
class Textiler:
"""Textile formatter.
This is the base class for the PyTextile text processor.
"""
def __init__(self, text=''):
"""Instantiate the class, passing the text to be formatted.
Here we pre-process the text and collect all the link
lookups for later.
"""
self.text = text
# Basic regular expressions.
self.res = res
# Smart searches.
self.searches = {}
self.searches['imdb'] = 'http://www.imdb.com/Find?for=%s'
self.searches['google'] = 'http://www.google.com/search?q=%s'
self.searches['python'] = 'http://www.python.org/doc/current/lib/module-%s.html'
if amazon_associate_id:
self.searches['isbn'] = ''.join(['http://', AMAZON, '/exec/obidos/ASIN/%s/', amazon_associate_id])
self.searches['amazon'] = ''.join(['http://', AMAZON, '/exec/obidos/external-search?mode=blended&keyword=%s&tag=', amazon_associate_id])
else:
self.searches['isbn'] = ''.join(['http://', AMAZON, '/exec/obidos/ASIN/%s'])
self.searches['amazon'] = ''.join(['http://', AMAZON, '/exec/obidos/external-search?mode=blended&keyword=%s'])
# These are the blocks we know.
self.signatures = [
# Paragraph.
(r'''^p # Paragraph signature
%(battr)s # Paragraph attributes
(?P\.) # .
(?P\.)? # Extended paragraph denoted by a second dot
\s # whitespace
(?P.*) # text
''' % self.res, self.paragraph),
# Pre-formatted text.
(r'''^pre # Pre signature
%(battr)s # Pre attributes
(?P\.) # .
(?P\.)? # Extended pre denoted by a second dot
\s # whitespace
(?P.*) # text
''' % self.res, self.pre),
# Block code.
(r'''^bc # Blockcode signature
%(battr)s # Blockcode attributes
(?P\.) # .
(?P\.)? # Extended blockcode denoted by a second dot
\s # whitespace
(?P.*) # text
''' % self.res, self.bc),
# Blockquote.
(r'''^bq # Blockquote signature
%(battr)s # Blockquote attributes
(?P\.) # .
(?P\.)? # Extended blockquote denoted by a second dot
(:(?P # Optional cite attribute
( #
%(url)s # URL
| "[\w]+(?:\s[\w]+)*" # "Name inside quotes"
)) #
)? #
\s # whitespace
(?P.*) # text
''' % self.res, self.blockquote),
# Header.
(r'''^h # Header signature
(?P\d) # Header number
%(battr)s # Header attributes
(?P\.) # .
(?P\.)? # Extended header denoted by a second dot
\s # whitespace
(?P.*) # text
''' % self.res, self.header),
# Footnote.
(r'''^fn # Footnote signature
(?P[\d]+) # Footnote number
(?P\.) # .
(?P\.)? # Extended footnote denoted by a second dot
\s # whitespace
(?P.*) # text
''', self.footnote),
# Definition list.
(r'''^dl # Definition list signature
%(battr)s # Definition list attributes
(?P\.) # .
(?P\.)? # Extended definition list denoted by a second dot
\s # whitespace
(?P.*) # text
''' % self.res, self.dl),
# Ordered list (attributes to first - ).
(r'''^%(olattr)s # Ordered list attributes
\# # Ordered list signature
%(liattr)s # List item attributes
(?P\.)? # .
\s # whitespace
(?P.*) # text
''' % self.res, self.ol),
# Unordered list (attributes to first
- ).
(r'''^%(olattr)s # Unrdered list attributes
\* # Unordered list signature
%(liattr)s # Unordered list attributes
(?P\.)? # .
\s # whitespace
(?P.*) # text
''' % self.res, self.ul),
# Escaped text.
(r'''^==?(?P.*?)(==)?$ # Escaped text
''', self.escape),
(r'''^(?P<.*)$ # XHTML tag
''', self.escape),
# itex code.
(r'''^(?P # itex code
\\\[ # starts with \[
.*? # complicated mathematical equations go here
\\\]) # ends with \]
''', self.itex),
# Tables.
(r'''^table # Table signature
%(tattr)s # Table attributes
(?P\.) # .
(?P\.)? # Extended blockcode denoted by a second dot
\s # whitespace
(?P.*) # text
''' % self.res, self.table),
# Simple tables.
(r'''^(?P
\|
.*)
''', self.table),
# About.
(r'''^(?Ptell\sme\sabout\stextile\.)$''', self.about),
]
def preprocess(self):
"""Pre-processing of the text.
Remove whitespace, fix carriage returns.
"""
# Remove whitespace.
self.text = self.text.strip()
# Zap carriage returns.
self.text = self.text.replace("\r\n", "\n")
self.text = self.text.replace("\r", "\n")
# Minor sanitizing.
self.text = self.sanitize(self.text)
def grab_links(self):
"""Grab link lookups.
Check the text for link lookups, store them in a
dictionary, and clean them up.
"""
# Grab links like this: '[id]example.com'
links = {}
p = re.compile(r'''(?:^|\n)\[([\w]+?)\](%(url)s)(?:$|\n)''' % self.res, re.VERBOSE)
for key, link in p.findall(self.text):
links[key] = link
# And clear them from the text.
self.text = p.sub('', self.text)
return links
def process(self, head_offset=HEAD_OFFSET, validate=VALIDATE, sanitize=SANITIZE, output=OUTPUT, encoding=ENCODING):
"""Process the text.
Here we actually process the text, splitting the text in
blocks and applying the corresponding function to each
one of them.
"""
# Basic global changes.
self.preprocess()
# Grab lookup links and clean them from the text.
self._links = self.grab_links()
# Offset for the headers.
self.head_offset = head_offset
# Process each block.
self.blocks = self.split_text()
text = []
for [function, captures] in self.blocks:
text.append(function(**captures))
text = '\n\n'.join(text)
# Add titles to footnotes.
text = self.footnotes(text)
# Convert to desired output.
if isinstance(text, str):
text = unicode(text, encoding)
text = text.encode(output, 'xmlcharrefreplace')
# Sanitize?
if sanitize:
p = _HTMLSanitizer()
p.feed(text)
text = p.output()
# Validate output.
if _tidy and validate:
text = _tidy(text)
return text
def sanitize(self, text):
"""Fix single tags.
Fix tags like
![]() ,
and
.
---
h1. Sanitizing
Textile can help you generate valid XHTML(eXtensible HyperText Markup Language).
It will fix any single tags that are not properly closed, like
@![]() @, @
@ and @
@.
If you have "mx.Tidy":http://www.egenix.com/files/python/mxTidy.html
and/or "µTidyLib":http://utidylib.sourceforge.net/ installed,
it also can optionally validade the generated code with these wrappers
to ensure 100% valid XHTML(eXtensible HyperText Markup Language).
"""
# Fix single tags like ![]() and
.
text = preg_replace(r'''<(img|br|hr)(.*?)(?:\s*/?\s*)?>''', r'''<\1\2 />''', text)
# Remove ampersands.
text = preg_replace(r'''&(?!#?[xX]?(?:[0-9a-fA-F]+|\w{1,8});)''', r'''&''', text)
return text
def split_text(self):
"""Process the blocks from the text.
Split the blocks according to the signatures, join extended
blocks and associate each one of them with a function to
process them.
---
h1. Blocks
Textile process your text by dividing it in blocks. Each block
is identified by a signature and separated from other blocks by
an empty line.
All signatures should end with a period followed by a space. A
header @@ can be done this way:
pre. h1. This is a header 1.
Blocks may continue for multiple paragraphs of text. If you want
a block signature to stay "active", use two periods after the
signature instead of one. For example:
pre.. bq.. This is paragraph one of a block quote.
This is paragraph two of a block quote.
=p. Now we're back to a regular paragraph.
p. Becomes:
pre..
This is paragraph one of a block quote.
This is paragraph two of a block quote.
Now we’re back to a regular paragraph.
p. The blocks can be customised by adding parameters between the
signature and the period. These include:
dl. {style rule}:A CSS(Cascading Style Sheets) style rule.
[ll]:A language identifier (for a "lang" attribute).
(class) or (#id) or (class#id):For CSS(Cascading Style Sheets) class and id attributes.
>, <, =, <>:Modifier characters for alignment. Right-justification, left-justification, centered, and full-justification. The paragraph will also receive the class names "right", "left", "center" and "justify", respectively.
( (one or more):Adds padding on the left. 1em per "(" character is applied. When combined with the align-left or align-right modifier, it makes the block float.
) (one or more):Adds padding on the right. 1em per ")" character is applied. When combined with the align-left or align-right modifier, it makes the block float.
Here's an overloaded example:
pre. p(())>(class#id)[en]{color:red}. A simple paragraph.
Becomes:
pre. A simple paragraph.
"""
# Clear signature.
clear_sig = r'''^clear(?P[<>])?\.$'''
clear = None
extending = 0
# We capture the \n's because they are important inside "pre..".
blocks = re.split(r'''(\n{2,})''', self.text)
output = []
for block in blocks:
# Check for the clear signature.
m = re.match(clear_sig, block)
if m:
clear = m.group('alignment')
if clear:
clear = {'<': 'clear:left;', '>': 'clear:right;'}[clear]
else:
clear = 'clear:both;'
else:
# Check each of the code signatures.
for regexp, function in self.signatures:
p = re.compile(regexp, (re.VERBOSE | re.DOTALL))
m = p.match(block)
if m:
# Put everything in a dictionary.
captures = m.groupdict()
# If we are extending a block, we require a dot to
# break it, so we can start lines with '#' inside
# an extended without matching an ordered list.
if extending and not captures.get('dot', None):
output[-1][1]['text'] += block
break
elif captures.has_key('dot'):
del captures['dot']
# If a signature matches, we are not extending a block.
extending = 0
# Check if we should extend this block.
if captures.has_key('extend'):
extending = captures['extend']
del captures['extend']
# Apply head_offset.
if captures.has_key('header'):
captures['header'] = int(captures['header']) + self.head_offset
# Apply clear.
if clear:
captures['clear'] = clear
clear = None
# Save the block to be processed later.
output.append([function, captures])
break
else:
if extending:
# Append the text to the last block.
output[-1][1]['text'] += block
elif block.strip():
output.append([self.paragraph, {'text': block}])
return output
def parse_params(self, parameters, clear=None, align_type='block'):
"""Parse the parameters from a block signature.
This function parses the parameters from a block signature,
splitting the information about class, id, language and
style. The positioning (indentation and alignment) is parsed
and stored in the style.
A paragraph like:
p>(class#id){color:red}[en]. Paragraph.
or:
p{color:red}[en](class#id)>. Paragraph.
will have its parameters parsed to:
output = {'lang' : 'en',
'class': 'class',
'id' : 'id',
'style': 'color:red;text-align:right;'}
Note that order is not important.
"""
if not parameters:
if clear:
return {'style': clear}
else:
return {}
output = {}
# Match class from (class) or (class#id).
m = re.search(r'''\((?P[\w]+(\s[\w]+)*)(\#[\w]+)?\)''', parameters)
if m: output['class'] = m.group('class')
# Match id from (#id) or (class#id).
m = re.search(r'''\([\w]*(\s[\w]+)*\#(?P[\w]+)\)''', parameters)
if m: output['id'] = m.group('id')
# Match [language].
m = re.search(r'''\[(?P[\w-]+)\]''', parameters)
if m: output['lang'] = m.group('lang')
# Match {style}.
m = re.search(r'''{(?P |