Merge lp:~justas.sadzevicius/schooltool/schooltool.pdf_testing into lp:~schooltool-owners/schooltool/schooltool

[Justas Sadzevičius]

[Justas Sadzevičius (justas.sadzevicius)]

For PDF reports: testing helpers for stories of Reportlab platypus flowables.

[lp:~justas.sadzevicius/schooltool/schooltool.pdf_testing]

2467. By Justas Sadzevičius on 2009-03-30

Refactored helpers to a single StoryXML class.

2468. By Justas Sadzevičius on 2009-03-30

Whitespace

2469. By Justas Sadzevičius on 2009-03-31

Improved readability of README.txt and test_pdf a bit.

[Ignas Mikalajūnas (ignas)]

review: Approve

=== modified file 'src/schooltool/testing/README.txt'
--- src/schooltool/testing/README.txt	2008-01-15 18:46:51 +0000
+++ src/schooltool/testing/README.txt	2009-03-30 12:24:08 +0000
@@ -161,3 +161,60 @@
     >>> print analyze.queryHTML('/html/body/h1', html)[0]
     <h1>This is my page!</h1>
 
+
+Reportlab PDF story testing
+---------------------------
+
+Schooltool PDF reports utilize Reportlab platypus module.  A report is
+built from a list of platypus flowables known as as 'story'.
+
+Let's build a short pdf story.
+
+    >>> from reportlab.lib.styles import ParagraphStyle
+    >>> from reportlab.platypus.paragraph import Paragraph
+    >>> from reportlab.platypus.flowables import PageBreak
+
+    >>> style = ParagraphStyle(name='Test', fontName='Times-Roman')
+
+    >>> story = [
+    ...     Paragraph('Hello world', style),
+    ...     PageBreak(),
+    ...     Paragraph('A new page', style)]
+
+There are several helpers for testing the stories.
+
+    >>> from schooltool.testing import pdf
+
+The tools aim to build a human readable XML representation of the
+story.  There is a helper which prints the formatted XML:
+
+    >>> pdf.printStoryXML(story)
+    <story>
+    <Paragraph>Hello world</Paragraph>
+    <PageBreak/>
+    <Paragraph>A new page</Paragraph>
+    </story>
+
+As with HTML analyzation tools, there are helpers for XPath queries:
+
+    >>> pdf.queryStory('//Paragraph', story)
+    ['<Paragraph>Hello world</Paragraph>',
+     '<Paragraph>A new page</Paragraph>']
+
+    >>> pdf.printQuery('//Paragraph', story)
+    <Paragraph>Hello world</Paragraph>
+    <Paragraph>A new page</Paragraph>
+
+These helpers also work on single platypus flowables:
+
+    >>> pdf.printStoryXML(Paragraph('Some text', style))
+    <story>
+    <Paragraph>Some text</Paragraph>
+    </story>
+
+If these helpers are not sufficient, we can build the raw XML document.
+
+    >>> document = pdf.getStoryXML(story)
+    >>> document
+    <...ElementTree object ...>
+
 
