reportlab-layout 1.0.0__py3-none-any.whl

reportlab_layout/__init__.py

@@ -0,0 +1,69 @@
+"""Une couche de mise en page à curseur au-dessus de reportlab.
+
+Le canvas de reportlab dessine où on lui dit, en points, depuis le coin
+bas-gauche. Ses ``platypus`` templates, à l'inverse, gèrent le flux mais
+reprennent la main sur la page entière. Ce paquet occupe l'espace entre les
+deux : un curseur qui descend dans la page, et le canvas resté accessible pour
+tout ce qui doit être placé au point près.
+
+    from reportlab_layout import PDFMaker
+
+    with PDFMaker("bulletin.pdf", top=20) as doc:
+        doc.draw_paragraph("Bulletin du 3e trimestre", "Heading1 Centered")
+        doc.add_space()
+        doc.draw_table([["Matière", "Note"], ["Maths", "17"]])
+"""
+
+from reportlab_layout.boxes import Box
+from reportlab_layout.colors import ColorLike, to_color
+from reportlab_layout.cursor import Cursor
+from reportlab_layout.document import PDFMaker
+from reportlab_layout.frames import FrameWriter
+from reportlab_layout.geometry import Margins, PageGeometry, resolve_pagesize
+from reportlab_layout.images import ImageSpec, image_spec, load_image
+from reportlab_layout.metrics import (
+    TextMetrics,
+    baseline_offset,
+    cap_height,
+    font_ascent,
+    font_descent,
+    font_height,
+    string_width,
+)
+from reportlab_layout.numbering import NumberedCanvas
+from reportlab_layout.shapes import ShapePainter
+from reportlab_layout.styles import STYLES, StyleLike, add_style, make_stylesheet, resolve_style
+from reportlab_layout.text import TextPainter
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "STYLES",
+    "Box",
+    "ColorLike",
+    "Cursor",
+    "FrameWriter",
+    "ImageSpec",
+    "Margins",
+    "NumberedCanvas",
+    "PDFMaker",
+    "PageGeometry",
+    "ShapePainter",
+    "StyleLike",
+    "TextMetrics",
+    "TextPainter",
+    "__version__",
+    "add_style",
+    "baseline_offset",
+    "cap_height",
+    "font_ascent",
+    "font_descent",
+    "font_height",
+    "image_spec",
+    "load_image",
+    "make_stylesheet",
+    "resolve_pagesize",
+    "resolve_style",
+    "string_width",
+    "to_color",
+]

reportlab_layout/boxes.py

@@ -0,0 +1,30 @@
+"""Rectangle rendu par une opération de tracé."""
+
+from typing import NamedTuple
+
+__all__ = ["Box"]
+
+
+class Box(NamedTuple):
+    """Rectangle effectivement occupé par un élément dessiné, repère canvas.
+
+    Se déballe comme un quadruplet ``(x, y, width, height)``. ``x, y`` est le
+    coin **bas-gauche**, comme partout dans reportlab.
+    """
+
+    x: float
+    y: float
+    width: float
+    height: float
+
+    @property
+    def right(self) -> float:
+        return self.x + self.width
+
+    @property
+    def top(self) -> float:
+        return self.y + self.height
+
+    @property
+    def center(self) -> tuple[float, float]:
+        return (self.x + self.width / 2, self.y + self.height / 2)

reportlab_layout/colors.py

@@ -0,0 +1,31 @@
+"""Conversion des couleurs vers le type attendu par reportlab."""
+
+from typing import TypeAlias
+
+from reportlab.lib.colors import Color, HexColor, toColor
+
+__all__ = ["ColorLike", "to_color"]
+
+#: Tout ce qui peut désigner une couleur dans ce paquet. ``None`` signifie
+#: « conserver la couleur courante du canvas ».
+ColorLike: TypeAlias = Color | str | tuple[float, ...] | list[float] | None
+
+
+def to_color(value: ColorLike) -> Color | None:
+    """Normalise une couleur en ``reportlab.lib.colors.Color``.
+
+    Accepte un ``Color``, un nom CSS ou une chaîne ``"#rrggbb"``, un triplet ou
+    quadruplet de flottants dans ``[0, 1]``. ``None`` est rendu tel quel : il
+    signifie « ne pas toucher à la couleur courante ».
+    """
+    if value is None or isinstance(value, Color):
+        return value
+    if isinstance(value, str):
+        return HexColor(value) if value.startswith("#") else toColor(value)
+    if isinstance(value, tuple | list):
+        if len(value) == 3:
+            return Color(*value)
+        if len(value) == 4:
+            return Color(value[0], value[1], value[2], alpha=value[3])
+        raise ValueError(f"Un tuple de couleur doit avoir 3 ou 4 composantes, reçu {len(value)}")
+    raise TypeError(f"Couleur non convertible : {value!r}")

reportlab_layout/cursor.py

@@ -0,0 +1,58 @@
+"""Curseur de flux : profondeur d'écriture courante dans la page."""
+
+__all__ = ["Cursor"]
+
+
+class Cursor:
+    """Suit la profondeur d'écriture, mesurée depuis le haut de la page.
+
+    La profondeur croît vers le bas, contrairement à l'ordonnée du canvas
+    reportlab. La conversion est du ressort de
+    :class:`~reportlab_layout.geometry.PageGeometry`.
+    """
+
+    def __init__(self, top: float, bottom_depth: float) -> None:
+        self._top = top
+        self._bottom_depth = bottom_depth
+        self._depth = top
+
+    def __repr__(self) -> str:
+        return f"Cursor(depth={self._depth:.1f}, remaining={self.remaining:.1f})"
+
+    @property
+    def depth(self) -> float:
+        """Profondeur courante, en points."""
+        return self._depth
+
+    @depth.setter
+    def depth(self, value: float) -> None:
+        self._depth = float(value)
+
+    @property
+    def top(self) -> float:
+        """Profondeur de départ, c'est-à-dire la marge haute."""
+        return self._top
+
+    @property
+    def bottom_depth(self) -> float:
+        """Profondeur de la limite basse de la zone de contenu."""
+        return self._bottom_depth
+
+    @property
+    def remaining(self) -> float:
+        """Hauteur restante avant la marge basse. Négative en cas de débordement."""
+        return self._bottom_depth - self._depth
+
+    def fits(self, height: float) -> bool:
+        """Vrai si un élément de hauteur ``height`` tient encore sur la page."""
+        return height <= self.remaining
+
+    def reset(self) -> float:
+        """Ramène le curseur en haut de la zone de contenu."""
+        self._depth = self._top
+        return self._depth
+
+    def advance(self, height: float) -> float:
+        """Descend le curseur de ``height`` points et rend la nouvelle profondeur."""
+        self._depth += height
+        return self._depth