Skip to content

Commit c66ee8c

Browse files
MartinThomaMartinThoma
authored
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
1 parent a791ef1 commit c66ee8c

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

59 files changed

+3524
-1491
lines changed

‎.github/ISSUE_TEMPLATE/feature-request.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Explain briefly what you want to achive.
1515
How would your feature be used? (Remove this if it is not applicable.)
1616

1717
```python
18-
from PyPDF2 import PdfFileReader, PdfFileWriter
18+
from PyPDF2 import PdfReader, PdfWriter
1919

2020
... # your new feature in action!
2121
```

‎CHANGELOG‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,131 @@
1+
Version 1.28.0, 2022-05-22
2+
--------------------------
3+
4+
This release adds a lot of deprecation warnings in preparation of the
5+
PyPDF2 2.0.0 release. The changes are mostly using snake_case function-, method-,
6+
and variable-names as well as using properties instead of getter-methods.
7+
8+
### Deprecations (DEP)
9+
10+
* Make the `PyPDF2.utils` module private
11+
* Rename of core classes:
12+
* PdfFileReader ➔ PdfReader
13+
* PdfFileWriter ➔ PdfWriter
14+
* PdfFileMerger ➔ PdfMerger
15+
* Use PEP8 conventions for function names and parameters
16+
* If a property and a getter-method are both present, use the property
17+
18+
#### Details
19+
20+
In many places:
21+
- getObject ➔ get_object
22+
- writeToStream ➔ write_to_stream
23+
- readFromStream ➔ read_from_stream
24+
25+
PyPDF2.generic
26+
- readObject ➔ read_object
27+
- convertToInt ➔ convert_to_int
28+
- DocumentInformation.getText ➔ DocumentInformation._get_text :
29+
This method should typically not be used; please let me know if you need it.
30+
31+
PdfReader class:
32+
- `reader.getPage(pageNumber)` ➔ `reader.pages[page_number]`
33+
- `reader.getNumPages()` / `reader.numPages` ➔ `len(reader.pages)`
34+
- getDocumentInfo ➔ metadata
35+
- flattenedPages attribute ➔ flattened_pages
36+
- resolvedObjects attribute ➔ resolved_objects
37+
- xrefIndex attribute ➔ xref_index
38+
- getNamedDestinations / namedDestinations attribute ➔ named_destinations
39+
- getPageLayout / pageLayout ➔ page_layout attribute
40+
- getPageMode / pageMode ➔ page_mode attribute
41+
- getIsEncrypted / isEncrypted ➔ is_encrypted attribute
42+
- getOutlines ➔ get_outlines
43+
- readObjectHeader ➔ read_object_header (TODO: read vs get?)
44+
- cacheGetIndirectObject ➔ cache_get_indirect_object (TODO: public vs private?)
45+
- cacheIndirectObject ➔ cache_indirect_object (TODO: public vs private?)
46+
- getDestinationPageNumber ➔ get_destination_page_number
47+
- readNextEndLine ➔ read_next_end_line
48+
- _zeroXref ➔ _zero_xref
49+
- _authenticateUserPassword ➔ _authenticate_user_password
50+
- _pageId2Num attribute ➔ _page_id2num
51+
- _buildDestination ➔ _build_destination
52+
- _buildOutline ➔ _build_outline
53+
- _getPageNumberByIndirect(indirectRef) ➔ _get_page_number_by_indirect(indirect_ref)
54+
- _getObjectFromStream ➔ _get_object_from_stream
55+
- _decryptObject ➔ _decrypt_object
56+
- _flatten(..., indirectRef) ➔ _flatten(..., indirect_ref)
57+
- _buildField ➔ _build_field
58+
- _checkKids ➔ _check_kids
59+
- _writeField ➔ _write_field
60+
- _write_field(..., fieldAttributes) ➔ _write_field(..., field_attributes)
61+
- _read_xref_subsections(..., getEntry, ...) ➔ _read_xref_subsections(..., get_entry, ...)
62+
63+
PdfWriter class:
64+
- `writer.getPage(pageNumber)` ➔ `writer.pages[page_number]`
65+
- `writer.getNumPages()` ➔ `len(writer.pages)`
66+
- addMetadata ➔ add_metadata
67+
- addPage ➔ add_page
68+
- addBlankPage ➔ add_blank_page
69+
- addAttachment(fname, fdata) ➔ add_attachment(filename, data)
70+
- insertPage ➔ insert_page
71+
- insertBlankPage ➔ insert_blank_page
72+
- appendPagesFromReader ➔ append_pages_from_reader
73+
- updatePageFormFieldValues ➔ update_page_form_field_values
74+
- cloneReaderDocumentRoot ➔ clone_reader_document_root
75+
- cloneDocumentFromReader ➔ clone_document_from_reader
76+
- getReference ➔ get_reference
77+
- getOutlineRoot ➔ get_outline_root
78+
- getNamedDestRoot ➔ get_named_dest_root
79+
- addBookmarkDestination ➔ add_bookmark_destination
80+
- addBookmarkDict ➔ add_bookmark_dict
81+
- addBookmark ➔ add_bookmark
82+
- addNamedDestinationObject ➔ add_named_destination_object
83+
- addNamedDestination ➔ add_named_destination
84+
- removeLinks ➔ remove_links
85+
- removeImages(ignoreByteStringObject) ➔ remove_images(ignore_byte_string_object)
86+
- removeText(ignoreByteStringObject) ➔ remove_text(ignore_byte_string_object)
87+
- addURI ➔ add_uri
88+
- addLink ➔ add_link
89+
- getPage(pageNumber) ➔ get_page(page_number)
90+
- getPageLayout / setPageLayout / pageLayout ➔ page_layout attribute
91+
- getPageMode / setPageMode / pageMode ➔ page_mode attribute
92+
- _addObject ➔ _add_object
93+
- _addPage ➔ _add_page
94+
- _sweepIndirectReferences ➔ _sweep_indirect_references
95+
96+
PdfMerger class
97+
- `__init__` parameter: strict=True ➔ strict=False (the PdfFileMerger still has the old default)
98+
- addMetadata ➔ add_metadata
99+
- addNamedDestination ➔ add_named_destination
100+
- setPageLayout ➔ set_page_layout
101+
- setPageMode ➔ set_page_mode
102+
103+
Page class:
104+
- artBox / bleedBox/ cropBox/ mediaBox / trimBox ➔ artbox / bleedbox/ cropbox/ mediabox / trimbox
105+
- getWidth, getHeight ➔ width / height
106+
- getLowerLeft_x / getUpperLeft_x ➔ left
107+
- getUpperRight_x / getLowerRight_x ➔ right
108+
- getLowerLeft_y / getLowerRight_y ➔ bottom
109+
- getUpperRight_y / getUpperLeft_y ➔ top
110+
- getLowerLeft / setLowerLeft ➔ lower_left property
111+
- upperRight ➔ upper_right
112+
- mergePage ➔ merge_page
113+
- rotateClockwise / rotateCounterClockwise ➔ rotate_clockwise
114+
- _mergeResources ➔ _merge_resources
115+
- _contentStreamRename ➔ _content_stream_rename
116+
- _pushPopGS ➔ _push_pop_gs
117+
- _addTransformationMatrix ➔ _add_transformation_matrix
118+
- _mergePage ➔ _merge_page
119+
120+
XmpInformation class:
121+
- getElement(..., aboutUri, ...) ➔ get_element(..., about_uri, ...)
122+
- getNodesInNamespace(..., aboutUri, ...) ➔ get_nodes_in_namespace(..., aboutUri, ...)
123+
- _getText ➔ _get_text
124+
125+
utils.py:
126+
- matrixMultiply ➔ matrix_multiply
127+
- RC4_encrypt is moved to the security module
128+
1129
Version 1.27.12, 2022-05-02
2130
---------------------------
3131

