Is the project still active?

[erelsgl]

Because the Readme shows "error".

[contactzen]

Try zen-knit. It is inspired by this project

[mauro3]

I just saw this https://github.com/mwouts/jupytext. However, I have not tried it, so I cannot vouch for it.

[phlummox]

Looks like the last commit by the author, @mpastell, was around 5 years ago –

• 0e43d825e6973f8bc98f0adcfd0dad6d56aa8021

and the last commit by any maintainer was by @abukaj around 4 years ago (as at 2023) –

• 45b56ec60c5badb4e40796178397a4eae5bdddcb

@mpastell is still active on GitHub (e.g. at https://github.com/TwinYields/TwinYields), but not in this repository, so I guess it's abandonware :/

Alternatives

Some alternatives I found or that have been mentioned:

• Jupytext (https://github.com/mwouts/jupytext), mentioned by @mauro3 does look like a (reasonable, but heavyweight?) alternative; it lets you convert back and forth between a Jupyter notebook and other forms (such as markdown with embedded Python blocks to be run). So a combination of https://github.com/jupyter/ and Jupytext would cover most use cases of Pweave, I think.

  Going forward, I think this will be my tool of choice, but only because I don't mind having a swathe of Jupyter-related packages as dependencies. Others might prefer something lighter weight.

• Cog. A somewhat similar project to Pweave (though more limited, I think) is Cog (documentation here). It lets you embed Python fragments in any file between [[[cog ... ]]] delimeters, and inserts the output of that code directly after.

  Dependencies: apparently, none besides Python (>= 3.7, possibly?).

• Knitty. Another similar project (https://github.com/kiwi0fruit/knitty), but it too appears to be abandonware, and has some obnoxious behaviour: it overwrites your user-installed version of pandoc with a version of its own.

• Pytwine. https://github.com/arranstewart/pytwine/. Minimalistic tool, takes in Markdown files containing Python fragments in fenced code blocks (i.e. blocks starting with ```aaa), and replaces them with the output of the code. Seems to be somewhat lacking documentation, though, and the README states that it's "pre-alpha"; but on the plus side, seems to have no other dependencies besides python >= 3.6.

Literate programming-related projects

Some somewhat-related programs, in the "literate programming" space:

• Pycco. https://github.com/pycco-docs/pycco/ (documentation here). Prettily presents code alongside its embedded documentation, as HTML. I haven't tried it out, just saw it exists

• Pollen. https://docs.racket-lang.org/pollen/. Not Python, but Racket – motto is "The book is a program". Some limitations: (a) can't say I actually like the demo output much, though it's apparently very customizable. (b) seems to be aimed at producing HTML output, though apparently other formats (PDF) are possible. Author's apologia: https://docs.racket-lang.org/pollen/quick-tour.html#%28part._.The_end_of_the_beginning%29

Pandoc

Also, there's Pandoc, the mammoth in the document-conversion space, which is designed to let you convert between any number of document formats – but one feature is that it lets you specify filters, plugins written in Haskell, Python, or a bunch of other languages which let you operate in arbitrary ways on Pandoc's internal representation of a document.

There are all sorts of published filters, which let you do things like insert diagrams written in Mermaid syntax, improve the way Pandoc handles numbering, cross references, and bibliographic references. A filter to "Find all code blocks with class python and run them using the python interpreter, printing the results to the console" is left as an exercise of the reader, though I'm sure there's a published equivalent somewhere.

In theory, all of this sounds awesome and ideal, and should let you do absolutely anything you want with almost any sort of document. In practice, I've found it kind of irritating for small, ad-hoc projects, because you (a) you need to install multiple tools – Pandoc and the appropriate filters, and (b) you need to keep any filters you use in lockstep with the version of Pandoc you're using, or they'll disagree about the AST they're working with and produce runtime errors. For a major project, that's fine, versioning the tools you use is just part of the job, but for small, ad hoc projects, I want just one tool which I can install, which does just one thing (execute code blocks), and which changes pretty conservatively (so I don't have to re-learn how to do stuff). But YMMV.

Other potentially useful links

Other links that might be of interest:

• In March 2022, I was looking for a replacement for Pweave, and assessed the alternatives in a Gist, https://gist.github.com/phlummox/7ad2544c5a9968c80a74d835cbdf064c.
• A list by @mrtns that I came across while compiling my own list: https://gist.github.com/mrtns/da998d5fde666d6da26807e1f246246e.
• https://beepb00p.xyz/exobrain/programming/literate.html. @karlicoss's braindump of literate programming and documentation tools, 2019‒2021.
• https://wiki.c2.com/?LiterateProgramming. Page on WikiWikiWeb, the First, the Ur-Wiki,¹ on literate programming.

Footnotes

1. Launched on 25 March 1995 by programmer Ward Cunningham, according to Wikipedia. ↩

[erelsgl]

Thanks a lot for the detailed survey!

[amichuda]

I would also check out quarto, the successor to rmarkdown, which integrates python really well:

https://quarto.org/

[phlummox]

Thanks a lot for the detailed survey!

No problem :) I once again am in need of a tool in the Python-report-generator space, so thought I'd add my findings here.