Add and improve documentation

[j-t-1]

The better examples we have the more we can answer questions by directing them to the documentation.

Questions:

1. For an extra example, can we replace pdftk crazyones.pdf output crazyones-uncomp.pdf uncompress?

from pypdf import PdfWriter

writer = PdfWriter(clone_from="crazyones.pdf")

for page in writer.pages:
    page.compress_content_streams(level=0)

with open("crazyones-uncomp.pdf", "wb") as f:
    writer.write(f)

2. We can have a delete page example in file-size.html (copied bits from the commit ENH: Add page deletion feature to PdfWriter #1843) approximately:

url = "https://corpora.tika.apache.org/base/docs/govdocs1/941/941536.pdf"
name = "tika-941536.pdf"
writer = PdfWriter(clone_from=BytesIO(get_pdf_from_url(url, name=name)))
del writer.pages[1]
with open("crazyones-uncomp.pdf", "wb") as f:
    writer.write(f)

3. In streaming-data.html example below

• Can we clone_from PdfWriter and not use PdfReader?
• It is incomplete because raw_bytes_data has not been initialized, how to do so?
• Explain why BytesIO is needed?

from io import BytesIO

import boto3
from pypdf import PdfReader, PdfWriter


reader = PdfReader(BytesIO(raw_bytes_data))
writer = PdfWriter()

# Add all pages to the writer
for page in reader.pages:
    writer.add_page(page)

# Add a password to the new PDF
writer.encrypt("my-secret-password")

# Save the new PDF to a file
with BytesIO() as bytes_stream:
    writer.write(bytes_stream)
    bytes_stream.seek(0)
    s3 = boto3.client("s3")
    s3.write_get_object_response(
        Body=bytes_stream, RequestRoute=request_route, RequestToken=request_token
    )

4. We do not currently have a get_pdf_from_url example in the documentation?

[stefan6419846]

get_pdf_from_url is not part of distributions and thus should not be used outside the internal developer docs. If only, it should be part of the developer docs on how to write tests.

Regarding (3): raw_bytes_data just represents raw PDF bytes, id est something in the format raw_bytes_data = b"%PDF-1.5\n%\xc3\xa4\xc3\xbc\xc3\xb6\xc3\x9f\n2 0 obj\n<</Length 3 0 R/Filter/...61F91FB54AC41C92CC454B023\n>>\nstartxref\n7652\n%%EOF\n" Without BytesIO, this would be interpreted as a path and not as pure byte data.