1

"""

     2

    Generating XHTML output

     3

     4

    XXX: use a 'real' XML builder?

     5

"""

     6

     7

from cgi import escape

     8

import itertools as _itertools

     9

    10

class IRenderable (object) :

    11

    """

    12

        Something that's renderable as the contents of a HTML tag

    13

    """

    14

    15

    def render_raw_lines (self, indent=u'\t') :

    16

        """

    17

            Render the indented lines for tag and contents, without newlines

    18

        """

    19

    20

        abstract

    21

    22

    def render_lines (self, indent=u'\t', newline=u'\n') :

    23

        """

    24

            Render full output lines with given newlines

    25

    26

            >>> list(Tag('xx', 'yy').render_lines())

    27

            [u'<xx>\\n', u'\\tyy\\n', u'</xx>\\n']

    28

        """

    29

    31

            yield line + newline

    32

    33

    def render_unicode (self, **render_opts) :

    34

        """

    35

            Render full tag as a single unicode string

    36

    37

            >>> Tag('xx', 'yy').render_unicode()

    38

            u'<xx>\\n\\tyy\\n</xx>\\n'

    39

        """

    40

    41

        return "".join(self.render_lines(**render_opts))

    42

    43

    def render_str (self, encoding='ascii', **render_opts) :

    44

        """

    45

            Render full tag as an encoded string

    46

    47

            >>> Tag('xx', 'yy').render_str()

    48

            '<xx>\\n\\tyy\\n</xx>\\n'

    49

        """

    50

    51

        return self.render_unicode(**render_opts).encode(encoding)

    52

    53

    def render_out (self, stream, encoding=None, **render_opts) :

    54

        """

    55

            Render output into the given stream, encoding using the given encoding if given.

    56

    57

            >>> from StringIO import StringIO; buf = StringIO(); Tag('xx', 'yy').render_out(buf, 'ascii'); buf.getvalue()

    58

            '<xx>\\n\\tyy\\n</xx>\\n'

    59

        """

    60

    61

        for line in self.render_lines(**render_opts) :

    62

            if encoding :

    63

                line = line.encode(encoding)

    64

    65

            stream.write(line)

    66

    67

    def render_file (self, file, encoding=None, **render_opts) :

    68

        """

    69

            Render output to given file, overwriteing anything already there

    70

        """

    71

    73

    74

    # default output

    75

    __str__ = render_str

    76

    __unicode__ = render_unicode

    77

    78

    # default .render method

    79

    render = render_unicode

    80

    81

