pypresent 0.1.0__tar.gz

pypresent-0.1.0/.gitignore

@@ -0,0 +1,221 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# pypresent: built decks, all rebuilt by demos/build.sh
+demos/out/

pypresent-0.1.0/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the
+versions are [semantic](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-11-07
+
+The first release. It began as a single `present.py` that built one lecture's
+deck, and is now a package.
+
+### Added
+
+- **Markdown decks.** A `.md` file is a source in its own right: headings and
+  `---` lines cut it into slides, and a `key: value` front matter block declares
+  the deck the way a notebook's first cell does.
+- **Markdown output.** `--format md` writes the same slides as a markdown
+  document — a readable handout that `pypresent` can read straight back in.
+  Pictures are data URIs by default, or written out beside the file with
+  `render_markdown(assets=…)`.
+- **Themes.** Every colour, size and font is a named token; the stylesheet is
+  written entirely in terms of them. A theme is a name, a `.toml`/`.json`/`.yaml`
+  file, a dict, or a `Theme` — with `base` to build on a built-in. Four ship:
+  `warm`, `office`, `dark`, `slate`. `pypresent themes NAME` prints one as a file
+  you can edit.
+- **`pypresent check`** as a command of its own, so drift can be found without
+  rendering.
+- **`notes()`**, and `notes=` on a slide: speaker notes that stay in the deck and
+  never reach the slide.
+- **`kernel="auto"`** (the default): a notebook is executed by the very
+  interpreter `pypresent` is installed in, so a fresh virtualenv and a CI runner
+  both work with no kernelspec registered anywhere.
+- Images beyond PNG — jpg, gif, webp, svg — embedded by their real type.
+- A test suite, a demo folder, and CI on Linux, macOS and Windows.
+
+### Removed
+
+- **`audit`.** It opened the built deck in headless Chrome to report which
+  slides the renderer had shrunk to fit. That is one subprocess, one browser to
+  have installed and one injected probe script, to say something you see the
+  moment you open the deck. The shrinking itself is unchanged — an over-full
+  slide still scales rather than overflowing — and with it went `fit_floor`,
+  `sparse`, `audit_size` and `chrome` on a `Presentation`.
+
+### Changed
+
+- `present.py` is now the `pypresent` package, and the tool is `pypresent`
+  rather than `python present.py`.
+- `lecture=` is now `source=`, since the notebook being quoted need not be a
+  lecture. `lecture=` still works, and a deck whose declaration was stored under
+  the old name still loads.
+- The command's first positional is the deck, and it may be a `.md`.
+- **`build` runs the source notebook as well, by default.** The deck quotes what
+  the source printed, so a build that does not re-run it can put new code beside
+  an old number; that was opt-in behind `--source` and is now what a build is.
+  The two runs are taken away rather than added: `--skip-source-run` and
+  `--skip-slides-run` replace `--source` and `--no-run`, and passing both
+  executes nothing. In Python, `build(run=…, source=…)` is now
+  `build(run_source=…, run_slides=…)`.
+- `export --mode slide --format md` now uses this package's own renderer rather
+  than nbconvert, so it writes the slides rather than the notebook.
+- `-o` on the command line is relative to the shell's directory rather than the
+  deck's.
+
+### Fixed
+
+- `trim={'head': n, 'tail': n}` on a block that already fits no longer truncates
+  it and drops the tail.
+- The cell that declares the presentation is no longer rendered as a slide of its
+  own source, and `check` no longer complains that it declares no slide.
+- **A non-UTF-8 terminal no longer breaks a build.** A deck carries arrows, a
+  middle dot and often Hebrew, and a redirected stdout under a locale that
+  cannot encode them - a pipe on a Windows runner, a cron job with `LC_ALL=C` -
+  made `pypresent` die printing its own progress line. Messages now fall back to
+  a plain-text equivalent (`·` to `-`, `…` to `...`); the deck file itself was
+  always written as UTF-8 and is unchanged. CI runs the suite under `LC_ALL=C`
+  so this is caught in seconds rather than in the Windows job.
+
+[Unreleased]: https://github.com/Barakkol33/pypresent/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Barakkol33/pypresent/releases/tag/v0.1.0

pypresent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Barak Kolnik
+
+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.

pypresent-0.1.0/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.5
+Name: pypresent
+Version: 0.1.0
+Summary: Slides from a Jupyter notebook, quoting its code and output, as one self-contained HTML file.
+Project-URL: Homepage, https://github.com/Barakkol33/pypresent
+Project-URL: Documentation, https://github.com/Barakkol33/pypresent/blob/main/docs/README.md
+Project-URL: Source, https://github.com/Barakkol33/pypresent
+Project-URL: Issues, https://github.com/Barakkol33/pypresent/issues
+Project-URL: Changelog, https://github.com/Barakkol33/pypresent/blob/main/CHANGELOG.md
+Author-email: Barak Kolnik <barakkol@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: html,jupyter,markdown,notebook,presentation,reveal,slides
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Framework :: Jupyter
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics :: Presentation
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: ipykernel>=6.0; extra == 'dev'
+Requires-Dist: nbclient>=0.9; extra == 'dev'
+Requires-Dist: nbconvert>=7.0; extra == 'dev'
+Requires-Dist: nbformat>=5.9; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: pyyaml>=6.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: jupyter
+Requires-Dist: ipykernel>=6.0; extra == 'jupyter'
+Requires-Dist: nbclient>=0.9; extra == 'jupyter'
+Requires-Dist: nbconvert>=7.0; extra == 'jupyter'
+Requires-Dist: nbformat>=5.9; extra == 'jupyter'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# pypresent
+
+**The notebook is the slides.** `pypresent` turns a Jupyter notebook into one
+self-contained HTML deck: no server, no build folder, no `_files/` directory,
+nothing to upload. One file you can mail, open from a memory stick, or commit
+next to the notebook it came from.
+
+And the deck never pastes the code — it quotes the lecture, at build time.
+
+[![CI](https://github.com/Barakkol33/pypresent/actions/workflows/ci.yml/badge.svg)](https://github.com/Barakkol33/pypresent/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/pypresent.svg)](https://pypi.org/project/pypresent/)
+[![Python](https://img.shields.io/pypi/pyversions/pypresent.svg)](https://pypi.org/project/pypresent/)
+[![License](https://img.shields.io/pypi/l/pypresent.svg)](LICENSE)
+
+```bash
+pip install pypresent            # rendering only - no Jupyter needed
+pip install "pypresent[jupyter]" # and executing the notebooks
+```
+
+## The point of it
+
+A lecture notebook and its deck usually drift apart: the code is pasted onto a
+slide, the number beside it was true three runs ago, and the chart is a PNG
+somebody exported in March.
+
+`pypresent` never pastes. A cell in the lecture is named with a comment, and is
+otherwise an ordinary cell that knows nothing about any deck — here `tokenize`
+came from a cell above it:
+
+```python
+# slide: counts
+from collections import Counter
+
+CORPUS = 'the cat sat on the mat and the cat sat again'
+counts = Counter(tokenize(CORPUS))
+print(counts.most_common(3))
+print(f'{len(counts)} distinct tokens')
+```
+
+Run the lecture and it prints:
+
+```
+[('cat', 2), ('sat', 2), ('mat', 1)]
+6 distinct tokens
+```
+
+The deck then quotes that cell **by name**, and copies nothing:
+
+```python
+slide('''
+## And what it printed
+
+- `result()` is the cell's own output, not a number typed twice
+- re-run the lecture and the slide changes with it
+''',
+    code('counts', drop=['from collections']),
+    result('counts'),
+    layout='split',
+)
+```
+
+Then:
+
+```bash
+pypresent build                  # run the lecture, run the deck, write one html file
+```
+
+which is this slide — the listing is the code that ran, and the numbers under it
+are the ones it printed:
+
+![A slide: two bullets on the left; on the right the quoted listing, and under it a lighter box holding the output it produced](docs/img/quoted-output.png)
+
+`code()` is the listing, `result()` is what it printed, and `figure()` is what it
+drew — a chart is code output the same way a number is, read out of the lecture's
+stored output at render time, so there is no PNG beside the deck to go stale:
+
+![A slide: three bullets on the left; on the right a framed bar chart of token lengths, drawn by the lecture](docs/img/quoted-figure.png)
+
+All three are resolved when the deck is built, so what a slide shows is what
+actually ran — and a name that stops matching is reported by the build rather
+than going quietly stale.
+
+Both slides above are [`demos/05-notebook-slides.ipynb`](demos/05-notebook-slides.ipynb)
+as it stands, rendered by `./demos/build.sh` and screenshotted by
+[`demos/screenshot.sh`](demos/screenshot.sh).
+
+## What a deck declares
+
+The slide notebook says everything about itself in its first cell, so the
+command line needs nothing but the file:
+
+```python
+from pypresent import Presentation, slide, code, result, figure
+
+deck = Presentation(
+    slides='talk-slides.ipynb',   # this notebook: nothing but slide() calls
+    source='talk.ipynb',          # what code(), result() and figure() quote
+    output='out/talk.html',
+    title='A talk', lang='en', theme='office',
+)
+deck                              # the last line, so the cell stores it
+```
+
+The declaration is kept as a cell output, the way a slide is. A flag still wins
+over it: `pypresent build --theme dark -o /tmp/x.html`.
+
+## Themes
+
+Every colour, size and font is a named token, and the stylesheet is written
+entirely in terms of them — so restyling is changing values, never forking a
+renderer.
+
+```python
+Presentation(..., theme='dark')                       # a built-in
+Presentation(..., theme={'base': 'office', 'accent': '#a8441f'})
+Presentation(..., theme='themes/house-style.toml')    # a file
+Presentation(..., theme=Theme.named('slate').replace(bullet_size='4.6cqh'))
+```
+
+Four built-ins ship with it — `warm`, `office`, `dark`, `slate`. To start from
+one, print it as a file you can edit:
+
+```bash
+pypresent themes                 # what there is
+pypresent themes dark > mine.toml
+pypresent build --theme mine.toml
+```
+
+`css=` is still there for the one selector no token covers.
+See [the theme reference](docs/README.md#themes) for every token.
+
+## Right to left
+
+`lang='he'` implies `dir="rtl"`, which mirrors the whole layout — bullets, the
+two-tone title rule, the cover band, the arrow keys — and switches to a
+Hebrew-first font stack, while keeping code and output left to right, because
+Python does not read right to left.
+
+## Commands
+
+| | |
+| --- | --- |
+| `pypresent build` | run the source notebook, then the slide notebook, check, render |
+| `pypresent build --skip-source-run` | leave the source notebook alone |
+| `pypresent build --skip-slides-run` | check and render the stored outputs |
+| `pypresent render` | render only, no kernel and no check |
+| `pypresent check` | what has drifted, said and not corrected |
+| `pypresent export --mode nb --format html` | the source notebook through nbconvert |
+| `pypresent themes [name]` | the built-in themes |
+
+## It also takes a markdown file
+
+A `.md` file works as a source, cut into slides by its headings and `---` lines,
+with a front matter block declaring the deck. It quotes nothing — there is no
+notebook to quote — so it is the lesser half of this, but it is there when a talk
+has no code in it:
+
+```bash
+pypresent render talk.md
+```
+
+`--format md` writes slides back out the same way. See
+[the docs](docs/README.md#writing-slides).
+
+## Documentation
+
+**[The documentation is one page](docs/README.md)**, with everything on it:
+
+- [Quickstart](docs/README.md#quickstart) — from nothing to a deck
+- [Writing slides](docs/README.md#writing-slides) — every block, and what it is for
+- [Themes](docs/README.md#themes) — every token, and how to ship your own
+- [The command line](docs/README.md#the-command-line)
+- [The Python API](docs/README.md#the-python-api)
+
+And [`demos/`](demos/) is the same thing as decks you can open — every block, the
+four themes, a right-to-left deck, a hand-written theme, and a notebook deck that
+quotes its lecture.
+
+## Why not reveal.js / Quarto / RISE
+
+Those are all good, and all bigger. `pypresent` is for one case: a lecture
+notebook that must stay the single source of the code, and a deck of it that
+must be one file with no toolchain to reproduce. If you want speaker view,
+fragments, plugins and a themeing ecosystem, use reveal.js.
+
+## License
+
+MIT — see [LICENSE](LICENSE).