Litrepl presubmission

[sergei-mironov]

Submitting Author: Sergei Mironov (@sergei-mironov)
Package Name: Litrepl
One-Line Description of Package: A tool for code snippet evaluation in Markdown/LaTeX documents.
Repository Link (if existing): https://github.com/sergei-mironov/litrepl
EiC: TBD

---

Code of Conduct & Commitment to Maintain Package

• I agree to abide by [pyOpenSci's Code of Conduct][PyOpenSciCodeOfConduct] during the review process and in maintaining my package after should it be accepted.
• I have read and will commit to package maintenance after the review as per the [pyOpenSci Policies Guidelines][Commitment].

Description

Litrepl is a command-line processor for Markdown or LaTeX documents with literate programming code sections. Instructed by its arguments, it evaluates and updates sections via background interpreters. Interpreters can stay active for a read-eval-paste-loop style. The repository includes a Vim plugin to demonstrate editor integration.

Community Partnerships

N/A

Scope

• Please indicate which [category or categories][PackageCategories] this package falls under:

  • Data retrieval
  • Data extraction
  • Data processing/munging
  • Data deposition
  • Data validation and testing
  • Data visualization
  • Workflow automation
  • Citation management and bibliometrics
  • Scientific software wrappers
  • Database interoperability

Domain Specific

N/A

---

• Explain how and why the package falls under these categories (briefly, 1-2 sentences). For community partnerships, check also their specific guidelines as documented in the links above. Please note any areas you are unsure of:
• Who is the target audience and what are the scientific applications of this package?

The target audience comprises both the general public and scientific researchers who are interested in methods for reproducible research. For scientists, the primary applications include running code while editing LaTeX paper sources and checking software documentation for errors.

• Are there other Python packages that accomplish similar things? If so, how does yours differ?

There are many tools associated with literate programming and REPL concepts, such as Jupyter Notebooks, CodeBraid, and PWeave, all the way back to Donald Knuth's WEB.

Litrepl has the following unique properties compared to other modern tools:

• Provides greater flexibility in selecting the programming language for a text document. The programming language interpreters are treated as full-duplex text streams, making them compatible with nearly any popular language console. While Python is the primary supported language (including both IPython and standard Python), there is compatibility with the Bourne Shell family and a custom AI communication interpreter.

  • One obvious limitation of this model is the restriction to text output format. We argue that it can be overcome by side-channel data transfers; for example, a program can save an image to disk and output a file name.

• Provides more flexibility in text document formats. Unlike Jupyter notebooks that use their own document format and CodeBraid, which only works with Markdown, Litrepl uses simple context-free grammars to analyze documents. In addition to Markdown, we support LaTeX, which is popular among scientists. Other formats can be easily integrated using our method.

• Has a significantly smaller code base. According to the SLOC metric, Litrepl comprises less than 2000 lines of Python code, compared to over 10,000 lines for Jupyter Core and Notebooks, and the additional 9,000 for CodeBraid. As of this writing, Litrepl has only two Python dependencies.

  • This minimalism comes at the cost of requiring specific POSIX operating system features. This design choice is driven by POSIX being a well-established standard widely adopted in the open-source community.