From 05f7f938168f9b3195c9b101f4b98f298ab2e981 Mon Sep 17 00:00:00 2001 From: Santhosh Thottingal Date: Sun, 19 Jul 2009 18:22:04 +0530 Subject: Templating Library --- silpa/common/PyMeld.py | 1130 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1130 insertions(+) create mode 100644 silpa/common/PyMeld.py diff --git a/silpa/common/PyMeld.py b/silpa/common/PyMeld.py new file mode 100644 index 0000000..d5acf21 --- /dev/null +++ b/silpa/common/PyMeld.py @@ -0,0 +1,1130 @@ +#!/usr/bin/env python + +# +# PyMeld is released under the terms of the MIT License: +# +# Copyright (c) 2002-2009 Entrian Solutions Ltd. +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in +# all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +# THE SOFTWARE. +# + +r"""A simple, lightweight system for manipulating HTML (and XML, informally) +using a Pythonic object model. `PyMeld` is a single Python module, +_PyMeld.py_. This beta version requires Python 2.2 or above, but the +final production version may work with previous releases of Python (with +slightly limited features) if there's sufficient demand. + +*Features:* + + o Allows program logic and HTML to be completely separated - a graphical + designer can design the HTML in a visual HTML editor, without needing to + deal with any non-standard syntax or non-standard attribute names. The + program code knows nothing about XML or HTML - it just deals with objects + and attributes like any other piece of Python code. + + o Designed with common HTML-application programming tasks in mind. + Populating an HTML form with a record from a database is a one-liner + (using the `%` operator - see below). Building an HTML table from a set + of records is just as easy, as shown in the example below. + + o No special requirements for the HTML/XML (or just one: attribute values + must be quoted) - so you can use any editor, and your HTML/XML doesn't + need to be strictly valid. + + o Works by string substitution, rather than by decomposing and rebuilding the + markup, hence has no impact on the parts of the page you don't manipulate. + + o Does nothing but manipulating HTML/XML, hence fits in with any other Web + toolkits you're using. + + o Tracebacks always point to the right place - many Python/HTML mixing + systems use exec or eval, making bugs hard to track down. + + +*Quick overview* + +A `PyMeld.Meld` object represents an XML document, or a piece of one. +All the elements in a document with `id=name` attributes are made available +by a Meld object as `object.name`. The attributes of elements are available +in the same way. A brief example is worth a thousand words: + +>>> from PyMeld import Meld +>>> xhtml = ''' +... +... ''' +>>> page = Meld(xhtml) # Create a Meld object from XHTML. +>>> print page.message # Access an element within the document. + +>>> print page.message.rows # Access an attribute of an element. +2 +>>> page.message = "New message." # Change the content of an element. +>>> page.message.rows = 4 # Change an attribute value. +>>> del page.message.wrap # Delete an attribute. +>>> print page # Print the resulting page. + + + + +So the program logic and the HTML are completely separated - a graphical +designer can design the HTML in a visual XHTML editor, without needing to +deal with any non-standard syntax or non-standard attribute names. The +program code knows nothing about XML or HTML - it just deals with objects and +attributes like any other piece of Python code. Populating an HTML form with +a record from a database is a one-liner (using the `%` operator - see below). +Building an HTML table from a set of records is just as easy, as shown in the +example below: + + +*Real-world example:* + +Here's a data-driven example populating a table from a data source, basing the +table on sample data put in by the page designer. Note that in the real world +the HTML would normally be a larger page read from an external file, keeping +the data and presentation separate, and the data would come from an external +source like an RDBMS. The HTML could be full of styles, images, anything you +like and it would all work just the same. + +>>> xhtml = ''' +... +... +...

Name	Age
Example name	21

