Coverage for src/lcdoc/mkdocs/lp/__init_

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 run_docs_hooks,

39 split_off_fenced_blocks,

40)

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

45# :docs:known_page_assets

46h = 'header' 2 ctxlppytest

47known_assets = {

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

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

50 'jquery_datatables': {

51 h: [

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

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

54 ]

55 },

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

57}

58# :docs:known_page_assets

61def patch_mkdocs_to_not_crash_on_urls(): 2 ctxlppytest

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

65 except ValueError as ex:

66 if a and '[' in a[0]:

67 try:

68 return self.orig_path_to_url(a[0].split('[', 1)[0], **kw)

69 except:

70 pass

71 except:

72 pass

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

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

76 RPT.orig_path_to_url = RPT.path_to_url 2 ctxlppytest

77 RPT.path_to_url = robust_path_to_url 2 ctxlppytest

80patch_mkdocs_to_not_crash_on_urls() 2 ctxlppytest

83def add_assets_to_page(page, d): 2 ctxlppytest

84 """

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

86 """

87 # support:

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

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

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

99 m = page.lp_page_assets = {'header': {}, 'footer': {}, 'md': {}, 'func': {}} 13 ctxlp|about/coverage.mdlp|about/navigation.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

100 # lp_page_assets_md lp_page_assets_header lp_page_assets_footer

103 # to have them sortable first

108 else:

110

111

112# :docs:hashed_headers

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

114# a block which is the cache key:

115hashed_headers = [

116 'asserts',

117 'body',

118 'chmod',

119 'cwd',

120 'delim',

121 'dir',

122 'expect',

123 'mode',

124 'new_session',

125 'pdb',

126 'post',

127 'pre',

128 'session',

129 'timeout',

130]

131# :docs:hashed_headers

132

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

134

135env_args = {} 2 ctxlppytest

136

137# :docs:eval_parameter_values

138class Eval: 2 ctxlppytest

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

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

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

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

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

144 default = 'always' 2 ctxlppytest

145

146

147# :docs:eval_parameter_values

148

149

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

151

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

153

154

155class LP: 2 ctxlppytest

156 lpnr = 0 2 ctxlppytest

157 blocks_on_page = None 2 ctxlppytest

158 page = None # current page 2 ctxlppytest

159 config = None # the mkdocs config 2 ctxlppytest

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

161 page_initted = False 2 ctxlppytest

162 dflt_evaluation_timeout = 5 2 ctxlppytest

163 on_err_keep_running = False 2 ctxlppytest

164 previous_results = None 2 ctxlppytest

165 cur_results = None 2 ctxlppytest

166 break_on_err = False 2 ctxlppytest

167 fn_lp = None 2 ctxlppytest

168 cov = None # current coverage context 2 ctxlppytest

169 create_coverage_backrefs = False 2 ctxlppytest

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

171 # fmt:off

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

173 py_err = 'Python args parse error' 2 ctxlppytest

174 err_admon = 'LP error' 2 ctxlppytest

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

176 easy_args_err = 'Easy args parse error' 2 ctxlppytest

177 header_parse_err = 'Header_parse_error' 2 ctxlppytest

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

179 dflt_args = None 2 ctxlppytest

180 # fmt:on

181

182 def init_page(): 2 ctxlppytest

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

201

202 def set_page_env_vars(): 2 ctxlppytest

203 # useable in evaluated blocks:

208

209 def configure_from_env(): 2 ctxlppytest

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

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

212 LP.set_page_env_vars() 1 ctxlp

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

214 for k, v in env_vars: 1 ctxlp

215 v = lit_prog.cast(v) 1 ctxlp

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

217 env_args[k] = v 1 ctxlp

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

219

220 def is_lp_block(header_line): 2 ctxlppytest

223

224 def parse_lp_block(lines): 2 ctxlppytest

225 """

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

227

228 {'args': (),

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

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

231 'indent': '',

232 'kwargs': {'addsrc': 1,

233 'asserts': 'Hello',

234 'fmt': 'xt_flat',

235 'session': 'foo'},

236 'lang': 'bash',

237 'nr': 0,

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

239 'echo "Hello World!"\n'

240 '```',

241 'source_id': 'f688f2633ae97209c5c0a5a0fdb93384'}

242 """

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

250 # out and still take result from cache:

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

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

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

263

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

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

266 # (cope = eval only on change)

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

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

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

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

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

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

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

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

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

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

286 spec = {

287 'nr': LP.lpnr,

288 'code': code,

289 'lang': lang,

290 'args': a,

291 'kwargs': kw,

292 'indent': ind * ' ',

293 'source': source,

294 'source_id': sid,

295 'fn': LP.fn_lp,

296 }

300

301 def extract_header_args(lp_header): 2 ctxlppytest

308

309 return (

310 LP.header_parse_err,

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

312 )

313

315

316 def load_previous_results(): 2 ctxlppytest

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

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

325 except Exception as ex:

326 msg = 'Err eval previous result'

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

328 r = {}

332 return app.debug('All eval results found in previous run')

336

337 def handle_skips(blocks): 2 ctxlppytest

338 """

339 Skips are never evaluated, even when missing.

340

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

342 .md for old results

343 """

345

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

351

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

354

358 for c in blocks:

359 skip(c)

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

361 return True

363 s = False

364 for c in blocks:

365 if c == b:

366 s = True

367 continue

368 if s:

369 skip(c)

370 return True

371

373 for c in blocks:

374 if c == b:

375 return True

376 skip(c)

377

379 return True

380

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

388

389 def run_block(spec): 2 ctxlppytest

390 """

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

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

393 """

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

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

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

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

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

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

405 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

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

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

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

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

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

411 kw['mode'] = mode.split(':', 1)[1]

412

414

415 # set the default args, they might be updated from page level params:

416 # if 'param' in LP.fn_lp: breakpoint() # FIXME BREAKPOINT

420 # those kw will parametrize lp.py:run -> add more infos about the spec:

421 # some plugins may need that, why not:

426

427 # When ANY block changed, we re-eval all, except those skipped:

428 # This is usually when editing a page, user may change md but as soon as he

429 # changes lp source we re-eval the whole page. If critical user has to use skips:

431 # is THIS one missing?

434 prev_res = None

435

438

440 # block level eval set?:

442 if not evl_policy.split(':', 1)[1] in spec['source']:

443 app.warning('Skipping block, not eval match', eval=evl_policy)

444 skip(True)

445 else:

446

447 skip(False)

449 skip(False) 3 ctxlp|features/lp/eval.mdlp|features/lp/examples.mdlp|features/lp/sessions.md

451 skip(True)

453 if prev_res: 453 ↛ 454line 453 didn't jump to line 454, because the condition on line 453 was never true2 ctxlp|about/coverage.mdlp|task_runner.md

454 skip(True)

455 else:

456 skip(False) 2 ctxlp|about/coverage.mdlp|task_runner.md