‎PyPDF2/__init__.py‎

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,23 @@
1-
from PyPDF2 import pdf
2-
from PyPDF2._reader import PdfFileReader
1+
from PyPDF2._reader import DocumentInformation, PdfFileReader, PdfReader
32
from PyPDF2._version import __version__
4-
from PyPDF2._writer import PdfFileWriter
5-
from PyPDF2.merger import PdfFileMerger
3+
from PyPDF2._writer import PdfFileWriter, PdfWriter
4+
from PyPDF2.merger import PdfFileMerger, PdfMerger
65
from PyPDF2.pagerange import PageRange, parse_filename_page_ranges
76
from PyPDF2.papersizes import PaperSize
87

8+
from ._page import Transformation
9+
910
__all__ = [
1011
"__version__",
1112
"PageRange",
1213
"PaperSize",
14+
"DocumentInformation",
1315
"parse_filename_page_ranges",
14-
"pdf",
15-
"PdfFileMerger",
16-
"PdfFileReader",
17-
"PdfFileWriter",
16+
"PdfFileMerger", # will be removed soon; use PdfMerger instead
17+
"PdfFileReader", # will be removed soon; use PdfReader instead
18+
"PdfFileWriter", # will be removed soon; use PdfWriter instead
19+
"PdfMerger",
20+
"Transformation",
21+
"PdfReader",
22+
"PdfWriter",
1823
]

0 commit comments

Comments
 (0)