''' +>>> doc = Meld(xhtml) +>>> templateRow = doc.row.clone() # Take a copy of the template row, then +>>> del doc.row # delete it to make way for the real rows. +>>> for name, age in [("Richie", 30), ("Dave", 39), ("John", 78)]: +... newRow = templateRow.clone() +... newRow.name = name +... newRow.age = age +... doc.people += newRow +>>> print re.sub(r'\s*', '\n', str(doc)) # Prettify the output + + + + + +

Name	Age
Richie	30
Dave	39
John	78

Frances

+ ... + ... + ...

Name	Age
Example	21

''' + >>> doc = Meld(xhtml) + >>> rowFormat = doc.row.toFormatString() + >>> rows = [] + >>> for name, age in [("Richie", 30), ("Dave", 39), ("John", 78)]: + ... rows.append(rowFormat % (name, age)) + >>> doc.people = '\n' + doc.header + ''.join(rows) + >>> print re.sub(r'\s*', '\n', str(doc)) # Prettify + + + + + +
Name Age
Richie 30
Dave 39
John 78
+ + So the inner loop no longer contains any PyMeld calls at all - it only + manipulates strings and lists. Here's what `doc.row.toFormatString()` + actually returns - note that this is a string, not a PyMeld object: + + >>> print doc.row.toFormatString() + %s%s + + You can ask for a format string that expects a dictionary rather than + a tuple using the `useDict` parameter: + + >>> print doc.row.toFormatString(useDict=True) + %(name)s%(age)s + + If your markup contains `%` symbols, they are correctly quoted in the + resulting format string: + + >>> doc = Meld("
10% gin.
") + >>> print doc.toFormatString() +
10%% %s.
+ >>> print doc.toFormatString() % 'vodka' +
10% vodka.
+ """ + + # Build a dictionary mapping from all the possible keys to special + # marker values. It doesn't matter if there's some text with `id='x'` + # in there, because it will just be ignored. + self._updatePositions() + content = self._markup.s[self._openEnd:self._closeStart] + quotesAndKeys = re.findall(r'\bid=(["\'])([^"\']+)\1', content) + keysToMarkers = {} + for unusedQuote, key in quotesAndKeys: + if self._dashes: + key = string.replace(key, '-', '_') + keysToMarkers[key] = ":PyMeldMarker'%s':" % key + + # Now use the PyMeld `%` operator to populate the tags. + format = str(self % keysToMarkers) + + # Convert the resulting marked-up string to a format string, by + # quoting all the % characters then inserting %s directives. + format = string.replace(format, '%', '%%') + if useDict: + return re.sub(r":PyMeldMarker'([^']+)':", r'%(\1)s', format) + else: + return re.sub(r":PyMeldMarker'[^']+':", r'%s', format) + + def clone(self, readonly=0, replaceUnderscoreWithDash=False): + """Creates a clone of a `Meld`, for instance to change an attribute + without affecting the original document: + + >>> p = Meld('
Hello World
') + >>> q = p.clone() + >>> q.who = "Richie" + >>> print q.who + Richie + >>> print p.who + World + """ + + self._updatePositions() + markup = self._markup.s[self._openStart:self._closeEnd] + return Meld(markup, readonly, replaceUnderscoreWithDash) + + def __add__(self, other): + """`object1 + object2` turns both objects into strings and returns the + concatenation of the strings: + + >>> a = Meld('1') + >>> b = Meld('2') + >>> c = Meld('3') + >>> print a + b + 12 + >>> print a.x + b.y + c.z + 123 + """ + + if isinstance(other, Meld): + other._updatePositions() + other = other._markup.s[other._openStart:other._closeEnd] + self._updatePositions() + return self._markup.s[self._openStart:self._closeEnd] + other + + def __radd__(self, other): + """See `__add__`""" + # The case where `other` is a Meld can never happen, because + # __add__ will be called instead. + self._updatePositions() + return other + self._markup.s[self._openStart:self._closeEnd] + + def __iadd__(self, other): + """`object1 += object2` appends a string or a clone of a Meld to + the end of another Meld's content. This is used to build things + like HTML tables, which are collections of other objects (eg. table + rows). See *Real-world example* in the main documentation.""" + + if self._readonly: + raise ReadOnlyError, READ_ONLY_MESSAGE + if isinstance(other, Meld): + other._updatePositions() + other = other._markup.s[other._openStart:other._closeEnd] + self._updatePositions() + self._markup.s = self._markup.s[:self._closeStart] + \ + other + \ + self._markup.s[self._closeStart:] + return self + + def __str__(self): + """Returns the XML that this `Meld` represents. Don't call + this directly - instead convert a `Meld` to a string using + `str(object)`. `print` does this automatically, which is why + none of the examples calls `str`.""" + + self._updatePositions() + if self._name is None: + return str(self._markup.s) + else: + return str(self._markup.s[self._openStart:self._closeEnd]) + + def __unicode__(self): + """Returns the XML that this `Meld` represents. Don't call + this directly - instead convert a `Meld` to unicode using + `unicode(object)`. `print` does this automatically, which is why + none of the examples calls `str`. Note that PyMeld's ability to + handle Unicode is largely untested.""" + + self._updatePositions() + return unicode(self._markup.s[self._openStart:self._closeEnd]) + + +# +# Extra tests, for features that aren't tested by the (visible) docstrings: +# +__test__ = { +'entities and charrefs': """ +>>> page = Meld('''• This "and that"... +... x''') +>>> print page.s.title +"Quoted" & Not +>>> page.s.title = page.s.title # Accept liberally, produce strictly. +>>> print page +• This "and that"... +x +>>> page.s.title = page.s.title + " <>" +>>> print page.s.title +"Quoted" & Not <> +>>> print page.s +x +""", + +'assigning to _content': """ +>>> page = Meld('''Old''') +>>> page.s._content = "New" +>>> print page +New +>>> page._content = "All new" +>>> print page +All new +""", + +'deleting _content': """ +>>> page = Meld('''Old''') +>>> del page.s._content +>>> print page + +""", + +'constructing from an unknown type': """ +>>> page = Meld(1) +Traceback (most recent call last): +... +TypeError: Melds must be constructed from strings +""", + +'accessing a non-existent attribute': """ +>>> page = Meld('') +>>> print page.spam +Traceback (most recent call last): +... +AttributeError: No element or attribute named 'spam' +>>> del page.spam +Traceback (most recent call last): +... +AttributeError: No element or attribute named 'spam' +>>> print page.body.spam # For non-container Melds +Traceback (most recent call last): +... +AttributeError: No element or attribute named 'spam' +>>> del page.body.spam # For non-container Melds +Traceback (most recent call last): +... +AttributeError: No element or attribute named 'spam' +""", + +'add new things':""" +>>> page = Meld('''''') +>>> page.empty = "Not any more" +>>> page.empty.cols = 60 +>>> print page +Not any more +""", + +'readonly': """ +>>> page = Meld('''No!''', readonly=True) +>>> page.no = "Yes?" +Traceback (most recent call last): +... +ReadOnlyError: You can't modify this read-only Meld object + +>>> page.no.attribute = "Yes?" +Traceback (most recent call last): +... +ReadOnlyError: You can't modify this read-only Meld object + +>>> page.no += "More?" +Traceback (most recent call last): +... +ReadOnlyError: You can't modify this read-only Meld object + +>>> del page.no +Traceback (most recent call last): +... +ReadOnlyError: You can't modify this read-only Meld object +""", + +'copy from one to another': """ +>>> a = Meld('One') +>>> b = Meld('Two') +>>> a.one = b.two +>>> print a +Two +>>> b.two = "New" +>>> print a # Checking for side-effects +Two +""", + +'mixed-type add, radd and iadd': """ +>>> a = Meld('1') +>>> print a.one + "x" +1x +>>> print "x" + a.one +x1 +>>> a.one += "y" +>>> print a +1y +""", + +'access top-level element': """ +>>> d = Meld("spam") +>>> print d.x +spam +""", + +'access nested element with same name': """ +>>> d = Meld("spam") +>>> print d.x.x +spam +>>> d = Meld("spam") +>>> print d.x.x +spam +""", + +# This is just a smoke-test; proper Unicode support is untested, though +# the code does attempt to be unicode-friendly. +'unicode': r""" +>>> u = Meld(u'One') +>>> a = Meld('Two') +>>> u.one = a.two +>>> print repr(unicode(u)) +u'Two' +>>> a.two = Meld(u'') +>>> print a + +""", + +'private attributes': """ +>>> page = Meld('x') +>>> page._private = "Spam" +>>> print repr(page._private) +'Spam' +>>> print page +x +>>> del page._private +>>> print repr(page._private) +Traceback (most recent call last): +... +AttributeError: _private +>>> del page._private +Traceback (most recent call last): +... +AttributeError: _private +>>> print page +x +""", + +'no markup': """ +>>> page = Meld("Hello world") +>>> print page.spam +Traceback (most recent call last): +... +ValueError: This isn't any form of markup I recognize +""", + +'nesting': """ +>>> page = Meld(''' +... Hello +... World +... and friends +... ! +... Goodbye +... +... ''') +>>> print page.all +Hello + World + and friends + ! + Goodbye + +>>> print page.extra +and friends +""", + +'re-bug': """ +>>> page = Meld("") +>>> print page.x # Was "" + +""", + +'underscores': """ +>>> html = '
xxx
' +>>> meld = Meld(html, replaceUnderscoreWithDash=True) +>>> print meld % {'header_box': 'Mod'} +
Mod
+>>> print meld.toFormatString(useDict=True) +
%(header_box)s
+>>> meld.header_box = 'yyy' +>>> meld.header_box.dash_attr = '___' +>>> print meld +
yyy
+""", + +'doctype': """ +>>> html = '\\nz' +>>> meld = Meld(html) +>>> meld.a = 'a' +>>> meld.y = 'b' +>>> print meld +\nb +""", + +'eichin-bug': """ +>>> page = Meld(''' +...
label Running
''') +>>> print page.Instance_1_4 +Running +""", +} + + +# Entrian.Coverage: Pragma Stop + +def test(): + """Tests the `PyMeld` module, performing code coverage analysis if + `Entrian.Coverage` is available. Returns `(failed, total)`, a la + `doctest.testmod`.""" + + import doctest + try: + from Entrian import Coverage + Coverage.start('PyMeld') + except ImportError: + Coverage = False + + ## # Profiling. + ## import PyMeld + ## import profile, pstats + ## profile.run("import doctest, PyMeld; result = doctest.testmod(PyMeld)", "rjh") + ## s = pstats.Stats("rjh") + ## s.sort_stats('cumulative').print_stats() + + ## # Cheap benchmark, for comparing new versions with old. + ## import PyMeld + ## for i in range(100): + ## reload(doctest) + ## result = doctest.testmod(PyMeld) + + import PyMeld + result = doctest.testmod(PyMeld) + + if Coverage: + analysis = Coverage.getAnalysis() + analysis.printAnalysis() + return result + +if __name__ == '__main__': + failed, total = test() + if failed == 0: # Else `doctest.testmod` prints the failures. + print "All %d tests passed." % total -- cgit