=== added file 'src/schooltool/testing/pdf.py'
--- src/schooltool/testing/pdf.py	1970-01-01 00:00:00 +0000
+++ src/schooltool/testing/pdf.py	2009-03-30 11:49:24 +0000
@@ -0,0 +1,240 @@
+#
+# SchoolTool - common information systems platform for school administration
+# Copyright (c) 2005 Shuttleworth Foundation
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+#
+"""
+SchoolTool Reporlab PDF testing helpers.
+
+$Id$
+
+"""
+
+import cgi
+from cStringIO import StringIO
+from lxml import etree
+
+from reportlab import platypus
+
+
+def getStoryXML(story):
+    """Build human readable XML from a story of Reportlab flowables"""
+    parser = Parser(formatters=_xml_formatters,
+                    default=format_classname_xml)
+    text = u'<story>\n%s\n</story>' % parser(story)
+    return etree.parse(StringIO(text.encode('UTF-8')))
+
+
+def printStoryXML(story):
+    print etree.tostring(getStoryXML(story),
+                         pretty_print=True)
+
+def queryStory(xpath, story):
+    """Perform an XPath query on XML built from the story of
+    Reportlab flowables"""
+    doc = getStoryXML(story)
+    result = []
+    for node in doc.xpath(xpath):
+        if isinstance(node, basestring):
+            result.append(node)
+        else:
+            result.append(etree.tostring(node, pretty_print=True))
+    return [s.strip() for s in result]
+
+
+def printQuery(xpath, story):
+    """Print results of XPath query on XML built from the story of
+    Reportlab flowables"""
+    for entry in queryStory(xpath, story):
+        print entry
+
+
+null_formatter = lambda parser, flowable: u''
+
+
+class Parser(object):
+    def __init__(self, formatters={}, default=null_formatter):
+        self.formatters = formatters.copy()
+        self.default = default
+
+    def __call__(self, flowable):
+        formatter = self.formatters.get(flowable.__class__, self.default)
+        return formatter(self, flowable)
+
+
+def format_flowable_list(parser, flowables):
+    parsed = [parser(flowable)
+              for flowable in flowables]
+    return '\n'.join([text for text in parsed if text])
+
+
+def format_str_text(parser, flowable):
+    return unicode(flowable)
+
+
+def format_classname_text(parser, flowable):
+    return unicode(flowable.__class__.__name__)
+
+
+def format_str_xml(parser, flowable):
+    return cgi.escape(unicode(flowable))
+
+
+def format_classname_xml(parser, flowable):
+    return u'<%s />' % format_classname_text(parser, flowable)
+
+
+def format_container_xml(parser, flowable):
+    tag_name = format_classname_text(parser, flowable)
+    content = parser(flowable._content)
+    return u'<%s>\n%s\n</%s>' % (tag_name, content, tag_name)
+
+
+def format_preformatted_xml(parser, flowable):
+    tag_name = format_classname_text(parser, flowable)
+    return u'<%s bulletText="%s">%s</%s>' % (
+        tag_name,
+        cgi.escape(flowable.bulletText),
+        cgi.escape(u'\n'.join(flowable.lines)),
+        tag_name)
+
+
+def format_table_xml(parser, flowable):
+    tag_name = format_classname_text(parser, flowable)
+    text = u'<%s>\n' % tag_name
+    for row in flowable._cellvalues:
+        text += '<tr>\n'
+        for cell in row:
+            text += '<td>%s</td>\n' % parser(cell)
+        text += '</tr>\n'
+    text += u'</%s>' % tag_name
+    return text
+
+
+class Format_Attributes_XML(object):
+    def __init__(self, attributes=[], content=''):
+        self.attribute_names = attributes
+        self.content_attribute = content
+
+    def formatAttr(self, parser, flowable, attr_name):
+        words = [word for word in attr_name.split('_') if word]
+        if words:
+            # first word starts with lower case
+            words[0] = words[0][:1].lower() + words[0][1:]
+        # other words start with upper case
+        words[1:] = [word[:1].upper() + word[1:] for word in words[1:]]
+        pretty_name = ''.join(words)
+
+        return u'%s="%s"' % (
+            pretty_name,
+            cgi.escape(str(getattr(flowable, attr_name, None))))
+
+    def formatContents(self, parser, flowable):
+        contents = u''
+        if self.content_attribute:
+            contents = getattr(
+                flowable, self.content_attribute, '')
+        return unicode(cgi.escape(contents))
+
+    def __call__(self, parser, flowable):
+        tag_name = format_classname_text(parser, flowable)
+        text = u'<%s' % tag_name
+        for attr_name in self.attribute_names:
+            text += u' %s' % self.formatAttr(parser, flowable, attr_name)
+
+        contents = self.formatContents(parser, flowable)
+        if contents:
+            text += u'>%s</%s>' % (contents, tag_name)
+        else:
+            text += u' />'
+
+        return text
+
+
+class Format_Paragraph_XML(Format_Attributes_XML):
+    def __init__(self, attributes=[]):
+        Format_Attributes_XML.__init__(self, attributes=attributes)
+
+    def formatContents(self, parser, flowable):
+        return unicode(cgi.escape(flowable.getPlainText()))
+
+
+class Format_ParaAndImage_XML(Format_Attributes_XML):
+
+    def __init__(self):
+        Format_Attributes_XML.__init__(self, ['xpad', 'ypad'])
+
+    def formatContents(self, parser, flowable):
+        text = parser([flowable.I, flowable.P])
+        return text and '\n%s\n' % text or ''
+
+
+_xml_formatters = {
+    # system
+    type(None): null_formatter,
+    list: format_flowable_list,
+
+    # plain text
+    str: format_str_xml,
+    unicode: format_str_xml,
+
+    # paragraph text
+    platypus.paragraph.Paragraph: Format_Paragraph_XML(),
+    platypus.xpreformatted.XPreformatted: Format_Paragraph_XML(
+        attributes=['bulletText']),
+    platypus.xpreformatted.PythonPreformatted: Format_Paragraph_XML(
+        attributes=['bulletText']),
+    platypus.flowables.Preformatted: format_preformatted_xml,
+
+    # graphics
+    platypus.flowables.Image:
+        Format_Attributes_XML(['filename', '_width', '_height']),
+    platypus.flowables.HRFlowable:
+        Format_Attributes_XML(
+            ['width', 'lineWidth', 'spaceBefore', 'spaceAfter',
+             'hAlign', 'vAlign']),
+
+    # containers
+    platypus.tables.Table: format_table_xml,
+    platypus.tables.LongTable: format_table_xml,
+    platypus.flowables.ParagraphAndImage: Format_ParaAndImage_XML(),
+    #platypus.flowables.ImageAndFlowables
+    #platypus.flowables.PTOContainer, # (Please Turn Over The Page behaviour)
+
+    # spacing
+    platypus.flowables.KeepInFrame: format_container_xml,
+    platypus.flowables.KeepTogether: format_container_xml,
+    platypus.flowables.PageBreak: format_classname_xml,
+    platypus.flowables.SlowPageBreak: format_classname_xml,
+    platypus.flowables.CondPageBreak: Format_Attributes_XML(['height']),
+    platypus.flowables.Spacer: Format_Attributes_XML(
+        ['width', 'height']),
+
+    # other
+    platypus.flowables.AnchorFlowable: Format_Attributes_XML(['_name']),
+    #platypus.tableofcontents.TableOfContents,
+    #platypus.tableofcontents.SimpleIndex,
+
+    # omit from output
+    platypus.flowables.UseUpSpace: null_formatter,
+    platypus.flowables.Flowable: null_formatter,
+    platypus.flowables.TraceInfo: null_formatter,
+    platypus.flowables.Macro: null_formatter,
+    platypus.flowables.CallerMacro: null_formatter,
+    platypus.flowables.FailOnWrap: null_formatter,
+    platypus.flowables.FailOnDraw: null_formatter,
+}
+
 
