1

"""

     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

    71

class Tag (IRenderable) :

    72

    """

    73

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

    74

    75

        Provides various kinds of rendering output

    76

    """

    77

    78

    @staticmethod

    79

    def process_contents (contents) :

    80

        """

    81

            Postprocess contents iterable to return new list.

    82

    83

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

    84

    87

            >>> Tag.process_contents([])

    88

            []

    89

            >>> Tag.process_contents([None])

    90

            []

    91

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

    92

            [u'foo']

    93

        """

    94

    95

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

    96

    97

    @staticmethod

    98

    def process_attrs (attrs) :

    99

        """

   100

            Postprocess attributes.

   101

   102

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

   103

   104

            TODO: only remove one underscore

   105

   106

            >>> Tag.process_attrs(dict())

   107

            {}

   108

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

   109

            {'foo': 'bar'}

   110

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

   111

            {'class': 'bar'}

   112

        """

   113

   114

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

   115

   116

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

   117

        """

   118

            Construct tag with given name/attributes or contents.

   119

   120

            The filtering rules desribed in process_contents/process_attrs apply.

   121

   122

            >>> Tag('foo')

   123

            Tag('foo')

   124

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

   125

            Tag('foo', 'quux')

   126

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

   127

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

   128

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

   129

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

   130

        """

   131

   132

        self.name = name

   133

   134

        # store filtered/processed versions

   135

        self.contents = self.process_contents(contents)

   136

        self.attrs = self.process_attrs(attrs)

   137

   138

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

   139

        """

   140

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

   141

   142

            The filtering rules desribed in process_contents/process_attrs apply.

   143

   144

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

   145

            Tag('foo', 'bar')

   146

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

   147

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

   148

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

   149

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

   150

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

   151

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

   152

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

   153

            Tag('a')

   154

        """

   155

   156

        # merge attrs/contents

   157

        # XXX: new_attrs is not an iterator...

   158

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

   159

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

   160

   161

        # build new tag

   162

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

   163

   164

    @staticmethod

   165

    def format_attr (name, value) :

   166

        """

   167

            Format a single HTML tag attribute

   168

   169

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

   170

            u'name="value"'

   171

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

   172

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

   173

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

   174

            u'xx="1337"'

   175

        """

   176

   177

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

   178

   179

    def render_attrs (self) :

   180

        """

   181

            Return the HTML attributes string

   182

   183

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

   184

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

   185

        """

   186

   187

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

   188

   189

    def render_contents (self, **render_opts) :

   190

        """

   191

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

   192

   193

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

   194

            [u'5']

   195

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

   196

            [u'line1', u'line2']

   197

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

   198

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

   199

        """

   200

   201

        for content in self.contents :

   202

            if isinstance(content, IRenderable) :

   203

                # sub-tags

   204

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

   205

                    yield line

   206

   207

            else :

   208

                # escape raw values

   209

                yield escape(unicode(content))

   210

   211

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

   212

        """

   213

            Render the tag and indented content

   214

   215

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

   216

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

   217

        """

   218

   219

        # render attr string, including preceding space

   220

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

   221

   222

        if self.contents :

   223

            # tag with content

   224

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

   225

   226

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

   227

                yield indent + line

   228

   229

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

   230

   231

        else :

   232

            # singleton tag

   233

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

   234

   235

   236

    def __repr__ (self) :

   237

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

   238

            [

   239

                repr(self.name)

   240

            ] + [

   241

                repr(c) for c in self.contents

   242

            ] + [

   243

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

   244

            ]

   245

        )

   246

   247

class Text (IRenderable) :

   248

    """

   249

        Raw HTML text

   250

    """

   251

   252

    def __init__ (self, line) :

   253

        """

   254

            Initialize to render as the given lines

   255

        """

   256

   257

        self.lines = [line]

   258

   259

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

   260

        return self.lines

   261

   327

class TagFactory (object) :

   328

    """

   329

        Build Tags with names give as attribute names

   330

    """

   331

   332

    def __getattr__ (self, name) :

   333

        """

   334

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

   335

   336

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

   337

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

   338

        """

   339

   340

        return Tag(name)

   341

   342

# pretty names

   343

tag = Tag

   344

tags = TagFactory()

   345

raw = Text

   346

   347

# testing

   348

if __name__ == '__main__' :

   349

    import doctest

   350

   351

    doctest.testmod()

   352