typing

Author: andersonhc

.github/workflows/continuous-integration-workflow.yml

@@ -70,6 +70,9 @@ jobs:
           pylint fpdf test tutorial/tuto*.py
           bandit -c .banditrc.yml -r contributors/ fpdf/ tutorial/
           semgrep scan --config auto --error --strict --exclude-rule=python.lang.security.insecure-hash-function.insecure-hash-function fpdf
+      - name: Run type checkers 🔎
+        run: |
+          mypy
       - name: Scan project with grype 🔎
         uses: anchore/scan-action@3c9a191a0fbab285ca6b8530b5de5a642cba332f # v7.2.2
         with:

.pre-commit-config.yaml

@@ -23,6 +23,21 @@ repos:
     rev: v1.30.2
     hooks:
       - id: typos
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: 'v1.19.0'
+    hooks:
+      - id: mypy
+        args:
+          - --config-file=./pyproject.toml
+        files: ^fpdf/.*\.py$
+        additional_dependencies:
+          - cryptography
+          - defusedxml
+          - endesive
+          - fonttools
+          - numpy
+          - Pillow
+          - uharfbuzz
   - repo: local
     hooks:
     -   id: no-print-in-sources

fpdf/__init__.py

@@ -15,27 +15,28 @@
 * `fpdf.template.FlexTemplate`
 """
 
-import warnings, sys
+import sys
+import warnings
 
 from .deprecation import WarnOnDeprecatedModuleAttributes
 from .enums import Align, TextMode, XPos, YPos
 from .errors import FPDFException
 from .fonts import FontFace, TextStyle
 from .fpdf import (
     FPDF,
-    TitleStyle,
     FPDF_FONT_DIR as _FPDF_FONT_DIR,
     FPDF_VERSION as _FPDF_VERSION,
+    TitleStyle,
 )
-from .html import HTMLMixin, HTML2FPDF
+from .html import HTML2FPDF, HTMLMixin
 from .prefs import ViewerPreferences
-from .template import Template, FlexTemplate
+from .template import FlexTemplate, Template
 from .util import get_scale_factor
 
 try:
     # This module only exists in PyFPDF, it has been removed in fpdf2 since v2.5.7:
     # pylint: disable=import-self
-    from . import ttfonts
+    from . import ttfonts  # type: ignore[attr-defined]
 
     warnings.warn(
         "You have both PyFPDF & fpdf2 installed. "

fpdf/actions.py

@@ -1,21 +1,35 @@
-from abc import ABC
 import warnings
+from abc import ABC
+from typing import TYPE_CHECKING, Optional, Union
 
 from .syntax import PDFString, build_obj_dict, create_dictionary_string
 
+if TYPE_CHECKING:
+    from .encryption import StandardSecurityHandler
+    from .syntax import Destination
+
 
 class Action(ABC):
-    def __init__(self, next_action=None):
+    def __init__(self, next_action: Optional["Action"] = None) -> None:
         """
         Args:
             next (PDFObject | str): optional reference to another Action to trigger after this one
         """
         self.next = next_action
 
-    def serialize(self, _security_handler=None, _obj_id=None):
+    def serialize(
+        self,
+        _security_handler: Optional["StandardSecurityHandler"] = None,
+        _obj_id: Optional[int] = None,
+    ) -> str:
         raise NotImplementedError
 
-    def _serialize(self, key_values=None, _security_handler=None, _obj_id=None):
+    def _serialize(
+        self,
+        key_values: Optional[dict[str, object]] = None,
+        _security_handler: Optional["StandardSecurityHandler"] = None,
+        _obj_id: Optional[int] = None,
+    ) -> str:
         if key_values is None:
             key_values = {}
         if self.next:
@@ -25,11 +39,15 @@ def _serialize(self, key_values=None, _security_handler=None, _obj_id=None):
 
 
 class URIAction(Action):
-    def __init__(self, uri, next_action=None):
-        super().__init__(next)
+    def __init__(self, uri: str, next_action: Optional[Action] = None) -> None:
+        super().__init__(next_action)
         self.uri = uri
 
-    def serialize(self, _security_handler=None, _obj_id=None):
+    def serialize(
+        self,
+        _security_handler: Optional["StandardSecurityHandler"] = None,
+        _obj_id: Optional[int] = None,
+    ) -> str:
         return super()._serialize(
             {"s": "/URI", "u_r_i": PDFString(self.uri, encrypt=True)},
             _security_handler=_security_handler,
@@ -38,13 +56,17 @@ def serialize(self, _security_handler=None, _obj_id=None):
 
 
 class NamedAction(Action):
-    def __init__(self, action_name, next_action=None):
-        super().__init__(next)
+    def __init__(self, action_name: str, next_action: Optional[Action] = None) -> None:
+        super().__init__(next_action)
         if action_name not in ("NextPage", "PrevPage", "FirstPage", "LastPage"):
             warnings.warn("Non-standard named action added")
         self.action_name = action_name
 
-    def serialize(self, _security_handler=None, _obj_id=None):
+    def serialize(
+        self,
+        _security_handler: Optional["StandardSecurityHandler"] = None,
+        _obj_id: Optional[int] = None,
+    ) -> str:
         return super()._serialize(
             {"s": "/Named", "n": f"/{self.action_name}"},
             _security_handler=_security_handler,
@@ -53,13 +75,19 @@ def serialize(self, _security_handler=None, _obj_id=None):
 
 
 class GoToAction(Action):
-    def __init__(self, dest, next_action=None):
+    def __init__(
+        self, dest: Union[str, "Destination"], next_action: Optional[Action] = None
+    ) -> None:
         super().__init__(next_action)
         if isinstance(dest, str) and dest.startswith("#"):
             dest = PDFString(dest[1:], encrypt=True)
         self.dest = dest
 
-    def serialize(self, _security_handler=None, _obj_id=None):
+    def serialize(
+        self,
+        _security_handler: Optional["StandardSecurityHandler"] = None,
+        _obj_id: Optional[int] = None,
+    ) -> str:
         return super()._serialize(
             {"s": "/GoTo", "d": self.dest},
             _security_handler=_security_handler,
@@ -68,12 +96,18 @@ def serialize(self, _security_handler=None, _obj_id=None):
 
 
 class GoToRemoteAction(Action):
-    def __init__(self, file, dest, next_action=None):
+    def __init__(
+        self, file: str, dest: "Destination", next_action: Optional[Action] = None
+    ) -> None:
         super().__init__(next_action)
         self.file = file
         self.dest = dest
 
-    def serialize(self, _security_handler=None, _obj_id=None):
+    def serialize(
+        self,
+        _security_handler: Optional["StandardSecurityHandler"] = None,
+        _obj_id: Optional[int] = None,
+    ) -> str:
         return super()._serialize(
             {"s": "/GoToR", "f": PDFString(self.file, encrypt=True), "d": self.dest},
             _security_handler=_security_handler,
@@ -84,11 +118,15 @@ def serialize(self, _security_handler=None, _obj_id=None):
 class LaunchAction(Action):
     "As of 2022, this does not seem honored by neither Adobe Acrobat nor Sumatra readers."
 
-    def __init__(self, file, next_action=None):
+    def __init__(self, file: str, next_action: Optional[Action] = None) -> None:
         super().__init__(next_action)
         self.file = file
 
-    def serialize(self, _security_handler=None, _obj_id=None):
+    def serialize(
+        self,
+        _security_handler: Optional["StandardSecurityHandler"] = None,
+        _obj_id: Optional[int] = None,
+    ) -> str:
         return super()._serialize(
             {"s": "/Launch", "f": PDFString(self.file, encrypt=True)},
             _security_handler=_security_handler,

fpdf/annotations.py

@@ -4,7 +4,7 @@
 
 import hashlib
 from datetime import datetime
-from typing import Optional, Tuple, Union
+from typing import TYPE_CHECKING, Any, Optional, Sequence, Union
 
 from .actions import Action
 from .enums import (
@@ -14,18 +14,20 @@
     FileAttachmentAnnotationName,
 )
 from .syntax import (
-    build_obj_dict,
     Destination,
     Name,
     PDFContentStream,
     PDFDate,
     PDFObject,
     PDFString,
+    build_obj_dict,
+    create_dictionary_string as pdf_dict,
+    create_list_string as pdf_list,
+    iobj_ref as pdf_ref,
 )
-from .syntax import create_dictionary_string as pdf_dict
-from .syntax import create_list_string as pdf_list
-from .syntax import iobj_ref as pdf_ref
 
+if TYPE_CHECKING:
+    from .encryption import StandardSecurityHandler
 
 # cf. https://docs.verapdf.org/validation/pdfa-part1/#rule-653-2
 DEFAULT_ANNOT_FLAGS = (AnnotationFlag.PRINT,)
@@ -35,26 +37,26 @@ class AnnotationMixin:
     def __init__(
         self,
         subtype: str,
-        x: int,
-        y: int,
-        width: int,
-        height: int,
-        flags: Union[Tuple[AnnotationFlag], Tuple[str]] = DEFAULT_ANNOT_FLAGS,
-        contents: str = None,
-        dest: Destination = None,
-        action: Action = None,
-        color: tuple = None,
-        modification_time: datetime = None,
-        title: str = None,
-        quad_points: tuple = None,
-        border_width: int = 0,  # PDF readers support: displayed by Acrobat but not Sumatra
-        name: Union[AnnotationName, FileAttachmentAnnotationName] = None,
-        ink_list: Tuple[int] = (),  # for ink annotations
-        file_spec: str = None,
-        field_type: str = None,
-        value=None,
-        default_appearance: str = None,  # for free text annotations
-    ):
+        x: float,
+        y: float,
+        width: float,
+        height: float,
+        flags: tuple[AnnotationFlag | str, ...] = DEFAULT_ANNOT_FLAGS,
+        contents: Optional[str] = None,
+        dest: Optional[Destination | PDFString] = None,
+        action: Optional[Action] = None,
+        color: Optional[tuple[float, float, float]] = None,
+        modification_time: Optional[datetime] = None,
+        title: Optional[str] = None,
+        quad_points: Optional[Sequence[float]] = None,
+        border_width: float = 0,  # PDF readers support: displayed by Acrobat but not Sumatra
+        name: Union[AnnotationName, FileAttachmentAnnotationName, None] = None,
+        ink_list: Optional[tuple[float, ...]] = None,  # for ink annotations
+        file_spec: Optional[Union["FileSpec", str]] = None,
+        field_type: Optional[str] = None,
+        value: Optional[str] = None,
+        default_appearance: Optional[str] = None,  # for free text annotations
+    ) -> None:
         self.type = Name("Annot")
         self.subtype = Name(subtype)
         self.rect = f"[{x:.2f} {y - height:.2f} {x + width:.2f} {y:.2f}]"
@@ -69,14 +71,14 @@ def __init__(
         self.t = PDFString(title, encrypt=True) if title else None
         self.m = PDFDate(modification_time, encrypt=True) if modification_time else None
         self.quad_points = (
-            pdf_list(f"{quad_point:.2f}" for quad_point in quad_points)
+            pdf_list([f"{quad_point:.2f}" for quad_point in quad_points])
             if quad_points
             else None
         )
         self.p = None  # must always be set before calling .serialize()
         self.name = name
         self.ink_list = (
-            ("[" + pdf_list(f"{coord:.2f}" for coord in ink_list) + "]")
+            ("[" + pdf_list([f"{coord:.2f}" for coord in ink_list]) + "]")
             if ink_list
             else None
         )
@@ -87,7 +89,7 @@ def __init__(
 class PDFAnnotation(AnnotationMixin, PDFObject):
     "A PDF annotation that get serialized as an obj<</>>endobj block"
 
-    def __init__(self, *args, **kwargs):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
         super().__init__(*args, **kwargs)
 
 
@@ -115,15 +117,19 @@ class AnnotationDict(AnnotationMixin):
         "d_a",
     )
 
-    def serialize(self, _security_handler=None, _obj_id=None):
+    def serialize(
+        self,
+        _security_handler: Optional["StandardSecurityHandler"] = None,
+        _obj_id: Optional[int] = None,
+    ) -> str:
         obj_dict = build_obj_dict(
             {key: getattr(self, key) for key in dir(self)},
             _security_handler=_security_handler,
             _obj_id=_obj_id,
         )
         return pdf_dict(obj_dict)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         keys = [key for key in dir(self) if not key.startswith("__")]
         d = {key: getattr(self, key) for key in keys}
         d = {key: value for key, value in d.items() if not callable(value)}
@@ -145,7 +151,7 @@ def __init__(
     ):
         super().__init__(contents=contents, compress=compress)
         self.type = Name("EmbeddedFile")
-        params = {"/Size": len(contents)}
+        params: dict[str, object] = {"/Size": len(contents)}
         if creation_date:
             params["/CreationDate"] = PDFDate(creation_date, with_tz=True).serialize()
         if modification_date:
@@ -158,22 +164,22 @@ def __init__(
         if mime_type:
             self.subtype = Name(mime_type)
         self.params = pdf_dict(params)
-        self._basename = basename  # private so that it does not get serialized
-        self._desc = desc  # private so that it does not get serialized
-        self._globally_enclosed = True
-        self._af_relationship = af_relationship
-        self._file_spec = None
+        self._basename: str = basename  # private so that it does not get serialized
+        self._desc: str = desc  # private so that it does not get serialized
+        self._globally_enclosed: bool = True
+        self._af_relationship: Optional[AssociatedFileRelationship] = af_relationship
+        self._file_spec: Optional[FileSpec] = None
 
-    def globally_enclosed(self):
+    def globally_enclosed(self) -> bool:
         return self._globally_enclosed
 
-    def set_globally_enclosed(self, value):
+    def set_globally_enclosed(self, value: bool) -> None:
         self._globally_enclosed = value
 
-    def basename(self):
+    def basename(self) -> str:
         return self._basename
 
-    def file_spec(self):
+    def file_spec(self) -> "FileSpec":
         if not self._file_spec:
             self._file_spec = FileSpec(
                 self, self._basename, self._desc, self._af_relationship
@@ -201,5 +207,5 @@ def __init__(
         self._embedded_file = embedded_file
 
     @property
-    def e_f(self):
+    def e_f(self) -> str:
         return pdf_dict({"/F": pdf_ref(self._embedded_file.id)})