1

"""

     2

    Generating XHTML output from nested python objects

     3

     4

    XXX: use a 'real' XML builder?

     5

     6

    To use:

     7

     8

    >>> from html import tags

     9

    >>> str(tags.a(href="http://www.google.com")("Google <this>!"))

    10

    '<a href="http://www.google.com">\\n\\tGoogle &lt;this&gt;!\\n</a>\\n'

    11

"""

    12

    13

from cgi import escape

    14

import itertools as _itertools, types as _types

    15

    16

class IRenderable (object) :

    17

    """

    18

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

    19

    20

        This is just used by Container for rendering Tags as actual HTML, vs just plain strs as escaped data.

    21

    22

        Additionally, some str vs unicode vs file stuff..

    23

    """

    24

    25

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

    26

        """

    27

            Render the indented lines for tag and contents, without newlines

    28

        """

    29

    30

        abstract

    31

    32

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

    33

        """

    34

            Render full output lines with given newlines

    35

    36

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

    37

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

    38

        """

    39

    40

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

    41

            yield line + newline

    42

    43

    def render_unicode (self, **render_opts) :

    44

        """

    45

            Render full tag as a single unicode string

    46

    47

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

    48

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

    49

        """

    50

    51

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

    52

    53

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

    54

        """

    55

            Render full tag as an encoded string

    56

    57

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

    58

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

    59

        """

    60

    61

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

    62

    63

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

    64

        """

    65

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

    66

    67

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

    68

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

    69

        """

    70

    71

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

    72

            if encoding :

    73

                line = line.encode(encoding)

    74

    75

            stream.write(line)

    76

    77

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

    78

        """

    79

            Render output to given file, overwriteing anything already there

    80

        """

    81

    82

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

    83

    84

    # default output

    85

    __str__ = render_str

    86

    __unicode__ = render_unicode

    87

    88

    # default .render method

    89

    render = render_unicode

    90

    91

class Container (IRenderable) :

    92

    """

    93

        A container holds a sequence of other renderable items.

    94

    95

        This is just used as the superclass for Tag, and just serves to gives us useful handling for e.g. generators as

    96

        tag contents (iterate through them instead of repr'ing them).

    97

    """

    98

    99

    @classmethod

   100

    def process_contents (cls, contents) :

   101

        """

   102

            Postprocess contents iterable to return new list.

   103

   104

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

   105

   106

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

   107

   108

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

   109

            []

   110

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

   111

            []

   112

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

   113

            [u'foo']

   114

        """

   115

   116

        for content in contents :

   117

            if content is None :

   118

                continue

   119

   120

            # Hardcoded list of special-case nested contents

   121

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

   122

                for subcontent in cls.process_contents(content) :

   123

                    yield subcontent

   124

   125

            else :

   126

                # normal, handle as IRenderable/unicode data

   127

                yield content

   128

   129

    def __init__ (self, *contents) :

   130

        """

   131

            Construct this container with the given sub-items

   132

        """

   133

   134

        # store postprocessed

   135

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

   136

   137

    def render_raw_lines (self, **render_opts) :

   138

        """

   139

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

   140

   141

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

   142

            [u'5']

   143

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

   144

            [u'line1', u'line2']

   145

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

   146

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

   147

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

   148

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

   149

        """

   150

   151

        for content in self.contents :

   152

            if isinstance(content, IRenderable) :

   153

                # sub-items

   154

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

   155

                    yield line

   156

   157

            else :

   158

                # escape raw values

   159

                yield escape(unicode(content))

   160

   161

    def __repr__ (self) :

   162

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

   163

   164

