Next Breaking Changes

[MartinThoma]

We have a couple of methods in pypdf which are marked deprecate_with_replacement / deprecation_with_replacement / deprecate_no_replacement / deprecation_no_replacement. Those will go their planned way.

But there are some other parts within pypdf that you might want to get deprecated or breaking changes of which you think they would benefit the library. The idea is to collect and evaluate those here. Then we can make a major release. I want to limit the times at which users have to adjust, hence collecting those makes sense.

Please let me know if something else pops into your mind :-)

Next breaking changes

• Switch to None or Exception for page_number / get_page_number / get_destination_page_number #1914 : Make sure the users deal with error cases.
• Remove the encryption_key parameter from write_to_stream as done in ENH: Add AES support for encrypting PDF files (merged via other PRs) #1816

[j-t-1]

How about we deprecate deprecation?

Change deprecation_with_replacement to deprecated_with_replacement and deprecation_no_replacement to deprecated_no_replacement.

I think deprecate_with_replacement / deprecation_with_replacement and deprecate_no_replacement / deprecation_no_replacement are semantically too similar, whereas deprecated is past tense.

[stefan6419846]

I would not consider this a breaking change due to the methods already being mostly internal and nobody should be using them outside of our code.

[pubpub-zz]

Depreciation sounds more like the process is in progress. It's more likely deprecate that could be renamed into deprecated.
In any case the functions should be referenced in a dev section of the depreciation process page

[j-t-1]

Thinking about it, once it is known what the difference is (and we have documentation for this) the existing functions are adequate and is useful for grep.

[j-t-1]

For readability how about renaming these files:

_viewerpref.py to _viewer_preferences.py
pagerange.py to page_range.py
papersizes.py to paper_size.py

Unsure if this is a breaking change.

[stefan6419846]

The first change is no publicly facing one and thus could be done at any time. Nevertheless, we should focus on a consistent naming scheme (singular vs. plural) when renaming - your proposal already mixes this up.

[pubpub-zz]

I'm not convinced. The current names can be understood, name completion is available is available in nearly all environments and does not provide more features. It will only break upward compatibility

[j-t-1]

Singular could be the default, but if the main class in the file is plural then this takes precedence, for example ViewerPreferences. File papersizes.py contains class PaperSize so removing the 's' would be good for consistency.

Having underscores makes reading the code quicker and would give consistency with some of the other file names.

@pubpub-zz what are the compatibility issues?