fpdf2: improve text_align types and .table() method signature (#12123)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

stubs/fpdf2/fpdf/fpdf.pyi

@@ -25,9 +25,11 @@ from .enums import (
     RenderStyle,
     TableBordersLayout,
     TableCellFillMode,
+    TableHeadingsDisplay,
     TextDirection,
     TextMarkupType,
     TextMode as TextMode,
+    VAlign,
     WrapMode as WrapMode,
     XPos as XPos,
     YPos as YPos,
@@ -41,14 +43,14 @@ from .image_datastructures import (
     ImageInfo as ImageInfo,
     RasterImageInfo as RasterImageInfo,
     VectorImageInfo as VectorImageInfo,
-    _AlignLiteral,
+    _TextAlign,
 )
 from .output import OutputProducer, PDFPage
 from .recorder import FPDFRecorder
 from .structure_tree import StructureTreeBuilder
 from .syntax import DestinationXYZ
 from .table import Table
-from .util import _Unit
+from .util import Padding, _Unit
 
 __all__ = [
     "FPDF",
@@ -489,7 +491,7 @@ class FPDF(GraphicsStateMixin):
         ncols: int = 1,
         gutter: float = 10,
         balance: bool = False,
-        text_align: Align | _AlignLiteral = "LEFT",
+        text_align: str | _TextAlign | tuple[_TextAlign | str, ...] = "LEFT",
         line_height: float = 1,
         l_margin: float | None = None,
         r_margin: float | None = None,
@@ -570,17 +572,26 @@ class FPDF(GraphicsStateMixin):
         self,
         rows: Iterable[Incomplete] = (),
         *,
-        align: str | Align = "CENTER",
+        # Keep in sync with `fpdf.table.Table`:
+        align: str | _TextAlign = "CENTER",
+        v_align: str | VAlign = "MIDDLE",
         borders_layout: str | TableBordersLayout = ...,
         cell_fill_color: int | tuple[Incomplete, ...] | DeviceGray | DeviceRGB | None = None,
         cell_fill_mode: str | TableCellFillMode = ...,
         col_widths: int | tuple[int, ...] | None = None,
         first_row_as_headings: bool = True,
+        gutter_height: float = 0,
+        gutter_width: float = 0,
         headings_style: FontFace = ...,
         line_height: int | None = None,
         markdown: bool = False,
-        text_align: str | Align = "JUSTIFY",
+        text_align: str | _TextAlign | tuple[str | _TextAlign, ...] = "JUSTIFY",
         width: int | None = None,
+        wrapmode: WrapMode = ...,
+        padding: float | Padding | None = None,
+        outer_border_width: float | None = None,
+        num_heading_rows: int = 1,
+        repeat_headings: TableHeadingsDisplay | int = 1,
     ) -> _GeneratorContextManager[Table]: ...
     @overload
     def output(  # type: ignore[overload-overlap]

stubs/fpdf2/fpdf/image_datastructures.pyi

@@ -31,6 +31,7 @@ _AlignLiteral: TypeAlias = Literal[
     "r",
     "j",
 ]
+_TextAlign: TypeAlias = Align | _AlignLiteral
 
 class ImageInfo(dict[str, Any]):
     @property
@@ -43,7 +44,7 @@ class ImageInfo(dict[str, Any]):
     def rendered_height(self) -> int: ...
     def scale_inside_box(self, x: float, y: float, w: float, h: float) -> tuple[float, float, float, float]: ...
     @staticmethod
-    def x_by_align(x: Align | _AlignLiteral, w: float, pdf: FPDF, keep_aspect_ratio: Literal[False]) -> float: ...
+    def x_by_align(x: _TextAlign, w: float, pdf: FPDF, keep_aspect_ratio: Literal[False]) -> float: ...
 
 class RasterImageInfo(ImageInfo):
     def size_in_document_units(self, w: float, h: float, scale=1) -> tuple[float, float]: ...

stubs/fpdf2/fpdf/table.pyi

@@ -10,6 +10,7 @@ from .drawing import DeviceGray, DeviceRGB
 from .enums import Align, TableBordersLayout, TableCellFillMode, TableHeadingsDisplay, TableSpan, VAlign, WrapMode
 from .fonts import FontFace
 from .fpdf import FPDF
+from .image_datastructures import _TextAlign
 from .util import Padding
 
 DEFAULT_HEADINGS_STYLE: FontFace
@@ -22,7 +23,8 @@ class Table:
         fpdf: FPDF,
         rows: Iterable[str] = (),
         *,
-        align: str | Align = "CENTER",
+        # Keep in sync with `fpdf.fpdf.FPDF.table`:
+        align: str | _TextAlign = "CENTER",
         v_align: str | VAlign = "MIDDLE",
         borders_layout: str | TableBordersLayout = ...,
         cell_fill_color: int | tuple[Incomplete, ...] | DeviceGray | DeviceRGB | None = None,
@@ -34,7 +36,7 @@ class Table:
         headings_style: FontFace = ...,
         line_height: int | None = None,
         markdown: bool = False,
-        text_align: str | Align = "JUSTIFY",
+        text_align: str | _TextAlign | tuple[str | _TextAlign, ...] = "JUSTIFY",
         width: int | None = None,
         wrapmode: WrapMode = ...,
         padding: float | Padding | None = None,

stubs/fpdf2/fpdf/text_region.pyi

@@ -4,7 +4,7 @@ from typing import NamedTuple
 from typing_extensions import Self
 
 from .enums import Align, WrapMode
-from .image_datastructures import RasterImageInfo, VectorImageInfo, _AlignLiteral
+from .image_datastructures import RasterImageInfo, VectorImageInfo, _TextAlign
 
 class Extents(NamedTuple):
     left: float
@@ -24,7 +24,7 @@ class LineWrapper(NamedTuple):
 
 class Paragraph:
     pdf: Incomplete
-    text_align: Incomplete
+    text_align: Align
     line_height: Incomplete
     top_margin: Incomplete
     bottom_margin: Incomplete
@@ -34,7 +34,7 @@ class Paragraph:
     def __init__(
         self,
         region,
-        text_align: Incomplete | None = None,
+        text_align: _TextAlign | None = None,
         line_height: Incomplete | None = None,
         top_margin: float = 0,
         bottom_margin: float = 0,
@@ -67,7 +67,7 @@ class ImageParagraph:
         self,
         region,
         name,
-        align: Align | _AlignLiteral | None = None,
+        align: _TextAlign | None = None,
         width: float | None = None,
         height: float | None = None,
         fill_width: bool = False,
@@ -93,7 +93,7 @@ class ParagraphCollectorMixin:
         pdf,
         *args,
         text: str | None = None,
-        text_align: Align | _AlignLiteral = "LEFT",
+        text_align: _TextAlign = "LEFT",
         line_height: float = 1.0,
         print_sh: bool = False,
         skip_leading_spaces: bool = False,
@@ -108,7 +108,7 @@ class ParagraphCollectorMixin:
     def ln(self, h: float | None = None) -> None: ...
     def paragraph(
         self,
-        text_align: Incomplete | None = None,
+        text_align: _TextAlign | None = None,
         line_height: Incomplete | None = None,
         skip_leading_spaces: bool = False,
         top_margin: int = 0,
@@ -119,7 +119,7 @@ class ParagraphCollectorMixin:
     def image(
         self,
         name,
-        align: Align | _AlignLiteral | None = None,
+        align: _TextAlign | None = None,
         width: float | None = None,
         height: float | None = None,
         fill_width: bool = False,