fpdf2: complete stubs (#8855)

stubs/fpdf2/@tests/stubtest_allowlist.txt

@@ -1,3 +1,6 @@
 # The "dest" argument is unused and will be removed.
 fpdf.FPDF.output
 fpdf.fpdf.FPDF.output
+
+# Unnecessary re-export from codecs
+fpdf.syntax.BOM_UTF16_BE

stubs/fpdf2/METADATA.toml

@@ -1,2 +1,5 @@
 version = "2.5.*"
 requires = ["types-Pillow"]
+
+[tool.stubtest]
+ignore_missing_stub = false

stubs/fpdf2/fpdf/__init__.pyi

@@ -1,10 +1,28 @@
 from pathlib import Path
 
+from .enums import XPos as XPos, YPos as YPos
 from .fpdf import FPDF as FPDF, TitleStyle as TitleStyle
 from .html import HTML2FPDF as HTML2FPDF, HTMLMixin as HTMLMixin
-from .template import Template as Template
+from .prefs import ViewerPreferences as ViewerPreferences
+from .template import FlexTemplate as FlexTemplate, Template as Template
 
 __license__: str
 __version__: str
 FPDF_VERSION: str
 FPDF_FONT_DIR: Path
+
+__all__ = [
+    "__version__",
+    "__license__",
+    "FPDF",
+    "XPos",
+    "YPos",
+    "Template",
+    "FlexTemplate",
+    "TitleStyle",
+    "ViewerPreferences",
+    "HTMLMixin",
+    "HTML2FPDF",
+    "FPDF_VERSION",
+    "FPDF_FONT_DIR",
+]

stubs/fpdf2/fpdf/drawing.pyi

@@ -1,5 +1,5 @@
 import decimal
-from _typeshed import Incomplete
+from _typeshed import Incomplete, Self
 from collections import OrderedDict
 from collections.abc import Generator
 from contextlib import _GeneratorContextManager
@@ -109,6 +109,7 @@ class GraphicsStyle:
     @classmethod
     def merge(cls, parent, child): ...
     def __init__(self) -> None: ...
+    def __deepcopy__(self: Self, memo) -> Self: ...
     @property
     def allow_transparency(self): ...
     @allow_transparency.setter
@@ -302,6 +303,7 @@ class DrawingContext:
 
 class PaintedPath:
     def __init__(self, x: int = ..., y: int = ...) -> None: ...
+    def __deepcopy__(self: Self, memo) -> Self: ...
     @property
     def style(self): ...
     @property
@@ -357,6 +359,7 @@ class GraphicsContext:
     style: GraphicsStyle
     path_items: list[Incomplete]
     def __init__(self) -> None: ...
+    def __deepcopy__(self: Self, memo) -> Self: ...
     @property
     def transform(self): ...
     @transform.setter

stubs/fpdf2/fpdf/enums.pyi

@@ -9,6 +9,10 @@ class DocumentState(IntEnum):
     GENERATING_PAGE: int
     CLOSED: int
 
+class SignatureFlag(IntEnum):
+    SIGNATURES_EXIST: int
+    APPEND_ONLY: int
+
 class CoerciveEnum(Enum):
     @classmethod
     def coerce(cls: type[Self], value: Self | str) -> Self: ...

stubs/fpdf2/fpdf/errors.pyi

@@ -7,3 +7,6 @@ class FPDFPageFormatException(FPDFException):
     unknown: Any
     one: Any
     def __init__(self, argument, unknown: bool = ..., one: bool = ...) -> None: ...
+
+class FPDFUnicodeEncodingException(FPDFException):
+    def __init__(self, text_index, character, font_name) -> None: ...

stubs/fpdf2/fpdf/fpdf.pyi

@@ -11,6 +11,7 @@ from typing_extensions import Literal, TypeAlias
 from PIL import Image
 
 from .actions import Action
+from .drawing import DrawingContext, PaintedPath
 from .enums import (
     Align,
     AnnotationFlag,
@@ -18,15 +19,19 @@ from .enums import (
     Corner,
     FileAttachmentAnnotationName,
     PageLayout,
+    PathPaintRule,
     RenderStyle,
     TextMarkupType,
-    XPos,
-    YPos,
+    TextMode as TextMode,
+    XPos as XPos,
+    YPos as YPos,
 )
 from .recorder import FPDFRecorder
 from .syntax import DestinationXYZ
 from .util import _Unit
 
+__all__ = ["FPDF", "XPos", "YPos", "get_page_format", "TextMode", "TitleStyle", "PAGE_FORMATS"]
+
 _Orientation: TypeAlias = Literal["", "portrait", "p", "P", "landscape", "l", "L"]
 _Format: TypeAlias = Literal["", "a3", "A3", "a4", "A4", "a5", "A5", "letter", "Letter", "legal", "Legal"]
 _FontStyle: TypeAlias = Literal["", "B", "I"]
@@ -61,6 +66,7 @@ class Annotation(NamedTuple):
     embedded_file_name: str | None = ...
     field_type: str | None = ...
     value: str | None = ...
+    def serialize(self, fpdf) -> str: ...
 
 class EmbeddedFile(NamedTuple):
     basename: str
@@ -172,9 +178,13 @@ class FPDF:
     @property
     def is_ttf_font(self) -> bool: ...
     @property
+    def page_mode(self): ...
+    @property
     def epw(self) -> float: ...
     @property
     def eph(self) -> float: ...
+    @property
+    def pages_count(self) -> int: ...
     def set_margin(self, margin: float) -> None: ...
     def set_margins(self, left: float, top: float, right: float = ...) -> None: ...
     l_margin: float
@@ -235,6 +245,12 @@ class FPDF:
     def get_string_width(self, s: str, normalized: bool = ..., markdown: bool = ...) -> float: ...
     def set_line_width(self, width: float) -> None: ...
     def set_page_background(self, background) -> None: ...
+    def drawing_context(self, debug_stream: Incomplete | None = ...) -> _GeneratorContextManager[DrawingContext]: ...
+    def new_path(
+        self, x: float = ..., y: float = ..., paint_rule: PathPaintRule = ..., debug_stream: Incomplete | None = ...
+    ) -> _GeneratorContextManager[PaintedPath]: ...
+    def draw_path(self, path: PaintedPath, debug_stream: Incomplete | None = ...) -> None: ...
+    def set_dash_pattern(self, dash: float = ..., gap: float = ..., phase: float = ...) -> None: ...
     def line(self, x1: float, y1: float, x2: float, y2: float) -> None: ...
     def polyline(
         self, point_list: list[tuple[float, float]], fill: bool = ..., polygon: bool = ..., style: RenderStyle | str | None = ...
@@ -272,6 +288,32 @@ class FPDF:
         rotate_degrees: float = ...,
         style: RenderStyle | str | None = ...,
     ): ...
+    def arc(
+        self,
+        x: float,
+        y: float,
+        a: float,
+        start_angle: float,
+        end_angle: float,
+        b: float | None = ...,
+        inclination: float = ...,
+        clockwise: bool = ...,
+        start_from_center: bool = ...,
+        end_at_center: bool = ...,
+        style: RenderStyle | str | None = ...,
+    ) -> None: ...
+    def solid_arc(
+        self,
+        x: float,
+        y: float,
+        a: float,
+        start_angle: float,
+        end_angle: float,
+        b: float | None = ...,
+        inclination: float = ...,
+        clockwise: bool = ...,
+        style: RenderStyle | str | None = ...,
+    ) -> None: ...
     def add_font(
         self, family: str, style: _FontStyle = ..., fname: str | None = ..., uni: bool | Literal["DEPRECATED"] = ...
     ) -> None: ...
@@ -344,9 +386,29 @@ class FPDF:
         modification_time: datetime.datetime | None = ...,
         page: int | None = ...,
     ) -> Annotation: ...
+    def ink_annotation(
+        self,
+        coords: Iterable[Incomplete],
+        contents: str = ...,
+        title: str = ...,
+        color: Sequence[float] = ...,
+        border_width: int = ...,
+    ) -> Annotation: ...
     def text(self, x: float, y: float, txt: str = ...) -> None: ...
     def rotate(self, angle: float, x: float | None = ..., y: float | None = ...) -> None: ...
     def rotation(self, angle: float, x: float | None = ..., y: float | None = ...) -> _GeneratorContextManager[None]: ...
+    def local_context(
+        self,
+        font_family: Incomplete | None = ...,
+        font_style: Incomplete | None = ...,
+        font_size: Incomplete | None = ...,
+        line_width: Incomplete | None = ...,
+        draw_color: Incomplete | None = ...,
+        fill_color: Incomplete | None = ...,
+        text_color: Incomplete | None = ...,
+        dash_pattern: Incomplete | None = ...,
+        **kwargs,
+    ) -> _GeneratorContextManager[None]: ...
     @property
     def accept_page_break(self) -> bool: ...
     def cell(
@@ -406,10 +468,37 @@ class FPDF:
     @overload
     def output(self, name: str) -> None: ...
     def normalize_text(self, txt: str) -> str: ...
+    def sign_pkcs12(
+        self,
+        pkcs_filepath: str,
+        password: bytes | None = ...,
+        hashalgo: str = ...,
+        contact_info: str | None = ...,
+        location: str | None = ...,
+        signing_time: datetime.datetime | None = ...,
+        reason: str | None = ...,
+        flags: tuple[AnnotationFlag, ...] = ...,
+    ) -> None: ...
+    def sign(
+        self,
+        key,
+        cert,
+        extra_certs: Sequence[Incomplete] = ...,
+        hashalgo: str = ...,
+        contact_info: str | None = ...,
+        location: str | None = ...,
+        signing_time: datetime.datetime | None = ...,
+        reason: str | None = ...,
+        flags: tuple[AnnotationFlag, ...] = ...,
+    ) -> None: ...
+    def file_id(self) -> str: ...
     def interleaved2of5(self, txt, x: float, y: float, w: float = ..., h: float = ...) -> None: ...
     def code39(self, txt, x: float, y: float, w: float = ..., h: float = ...) -> None: ...
     def rect_clip(self, x: float, y: float, w: float, h: float) -> _GeneratorContextManager[None]: ...
+    def elliptic_clip(self, x: float, y: float, w: float, h: float) -> _GeneratorContextManager[None]: ...
+    def round_clip(self, x: float, y: float, r: float) -> _GeneratorContextManager[None]: ...
     def unbreakable(self) -> _GeneratorContextManager[FPDFRecorder]: ...
+    def offset_rendering(self) -> _GeneratorContextManager[FPDFRecorder]: ...
     def insert_toc_placeholder(self, render_toc_function, pages: int = ...) -> None: ...
     def set_section_title_styles(
         self,

stubs/fpdf2/fpdf/html.pyi

@@ -1,6 +1,10 @@
 from html.parser import HTMLParser
 from typing import Any
 
+__author__: str
+__copyright__: str
+__license__: str
+
 LOGGER: Any
 BULLET_WIN1252: str
 DEFAULT_HEADING_SIZES: Any

stubs/fpdf2/fpdf/outline.pyi

@@ -1,3 +1,4 @@
+from _typeshed import Incomplete
 from typing import Any, NamedTuple
 
 from .structure_tree import StructElem
@@ -30,3 +31,5 @@ class OutlineDictionary(PDFObject):
     def __init__(self, **kwargs) -> None: ...
 
 def serialize_outline(sections, first_object_id: int = ..., fpdf: Any | None = ...): ...
+def build_outline(sections, first_object_id, fpdf) -> tuple[Incomplete, Incomplete]: ...
+def outline_as_str(outline, outline_items, fpdf) -> str: ...

stubs/fpdf2/fpdf/syntax.pyi

@@ -1,5 +1,7 @@
+from _typeshed import Incomplete, SupportsItems
 from abc import ABC
-from typing import Any
+from re import Pattern
+from typing import Any, ClassVar
 from typing_extensions import Literal
 
 def clear_empty_fields(d): ...
@@ -25,9 +27,11 @@ class PDFObject:
     def ref(self): ...
     def serialize(self, fpdf: Any | None = ..., obj_dict: Any | None = ...): ...
 
+def build_obj_dict(key_values: SupportsItems[str, Incomplete]) -> dict[str, str]: ...
 def camel_case(snake_case: str) -> str: ...
 
 class PDFString(str):
+    USE_HEX_ENCODING: ClassVar[bool]
     def serialize(self): ...
 
 class PDFArray(list[Any]):
@@ -50,4 +54,5 @@ class DestinationXYZ(Destination):
 class Raw(str): ...
 
 class Name(str):
+    NAME_ESC: ClassVar[Pattern[bytes]]
     def pdf_repr(self) -> str: ...

stubs/fpdf2/fpdf/template.pyi

@@ -1,5 +1,9 @@
 from typing import Any
 
+__author__: str
+__copyright__: str
+__license__: str
+
 class FlexTemplate:
     pdf: Any
     splitting_pdf: Any

stubs/fpdf2/fpdf/util.pyi

@@ -1,10 +1,13 @@
+import datetime
 from collections.abc import Iterable
 from typing import Any
 from typing_extensions import Literal, TypeAlias
 
 _Unit: TypeAlias = Literal["pt", "mm", "cm", "in"]
 
-def enclose_in_parens(s): ...
+def object_id_for_page(page: int) -> int: ...
+def format_date(date: datetime.datetime, with_tz: bool = ...) -> str: ...
+def enclose_in_parens(s: str) -> str: ...
 def escape_parens(s): ...
 def b(s): ...
 def get_scale_factor(unit: _Unit | float) -> float: ...