polyglot-pmd 0.1.0__tar.gz

polyglot_pmd-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+/.pytest_cache/
+/dist/
+/test-report.html
+**/__pycache__/
+*.py[cod]
+*.egg-info/

polyglot_pmd-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 PMD contributors
+
+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.
+

polyglot_pmd-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: polyglot-pmd
+Version: 0.1.0
+Summary: A reusable Python implementation of the PMD polyglot Markdown notebook format
+Author: PMD contributors
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing :: Markup
+Requires-Python: >=3.10
+Requires-Dist: markdown-it-py<5,>=3.0
+Requires-Dist: pyyaml<7,>=6.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Polyglot PMD
+
+`polyglot-pmd` is a reusable Python implementation of the PMD 0.1 polyglot
+Markdown notebook specification in [`spec.md`](spec.md). It parses and validates
+plain-text `.pmd` documents, resolves their dependency graph, runs every cell in
+an isolated process, and renders a self-contained HTML report.
+
+> PMD cells execute arbitrary code with the privileges of the user running
+> `pmd`. Review a document before running, testing, or rendering it.
+
+## Install
+
+From this checkout:
+
+```console
+python -m pip install -e ./pmd-impl
+pmd check pmd-impl/example.pmd --graph
+pmd run pmd-impl/example.pmd --fresh
+pmd test pmd-impl/example.pmd
+pmd render pmd-impl/example.pmd --to html
+```
+
+Once published:
+
+```console
+python -m pip install polyglot-pmd
+```
+
+Python 3.10 or newer is required. The package depends only on PyYAML and
+markdown-it-py. Language interpreters used by a document must also be installed.
+
+## Library API
+
+```python
+from pathlib import Path
+
+from pmd_notebook import Runner, load, render_html, validate
+
+document = load("analysis.pmd")
+errors = validate(document)
+if errors:
+    raise ValueError("\n".join(errors))
+
+result = Runner().run(document, fresh=True)
+if not result.ok:
+    failed = [cell for cell in result.cells if cell.status == "failed"]
+
+page, render_result = render_html(document, result)
+Path("analysis.html").write_text(page, encoding="utf-8")
+```
+
+The public API exports `parse`, `load`, `validate`, `closure`,
+`topological_order`, `graph_lines`, `Runner`, `Cache`, `execute`, and
+`render_html`, plus the corresponding result dataclasses.
+
+## Context Bindings
+
+Each cell receives `PMD_CELL_OUT` and `PMD_CTX_FILE`. Built-in engines add these
+bindings:
+
+| Engine | Read | Write | Presence check |
+| --- | --- | --- | --- |
+| Python | `ctx.get("key")` or `ctx.key` | `ctx.set("key", value)` or `ctx.key = value` | `ctx.has("key")` |
+| Bash/sh | `ctx_get key` | `ctx_set key 'JSON_VALUE'` | `ctx_has key` |
+| PowerShell | `Get-CtxValue key` | `Set-CtxValue key $value` | `Test-CtxValue key` |
+| SQL | `ctx_get('key')` | `ctx_set('key', 'JSON_VALUE')` | not provided |
+
+Shell reads print JSON, so a stored string includes JSON quotes. SQL uses an
+isolated in-memory SQLite database. Override commands under frontmatter
+`engines.<language>.command`; custom engines still receive the two environment
+variables but must provide their own context helpers.
+
+Write `.png`, `.jpg`, `.jpeg`, `.svg`, `.csv`, `.md`, or any other attachment
+under `PMD_CELL_OUT`. The HTML renderer embeds all files and makes no network
+requests. Python also receives `display.markdown`, `display.csv`,
+`display.image`, and `display.file` convenience methods.
+
+## Caching
+
+Successful dependency results are cached under `PMD_CACHE_DIR`, or
+`~/.cache/polyglot-pmd` by default. Keys include source, attributes, engine
+command, and the resolved transitive context. `--fresh` bypasses reads. A cell
+named by `--cell` always executes; only its dependencies may come from cache.
+Context itself remains scoped to one invocation.
+
+## Optional Workbench
+
+Run `python server.py` and open `http://localhost:8765`. The local workbench is
+not installed as part of the Python package.
+
+## Publishing to PyPI
+
+1. Replace package author metadata if desired and choose the final project URL.
+2. Run `python -m pip install -e ".[dev]"`.
+3. Run `pytest` and `python -m build`.
+4. Check artifacts with `python -m twine check dist/*`.
+5. Upload to TestPyPI, install-test the wheel, then upload to PyPI.
+
+```console
+python -m twine upload --repository testpypi dist/*
+python -m twine upload dist/*
+```
+
+PDF and `.ipynb` are optional PMD render targets and are intentionally not
+implemented. The CLI refuses them clearly instead of silently losing content.
+

polyglot_pmd-0.1.0/README.md

