Source code for memeplotlib._meme

"""Object-oriented Meme API."""

from __future__ import annotations

from collections.abc import Sequence
from pathlib import Path
from typing import TYPE_CHECKING, Any

import matplotlib.pyplot as plt

from memeplotlib._alt import default_meme_alt_text, savefig_metadata, set_alt_text
from memeplotlib._cache import default_cache
from memeplotlib._config import config
from memeplotlib._rendering import render_meme
from memeplotlib._template import Template, TextPosition, _resolve_template
from memeplotlib._url import OverlaySpec

if TYPE_CHECKING:
    from matplotlib.axes import Axes
    from matplotlib.figure import Figure


[docs] class Meme: """A meme builder with a fluent (chainable) API. Parameters ---------- template : str or Template Template identifier (memegen ID, file path, URL) or a :class:`Template` instance. *lines : str Initial text lines. font : str or None, optional Font family name. color : str or None, optional Text fill color. outline_color : str or None, optional Text outline color. Forces the Pillow backend under ``backend="auto"``, since memegen renders a hard-coded black stroke. outline_width : float or None, optional Outline stroke width; under Pillow it scales with the fitted font size (each unit adds 1/24 of it). Forces the Pillow backend under ``backend="auto"``. fontsize : float or None, optional Font size: points under the matplotlib backend, pixels at the template's native resolution (used as a maximum) under Pillow. Forces the Pillow backend under ``backend="auto"`` (memegen always auto-fits). style : str or None, optional Text transform -- ``"upper"``, ``"lower"``, or ``"none"``. backend : str or None, optional Override the rendering backend (``"auto"``, ``"memegen"``, ``"pillow"``, ``"matplotlib"``). ``None`` uses ``config["backend"]``. extension : str or None, optional Output format requested from memegen (``"png"``, ``"jpg"``, ``"gif"``, ``"webp"``). memegen backend only. width, height : int or None, optional Output dimensions in pixels. memegen backend only. layout : str or None, optional memegen layout (e.g. ``"top"``). memegen backend only. background : str or None, optional Custom background image URL. memegen backend only. overlays : sequence of OverlaySpec or None, optional Ad-hoc overlay image placements. memegen backend only. template_style : str or None, optional memegen template-specific style (e.g. ``"maga"``). memegen backend only. alt_text : str or None, optional Text alternative for screen-reader users. ``None`` generates one from the template name and captions; see :attr:`alt_text`. Examples -------- >>> from memeplotlib import Meme >>> Meme("buzz").top("memes").bottom("memes everywhere").show() # doctest: +SKIP >>> m = Meme("drake") # doctest: +SKIP >>> m.top("writing tests") # doctest: +SKIP >>> m.bottom("shipping to prod") # doctest: +SKIP >>> fig, ax = m.render() # doctest: +SKIP >>> m.save("output.png") # doctest: +SKIP >>> # Per-line override forces the Pillow backend. >>> Meme("buzz").top("hi").line(1, "world", fontsize=48).save("out.png") # doctest: +SKIP """ def __init__( self, template: str | Template, *lines: str, font: str | None = None, color: str | None = None, outline_color: str | None = None, outline_width: float | None = None, fontsize: float | None = None, style: str | None = None, backend: str | None = None, extension: str | None = None, width: int | None = None, height: int | None = None, layout: str | None = None, background: str | None = None, overlays: Sequence[OverlaySpec] | None = None, template_style: str | None = None, alt_text: str | None = None, ): self._template_str: str | None = None self._template: Template | None = None if isinstance(template, Template): self._template = template else: self._template_str = template self._lines: list[str] = list(lines) self._font = font self._color = color self._outline_color = outline_color self._outline_width = outline_width self._fontsize = fontsize self._style = style self._backend = backend self._extension = extension self._width = width self._height = height self._layout = layout self._background = background self._overlays = list(overlays) if overlays else None self._template_style = template_style self._alt_text = alt_text self._per_line_overrides: dict[int, dict[str, object]] = {} self._fig: Figure | None = None self._ax: Axes | None = None self._cache = default_cache() def _get_template(self) -> Template: if self._template is None: assert self._template_str is not None # set by __init__ when _template is None self._template = _resolve_template(self._template_str) return self._template def _invalidate(self) -> None: """Drop the cached render so the next show()/save() reflects edits.""" self._fig = None self._ax = None
[docs] def top(self, text: str) -> Meme: """Set the top text line (index 0). Parameters ---------- text : str The text to place at the top of the meme. Returns ------- Meme Self, for method chaining. """ if len(self._lines) == 0: self._lines.append(text) else: self._lines[0] = text self._invalidate() return self
[docs] def bottom(self, text: str) -> Meme: """Set the bottom text line (index 1). Parameters ---------- text : str The text to place at the bottom of the meme. Returns ------- Meme Self, for method chaining. """ while len(self._lines) < 2: self._lines.append("") self._lines[1] = text self._invalidate() return self
[docs] def text(self, index: int, text: str) -> Meme: """Set text at a specific line index. Parameters ---------- index : int Zero-based line index. text : str The text to place at the given position. Returns ------- Meme Self, for method chaining. """ while len(self._lines) <= index: self._lines.append("") self._lines[index] = text self._invalidate() return self
[docs] def line( self, index: int, text: str, *, fontsize: float | None = None, color: str | None = None, font: str | None = None, position: TextPosition | None = None, outline_color: str | None = None, outline_width: float | None = None, style: str | None = None, ) -> Meme: """Set text and per-line styling overrides for a single slot. Passing any styling override forces the Pillow backend on render (memegen has no per-line equivalent). Parameters ---------- index : int Zero-based line index. text : str The text to place at the given slot. fontsize : float, optional Override font size for this slot. color : str, optional Override fill colour for this slot. font : str, optional Override font family for this slot. position : TextPosition, optional Override the text-box position metadata for this slot. outline_color : str, optional Override the outline colour for this slot (e.g. a white outline for a caption over a dark region). outline_width : float, optional Override the outline width for this slot. style : str, optional Override the text transform for this slot -- ``"upper"``, ``"lower"``, or ``"none"``. Returns ------- Meme Self, for method chaining. """ self.text(index, text) override: dict[str, object] = {} if fontsize is not None: override["fontsize"] = fontsize if color is not None: override["color"] = color if font is not None: override["font"] = font if position is not None: override["position"] = position if outline_color is not None: override["outline_color"] = outline_color if outline_width is not None: override["outline_width"] = outline_width if style is not None: override["style"] = style if override: self._per_line_overrides[index] = override self._invalidate() return self
[docs] def with_backend(self, backend: str) -> Meme: """Set the rendering backend. Parameters ---------- backend : str One of ``"auto"``, ``"memegen"``, ``"pillow"``, ``"matplotlib"``. Returns ------- Meme Self, for method chaining. """ self._backend = backend self._invalidate() return self
[docs] def with_alt_text(self, text: str | None) -> Meme: """Set (or, with ``None``, reset to the generated default) the alt text. Parameters ---------- text : str or None Description of the meme for screen-reader users. Returns ------- Meme Self, for method chaining. """ self._alt_text = text if self._ax is not None: set_alt_text(self._ax, self.alt_text) return self
@property def alt_text(self) -> str: """The alt text for this meme: explicit, or generated from its captions. Generating the default resolves the template (which may require a network request for memegen IDs). """ if self._alt_text is not None: return self._alt_text return default_meme_alt_text(self._get_template(), self._lines)
[docs] def render( self, ax: Axes | None = None, figsize: tuple[float, float] | None = None, dpi: int | None = None, ) -> tuple[Figure, Axes]: """Render the meme and return the Figure and Axes. Parameters ---------- ax : Axes or None, optional Existing axes to render onto. figsize : tuple of (float, float) or None, optional Figure size in inches ``(width, height)``. dpi : int or None, optional Dots per inch. Returns ------- tuple of (Figure, Axes) The rendered matplotlib Figure and Axes. """ template = self._get_template() # Mirror meme(): memegen can't honour an explicit fontsize or a # custom outline, so any of them forces Pillow under "auto". force_pillow = bool( self._per_line_overrides or self._fontsize is not None or self._outline_color is not None or self._outline_width is not None ) backend_val = self._backend if self._backend is not None else config["backend"] fig, ax_out = render_meme( template, self._lines, ax=ax, figsize=figsize, dpi=dpi, font=self._font, color=self._color, outline_color=self._outline_color, outline_width=self._outline_width, fontsize=self._fontsize, style=self._style, cache=self._cache, backend=backend_val, extension=self._extension, width=self._width, height=self._height, layout=self._layout, background=self._background, overlays=self._overlays, template_style=self._template_style, force_pillow=force_pillow, per_line_overrides=self._per_line_overrides or None, ) set_alt_text(ax_out, self.alt_text) self._fig = fig self._ax = ax_out return fig, ax_out
[docs] def show(self) -> None: """Render and display the meme. Calls :meth:`render` if the meme has not been rendered yet, then displays the figure with ``matplotlib.pyplot.show()``. """ if self._fig is None: self.render() plt.show()
[docs] def save(self, path: str | Path, dpi: int | None = None, **kwargs: Any) -> None: """Render and save the meme to a file. Parameters ---------- path : str or Path Output file path (e.g., ``"meme.png"``). dpi : int or None, optional Dots per inch for the saved image. **kwargs Additional keyword arguments passed to :meth:`matplotlib.figure.Figure.savefig`. The alt text is embedded as PNG/SVG ``Description`` (PDF ``Subject``) metadata; entries in a ``metadata`` kwarg take precedence. """ if self._fig is None: self.render(dpi=dpi) assert self._fig is not None # render() always assigns self._fig metadata = {**savefig_metadata(path, self.alt_text), **kwargs.pop("metadata", {})} if metadata: kwargs["metadata"] = metadata self._fig.savefig( str(path), dpi=dpi if dpi is not None else config["dpi"], bbox_inches="tight", pad_inches=0, **kwargs, )