DEP: Class, variable, and module names

.github/ISSUE_TEMPLATE/feature-request.md

@@ -15,7 +15,7 @@ Explain briefly what you want to achive.
 How would your feature be used? (Remove this if it is not applicable.)
 
 ```python
-from PyPDF2 import PdfFileReader, PdfFileWriter
+from PyPDF2 import PdfReader, PdfWriter
 
 ...  # your new feature in action!
 ```

CHANGELOG

@@ -1,3 +1,131 @@
+Version 1.28.0, 2022-05-22
+--------------------------
+
+This release adds a lot of deprecation warnings in preparation of the
+PyPDF2 2.0.0 release. The changes are mostly using snake_case function-, method-,
+and variable-names as well as using properties instead of getter-methods.
+
+### Deprecations (DEP)
+
+* Make the `PyPDF2.utils` module private
+* Rename of core classes:
+  * PdfFileReader ➔ PdfReader
+  * PdfFileWriter ➔ PdfWriter
+  * PdfFileMerger ➔ PdfMerger
+* Use PEP8 conventions for function names and parameters
+* If a property and a getter-method are both present, use the property
+
+#### Details
+
+In many places:
+  - getObject ➔ get_object
+  - writeToStream ➔ write_to_stream
+  - readFromStream ➔ read_from_stream
+
+PyPDF2.generic
+  - readObject ➔ read_object
+  - convertToInt ➔ convert_to_int
+  - DocumentInformation.getText ➔ DocumentInformation._get_text :
+    This method should typically not be used; please let me know if you need it.
+
+PdfReader class:
+  - `reader.getPage(pageNumber)` ➔ `reader.pages[page_number]`
+  - `reader.getNumPages()` / `reader.numPages` ➔ `len(reader.pages)`
+  - getDocumentInfo ➔ metadata
+  - flattenedPages attribute ➔ flattened_pages
+  - resolvedObjects attribute ➔ resolved_objects
+  - xrefIndex attribute ➔ xref_index
+  - getNamedDestinations / namedDestinations attribute ➔ named_destinations
+  - getPageLayout / pageLayout ➔ page_layout attribute
+  - getPageMode / pageMode ➔ page_mode attribute
+  - getIsEncrypted / isEncrypted ➔ is_encrypted attribute
+  - getOutlines ➔ get_outlines
+  - readObjectHeader ➔ read_object_header (TODO: read vs get?)
+  - cacheGetIndirectObject ➔ cache_get_indirect_object (TODO: public vs private?)
+  - cacheIndirectObject ➔ cache_indirect_object (TODO: public vs private?)
+  - getDestinationPageNumber ➔ get_destination_page_number
+  - readNextEndLine ➔ read_next_end_line
+  - _zeroXref ➔ _zero_xref
+  - _authenticateUserPassword ➔ _authenticate_user_password
+  - _pageId2Num attribute ➔ _page_id2num
+  - _buildDestination ➔ _build_destination
+  - _buildOutline ➔ _build_outline
+  - _getPageNumberByIndirect(indirectRef) ➔ _get_page_number_by_indirect(indirect_ref)
+  - _getObjectFromStream ➔ _get_object_from_stream
+  - _decryptObject ➔ _decrypt_object
+  - _flatten(..., indirectRef) ➔ _flatten(..., indirect_ref)
+  - _buildField ➔ _build_field
+  - _checkKids ➔ _check_kids
+  - _writeField ➔ _write_field
+  - _write_field(..., fieldAttributes) ➔ _write_field(..., field_attributes)
+  - _read_xref_subsections(..., getEntry, ...) ➔ _read_xref_subsections(..., get_entry, ...)
+
+PdfWriter class:
+  - `writer.getPage(pageNumber)` ➔ `writer.pages[page_number]`
+  - `writer.getNumPages()` ➔ `len(writer.pages)`
+  - addMetadata ➔ add_metadata
+  - addPage ➔ add_page
+  - addBlankPage ➔ add_blank_page
+  - addAttachment(fname, fdata) ➔ add_attachment(filename, data)
+  - insertPage ➔ insert_page
+  - insertBlankPage ➔ insert_blank_page
+  - appendPagesFromReader ➔ append_pages_from_reader
+  - updatePageFormFieldValues ➔ update_page_form_field_values
+  - cloneReaderDocumentRoot ➔ clone_reader_document_root
+  - cloneDocumentFromReader ➔ clone_document_from_reader
+  - getReference ➔ get_reference
+  - getOutlineRoot ➔ get_outline_root
+  - getNamedDestRoot ➔ get_named_dest_root
+  - addBookmarkDestination ➔ add_bookmark_destination
+  - addBookmarkDict ➔ add_bookmark_dict
+  - addBookmark ➔ add_bookmark
+  - addNamedDestinationObject ➔ add_named_destination_object
+  - addNamedDestination ➔ add_named_destination
+  - removeLinks ➔ remove_links
+  - removeImages(ignoreByteStringObject) ➔ remove_images(ignore_byte_string_object)
+  - removeText(ignoreByteStringObject) ➔ remove_text(ignore_byte_string_object)
+  - addURI ➔ add_uri
+  - addLink ➔ add_link
+  - getPage(pageNumber) ➔ get_page(page_number)
+  - getPageLayout / setPageLayout / pageLayout ➔ page_layout attribute
+  - getPageMode / setPageMode / pageMode ➔ page_mode attribute
+  - _addObject ➔ _add_object
+  - _addPage ➔ _add_page
+  - _sweepIndirectReferences ➔ _sweep_indirect_references
+
+PdfMerger class
+  - `__init__` parameter: strict=True ➔ strict=False (the PdfFileMerger still has the old default)
+  - addMetadata ➔ add_metadata
+  - addNamedDestination ➔ add_named_destination
+  - setPageLayout ➔ set_page_layout
+  - setPageMode ➔ set_page_mode
+
+Page class:
+  - artBox / bleedBox/ cropBox/ mediaBox / trimBox ➔ artbox / bleedbox/ cropbox/ mediabox / trimbox
+    - getWidth, getHeight  ➔ width / height
+    - getLowerLeft_x / getUpperLeft_x ➔ left
+    - getUpperRight_x / getLowerRight_x ➔ right
+    - getLowerLeft_y / getLowerRight_y ➔ bottom
+    - getUpperRight_y / getUpperLeft_y ➔ top
+    - getLowerLeft / setLowerLeft ➔ lower_left property
+    - upperRight ➔ upper_right
+  - mergePage ➔ merge_page
+  - rotateClockwise / rotateCounterClockwise ➔ rotate_clockwise
+  - _mergeResources ➔ _merge_resources
+  - _contentStreamRename ➔ _content_stream_rename
+  - _pushPopGS ➔ _push_pop_gs
+  - _addTransformationMatrix ➔ _add_transformation_matrix
+  - _mergePage ➔ _merge_page
+
+XmpInformation class:
+  - getElement(..., aboutUri, ...) ➔ get_element(..., about_uri, ...)
+  - getNodesInNamespace(..., aboutUri, ...) ➔ get_nodes_in_namespace(..., aboutUri, ...)
+  - _getText ➔ _get_text
+
+utils.py:
+  - matrixMultiply ➔ matrix_multiply
+  - RC4_encrypt is moved to the security module
+
 Version 1.27.12, 2022-05-02
 ---------------------------
 

