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

# XXX: needs some refactoring for Text vs Tag now

    10

# XXX: not all tags work in self-closing form, e.g. empty html.title() breaks badly

    11

    12

import itertools as itertools

    13

import types as types

    14

from xml.sax import saxutils

    15

    16

class Renderable (object) :

    17

    """

    18

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

    19

    """

    20

    21

    # types of nested items to flatten

    22

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

    23

    24

    @classmethod

    25

    def process_contents (cls, *args) :

    26

        """

    27

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

    28

            items, eagerly converting them to unicode.

    29

    30

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

    31

    32

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

    33

            False

    34

    35

            Items that are None will be ignored:

    36

    37

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

    38

            []

    39

    40

            Various Python container types are recursively flattened:

    41

    42

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

    43

            [u'1', u'2']

    44

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

    45

            [u'1', u'2']

    46

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

    47

            [u'1', u'2']

    48

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

    49

            [u'1', u'2']

    50

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

    51

            [u'1', u'2']

    52

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

    53

            [u'1', u'2']

    54

    55

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

    56

    57

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

    58

            [tag('foo')]

    59

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

    60

            [Text(u'bar')]

    61

    62

            All other objects are converted to unicode:

    63

    64

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

    65

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

    66

    67

        """

    68

    69

        for arg in args :

    70

            if arg is None :

    71

                # skip null: None

    72

                continue

    73

    74

            elif isinstance(arg, cls.CONTAINER_TYPES) :

    75

                # flatten nested container: tuple/list/generator

    76

                for node in arg :

    77

                    # recurse

    78

                    for item in cls.process_contents(node) :

    79

                        yield item

    80

    81

            elif isinstance(arg, Renderable) :

    82

                # yield item: Renderable

    83

                yield arg

    84

    85

            else :

    86

                # as unicode

    87

                yield unicode(arg)

    88

    89

    90

    def flatten (self) :

    91

        """

    92

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

    93

        """

    94

    95

        raise NotImplementedError()

    96

    97

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

    98

        """

    99

            Yield a series of lines for this render.

   100

        """

   101

   102

        for indent_level, line in self.flatten() :

   103

            yield (indent * indent_level) + line

   104

   105

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

   106

        """

   107

            Render as a single unicode string.

   108

   109

            No newline is returned at the end of the string.

   110

   111

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

   112

            u'<a>XYbX</a>'

   113

        """

   114

   115

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

   116

   117

    # required for print

   118

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

   119

        """

   120

            Render as a single string.

   121

        """

   122

   123

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

   124

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

   125

   126

    # formal interface using defaults

   127

    __iter__ = iter

   128

    __unicode__ = unicode

   129

    __str__ = str

   130

   131

class Text (Renderable) :

   132

    """

   133

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

   134

   135

        >>> Text(u'foo')

   136

        Text(u'foo')

   137

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

   138

        [u'<foo>']

   139

        >>> list(Text('<foo>', tag('p', 'test')))

   140

        [u'<foo>', u'<p>', u'\\ttest', u'</p>']

   141

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

   142

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

   143

        >>> list(Text(range(2)))

   144

        [u'0', u'1']

   145

   146

    """

   147

   148

    def __init__ (self, *contents) :

   149

        self.contents = self.process_contents(*contents)

   150

   151

    def flatten (self, indent=0) :

   152

        for item in self.contents :

   153

            if isinstance(item, Renderable) :

   154

                # recursively flatten items

   155

                for line_indent, line in item.flatten() :

   156

                    # indented

   157

                    yield indent + line_indent, line

   158

   159

            else :

   160

                # render raw value

   161

                yield indent, unicode(item)

   162

   163

    def __repr__ (self) :

   164

        return "Text(%s)" % (', '.join(repr(item) for item in self.contents))

   165

   166

