texformules 0.1.0__py3-none-any.whl

texformules/__init__.py

@@ -0,0 +1,51 @@
+"""LaTeX formulas typeset in batches, cached as PNG and one-page PDF with their baseline.
+
+Two steps, two modules:
+
+- ``fragments`` cuts a line into text and LaTeX fragments, on latexdetok's tree
+  (:func:`split`), removes the comments and can set French spacing; the whole line
+  goes through latexdetok, and what it finds wrong follows each fragment
+  (:class:`Problem`);
+- ``formulas`` typesets the fragments in a single compilation per batch, with the
+  document's preamble, and keeps them as PNG and as one-page PDF, with their baseline
+  (:class:`FormulaBook`, :class:`PdfBox`).
+
+Only latexdetok and pypdfium2 are needed to import it; LaTeX is called at the first
+missing formula. ``texformules.figures``, with the ``figures`` extra, styles matplotlib
+figures for the same documents.
+
+    book = FormulaBook(default_cache(), dpi=600)
+    fragments = split(r"Result: $T_0=\\SI{2.0}{s}$, 2 marks")
+    formulas = book.render(f.text for f in fragments if f.latex)
+    for formula in formulas.values():
+        pdf, box = book.pdf(formula.key), formula.pdf_box  # box in PDF points
+"""
+
+from texformules.formulas import (
+    BP_PER_PT,
+    Formula,
+    FormulaBook,
+    PdfBox,
+    Runner,
+    default_cache,
+    default_preamble,
+)
+from texformules.fragments import Fragment, Problem, comments, french_spacing, split
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BP_PER_PT",
+    "Formula",
+    "FormulaBook",
+    "Fragment",
+    "PdfBox",
+    "Problem",
+    "Runner",
+    "__version__",
+    "comments",
+    "default_cache",
+    "default_preamble",
+    "french_spacing",
+    "split",
+]

texformules/figures/__init__.py

@@ -0,0 +1,66 @@
+"""matplotlib figures ready for a LaTeX document: size in cm, fonts, decimal comma,
+insets, tight cropping. Needs the ``figures`` extra (matplotlib).
+
+Usage::
+
+    import matplotlib.pyplot as plt
+    from texformules.figures import apply_style, save_figure, style_axes
+
+    apply_style(8, 6)  # width, height in cm, before creating the figures
+    fig, ax = plt.subplots()
+    ax.plot(x, y)
+    style_axes(ax)  # spines, ticks, decimal comma
+    save_figure(fig, "figure.pdf")  # cropped by pdfcrop
+
+Formerly the separate ``latex_figures`` package; its names are kept as deprecated
+aliases (:mod:`texformules.figures.legacy`).
+"""
+
+# First: a clear error, naming the extra, when matplotlib is missing.
+import texformules.figures._require  # noqa: F401  # isort: skip
+from texformules.figures.axes import DecimalCommaFormatter, add_inset, style_axes
+from texformules.figures.export import FORMATS, save_figure
+from texformules.figures.legacy import (
+    PREAMBULE,
+    ScalarFormatterVirgule,
+    add_subplot_axes,
+    fig_size,
+    format_axes,
+    latexify,
+    parametres_latex,
+    restaurer,
+    save_fig,
+)
+from texformules.figures.style import (
+    INCH,
+    MAX_HEIGHT,
+    PREAMBLE,
+    apply_style,
+    figure_size,
+    restore_style,
+    style_params,
+)
+
+__all__ = [
+    "FORMATS",
+    "INCH",
+    "MAX_HEIGHT",
+    "PREAMBLE",
+    "PREAMBULE",
+    "DecimalCommaFormatter",
+    "ScalarFormatterVirgule",
+    "add_inset",
+    "add_subplot_axes",
+    "apply_style",
+    "fig_size",
+    "figure_size",
+    "format_axes",
+    "latexify",
+    "parametres_latex",
+    "restaurer",
+    "restore_style",
+    "save_fig",
+    "save_figure",
+    "style_axes",
+    "style_params",
+]

texformules/figures/_require.py

