From 5b905ed182e9921d997a719da03af0e28e0bf7f6 Mon Sep 17 00:00:00 2001
From: jingeli <benjaminli801@gmail.com>
Date: Fri, 29 Dec 2023 19:11:37 -0600
Subject: [PATCH] PPF-433: also change deprecating attribute docstrings to
 todos

---
 PyPDFForm/wrapper.py     | 21 ++++++++++++++++++---
 docs/examples.md         |  8 ++++----
 tests/test_dropdown.py   |  4 ++--
 tests/test_functional.py | 14 +++++++++++---
 4 files changed, 35 insertions(+), 12 deletions(-)

diff --git a/PyPDFForm/wrapper.py b/PyPDFForm/wrapper.py
index 92312a91..d1283913 100644
--- a/PyPDFForm/wrapper.py
+++ b/PyPDFForm/wrapper.py
@@ -50,7 +50,7 @@ def read(self) -> bytes:
 
     @property
     def elements(self) -> dict:
-        """About to be deprecated."""
+        """ToDo: deprecate this."""
 
         warn(
             DEPRECATION_NOTICE.format(
@@ -197,7 +197,8 @@ def draw_image(
 
         return self
 
-    def generate_schema(self) -> dict:
+    @property
+    def schema(self) -> dict:
         """Generates a json schema for the PDF form template."""
 
         result = {
@@ -209,6 +210,20 @@ def generate_schema(self) -> dict:
 
         return result
 
+    def generate_schema(self) -> dict:
+        """ToDo: deprecate this."""
+
+        warn(
+            DEPRECATION_NOTICE.format(
+                f"{self.__class__.__name__}.generate_schema()",
+                f"{self.__class__.__name__}.schema",
+            ),
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
+        return self.schema
+
     @classmethod
     def register_font(
         cls, font_name: str, ttf_file: Union[bytes, str, BinaryIO]
@@ -221,7 +236,7 @@ def register_font(
 
 
 class PyPDFForm(PdfWrapper):
-    """About to be deprecated."""
+    """ToDo: deprecate this."""
 
     def __init__(
         self,
diff --git a/docs/examples.md b/docs/examples.md
index 36f37713..cf3e8917 100644
--- a/docs/examples.md
+++ b/docs/examples.md
@@ -360,9 +360,9 @@ with open(PATH_TO_OUTPUT_PDF_FORM, "wb+") as output:
     output.write(filled_pdf.read())
 ```
 
-## Generate JSON schema
+## Retrieve JSON schema
 
-This example demos how to generate a JSON schema for a PDF form.
+This example demos how to retrieve a JSON schema for the data used to fill a PDF form.
 
 ```python
 import json
@@ -377,7 +377,7 @@ PATH_TO_DOWNLOADED_SAMPLE_PDF_FORM = os.path.join(
 print(
     json.dumps(PdfWrapper(
         PATH_TO_DOWNLOADED_SAMPLE_PDF_FORM
-    ).generate_schema(), indent=4, sort_keys=True)
+    ).schema, indent=4, sort_keys=True)
 )
 ```
 
@@ -452,7 +452,7 @@ PATH_TO_FILLED_PDF_FORM = os.path.join(
 )  # Change this to where you wish to put your filled PDF form
 
 obj = PdfWrapper(PATH_TO_DOWNLOADED_SAMPLE_PDF_FORM)
-print(obj.pages[0].generate_schema())
+print(obj.pages[0].schema)
 
 with open(PATH_TO_FILLED_PDF_FORM, "wb+") as output:
     output.write(
diff --git a/tests/test_dropdown.py b/tests/test_dropdown.py
index 6ef74dbf..2513f016 100644
--- a/tests/test_dropdown.py
+++ b/tests/test_dropdown.py
@@ -5,8 +5,8 @@
 from PyPDFForm import PdfWrapper
 
 
-def test_generate_schema(sample_template_with_dropdown):
-    schema = PdfWrapper(sample_template_with_dropdown).generate_schema()
+def test_schema(sample_template_with_dropdown):
+    schema = PdfWrapper(sample_template_with_dropdown).schema
 
     for key, value in schema["properties"].items():
         if key == "dropdown_1":
diff --git a/tests/test_functional.py b/tests/test_functional.py
index 09376cf8..40ee36bc 100644
--- a/tests/test_functional.py
+++ b/tests/test_functional.py
@@ -30,6 +30,14 @@ def test_elements_deprecation_notice(template_stream):
         assert r
 
 
+def test_generate_schema_deprecation_notice(template_stream):
+    with pytest.warns(DeprecationWarning) as r:
+        obj = PdfWrapper(template_stream)
+        assert not r
+        assert obj.generate_schema() == obj.schema
+        assert r
+
+
 def test_pypdfform_deprecation_notice(template_stream):
     with pytest.warns(DeprecationWarning) as r:
         assert PyPDFForm(template_stream)
@@ -322,7 +330,7 @@ def test_addition_operator_3_times_sejda(
         assert result.read() == expected
 
 
-def test_generate_schema(sample_template_with_comb_text_field):
+def test_schema(sample_template_with_comb_text_field):
     data = {
         "FirstName": "John",
         "MiddleName": "Joe",
@@ -330,7 +338,7 @@ def test_generate_schema(sample_template_with_comb_text_field):
         "Awesomeness": True,
         "Gender": 0,
     }
-    schema = PdfWrapper(sample_template_with_comb_text_field).generate_schema()
+    schema = PdfWrapper(sample_template_with_comb_text_field).schema
 
     assert schema["type"] == "object"
     properties = schema["properties"]
@@ -369,7 +377,7 @@ def test_generate_schema(sample_template_with_comb_text_field):
 def test_sample_data(sejda_template_complex):
     obj = PdfWrapper(sejda_template_complex)
     try:
-        validate(instance=obj.sample_data, schema=obj.generate_schema())
+        validate(instance=obj.sample_data, schema=obj.schema)
     except ValidationError:
         assert False