css/lib/python/cs/html.py at main · cameron-simpson/css · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
#!/usr/bin/python
#
# Useful HTML facilities.
#       - Cameron Simpson <cs@cskk.id.au>
#

from __future__ import absolute_import

DISTINFO = {
    'description': "easy HTML and XHTML transcription",
    'keywords': ["python2", "python3"],
    'classifiers': [
        "Programming Language :: Python",
        "Programming Language :: Python :: 2",
        "Programming Language :: Python :: 3",
    ],
    'install_requires': ['cs.logutils', 'cs.py3'],
}

from io import StringIO
import re
import sys
from cs.logutils import warning
from cs.py3 import StringTypes
from cs.x import X

# Characters safe to transcribe unescaped.
re_SAFETEXT = re.compile(r'[^<>&]+')
# Characters safe to use inside "" in tag attribute values.
# See HTML 4.01 section 3.2.2
re_SAFETEXT_DQ = re.compile(r'[-a-zA-Z0-9._:\s/;(){}%]+')

# convenience wrappers
A = lambda *tok: ['A'] + list(tok)
B = lambda *tok: ['B'] + list(tok)
NBSP = ['&nbsp;']
TH = lambda *tok: ['TH'] + list(tok)
TD = lambda *tok: ['TD'] + list(tok)
TR = lambda *tok: ['TR'] + list(tok)
META = lambda name, content: ['META', {'name': name, 'content': content}]
LINK = lambda rel, href, **kw: ['LINK',
                                dict([('rel', rel), ('href', href)] + list(kw.items()))]
SCRIPT_SRC = lambda src, ctype='text/javascript': [ 'SCRIPT', {'src': src, 'type': ctype}]

comment = lambda *tok: ['<!--'] + list(tok)
entity = lambda entity_name: [ '&' + entity_name + ';' ]

def page_HTML(title, *tokens, **kw):
  ''' Convenience function returning an '<HTML>' token for a page.
      Keyword parameters:
      `content_type`: "http-equiv" Content-Type, default: "text/html; charset=UTF-8".
      `head_tokens`: optional extra markup tokens for the HEAD section.
      `body_attrs`: optional attributes for the BODY section tag.
  '''
  content_type = kw.pop('content_type', 'text/html; charset=UTF-8')
  head_tokens = kw.pop('head_tokens', ())
  body_attrs = kw.pop('body_attrs', {})
  if kw:
    raise ValueError("unexpected keywords: %r" % (kw,))
  body = ['BODY', body_attrs]
  body.extend(tokens)
  head = ['HEAD',
          ['META', {
              'http-equiv': 'Content-Type', 'content': content_type}], '\n',
          ['TITLE', title], '\n',
          ]
  head.extend(head_tokens)
  return ['HTML',
          head,
          body,
          ]

def attrquote(s):
  ''' Quote a string for use as a tag attribute.
      See HTML 4.01 section 3.2.2.
  '''
  qsv = ['"']
  offset = 0
  while offset < len(s):
    m = re_SAFETEXT_DQ.search(s, offset)
    if not m:
      break
    for c in s[offset:m.start()]:
      qsv.extend( ('&#', str(ord(c)), ';') )
    qsv.append(m.group())
    offset = m.end()
  qsv.append(s[offset:])
  qsv.append('"')
  return ''.join(qsv)

def nbsp(s):
  ''' Generator yielding tokens to translate all whitespace in `s` into &nbsp; entitites.
      Example:
        list(nobr('a b  cd')) ==> ['a', ['&nbsp;'], 'b', ['&nbsp;'], ['&nbsp;'], 'cd']
  '''
  wordchars = []
  for c in s:
    if c.isspace():
      if wordchars:
        yield ''.join(wordchars)
        wordchars = []
      yield NBSP
    else:
      wordchars.append(c)
  if wordchars:
    yield ''.join(wordchars)

def tok2s(*tokens):
  ''' Transcribe tokens to a string, return the string.
      Trivial wrapper for transcribe().
  '''
  return ''.join(transcribe(*tokens))

def puttok(fp, *tokens):
  ''' Transcribe tokens as HTML text to the file `fp`.
      Trivial wrapper for transcribe().
  '''
  for s in transcribe(*tokens):
    fp.write(s)

def transcribe(*tokens):
  ''' Transcribe tokens as HTML text and yield text portions as generated.
      A token is a string, a sequence or a Tag object.
      A string is safely transcribed as flat text.
      A sequence has:
        [0] the tag name
        [1] optionally a mapping of attribute values
        Further elements are tokens contained within this token.
  '''
  return _transcribe(False, *tokens)

