PyPDFForm 4.7.6__tar.gz → 4.7.8__tar.gz

{pypdfform-4.7.6 → pypdfform-4.7.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyPDFForm
-Version: 4.7.6
+Version: 4.7.8
 Summary: The Python library for PDF forms.
 Author: Jinge Li
 License-Expression: MIT

{pypdfform-4.7.6 → pypdfform-4.7.8}/PyPDFForm/__init__.py

@@ -22,15 +22,15 @@ PyPDFForm aims to simplify PDF form manipulation, making it accessible to develo
 
 import logging
 
-__version__ = "4.7.6"
-
-from .annotations import Annotations
-from .assets.blank import BlankPage
-from .middleware import Widgets
-from .raw import RawElements
-from .types import PdfArray
-from .widgets import Fields
-from .wrapper import PdfWrapper
+__version__ = "4.7.8"
+
+from .lib.annotations import Annotations
+from .lib.assets.blank import BlankPage
+from .lib.middleware import Widgets
+from .lib.raw import RawElements
+from .lib.types import PdfArray
+from .lib.widgets import Fields
+from .lib.wrapper import PdfWrapper
 
 # TODO: figure out why `Annotation sizes differ:`
 for logger in [

{pypdfform-4.7.6/PyPDFForm → pypdfform-4.7.8/PyPDFForm/lib}/annotations/__init__.py

@@ -34,7 +34,7 @@ class Annotations:
     A container class that provides convenient access to all available PDF annotation types.
 
     This class acts as a namespace for the various `Annotation` classes defined in the
-    `PyPDFForm.annotations` package, making it easier to reference them (e.g., `Annotations.TextAnnotation`).
+    `PyPDFForm.lib.annotations` package, making it easier to reference them (e.g., `Annotations.TextAnnotation`).
     """
 
     TextAnnotation = TextAnnotation

pypdfform-4.7.8/PyPDFForm/lib/deprecation.py

@@ -0,0 +1,74 @@
+# -*- coding: utf-8 -*-
+"""
+A module for handling deprecation notices within the PyPDFForm library.
+
+This module provides utility functions to issue standard DeprecationWarning
+messages, ensuring consistency across the library when notifying users of
+deprecated features.
+"""
+
+from functools import wraps
+from warnings import warn
+
+from .constants import DEPRECATION_NOTICE, DEPRECATION_REPLACE_NOTICE
+
+
+def deprecation_notice(to_replace: str, param: str = "") -> callable:
+    """
+    Issues a DeprecationWarning when a deprecated method is called. Can also be called
+    directly within a method to emit deprecation warnings conditionally.
+
+    Args:
+        to_replace (str): The name of the method to use instead.
+        param (str): Optional parameter name to include in the deprecation notice.
+
+    Returns:
+        callable: A decorator function. The decorator has an `emit_notice` method
+            that can be called directly within a method body for conditional emission.
+
+    Examples:
+        As a decorator (emits on every call)::
+
+            @deprecation_notice(to_replace="new_method")
+            def old_method(self):
+                pass
+
+        As a decorator with a parameter (emits on every call)::
+
+            @deprecation_notice(to_replace="old_method.new_param.", param="old_param")
+            def old_method(self, old_param=None):
+                pass
+
+        Conditionally within a method body::
+
+            def my_method(self, use_legacy=False):
+                if use_legacy:
+                    deprecation_notice(to_replace="", param="use_legacy").emit_notice(self, "my_method")
+                    # legacy logic here
+    """
+
+    def _emit(class_name: str, method_name: str, stacklevel: int):
+        to_deprecate = (
+            f"{class_name}.{method_name}.{param}"
+            if param
+            else f"{class_name}.{method_name}"
+        )
+        notice = DEPRECATION_NOTICE.format(to_deprecate)
+        if to_replace:
+            replacement = f"{class_name}.{to_replace}"
+            notice = f"{notice} {DEPRECATION_REPLACE_NOTICE.format(replacement)}"
+        warn(notice, DeprecationWarning, stacklevel=stacklevel)
+
+    def decorator(func: callable) -> callable:
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            _emit(args[0].__class__.__name__, func.__name__, stacklevel=3)
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    def emit_notice(obj, method_name: str):
+        _emit(obj.__class__.__name__, method_name, stacklevel=4)
+
+    decorator.emit_notice = emit_notice
+    return decorator

{pypdfform-4.7.6/PyPDFForm → pypdfform-4.7.8/PyPDFForm/lib}/middleware/__init__.py

@@ -26,7 +26,7 @@ class Widgets:
     A container class that provides convenient access to all available middleware widget classes.
 
     This class acts as a namespace for the various middleware classes defined in the
-    `PyPDFForm.middleware` package, making it easier to reference them (e.g., `Widgets.Text`).
+    `PyPDFForm.lib.middleware` package, making it easier to reference them (e.g., `Widgets.Text`).
     """
 
     Text = Text

{pypdfform-4.7.6/PyPDFForm → pypdfform-4.7.8/PyPDFForm/lib}/raw/__init__.py

@@ -25,7 +25,7 @@ class RawElements:
     A container class that provides convenient access to all available raw drawable elements.
 
     This class acts as a namespace for the various `Raw` classes defined in the
-    `PyPDFForm.raw` package, making it easier to reference them (e.g., `RawElements.RawText`).
+    `PyPDFForm.lib.raw` package, making it easier to reference them (e.g., `RawElements.RawText`).
     """
 
     RawText = RawText

{pypdfform-4.7.6/PyPDFForm → pypdfform-4.7.8/PyPDFForm/lib}/template.py

@@ -325,7 +325,7 @@ def create_annotations(
 
     This function takes a PDF template and a list of annotation objects, and
     renders each annotation onto its specified page in the PDF. It supports
-    various annotation types defined in the `PyPDFForm.annotations` package.
+    various annotation types defined in the `PyPDFForm.lib.annotations` package.
 
     Args:
         template (bytes): The PDF template to add annotations to.

{pypdfform-4.7.6/PyPDFForm → pypdfform-4.7.8/PyPDFForm/lib}/widgets/__init__.py

@@ -29,7 +29,7 @@ class Fields:
     A container class that provides convenient access to all available PDF form field types.
 
     This class acts as a namespace for the various `Field` classes defined in the
-    `PyPDFForm.widgets` package, making it easier to reference them (e.g., `Fields.TextField`).
+    `PyPDFForm.lib.widgets` package, making it easier to reference them (e.g., `Fields.TextField`).
     """
 
     TextField = TextField

{pypdfform-4.7.6/PyPDFForm → pypdfform-4.7.8/PyPDFForm/lib}/wrapper.py

@@ -712,6 +712,9 @@ class PdfWrapper:
             raise NotImplementedError
 
         if defer:
+            deprecation_notice(to_replace="", param="defer").emit_notice(
+                self, "update_widget_key"
+            )
             self._keys_to_update.append((old_key, new_key, index))
             return self
 

{pypdfform-4.7.6 → pypdfform-4.7.8}/PyPDFForm.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyPDFForm
-Version: 4.7.6
+Version: 4.7.8
 Summary: The Python library for PDF forms.
 Author: Jinge Li
 License-Expression: MIT

pypdfform-4.7.8/PyPDFForm.egg-info/SOURCES.txt

@@ -0,0 +1,72 @@
+LICENSE
+README.md
+pyproject.toml
+PyPDFForm/__init__.py
+PyPDFForm.egg-info/PKG-INFO
+PyPDFForm.egg-info/SOURCES.txt
+PyPDFForm.egg-info/dependency_links.txt
+PyPDFForm.egg-info/requires.txt
+PyPDFForm.egg-info/top_level.txt
+PyPDFForm/lib/__init__.py
+PyPDFForm/lib/adapter.py
+PyPDFForm/lib/constants.py
+PyPDFForm/lib/coordinate.py
+PyPDFForm/lib/deprecation.py
+PyPDFForm/lib/egress.py
+PyPDFForm/lib/filler.py
+PyPDFForm/lib/font.py
+PyPDFForm/lib/hooks.py
+PyPDFForm/lib/image.py
+PyPDFForm/lib/patterns.py
+PyPDFForm/lib/template.py
+PyPDFForm/lib/types.py
+PyPDFForm/lib/utils.py
+PyPDFForm/lib/watermark.py
+PyPDFForm/lib/wrapper.py
+PyPDFForm/lib/annotations/__init__.py
+PyPDFForm/lib/annotations/base.py
+PyPDFForm/lib/annotations/link.py
+PyPDFForm/lib/annotations/stamp.py
+PyPDFForm/lib/annotations/text.py
+PyPDFForm/lib/annotations/text_markup.py
+PyPDFForm/lib/assets/__init__.py
+PyPDFForm/lib/assets/bedrock.py
+PyPDFForm/lib/assets/blank.py
+PyPDFForm/lib/middleware/__init__.py
+PyPDFForm/lib/middleware/base.py
+PyPDFForm/lib/middleware/checkbox.py
+PyPDFForm/lib/middleware/dropdown.py
+PyPDFForm/lib/middleware/image.py
+PyPDFForm/lib/middleware/radio.py
+PyPDFForm/lib/middleware/signature.py
+PyPDFForm/lib/middleware/text.py
+PyPDFForm/lib/raw/__init__.py
+PyPDFForm/lib/raw/circle.py
+PyPDFForm/lib/raw/ellipse.py
+PyPDFForm/lib/raw/image.py
+PyPDFForm/lib/raw/line.py
+PyPDFForm/lib/raw/rect.py
+PyPDFForm/lib/raw/text.py
+PyPDFForm/lib/widgets/__init__.py
+PyPDFForm/lib/widgets/base.py
+PyPDFForm/lib/widgets/checkbox.py
+PyPDFForm/lib/widgets/dropdown.py
+PyPDFForm/lib/widgets/image.py
+PyPDFForm/lib/widgets/radio.py
+PyPDFForm/lib/widgets/signature.py
+PyPDFForm/lib/widgets/text.py
+tests/test_bulk_create_fields.py
+tests/test_create_widget.py
+tests/test_draw_elements.py
+tests/test_dropdown.py
+tests/test_extract_middleware_attributes.py
+tests/test_fill_max_length_text_field.py
+tests/test_font_widths.py
+tests/test_functional.py
+tests/test_generate_appearance_streams.py
+tests/test_js.py
+tests/test_need_appearances.py
+tests/test_paragraph.py
+tests/test_signature.py
+tests/test_use_full_widget_name.py
+tests/test_widget_attr_trigger.py

{pypdfform-4.7.6 → pypdfform-4.7.8}/tests/test_font_widths.py

@@ -13,10 +13,10 @@ from fontTools.ttLib import TTLibError
 from pypdf import PdfWriter
 
 from PyPDFForm import PdfWrapper
-from PyPDFForm.constants import (DEFAULT_ASSUMED_GLYPH_WIDTH, DR,
-                                 ENCODING_TABLE_SIZE, AcroForm, Font,
-                                 FontDescriptor, MissingWidth, Widths)
-from PyPDFForm.font import compute_font_glyph_widths
+from PyPDFForm.lib.constants import (DEFAULT_ASSUMED_GLYPH_WIDTH, DR,
+                                     ENCODING_TABLE_SIZE, AcroForm, Font,
+                                     FontDescriptor, MissingWidth, Widths)
+from PyPDFForm.lib.font import compute_font_glyph_widths
 
 
 @pytest.fixture
@@ -72,7 +72,7 @@ def test_compute_font_widths_raises_for_invalid_ttf():
 
 
 def test_compute_font_glyph_widths_with_missing_tables():
-    with patch("PyPDFForm.font.FT_TTFont") as mock_ttfont:
+    with patch("PyPDFForm.lib.font.FT_TTFont") as mock_ttfont:
         mock_font = MagicMock()
         mock_font.get.side_effect = lambda table: None
         mock_ttfont.return_value = mock_font

{pypdfform-4.7.6 → pypdfform-4.7.8}/tests/test_functional.py

@@ -7,10 +7,10 @@ import pytest
 from jsonschema import ValidationError, validate
 
 from PyPDFForm import Annotations, BlankPage, Fields, PdfArray, PdfWrapper
-from PyPDFForm.constants import DA, UNIQUE_SUFFIX_LENGTH, T, V
-from PyPDFForm.deprecation import deprecation_notice
-from PyPDFForm.middleware.base import Widget
-from PyPDFForm.template import get_widgets_by_page
+from PyPDFForm.lib.constants import DA, UNIQUE_SUFFIX_LENGTH, T, V
+from PyPDFForm.lib.deprecation import deprecation_notice
+from PyPDFForm.lib.middleware.base import Widget
+from PyPDFForm.lib.template import get_widgets_by_page
 
 
 def test_deprecation_warning():
@@ -27,6 +27,70 @@ def test_deprecation_warning():
         assert obj.old_method() == "result"
 
 
+def test_deprecation_warning_with_param():
+    class MockClass:
+        @deprecation_notice(to_replace="old_method.new_param", param="old_param")
+        def old_method(self):
+            return "result"
+
+    obj = MockClass()
+    with pytest.warns(
+        DeprecationWarning,
+        match="MockClass.old_method.old_param will be deprecated soon. Use MockClass.old_method.new_param instead.",
+    ):
+        assert obj.old_method() == "result"
+
+
+def test_deprecation_warning_empty_replace():
+    class MockClass:
+        @deprecation_notice(to_replace="")
+        def old_method(self):
+            return "result"
+
+    obj = MockClass()
+    with pytest.warns(
+        DeprecationWarning,
+        match="MockClass.old_method will be deprecated soon.",
+    ) as record:
+        assert obj.old_method() == "result"
+    assert "Use" not in str(record[0].message)
+
+
+def test_deprecation_warning_direct_call():
+    class MockClass:
+        def my_method(self, use_legacy=False):
+            if use_legacy:
+                deprecation_notice(to_replace="", param="use_legacy").emit_notice(
+                    self, "my_method"
+                )
+            return "result"
+
+    obj = MockClass()
+    assert obj.my_method(use_legacy=False) == "result"
+    with pytest.warns(
+        DeprecationWarning,
+        match="MockClass.my_method.use_legacy will be deprecated soon.",
+    ):
+        assert obj.my_method(use_legacy=True) == "result"
+
+
+def test_deprecation_warning_direct_call_with_replace():
+    class MockClass:
+        def my_method(self, use_legacy=False):
+            if use_legacy:
+                deprecation_notice(
+                    to_replace="my_method.new_param", param="use_legacy"
+                ).emit_notice(self, "my_method")
+            return "result"
+
+    obj = MockClass()
+    with pytest.warns(
+        DeprecationWarning,
+        match="MockClass.my_method.use_legacy will be deprecated soon. Use MockClass.my_method.new_param instead.",
+    ):
+        assert obj.my_method(use_legacy=True) == "result"
+
+
 def test_base_schema_definition():
     assert Widget("foo").schema_definition == {}
 

pypdfform-4.7.6/PyPDFForm/deprecation.py

@@ -1,43 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-A module for handling deprecation notices within the PyPDFForm library.
-
-This module provides utility functions to issue standard DeprecationWarning
-messages, ensuring consistency across the library when notifying users of
-deprecated features.
-"""
-
-from functools import wraps
-from warnings import warn
-
-from .constants import DEPRECATION_NOTICE, DEPRECATION_REPLACE_NOTICE
-
-
-def deprecation_notice(to_replace: str) -> callable:
-    """
-    A decorator that issues a DeprecationWarning when a deprecated method is called.
-
-    Args:
-        to_replace: The name of the method to use instead.
-
-    Returns:
-        callable: A decorator function.
-    """
-
-    def decorator(func: callable) -> callable:
-        @wraps(func)
-        def wrapper(*args, **kwargs):
-            class_name = args[0].__class__.__name__
-            method_name = func.__name__
-            to_deprecate = f"{class_name}.{method_name}"
-            replacement = f"{class_name}.{to_replace}"
-            warn(
-                f"{DEPRECATION_NOTICE.format(to_deprecate)} {DEPRECATION_REPLACE_NOTICE.format(replacement)}",
-                DeprecationWarning,
-                stacklevel=2,
-            )
-            return func(*args, **kwargs)
-
-        return wrapper
-
-    return decorator

pypdfform-4.7.6/PyPDFForm.egg-info/SOURCES.txt

@@ -1,71 +0,0 @@
-LICENSE
-README.md
-pyproject.toml
-PyPDFForm/__init__.py
-PyPDFForm/adapter.py
-PyPDFForm/constants.py
-PyPDFForm/coordinate.py
-PyPDFForm/deprecation.py
-PyPDFForm/egress.py
-PyPDFForm/filler.py
-PyPDFForm/font.py
-PyPDFForm/hooks.py
-PyPDFForm/image.py
-PyPDFForm/patterns.py
-PyPDFForm/template.py
-PyPDFForm/types.py
-PyPDFForm/utils.py
-PyPDFForm/watermark.py
-PyPDFForm/wrapper.py
-PyPDFForm.egg-info/PKG-INFO
-PyPDFForm.egg-info/SOURCES.txt
-PyPDFForm.egg-info/dependency_links.txt
-PyPDFForm.egg-info/requires.txt
-PyPDFForm.egg-info/top_level.txt
-PyPDFForm/annotations/__init__.py
-PyPDFForm/annotations/base.py
-PyPDFForm/annotations/link.py
-PyPDFForm/annotations/stamp.py
-PyPDFForm/annotations/text.py
-PyPDFForm/annotations/text_markup.py
-PyPDFForm/assets/__init__.py
-PyPDFForm/assets/bedrock.py
-PyPDFForm/assets/blank.py
-PyPDFForm/middleware/__init__.py
-PyPDFForm/middleware/base.py
-PyPDFForm/middleware/checkbox.py
-PyPDFForm/middleware/dropdown.py
-PyPDFForm/middleware/image.py
-PyPDFForm/middleware/radio.py
-PyPDFForm/middleware/signature.py
-PyPDFForm/middleware/text.py
-PyPDFForm/raw/__init__.py
-PyPDFForm/raw/circle.py
-PyPDFForm/raw/ellipse.py
-PyPDFForm/raw/image.py
-PyPDFForm/raw/line.py
-PyPDFForm/raw/rect.py
-PyPDFForm/raw/text.py
-PyPDFForm/widgets/__init__.py
-PyPDFForm/widgets/base.py
-PyPDFForm/widgets/checkbox.py
-PyPDFForm/widgets/dropdown.py
-PyPDFForm/widgets/image.py
-PyPDFForm/widgets/radio.py
-PyPDFForm/widgets/signature.py
-PyPDFForm/widgets/text.py
-tests/test_bulk_create_fields.py
-tests/test_create_widget.py
-tests/test_draw_elements.py
-tests/test_dropdown.py
-tests/test_extract_middleware_attributes.py
-tests/test_fill_max_length_text_field.py
-tests/test_font_widths.py
-tests/test_functional.py
-tests/test_generate_appearance_streams.py
-tests/test_js.py
-tests/test_need_appearances.py
-tests/test_paragraph.py
-tests/test_signature.py
-tests/test_use_full_widget_name.py
-tests/test_widget_attr_trigger.py