Metadata-Version: 2.5
Name: imscribe
Version: 0.2.0
Summary: Markdown, streaming and diff views for Dear ImGui, typeset by imtypeset
Project-URL: Repository, https://github.com/WalterCReel3/imscribe
Author: Walter Reel
License-Expression: MIT
License-File: LICENSE
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Requires-Dist: fonttools>=4.50
Requires-Dist: imgui-bundle==1.92.900
Requires-Dist: imtypeset==0.4.3.192900; python_version >= '3.11' and python_version < '3.15' and ((sys_platform == 'linux' and platform_machine == 'x86_64') or (sys_platform == 'darwin' and platform_machine == 'arm64'))
Requires-Dist: markdown-it-py>=3.0
Provides-Extra: dev
Requires-Dist: black>=24.1; extra == 'dev'
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: hatchling>=1.27; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: numpy>=1.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.16; extra == 'dev'
Requires-Dist: twine>=6.0; extra == 'dev'
Description-Content-Type: text/markdown

# imscribe

Markdown, streaming and diff views for [Dear ImGui](https://github.com/ocornut/imgui)
in Python: paragraphs justified and broken into lines the way TeX breaks
them, headings, lists, tables, fenced code, formulas written as `$...$`,
text that arrives a piece at a time, side-by-side and unified diffs,
selection and copying. You hand a view markdown source and call `draw` each
frame, inside your own window.

The text is set and drawn by [imtypeset](https://pypi.org/project/imtypeset/),
a C++ library that binds to the Dear ImGui inside the
[`imgui-bundle`](https://pypi.org/project/imgui-bundle/) wheel. imscribe is the
Python layer over it: it reads the markdown, describes it to the library, and
is the views. There is no other renderer in it: where imtypeset is not
installed a view draws nothing and says why.

This is `0.2.0`, the first full release (`0.2.0b1` was the beta before it):

```
pip install imscribe
```

## Two pins, held together

imscribe requires both of these exactly, and they move together:

```
imgui-bundle==1.92.900
imtypeset==0.4.3.192900
```

An imtypeset wheel is built for one `imgui-bundle` version and its fourth
number says which (`192900` is `1.92.900`). So imscribe cannot be installed
beside anything that needs another `imgui-bundle`. An application that pins
its own dependencies pins these two with it.

## Where it runs

Anywhere `imgui-bundle` 1.92.900 does, as far as installing goes. It DRAWS
where imtypeset has a wheel:

| | CPython |
|---|---|
| Linux x86-64, glibc 2.28 or later | 3.11, 3.12, 3.13, 3.14 |
| macOS 14 or later on Apple Silicon | 3.11, 3.12, 3.13, 3.14 |

Not Windows, not Linux on arm64, not macOS on Intel: there `pip install
imscribe` succeeds without imtypeset, `imscribe.typesetter.kind()` answers
`Kind.NOT_INSTALLED`, and nothing is drawn. On Linux with musl (Alpine), with
a glibc older than 2.28, and on macOS older than 14, the install fails at
imtypeset, which has no wheel that fits; `imgui-bundle` has none for an old
glibc or an old macOS either.

On Linux, `imgui-bundle`'s extension module loads `libX11.so.6` and
`libXext.so.6` from the system when it is imported (read from the 1.92.900
wheel's binaries); neither is in a wheel. On Debian and Ubuntu they are the
packages `libx11-6` and `libxext6`. imtypeset's library asks the system for
nothing beyond the C and C++ runtimes.

## Using it

```python
from imgui_bundle import hello_imgui, immapp
from imscribe import DARK_PALETTE, Theme, TypesetView, typesetter

SOURCE = "# Hello\n\nSome *markdown*, set in lines of even colour, and $e^{i\\pi} + 1 = 0$."
assert typesetter.module() is not None, typesetter.reason()  # before any window
views = []

def fonts():
    hello_imgui.imgui_default_settings.load_default_font_with_font_awesome_icons()
    typesetter.load_fonts()  # last, after the application's own fonts

def gui():
    if not views:  # on the first frame: the fonts are loaded by then
        views.append(TypesetView(SOURCE, theme=Theme.build(), palette=DARK_PALETTE, math=True))
    views[0].draw(palette=DARK_PALETTE)

params = hello_imgui.RunnerParams()
params.callbacks.load_additional_fonts = fonts
params.callbacks.show_gui = gui
params.callbacks.before_exit = typesetter.unload  # before Dear ImGui's context goes
immapp.run(params)
```

Where no imtypeset was found, the `assert` stops with the sentence for "there
is no imtypeset here": imtypeset is not installed: pip installs it with
imscribe where imtypeset has a wheel (CPython 3.11 to 3.14 on Linux x86-64 and
on macOS 14 or later on arm64), and IMTYPESET_LIBRARY names no library. On a
platform outside the table above there is nothing to do about it; the variable
is only how a developer names a library built from source. With
`IMSCRIBE_NO_TYPESET` set, an installed imtypeset is not looked for and the
sentence says so instead.

`TypesetStreamView` takes text as it arrives (`append`), and `TypesetDiffView`
two texts or a unified diff. `python -m imscribe.typesetter` prints, with no
window, which imtypeset was found and whether it was accepted.

## What is not known

- **Nobody but its author has looked at what it draws.** The tests measure
  where text is placed and that frames are drawn; none of them judges how it
  looks.
- **macOS has been run once, by hand.** The owner ran the `0.2.0b1` demo and
  test suite on one Apple Silicon Mac (macOS 26.7, CPython 3.11); the 25 tests
  that failed there read `/proc/loadavg`, which a Mac does not have, and are
  fixed. Nothing has been run on a Mac since, and no CI runs there.
  imtypeset's wheels pass their own installed checks on GitHub's macOS arm64
  runners (three of that project's 55 tests fail there, by its own notes).
- Everything was measured on Linux x86-64, CPython 3.11, with a software
  renderer and a display scale of 1.

## More

The repository has the examples, the demo application, the tests and the
notes on every decision: <https://github.com/WalterCReel3/imscribe>

MIT licence. The fonts the views set text in are not in this package: they
ship in the `imgui-bundle` wheel under their own licences.