def transcribe_s(*tokens):
  ''' Transcribe tokens as HTML text and return the text.
      Convenience wrapper for transcribe().
  '''
  return ''.join(transcribe(*tokens))

def xtranscribe(*tokens):
  ''' Transcribe tokens as XHTML text and yield text portions as generated.
      A token is a string, a sequence or a Tag object.
      A string is safely transcribed as flat text.
      A sequence has:
        [0] the tag name
        [1] optionally a mapping of attribute values
        Further elements are tokens contained within this token.
  '''
  return _transcribe(True, *tokens)

def xtranscribe_s(*tokens):
  ''' Transcribe tokens as XHTML text and return the text.
      Convenience wrapper for xtranscribe().
  '''
  return ''.join(xtranscribe(*tokens))

def _transcribe(is_xhtml, *tokens):
  ''' Transcribe tokens as HTML or XHTML text and yield text portions as generated.
      A token is a string, a sequence or a Tag object.
      A string is safely transcribed as flat text.
      A sequence has:
        [0] the tag name
        [1] optionally a mapping of attribute values
        Further elements are tokens contained within this token.
  '''
  for tok in tokens:
    if isinstance(tok, StringTypes):
      for txt in transcribe_string(tok):
        yield txt
      continue
    if isinstance(tok, (int, float)):
      yield str(tok)
      continue
    # token
    try:
      tag = tok.tag
      attrs = tok.attrs
    except AttributeError:
      # not a preformed token with .tag and .attrs
      # [ "&ent;" ] is an HTML character entity
      if len(tok) == 1 and tok[0].startswith('&'):
        yield tok[0]
        continue
      # raw array [ tag[, attrs][, tokens...] ]
      tok = list(tok)
      tag = tok.pop(0)
      if len(tok) > 0 and hasattr(tok[0], 'keys'):
        attrs = tok.pop(0)
      else:
        attrs = {}
    if tag == '<!--':
      yield '<!--'
      buf = StringIO()
      for t in tok:
        if not isinstance(t, StringTypes):
          raise ValueError("invalid non-string inside \"<!--\" comment: %r" % (t,))
        buf.write(t)
      comment_text = buf.getvalue()
      buf.close()
      if '-->' in comment_text:
        raise ValueError("invalid \"-->\" inside \"<!--\" comment: %r" % (comment,))
      yield comment_text
      yield '-->'
      continue
    # HTML is case insensitive and XHTML has lower case tags
    tag = tag.lower()
    is_single = tag in ('br', 'img', 'hr', 'link', 'meta', 'input')
    is_SCRIPT = (tag.lower() == 'script')
    if is_SCRIPT:
      if 'language' not in [a.lower() for a in attrs.keys()]:
        attrs['language'] = 'JavaScript'
      if 'src' in attrs:
        if tok:
          warning("<script> with src=, discarding internal tokens: %r", tokens)
          tok = ()
    yield '<'
    yield tag
    for k in sorted(attrs.keys()):
      v = attrs[k]
      yield ' '
      yield k
      if is_xhtml and v is None:
        v = k
      if v is not None:
        yield '='
        yield attrquote(str(v))
    if is_xhtml and is_single:
      yield '/'
    yield '>'
    # protect inline SCRIPT source code with HTML comments
    if is_SCRIPT and 'src' not in attrs:
      yield "<!--\n"
    for txt in _transcribe(is_xhtml, *tok):
      if is_single:
        error("content inside singleton tag %r!", tag)
        break
      yield txt
    if is_SCRIPT and 'src' not in attrs:
      yield "\n-->"
    if not is_single:
      yield '</'
      yield tag
      yield '>'

def quote(s, safe_re=None):
  ''' Return transcription of string in HTML safe form.
  '''
  return ''.join(transcribe_string(s))

def puttext(fp, s, safe_re=None):
  ''' Transcribe plain text in HTML safe form to the file `fp`.
      Trivial wrapper for transcribe_string().
  '''
  for chunk in transcribe_string(s, safe_re=safe_re):
    fp.write(chunk)

def transcribe_string(s, safe_re=None):
  ''' Generator yielding HTML text chunks transcribing the string `s`.
  '''
  if safe_re is None:
    safe_re = re_SAFETEXT
  while len(s):
    m = safe_re.match(s)
    if m:
      safetext = m.group(0)
      yield safetext
      s = s[len(safetext):]
    else:
      if s[0] == '<':
        yield '&lt;'
      elif s[0] == '>':
        yield '&gt;'
      elif s[0] == '&':
        yield '&amp;'
      else:
        yield '&#%d;' % ord(s[0])
      s = s[1:]