1

"""

     2

    Generate XHTML output from python code.

     3

     4

    >>> from html import tags

     5

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

     6

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

     7

"""

     8

     9

import itertools as itertools

    10

import types as types

    11

from xml.sax import saxutils

    12

    13

class Renderable (object) :

    14

    """

    15

        Structured data that's flattened into indented lines of text.

    16

    """

    17

    18

    def flatten (self) :

    19

        """

    20

            Flatten this object into a series of (identlevel, line) tuples.

    21

        """

    22

    23

        raise NotImplementedError()

    24

    25

    def iter (self, indent='\t') :

    26

        """

    27

            Yield a series of lines for this render.

    28

        """

    29

    30

        for indent_level, line in self.flatten() :

    31

            yield (indent * indent_level) + line

    32

    33

    def unicode (self, newline=u'\n', **opts) :

    34

        """

    35

            Render as a single unicode string.

    36

    37

            No newline is returned at the end of the string.

    38

    39

            >>> Tag.build('a', 'b').unicode(newline='X', indent='Y')

    40

            u'<a>XYbX</a>'

    41

        """

    42

    43

        return newline.join(self.iter(**opts))

    44

    45

    # required for print

    46

    def str (self, newline='\n', encoding='ascii', **opts) :

    47

        """

    48

            Render as a single string.

    49

        """

    50

    51

        # XXX: try and render as non-unicode, i.e. binary data in the tree?

    52

        return newline.join(line.encode(encoding) for line in self.iter(**opts))

    53

    54

    # formal interface using defaults

    55

    __iter__ = iter

    56

    __unicode__ = unicode

    57

    __str__ = str

    58

    59

class Text (Renderable) :

    60

    """

    61

        Plain un-structured/un-processed HTML text for output

    62

    63

        >>> Text('foo')

    64

        Text(u'foo')

    65

        >>> list(Text('<foo>'))

    66

        [u'<foo>']

    67

        >>> list(tag('a', Text('<foo>')))

    68

        [u'<a>', u'\\t<foo>', u'</a>']

    69

    """

    70

    71

    def __init__ (self, text) :

    72

        self.text = unicode(text)

    73

    74

    def flatten (self) :

    75

        yield (0, self.text)

    76

    77

    def __repr__ (self) :

    78

        return "Text(%r)" % (self.text, )

    79

    80

