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, types as _types

     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

    30

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

    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

    72

        self.render_out(file.open_write(encoding), **render_opts)

    73

    74

    # default output

    75

    __str__ = render_str

    76

    __unicode__ = render_unicode

    77

    78

    # default .render method

    79

    render = render_unicode

    80

    81

class Container (IRenderable) :

    82

    """

    83

        A container holds a sequence of other renderable items.

    84

    """

    85

    86

    @classmethod

    87

    def process_contents (cls, contents) :

    88

        """

    89

            Postprocess contents iterable to return new list.

    90

    91

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

    92

    93

            Certain core sequence types will be recognized and flattened for output: tuples, lists, and generators.

    94

    95

            >>> list(Container.process_contents([]))

    96

            []

    97

            >>> list(Container.process_contents([None]))

    98

            []

    99

            >>> list(Container.process_contents([u'foo']))

   100

            [u'foo']

   101

        """

   102

   103

        for content in contents :

   104

            if content is None :

   105

                continue

   106

   107

            # Hardcoded list of special-case nested contents

   108

            elif isinstance(content, (_types.TupleType, _types.ListType, _types.GeneratorType)) :

   109

                for subcontent in cls.process_contents(content) :

   110

                    yield subcontent

   111

   112

            else :

   113

                # normal, handle as IRenderable/unicode data

   114

                yield content

   115

   116

    def __init__ (self, *contents) :

   117

        """

   118

            Construct this container with the given sub-items

   119

        """

   120

   121

        # store postprocessed

   122

        self.contents = list(self.process_contents(contents))

   123

   124

    def render_raw_lines (self, **render_opts) :

   125

        """

   126

            Render our contents as a series of non-indented lines, with the contents handling indentation themselves.

   127

   128

            >>> list(Container(5).render_raw_lines())

   129

            [u'5']

   130

            >>> list(Container('line1', 'line2').render_raw_lines())

   131

            [u'line1', u'line2']

   132

            >>> list(Container('a', Tag('b', 'bb'), 'c').render_raw_lines())

   133

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

   134

            >>> list(Container(Tag('hr'), Tag('foo')('bar')).render_raw_lines())

   135

            [u'<hr />', u'<foo>', u'\\tbar', u'</foo>']

   136

        """

   137

   138

        for content in self.contents :

   139

            if isinstance(content, IRenderable) :

   140

                # sub-items

   141

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

   142

                    yield line

   143

   144

            else :

   145

                # escape raw values

   146

                yield escape(unicode(content))

   147

   148

    def __repr__ (self) :

   149

        return 'Container(%s)' % ', '.join(repr(c) for c in self.contents)

   150

   151

