Make methods return 'self' to allow method chaining

[MartinThoma]

A user stumbled over this: #460

I would just make all methods returns self + document that the function operates in place.

What do you think @MasterOdin / @sekrause ?

[sekrause]

That could be a unusual and possibly confusing API. I've mainly encountered two different kinds of APIs so far:

1. Where methods directly manipulate a mutable object (like PyPDF2 right now) and return nothing.
2. Those that allow method chaining usually use immutable objects and return a completely new object with each methd call, leaving the original object unchanged. The SQLAlchemy query API is a good example of this kind of API.

I wouldn't advice for mixing both.

[MartinThoma]

Apparently fluent interfaces typically use a clone method in between: https://kracekumar.com/post/100897281440/fluent-interface-in-python/

Copying all page data seems super inefficient; I wouldn't want to do that.

But maybe a PageTransformation object could capture all transformations done to a page. That would be way more lightweight. I need to see more examples... I guess it might be over-engineering as people probably do one or two transformations on a page only.