@@ -0,0 +1,106 @@
+# Polyglot PMD
+
+`polyglot-pmd` is a reusable Python implementation of the PMD 0.1 polyglot
+Markdown notebook specification in [`spec.md`](spec.md). It parses and validates
+plain-text `.pmd` documents, resolves their dependency graph, runs every cell in
+an isolated process, and renders a self-contained HTML report.
+
+> PMD cells execute arbitrary code with the privileges of the user running
+> `pmd`. Review a document before running, testing, or rendering it.
+
+## Install
+
+From this checkout:
+
+```console
+python -m pip install -e ./pmd-impl
+pmd check pmd-impl/example.pmd --graph
+pmd run pmd-impl/example.pmd --fresh
+pmd test pmd-impl/example.pmd
+pmd render pmd-impl/example.pmd --to html
+```
+
+Once published:
+
+```console
+python -m pip install polyglot-pmd
+```
+
+Python 3.10 or newer is required. The package depends only on PyYAML and
+markdown-it-py. Language interpreters used by a document must also be installed.
+
+## Library API
+
+```python
+from pathlib import Path
+
+from pmd_notebook import Runner, load, render_html, validate
+
+document = load("analysis.pmd")
+errors = validate(document)
+if errors:
+    raise ValueError("\n".join(errors))
+
+result = Runner().run(document, fresh=True)
+if not result.ok:
+    failed = [cell for cell in result.cells if cell.status == "failed"]
+
+page, render_result = render_html(document, result)
+Path("analysis.html").write_text(page, encoding="utf-8")
+```
+
+The public API exports `parse`, `load`, `validate`, `closure`,
+`topological_order`, `graph_lines`, `Runner`, `Cache`, `execute`, and
+`render_html`, plus the corresponding result dataclasses.
+
+## Context Bindings
+
+Each cell receives `PMD_CELL_OUT` and `PMD_CTX_FILE`. Built-in engines add these
+bindings:
+
+| Engine | Read | Write | Presence check |
+| --- | --- | --- | --- |
+| Python | `ctx.get("key")` or `ctx.key` | `ctx.set("key", value)` or `ctx.key = value` | `ctx.has("key")` |
+| Bash/sh | `ctx_get key` | `ctx_set key 'JSON_VALUE'` | `ctx_has key` |
+| PowerShell | `Get-CtxValue key` | `Set-CtxValue key $value` | `Test-CtxValue key` |
+| SQL | `ctx_get('key')` | `ctx_set('key', 'JSON_VALUE')` | not provided |
+
+Shell reads print JSON, so a stored string includes JSON quotes. SQL uses an
+isolated in-memory SQLite database. Override commands under frontmatter
+`engines.<language>.command`; custom engines still receive the two environment
+variables but must provide their own context helpers.
+
+Write `.png`, `.jpg`, `.jpeg`, `.svg`, `.csv`, `.md`, or any other attachment
+under `PMD_CELL_OUT`. The HTML renderer embeds all files and makes no network
+requests. Python also receives `display.markdown`, `display.csv`,
+`display.image`, and `display.file` convenience methods.
+
+## Caching
+
+Successful dependency results are cached under `PMD_CACHE_DIR`, or
+`~/.cache/polyglot-pmd` by default. Keys include source, attributes, engine
+command, and the resolved transitive context. `--fresh` bypasses reads. A cell
+named by `--cell` always executes; only its dependencies may come from cache.
+Context itself remains scoped to one invocation.
+
+## Optional Workbench
+
+Run `python server.py` and open `http://localhost:8765`. The local workbench is
+not installed as part of the Python package.
+
+## Publishing to PyPI
+
+1. Replace package author metadata if desired and choose the final project URL.
+2. Run `python -m pip install -e ".[dev]"`.
+3. Run `pytest` and `python -m build`.
+4. Check artifacts with `python -m twine check dist/*`.
+5. Upload to TestPyPI, install-test the wheel, then upload to PyPI.
+
+```console
+python -m twine upload --repository testpypi dist/*
+python -m twine upload dist/*
+```
+
+PDF and `.ipynb` are optional PMD render targets and are intentionally not
+implemented. The CLI refuses them clearly instead of silently losing content.
+

polyglot_pmd-0.1.0/example.pmd

@@ -0,0 +1,34 @@
+---
+pmd: "0.1"
+title: "Signal analysis"
+timeout_default: "30s"
+---
+# Signal analysis
+
+A minimal polyglot notebook. Each cell is isolated; data crosses boundaries through ctx.
+
+```python {#generate independent=true tags=demo}
+ctx.values = [3, 8, 13, 21, 34]
+values = ctx.values
+print(f"Generated {len(values)} observations")
+```
+
+
+
+```python {#summarize depends-on=generate}
+values = ctx.values
+average = sum(values) / len(values)
+ctx.average = average
+print(f"Mean signal: {average:.2f}")
+display.markdown(f"## Result\n\nThe mean signal is **{average:.2f}**.", name="summary")
+```
+
+
+
+```python {#verify role=test test-of=summarize}
+assert ctx.average > 0
+print("Average is positive")
+```
+
+
+

polyglot_pmd-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "polyglot-pmd"
+version = "0.1.0"
+description = "A reusable Python implementation of the PMD polyglot Markdown notebook format"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "PMD contributors" }]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Text Processing :: Markup",
+]
+dependencies = [
+  "markdown-it-py>=3.0,<5",
+  "PyYAML>=6.0,<7",
+]
+
+[project.optional-dependencies]
+dev = ["build>=1.2", "pytest>=8", "twine>=5"]
+
+[project.scripts]
+pmd = "pmd_notebook.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pmd_notebook"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/pmd_notebook",
+  "tests",
+  "LICENSE",
+  "README.md",
+  "pyproject.toml",
+  "spec.md",
+  "example.pmd",
+]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]