=== added directory 'src/schooltool/testing/tests'
=== removed file 'src/schooltool/testing/tests.py'
--- src/schooltool/testing/tests.py	2005-10-01 10:25:55 +0000
+++ src/schooltool/testing/tests.py	1970-01-01 00:00:00 +0000
@@ -1,36 +0,0 @@
-#
-# SchoolTool - common information systems platform for school administration
-# Copyright (c) 2005 Shuttleworth Foundation
-#
-# This program is free software; you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation; either version 2 of the License, or
-# (at your option) any later version.
-#
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with this program; if not, write to the Free Software
-# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
-#
-"""
-Testing the package.
-
-$Id$
-"""
-
-import unittest
-from zope.testing import doctest
-
-
-def test_suite():
-    return unittest.TestSuite((
-        doctest.DocFileSuite('README.txt',
-                             optionflags=doctest.NORMALIZE_WHITESPACE),
-        ))
-
-if __name__ == '__main__':
-    unittest.main(default='test_suite')
 
=== added file 'src/schooltool/testing/tests/__init__.py'
--- src/schooltool/testing/tests/__init__.py	1970-01-01 00:00:00 +0000
+++ src/schooltool/testing/tests/__init__.py	2009-03-30 11:49:24 +0000
@@ -0,0 +1,36 @@
+#
+# SchoolTool - common information systems platform for school administration
+# Copyright (c) 2005 Shuttleworth Foundation
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+#
+"""
+Testing the package.
+
+$Id$
+"""
+
+import unittest
+from zope.testing import doctest
+
+
+def test_suite():
+    return unittest.TestSuite((
+        doctest.DocFileSuite('../README.txt',
+                             optionflags=doctest.NORMALIZE_WHITESPACE),
+        ))
+
+if __name__ == '__main__':
+    unittest.main(default='test_suite')
 
