ENH: Wrap and align text in flattened PDF forms #3465

PJBrs · 2025-09-13T14:47:27Z

This patch implements text wrapping and alignment in appearance streams.

The scale_text method was vibe-coded, as well as the code for right-aligned text and centered text, but they both work great.

The result offers a good basis for text wrapping. I did notice, however, that the results with pdftk are better. In the future, it would be nice to read the info for the annotation border from the annotiation instead of just adding some padding here and there (which is the case now). Also, I notice there's also an annotation option called "comb" that is not taken into account. Then there is annotation text colour... Finally, pdftk takes into account the font bounding box / ascent in deciding scaled font size.

For now, however, this PR "finishes" PDF flattening in the sense that it correctly wraps long texts and aligns it as intended.

Related but not fixed here: #2153
I think this does fix the alignment part of #1919

codecov · 2025-09-13T14:56:42Z

Codecov Report

❌ Patch coverage is 97.82609% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.12%. Comparing base (3b5c85f) to head (fcb45b3).

Files with missing lines	Patch %	Lines
pypdf/generic/_appearance_stream.py	97.67%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3465      +/-   ##
==========================================
+ Coverage   97.10%   97.12%   +0.01%     
==========================================
  Files          57       57              
  Lines        9711     9778      +67     
  Branches     1759     1773      +14     
==========================================
+ Hits         9430     9497      +67     
  Misses        168      168              
  Partials      113      113

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

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

pypdf/_writer.py

PJBrs · 2025-09-26T11:20:53Z

This is a reworked version on top of #3466

Not for review right now.

mypy complained that the .from_font_resource method's return type is Optional[FontDescriptor]. Change the code to not confuse mypy.

This adds a method to calculate the width of a text string. This method can later be used to wrap text at a certain length. Code blatantly copied from the _font.py file in the text extractor code.

PJBrs · 2025-11-05T14:37:24Z

@stefan6419846 First, thanks very much for merging the refactoring of appearance stream code from _writer.py to generic_appearance_stream.py!

With that in place, it should now be easier to review this PR, which adds text wrapping, scaling and alignment for text appearance streams.

pypdf/generic/_appearance_stream.py

This patch adds a method to scale and wrap text, depending on whether or not text is allowed to be wrapped. It takes a couple of arguments, including the text string itself, field width and height, font size, a FontDescriptor with character widths, and a bool specifying whether or not text is allowed to wrap. Returns the text in in the form of list of tuples, each tuple containing the length of a line and its contents, and the font size for these lines and lengths.

This patch scales and/or wrap text that does not fit into a text field unaltered, under the condition that font size was set to 0 in the default appearance stream. We only wrap text if the multiline bit was set in the corresponding annotation's field flags, otherwise we just scale the font until it fits. We move the escaping of parentheses below, so that it does not interfere with calculating the width of a text string.

Make sure that we always have Helvetica as a viable font resource, for which we surely have all necessary font metrics needed for text wrapping.

This patch changes the TextAppearanceStream code so that it can deal with right alignment and centered text. Note that both require correct font metrics in order to work.

We need the info that is in CORE_FONT_METRICS, and that is the same information as in _default_fonts_space_width anyway. So this patch removes a bit of redundancy.

Add tests for the TextStreamAppearance.

stefan6419846 · 2025-11-06T15:53:58Z

docs/user/forms.md


+If you want to flatten your form, that is, keeping all form field contents while
+removing the form fields themselves, you can set `flatten=True` to convert form
+field contents to regular pdf content, and then use


Suggested change

field contents to regular pdf content, and then use

field contents to regular PDF content, and then use

stefan6419846 · 2025-11-06T15:54:06Z

docs/user/forms.md

+removing the form fields themselves, you can set `flatten=True` to convert form
+field contents to regular pdf content, and then use
+`writer.remove_annotations(subtypes="/Widget")` to remove all form fields. This
+will result in a flattened pdf.


Suggested change

will result in a flattened pdf.

will result in a flattened PDF.

stefan6419846 · 2025-11-06T15:54:20Z

pypdf/generic/_appearance_stream.py

+        font_size: float,
+        field_width: float,
+        field_height: float,
+        txt: str,


Suggested change

txt: str,

text: str,

stefan6419846 · 2025-11-06T15:55:51Z

pypdf/generic/_appearance_stream.py

+            return [(test_width, txt)], font_size
+        # Multiline:
+        orig_txt = txt
+        paragraphs = re.sub(r"\n", "\r", txt).split("\r")


Why do we need a regex for replacing plain newlines?

stefan6419846 · 2025-11-06T15:56:59Z

pypdf/generic/_appearance_stream.py

+                return [(test_width, txt)], font_size
+            return [(test_width, txt)], font_size
+        # Multiline:
+        orig_txt = txt


Suggested change

orig_txt = txt

original_text = text

stefan6419846 · 2025-11-06T16:04:04Z

tests/test_appearance_stream.py

