Source code

Download source archive ↓

src/pypdf/generic/_fit.py

1from collections.abc import Sequence
2from typing import Any
3
4from ._base import is_null_or_none
5
6
7class Fit:
8    def __init__(
9        self, fit_type: str, fit_args: Sequence[float | Any | None] = ()
10    ) -> None:
11        from ._base import FloatObject, NameObject, NullObject, NumberObject  # noqa: PLC0415
12
13        self.fit_type = NameObject(fit_type)
14        self.fit_args: list[NullObject | FloatObject | NumberObject] = [
15            NullObject() if is_null_or_none(a) else FloatObject(a) for a in fit_args
16        ]
17
18    @classmethod
19    def xyz(
20        cls,
21        left: float | None = None,
22        top: float | None = None,
23        zoom: float | None = None,
24    ) -> "Fit":
25        """
26        Display the page designated by page, with the coordinates (left, top)
27        positioned at the upper-left corner of the window and the contents
28        of the page magnified by the factor zoom.
29
30        A null value for any of the parameters left, top, or zoom specifies
31        that the current value of that parameter is to be retained unchanged.
32
33        A zoom value of 0 has the same meaning as a null value.
34
35        Args:
36            left:
37            top:
38            zoom:
39
40        Returns:
41            The created fit object.
42
43        """
44        return Fit(fit_type="/XYZ", fit_args=(left, top, zoom))
45
46    @classmethod
47    def fit(cls) -> "Fit":
48        """
49        Display the page designated by page, with its contents magnified just
50        enough to fit the entire page within the window both horizontally and
51        vertically.
52
53        If the required horizontal and vertical magnification factors are
54        different, use the smaller of the two, centering the page within the
55        window in the other dimension.
56        """
57        return Fit(fit_type="/Fit")
58
59    @classmethod
60    def fit_horizontally(cls, top: float | None = None) -> "Fit":
61        """
62        Display the page designated by page, with the vertical coordinate top
63        positioned at the top edge of the window and the contents of the page
64        magnified just enough to fit the entire width of the page within the
65        window.
66
67        A null value for ``top`` specifies that the current value of that
68        parameter is to be retained unchanged.
69
70        Args:
71            top:
72
73        Returns:
74            The created fit object.
75
76        """
77        return Fit(fit_type="/FitH", fit_args=(top,))
78
79    @classmethod
80    def fit_vertically(cls, left: float | None = None) -> "Fit":
81        return Fit(fit_type="/FitV", fit_args=(left,))
82
83    @classmethod
84    def fit_rectangle(
85        cls,
86        left: float | None = None,
87        bottom: float | None = None,
88        right: float | None = None,
89        top: float | None = None,
90    ) -> "Fit":
91        """
92        Display the page designated by page, with its contents magnified
93        just enough to fit the rectangle specified by the coordinates
94        left, bottom, right, and top entirely within the window
95        both horizontally and vertically.
96
97        If the required horizontal and vertical magnification factors are
98        different, use the smaller of the two, centering the rectangle within
99        the window in the other dimension.
100
101        A null value for any of the parameters may result in unpredictable
102        behavior.
103
104        Args:
105            left:
106            bottom:
107            right:
108            top:
109
110        Returns:
111            The created fit object.
112
113        """
114        return Fit(fit_type="/FitR", fit_args=(left, bottom, right, top))
115
116    @classmethod
117    def fit_box(cls) -> "Fit":
118        """
119        Display the page designated by page, with its contents magnified just
120        enough to fit its bounding box entirely within the window both
121        horizontally and vertically.
122
123        If the required horizontal and vertical magnification factors are
124        different, use the smaller of the two, centering the bounding box
125        within the window in the other dimension.
126        """
127        return Fit(fit_type="/FitB")
128
129    @classmethod
130    def fit_box_horizontally(cls, top: float | None = None) -> "Fit":
131        """
132        Display the page designated by page, with the vertical coordinate top
133        positioned at the top edge of the window and the contents of the page
134        magnified just enough to fit the entire width of its bounding box
135        within the window.
136
137        A null value for top specifies that the current value of that parameter
138        is to be retained unchanged.
139
140        Args:
141            top:
142
143        Returns:
144            The created fit object.
145
146        """
147        return Fit(fit_type="/FitBH", fit_args=(top,))
148
149    @classmethod
150    def fit_box_vertically(cls, left: float | None = None) -> "Fit":
151        """
152        Display the page designated by page, with the horizontal coordinate
153        left positioned at the left edge of the window and the contents of the
154        page magnified just enough to fit the entire height of its bounding box
155        within the window.
156
157        A null value for left specifies that the current value of that
158        parameter is to be retained unchanged.
159
160        Args:
161            left:
162
163        Returns:
164            The created fit object.
165
166        """
167        return Fit(fit_type="/FitBV", fit_args=(left,))
168
169    def __str__(self) -> str:
170        if not self.fit_args:
171            return f"Fit({self.fit_type})"
172        return f"Fit({self.fit_type}, {self.fit_args})"
173
174
175DEFAULT_FIT = Fit.fit()