Implementation of get_contents

[j-t-1]

pypdf/pypdf/_page.py

Lines 964 to 983 in f5c5747

	def get_contents(self) -> Optional[ContentStream]:
	"""
	Access the page contents.
	Returns:
	The ``/Contents`` object, or ``None`` if it does not exist.
	``/Contents`` is optional, as described in §7.7.3.3 of the PDF Reference.
	"""
	if PG.CONTENTS in self:
	try:
	pdf = cast(IndirectObject, self.indirect_reference).pdf
	except AttributeError:
	pdf = None
	obj = self[PG.CONTENTS]
	if is_null_or_none(obj):
	return None
	resolved_object = obj.get_object()
	return ContentStream(resolved_object, pdf)
	return None

Are there advantages to the above implementation? Why not do similar to _get_contents_as_bytes (below), but join as a string and cast to a ContentStream? Further, only this handles when the content stream is an array?

pypdf/pypdf/_page.py

Lines 949 to 962 in f5c5747

	def _get_contents_as_bytes(self) -> Optional[bytes]:
	"""
	Return the page contents as bytes.
	Returns:
	The ``/Contents`` object as bytes, or ``None`` if it doesn't exist.
	"""
	if PG.CONTENTS in self:
	obj = self[PG.CONTENTS].get_object()
	if isinstance(obj, list):
	return b"".join(x.get_object().get_data() for x in obj)
	return cast(EncodedStreamObject, obj).get_data()
	return None

[stefan6419846]

I always suggest to use Git blaming to identify why these changes were done and dig through the code.

In this specific case, _get_contents_as_bytes has been introduced in 94f23f9 to speed up inline image extraction. It is an internal method only.

The regular public method is get_contents. Here the array handling is moved to the constructor of the ContentStream class.

Section 7.7.3.3 (table 31) indicates that our list handing might be wrong:

The value shall be either a single stream or an array of streams. If the value is an array, the effect shall be as if all of the streams in the array were concatenated with at least one white-space character added between the streams’ data, in order, to form a single stream.

[j-t-1]

Yes get_contents will need slightly amending. Will it need the get_data method, as in _get_contents_as_bytes?

Is the design decision for ContentStream having a pdf argument so that we can tell if it is part of a PDF or not (if the argument is None) and also to tell which PDF it is part of if pypdf is dealing with more than one pdf (say when merging)?

[stefan6419846]

get_data() is accessing the (decoded) byte data of the corresponding content stream, thus this only relevant when reading from the original PDF file.

I have not been involved in the design of the class, but skimming through the usages of self.pdf in ContentStream seems to indicate that this is used to avoid cloning if the content streams are both targeting the same PDF reference.