+"""
+    selection = "Option A"
+    assert (b"4.0 Tf") in appearance_stream.get_data()
+    text = "pneumonoultramicroscopicsilicovolcanoconiosis"


Suggested change

text = "pneumonoultramicroscopicsilicovolcanoconiosis"

text = "pneumonoultramicroscopicsilicovolcanoconiosis"

stefan6419846 · 2025-11-06T16:04:15Z

tests/test_appearance_stream.py

+    appearance_stream = TextStreamAppearance(
+        text, selection, rectangle=rectangle, font_size=font_size, is_multiline=is_multiline
+    )
+    assert (b"7.2 Tf") in appearance_stream.get_data()


Suggested change

assert (b"7.2 Tf") in appearance_stream.get_data()

assert b"7.2 Tf" in appearance_stream.get_data()

stefan6419846 · 2025-11-06T16:04:21Z

tests/test_appearance_stream.py

+        text, selection, rectangle=rectangle, font_size=font_size, is_multiline=is_multiline
+    )
+    assert (b"7.2 Tf") in appearance_stream.get_data()
+    rectangle = (0, 0, 10, 100)


Suggested change

rectangle = (0, 0, 10, 100)

rectangle = (0, 0, 10, 100)

stefan6419846 · 2025-11-06T16:04:29Z

tests/test_appearance_stream.py

+    appearance_stream = TextStreamAppearance(
+        text, rectangle=rectangle, font_size=font_size, is_multiline=is_multiline
+    )
+    assert (b"OneWord") in appearance_stream.get_data()


Suggested change

assert (b"OneWord") in appearance_stream.get_data()

assert b"OneWord" in appearance_stream.get_data()

stefan6419846 · 2025-11-06T16:05:04Z

tests/test_writer.py

    assert writer.pages[0]["/Annots"][13].get_object()["/AP"]["/N"].get_data() == (
        b"q\n/Tx BMC \nq\n1 1 105.29520000000001 10.835000000000036 re\n"
-        b"W\nBT\n/Arial 8.0 Tf 0 g\n2 2.8350000000000364 Td\n(0) Tj\nET\n"
+        b"W\nBT\n/Helv 8.0 Tf 0 g\n2 2.8350000000000364 Td\n(0) Tj\nET\n"


Why do we change the font default?

stefan6419846 reviewed Sep 13, 2025

View reviewed changes

pypdf/_writer.py Outdated Show resolved Hide resolved

stefan6419846 reviewed Sep 13, 2025

View reviewed changes

pypdf/_writer.py Outdated Show resolved Hide resolved

PJBrs marked this pull request as draft September 15, 2025 12:02

PJBrs force-pushed the wrap branch from 438cc37 to 6af7101 Compare September 26, 2025 10:56

PJBrs force-pushed the wrap branch from 6af7101 to 4ccfa3a Compare October 6, 2025 18:54

PJBrs force-pushed the wrap branch from 4ccfa3a to 5f10527 Compare October 26, 2025 20:58

PJBrs added 2 commits November 5, 2025 14:54

ROB: _font: Always returns a FontDescriptor; fix typing

6f194bb

mypy complained that the .from_font_resource method's return type is Optional[FontDescriptor]. Change the code to not confuse mypy.

ENH: _font: Add method to calculate text width

f69c182

This adds a method to calculate the width of a text string. This method can later be used to wrap text at a certain length. Code blatantly copied from the _font.py file in the text extractor code.

PJBrs force-pushed the wrap branch from 5f10527 to 30b73c6 Compare November 5, 2025 14:26

PJBrs marked this pull request as ready for review November 5, 2025 14:35

PJBrs commented Nov 5, 2025

View reviewed changes

pypdf/generic/_appearance_stream.py Outdated Show resolved Hide resolved

PJBrs added 8 commits November 5, 2025 17:46

ROB: TextAppearanceStream: Add default font resource

baefcb7

Make sure that we always have Helvetica as a viable font resource, for which we surely have all necessary font metrics needed for text wrapping.

ENH: TextAppearanceStream: Add right alignment and centering

9ebdbe4

This patch changes the TextAppearanceStream code so that it can deal with right alignment and centered text. Note that both require correct font metrics in order to work.

MAINT: TextAppearanceStream: Don't use _default_fonts_space_width

f2d25d0

We need the info that is in CORE_FONT_METRICS, and that is the same information as in _default_fonts_space_width anyway. So this patch removes a bit of redundancy.

ENH: tests: _appearance_stream

c54cc0c

Add tests for the TextStreamAppearance.

ENH: docs: Add documentation about flattening a PDF form

a22d96f

MAINT: Add myself as contributor

fcb45b3

PJBrs force-pushed the wrap branch from 30b73c6 to fcb45b3 Compare November 5, 2025 17:02

PJBrs requested a review from stefan6419846 November 5, 2025 17:31

stefan6419846 requested changes Nov 6, 2025

View reviewed changes

	field contents to regular pdf content, and then use
	field contents to regular PDF content, and then use

	will result in a flattened pdf.
	will result in a flattened PDF.

	text = "pneumonoultramicroscopicsilicovolcanoconiosis"

	text = "pneumonoultramicroscopicsilicovolcanoconiosis"

	assert (b"7.2 Tf") in appearance_stream.get_data()
	assert b"7.2 Tf" in appearance_stream.get_data()

	assert (b"OneWord") in appearance_stream.get_data()
	assert b"OneWord" in appearance_stream.get_data()

ENH: Wrap and align text in flattened PDF forms #3465

Are you sure you want to change the base?

ENH: Wrap and align text in flattened PDF forms #3465

Conversation

PJBrs commented Sep 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Sep 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

PJBrs commented Sep 26, 2025

Uh oh!

PJBrs commented Nov 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

PJBrs commented Sep 13, 2025 •

edited

Loading

codecov bot commented Sep 13, 2025 •

edited

Loading

PJBrs commented Nov 5, 2025 •

edited

Loading