DEP: PEP8-style module, class, and method names (#867)

This commit strives to make the usage for new PyPDF2 users easier by following
PEP8 naming schemes. It's mostly about camelCase method names being converted to
snake_case. Other changes make the public interface of PyPDF2 smaller and thus
easier to discover.

This commit does not introduce any breaking changes as the old modules /
classes / method signatures are still present. They have now deprecation
warnings and the docs show that those are considered deprecated.

If a property and a getter-method are both present, use the property.

Module level changes
--------------------

- utils ➔ _utils: The module is renamed to '_utils' to indicate that it should
                not be used by PyPDF2 users. It's only meant for PyPDF2 itself.
- The 'pdf' module was removed. Most classes / functions are now either in
  '_utils' or in 'generic'.


Core classes
------------

- PdfFileReader➔ PdfReader (strict=False is new default)
- PdfFileWriter➔ PdfWriter
- PdfFileMerger➔ PdfMerger (strict=False is new default)

PdfReader
---------

- writer.getPage(pageNumber) ➔ writer.pages[page_number]
- writer.getNumPages() ➔ len(writer.pages)
- getPageLayout / pageLayout ➔ page_layout
- getPageMode / pageMode ➔ page_mode
- getIsEncrypted / isEncrypted ➔ is_encrypted
- getDocumentInfo ➔ metadata

PdfWriter
---------

- writer.getPage(pageNumber) ➔ writer.pages[page_number]
- writer.getNumPages() ➔ len(writer.pages)
- getPageLayout / setPageLayout / pageLayout ➔ page_layout
- getPageMode / setPageMode / pageMode ➔ page_mode

Page
----

- mediabox / trimbox / cropbox / bleedbox / artbox:
    - 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
- Add Transformation class to make it easy to create transformation matrices
- add_transformation and merge_page should be used instead of:
    - mergeTransformedPage
    - mergeScaledPage
    - mergeRotatedPage
    - mergeTranslatedPage
    - mergeRotatedTranslatedPage
    - mergeRotatedScaledPage
    - mergeScaledTranslatedPage
    - mergeRotatedScaledTranslatedPage

See the CHANGELOG for a full list of changes

.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",
 ]