class Tag (IRenderable) :

    82

    """

    83

        A HTML tag, with attributes and contents, which can a mixture of data and other renderables(tags).

    84

    85

        Provides various kinds of rendering output

    86

    """

    87

    88

    @staticmethod

    89

    def process_contents (contents) :

    90

        """

    91

            Postprocess contents iterable to return new list.

    92

    93

            Items that are None will be omitted from the return value.

    94

    95

            XXX: flatten

    96

    97

            >>> Tag.process_contents([])

    98

            []

    99

            >>> Tag.process_contents([None])

   100

            []

   101

            >>> Tag.process_contents([u'foo'])

   102

            [u'foo']

   103

        """

   104

   105

        return [c for c in contents if c is not None]

   106

   107

    @staticmethod

   108

    def process_attrs (attrs) :

   109

        """

   110

            Postprocess attributes.

   111

   112

            Key-value pairs where the value is None will be ommitted, and any trailing underscores in the key omitted.

   113

   114

            TODO: only remove one underscore

   115

   116

            >>> Tag.process_attrs(dict())

   117

            {}

   118

            >>> Tag.process_attrs(dict(foo='bar'))

   119

            {'foo': 'bar'}

   120

            >>> Tag.process_attrs(dict(class_='bar', frob=None))

   121

            {'class': 'bar'}

   122

        """

   123

   124

        return dict((k.rstrip('_'), v) for k, v in attrs.iteritems() if v is not None)

   125

   126

    def __init__ (self, name, *contents, **attrs) :

   127

        """

   128

            Construct tag with given name/attributes or contents.

   129

   130

            The filtering rules desribed in process_contents/process_attrs apply.

   131

   132

            >>> Tag('foo')

   133

            Tag('foo')

   134

            >>> Tag('foo', 'quux')

   135

            Tag('foo', 'quux')

   136

            >>> Tag('foo', 'quux', bar=5)

   137

            Tag('foo', 'quux', bar=5)

   138

            >>> Tag('foo', class_='ten')

   139

            Tag('foo', class='ten')

   140

        """

   141

   142

        self.name = name

   143

   144

        # store filtered/processed versions

   145

        self.contents = self.process_contents(contents)

   146

        self.attrs = self.process_attrs(attrs)

   147

   148

    def __call__ (self, *contents, **attrs) :

   149

        """

   150

            Return a new Tag with this tag's attributes and contents, as well as the given attributes/contents.

   151

   152

            The filtering rules desribed in process_contents/process_attrs apply.

   153

   154

            >>> Tag('foo')('bar')

   155

            Tag('foo', 'bar')

   156

            >>> Tag('a', href='index.html')("Home")

   157

            Tag('a', 'Home', href='index.html')

   158

            >>> Tag('bar', None)(5, foo=None, class_='bar')

   159

            Tag('bar', 5, class='bar')

   160

            >>> Tag('a')('b')('c')(asdf=5)

   161

            Tag('a', 'b', 'c', asdf=5)

   162

            >>> t1 = Tag('a'); t2 = t1('b'); t1

   163

            Tag('a')

   164

        """

   165

   166

        # merge attrs/contents

   167

        # XXX: new_attrs is not an iterator...

   168

        new_attrs = dict(_itertools.chain(self.attrs.iteritems(), attrs.iteritems()))

   169

        new_contents = _itertools.chain(self.contents, contents)

   170

   171

        # build new tag

   172

        return Tag(self.name, *new_contents, **new_attrs)

   173

   174

    @staticmethod

   175

    def format_attr (name, value) :

   176

        """

   177

            Format a single HTML tag attribute

   178

   179

            >>> Tag.format_attr('name', 'value')

   180

            u'name="value"'

   181

            >>> Tag.format_attr('this', '<a"b>')

   182

            u'this="<a"b>"'

   183

            >>> Tag.format_attr('xx', 1337)

   184

            u'xx="1337"'

   185

        """

   186

   187

        return u'%s="%s"' % (name, escape(unicode(value), True))

   188

   189

    def render_attrs (self) :

   190

        """

   191

            Return the HTML attributes string

   192

   193

            >>> Tag('x', foo=5, bar='<').render_attrs()

   194

            u'foo="5" bar="<"'

   195

        """

   196

   197

        return " ".join(self.format_attr(n, v) for n, v in self.attrs.iteritems())

   198

   199

    def render_contents (self, **render_opts) :

   200

        """

   201

            Render the contents of the tag as a series of indented lines, with given render_lines options for subtags

   202

   203

            >>> list(Tag('x', 5).render_contents())

   204

            [u'5']

   205

            >>> list(Tag('x', 'line1', 'line2').render_contents())

   206

            [u'line1', u'line2']

   207

            >>> list(Tag('x', 'a', Tag('b', 'bb'), 'c').render_contents())

   208

            [u'a', u'<b>', u'\\tbb', u'</b>', u'c']

   209

        """

   210

   211

        for content in self.contents :

   212

            if isinstance(content, IRenderable) :

   213

                # sub-tags

   214

                for line in content.render_raw_lines(**render_opts) :

   215

                    yield line

   216

   217

            else :

   218

                # escape raw values

   219

                yield escape(unicode(content))

   220

   221

    def render_raw_lines (self, indent=u'\t') :

   222

        """

   223

            Render the tag and indented content

   224

   225

            >>> list(Tag('xx', 'yy', zz='foo').render_raw_lines(indent=' '))

   226

            [u'<xx zz="foo">', u' yy', u'</xx>']

   227

        """

   228

   229

        # render attr string, including preceding space

   230

        attrs_stuff = (" " + self.render_attrs()) if self.attrs else ""

   231

   232

        if self.contents :

   233

            # tag with content

   234

            yield u"<%s%s>" % (self.name, attrs_stuff)

   235

   236

            for line in self.render_contents(indent=indent) :

   237

                yield indent + line

   238

   239

            yield u"</%s>" % (self.name, )

   240

   241

        else :

   242

            # singleton tag

   243

            yield u"<%s%s />" % (self.name, attrs_stuff)

   244

   245

   246

    def __repr__ (self) :

   247

        return 'Tag(%s)' % ', '.join(

   248

            [

   249

                repr(self.name)

   250

            ] + [

   251

                repr(c) for c in self.contents

   252

            ] + [

   253

                '%s=%r' % (name, value) for name, value in self.attrs.iteritems()

   254

            ]

   255

        )

   256

   257

