mpl-typst 0.1.0__tar.gz

mpl_typst-0.1.0/.gitignore

@@ -0,0 +1,159 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$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
+
+# 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
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.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/
+
+# Ignore rendering products.
+gallery/*.pdf
+gallery/*.png
+gallery/*.svg
+gallery/*.typ

mpl_typst-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Daniel Bershatsky
+
+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.

mpl_typst-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.1
+Name: mpl-typst
+Version: 0.1.0
+Summary: Typst backend for matplotlib (Python visualization library).
+Author-email: Daniel Bershatsky <daniel.bershatsky@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/daskol/typst-mpl-backend
+Project-URL: Repository, https://github.com/daskol/typst-mpl-backend.git
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Other Environment
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: Text Processing
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: <4,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib
+Provides-Extra: dev
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: pytest>=7; extra == "dev"
+
+# Typst Matplotlib Backend
+
+*Typst backend for matplotlib (Python visualization library).*
+
+## Overview
+
+At the moment, Typst supports main vector and raster image formats. Namely,
+images in PNG, JPEG, GIF, or SVG format can be easily emplaced in a document
+with Typst. However, it is **not possible** to keep metadata and annotations.
+These are mandatory in order to allow a reader to select and interact with
+vector content (e.g. text) on images. Although SVG can contain text metadata in
+principle, Typst does not support this feature at the moment but still it is
+able to render SVG as a vector content.
+
+This package solves this problem for `matplotlib` users. Basically, this
+project implements a custom render (or backend) for `matplotlib` which
+generates `typ`-file containing Typst markup. Generated markup file can be
+later included in the original markup so that the resulting PDF will have
+interactable content. Matplotlib exploits exactly the same strategy in order to
+generate PGF-files &mdash; a LaTeX markup itself &mdash; which can be included
+into LaTeX markup directly.
+
+## Usage
+
+In order to render image with `mpl_typst` one can import `mpl_typst.as_default`
+module in order to use `mpl_typst` backend by default.
+
+```python
+import mpl_typst.as_default
+```
+
+Or one can configure it manually.
+
+```python
+import matplotlib
+import mpl_typst
+mpl.use('module://mpl_typst')
+```
+
+Also, it is possible to use rendering context as usual to override backend.
+
+```python
+import matplotlib as mpl
+import mpl_typst
+with mpl.rc_context({'backend': 'module://mpl_typst'}):  # or mpl_typst.BACKEND
+    ...
+```
+
+Next, you can save your figure to `typ` as usual.
+
+```python
+fig, ax = plt.subplots()
+...
+fig.savefig('line-plot-simple.typ')
+```
+
+As soon as you get a `typ`-file you can included it directly to `figure`
+function and adjust figure time.
+
+```typst
+#figure(
+  include "line-plot-simple.typ",
+  kind: image,
+  caption: [Simple line plot],
+  placement: top,
+) <line-plot-simple>
+```

mpl_typst-0.1.0/README.md

@@ -0,0 +1,67 @@
+# Typst Matplotlib Backend
+
+*Typst backend for matplotlib (Python visualization library).*
+
+## Overview
+
+At the moment, Typst supports main vector and raster image formats. Namely,
+images in PNG, JPEG, GIF, or SVG format can be easily emplaced in a document
+with Typst. However, it is **not possible** to keep metadata and annotations.
+These are mandatory in order to allow a reader to select and interact with
+vector content (e.g. text) on images. Although SVG can contain text metadata in
+principle, Typst does not support this feature at the moment but still it is
+able to render SVG as a vector content.
+
+This package solves this problem for `matplotlib` users. Basically, this
+project implements a custom render (or backend) for `matplotlib` which
+generates `typ`-file containing Typst markup. Generated markup file can be
+later included in the original markup so that the resulting PDF will have
+interactable content. Matplotlib exploits exactly the same strategy in order to
+generate PGF-files — a LaTeX markup itself — which can be included
+into LaTeX markup directly.
+
+## Usage
+
+In order to render image with `mpl_typst` one can import `mpl_typst.as_default`
+module in order to use `mpl_typst` backend by default.
+
+```python
+import mpl_typst.as_default
+```
+
+Or one can configure it manually.
+
+```python
+import matplotlib
+import mpl_typst
+mpl.use('module://mpl_typst')
+```
+
+Also, it is possible to use rendering context as usual to override backend.
+
+```python
+import matplotlib as mpl
+import mpl_typst
+with mpl.rc_context({'backend': 'module://mpl_typst'}):  # or mpl_typst.BACKEND
+    ...
+```
+
+Next, you can save your figure to `typ` as usual.
+
+```python
+fig, ax = plt.subplots()
+...
+fig.savefig('line-plot-simple.typ')
+```
+
+As soon as you get a `typ`-file you can included it directly to `figure`
+function and adjust figure time.
+
+```typst
+#figure(
+  include "line-plot-simple.typ",
+  kind: image,
+  caption: [Simple line plot],
+  placement: top,
+) <line-plot-simple>
+```

mpl_typst-0.1.0/gallery/line-plot-simple.py

@@ -0,0 +1,16 @@
+#!/usr/bin/env python3
+
+import matplotlib.pyplot as plt
+
+from mpl_typst import rc_context
+
+with rc_context():
+    fig, ax = plt.subplots(figsize=(3.25, 2.01), layout='constrained')
+    ax.plot([i ** 2 for i in range(10)], '-..', label=r'$x^2$')
+    ax.legend()
+    ax.set_xlabel(r'$x$')
+    ax.set_ylabel(r'$f(x)$')
+    fig.savefig('line-plot-simple.typ')
+    fig.savefig('line-plot-simple.pdf')
+    fig.savefig('line-plot-simple.png')
+    fig.savefig('line-plot-simple.svg')

mpl_typst-0.1.0/gallery/main.typ

@@ -0,0 +1,43 @@
+/**
+ * main.typ
+ *
+ * This is an example paper which demonstrates how to use typ-files rendered
+ * with custom `matplotlib` backend based on Typst.
+ */
+
+#set document(title: [#smallcaps[Typst] #smallcaps[Matplotlib] Backend Demo])
+#set page(
+  paper: "a4",
+  margin: (left: 0.75in, right: 8.5in - (0.75in + 6.75in), top: 1.0in),
+)
+
+#set par(justify: true, leading: 0.58em)
+#set text(font: "Times", size: 10pt)
+#show: it => columns(2, gutter: 0.25in, it)
+
+#lorem(50)
+
+#lorem(50)
+
+#lorem(50)
+
+#lorem(50)
+
+#lorem(50)
+
+#lorem(50)
+
+#lorem(50)
+
+// NOTE The point is to include typ-file and adjust figure kind
+// correspondently.
+#figure(
+  include "line-plot-simple.typ",
+  kind: image,
+  caption: [Simple line plot],
+  placement: top,
+) <line-plot-simple>
+
+#lorem(50)
+
+#lorem(50)

