BUG: Improve PdfWriter handing of context manager

[pubpub-zz]

closes #2912

[stefan6419846]

Why only as unnamed argument?

[pubpub-zz]

the unnamed parameter will be assigned to fileobj or clone_from. I do not really understand your question

[stefan6419846]

I have been thinking about what would be the best way to handle such cases and whether we really need this whole PR - IMHO keyword arguments should always be preferred over positional arguments, while keyword arguments have always worked correctly.

My recommendation would be to keep the old behavior, but deprecate unnamed arguments and make the constructor keyword-only in the future. This way, we force users to clearly express their intents without having to introduce further magic on our side.

[pubpub-zz]

I prefer to keep it as it is now : first for many cases it is easier to not need to add a parameter name when typing. second we have this syntax for some time. Let's open a discussion about it and will see what is the feedback.

[stefan6419846]

With your proposed approach, we get some sort of mixed handling which I consider even more harmful: Previously, you would be able to pass all parameters as positional ones, but allowing for keyword-based and mixed ones as well. The current state of this PR will drop all positional parameters except the first one. This is an undocumented breaking change which would need a deprecation process as well - thus switching to keyword-only arguments with a deprecation process is not much different while enforcing users to actually think of what they want to do.

The amount of characters to type should not really matter as well. A few libraries already migrated to keyword-only arguments in the past as this makes everything more readable. Additionally, every modern IDE (and even some regular text editors) provide support for autocompletion based upon the method signature.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Please upload report for BASE (main@59ae169). Learn more about missing BASE report.
Report is 3 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2913   +/-   ##
=======================================
  Coverage        ?   96.37%           
=======================================
  Files           ?       52           
  Lines           ?     8736           
  Branches        ?     1592           
=======================================
  Hits            ?     8419           
  Misses          ?      187           
  Partials        ?      130           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[stefan6419846]

While #2913 (review) is not addressed accordingly (without just marking it as resolved), I do not consider this to be ready for merging.