DEP: Rename names to be PEP8-compliant

PdfWriter.get_page: the pageNumber parameter is renamed to page_number
PyPDF2.generic:

* readHexStringFromStream ➔ read_hex_string_from_stream
* TreeObject.emptyTree ➔ TreeObject.empty_tree

xmp:

* XmpInformation.rdfRoot ➔ XmpInformation.rdf_root
* XmpInformation.xmp_createDate ➔ XmpInformation.xmp_create_date
* XmpInformation.xmp_creatorTool ➔ XmpInformation.xmp_creator_tool
* XmpInformation.xmp_metadataDate ➔ XmpInformation.xmp_metadata_date
* XmpInformation.xmp_modifyDate ➔ XmpInformation.xmp_modify_date
* XmpInformation.xmpMetadata ➔ XmpInformation.xmp_metadata
* XmpInformation.xmpmm_documentId ➔ XmpInformation.xmpmm_document_id
* XmpInformation.xmpmm_instanceId ➔ XmpInformation.xmpmm_instance_id

PyPDF2/_writer.py

@@ -215,18 +215,30 @@ def insertPage(self, page: PageObject, index: int = 0) -> None:  # pragma: no co
         deprecate_with_replacement("insertPage", "insert_page")
         self.insert_page(page, index)
 
-    def get_page(self, pageNumber: int) -> PageObject:  # TODO: PEP8
+    def get_page(
+        self, page_number: Optional[int] = None, pageNumber: Optional[int] = None
+    ) -> PageObject:
         """
         Retrieve a page by number from this PDF file.
 
-        :param int pageNumber: The page number to retrieve
+        :param int page_number: The page number to retrieve
             (pages begin at zero)
-        :return: the page at the index given by *pageNumber*
+        :return: the page at the index given by *page_number*
         :rtype: :class:`PageObject<PyPDF2._page.PageObject>`
         """
+        if pageNumber is not None:
+            if page_number is not None:
+                raise ValueError("Please only use the page_number parameter")
+            else:
+                deprecate_with_replacement(
+                    "get_page(pageNumber)", "get_page(page_number)", "4.0.0"
+                )
+                page_number = pageNumber
+        if page_number is None and pageNumber is None:
+            raise ValueError("Please specify the page_number")
         pages = cast(Dict[str, Any], self.get_object(self._pages))
         # XXX: crude hack
-        return pages[PA.KIDS][pageNumber].get_object()
+        return pages[PA.KIDS][page_number].get_object()
 
     def getPage(self, pageNumber: int) -> PageObject:  # pragma: no cover
         """

PyPDF2/filters.py

@@ -76,9 +76,8 @@ def compress(data: bytes) -> bytes:
 class FlateDecode:
     @staticmethod
     def decode(
-        # TODO: PEP8
         data: bytes,
-        decodeParms: Union[None, ArrayObject, DictionaryObject],
+        decodeParms: Union[None, ArrayObject, DictionaryObject],  # TODO: PEP8
     ) -> bytes:
         """
         :param data: flate-encoded data.
@@ -171,9 +170,8 @@ class ASCIIHexDecode:
 
     @staticmethod
     def decode(
-        # TODO: PEP8
         data: str,
-        decodeParms: Union[None, ArrayObject, DictionaryObject] = None,
+        decodeParms: Union[None, ArrayObject, DictionaryObject] = None,  # TODO: PEP8
     ) -> str:
         """
         :param data: a str sequence of hexadecimal-encoded values to be
@@ -289,9 +287,8 @@ def decode(self) -> str:
 
     @staticmethod
     def decode(
-        # TODO: PEP8
         data: bytes,
-        decodeParms: Union[None, ArrayObject, DictionaryObject] = None,
+        decodeParms: Union[None, ArrayObject, DictionaryObject] = None,  # TODO: PEP8
     ) -> str:
         """
         :param data: ``bytes`` or ``str`` text to decode.