class Tag (Renderable) :

    81

    """

    82

        An immutable HTML tag structure, with the tag's name, attributes and contents.

    83

    """

    84

    85

    # types of nested items to flatten

    86

    CONTAINER_TYPES = (types.TupleType, types.ListType, types.GeneratorType)

    87

    88

    # types of items to keep as-is

    89

    ITEM_TYPES = (Renderable, )

    90

    91

    @classmethod

    92

    def process_contents (cls, *args) :

    93

        """

    94

            Yield the HTML tag's contents from the given sequence of positional arguments as a series of flattened

    95

            items, eagerly converting them to unicode.

    96

    97

            If no arguments are given, we don't have any children:

    98

    99

            >>> bool(list(Tag.process_contents()))

   100

            False

   101

   102

            Items that are None will be ignored:

   103

   104

            >>> list(Tag.process_contents(None))

   105

            []

   106

   107

            Various Python container types are recursively flattened:

   108

   109

            >>> list(Tag.process_contents([1, 2]))

   110

            [u'1', u'2']

   111

            >>> list(Tag.process_contents([1], [2]))

   112

            [u'1', u'2']

   113

            >>> list(Tag.process_contents([1, [2]]))

   114

            [u'1', u'2']

   115

            >>> list(Tag.process_contents(n + 1 for n in xrange(2)))

   116

            [u'1', u'2']

   117

            >>> list(Tag.process_contents((1, 2)))

   118

            [u'1', u'2']

   119

            >>> list(Tag.process_contents((1), (2, )))

   120

            [u'1', u'2']

   121

   122

            Our own HTML-aware objects are returned as-is:

   123

   124

            >>> list(Tag.process_contents(Tag.build('foo')))

   125

            [tag('foo')]

   126

            >>> list(Tag.process_contents(Text('bar')))

   127

            [Text(u'bar')]

   128

   129

            All other objects are converted to unicode:

   130

   131

            >>> list(Tag.process_contents('foo', u'bar', 0.123, False))

   132

            [u'foo', u'bar', u'0.123', u'False']

   133

   134

        """

   135

   136

        for arg in args :

   137

            if arg is None :

   138

                # skip null: None

   139

                continue

   140

   141

            elif isinstance(arg, cls.CONTAINER_TYPES) :

   142

                # flatten nested container: tuple/list/generator

   143

                for node in arg :

   144

                    # recurse

   145

                    for item in cls.process_contents(node) :

   146

                        yield item

   147

   148

            elif isinstance(arg, cls.ITEM_TYPES) :

   149

                # yield item: Renderable

   150

                yield arg

   151

   152

            else :

   153

                # as unicode

   154

                yield unicode(arg)

   155

   156

    @classmethod

   157

    def process_attrs (cls, **kwargs) :

   158

        """

   159

            Yield the HTML tag attributes from the given set of keyword arguments as a series of (name, value) tuples.

   160

   161

            Keyword-only options (`_key=value`) are filtered out:

   162

   163

            >>> dict(Tag.process_attrs(_opt=True))

   164

            {}

   165

   166

            Attributes with a value of None/False are filtered out:

   167

   168

            >>> dict(Tag.process_attrs(foo=None, bar=False))

   169

            {}

   170

   171

            A value given as True is returned as the key's value:

   172

   173

            >>> dict(Tag.process_attrs(quux=True))

   174

            {'quux': u'quux'}

   175

   176

            A (single) trailing underscore in the attribute name is removed:

   177

   178

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

   179

            {'class': u'foo'}

   180

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

   181

            {'data_': u'foo'}

   182

        """

   183

   184

        for key, value in kwargs.iteritems() :

   185

            # keyword arguments are always pure strings

   186

            assert type(key) is str

   187

   188

            if value is None or value is False:

   189

                # omit

   190

                continue

   191

   192

            if key.startswith('_') :

   193

                # option

   194

                continue

   195

   196

            if key.endswith('_') :

   197

                # strip underscore

   198

                key = key[:-1]

   199

   200

            if value is True :

   201

                # flag attr

   202

                value = key

   203

   204

            yield key, unicode(value)

   205

   206

    @classmethod

   207

    def process_opts (cls, **kwargs) :

   208

        """

   209

            Return a series of of the keyword-only _options, extracted from the given dict of keyword arguments, as 

   210

            (k, v) tuples.

   211

   212

            >>> Tag.process_opts(foo='bar', _bar=False)

   213

            (('bar', False),)

   214

        """

   215

   216

        return tuple((k.lstrip('_'), v) for k, v in kwargs.iteritems() if k.startswith('_'))

   217

   218

    @classmethod

   219

    def build (cls, _name, *args, **kwargs) :

   220

        """

   221

            Factory function for constructing Tags by directly passing in contents/attributes/options as Python function

   222

            arguments/keyword arguments.

   223

   224

            The first positional argument is the tag's name:

   225

   226

            >>> Tag.build('foo')

   227

            tag('foo')

   228

   229

            Further positional arguments are the tag's contents:

   230

   231

            >>> Tag.build('foo', 'quux', 'bar')

   232

            tag('foo', u'quux', u'bar')

   233

   234

            All the rules used by process_contents() are available:

   235

   236

            >>> Tag.build('foo', [1, None], None, (n for n in xrange(2)))

   237

            tag('foo', u'1', u'0', u'1')

   238

   239

            The special-case for a genexp as the only argument works:

   240

   241

            >>> f = lambda *args: Tag.build('foo', *args)

   242

            >>> f('hi' for n in xrange(2))

   243

            tag('foo', u'hi', u'hi')

   244

   245

            Attributes are passed as keyword arguments, with or without contents:

   246

   247

            >>> Tag.build('foo', id=1)

   248

            tag('foo', id=u'1')

   249

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

   250

            tag('foo', u'quux', bar=u'5')

   251

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

   252

            tag('foo', class=u'ten')

   253

   254

            The attribute names don't conflict with positional argument names:

   255

   256

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

   257

            tag('bar', name=u'foo')

   258

   259

            Options are handled as the 'real' keyword arguments:

   260

   261

            >>> print Tag.build('foo', _selfclosing=False)

   262

            <foo></foo>

   263

            >>> print Tag.build('foo', _foo='bar')

   264

            Traceback (most recent call last):

   265

                ...

   266

            TypeError: __init__() got an unexpected keyword argument 'foo'

   267

        """

   268

   269

        # pre-process incoming user values

   270

        contents = list(cls.process_contents(*args))

   271

        attrs = dict(cls.process_attrs(**kwargs))

   272

   273

        # XXX: use Python 2.6 keyword-only arguments instead?

   274

        options = dict(cls.process_opts(**kwargs))

   275

   276

        return cls(_name, contents, attrs, **options)

   277

   278

    def __init__ (self, name, contents, attrs, selfclosing=None, whitespace_sensitive=None) :

   279

        """

   280

            Initialize internal Tag state with the given tag identifier, flattened list of content items, dict of

   281

            attributes and dict of options.

   282

   283

                selfclosing             - set to False to render empty tags as <foo></foo> instead of <foo /> 

   284

                                          (for XHTML -> HTML compatibility)

   285

   286

                whitespace_sensitive    - do not indent tag content onto separate rows, render the full tag as a single

   287

                                          row

   288

   289

            Use the build() factory function to build Tag objects using Python's function call argument semantics.

   290

   291

            The tag name is used a pure string identifier:

   292

   293

            >>> Tag(u'foo', [], {})

   294

            tag('foo')

   295

            >>> Tag(u'\\xE4', [], {})

   296

            Traceback (most recent call last):

   297

                ...

   298

            UnicodeEncodeError: 'ascii' codec can't encode character u'\\xe4' in position 0: ordinal not in range(128)

   299

   300

            Contents have their order preserved:

   301

   302

            >>> Tag('foo', [1, 2], {})

   303

            tag('foo', 1, 2)

   304

            >>> Tag('foo', [2, 1], {})

   305

            tag('foo', 2, 1)

   306

   307

            Attributes can be given:

   308

   309

            >>> Tag('foo', [], dict(foo='bar'))

   310

            tag('foo', foo='bar')

   311

   312

            Options can be given:

   313

   314

            >>> print Tag('foo', [], {}, selfclosing=False)

   315

            <foo></foo>

   316

        """

   317

   318

        self.name = str(name)

   319

        self.contents = contents

   320

        self.attrs = attrs

   321

   322

        # options

   323

        self.selfclosing = selfclosing

   324

        self.whitespace_sensitive = whitespace_sensitive

   325

   326

    def __call__ (self, *args, **kwargs) :

   327

        """

   328

            Return a new Tag as a copy of this tag, but with the given additional attributes/contents.

   329

   330

            The same rules for function positional/keyword arguments apply as for build()

   331

   332

            >>> Tag.build('foo')('bar')

   333

            tag('foo', u'bar')

   334

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

   335

            tag('a', u'Home', href=u'index.html')

   336

   337

            New contents and attributes can be given freely, using the same rules as for Tag.build:

   338

   339

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

   340

            tag('bar', u'5', class=u'bar')

   341

   342

            Tag contents accumulate in order:

   343

   344

            >>> Tag.build('a')('b', ['c'])('d')

   345

            tag('a', u'b', u'c', u'd')

   346

   347

            Each Tag is immutable, so the called Tag isn't changed, but rather a copy is returned:

   348

   349

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

   350

            tag('a')

   351

   352

            Attribute values are replaced:

   353

   354

            >>> Tag.build('foo', a=2)(a=3)

   355

            tag('foo', a=u'3')

   356

   357

            Options are also supported:

   358

   359

            >>> list(Tag.build('foo')(bar='quux', _selfclosing=False))

   360

            [u'<foo bar="quux"></foo>']

   361

        """

   362

   363

        # accumulate contents

   364

        contents = self.contents + list(self.process_contents(*args))

   365

   366

        # merge attrs

   367

        attrs = dict(self.attrs)

   368

        attrs.update(self.process_attrs(**kwargs))

   369

   370

        # options

   371

        opts = dict(

   372

            selfclosing = self.selfclosing,

   373

            whitespace_sensitive = self.whitespace_sensitive,

   374

        )

   375

        opts.update(self.process_opts(**kwargs))

   376

   377

        # build updated tag

   378

        return Tag(self.name, contents, attrs, **opts)

   379

   380

    def render_attrs (self) :

   381

        """

   382

            Return the HTML attributes string

   383

   384

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

   385

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

   386

            >>> Tag.build('x', foo='a"b').render_attrs()

   387

            u'foo=\\'a"b\\''

   388

        """

   389

   390

        return " ".join(

   391

            (

   392

                u'%s=%s' % (name, saxutils.quoteattr(value))

   393

            ) for name, value in self.attrs.iteritems()

   394

        )

   395

   396

    def flatten_items (self, indent=1) :

   397

        """

   398

            Flatten our content into a series of indented lines.

   399

   400

            >>> list(Tag.build('tag', 5).flatten_items())

   401

            [(1, u'5')]

   402

            >>> list(Tag.build('tag', 'line1', 'line2').flatten_items())

   403

            [(1, u'line1'), (1, u'line2')]

   404

   405

            Nested :

   406

            >>> list(Tag.build('tag', 'a', Tag.build('b', 'bb'), 'c').flatten_items())

   407

            [(1, u'a'), (1, u'<b>'), (2, u'bb'), (1, u'</b>'), (1, u'c')]

   408

            >>> list(Tag.build('tag', Tag.build('hr'), Tag.build('foo')('bar')).flatten_items())

   409

            [(1, u'<hr />'), (1, u'<foo>'), (2, u'bar'), (1, u'</foo>')]

   410

        """

   411

   412

        for item in self.contents :

   413

            if isinstance(item, Renderable) :

   414

                # recursively flatten items

   415

                for line_indent, line in item.flatten() :

   416

                    # indented

   417

                    yield indent + line_indent, line

   418

   419

            else :

   420

                # render HTML-escaped raw value

   421

                # escape raw values

   422

                yield indent, saxutils.escape(item)

   423

   424

    def flatten (self) :

   425

        """

   426

            Render the tag and all content as a flattened series of indented lines.

   427

   428

            Empty tags collapse per default:

   429

   430

            >>> list(Tag.build('foo').flatten())

   431

            [(0, u'<foo />')]

   432

            >>> list(Tag.build('bar', id=5).flatten())

   433

            [(0, u'<bar id="5" />')]

   434

   435

            Values are indented inside the start tag:

   436

   437

            >>> list(Tag.build('foo', 'bar', a=5).flatten())

   438

            [(0, u'<foo a="5">'), (1, u'bar'), (0, u'</foo>')]

   439

   440

            Nested tags are further indented:

   441

   442

            >>> list(Tag.build('1', '1.1', Tag.build('1.2', '1.2.1'), '1.3', a=5).flatten())

   443

            [(0, u'<1 a="5">'), (1, u'1.1'), (1, u'<1.2>'), (2, u'1.2.1'), (1, u'</1.2>'), (1, u'1.3'), (0, u'</1>')]

   444

   445

            Empty tags are rendered with a separate closing tag on the same line, if desired:

   446

   447

            >>> list(Tag.build('foo', _selfclosing=False).flatten())

   448

            [(0, u'<foo></foo>')]

   449

            >>> list(Tag.build('foo', src='asdf', _selfclosing=False).flatten())

   450

            [(0, u'<foo src="asdf"></foo>')]

   451

   452

            Tags that are declared as whitespace-sensitive are collapsed onto the same line:

   453

   454

            >>> list(Tag.build('foo', _whitespace_sensitive=True).flatten())

   455

            [(0, u'<foo />')]

   456

            >>> list(Tag.build('foo', _whitespace_sensitive=True, _selfclosing=False).flatten())

   457

            [(0, u'<foo></foo>')]

   458

            >>> list(Tag.build('foo', 'bar', _whitespace_sensitive=True).flatten())

   459

            [(0, u'<foo>bar</foo>')]

   460

            >>> list(Tag.build('foo', 'bar\\nasdf\\tx', _whitespace_sensitive=True).flatten())

   461

            [(0, u'<foo>bar\\nasdf\\tx</foo>')]

   462

            >>> list(Tag.build('foo', 'bar', Tag.build('quux', 'asdf'), 'asdf', _whitespace_sensitive=True).flatten())

   463

            [(0, u'<foo>bar<quux>asdf</quux>asdf</foo>')]

   464

   465

            Embedded HTML given as string values is escaped:

   466

   467

            >>> list(Tag.build('foo', '<asdf>'))

   468

            [u'<foo>', u'\\t&lt;asdf&gt;', u'</foo>']

   469

   470

            Embedded quotes in attribute values are esacaped:

   471

   472

            >>> list(Tag.build('foo', style='ok;" onload="...'))

   473

            [u'<foo style=\\'ok;" onload="...\\' />']

   474

            >>> list(Tag.build('foo', style='ok;\\'" onload=..."\\''))

   475

            [u'<foo style="ok;\\'&quot; onload=...&quot;\\'" />']

   476

        """

   477

   478

        # optional attr spec

   479

        if self.attrs :

   480

            attrs = " " + self.render_attrs()

   481

   482

        else :

   483

            attrs = ""

   484

   485

        if not self.contents and self.selfclosing is False :

   486

            # empty tag, but don't use the self-closing syntax..

   487

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

   488

   489

        elif not self.contents  :

   490

            # self-closing xml tag

   491

            # do note that this is invalid HTML, and the space before the / is relevant for parsing it as HTML

   492

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

   493

   494

        elif self.whitespace_sensitive :

   495

            # join together each line for each child, discarding the indent

   496

            content = u''.join(line for indent, line in self.flatten_items())

   497

   498

            # render full tag on a single line

   499

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

   500

   501

        else :

   502

            # start tag

   503

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

   504

   505

            # contents, indented one level below the start tag

   506

            for indent, line in self.flatten_items(indent=1) :

   507

                yield indent, line

   508

   509

            # close tag

   510

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

   511

   512

    def __repr__ (self) :

   513

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

   514

            [

   515

                repr(self.name)

   516

            ] + [

   517

                repr(c) for c in self.contents

   518

            ] + [

   519

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

   520

            ]

   521

        )

   522

   523

# factory function for Tag

   524

tag = Tag.build

   525

   526

   527

class Document (Renderable) :

   528

    """

   529

        A full XHTML 1.0 document with optional XML header, doctype, html[@xmlns].

   530