@@ -0,0 +1,16 @@
+"""Fails early, and says which extra to install, when matplotlib is missing.
+
+``texformules.figures`` is the only part of the package that needs matplotlib, a heavy
+dependency the formulas do without: it comes with the ``figures`` extra. Without this
+check, the error would name matplotlib alone, and not how to get it.
+"""
+
+__all__: list[str] = []
+
+try:
+    import matplotlib  # noqa: F401
+except ModuleNotFoundError as error:  # pragma: no cover - depends on the environment
+    raise ModuleNotFoundError(
+        "texformules.figures needs matplotlib: pip install 'texformules[figures]'",
+        name=error.name,
+    ) from error

texformules/figures/axes.py

@@ -0,0 +1,93 @@
+"""Axes formatting: discreet spines, outward ticks, decimal comma."""
+
+from collections.abc import Sequence
+from typing import Any
+
+import matplotlib.pyplot as plt
+from matplotlib.axes import Axes
+from matplotlib.ticker import ScalarFormatter
+
+__all__ = ["DecimalCommaFormatter", "add_inset", "style_axes"]
+
+
+def _comma(text: str) -> str:
+    # In math mode (mathtext or LaTeX), "{,}" avoids the space that follows a
+    # punctuation comma.
+    return text.replace(".", "{,}")
+
+
+class DecimalCommaFormatter(ScalarFormatter):
+    """A ``ScalarFormatter`` in math notation, with a decimal comma, and powers of 10
+    outside [10⁻², 10⁴].
+
+    The comma does not go through ``locale.setlocale("fr_FR")``, which would act on
+    the whole program and fails where no French locale is installed.
+    """
+
+    def __init__(self, **kwargs: Any) -> None:
+        kwargs.setdefault("useMathText", True)
+        super().__init__(**kwargs)
+        self.set_powerlimits((-2, 4))
+
+    def __call__(self, x: float, pos: int | None = None) -> str:
+        return _comma(super().__call__(x, pos))
+
+    def get_offset(self) -> str:
+        return _comma(super().get_offset())
+
+
+def style_axes(ax: Axes | None = None, format_ticks: bool = True, decimal_comma: bool = True) -> Axes:
+    """Thin grey spines, outward ticks, and (``format_ticks``) a formatter of its own on
+    each linear axis: :class:`DecimalCommaFormatter`, or with ``decimal_comma=False`` a
+    mathtext ``ScalarFormatter`` with the same power limits. Calls ``tight_layout`` on
+    the figure of ``ax`` (the current axes by default).
+
+    Each axis gets its own formatter: a single shared formatter kept only one common
+    factor (the ×10⁵ of the x axis lost to the y axis's).
+    """
+    if ax is None:
+        ax = plt.gca()
+    for spine in ax.spines.values():
+        spine.set_visible(True)
+        spine.set_color("gray")
+        spine.set_linewidth(0.5)
+    ax.xaxis.set_ticks_position("bottom")
+    ax.yaxis.set_ticks_position("left")
+    for axis in (ax.xaxis, ax.yaxis):
+        axis.set_tick_params(direction="out", which="both", color="gray")
+        if format_ticks and axis.get_scale() == "linear":
+            axis.set_major_formatter(_formatter(decimal_comma))
+    figure = ax.get_figure()
+    if figure is not None:
+        figure.tight_layout()  # type: ignore[union-attr]
+    return ax
+
+
+def _formatter(decimal_comma: bool) -> ScalarFormatter:
+    if decimal_comma:
+        return DecimalCommaFormatter()
+    formatter = ScalarFormatter(useMathText=True)
+    formatter.set_powerlimits((-2, 4))
+    return formatter
+
+
+def add_inset(ax: Axes, rect: Sequence[float]) -> Axes:
+    """Inset axes inside ``ax``; ``rect = [x0, y0, width, height]`` as fractions of
+    ``ax`` (for instance ``[0.6, 0.1, 0.3, 0.3]``).
+
+    The tick labels shrink as the square root of the relative size. The inset follows
+    ``ax`` if the layout changes (``Axes.inset_axes``).
+
+    Example::
+
+        inset = add_inset(ax, rect=[0.6, 0.1, 0.3, 0.3])
+        inset.plot(wavelengths, sines, "o", ms=3)
+        inset.set_xlim(0, 650)
+    """
+    x0, y0, width, height = rect
+    inset = ax.inset_axes((x0, y0, width, height))
+    for axis, factor in ((inset.xaxis, width), (inset.yaxis, height)):
+        labels = axis.get_ticklabels()
+        size = labels[0].get_fontsize() if labels else 10.0
+        axis.set_tick_params(labelsize=size * factor**0.5)
+    return inset