class Text (IRenderable) :

   258

    """

   259

        Raw HTML text

   260

    """

   261

   262

    def __init__ (self, line) :

   263

        """

   264

            Initialize to render as the given lines

   265

        """

   266

   267

        self.lines = [line]

   268

   269

    def render_raw_lines (self, indent=u'\t') :

   270

        return self.lines

   271

   272

class XHTMLDocument (IRenderable) :

   273

    """

   274

        <?xml version="..." encoding="..." ?>

   275

        <!DOCTYPE ...>

   276

   277

        <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">

   278

            <head>

   279

                ...

   280

            </head>

   281

            <body>

   282

                ...

   283

            </body>

   284

        </html>

   285

    """

   286

   287

    def __init__ (self, 

   288

        head, body,

   289

        xml_version='1.0', xml_encoding='utf-8', 

   290

        doctype='html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"',

   291

        html_xmlns='http://www.w3.org/1999/xhtml', html_lang='en'

   292

    ) :

   293

        # store

   294

        self.xml_version = xml_version

   295

        self.xml_encoding = xml_encoding

   296

        self.doctype = doctype

   297

   298

        # build the document

   299

        self.document = Tag('html', **{'xmlns': html_xmlns, 'xml:lang': html_lang})(

   300

            Tag('head', head),

   301

            Tag('body', body),

   302

        )

   303

   304

    def render_raw_lines (self, **render_opts) :

   305

        """

   306

            Render the two header lines, and then the document

   307

        """

   308

   309

        yield '<?xml version="%s" encoding="%s" ?>' % (self.xml_version, self.xml_encoding)

   310

        yield '<!DOCTYPE %s>' % (self.doctype)

   311

   312

        for line in self.document.render_raw_lines(**render_opts) :

   313

            yield line

   314

   315

    def _check_encoding (self, encoding) :

   316

        if encoding and encoding != self.xml_encoding :

   317

            raise ValueError("encoding mismatch: %r should be %r" % (encoding, self.xml_encoding))

   318

   319

    def render_str (self, encoding=None, **render_opts) :

   320

        """

   321

            Wrap render_str to verify that the right encoding is used

   322

        """

   323

   324

        self._check_encoding(encoding)

   325

   326

        return super(XHTMLDocument, self).render_str(self.xml_encoding, **render_opts)

   327

   328

    def render_out (self, stream, encoding=None, **render_opts) :

   329

        """

   330

            Wrap render_out to verify that the right encoding is used

   331

        """

   332

   333

        self._check_encoding(encoding)

   334

   335

        return super(XHTMLDocument, self).render_out(stream, self.xml_encoding, **render_opts)

   336

   337

class TagFactory (object) :

   338

    """

   339

        Build Tags with names give as attribute names

   340

    """

   341

   342

    def __getattr__ (self, name) :

   343

        """

   344

            Get a Tag object with the given name, but no contents

   345

   346

            >>> TagFactory().a(href='bar')('quux')

   347

            Tag('a', 'quux', href='bar')

   348

        """

   349

   350

        return Tag(name)

   351

   352

# pretty names

   353

tag = Tag

   354

tags = TagFactory()

   355

raw = Text

   356

   357

# testing

   358

if __name__ == '__main__' :

   359

    import doctest

   360

   361

    doctest.testmod()

   362