Coverage for src/lcdoc/mkdocs/lp/__init_

Hot-keys on this page

r m x p toggle line displays

j k next/prev highlighted chunk

0 (zero) top of page

1 (one) first highlighted chunk

1"""

2## Literate Programming

4[org babel](https://orgmode.org/worg/org-contrib/babel/intro.html) inspired dyanamic code evaluation plugin.

6```bash

7 ```<bash|python> lp <header args>

8 echo "Hello World"

9 ```

10```

12Details see [here](../features/lp/)

14"""

15import contextlib 2 ctxlppytest

16import hashlib 2 ctxlppytest

17import json 2 ctxlppytest

18import traceback 2 ctxlppytest

19from ast import literal_eval 2 ctxlppytest

20from functools import partial 2 ctxlppytest

21from pprint import pformat 2 ctxlppytest

23import coverage 2 ctxlppytest

25# Required for urls in bodies of lp plugs like http://foo.bar[blank] in flowcharts.js:

26# Would crash mkdocs:

27from mkdocs.structure.pages import _RelativePathTreeprocessor as RPT 2 ctxlppytest

29from lcdoc import lp as lit_prog 2 ctxlppytest

30from lcdoc.mkdocs import markdown 2 ctxlppytest

31from lcdoc.mkdocs.tools import ( 2 ctxlppytest

32 MDPlugin,

33 app,

34 config_options,

35 link_assets,

36 now,

37 page_dir,

38 split_off_fenced_blocks,

39)

40from lcdoc.tools import dirname, exists, os, project, read_file, sys, write_file 2 ctxlppytest

44# :docs:known_page_assets

45h = 'header' 2 ctxlppytest

46known_assets = {

47 'd3': {h: '//unpkg.com/d3@6/dist/d3.min.js'},

48 'jquery': {h: '//code.jquery.com/jquery-latest.js'},

49 'jquery_datatables': {

50 h: [

51 '//cdn.datatables.net/1.11.2/js/jquery.dataTables.min.js',

52 #'//cdn.datatables.net/1.11.2/css/jquery.dataTables.min.css',

53 ]

54 },

55 'raphael': {h: '//cdnjs.cloudflare.com/ajax/libs/raphael/2.3.0/raphael.min.js'},

56}

57# :docs:known_page_assets

60def patch_mkdocs_to_not_crash_on_urls(): 2 ctxlppytest

61 def robust_path_to_url(self, *a, **kw): 2 ctxlppytest

64 except:

65 app.error('path_to_url parsing error', args=a, **kw)

66 return 'http://unparsable_url?url=%s' % str(a)

68 RPT.orig_path_to_url = RPT.path_to_url 2 ctxlppytest

69 RPT.path_to_url = robust_path_to_url 2 ctxlppytest

72patch_mkdocs_to_not_crash_on_urls() 2 ctxlppytest

75def add_assets_to_page(page, d): 2 ctxlppytest

76 """

77 d like {'md': {'mermaid': ..., 'header': {'chartist': ...}, 'footer': ...}

78 """

79 # support:

80 # page_assets = { 'mode': ['jquery'], 'footer': {...

82 return [add_assets_to_page(page, i) for i in d] 1 ctxlp|features/lp/plugs/lightbox/index.md

86 app.die('Unknown asset', asset=d, json={'known': known_assets})

91 m = page.lp_page_assets = {'header': {}, 'footer': {}, 'md': {}, 'func': {}} 12 ctxlp|about/coverage.mdlp|features/lp/examples.mdlp|features/lp/plugs/chart/index.mdlp|features/lp/plugs/chartist/index.mdlp|features/lp/plugs/drawio/index.mdlp|features/lp/plugs/flowchart/index.mdlp|features/lp/plugs/kroki/index.mdlp|features/lp/plugs/lightbox/index.mdlp|features/lp/plugs/markmap/index.mdlp|features/lp/plugs/mermaid/index.mdlp|features/lp/syntax.mdlp|index.md

92 # lp_page_assets_md lp_page_assets_header lp_page_assets_footer

95 # to have them sortable first

100 else:

102

103

104# :docs:hashed_headers

105# those header params will prevent to use caching when changed, they go into the hash of

106# a block which is the cache key:

107hashed_headers = [

108 'asserts',

109 'body',

110 'chmod',

111 'cwd',

112 'delim',

113 'dir',

114 'expect',

115 'mode',

116 'new_session',

117 'pdb',

118 'post',

119 'pre',

120 'session',

121 'timeout',

122]

123# :docs:hashed_headers

124

125lp_res_ext = '.lp.py' # when opened the ide will format 2 ctxlppytest

126

127env_args = {} 2 ctxlppytest

128

129# :docs:eval_parameter_values

130class Eval: 2 ctxlppytest

