markup.py 20 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529
  1. # This code is in the public domain, it comes
  2. # with absolutely no warranty and you can do
  3. # absolutely whatever you want with it.
  4. __date__ = '16 March 2015'
  5. __version__ = '1.10'
  6. __doc__= """
  7. This is markup.py - a Python module that attempts to
  8. make it easier to generate HTML/XML from a Python program
  9. in an intuitive, lightweight, customizable and pythonic way.
  10. It works with both python 2 and 3.
  11. The code is in the public domain.
  12. Version: %s as of %s.
  13. Documentation and further info is at http://markup.sourceforge.net/
  14. Please send bug reports, feature requests, enhancement
  15. ideas or questions to nogradi at gmail dot com.
  16. Installation: drop markup.py somewhere into your Python path.
  17. """ % ( __version__, __date__ )
  18. try:
  19. basestring
  20. import string
  21. except:
  22. # python 3
  23. basestring = str
  24. string = str
  25. long = int
  26. # tags which are reserved python keywords will be referred
  27. # to by a leading underscore otherwise we end up with a syntax error
  28. import keyword
  29. class element:
  30. """This class handles the addition of a new element."""
  31. def __init__( self, tag, case='lower', parent=None ):
  32. self.parent = parent
  33. if case == 'upper':
  34. self.tag = tag.upper( )
  35. elif case == 'lower':
  36. self.tag = tag.lower( )
  37. elif case =='given':
  38. self.tag = tag
  39. else:
  40. self.tag = tag
  41. def __call__( self, *args, **kwargs ):
  42. if len( args ) > 1:
  43. raise ArgumentError( self.tag )
  44. # if class_ was defined in parent it should be added to every element
  45. if self.parent is not None and self.parent.class_ is not None:
  46. if 'class_' not in kwargs:
  47. kwargs['class_'] = self.parent.class_
  48. if self.parent is None and len( args ) == 1:
  49. x = [ self.render( self.tag, False, myarg, mydict ) for myarg, mydict in _argsdicts( args, kwargs ) ]
  50. return '\n'.join( x )
  51. elif self.parent is None and len( args ) == 0:
  52. x = [ self.render( self.tag, True, myarg, mydict ) for myarg, mydict in _argsdicts( args, kwargs ) ]
  53. return '\n'.join( x )
  54. if self.tag in self.parent.twotags:
  55. for myarg, mydict in _argsdicts( args, kwargs ):
  56. self.render( self.tag, False, myarg, mydict )
  57. elif self.tag in self.parent.onetags:
  58. if len( args ) == 0:
  59. for myarg, mydict in _argsdicts( args, kwargs ):
  60. self.render( self.tag, True, myarg, mydict ) # here myarg is always None, because len( args ) = 0
  61. else:
  62. raise ClosingError( self.tag )
  63. elif self.parent.mode == 'strict_html' and self.tag in self.parent.deptags:
  64. raise DeprecationError( self.tag )
  65. else:
  66. raise InvalidElementError( self.tag, self.parent.mode )
  67. def render( self, tag, single, between, kwargs ):
  68. """Append the actual tags to content."""
  69. out = "<%s" % tag
  70. for key, value in list( kwargs.items( ) ):
  71. if value is not None: # when value is None that means stuff like <... checked>
  72. key = key.strip('_') # strip this so class_ will mean class, etc.
  73. if key == 'http_equiv': # special cases, maybe change _ to - overall?
  74. key = 'http-equiv'
  75. elif key == 'accept_charset':
  76. key = 'accept-charset'
  77. out = "%s %s=\"%s\"" % ( out, key, escape( value ) )
  78. else:
  79. out = "%s %s" % ( out, key )
  80. if between is not None:
  81. out = "%s>%s</%s>" % ( out, between, tag )
  82. else:
  83. if single:
  84. out = "%s />" % out
  85. else:
  86. out = "%s>" % out
  87. if self.parent is not None:
  88. self.parent.content.append( out )
  89. else:
  90. return out
  91. def close( self ):
  92. """Append a closing tag unless element has only opening tag."""
  93. if self.tag in self.parent.twotags:
  94. self.parent.content.append( "</%s>" % self.tag )
  95. elif self.tag in self.parent.onetags:
  96. raise ClosingError( self.tag )
  97. elif self.parent.mode == 'strict_html' and self.tag in self.parent.deptags:
  98. raise DeprecationError( self.tag )
  99. def open( self, **kwargs ):
  100. """Append an opening tag."""
  101. if self.tag in self.parent.twotags or self.tag in self.parent.onetags:
  102. self.render( self.tag, False, None, kwargs )
  103. elif self.mode == 'strict_html' and self.tag in self.parent.deptags:
  104. raise DeprecationError( self.tag )
  105. class page:
  106. """This is our main class representing a document. Elements are added
  107. as attributes of an instance of this class."""
  108. def __init__( self, mode='strict_html', case='lower', onetags=None, twotags=None, separator='\n', class_=None ):
  109. """Stuff that effects the whole document.
  110. mode -- 'strict_html' for HTML 4.01 (default)
  111. 'html' alias for 'strict_html'
  112. 'loose_html' to allow some deprecated elements
  113. 'xml' to allow arbitrary elements
  114. case -- 'lower' element names will be printed in lower case (default)
  115. 'upper' they will be printed in upper case
  116. 'given' element names will be printed as they are given
  117. onetags -- list or tuple of valid elements with opening tags only
  118. twotags -- list or tuple of valid elements with both opening and closing tags
  119. these two keyword arguments may be used to select
  120. the set of valid elements in 'xml' mode
  121. invalid elements will raise appropriate exceptions
  122. separator -- string to place between added elements, defaults to newline
  123. class_ -- a class that will be added to every element if defined"""
  124. valid_onetags = [ "AREA", "BASE", "BR", "COL", "FRAME", "HR", "IMG", "INPUT", "LINK", "META", "PARAM" ]
  125. valid_twotags = [ "A", "ABBR", "ACRONYM", "ADDRESS", "B", "BDO", "BIG", "BLOCKQUOTE", "BODY", "BUTTON",
  126. "CAPTION", "CITE", "CODE", "COLGROUP", "DD", "DEL", "DFN", "DIV", "DL", "DT", "EM", "FIELDSET",
  127. "FORM", "FRAMESET", "H1", "H2", "H3", "H4", "H5", "H6", "HEAD", "HTML", "I", "IFRAME", "INS",
  128. "KBD", "LABEL", "LEGEND", "LI", "MAP", "NOFRAMES", "NOSCRIPT", "OBJECT", "OL", "OPTGROUP",
  129. "OPTION", "P", "PRE", "Q", "SAMP", "SCRIPT", "SELECT", "SMALL", "SPAN", "STRONG", "STYLE",
  130. "SUB", "SUP", "TABLE", "TBODY", "TD", "TEXTAREA", "TFOOT", "TH", "THEAD", "TITLE", "TR",
  131. "TT", "UL", "VAR" ]
  132. deprecated_onetags = [ "BASEFONT", "ISINDEX" ]
  133. deprecated_twotags = [ "APPLET", "CENTER", "DIR", "FONT", "MENU", "S", "STRIKE", "U" ]
  134. self.header = [ ]
  135. self.content = [ ]
  136. self.footer = [ ]
  137. self.case = case
  138. self.separator = separator
  139. # init( ) sets it to True so we know that </body></html> has to be printed at the end
  140. self._full = False
  141. self.class_= class_
  142. if mode == 'strict_html' or mode == 'html':
  143. self.onetags = valid_onetags
  144. self.onetags += list( map( string.lower, self.onetags ) )
  145. self.twotags = valid_twotags
  146. self.twotags += list( map( string.lower, self.twotags ) )
  147. self.deptags = deprecated_onetags + deprecated_twotags
  148. self.deptags += list( map( string.lower, self.deptags ) )
  149. self.mode = 'strict_html'
  150. elif mode == 'loose_html':
  151. self.onetags = valid_onetags + deprecated_onetags
  152. self.onetags += list( map( string.lower, self.onetags ) )
  153. self.twotags = valid_twotags + deprecated_twotags
  154. self.twotags += list( map( string.lower, self.twotags ) )
  155. self.mode = mode
  156. elif mode == 'xml':
  157. if onetags and twotags:
  158. self.onetags = onetags
  159. self.twotags = twotags
  160. elif ( onetags and not twotags ) or ( twotags and not onetags ):
  161. raise CustomizationError( )
  162. else:
  163. self.onetags = russell( )
  164. self.twotags = russell( )
  165. self.mode = mode
  166. else:
  167. raise ModeError( mode )
  168. def __getattr__( self, attr ):
  169. # tags should start with double underscore
  170. if attr.startswith("__") and attr.endswith("__"):
  171. raise AttributeError( attr )
  172. # tag with single underscore should be a reserved keyword
  173. if attr.startswith( '_' ):
  174. attr = attr.lstrip( '_' )
  175. if attr not in keyword.kwlist:
  176. raise AttributeError( attr )
  177. return element( attr, case=self.case, parent=self )
  178. def __str__( self ):
  179. if self._full and ( self.mode == 'strict_html' or self.mode == 'loose_html' ):
  180. end = [ '</body>', '</html>' ]
  181. else:
  182. end = [ ]
  183. return self.separator.join( self.header + self.content + self.footer + end )
  184. def __call__( self, escape=False ):
  185. """Return the document as a string.
  186. escape -- False print normally
  187. True replace < and > by &lt; and &gt;
  188. the default escape sequences in most browsers"""
  189. if escape:
  190. return _escape( self.__str__( ) )
  191. else:
  192. return self.__str__( )
  193. def add( self, text ):
  194. """This is an alias to addcontent."""
  195. self.addcontent( text )
  196. def addfooter( self, text ):
  197. """Add some text to the bottom of the document"""
  198. self.footer.append( text )
  199. def addheader( self, text ):
  200. """Add some text to the top of the document"""
  201. self.header.append( text )
  202. def addcontent( self, text ):
  203. """Add some text to the main part of the document"""
  204. self.content.append( text )
  205. def init( self, lang='en', css=None, metainfo=None, title=None, header=None,
  206. footer=None, charset=None, encoding=None, doctype=None, bodyattrs=None, script=None, base=None ):
  207. """This method is used for complete documents with appropriate
  208. doctype, encoding, title, etc information. For an HTML/XML snippet
  209. omit this method.
  210. lang -- language, usually a two character string, will appear
  211. as <html lang='en'> in html mode (ignored in xml mode)
  212. css -- Cascading Style Sheet filename as a string or a list of
  213. strings for multiple css files (ignored in xml mode)
  214. metainfo -- a dictionary in the form { 'name':'content' } to be inserted
  215. into meta element(s) as <meta name='name' content='content'>
  216. (ignored in xml mode)
  217. base -- set the <base href="..."> tag in <head>
  218. bodyattrs --a dictionary in the form { 'key':'value', ... } which will be added
  219. as attributes of the <body> element as <body key='value' ... >
  220. (ignored in xml mode)
  221. script -- dictionary containing src:type pairs, <script type='text/type' src=src></script>
  222. or a list of [ 'src1', 'src2', ... ] in which case 'javascript' is assumed for all
  223. title -- the title of the document as a string to be inserted into
  224. a title element as <title>my title</title> (ignored in xml mode)
  225. header -- some text to be inserted right after the <body> element
  226. (ignored in xml mode)
  227. footer -- some text to be inserted right before the </body> element
  228. (ignored in xml mode)
  229. charset -- a string defining the character set, will be inserted into a
  230. <meta http-equiv='Content-Type' content='text/html; charset=myset'>
  231. element (ignored in xml mode)
  232. encoding -- a string defining the encoding, will be put into to first line of
  233. the document as <?xml version='1.0' encoding='myencoding' ?> in
  234. xml mode (ignored in html mode)
  235. doctype -- the document type string, defaults to
  236. <!DOCTYPE HTML PUBLIC '-//W3C//DTD HTML 4.01 Transitional//EN'>
  237. in html mode (ignored in xml mode)"""
  238. self._full = True
  239. if self.mode == 'strict_html' or self.mode == 'loose_html':
  240. if doctype is None:
  241. doctype = "<!DOCTYPE HTML PUBLIC '-//W3C//DTD HTML 4.01 Transitional//EN'>"
  242. self.header.append( doctype )
  243. self.html( lang=lang )
  244. self.head( )
  245. if charset is not None:
  246. self.meta( http_equiv='Content-Type', content="text/html; charset=%s" % charset )
  247. if metainfo is not None:
  248. self.metainfo( metainfo )
  249. if css is not None:
  250. self.css( css )
  251. if title is not None:
  252. self.title( title )
  253. if script is not None:
  254. self.scripts( script )
  255. if base is not None:
  256. self.base( href='%s' % base )
  257. self.head.close()
  258. if bodyattrs is not None:
  259. self.body( **bodyattrs )
  260. else:
  261. self.body( )
  262. if header is not None:
  263. self.content.append( header )
  264. if footer is not None:
  265. self.footer.append( footer )
  266. elif self.mode == 'xml':
  267. if doctype is None:
  268. if encoding is not None:
  269. doctype = "<?xml version='1.0' encoding='%s' ?>" % encoding
  270. else:
  271. doctype = "<?xml version='1.0' ?>"
  272. self.header.append( doctype )
  273. def css( self, filelist ):
  274. """This convenience function is only useful for html.
  275. It adds css stylesheet(s) to the document via the <link> element."""
  276. if isinstance( filelist, basestring ):
  277. self.link( href=filelist, rel='stylesheet', type='text/css', media='all' )
  278. else:
  279. for file in filelist:
  280. self.link( href=file, rel='stylesheet', type='text/css', media='all' )
  281. def metainfo( self, mydict ):
  282. """This convenience function is only useful for html.
  283. It adds meta information via the <meta> element, the argument is
  284. a dictionary of the form { 'name':'content' }."""
  285. if isinstance( mydict, dict ):
  286. for name, content in list( mydict.items( ) ):
  287. self.meta( name=name, content=content )
  288. else:
  289. raise TypeError( "Metainfo should be called with a dictionary argument of name:content pairs." )
  290. def scripts( self, mydict ):
  291. """Only useful in html, mydict is dictionary of src:type pairs or a list
  292. of script sources [ 'src1', 'src2', ... ] in which case 'javascript' is assumed for type.
  293. Will be rendered as <script type='text/type' src=src></script>"""
  294. if isinstance( mydict, dict ):
  295. for src, type in list( mydict.items( ) ):
  296. self.script( '', src=src, type='text/%s' % type )
  297. else:
  298. try:
  299. for src in mydict:
  300. self.script( '', src=src, type='text/javascript' )
  301. except:
  302. raise TypeError( "Script should be given a dictionary of src:type pairs or a list of javascript src's." )
  303. class _oneliner:
  304. """An instance of oneliner returns a string corresponding to one element.
  305. This class can be used to write 'oneliners' that return a string
  306. immediately so there is no need to instantiate the page class."""
  307. def __init__( self, case='lower' ):
  308. self.case = case
  309. def __getattr__( self, attr ):
  310. # tags should start with double underscore
  311. if attr.startswith("__") and attr.endswith("__"):
  312. raise AttributeError( attr )
  313. # tag with single underscore should be a reserved keyword
  314. if attr.startswith( '_' ):
  315. attr = attr.lstrip( '_' )
  316. if attr not in keyword.kwlist:
  317. raise AttributeError( attr )
  318. return element( attr, case=self.case, parent=None )
  319. oneliner = _oneliner( case='lower' )
  320. upper_oneliner = _oneliner( case='upper' )
  321. given_oneliner = _oneliner( case='given' )
  322. def _argsdicts( args, mydict ):
  323. """A utility generator that pads argument list and dictionary values, will only be called with len( args ) = 0, 1."""
  324. if len( args ) == 0:
  325. args = None,
  326. elif len( args ) == 1:
  327. args = _totuple( args[0] )
  328. else:
  329. raise Exception( "We should have never gotten here." )
  330. mykeys = list( mydict.keys( ) )
  331. myvalues = list( map( _totuple, list( mydict.values( ) ) ) )
  332. maxlength = max( list( map( len, [ args ] + myvalues ) ) )
  333. for i in range( maxlength ):
  334. thisdict = { }
  335. for key, value in zip( mykeys, myvalues ):
  336. try:
  337. thisdict[ key ] = value[i]
  338. except IndexError:
  339. thisdict[ key ] = value[-1]
  340. try:
  341. thisarg = args[i]
  342. except IndexError:
  343. thisarg = args[-1]
  344. yield thisarg, thisdict
  345. def _totuple( x ):
  346. """Utility stuff to convert string, int, long, float, None or anything to a usable tuple."""
  347. if isinstance( x, basestring ):
  348. out = x,
  349. elif isinstance( x, ( int, long, float ) ):
  350. out = str( x ),
  351. elif x is None:
  352. out = None,
  353. else:
  354. out = tuple( x )
  355. return out
  356. def escape( text, newline=False ):
  357. """Escape special html characters."""
  358. if isinstance( text, basestring ):
  359. if '&' in text:
  360. text = text.replace( '&', '&amp;' )
  361. if '>' in text:
  362. text = text.replace( '>', '&gt;' )
  363. if '<' in text:
  364. text = text.replace( '<', '&lt;' )
  365. if '\"' in text:
  366. text = text.replace( '\"', '&quot;' )
  367. if '\'' in text:
  368. text = text.replace( '\'', '&quot;' )
  369. if newline:
  370. if '\n' in text:
  371. text = text.replace( '\n', '<br>' )
  372. return text
  373. _escape = escape
  374. def unescape( text ):
  375. """Inverse of escape."""
  376. if isinstance( text, basestring ):
  377. if '&amp;' in text:
  378. text = text.replace( '&amp;', '&' )
  379. if '&gt;' in text:
  380. text = text.replace( '&gt;', '>' )
  381. if '&lt;' in text:
  382. text = text.replace( '&lt;', '<' )
  383. if '&quot;' in text:
  384. text = text.replace( '&quot;', '\"' )
  385. return text
  386. class dummy:
  387. """A dummy class for attaching attributes."""
  388. pass
  389. doctype = dummy( )
  390. doctype.frameset = """<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN" "http://www.w3.org/TR/html4/frameset.dtd">"""
  391. doctype.strict = """<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">"""
  392. doctype.loose = """<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">"""
  393. class russell:
  394. """A dummy class that contains anything."""
  395. def __contains__( self, item ):
  396. return True
  397. class MarkupError( Exception ):
  398. """All our exceptions subclass this."""
  399. def __str__( self ):
  400. return self.message
  401. class ClosingError( MarkupError ):
  402. def __init__( self, tag ):
  403. self.message = "The element '%s' does not accept non-keyword arguments (has no closing tag)." % tag
  404. class OpeningError( MarkupError ):
  405. def __init__( self, tag ):
  406. self.message = "The element '%s' can not be opened." % tag
  407. class ArgumentError( MarkupError ):
  408. def __init__( self, tag ):
  409. self.message = "The element '%s' was called with more than one non-keyword argument." % tag
  410. class InvalidElementError( MarkupError ):
  411. def __init__( self, tag, mode ):
  412. self.message = "The element '%s' is not valid for your mode '%s'." % ( tag, mode )
  413. class DeprecationError( MarkupError ):
  414. def __init__( self, tag ):
  415. self.message = "The element '%s' is deprecated, instantiate markup.page with mode='loose_html' to allow it." % tag
  416. class ModeError( MarkupError ):
  417. def __init__( self, mode ):
  418. self.message = "Mode '%s' is invalid, possible values: strict_html, html (alias for strict_html), loose_html, xml." % mode
  419. class CustomizationError( MarkupError ):
  420. def __init__( self ):
  421. self.message = "If you customize the allowed elements, you must define both types 'onetags' and 'twotags'."
  422. if __name__ == '__main__':
  423. import sys
  424. sys.stdout.write( __doc__ )