mpl_typst-0.1.0/gallery/pcolor.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python
+
+import matplotlib as mpl
+import matplotlib.pyplot as plt
+import numpy as np
+from mpl_toolkits.axes_grid1.axes_divider import make_axes_locatable
+
+from mpl_typst import rc_context
+
+mpl.rcParams.update({
+    'font.family': 'serif',
+    'font.size': 8,
+    'axes.labelsize': 8,
+    'legend.fontsize': 6,
+    'xtick.labelsize': 6,
+    'ytick.labelsize': 6,
+    'axes.titlesize': 8,
+})
+
+xticks = [512, 2048, 4096, 8192, 16384, 65536]
+yticks = [8, 32, 64, 96, 128]
+values = np.array([
+    0.6, 0.0, 0.1, 0.1, -0.2, 0.7, -0.0, -0.0, 0.2, 0.1, -0.1, 1.7, 0.0, 0.1,
+    0.1, 0.2, 0.1, 1.8, 0.0, 0.1, -0.0, 0.2, 0.5, 0.9, 0.0, 0.1, 0.2, 0.3, 0.8,
+    2.1
+]).reshape(5, 6)
+
+width, height = values.T.shape
+xs, ys = np.mgrid[:width + 1, :height + 1]
+
+with rc_context():
+    fig, ax = plt.subplots(figsize=(3.25, 2.01), layout='constrained')
+
+    img = ax.pcolor(xs, ys, values.T)
+
+    divider = make_axes_locatable(ax)
+    cax = divider.append_axes('right', size='8%', pad=0.1)
+    fig.colorbar(img, cax)
+
+    ax.set_xlabel('Number of tokens')
+    ax.set_xticks(np.arange(len(xticks)))
+    ax.set_xticklabels([f'{x:.1f}' if x < 1 else int(x) for x in xticks])
+
+    ax.set_ylabel('Rank r')
+    ax.set_yticks(np.arange(len(yticks)))
+    ax.set_yticklabels([str(x) for x in yticks])
+    ax.invert_yaxis()
+
+    fig.savefig('pcolor.pdf')
+    fig.savefig('pcolor.png')
+    fig.savefig('pcolor.svg')
+    fig.savefig('pcolor.typ')