131 never = 'never' # not even when not cached 2 ctxlppytest

132 always = 'always' # even when cached. except skipped 2 ctxlppytest

133 on_change = 'on_change' # only when block changed 2 ctxlppytest

134 on_page_change = 'on_page_change' # whan any block (md irrelevant) on page changed 2 ctxlppytest

135 # Default: anything else would confuse user. e.g. cat <filename> would show old still when it changed but no lp change involved:

136 default = 'always' 2 ctxlppytest

137

138

139# :docs:eval_parameter_values

140

141

142eval_modes = {k for k in dir(Eval) if not k[0] == '_'} 2 ctxlppytest

143

144int_env_vars = ['DOCU', 'DOCU_FILE'] 2 ctxlppytest

145

146

147class LP: 2 ctxlppytest

148 lpnr = 0 2 ctxlppytest

149 blocks_on_page = None 2 ctxlppytest

150 page = None # current page 2 ctxlppytest

151 config = None # the mkdocs config 2 ctxlppytest

152 config_lp_plugin = None # the mkdocs lp plugin config 2 ctxlppytest

153 page_initted = False 2 ctxlppytest

154 dflt_evaluation_timeout = 5 2 ctxlppytest

155 on_err_keep_running = False 2 ctxlppytest

156 previous_results = None 2 ctxlppytest

157 cur_results = None 2 ctxlppytest

158 break_on_err = False 2 ctxlppytest

159 fn_lp = None 2 ctxlppytest

160 cov = None # current coverage context 2 ctxlppytest

161 create_coverage_backrefs = False 2 ctxlppytest

162 docs_repo_base = '' # e.g. 'https://github.com/AXGKl/docutools/docs' 2 ctxlppytest

163 # fmt:off

164 texc = '!!! error "LP exception"' 2 ctxlppytest

165 py_err = 'Python args parse error' 2 ctxlppytest

166 err_admon = 'LP error' 2 ctxlppytest

167 interrupted = 'LP continuation stopped by user' 2 ctxlppytest

168 easy_args_err = 'Easy args parse error' 2 ctxlppytest

169 header_parse_err = 'Header_parse_error' 2 ctxlppytest

170 # page global args. base from env. settable via ```page lp foo=bar

171 dflt_args = None 2 ctxlppytest

172 # fmt:on

173

174 def init_page(): 2 ctxlppytest

175 """run only at first fc block found"""

193

194 def set_page_env_vars(): 2 ctxlppytest

195 # useable in evaluated blocks:

200

201 def configure_from_env(): 2 ctxlppytest

202 """run at startup (on_configure hook)"""

203 s = {'LP_', 'lp_'} 1 ctxlp

204 LP.set_page_env_vars() 1 ctxlp

205 env_vars = [(f[3:], os.environ[f]) for f in os.environ if f[:3] in s] 1 ctxlp

206 for k, v in env_vars: 1 ctxlp

207 v = lit_prog.cast(v) 1 ctxlp

208 app.debug('From environ', key=k, value=v) 1 ctxlp

209 env_args[k] = v 1 ctxlp

210 LP.stats['LP_env_vars'] = len(env_args) 1 ctxlp

211

212 def is_lp_block(header_line): 2 ctxlppytest

215

216 def parse_lp_block(lines): 2 ctxlppytest

217 """

218 Done for ALL LP blocks on the page, BEFORE the first block is evaluated!

219

220 {'args': (),

221 'code': ['echo "Hello World!"'],

222 'fn': '/home/gk/repos/docutools/docs/features/literate_programming.md.lp',

223 'indent': '',

224 'kwargs': {'addsrc': 1,

225 'asserts': 'Hello',

226 'fmt': 'xt_flat',

227 'session': 'foo'},

228 'lang': 'bash',

229 'nr': 0,

230 'source': '```bash lp addsrc=1 asserts=Hello fmt=xt_flat session=foo\n'

231 'echo "Hello World!"\n'

232 '```',

233 'source_id': 'f688f2633ae97209c5c0a5a0fdb93384'}

234 """

241 # for the hash we take the undindent version, i.e. we allow to shift it in /

242 # out and still take result from cache:

246 # if "rm foobar" in source: breakpoint() # FIXME BREAKPOINT

248 # support "bash lp:mermaid" ident to "bash lp mode=mermaid":

249 # also: lp:kroki:plantuml -> mode = 'kroki:plantuml' then, lp will import kroki.

255

256 # special param pointing to a file. when mtime changes, then hash must change:

257 # this way we can cope with changes of e.g. drawio files, or ext plantuml diag src

258 # (cope = eval only on change)

261 if not src[0] == '/': 261 ↛ 263line 261 didn't jump to line 263, because the condition on line 261 was never false2 ctxlp|features/lp/plugs/column/index.mdlp|features/lp/plugs/flowchart/index.md