PyPDF2/__init__.py

@@ -1,18 +1,23 @@
-from PyPDF2 import pdf
-from PyPDF2._reader import PdfFileReader
+from PyPDF2._reader import DocumentInformation, PdfFileReader, PdfReader
 from PyPDF2._version import __version__
-from PyPDF2._writer import PdfFileWriter
-from PyPDF2.merger import PdfFileMerger
+from PyPDF2._writer import PdfFileWriter, PdfWriter
+from PyPDF2.merger import PdfFileMerger, PdfMerger
 from PyPDF2.pagerange import PageRange, parse_filename_page_ranges
 from PyPDF2.papersizes import PaperSize
 
+from ._page import Transformation
+
 __all__ = [
     "__version__",
     "PageRange",
     "PaperSize",
+    "DocumentInformation",
     "parse_filename_page_ranges",
-    "pdf",
-    "PdfFileMerger",
-    "PdfFileReader",
-    "PdfFileWriter",
+    "PdfFileMerger",  # will be removed soon; use PdfMerger instead
+    "PdfFileReader",  # will be removed soon; use PdfReader instead
+    "PdfFileWriter",  # will be removed soon; use PdfWriter instead
+    "PdfMerger",
+    "Transformation",
+    "PdfReader",
+    "PdfWriter",
 ]