@@ -404,8 +401,7 @@ def _get_parameters(
     @staticmethod
     def decode(
         data: bytes,
-        # TODO: PEP8
-        decodeParms: Union[None, ArrayObject, DictionaryObject] = None,
+        decodeParms: Union[None, ArrayObject, DictionaryObject] = None,  # TODO: PEP8
         height: int = 0,
     ) -> bytes:
         parms = CCITTFaxDecode._get_parameters(decodeParms, height)

PyPDF2/generic.py

@@ -357,7 +357,16 @@ def readFromStream(
         return NumberObject.read_from_stream(stream)
 
 
-def readHexStringFromStream(  # TODO: PEP8
+def readHexStringFromStream(
+    stream: StreamType,
+) -> Union["TextStringObject", "ByteStringObject"]:
+    deprecate_with_replacement(
+        "readHexStringFromStream", "read_hex_string_from_stream", "4.0.0"
+    )
+    return read_hex_string_from_stream(stream)
+
+
+def read_hex_string_from_stream(
     stream: StreamType,
 ) -> Union["TextStringObject", "ByteStringObject"]:
     stream.read(1)
@@ -380,7 +389,15 @@ def readHexStringFromStream(  # TODO: PEP8
     return createStringObject(b_(txt))
 
 
-def readStringFromStream(  # TODO: PEP8
+def readStringFromStream(
+    stream: StreamType,
+    forced_encoding: Union[None, str, List[str], Dict[int, str]] = None,
+) -> Union["TextStringObject", "ByteStringObject"]:
+    deprecate_with_replacement("readStringFromStream", "read_string_from_stream")
+    return read_string_from_stream(stream, forced_encoding)
+
+
+def read_string_from_stream(
     stream: StreamType,
     forced_encoding: Union[None, str, List[str], Dict[int, str]] = None,
 ) -> Union["TextStringObject", "ByteStringObject"]:
@@ -941,7 +958,10 @@ def remove_child(self, child: Any) -> None:
             del child_obj[NameObject("/Prev")]
 
     def emptyTree(self) -> None:
-        # TODO: Missing rename
+        deprecate_with_replacement("emptyTree", "empty_tree", "4.0.0")
+        self.empty_tree()
+
+    def empty_tree(self) -> None:
         for child in self:
             child_obj = child.get_object()
             del child_obj[NameObject("/Parent")]
@@ -1251,13 +1271,13 @@ def read_object(
         if peek == b_("<<"):
             return DictionaryObject.read_from_stream(stream, pdf, forced_encoding)
         else:
-            return readHexStringFromStream(stream)
+            return read_hex_string_from_stream(stream)
     elif idx == 2:
         return ArrayObject.read_from_stream(stream, pdf, forced_encoding)
     elif idx == 3 or idx == 4:
         return BooleanObject.read_from_stream(stream)
     elif idx == 5:
-        return readStringFromStream(stream, forced_encoding)
+        return read_string_from_stream(stream, forced_encoding)
     elif idx == 6:
         return NullObject.read_from_stream(stream)
     elif idx == 7:

PyPDF2/xmp.py

@@ -204,11 +204,16 @@ class XmpInformation(PdfObject):
     def __init__(self, stream: ContentStream) -> None:
         self.stream = stream
         doc_root: Document = parseString(self.stream.get_data())
-        self.rdfRoot: XmlElement = doc_root.getElementsByTagNameNS(  # TODO: PEP8
+        self.rdf_root: XmlElement = doc_root.getElementsByTagNameNS(
             RDF_NAMESPACE, "RDF"
         )[0]
         self.cache: Dict[Any, Any] = {}
 
+    @property
+    def rdfRoot(self) -> XmlElement:
+        deprecate_with_replacement("rdfRoot", "rdf_root", "4.0.0")
+        return self.rdf_root
+
     def write_to_stream(
         self, stream: StreamType, encryption_key: Union[None, str, bytes]
     ) -> None:
@@ -226,7 +231,7 @@ def writeToStream(
         self.write_to_stream(stream, encryption_key)
 
     def get_element(self, about_uri: str, namespace: str, name: str) -> Iterator[Any]:
-        for desc in self.rdfRoot.getElementsByTagNameNS(RDF_NAMESPACE, "Description"):
+        for desc in self.rdf_root.getElementsByTagNameNS(RDF_NAMESPACE, "Description"):
             if desc.getAttributeNS(RDF_NAMESPACE, "about") == about_uri:
                 attr = desc.getAttributeNodeNS(namespace, name)
                 if attr is not None:
@@ -245,7 +250,7 @@ def getElement(
         return self.get_element(aboutUri, namespace, name)
 
     def get_nodes_in_namespace(self, about_uri: str, namespace: str) -> Iterator[Any]:
-        for desc in self.rdfRoot.getElementsByTagNameNS(RDF_NAMESPACE, "Description"):
+        for desc in self.rdf_root.getElementsByTagNameNS(RDF_NAMESPACE, "Description"):
             if desc.getAttributeNS(RDF_NAMESPACE, "about") == about_uri:
                 for i in range(desc.attributes.length):
                     attr = desc.attributes.item(i)
@@ -370,26 +375,43 @@ def _get_text(self, element: XmlElement) -> str:
     The name of the tool that created the PDF document.
     """
 
-    # TODO: PEP8
-    xmp_createDate = property(
+    xmp_create_date = property(
         _getter_single(XMP_NAMESPACE, "CreateDate", _converter_date)
     )
     """
     The date and time the resource was originally created.  The date and
     time are returned as a UTC datetime.datetime object.
     """
 
-    # TODO: PEP8
-    xmp_modifyDate = property(
+    @property
+    def xmp_createDate(self):
+        deprecate_with_replacement("xmp_createDate", "xmp_create_date")
+        return self.xmp_create_date
+
+    @xmp_createDate.setter
+    def xmp_createDate(self, value):
+        deprecate_with_replacement("xmp_createDate", "xmp_create_date")
+        self.xmp_create_date = value
+
+    xmp_modify_date = property(
         _getter_single(XMP_NAMESPACE, "ModifyDate", _converter_date)
     )
     """
     The date and time the resource was last modified.  The date and time
     are returned as a UTC datetime.datetime object.
     """
 
-    # TODO: PEP8
-    xmp_metadataDate = property(
+    @property
+    def xmp_modifyDate(self):
+        deprecate_with_replacement("xmp_modifyDate", "xmp_modify_date")
+        return self.xmp_modify_date
+
+    @xmp_modifyDate.setter
+    def xmp_modifyDate(self, value):
+        deprecate_with_replacement("xmp_modifyDate", "xmp_modify_date")
+        self.xmp_modify_date = value
+
+    xmp_metadata_date = property(
         _getter_single(XMP_NAMESPACE, "MetadataDate", _converter_date)
     )
     """
@@ -398,25 +420,62 @@ def _get_text(self, element: XmlElement) -> str:
     object.
     """
 
-    # TODO: PEP8
-    xmp_creatorTool = property(_getter_single(XMP_NAMESPACE, "CreatorTool"))
+    @property
+    def xmp_metadataDate(self):
+        deprecate_with_replacement("xmp_metadataDate", "xmp_metadata_date")
+        return self.xmp_metadata_date
+
+    @xmp_metadataDate.setter
+    def xmp_metadataDate(self, value):
+        deprecate_with_replacement("xmp_metadataDate", "xmp_metadata_date")
+        self.xmp_metadata_date = value
+
+    xmp_creator_tool = property(_getter_single(XMP_NAMESPACE, "CreatorTool"))
     """
     The name of the first known tool used to create the resource.
     """
 
-    # TODO: PEP8
-    xmpmm_documentId = property(_getter_single(XMPMM_NAMESPACE, "DocumentID"))
+    @property
+    def xmp_creatorTool(self):
+        deprecate_with_replacement("xmp_creatorTool", "xmp_creator_tool")
+        return self.xmp_creator_tool
+
+    @xmp_creatorTool.setter
+    def xmp_creatorTool(self, value):
+        deprecate_with_replacement("xmp_creatorTool", "xmp_creator_tool")
+        self.xmp_creator_tool = value
+
+    xmpmm_document_id = property(_getter_single(XMPMM_NAMESPACE, "DocumentID"))
     """
     The common identifier for all versions and renditions of this resource.
     """
 
-    # TODO: PEP8
-    xmpmm_instanceId = property(_getter_single(XMPMM_NAMESPACE, "InstanceID"))
+    @property
+    def xmpmm_documentId(self):
+        deprecate_with_replacement("xmpmm_documentId", "xmpmm_document_id")
+        return self.xmpmm_document_id
+
+    @xmpmm_documentId.setter
+    def xmpmm_documentId(self, value):
+        deprecate_with_replacement("xmpmm_documentId", "xmpmm_document_id")
+        self.xmpmm_document_id = value
+
+    xmpmm_instance_id = property(_getter_single(XMPMM_NAMESPACE, "InstanceID"))
     """
     An identifier for a specific incarnation of a document, updated each
     time a file is saved.
     """
 
+    @property
+    def xmpmm_instanceId(self):
+        deprecate_with_replacement("xmpmm_instanceId", "xmpmm_instance_id")
+        return self.xmpmm_instance_id
+
+    @xmpmm_instanceId.setter
+    def xmpmm_instanceId(self, value):
+        deprecate_with_replacement("xmpmm_instanceId", "xmpmm_instance_id")
+        self.xmpmm_instance_id = value
+
     @property
     def custom_properties(self) -> Dict[Any, Any]:
         """

make_changelog.py

@@ -20,7 +20,7 @@ def main(changelog_path: str):
     changes = get_formatted_changes(git_tag)
     print("-" * 80)
     print(changes)
-    # TODO: Write changes to changelog
+
     new_version = version_bump(git_tag)
     today = datetime.now()
     header = f"Version {new_version}, {today:%Y-%m-%d}\n"

tests/test_generic.py

@@ -23,9 +23,9 @@
     TreeObject,
     createStringObject,
     encode_pdfdocencoding,
+    read_hex_string_from_stream,
     read_object,
-    readHexStringFromStream,
-    readStringFromStream,
+    read_string_from_stream,
 )
 
 TESTS_ROOT = os.path.abspath(os.path.dirname(__file__))
@@ -115,43 +115,43 @@ def test_indirect_object_premature(value):
 
 def test_readHexStringFromStream():
     stream = BytesIO(b"a1>")
-    assert readHexStringFromStream(stream) == "\x10"
+    assert read_hex_string_from_stream(stream) == "\x10"
 
 
 def test_readHexStringFromStream_exception():
     stream = BytesIO(b"")
     with pytest.raises(PdfStreamError) as exc:
-        readHexStringFromStream(stream)
+        read_hex_string_from_stream(stream)
     assert exc.value.args[0] == "Stream has ended unexpectedly"
 
 
 def test_readStringFromStream_exception():
     stream = BytesIO(b"x")
     with pytest.raises(PdfStreamError) as exc:
-        readStringFromStream(stream)
+        read_string_from_stream(stream)
     assert exc.value.args[0] == "Stream has ended unexpectedly"
 
 
 def test_readStringFromStream_not_in_escapedict_no_digit():
     stream = BytesIO(b"x\\y")
     with pytest.raises(PdfReadError) as exc:
-        readStringFromStream(stream)
+        read_string_from_stream(stream)
     assert exc.value.args[0] == "Stream has ended unexpectedly"
 
 
 def test_readStringFromStream_multichar_eol():
     stream = BytesIO(b"x\\\n )")
-    assert readStringFromStream(stream) == " "
+    assert read_string_from_stream(stream) == " "
 
 
 def test_readStringFromStream_multichar_eol2():
     stream = BytesIO(b"x\\\n\n)")
-    assert readStringFromStream(stream) == ""
+    assert read_string_from_stream(stream) == ""
 
 
 def test_readStringFromStream_excape_digit():
     stream = BytesIO(b"x\\1a )")
-    assert readStringFromStream(stream) == "\x01 "
+    assert read_string_from_stream(stream) == "\x01 "
 
 
 def test_NameObject():
@@ -179,7 +179,7 @@ def test_destination_fit_r():
     assert d.top == FloatObject(0)
     assert d.bottom == FloatObject(0)
     assert list(d) == []
-    d.emptyTree()
+    d.empty_tree()
 
 
 def test_destination_fit_v():
@@ -401,4 +401,4 @@ def test_remove_child_in_tree():
     tree.add_child(obj, writer)
     tree.remove_child(obj)
     tree.add_child(obj, writer)
-    tree.emptyTree()
+    tree.empty_tree()

tests/test_xmp.py

@@ -72,7 +72,7 @@ def test_regression_issue774():
 def test_regression_issue914():
     path = os.path.join(RESOURCE_ROOT, "issue-914-xmp-data.pdf")
     reader = PdfReader(path)
-    assert reader.xmp_metadata.xmp_modifyDate == datetime(2022, 4, 9, 15, 22, 43)
+    assert reader.xmp_metadata.xmp_modify_date == datetime(2022, 4, 9, 15, 22, 43)
 
 
 @pytest.mark.parametrize(