DOC: Document new attachment functionality and allow updating content (#3379)

Author: stefan6419846

docs/index.rst

@@ -28,7 +28,7 @@ You can contribute to `pypdf on GitHub <https://github.com/py-pdf/pypdf>`_.
    user/extract-text
    user/post-processing-in-text-extraction
    user/extract-images
-   user/extract-attachments
+   user/handle-attachments
    user/encryption-decryption
    user/merging-pdfs
    user/cropping-and-transforming

docs/user/extract-attachments.md

@@ -0,0 +1,73 @@
+# Handle Attachments
+
+PDF documents can contain attachments, from time to time named embedded file as well.
+
+## Retrieve Attachments
+
+Attachments have a name, but it might not be unique. For this reason, the value of `reader.attachments["attachment_name"]`
+is a list.
+
+You can extract all attachments like this:
+
+```python
+from pypdf import PdfReader
+
+reader = PdfReader("example.pdf")
+
+for name, content_list in reader.attachments.items():
+    for i, content in enumerate(content_list):
+        with open(f"{name}-{i}", "wb") as fp:
+            fp.write(content)
+```
+
+Alternatively, you can retrieve them in an object-oriented fashion if you need
+further details for these files:
+
+```python
+from pypdf import PdfReader
+
+reader = PdfReader("example.pdf")
+
+for attachment in reader.attachment_list:
+    print(attachment.name, attachment.alternative_name, attachment.content)
+```
+
+## Add Attachments
+
+To add a new attachment, use the following code:
+
+```python
+from pypdf import PdfWriter
+
+writer = PdfWriter(clone_from="example.pdf")
+writer.add_attachment(filename="test.txt", data=b"Hello World!")
+```
+
+As you can see, the basic attachment properties are its name and content. If you
+want to modify further properties of it, the returned object provides corresponding
+setters:
+
+```python
+import datetime
+import hashlib
+
+from pypdf import PdfWriter
+from pypdf.generic import create_string_object, ByteStringObject, NameObject, NumberObject
+
+
+writer = PdfWriter(clone_from="example.pdf")
+embedded_file = writer.add_attachment(filename="test.txt", data=b"Hello World!")
+
+embedded_file.size = NumberObject(len(b"Hello World!"))
+embedded_file.alternative_name = create_string_object("test1.txt")
+embedded_file.description = create_string_object("My test file")
+embedded_file.subtype = NameObject("/text/plain")
+embedded_file.checksum = ByteStringObject(hashlib.md5(b"Hello World!").digest())
+embedded_file.modification_date = datetime.datetime.now(tz=datetime.timezone.utc)
+# embedded_file.content = "My new content."
+
+embedded_file.write("output.pdf")
+```
+
+The same functionality is available if you iterate over the attachments of a writer
+using `writer.attachment_list`.

docs/user/handle-attachments.md

@@ -204,6 +204,13 @@ def content(self) -> bytes:
         """Retrieve the actual file content."""
         return self._embedded_file.get_data()
 
+    @content.setter
+    def content(self, value: str | bytes) -> None:
+        """Set the file content."""
+        if isinstance(value, str):
+            value = value.encode("latin-1")
+        self._embedded_file.set_data(value)
+
     @property
     def size(self) -> int | None:
         """Retrieve the size of the uncompressed file in bytes."""

pypdf/generic/_files.py

@@ -263,6 +263,18 @@ def test_embedded_file_subtype_setter():
     assert embedded_file.subtype == "/application#2Fjson"
 
 
+def test_embedded_file_content_setter():
+    writer = PdfWriter()
+    embedded_file = writer.add_attachment("test.txt", b"content")
+    assert embedded_file.content == b"content"
+
+    embedded_file.content = b"Hello World!"
+    assert embedded_file.content == b"Hello World!"
+
+    embedded_file.content = "Lorem ipsum dolor sit amet"
+    assert embedded_file.content == b"Lorem ipsum dolor sit amet"
+
+
 def test_embedded_file_size_setter():
     writer = PdfWriter()
     embedded_file = writer.add_attachment("test.txt", b"content")