Cyclone-Team/gramps
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

html.py: Add newpage() function and docstrings

Browse Source 
svn: r12365
This commit is contained in:
Gerald Britton 2009-03-20 16:22:12 +00:00
parent a39b1ba156
commit 5a0414db32
1 changed files with 183 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

202
src/plugins/webreport/html.py
View File

@ -20,13 +20,21 @@
# $Id: html.py 10874 2009-03-03 18:00:00Z gbritton $ # $Id: html.py 10874 2009-03-03 18:00:00Z gbritton $
#------------------------------------------------------------------------
#
# Html
#
#------------------------------------------------------------------------
""" """
HTML operations. HTML operations.
This module exports one class and two functions. This module exports one class and one function.
""" """
__all__ = ['Html','newpage']
#------------------------------------------------------------------------ #------------------------------------------------------------------------
# #
# Constants # Constants
@ -77,14 +85,94 @@ _START_CLOSE = (
'meta', 'meta',
'param' 'param'
) )
#------------------------------------------------------------------------
# #
# helper functions.
#
#------------------------------------------------------------------------
def print_(line):
"""
Print function
"""
print line
def newpage(title='Title', encoding='utf-8', lang='en'):
"""
This function prepares a new Html class based page and returns
@type title: string
@param title: title for HTML page. Default='Title'
@type encoding: string
@param encoding: encoding to be used. Default = 'utf-8'
@type lang: string
@param lang: language to be used. Defaul = 'en'
@rtype: three object references
@return: references to the newly-created Html instances for
page, head and body
"""
meta1 = 'http-equiv="content-type" content="text/html;charset=%s"'
meta2 = 'http-equiv="Content-Style-Type" content="text/css"'
page = Html(
xmlns=_XMLNS,
attr='xml:lang="%s" lang="%s"' % ((lang,)*2)
)
page.addXML(encoding=encoding)
page.addDOCTYPE()
head = Html('head')
head += Html('title', title, inline=True, indent=True)
head += Html('meta', attr=meta1 % encoding, indent=True)
head += Html('meta', attr=meta2, indent=True)
body = Html('body')
page += (head, body)
return page, head, body
#------------------------------------------------------------------------
#
# Html class.
#
#------------------------------------------------------------------------
class Html(list): class Html(list):
""" """
HTML class. HTML class: Manages a rooted tree of HTML objects
""" """
__slots__ = ['items','indent','inline','end'] __slots__ = ['items', 'indent', 'inline', 'end']
# #
def __init__(self, tag='html', *args, **keywargs): def __init__(self, tag='html', *args, **keywargs):
"""
Class Constructor: Returns a new instance of the Html class
@type tag: string
@param tag: The HTML tag. Default is 'html'
@type args: optional positional parameters
@param args: 0 more positional arguments to be inserted between
opening and closing HTML tags.
@type indent: boolean
@param indent: True ==> indent this object with respect to its parent
False ==> do not indent this object
Defauls to False
@type inline: boolean
@param inline: True ==> instructs the write() method to output this
object and any child objects as a single string
False ==> output this object and its contents one string
at a time
Defaults to False
@type close: boolean or None
@param close: True ==> this tag should be closed normally
e.g. <tag>...</tag>
False ==> this tag should be automatically closed
e.g. <tag />
None ==> do not provide any closing for this tag
@type keywargs: optional keyword parameters
@param keywargs: 0 or more keyword=argument pairs that should be
copied into the opening tag as keyword="argument"
attributes
@rtype: object reference
@return: reference to the newly-created Html instance
"""
#
super(Html, self).__init__([]) super(Html, self).__init__([])
attr, indent, close, inline = '', False, True, False attr, indent, close, inline = '', False, True, False
# #
@ -112,9 +200,9 @@ class Html(list):
self += [tag] self += [tag]
self.end = None self.end = None
else: else:
if tag in _START_CLOSE: # is tag in special list that need no closer? if tag in _START_CLOSE: # if tag in special list
self.end = close = False self.end = close = False # it needs no closing tag
begin = '<%s%s%s>' % ( # build opening tag, passing in attributes begin = '<%s%s%s>' % ( # build opening tag; pass in attributes
tag, tag,
attr, attr,
('' if close or close is None else ' /') ('' if close or close is None else ' /')
@ -125,6 +213,15 @@ class Html(list):
) )
# #
def __add__(self, value): def __add__(self, value):
"""
Overload function for + and += operators
@type value: object
@param value: object to be added
@rtype: object reference
@return: reference to object with new value added
"""
if isinstance(value, Html) or not hasattr(value, '__iter__'): if isinstance(value, Html) or not hasattr(value, '__iter__'):
value = [value] value = [value]
index = len(self) - (1 if self.end else 0) index = len(self) - (1 if self.end else 0)
@ -134,23 +231,49 @@ class Html(list):
__iadd__ = append = extend = __add__ __iadd__ = append = extend = __add__
# #
def replace(self, cur_value, value): def replace(self, cur_value, value):
"""
Replace current value with new value
@type cur_value: object
@param cur_value: value of object to be replaced
@type value: object
@param value: replacement value
@rtype: object reference
@return: reference to object with new value added
"""
self[self.index(cur_value)] = value self[self.index(cur_value)] = value
# #
def __sub__(self, value): def __sub__(self, value):
"""
Overload function for - and -= operators
@type value: object
@param value: object to be removed
@rtype: object reference
@return: reference to object with value removed
"""
del self[self.index(value)] del self[self.index(value)]
return self return self
# #
__isub__ = remove = __sub__ __isub__ = remove = __sub__
#
def print_(data):
print data
# #
def __str__(self): def __str__(self):
"""
Returns string representation
@rtype: string
@return: string representatiof object
"""
return '%s'*len(self) % tuple(self[:]) return '%s'*len(self) % tuple(self[:])
# #
def __iter__(self): def __iter__(self):
"""
Iterator function: returns a generator that performs an
insertion-order tree traversal and yields each item found.
"""
for item in self[:]: # loop through all list elements for item in self[:]: # loop through all list elements
if isinstance(item, self.Html): # if nested list found if isinstance(item, Html): # if nested list found
for sub_item in item: # recurse for sub_item in item: # recurse
yield sub_item yield sub_item
else: else:
@ -159,39 +282,64 @@ class Html(list):
iterkeys = itervalues = iteritems = __iter__ iterkeys = itervalues = iteritems = __iter__
# #
def write(self, method=print_, tabs=''): def write(self, method=print_, tabs=''):
"""
Output function: performs an insertion-order tree traversal
and calls supplied method for each item found.
@type method: function reference
@param method: function to call with each item found
@type tabs: string
@oaram tabs: starting indentation
"""
tabs += '\t' if self.indent else '' tabs += '\t' if self.indent else ''
if self.inline: # if inline, write all list and if self.inline: # if inline, write all list and
method('%s%s' % (tabs,self)) # nested list elements method('%s%s' % (tabs, self)) # nested list elements
# #
else: else:
for item in self[:]: # not inline: write one at a time for item in self[:]: # else write one at a time
if isinstance(item, Html): if isinstance(item, Html):
item.write(method=method, tabs=tabs) # recurse if nested item.write(method=method, tabs=tabs) # recurse if nested
else: else:
method('%s%s' % (tabs, item)) # write the line if not method('%s%s' % (tabs, item)) # else write the line
# #
def addXML(self, version=1.0, encoding="UTF-8", standalone="no"): def addXML(self, version=1.0, encoding="UTF-8", standalone="no"):
xml = XML(version=version, encoding=encoding, standalone=standalone) """
self.insert(0, xml) Add an XML statement to the start of the list for this object
#
def addDOCTYPE(self, name='html', external_id=_XHTML10_STRICT, *args): @type version: decimal number
doctype = DOCTYPE(name='html', external_id=external_id, *args) @param version: version of XML to be used. Defaults to 1.0
if len(self) and self[0][:6] == '<?xml ': @type encoding: string
self.insert(1, doctype) @param encoding: encoding method to be used. Defaults to "UTF-8"
else: @type standalone: string
self.insert(0, doctype) @param standalone: "yes" or "no". Defaults to "no"
# """
def XML(version=1.0, encoding="UTF-8", standalone="no"): xml = '<?xml %s %s %s?>' % (
return '<?xml %s %s %s?>' % (
'version="%s"' % version, 'version="%s"' % version,
'encoding="%s"' % encoding, 'encoding="%s"' % encoding,
'standalone="%s"' % standalone 'standalone="%s"' % standalone
) )
self.insert(0, xml)
# #
def DOCTYPE(name='html', external_id=_XHTML10_STRICT, *args): def addDOCTYPE(self, name='html', external_id=_XHTML10_STRICT, *args):
return '<!DOCTYPE %s %s%s>' % ( """
Add a DOCTYPE statement to the start of the list
@type name: string
@param name: name of this DOCTYPE. Defaults to "html"
@type external_id: string
@param external_id: external identifier of this DOCTYPE.
Defaults to XHTML 1.0 STRICT
@type args: object
@param args: 0 or more positional parameters to be added to this
DOCTYPE.
"""
doctype = '<!DOCTYPE %s %s%s>' % (
name, name,
external_id, external_id,
' %s'*len(args) % args ' %s'*len(args) % args
) )
if len(self) and self[0][:6] == '<?xml ':
self.insert(1, doctype)
else:
self.insert(0, doctype)