class Tag (Renderable) :

   167

    """

   168

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

   169

    """

   170

   171

    @classmethod

   172

    def process_attrs (cls, **kwargs) :

   173

        """

   174

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

   175

   176

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

   177

   178

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

   179

            {}

   180

   181

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

   182

   183

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

   184

            {}

   185

   186

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

   187

   188

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

   189

            {'quux': u'quux'}

   190

   191

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

   192

   193

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

   194

            {'class': u'foo'}

   195

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

   196

            {'data_': u'foo'}

   197

        """

   198

   199

        for key, value in kwargs.iteritems() :

   200

            # keyword arguments are always pure strings

   201

            assert type(key) is str

   202

   203

            if value is None or value is False:

   204

                # omit

   205

                continue

   206

   207

            if key.startswith('_') :

   208

                # option

   209

                continue

   210

   211

            if key.endswith('_') :

   212

                # strip underscore

   213

                key = key[:-1]

   214

   215

            if value is True :

   216

                # flag attr

   217

                value = key

   218

   219

            yield key, unicode(value)

   220

   221

    @classmethod

   222

    def process_opts (cls, **kwargs) :

   223

        """

   224

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

   225

            (k, v) tuples.

   226

   227

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

   228

            (('bar', False),)

   229

        """

   230

   231

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

   232

   233

    @classmethod

   234

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

   235

        """

   236

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

   237

            arguments/keyword arguments.

   238

   239

            The first positional argument is the tag's name:

   240

   241

            >>> Tag.build('foo')

   242

            tag('foo')

   243

   244

            Further positional arguments are the tag's contents:

   245

   246

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

   247

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

   248

   249

            All the rules used by process_contents() are available:

   250

   251

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

   252

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

   253

   254

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

   255

   256

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

   257

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

   258

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

   259

   260

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

   261

   262

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

   263

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

   264

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

   265

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

   266

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

   267

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

   268

   269

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

   270

   271

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

   272

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

   273

   274

            Options are handled as the 'real' keyword arguments:

   275

   276

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

   277

            <foo></foo>

   278

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

   279

            Traceback (most recent call last):

   280

                ...

   281

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

   282

        """

   283

   284

        # pre-process incoming user values

   285

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

   286

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

   287

   288

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

   289

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

   290

   291

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

   292

   293

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

   294

        """

   295

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

   296

            attributes and dict of options.

   297

   298

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

   299

                                          (for XHTML -> HTML compatibility)

   300

   301

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

   302

                                          row

   303

   304

                escape                  - html-escape non-Renderable's (text)

   305

   306

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

   307

   308

            The tag name is used a pure string identifier:

   309

   310

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

   311

            tag('foo')

   312

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

   313

            Traceback (most recent call last):

   314

                ...

   315

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

   316

   317

            Contents have their order preserved:

   318

   319

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

   320

            tag('foo', 1, 2)

   321

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

   322

            tag('foo', 2, 1)

   323

   324

            Attributes can be given:

   325

   326

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

   327

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

   328

   329

            Options can be given:

   330

   331

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

   332

            <foo></foo>

   333

        """

   334

   335

        self.name = str(name)

   336

        self.contents = contents

   337

        self.attrs = attrs

   338

   339

        # options

   340

        self.selfclosing = selfclosing

   341

        self.whitespace_sensitive = whitespace_sensitive

   342

        self.escape = escape

   343

   344

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

   345

        """

   346

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

   347

   348

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

   349

   350

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

   351

            tag('foo', u'bar')

   352

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

   353

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

   354

   355

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

   356

   357

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

   358

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

   359

   360

            Tag contents accumulate in order:

   361

   362

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

   363

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

   364

   365

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

   366

   367

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

   368

            tag('a')

   369

   370

            Attribute values are replaced:

   371

   372

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

   373

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

   374

   375

            Options are also supported:

   376

   377

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

   378

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

   379

        """

   380

   381

        # accumulate contents

   382

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

   383

   384

        # merge attrs

   385

        attrs = dict(self.attrs)

   386

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

   387

   388

        # options

   389

        opts = dict(

   390

            selfclosing = self.selfclosing,

   391

            whitespace_sensitive = self.whitespace_sensitive,

   392

        )

   393

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

   394

   395

        # build updated tag

   396

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

   397

   398

    def render_attrs (self) :

   399

        """

   400

            Return the HTML attributes string

   401

   402

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

   403

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

   404

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

   405

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

   406

        """

   407

   408

        return " ".join(

   409

            (

   410

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

   411

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

   412

        )

   413

   414

    def flatten_items (self, indent=1) :

   415

        """

   416

            Flatten our content into a series of indented lines.

   417

   418

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

   419

            [(1, u'5')]

   420

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

   421

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

   422

   423

            Nested :

   424

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

   425

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

   426

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

   427

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

   428

        """

   429

   430

        for item in self.contents :

   431

            if isinstance(item, Renderable) :

   432

                # recursively flatten items

   433

                for line_indent, line in item.flatten() :

   434

                    # indented

   435

                    yield indent + line_indent, line

   436

   437

            elif self.escape :

   438

                # render HTML-escaped raw value

   439

                # escape raw values

   440

                yield indent, saxutils.escape(item)

   441

   442

            else :

   443

                # render raw value

   444

                yield indent, unicode(item)

   445

   446

    def flatten (self) :

   447

        """

   448

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

   449

   450

            Empty tags collapse per default:

   451

   452

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

   453

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

   454

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

   455

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

   456

   457

            Values are indented inside the start tag:

   458

   459

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

   460

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

   461

   462

            Nested tags are further indented:

   463

   464

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

   465

            [(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>')]

   466

   467

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

   468

   469

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

   470

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

   471

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

   472

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

   473

   474

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

   475

   476

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

   477

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

   478

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

   479

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

   480

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

   481

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

   482

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

   483

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

   484

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

   485

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

   486

   487

            Embedded HTML given as string values is escaped:

   488

   489

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

   490

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

   491

   492

            Embedded quotes in attribute values are esacaped:

   493

   494

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

   495

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

   496

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

   497

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

   498

        """

   499

   500

        # optional attr spec

   501

        if self.attrs :

   502

            attrs = " " + self.render_attrs()

   503

   504

        else :

   505

            attrs = ""

   506

   507

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

   508

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

   509

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

   510

   511

        elif not self.contents  :

   512

            # self-closing xml tag

   513

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

   514

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

   515

   516

        elif self.whitespace_sensitive :

   517

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

   518

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

   519

   520

            # render full tag on a single line

   521

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