262 src = dirname(LP.fn_lp) + '/' + src 2 ctxlp|features/lp/plugs/column/index.mdlp|features/lp/plugs/flowchart/index.md

263 kw['abs_src'] = src # convenience for plugins 2 ctxlp|features/lp/plugs/column/index.mdlp|features/lp/plugs/flowchart/index.md

264 if exists(src): 264 ↛ 267line 264 didn't jump to line 267, because the condition on line 264 was never false2 ctxlp|features/lp/plugs/column/index.mdlp|features/lp/plugs/flowchart/index.md

265 src += ':' + str(os.stat(src).st_mtime) 2 ctxlp|features/lp/plugs/column/index.mdlp|features/lp/plugs/flowchart/index.md

266 # these header args may change eval result, need to go into the hash:

272 # if lang == 'page': breakpoint() # FIXME BREAKPOINT

273 # eval result of same block could change, sideeffects in other evals in between:

275 sid += '_' 2 ctxlp|features/lp/examples.mdlp|features/lp/plugs/kroki/index.md

276 # if 'Alice' in str(code): breakpoint() # FIXME BREAKPOINT

277 spec = {

278 'nr': LP.lpnr,

279 'code': code,

280 'lang': lang,

281 'args': a,

282 'kwargs': kw,

283 'indent': ind * ' ',

284 'source': source,

285 'source_id': sid,

286 'fn': LP.fn_lp,

287 }

291

292 def extract_header_args(lp_header): 2 ctxlppytest

299

300 return (

301 LP.header_parse_err,

302 {LP.py_err: res[0], LP.easy_args_err: res[1], 'header': H},

303 )

304

306

307 def load_previous_results(): 2 ctxlppytest

309 # If no change we don't write it, so

310 # mkdocs wont rebuild (i.e. prevent looping on serve)

316 except Exception as ex:

317 msg = 'Err eval previous result'

318 app.warning(msg, exc=ex, content_start=r[:100], fn=fn)

319 r = {}

323 return app.debug('All eval results found in previous run') 1 ctxlp|index.md

327

328 def handle_skips(blocks): 2 ctxlppytest

329 """

330 Skips are never evaluated, even when missing.

331

332 Returning true when there are skips - telling LP that we need to check the

333 .md for old results

334 """

336

341 app.die('Not understood skip statment', unknown=n, allowed=h)

342

344 b['kwargs']['skip_this'] = True

345

349 for c in blocks:

350 skip(c)

351 b['kwargs'].pop('skip_this')

352 return True

354 s = False

355 for c in blocks:

356 if c == b:

357 s = True

358 continue

359 if s:

360 skip(c)

361 return True

362

364 for c in blocks:

365 if c == b:

366 return True

367 skip(c)

368

370 return True

371

372 def run_blocks(lp_blocks, raise_on_errs=None): 2 ctxlppytest

379

380 def run_block(spec): 2 ctxlppytest

381 """

382 fnd: '/home/gk/repos/blog/docs/ll/vim/vim.md'

383 block.keys: ['nr', 'code', 'lang', 'args', 'kwargs', 'indent', 'source', 'source_id', 'fn']

384 """

387 # handle page level parametrization already here - this is never skipped:

388 # we allow change of default args mid-page:

390 # if 'lp:page' in str(spec): breakpoint() # FIXME BREAKPOINT

393 kw.pop('mode') 3 ctxlp|features/lp/eval.mdlp|features/lp/examples.mdlp|features/lp/sessions.md

394 is_page = True 3 ctxlp|features/lp/eval.mdlp|features/lp/examples.mdlp|features/lp/sessions.md

395 LP.stats['blocks_page'] += 1 3 ctxlp|features/lp/eval.mdlp|features/lp/examples.mdlp|features/lp/sessions.md

396 m = {k: v for k, v in kw.items() if not k.startswith('skip_')} 3 ctxlp|features/lp/eval.mdlp|features/lp/examples.mdlp|features/lp/sessions.md

397 LP.dflt_args.update(m) 3 ctxlp|features/lp/eval.mdlp|features/lp/examples.mdlp|features/lp/sessions.md

398 kw['silent'] = True 3 ctxlp|features/lp/eval.mdlp|features/lp/examples.mdlp|features/lp/sessions.md

399 kw['lang'] = 'bash' 3 ctxlp|features/lp/eval.mdlp|features/lp/examples.mdlp|features/lp/sessions.md

400 kw['addsrc'] = False 3 ctxlp|features/lp/eval.mdlp|features/lp/examples.mdlp|features/lp/sessions.md

401 if ':' in mode: 401 ↛ 402line 401 didn't jump to line 402, because the condition on line 401 was never true3 ctxlp|features/lp/eval.mdlp|features/lp/examples.mdlp|features/lp/sessions.md