pidgy 2020.3.2.2.52

Conventions for writing code in the notebook.

pidgy literate notebook programming

pip install pidgy

pidgy combines ideas from literate programming and modern software practices to introduce markdown-forward python syntax.
The result is are programs that focus equally literary and computational quality, what results are documents with rich intertextuality between natural language and programming languages.

pidgy is an extension for the interactive python - IPython - shell and an IPython kernel.
It can be used when editting markdown documents and jupyter notebooks in jupyterlab. When pidgy is enabled:

• Write code in markdown, indented and fenced are executed.
• doctests in markdown are tested.
• Include objects in markdown with jinja2 template syntax.
• notebooks can be woven and tangled as documentation and code.
• notebooks can be reproduced as tests.
• ".md.ipynb" is a composite extension that indicates pidgy notebooks primarly written in markdown

The pidgy programming paper.

pidgy is a literate program, meaning it is written narrative first with a secondary capability of being a reusable program.

import pidgy

pidgy command line application

Install the IPython kernels

Install the pidgy kernel so you can use whenever you want.

pidgy kernel install

Load the IPython extension

Otherwise, using the pidgy IPython extension any jupyter notebook.

%load_ext pidgy

Likely, the only other paper of the api you made need is the pidgy.pidgyLoader that allows pidgy documents to be imported as normal source code. The loader searches for notebooks with the ".md.ipynb" extension and adds them to the python import system.

reuse pidgy documents as modules

with pidgy.pidgyLoader():
    import readme
assert readme.__file__.endswith('.md.ipynb')

testing pidgy notebooks.

pidgy is a pytest plugin that can be used to include literature (eg. blog posts, issues, docs) in software test suites.

pytest --nbval--doctest-modules readme.md.ipynb

The plurality of pidgy

Above we've highlight a few outcomes of pidgy programming. pidgy is written as both documentation and source code therefore it can be viewed by the following tools.

• nbviewer
• github pages
• pypi
• readthedocs
• binder
• github actions