mpl_typst-0.1.0/mpl_typst/__init__.py

@@ -0,0 +1,74 @@
+"""Package `mpl_typst` provides a :py:`matplotlib` backend for rendering
+directly to Typst as well as rendering to PDF, PNG, SVG indirectly through
+Typst renderer.
+
+One can import `mpl_typst.as_default` module in order to use `mpl_typst`
+backend by default.
+
+.. code:: python
+
+   import mpl_typst.as_default
+
+Or one can configure it manually.
+
+.. code:: python
+
+   import matplotlib
+   import mpl_typst
+   mpl.use('module://mpl_typst')
+
+Also, it is possible to use rendering context as usual to override backend.
+
+.. code:: python
+
+   import matplotlib as mpl
+   import mpl_typst
+   with mpl.rc_context({'backend': 'module://mpl_typst'}):
+       ...
+"""
+
+from contextlib import contextmanager
+from os import PathLike
+from pathlib import Path
+from typing import Any, Generator
+
+import matplotlib as mpl
+from mpl_typst.backend import (FigureCanvas, FigureManager, TypstFigureCanvas,
+                               TypstFigureManager, TypstRenderer,
+                               TypstRenderingError)
+
+__all__ = ('BACKEND', 'FigureCanvas', 'FigureManager', 'TypstFigureCanvas',
+           'TypstFigureManager', 'TypstGraphicsContext', 'TypstRenderer',
+           'TypstRenderingError', 'rc_context', 'use')
+
+# Backend specification for use with `matplotlib.use`
+BACKEND = 'module://mpl_typst'
+
+
+@contextmanager
+def rc_context(
+    rc: dict[str, Any] | None = None,
+    fname: PathLike | Path | str | None = None,
+) -> Generator[None, None, None]:
+    """A shortcut for using Typst as default backend in a context.
+
+    It forward all arguments to original :py:`matplotlib.rc_context` context
+    manager but it enforces use of `mpl_typst` backend in the beginning of
+    newly created context.
+
+    .. code:: python
+
+       import mpl_typst
+       with mpl_typst.rc_context():
+           ...
+    """
+    original_backend = mpl.rcParams['backend']
+    with mpl.rc_context(rc, fname):
+        mpl.use(BACKEND)
+        yield
+        mpl.use(original_backend)
+
+
+def use(*, force: bool = True):
+    """Set Typst rendering backend as default on (see :py:`matplotlib.use`)."""
+    mpl.use(BACKEND)

mpl_typst-0.1.0/mpl_typst/as_default.py

@@ -0,0 +1,7 @@
+"""This module is aimed to use by end-users in order to configure `mpl_typst`
+as default backend.
+"""
+
+from mpl_typst import use
+
+use()  # Use this MPL backend as default.