class Tag (Container) :

   165

    """

   166

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

   167

   168

        This is the core object, and the ~only one you really need to pay attention to.

   169

   170

        Provides various kinds of rendering output via IRenderable.

   171

    """

   172

   173

    @staticmethod

   174

    def process_attrs (attrs) :

   175

        """

   176

            Postprocess attributes.

   177

   178

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

   179

   180

            TODO: only remove one underscore

   181

   182

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

   183

            {}

   184

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

   185

            {'foo': 'bar'}

   186

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

   187

            {'class': 'bar'}

   188

        """

   189

   190

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

   191

   192

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

   193

        """

   194

            Construct tag with given name/attributes or contents.

   195

   196

            The filtering rules desribed in process_contents/process_attrs apply.

   197

   198

            >>> Tag('foo')

   199

            Tag('foo')

   200

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

   201

            Tag('foo', 'quux')

   202

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

   203

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

   204

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

   205

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

   206

            >>> Tag('bar', name='foo')

   207

            Tag('bar', name='foo')

   208

        """

   209

   210

        # store contents as container

   211

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

   212

   213

        # store postprocessed stuff

   214

        self.name = _name

   215

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

   216

   217

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

   218

        """

   219

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

   220

   221

            The filtering rules desribed in process_contents/process_attrs apply.

   222

   223

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

   224

            Tag('foo', 'bar')

   225

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

   226

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

   227

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

   228

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

   229

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

   230

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

   231

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

   232

            Tag('a')

   233

        """

   234

   235

        # merge attrs/contents

   236

        # XXX: new_attrs is not an iterator...

   237

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

   238

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

   239

   240

        # build new tag

   241

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

   242

   243

    @staticmethod

   244

    def format_attr (name, value) :

   245

        """

   246

            Format a single HTML tag attribute

   247

   248

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

   249

            u'name="value"'

   250

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

   251

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

   252

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

   253

            u'xx="1337"'

   254

        """

   255

   256

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

   257

   258

    def render_attrs (self) :

   259

        """

   260

            Return the HTML attributes string

   261

   262

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

   263

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

   264

        """

   265

   266

        return " ".join(self.format_attr(n, v) for n, v in self.attrs.iteritems() if not n.startswith('_'))

   267

   268

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

   269

        """

   270

            Render the tag and indented content

   271

   272

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

   273

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

   274

        """

   275

   276

        # opts

   277

        selfclosing = self.attrs.get('_selfclosing')

   278

        whitespace_sensitive = self.attrs.get('_whitespace_sensitive')

   279

   280

        # render attr string, including preceding space

   281

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

   282

   283

        if self.contents or selfclosing is False:

   284

   285

            if not whitespace_sensitive :

   286

                # wrapping tags

   287

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

   288

   289

                # subcontents

   290

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

   291

                    yield indent + line

   292

   293

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

   294

   295

            else :

   296

                # whole tag

   297

                yield u"<%s%s>%s</%s>" % (self.name, attrs_stuff, ''.join(super(Tag, self).render_raw_lines(indent=indent)), self.name)

   298

        else :

   299

            # singleton tag

   300

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

   301

   302

   303

    def __repr__ (self) :

   304

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

   305

            [

   306

                repr(self.name)

   307

            ] + [

   308

                repr(c) for c in self.contents

   309

            ] + [

   310

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

   311

            ]

   312

        )

   313

   314

class Text (IRenderable) :

   315

    """

   316

        Raw HTML text

   317

    """

   318

   319

    def __init__ (self, line) :

   320

        """

   321

            Initialize to render as the given lines

   322

        """

   323

   324

        self.lines = [line]

   325

   326

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

   327

        return self.lines

   328

   329

class Document (IRenderable) :

   330

    """

   331

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

   332

   333

        XXX: current rendering is a bit of a kludge

   334

   335

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

   336

        <!DOCTYPE ...>

   337

   338

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

   339

            <head>

   340

                ...

   341

            </head>

   342

            <body>

   343

                ...

   344

            </body>

   345

        </html>

   346

    """

   347

   348

    def __init__ (self, 

   349

        head, body,

   350

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

   351

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

   352

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

   353

    ) :

   354

        # store

   355

        self.xml_version = xml_version

   356

        self.xml_encoding = xml_encoding

   357

        self.doctype = doctype

   358

   359

        # build the document

   360

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

   361

            Tag('head', head),

   362

            Tag('body', body),

   363

        )

   364

   365

    def render_raw_lines (self, **render_opts) :

   366

        """

   367

            Render the two header lines, and then the document

   368

        """

   369

   370

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

   371

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

   372

   373

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

   374

            yield line

   375

   376

    def _check_encoding (self, encoding) :

   377

        if encoding and encoding != self.xml_encoding :

   378

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

   379

   380

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

   381

        """

   382

            Wrap render_str to verify that the right encoding is used

   383

        """

   384

   385

        self._check_encoding(encoding)

   386

   387

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

   388

   389

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

   390

        """

   391

            Wrap render_out to verify that the right encoding is used

   392

        """

   393

   394

        self._check_encoding(encoding)

   395

   396

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

   397

   398

class TagFactory (object) :

   399

    """

   400

        Build Tags with names give as attribute names

   401

   402

        >>> str(TagFactory().raw("><")

   403

        '><'

   404

    """

   408

   409

    # raw HTML

   410

    raw = Text

   411

   412

    def __getattr__ (self, name) :

   413

        """

   414

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

   415

   416

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

   417

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

   418

        """

   419

   420

        return Tag(name)

   421

   422

# pretty names

   423

container = Container

   424

tag = Tag

   425

tags = TagFactory()

   426

raw = Text

   427

document = Document

   428

   429

# testing

   430

if __name__ == '__main__' :

   431

    import doctest

   432

   433

    doctest.testmod()

   434