texformules/figures/export.py

@@ -0,0 +1,70 @@
+"""Saving a figure, cropped as tight as can be by an external tool.
+
+``bbox_inches="tight"`` leaves a margin around the text boxes; pdfcrop (PDF),
+ImageMagick (PNG) or epstool (EPS) crop to the ink. The figure goes through a temporary
+file, deleted afterwards, and the tools run without a shell: a path with spaces breaks
+nothing. Without the tool, the figure is saved uncropped, with a warning.
+"""
+
+import shutil
+import subprocess
+import tempfile
+import warnings
+from pathlib import Path
+from typing import Any
+
+from matplotlib.figure import Figure
+
+__all__ = ["FORMATS", "save_figure"]
+
+#: Format → possible cropping commands, the first one found is used ({e}: input, {s}: output).
+FORMATS: dict[str, list[list[str]]] = {
+    "pdf": [["pdfcrop", "{e}", "{s}"]],
+    "png": [["magick", "{e}", "-trim", "{s}"], ["convert", "{e}", "-trim", "{s}"]],
+    "eps": [["epstool", "--bbox", "--copy", "{e}", "{s}"]],
+}
+
+
+def _command(fmt: str) -> list[str] | None:
+    for command in FORMATS[fmt]:
+        if shutil.which(command[0]):
+            return command
+    return None
+
+
+def save_figure(
+    fig: Figure,
+    path: str | Path,
+    fmt: str | None = None,
+    dpi: int = 300,
+    tight: bool = True,
+    crop: bool = True,
+) -> Path:
+    """Saves ``fig`` as PDF, PNG or EPS (from the extension, or ``fmt``), cropped.
+
+    The extension is added to the name if it is missing. Returns the path written.
+
+    :raises ValueError: for a format outside :data:`FORMATS`.
+    :raises subprocess.CalledProcessError: when the cropping tool fails.
+    """
+    target = Path(path).expanduser().resolve()
+    fmt = fmt or target.suffix.lstrip(".").lower()
+    if fmt not in FORMATS:
+        raise ValueError(f"Unsupported format: {fmt!r} ({', '.join(FORMATS)}).")
+    if target.suffix.lower() != f".{fmt}":
+        target = target.with_name(target.name + f".{fmt}")
+    options: dict[str, Any] = {"dpi": dpi, "format": fmt, "bbox_inches": "tight" if tight else None}
+
+    command = _command(fmt) if crop else None
+    if crop and command is None:
+        tools = ", ".join(c[0] for c in FORMATS[fmt])
+        warnings.warn(f"{tools} not found: figure not cropped.", stacklevel=2)
+    if command is None:
+        fig.savefig(target, **options)
+        return target
+    with tempfile.TemporaryDirectory() as folder:
+        raw = Path(folder) / f"figure.{fmt}"
+        fig.savefig(raw, **options)
+        arguments = [a.format(e=raw, s=target) for a in command]
+        subprocess.run(arguments, check=True, capture_output=True)
+    return target

texformules/figures/legacy.py

