Woven text¶
import IPython, pidgy.base, traitlets, jinja2
with pidgy.pidgyLoader(lazy=True): import pidgy.compat.templating
class Weave(pidgy.base.Trait):
Nominally, since the earliest illuminated manuscripts, text is in with type and form. In [literate programming], the weave step explicitly refers to the act of converting an input source into other media forms.
The original [WEB] implementation models the properties of printed documents using the [TeX] document language.
pidgy
shares the same concerns with the form of the published document; in fact, this workflow produces a [PDF] document using the [ReadTheDocs] open-source service with [DVI], Knuth’s original woven target, as an intermediate product[^dvi].
However, prior to printed forms, pidgy
is concerned with the ability to Weave
hypertext and hypermedia forms generated by [literate computing] and composing documents in modern web-browsers. pidgy
uses as a document formatting language; it is chosen because it is the default document language of jupyter
technologies.
The source code for pidgy
is always [Markdown], it provides both the design and computation of an input. In [pidgy]
The Weave
class controls the display of pidgy
outputs, and it relies on the Weave.parent
interactive shell.
environment = traitlets.Instance('jinja2.Environment')
iframe_width = traitlets.Any("100%")
iframe_height = traitlets.Any("""600""")
def post_run_cell(self, result):
if not self.enabled: return
The Weave
step is invoked after a cell or code has been executed.
text = pidgy.util.strip_front_matter(result.info.raw_cell)
lines = text.splitlines() or ['']
if not lines[0].strip(): return
if text.startswith(('http:', "https:")):
lines in text.splitlines()
if all(x.startswith(('http:', "https:")) for x in lines):
return IPython.display.display(*(
IPython.display.IFrame(x, width=self.iframe_width, height=self.iframe_height)
for x in lines
))
pidgy
defers from printing the output if the first line is blank.
display = pidgy.compat.templating.MarkdownDisplay(
body=text, parent=self.parent, template=self.template(text)
)
self.display_manager.append(display)
display.display()
Transclusion with jinja2
templates.¶
jinja2
is a convention for notebooks in the nbconvert
universe. jinja2
is a popular templating engine that makes it possible to put programmatic objects into text.
render_template = traitlets.Bool(True).tag(description=
Weave.render_template
is a toggle for turning transclusion on and off.
)
By default templates are always rendered, but this feature can be turned off.
def template(self, text):
import builtins, operator
return self.environment.from_string(text, globals={
**vars(builtins), **vars(operator),
**(getattr(self.parent, 'user_ns', {})).get('__annotations__', {}),
**getattr(self.parent, 'user_ns', {})})
def render(self, text):
if not self.render_template: return text
import builtins, operator
try:
return self.template(text).render()
except BaseException as Exception: self.parent.showtraceback((type(Exception), Exception, Exception.__traceback__))
return text
display_manager = traitlets.Any()
@traitlets.default('display_manager')
def _default_display_manager(self):
manager = pidgy.compat.templating.DisplayManager(parent=self.parent)
manager.register()
return manager
@traitlets.default('environment')
def _default_environment(self):
More information about the default jinja2
environment may be found in the [compatability module].
return pidgy.compat.templating.environment(self.parent)