Standardization of class / method / function names

[MartinThoma]

I would like to rename:

• PdfFileReader➔PdfReader
• PdfFileWriter➔PdfWriter
• PdfFileMerger➔PdfMerger

Those 3 classes don't necessarily operate on files. They can operate on streams. Hence removing the "file" part makes sense to me.

Additionally, I would remove getters / setters in favor of properties in many cases.

Renames for PyPDF2.PdfFileReader:

• getDocumentInfo, documentInfo ➔ metadata
• getXmpMetadata, xmpMetadata ➔ xmp_metadata
• getNumPages, numPages ➔ len(reader.pages)
• getPage ➔ reader.pages[0]
• getNamedDestinations, namedDestinations ➔ named_destinations
• getFields ➔ fields
• getPageLayout, pageLayout ➔ page_layout
• getPageMode, pageMode ➔ page_mode
• getFormTextFields ➔ form_text_fields
• getOutlines: remove from public interface (add a leading underscore)
• getObject ➔ get_object
• readObjectHeader ➔ read_object_header
• getPageNumber ➔ get_page_number
• getDestinationPageNumber ➔ get_destination_page_number
• cacheGetIndirectObject / cacheIndirectObject: Is there a point in having those public?
• readNextEndLines should this be public?

What do you think about this renaming for PyPDF2 2.0.0?

[MartinThoma]

e.g. @MasterOdin / @sekrause ?

[sekrause]

Rename the class, but keep the old name as an alias so that old code keeps working.

[MasterOdin]

I agree with @sekrause in just that this library has existed for quite a long time, and it's perhaps worth not breaking existing tutorials and such out on the web / SO / etc. until there's been sufficient movement to see the new class names used everywhere.

By keeping the old class names, would make it possible to land this initially in 1.x if so wanted, but perhaps easier to wait till 2.0 at this point.

[MartinThoma]

Thank you for your input!

As a maintainer, I have 3 goals: (G1) I want to ensure that PyPDF2 has a good user experience. (G2) As PyPDF2 is an open source project, I also want to ensure that adhoc contributors have an easy time to make improvements. (G3) I want to make the live of maintainers easy.

For (G1), being reliable is important. It's also important to have an intuitive interface.

I would add deprecation notes to a 1.x release + the new names. So that people can switch within PyPDF2 1.X. If they don't see warnings, they can switch to 2.0.0. In 2.0.0 I want to get rid of inconsistencies in the interface / make it PEP8 compliant / ensure there is (only) one way to do one thing (e.g. properties instead of getters). I'm also looking at naming schemes of other libraries (e.g. documentInfo in PyPDF2 vs metadata in PyMuPDF/pikepdf vs info in pdfminer - I'm still uncertain about this one). And I'm looking at search queries (e.g. Google Trends)

It would be amazing to have a user group where I can make surveys. Keeping things as they are to prevent breaking stuff is always a strong argument. I don't want to have too many releases with breaking changes. So I try to get all of those things in the PyPDF2 2.0.0 release.

not breaking existing tutorials

That was one reason why I added several examples in the docs :-) There are actually a lot of really bad tutorials for PyPDF2 around (bad formatting, too many things happening at the same time, bad variable names, ...). I hope we can get more people to use the official docs + improve them where necessary.

I'll work on the topic in #867

[johns1c]

The large user base of PyPDF2 suggests that we are stuck with the user interface.

Creating new names and then pointing the old names to the new will, if done, have to be handled carefully. Most PyPDF2 users use it for quite simple operations (split and merge, manipulating metadata, text and image extraction etc) but any that go beyond this (such as wx.lib.pdfviewer) will rely on the object model and what might be considered internal routines.

The package is still broken in places. There are a number of places where the original Python 2 code does not work properly under Python 3 or results in conversion from bytes to unicode and then back again. There are also many places where the existing code can be simplified (even retaining 2.7 compatibility) and places where the pragmatic decisions made by coders need to be reviewed and documented.

I think that it would be good to offer an improved version that has fewer issues if asking the users to make changes.

when run under Python 3 occurs