@@ -0,0 +1,90 @@
+"""The names of latex_figures, the package ``texformules.figures`` replaces. Deprecated.
+
+latex_figures had French names (``restaurer``, ``ScalarFormatterVirgule``) and
+keyword arguments (``famille``, ``fig_width``); the package is English now. The old
+names stay so that existing scripts keep working unchanged after
+``from latex_figures import …`` becomes ``from texformules.figures import …``; new code
+uses the new names. They will go in a future major release.
+
+Where only the name changed, the alias is the new object itself. Where the arguments
+changed too, a thin wrapper keeps the old signature, and the old defaults: the old
+``latexify`` and ``parametres_latex`` keep :data:`PREAMBULE`, which loads French babel,
+where the new ones load nothing language-specific.
+"""
+
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+from matplotlib.figure import Figure
+
+from texformules.figures.axes import DecimalCommaFormatter, add_inset, style_axes
+from texformules.figures.export import save_figure
+from texformules.figures.style import apply_style, figure_size, restore_style, style_params
+
+__all__ = [
+    "PREAMBULE",
+    "ScalarFormatterVirgule",
+    "add_subplot_axes",
+    "fig_size",
+    "format_axes",
+    "latexify",
+    "parametres_latex",
+    "restaurer",
+    "save_fig",
+]
+
+#: latex_figures's default preamble: French babel and siunitx.
+PREAMBULE = "\\usepackage[french]{babel}\n\\usepackage{siunitx}"
+
+ScalarFormatterVirgule = DecimalCommaFormatter
+add_subplot_axes = add_inset
+format_axes = style_axes
+restaurer = restore_style
+
+
+def fig_size(
+    fig_width: float = 16.0, fig_height: float | None = None, ratio: float | None = None
+) -> tuple[float, float]:
+    """Deprecated: :func:`~texformules.figures.figure_size`."""
+    return figure_size(fig_width, fig_height, ratio)
+
+
+def parametres_latex(
+    fig_width: float | None = None,
+    fig_height: float | None = None,
+    ratio: float | None = None,
+    usetex: bool = True,
+    famille: str = "sans-serif",
+    preamble: str | Sequence[str] | None = None,
+) -> dict[str, Any]:
+    """Deprecated: :func:`~texformules.figures.style_params`, French babel by default."""
+    return style_params(fig_width, fig_height, ratio, usetex, famille, _old_default(preamble))
+
+
+def latexify(
+    fig_width: float | None = None,
+    fig_height: float | None = None,
+    ratio: float | None = None,
+    usetex: bool = True,
+    famille: str = "sans-serif",
+    preamble: str | Sequence[str] | None = None,
+) -> dict[str, Any]:
+    """Deprecated: :func:`~texformules.figures.apply_style`, French babel by default."""
+    return apply_style(fig_width, fig_height, ratio, usetex, famille, _old_default(preamble))
+
+
+def save_fig(
+    fig: Figure,
+    file_name: str | Path,
+    fmt: str | None = None,
+    dpi: int = 300,
+    tight: bool = True,
+    crop: bool = True,
+) -> Path:
+    """Deprecated: :func:`~texformules.figures.save_figure`."""
+    return save_figure(fig, file_name, fmt, dpi, tight, crop)
+
+
+def _old_default(preamble: str | Sequence[str] | None) -> str | Sequence[str]:
+    return PREAMBULE if preamble is None else preamble

texformules/figures/style.py