=== added file 'src/schooltool/testing/tests/test_pdf.py'
--- src/schooltool/testing/tests/test_pdf.py	1970-01-01 00:00:00 +0000
+++ src/schooltool/testing/tests/test_pdf.py	2009-03-30 12:24:08 +0000
@@ -0,0 +1,203 @@
+#
+# SchoolTool - common information systems platform for school administration
+# Copyright (c) 2005 Shuttleworth Foundation
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+#
+"""
+Tests for pdf testing helpers.
+
+$Id$
+"""
+
+import unittest
+from zope.testing import doctest
+
+from reportlab.lib.styles import ParagraphStyle
+from reportlab.lib import units
+from reportlab import platypus
+
+
+def buildTestStory():
+    para_style = ParagraphStyle(name='Test', fontName='Times-Roman')
+
+    flowables = []
+    flowables.append('Some\ntext')
+
+    flowables.append(
+        platypus.flowables.KeepInFrame(
+            units.inch*2, units.inch, content=[
+                platypus.paragraph.Paragraph('Single line', para_style),
+                u'unicode text']))
+    flowables.append(
+        platypus.xpreformatted.PythonPreformatted('print "foo"',
+                                                  para_style, bulletText='*'))
+    flowables.append(
+        platypus.flowables.KeepTogether([
+            platypus.paragraph.Paragraph(
+                'Multi &amp;\n<b>Line</b>', para_style),
+            platypus.xpreformatted.XPreformatted(
+                'Text', para_style, bulletText='*'),
+            ],
+            maxHeight=units.inch))
+
+    flowables.extend([
+        platypus.flowables.HRFlowable(),
+        platypus.flowables.Image('logo.png', height=units.inch),
+        platypus.flowables.ParagraphAndImage(
+            platypus.paragraph.Paragraph('Text', para_style),
+            platypus.flowables.Image('file.png'),
+            xpad=units.inch),
+        ])
+
+    flowables.extend([
+        platypus.flowables.PageBreak(),
+        platypus.flowables.SlowPageBreak(),
+        platypus.flowables.CondPageBreak(height=units.inch*2),
+        platypus.flowables.Spacer(units.inch*3, units.inch),
+        ])
+
+    flowables.append(platypus.flowables.AnchorFlowable('My anchor'))
+
+    # also add some uninteresting flowables
+    flowables.append(platypus.flowables.UseUpSpace())
+    flowables.append(platypus.flowables.Macro('print "foo"'))
+
+    return flowables
+
+
+def buildTableFlowable():
+    para_style = ParagraphStyle(name='Test', fontName='Times-Roman')
+
+    data = [
+        ['text',
+         platypus.paragraph.Paragraph('Text', para_style)],
+        [['several', 'items in a cell'],
+         platypus.flowables.Image('file.png')],
+    ]
+    return platypus.tables.Table(data)
+
+
+def buildNestedTables():
+    data = [
+        ['A table with another table inside!'],
+        [buildTableFlowable()]]
+    return platypus.tables.LongTable(data)
+
+
+def doctest_XML_building():
+    r"""Tests for getStoryXML and printStoryXML.
+
+        >>> story = buildTestStory()
+
+    getStoryXML builds an XML element tree with some some basic flowable
+    parameters.
+
+        >>> from schooltool.testing.pdf import getStoryXML
+        >>> doc = getStoryXML(story)
+
+        >>> doc
+        <...ElementTree object ...>
+
+    printStoryXML builds and prints the XML tree.
+
+        >>> from schooltool.testing.pdf import printStoryXML
+        >>> printStoryXML(story)
+        <story>
+          Some
+          text
+          <KeepInFrame>
+            <Paragraph>Single line</Paragraph>
+            unicode text
+          </KeepInFrame>
+          <PythonPreformatted bulletText="*">print "foo"</PythonPreformatted>
+          <KeepTogether>
+            <Paragraph>Multi &amp; Line</Paragraph>
+            <XPreformatted bulletText="*">Text</XPreformatted>
+          </KeepTogether>
+          <HRFlowable width="80%" lineWidth="1"
+                      spaceBefore="1" spaceAfter="1"
+                      hAlign="CENTER" vAlign="BOTTOM"/>
+          <Image filename="logo.png" width="None" height="72.0"/>
+          <ParagraphAndImage xpad="72.0" ypad="3">
+            <Image filename="file.png" width="None" height="None"/>
+            <Paragraph>Text</Paragraph>
+          </ParagraphAndImage>
+          <PageBreak/>
+          <SlowPageBreak/>
+          <CondPageBreak height="144.0"/>
+          <Spacer width="216.0" height="72.0"/>
+          <AnchorFlowable name="My anchor"/>
+        </story>
+
+    Test printing of tables.
+
+        >>> printStoryXML(buildNestedTables())
+        <story>
+          <LongTable>
+          <tr>
+            <td>A table with another table inside!</td>
+          </tr>
+          <tr>
+            <td><Table>
+              <tr>
+                <td>text</td>
+                <td><Paragraph>Text</Paragraph></td>
+              </tr>
+              <tr>
+                <td>several
+                    items in a cell</td>
+                <td><Image filename="file.png" width="None" height="None"/></td>
+              </tr>
+            </Table></td>
+            </tr>
+          </LongTable>
+        </story>
+
+    """
+
+
+def doctest_XML_query_helpers():
+    r"""Tests for queryStory and printQuery.
+
+        >>> story = buildTestStory()
+
+    queryStory builds the XML and performs xpath query on it.
+
+        >>> from schooltool.testing.pdf import queryStory
+        >>> queryStory('//Image', story)
+        ['<Image filename="logo.png" width="None" height="72.0"/>',
+         '<Image filename="file.png" width="None" height="None"/>']
+
+    printQuery is a helper which also prints the results:
+
+        >>> from schooltool.testing.pdf import printQuery
+        >>> printQuery('//Image', story)
+        <Image filename="logo.png" width="None" height="72.0"/>
+        <Image filename="file.png" width="None" height="None"/>
+
+    """
+
+
+def test_suite():
+    optionflags = (doctest.NORMALIZE_WHITESPACE |
+                   doctest.ELLIPSIS |
+                   doctest.REPORT_NDIFF)
+    return unittest.TestSuite((
+        doctest.DocTestSuite(optionflags=optionflags),
+        ))
+
+if __name__ == '__main__':
+    unittest.main(default='test_suite')
 
=== added file 'src/schooltool/testing/tests/test_readme.py'
--- src/schooltool/testing/tests/test_readme.py	1970-01-01 00:00:00 +0000
+++ src/schooltool/testing/tests/test_readme.py	2009-03-30 12:24:08 +0000
@@ -0,0 +1,39 @@
+#
+# SchoolTool - common information systems platform for school administration
+# Copyright (c) 2005 Shuttleworth Foundation
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+#
+"""
+Test suite for README-style tests.
+
+$Id$
+"""
+
+import unittest
+from zope.testing import doctest
+
+
+def test_suite():
+    optionflags = (doctest.NORMALIZE_WHITESPACE |
+                   doctest.ELLIPSIS |
+                   doctest.REPORT_NDIFF)
+    return unittest.TestSuite((
+        doctest.DocFileSuite('../README.txt',
+                             optionflags=optionflags),
+        ))
+
+if __name__ == '__main__':
+    unittest.main(default='test_suite')