class Tag (Container) :

   152

    """

   153

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

   154

   155

        Provides various kinds of rendering output

   156

    """

   157

   158

    @staticmethod

   159

    def process_attrs (attrs) :

   160

        """

   161

            Postprocess attributes.

   162

   163

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

   164

   165

            TODO: only remove one underscore

   166

   167

            >>> dict(Tag.process_attrs(dict()))

   168

            {}

   169

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

   170

            {'foo': 'bar'}

   171

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

   172

            {'class': 'bar'}

   173

        """

   174

   175

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

   176

   177

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

   178

        """

   179

            Construct tag with given name/attributes or contents.

   180

   181

            The filtering rules desribed in process_contents/process_attrs apply.

   182

   183

            >>> Tag('foo')

   184

            Tag('foo')

   185

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

   186

            Tag('foo', 'quux')

   187

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

   188

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

   189

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

   190

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

   191

        """

   192

   193

        # store contents as container

   194

        super(Tag, self).__init__(*contents)

   195

   196

        # store postprocessed stuff

   197

        self.name = name

   198

        self.attrs = dict(self.process_attrs(attrs))

   199

   200

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

   201

        """

   202

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

   203

   204

            The filtering rules desribed in process_contents/process_attrs apply.

   205

   206

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

   207

            Tag('foo', 'bar')

   208

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

   209

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

   210

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

   211

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

   212

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

   213

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

   214

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

   215

            Tag('a')

   216

        """

   217

   218

        # merge attrs/contents

   219

        # XXX: new_attrs is not an iterator...

   220

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

   221

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

   222

   223

        # build new tag

   224

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

   225

   226

    @staticmethod

   227

    def format_attr (name, value) :

   228

        """

   229

            Format a single HTML tag attribute

   230

   231

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

   232

            u'name="value"'

   233

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

   234

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

   235

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

   236

            u'xx="1337"'

   237

        """

   238

   239

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

   240

   241

    def render_attrs (self) :

   242

        """

   243

            Return the HTML attributes string

   244

   245

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

   246

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

   247

        """

   248

   249

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

   250

   251

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

   252

        """

   253

            Render the tag and indented content

   254

   255

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

   256

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

   257

        """

   258

   259

        # render attr string, including preceding space

   260

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

   261

   262

        if self.contents :

   263

            # wrapping tags

   264

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

   265

   266

            # subcontents

   267

            for line in super(Tag, self).render_raw_lines(indent=indent) :

   268

                yield indent + line

   269

   270

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

   271

   272

        else :

   273

            # singleton tag

   274

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

   275

   276

   277

    def __repr__ (self) :

   278

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

   279

            [

   280

                repr(self.name)

   281

            ] + [

   282

                repr(c) for c in self.contents

   283

            ] + [

   284

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

   285

            ]

   286

        )

   287

   288

class Text (IRenderable) :

   289

    """

   290

        Raw HTML text

   291

    """

   292

   293

    def __init__ (self, line) :

   294

        """

   295

            Initialize to render as the given lines

   296

        """

   297

   298

        self.lines = [line]

   299

   300

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

   301

        return self.lines

   302

   303

class XHTMLDocument (IRenderable) :

   304

    """

   305

        A full XHTML document with XML header, doctype, head and body.

   306

   307

        XXX: current rendering is a bit of a kludge

   308

   309

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

   310

        <!DOCTYPE ...>

   311

   312

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

   313

            <head>

   314

                ...

   315

            </head>

   316

            <body>

   317

                ...

   318

            </body>

   319

        </html>

   320

    """

   321

   322

    def __init__ (self, 

   323

        head, body,

   324

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

   325

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

   326

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

   327

    ) :

   328

        # store

   329

        self.xml_version = xml_version

   330

        self.xml_encoding = xml_encoding

   331

        self.doctype = doctype

   332

   333

        # build the document

   334

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

   335

            Tag('head', head),

   336

            Tag('body', body),

   337

        )

   338

   339

    def render_raw_lines (self, **render_opts) :

   340

        """

   341

            Render the two header lines, and then the document

   342

        """

   343

   344

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

   345

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

   346

   347

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

   348

            yield line

   349

   350

    def _check_encoding (self, encoding) :

   351

        if encoding and encoding != self.xml_encoding :

   352

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

   353

   354

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

   355

        """

   356

            Wrap render_str to verify that the right encoding is used

   357

        """

   358

   359

        self._check_encoding(encoding)

   360

   361

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

   362

   363

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

   364

        """

   365

            Wrap render_out to verify that the right encoding is used

   366

        """

   367

   368

        self._check_encoding(encoding)

   369

   370

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

   371

   372

class TagFactory (object) :

   373

    """

   374

        Build Tags with names give as attribute names

   375

    """

   376

   377

    def __getattr__ (self, name) :

   378

        """

   379

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

   380

   381

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

   382

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

   383

        """

   384

   385

        return Tag(name)

   386

   387

# pretty names

   388

container = Container

   389

tag = Tag

   390

tags = TagFactory()

   391

raw = Text

   392

   393

# testing

   394

if __name__ == '__main__' :

   395

    import doctest

   396

   397

    doctest.testmod()

   398