@@ -0,0 +1,135 @@
+"""matplotlib settings for figures inserted in a LaTeX document.
+
+Dimensions are in centimetres, like in the document. The settings start from those of
+the SciPy "Cookbook" (Matplotlib/LaTeX_Examples). With ``usetex``, the LaTeX preamble
+loads amsmath and siunitx, so that labels are written as in the document
+(``\\qty{3}{\\m\\per\\s}``).
+
+The settings saved before the first :func:`apply_style` live in a module variable, not
+in a class: ``rcParams`` is itself global to matplotlib, and :func:`restore_style`
+must undo every :func:`apply_style` since, whoever made it.
+"""
+
+import copy
+import math
+import warnings
+from collections.abc import Sequence
+from typing import Any
+
+import matplotlib as mpl
+
+__all__ = [
+    "INCH",
+    "MAX_HEIGHT",
+    "PREAMBLE",
+    "apply_style",
+    "figure_size",
+    "restore_style",
+    "style_params",
+]
+
+INCH = 2.54  # cm
+MAX_HEIGHT = 22.0  # cm, the usable height of an A4 page
+_GOLDEN_RATIO = (math.sqrt(5) - 1) / 2  # 0.618
+#: Default LaTeX preamble (``text.latex.preamble``), used when ``usetex`` is true.
+PREAMBLE = "\\usepackage{amsmath}\n\\usepackage{siunitx}"
+
+# Settings from before the first ``apply_style``, given back by ``restore_style``.
+_SAVED: dict[str, Any] | None = None
+
+
+def figure_size(
+    width: float = 16.0, height: float | None = None, ratio: float | None = None
+) -> tuple[float, float]:
+    """Size (width, height) in inches of a figure given in cm.
+
+    Without a height, it is ``ratio`` × width (the golden ratio by default). Beyond
+    22 cm, the height is brought down to 22 cm, with a warning.
+    """
+    if height is None:
+        height = width * (_GOLDEN_RATIO if ratio is None else ratio)
+    if height > MAX_HEIGHT:
+        warnings.warn(
+            f"Figure height {height} cm too tall: brought down to {MAX_HEIGHT} cm.",
+            stacklevel=2,
+        )
+        height = MAX_HEIGHT
+    return width / INCH, height / INCH
+
+
+def style_params(
+    width: float | None = None,
+    height: float | None = None,
+    ratio: float | None = None,
+    usetex: bool = True,
+    family: str = "sans-serif",
+    preamble: str | Sequence[str] | None = None,
+) -> dict[str, Any]:
+    """The rc parameters of :func:`apply_style`, to pass to ``plt.rc_context`` as well.
+
+    ``width`` in cm (16 by default), ``height`` in cm or ``ratio`` × width; ``family``:
+    ``"sans-serif"`` or ``"serif"``; ``preamble``: the LaTeX preamble (a string, or one
+    line per item), :data:`PREAMBLE` by default, ``""`` for none; it only matters with
+    ``usetex``.
+    """
+    inches_wide, inches_high = figure_size(16.0 if width is None else width, height, ratio)
+    if preamble is None:
+        preamble = PREAMBLE
+    elif not isinstance(preamble, str):
+        preamble = "\n".join(preamble)
+    return {
+        "pgf.texsystem": "pdflatex",
+        "axes.labelsize": 11,
+        "axes.titlesize": 11,
+        "axes.formatter.use_mathtext": True,
+        "font.size": 11,
+        "text.usetex": usetex,
+        "text.latex.preamble": preamble,
+        "font.family": family,
+        "font.serif": ["Times New Roman", "Times", "DejaVu Serif"],
+        "font.sans-serif": ["Arial", "Helvetica", "DejaVu Sans"],
+        "legend.fontsize": 8,
+        "xtick.labelsize": 10,
+        "ytick.labelsize": 10,
+        "lines.markersize": 3,
+        "figure.figsize": [inches_wide, inches_high],
+        "figure.subplot.left": 0.16,
+        "figure.subplot.right": 0.94,
+        "figure.subplot.bottom": 0.14,
+        "figure.subplot.top": 0.96,
+        "figure.subplot.wspace": 0.3,
+        "figure.subplot.hspace": 0.2,
+    }
+
+
+def apply_style(
+    width: float | None = None,
+    height: float | None = None,
+    ratio: float | None = None,
+    usetex: bool = True,
+    family: str = "sans-serif",
+    preamble: str | Sequence[str] | None = None,
+) -> dict[str, Any]:
+    """Applies :func:`style_params` to matplotlib (before creating the figures) and returns them.
+
+    Figures already created keep their settings; no need to restart the console. No
+    locale is changed: the decimal comma comes from :func:`~texformules.figures.style_axes`.
+    :func:`restore_style` gives back the settings from before.
+    """
+    global _SAVED
+    params = style_params(width, height, ratio, usetex, family, preamble)
+    if _SAVED is None:
+        _SAVED = {key: copy.deepcopy(mpl.rcParams[key]) for key in params}  # type: ignore[index]
+    # matplotlib ≥ 3.11's stubs only accept literal keys; matplotlib checks every key at
+    # run time anyway.
+    mpl.rcParams.update(params)  # type: ignore[arg-type]
+    return params
+
+
+def restore_style() -> None:
+    """Gives matplotlib back the settings from before the first :func:`apply_style` (its
+    inverse); does nothing if it was not called."""
+    global _SAVED
+    if _SAVED is not None:
+        mpl.rcParams.update(_SAVED)  # type: ignore[arg-type]
+        _SAVED = None