nhandu 0.1.0__tar.gz

nhandu-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tiago Tresoldi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nhandu-0.1.0/PKG-INFO

@@ -0,0 +1,305 @@
+Metadata-Version: 2.4
+Name: nhandu
+Version: 0.1.0
+Summary: A literate programming tool for Python that weaves code and documentation into scientific reports
+Author-email: Tiago Tresoldi <tiago.tresoldi@lingfil.uu.se>
+License: MIT
+Project-URL: Homepage, https://github.com/tresoldi/nhandu
+Project-URL: Issues, https://github.com/tresoldi/nhandu/issues
+Keywords: literate-programming,scientific-computing,reports,documentation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Documentation
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: mistune>=3.0
+Requires-Dist: pygments>=2.19
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Requires-Dist: types-Pygments; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Provides-Extra: test
+Requires-Dist: numpy>=1.20; extra == "test"
+Requires-Dist: pandas>=2.0; extra == "test"
+Requires-Dist: matplotlib>=3.5; extra == "test"
+Provides-Extra: all
+Requires-Dist: nhandu[dev,test]; extra == "all"
+Dynamic: license-file
+
+
+# Nhandu 
+
+> *Nhandu* (/ɲãndu/, approximately "NYAN-doo") means "spider" in many Tupi-Guarani languages, a fitting name for a tool that weaves together code and documentation, much like Knuth's original vision of literate programming.
+
+**Literate programming for Python: Write executable documents in plain `.py` files.**
+
+Nhandu transforms ordinary Python files with markdown comments into beautiful, reproducible reports. It's lighter than Jupyter, simpler than Quarto, and perfectly git-friendly.
+
+## Why Nhandu?
+
+Contemporary literate programming in Python faces a documentation dilemma:
+
+- **Jupyter notebooks** are powerful but use JSON format (git diffs are messy), require a browser/server, and mix code with metadata
+- **Quarto** is feature-rich but complex, with many configuration options and a learning curve
+- **Pweave** has not been maintained for many years and is incompatible with currently supported Python versions.
+- **Traditional scripts** lack integrated documentation and visualization
+
+Nhandu offers a different solution:
+
+- Write literate programs in **normal `.py` files**: no special format, just comments
+- **Perfect git diffs**: plain text, not JSON, no timestamps, no hashes
+- **No server or browser** required—just run the command
+- **Zero configuration needed**: smart defaults get you started immediately
+- **Python-native**: designed specifically for the Python ecosystem
+
+Nhandu also supports traditional `.md` files with code blocks if you prefer that style.
+
+## Quick Start
+
+### Your First Literate Program
+
+Create a file `analysis.py`:
+
+```python
+#' # My First Analysis
+#'
+#' This is a literate Python program. Lines starting with `#'` are markdown.
+#' Everything else is regular Python code.
+
+import numpy as np
+
+# Generate some data
+data = np.random.normal(0, 1, 1000)
+
+#' ## Results
+#'
+#' Let's compute some statistics:
+
+print(f"Mean: {data.mean():.3f}")
+print(f"Std Dev: {data.std():.3f}")
+
+#' The data looks normally distributed, as expected.
+```
+
+### Generate Your Report
+
+```bash
+nhandu analysis.py
+```
+
+This creates `analysis.html` with your code, output, and nicely formatted documentation, from a plain Python script.
+
+## Features
+
+### Smart Output Capture
+
+Nhandu automatically captures:
+
+- **Print statements** and stdout
+- **Matplotlib plots** (no `plt.show()` needed!)
+- **Expression results** (like Jupyter cells)
+- **Rich objects** (DataFrames render as tables in HTML)
+
+### Syntax Highlighting
+
+Server-side syntax highlighting with 50+ themes via Pygments. Popular themes include: `github-dark` (default), `monokai`, `dracula`, `one-dark`, `vs`, and `solarized-light`.
+
+### Multiple Output Formats
+
+Markdown output can be converted to PDF, Word, LaTeX, and more using [pandoc](https://pandoc.org/) or similar tools. Native HTML support is implemented out-of-the-box.
+
+### Configuration (Optional)
+
+Power users can customize their reports via YAML frontmatter:
+
+```python
+#' ---
+#' title: My Scientific Report
+#' output: html
+#' code_theme: dracula
+#' plot_dpi: 150
+#' ---
+#'
+#' # Introduction
+#' ...
+```
+
+It is also possible to use a configuration file (`nhandu.yaml`) or CLI arguments.
+
+## How It Works
+
+### Literate Python Format (`.py` files)
+
+Nhandu treats Python files specially when they contain markdown comments:
+
+```python
+#' # This is a markdown heading
+#'
+#' Any line starting with #' is treated as **markdown**.
+#' You can use all standard markdown features.
+
+# This is a regular Python comment
+x = 42  # Regular code continues to work normally
+
+#' Back to documentation. Variables persist across blocks:
+
+print(f"x = {x}")
+```
+
+**Hidden code blocks** let you run setup code without cluttering your report:
+
+```python
+#| hide
+import pandas as pd
+import matplotlib.pyplot as plt
+# Configuration code here—runs but doesn't appear in output
+#|
+
+#' Now let's analyze our data:
+# This code WILL appear in the output
+data = pd.read_csv("data.csv")
+```
+
+### Traditional Markdown Format (`.md` files)
+
+You can also use standard markdown files with code blocks:
+
+````markdown
+# My Analysis
+
+Here's some Python code:
+
+```python
+import numpy as np
+x = np.linspace(0, 10, 100)
+print(f"Generated {len(x)} points")
+```
+
+The output will appear in your rendered document. In case of HTML output, any figures are embedded in the file, so that you have a single file to distribute.
+
+````
+
+### Execution Model
+
+- **Shared namespace**: All code blocks share the same Python environment
+- **Sequential execution**: Blocks run in document order
+- **Output capture**: stdout, plots, and expression results are all captured
+- **Rich formatting**: Automatic handling of matplotlib figures, pandas DataFrames, and more
+
+## Examples
+
+Check out the [`examples/`](https://github.com/tresoldi/nhandu/tree/main/examples/) directory for complete demonstrations:
+
+- **[01_hello_world.py](https://github.com/tresoldi/nhandu/tree/main/examples/01_hello_world.py)** - Basic syntax and concepts [[OUTPUT](https://htmlpreview.github.io/?https://github.com/tresoldi/nhandu/blob/main/examples/01_hello_world.py.html)]
+- **[02_data_analysis.py](https://github.com/tresoldi/nhandu/tree/main/examples/02_data_analysis.py)** - Working with data using standard library [[OUTPUT](https://htmlpreview.github.io/?https://github.com/tresoldi/nhandu/blob/main/examples/02_data_analysis.py.html)]
+- **[03_plotting.py](https://github.com/tresoldi/nhandu/tree/main/examples/03_plotting.py)** - Creating visualizations with matplotlib [[OUTPUT](https://htmlpreview.github.io/?https://github.com/tresoldi/nhandu/blob/main/examples/03_plotting.py.html)]
+- **[04_scientific_computation.py](https://github.com/tresoldi/nhandu/tree/main/examples/04_scientific_computation.py)** - Numerical computing with NumPy [[OUTPUT](https://htmlpreview.github.io/?https://github.com/tresoldi/nhandu/blob/main/examples/04_scientific_computation.py.html)]
+- **[05_advanced_report.py](https://github.com/tresoldi/nhandu/tree/main/examples/05_advanced_report.py)** - Complex report with pandas and multiple visualizations [[OUTPUT](https://htmlpreview.github.io/?https://github.com/tresoldi/nhandu/blob/main/examples/05_advanced_report.py.html)]
+
+## Installation & Usage
+
+### Install from PyPI
+
+```bash
+pip install nhandu
+```
+
+### Install from Source
+
+```bash
+git clone https://github.com/tresoldi/nhandu.git
+cd nhandu
+pip install -e .
+```
+
+### Basic Usage
+
+```bash
+nhandu document.py                       # Process literate Python file → document.html
+nhandu document.md                       # Process markdown file → document.html
+nhandu document.py -o report.html        # Specify output file
+nhandu document.py --format md           # Output as markdown
+nhandu document.py --code-theme monokai  # Custom syntax theme
+nhandu document.py --verbose             # Show processing details
+```
+
+### CLI Options
+
+```
+nhandu [OPTIONS] INPUT
+
+Options:
+  -o, --output PATH           Output file path
+  --format {html,md}          Output format (default: html)
+  --config PATH               Configuration file (YAML)
+  --working-dir PATH          Working directory for code execution
+  --timeout SECONDS           Execution timeout
+  --code-theme THEME          Syntax highlighting theme
+  --verbose, -v               Enable verbose output
+  --version                   Show version
+  --help                      Show help message
+```
+
+### Roadmap
+
+Current priorities:
+
+- [ ] Native PDF output support
+- [ ] Inline code evaluation (`<%= expression %>` syntax)
+- [ ] Custom HTML templates (Jinja2)
+- [ ] Watch mode for live development
+- [ ] Rich display for more object types (NumPy arrays, scikit-learn models)
+- [ ] Caching system for faster re-renders
+
+See [issues](https://github.com/tresoldi/nhandu/issues) for more details and to suggest features.
+
+## Project Information
+
+### Citation and Acknowledgements
+
+If you use Nhandu in your research, please cite:
+
+```bibtex
+@software{tresoldi2025nhandu,
+  author = {Tresoldi, Tiago},
+  title = {Nhandu: Literate Programming for Python},
+  year = {2025},
+  publisher = {Department of Linguistics and Philology, Uppsala University},
+  address = {Uppsala, Sweden},
+  url = {https://github.com/tresoldi/nhandu},
+  orcid = {0000-0002-2863-1467}
+}
+```
+
+The earliest stages of development took place within the context of
+the [Cultural Evolution of Texts](https://github.com/evotext/) project, with funding from the
+[Riksbankens Jubileumsfond](https://www.rj.se/) (grant agreement ID:
+[MXM19-1087:1](https://www.rj.se/en/anslag/2019/cultural-evolution-of-texts/)).
+
+### License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+### Acknowledgments
+
+Nhandu is inspired by:
+- Donald Knuth's original [literate programming](https://en.wikipedia.org/wiki/Literate_programming) vision
+- [knitr](https://yihui.org/knitr/) and R Markdown's approach to reproducible research
+- [Jupyter](https://jupyter.org/)'s interactive computing paradigm
+- [Quarto](https://quarto.org/)'s modern scientific publishing tools
+- [Pweave](http://mpastell.com/pweave/)'s Python implementation (though no longer maintained)
+
+Special thanks to the scientific Python community for building the ecosystem that makes tools like this possible.

nhandu-0.1.0/README.md

@@ -0,0 +1,264 @@
+
+# Nhandu 
+
+> *Nhandu* (/ɲãndu/, approximately "NYAN-doo") means "spider" in many Tupi-Guarani languages, a fitting name for a tool that weaves together code and documentation, much like Knuth's original vision of literate programming.
+
+**Literate programming for Python: Write executable documents in plain `.py` files.**
+
+Nhandu transforms ordinary Python files with markdown comments into beautiful, reproducible reports. It's lighter than Jupyter, simpler than Quarto, and perfectly git-friendly.
+
+## Why Nhandu?
+
+Contemporary literate programming in Python faces a documentation dilemma:
+
+- **Jupyter notebooks** are powerful but use JSON format (git diffs are messy), require a browser/server, and mix code with metadata
+- **Quarto** is feature-rich but complex, with many configuration options and a learning curve
+- **Pweave** has not been maintained for many years and is incompatible with currently supported Python versions.
+- **Traditional scripts** lack integrated documentation and visualization
+
+Nhandu offers a different solution:
+
+- Write literate programs in **normal `.py` files**: no special format, just comments
+- **Perfect git diffs**: plain text, not JSON, no timestamps, no hashes
+- **No server or browser** required—just run the command
+- **Zero configuration needed**: smart defaults get you started immediately
+- **Python-native**: designed specifically for the Python ecosystem
+
+Nhandu also supports traditional `.md` files with code blocks if you prefer that style.
+
+## Quick Start
+
+### Your First Literate Program
+
+Create a file `analysis.py`:
+
+```python
+#' # My First Analysis
+#'
+#' This is a literate Python program. Lines starting with `#'` are markdown.
+#' Everything else is regular Python code.
+
+import numpy as np
+
+# Generate some data
+data = np.random.normal(0, 1, 1000)
+
+#' ## Results
+#'
+#' Let's compute some statistics:
+
+print(f"Mean: {data.mean():.3f}")
+print(f"Std Dev: {data.std():.3f}")
+
+#' The data looks normally distributed, as expected.
+```
+
+### Generate Your Report
+
+```bash
+nhandu analysis.py
+```
+
+This creates `analysis.html` with your code, output, and nicely formatted documentation, from a plain Python script.
+
+## Features
+
+### Smart Output Capture
+
+Nhandu automatically captures:
+
+- **Print statements** and stdout
+- **Matplotlib plots** (no `plt.show()` needed!)
+- **Expression results** (like Jupyter cells)
+- **Rich objects** (DataFrames render as tables in HTML)
+
+### Syntax Highlighting
+
+Server-side syntax highlighting with 50+ themes via Pygments. Popular themes include: `github-dark` (default), `monokai`, `dracula`, `one-dark`, `vs`, and `solarized-light`.
+
+### Multiple Output Formats
+
+Markdown output can be converted to PDF, Word, LaTeX, and more using [pandoc](https://pandoc.org/) or similar tools. Native HTML support is implemented out-of-the-box.
+
+### Configuration (Optional)
+
+Power users can customize their reports via YAML frontmatter:
+
+```python
+#' ---
+#' title: My Scientific Report
+#' output: html
+#' code_theme: dracula
+#' plot_dpi: 150
+#' ---
+#'
+#' # Introduction
+#' ...
+```
+
+It is also possible to use a configuration file (`nhandu.yaml`) or CLI arguments.
+
+## How It Works
+
+### Literate Python Format (`.py` files)
+
+Nhandu treats Python files specially when they contain markdown comments:
+
+```python
+#' # This is a markdown heading
+#'
+#' Any line starting with #' is treated as **markdown**.
+#' You can use all standard markdown features.
+
+# This is a regular Python comment
+x = 42  # Regular code continues to work normally
+
+#' Back to documentation. Variables persist across blocks:
+
+print(f"x = {x}")
+```
+
+**Hidden code blocks** let you run setup code without cluttering your report:
+
+```python
+#| hide
+import pandas as pd
+import matplotlib.pyplot as plt
+# Configuration code here—runs but doesn't appear in output
+#|
+
+#' Now let's analyze our data:
+# This code WILL appear in the output
+data = pd.read_csv("data.csv")
+```
+
+### Traditional Markdown Format (`.md` files)
+
+You can also use standard markdown files with code blocks:
+
+````markdown
+# My Analysis
+
+Here's some Python code:
+
+```python
+import numpy as np
+x = np.linspace(0, 10, 100)
+print(f"Generated {len(x)} points")
+```
+
+The output will appear in your rendered document. In case of HTML output, any figures are embedded in the file, so that you have a single file to distribute.
+
+````
+
+### Execution Model
+
+- **Shared namespace**: All code blocks share the same Python environment
+- **Sequential execution**: Blocks run in document order
+- **Output capture**: stdout, plots, and expression results are all captured
+- **Rich formatting**: Automatic handling of matplotlib figures, pandas DataFrames, and more
+
+## Examples
+
+Check out the [`examples/`](https://github.com/tresoldi/nhandu/tree/main/examples/) directory for complete demonstrations:
+
+- **[01_hello_world.py](https://github.com/tresoldi/nhandu/tree/main/examples/01_hello_world.py)** - Basic syntax and concepts [[OUTPUT](https://htmlpreview.github.io/?https://github.com/tresoldi/nhandu/blob/main/examples/01_hello_world.py.html)]
+- **[02_data_analysis.py](https://github.com/tresoldi/nhandu/tree/main/examples/02_data_analysis.py)** - Working with data using standard library [[OUTPUT](https://htmlpreview.github.io/?https://github.com/tresoldi/nhandu/blob/main/examples/02_data_analysis.py.html)]
+- **[03_plotting.py](https://github.com/tresoldi/nhandu/tree/main/examples/03_plotting.py)** - Creating visualizations with matplotlib [[OUTPUT](https://htmlpreview.github.io/?https://github.com/tresoldi/nhandu/blob/main/examples/03_plotting.py.html)]
+- **[04_scientific_computation.py](https://github.com/tresoldi/nhandu/tree/main/examples/04_scientific_computation.py)** - Numerical computing with NumPy [[OUTPUT](https://htmlpreview.github.io/?https://github.com/tresoldi/nhandu/blob/main/examples/04_scientific_computation.py.html)]
+- **[05_advanced_report.py](https://github.com/tresoldi/nhandu/tree/main/examples/05_advanced_report.py)** - Complex report with pandas and multiple visualizations [[OUTPUT](https://htmlpreview.github.io/?https://github.com/tresoldi/nhandu/blob/main/examples/05_advanced_report.py.html)]
+
+## Installation & Usage
+
+### Install from PyPI
+
+```bash
+pip install nhandu
+```
+
+### Install from Source
+
+```bash
+git clone https://github.com/tresoldi/nhandu.git
+cd nhandu
+pip install -e .
+```
+
+### Basic Usage
+
+```bash
+nhandu document.py                       # Process literate Python file → document.html
+nhandu document.md                       # Process markdown file → document.html
+nhandu document.py -o report.html        # Specify output file
+nhandu document.py --format md           # Output as markdown
+nhandu document.py --code-theme monokai  # Custom syntax theme
+nhandu document.py --verbose             # Show processing details
+```
+
+### CLI Options
+
+```
+nhandu [OPTIONS] INPUT
+
+Options:
+  -o, --output PATH           Output file path
+  --format {html,md}          Output format (default: html)
+  --config PATH               Configuration file (YAML)
+  --working-dir PATH          Working directory for code execution
+  --timeout SECONDS           Execution timeout
+  --code-theme THEME          Syntax highlighting theme
+  --verbose, -v               Enable verbose output
+  --version                   Show version
+  --help                      Show help message
+```
+
+### Roadmap
+
+Current priorities:
+
+- [ ] Native PDF output support
+- [ ] Inline code evaluation (`<%= expression %>` syntax)
+- [ ] Custom HTML templates (Jinja2)
+- [ ] Watch mode for live development
+- [ ] Rich display for more object types (NumPy arrays, scikit-learn models)
+- [ ] Caching system for faster re-renders
+
+See [issues](https://github.com/tresoldi/nhandu/issues) for more details and to suggest features.
+
+## Project Information
+
+### Citation and Acknowledgements
+
+If you use Nhandu in your research, please cite:
+
+```bibtex
+@software{tresoldi2025nhandu,
+  author = {Tresoldi, Tiago},
+  title = {Nhandu: Literate Programming for Python},
+  year = {2025},
+  publisher = {Department of Linguistics and Philology, Uppsala University},
+  address = {Uppsala, Sweden},
+  url = {https://github.com/tresoldi/nhandu},
+  orcid = {0000-0002-2863-1467}
+}
+```
+
+The earliest stages of development took place within the context of
+the [Cultural Evolution of Texts](https://github.com/evotext/) project, with funding from the
+[Riksbankens Jubileumsfond](https://www.rj.se/) (grant agreement ID:
+[MXM19-1087:1](https://www.rj.se/en/anslag/2019/cultural-evolution-of-texts/)).
+
+### License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+### Acknowledgments
+
+Nhandu is inspired by:
+- Donald Knuth's original [literate programming](https://en.wikipedia.org/wiki/Literate_programming) vision
+- [knitr](https://yihui.org/knitr/) and R Markdown's approach to reproducible research
+- [Jupyter](https://jupyter.org/)'s interactive computing paradigm
+- [Quarto](https://quarto.org/)'s modern scientific publishing tools
+- [Pweave](http://mpastell.com/pweave/)'s Python implementation (though no longer maintained)
+
+Special thanks to the scientific Python community for building the ecosystem that makes tools like this possible.