pdfdancer-client-python 3.0.2__tar.gz → 3.0.3__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/.github/workflows/ci.yml +4 -4
  2. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/.github/workflows/daily-tests.yml +2 -2
  3. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/.github/workflows/release.yml +3 -3
  4. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/.github/workflows/sdk-backward-compat.yml +2 -2
  5. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/PKG-INFO +32 -1
  6. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/README.md +31 -0
  7. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/src/pdfdancer/__init__.py +2 -0
  8. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/src/pdfdancer/_version.py +2 -2
  9. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/src/pdfdancer/text_editing.py +124 -22
  10. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/src/pdfdancer_client_python.egg-info/PKG-INFO +32 -1
  11. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/src/pdfdancer_client_python.egg-info/SOURCES.txt +1 -0
  12. pdfdancer_client_python-3.0.3/src/pdfdancer_client_python.egg-info/scm_file_list.json +1670 -0
  13. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/.autosnap.toml +0 -0
  14. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/.flake8 +0 -0
  15. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/.github/dependabot.yml +0 -0
  16. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/.gitignore +0 -0
  17. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/.gitmodules +0 -0
  18. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/LICENSE +0 -0
  19. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/MANIFEST.in +0 -0
  20. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/Makefile +0 -0
  21. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/NOTICE +0 -0
  22. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/TODO.md +0 -0
  23. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/check.py +0 -0
  24. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/docs/capabilities/.gitkeep +0 -0
  25. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/docs/capabilities/CLEAR_CLIPPING.md +0 -0
  26. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/media/logo-orange-512h.webp +0 -0
  27. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/media/logo-orange-60h.webp +0 -0
  28. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/media/logo-silver-512h.webp +0 -0
  29. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/media/logo-silver-60h.webp +0 -0
  30. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/pyproject.toml +0 -0
  31. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/setup.cfg +0 -0
  32. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/src/pdfdancer/_runtime_version.py +0 -0
  33. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/src/pdfdancer/exceptions.py +0 -0
  34. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/src/pdfdancer/fingerprint.py +0 -0
  35. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/src/pdfdancer/image_builder.py +0 -0
  36. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/src/pdfdancer/models.py +0 -0
  37. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/src/pdfdancer/page_builder.py +0 -0
  38. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/src/pdfdancer/path_builder.py +0 -0
  39. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/src/pdfdancer/pdfdancer_v2.py +0 -0
  40. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/src/pdfdancer/types.py +0 -0
  41. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/src/pdfdancer_client_python.egg-info/dependency_links.txt +0 -0
  42. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/src/pdfdancer_client_python.egg-info/requires.txt +0 -0
  43. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/src/pdfdancer_client_python.egg-info/top_level.txt +0 -0
  44. {pdfdancer_client_python-3.0.2 → pdfdancer_client_python-3.0.3}/test.sh +0 -0
@@ -74,7 +74,7 @@ jobs:
74
74
  core.setOutput('base_url', urlMatch[1]);
75
75
 
76
76
  - name: Set up Python ${{ matrix.python-version }}
77
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
77
+ uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
78
78
  with:
79
79
  python-version: ${{ matrix.python-version }}
80
80
 
@@ -106,7 +106,7 @@ jobs:
106
106
 
107
107
  - name: Upload test results
108
108
  if: failure()
109
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
109
+ uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
110
110
  with:
111
111
  name: test-results-python-${{ matrix.python-version }}
112
112
  path: |
@@ -137,7 +137,7 @@ jobs:
137
137
  submodules: true
138
138
 
139
139
  - name: Set up Python ${{ matrix.python-version }}
140
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
140
+ uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
141
141
  with:
142
142
  python-version: ${{ matrix.python-version }}
143
143
 
@@ -207,7 +207,7 @@ jobs:
207
207
 
208
208
  - name: Upload test results
209
209
  if: failure()
210
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
210
+ uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
211
211
  with:
212
212
  name: test-results-${{ matrix.os }}-python-${{ matrix.python-version }}
213
213
  path: |
@@ -24,7 +24,7 @@ jobs:
24
24
  submodules: true
25
25
 
26
26
  - name: Set up Python ${{ matrix.python-version }}
27
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
27
+ uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
28
28
  with:
29
29
  python-version: ${{ matrix.python-version }}
30
30
 
@@ -94,7 +94,7 @@ jobs:
94
94
 
95
95
  - name: Upload test results
96
96
  if: failure()
97
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
97
+ uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
98
98
  with:
99
99
  name: test-results-${{ matrix.os }}-python-${{ matrix.python-version }}
100
100
  path: |
@@ -19,7 +19,7 @@ jobs:
19
19
  submodules: true
20
20
 
21
21
  - name: Set up Python 3.12
22
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
22
+ uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
23
23
  with:
24
24
  python-version: '3.12'
25
25
 
@@ -47,10 +47,10 @@ jobs:
47
47
  run: python -m twine check dist/*
48
48
 
49
49
  - name: Publish to PyPI
50
- uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1
50
+ uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # release/v1
51
51
 
52
52
  - name: Create GitHub Release
53
- uses: softprops/action-gh-release@3bb12739c298aeb8a4eeaf626c5b8d85266b0e65 # v2
53
+ uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64 # v3.0.3
54
54
  with:
55
55
  generate_release_notes: true
56
56
  files: dist/*
@@ -58,7 +58,7 @@ jobs:
58
58
  submodules: true
59
59
 
60
60
  - name: Set up Python
61
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
61
+ uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
62
62
  with:
63
63
  python-version: '3.12'
64
64
 
@@ -82,7 +82,7 @@ jobs:
82
82
 
83
83
  - name: Upload test results
84
84
  if: failure()
85
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
85
+ uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
86
86
  with:
87
87
  name: test-results-${{ matrix.tag }}
88
88
  path: |
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pdfdancer-client-python
3
- Version: 3.0.2
3
+ Version: 3.0.3
4
4
  Summary: Python client for PDFDancer API
5
5
  Author-email: "The Famous Cat Ltd." <hi@thefamouscat.com>
6
6
  License-Expression: Apache-2.0
@@ -276,6 +276,37 @@ pdf.text().insert(
276
276
  Each mutation returns `TextEditResponse`, including match and change counts, changed page numbers, per-change
277
277
  diagnostics, warnings, and errors.
278
278
 
279
+ ### Explicit alignment
280
+
281
+ Text replace can align each edited line explicitly with `TextAlignment`. Each edited line keeps its original visible
282
+ text extent as the reference: `LEFT` keeps the left edge, `RIGHT` keeps the right edge, `CENTERED` keeps the midpoint,
283
+ and `JUSTIFIED` keeps both edges by changing the word gaps. Without an alignment, the API detects the alignment from
284
+ the source PDF.
285
+
286
+ ```python
287
+ from pdfdancer import TextAlignment, TextOperationDiagnostic, TextReplaceRequest
288
+
289
+ response = pdf.text().replace(
290
+ TextReplaceRequest.literal("<<account_number>>", "BC5502731")
291
+ .alignment(TextAlignment.RIGHT)
292
+ .build()
293
+ )
294
+ if any(e.code == TextOperationDiagnostic.ALIGNMENT_NOT_HONORED for e in response.errors or ()):
295
+ ... # the text of the unit named in the error was not changed; other matches can have changed
296
+ ```
297
+
298
+ - `alignment()` alone uses `reflowWhenSupported` with the `noReflow` profile. You can combine it with
299
+ `reflow_when_supported(profile)` or `require_reflow(profile)` in any order. `layout(...)` keeps an alignment that
300
+ you set with `alignment()`, unless the layout that you pass has its own alignment.
301
+ - A layout with no mode and no profile (for example, `hyphenation_enabled(False)` alone) uses the `noReflow` profile.
302
+ - `replace_with_image(...)` uses a `sourceAnchored` layout. If you do not set a layout, the SDK sets it.
303
+ - `alignment()` is valid only for replace. With `source_anchored()` or `replace_with_image(...)`, `build()` raises
304
+ `ValidationException`. The delete, insert, and style requests reject a layout that has an alignment.
305
+ - If the API cannot apply the alignment (for example, the replacement adds or removes a line, or the profile re-wraps
306
+ the lines), the response has the error code `TextOperationDiagnostic.ALIGNMENT_NOT_HONORED`. The API does not change
307
+ the text of the unit named in the error. Other matches can still change. The SDK does not raise an exception for
308
+ this error. Check `response.errors` together with `response.changed`.
309
+
279
310
  ## Shared Models
280
311
 
281
312
  `Color` requires integral RGBA components in the inclusive range 0–255. Alpha defaults to 255; `BLACK`, `WHITE`, and
@@ -240,6 +240,37 @@ pdf.text().insert(
240
240
  Each mutation returns `TextEditResponse`, including match and change counts, changed page numbers, per-change
241
241
  diagnostics, warnings, and errors.
242
242
 
243
+ ### Explicit alignment
244
+
245
+ Text replace can align each edited line explicitly with `TextAlignment`. Each edited line keeps its original visible
246
+ text extent as the reference: `LEFT` keeps the left edge, `RIGHT` keeps the right edge, `CENTERED` keeps the midpoint,
247
+ and `JUSTIFIED` keeps both edges by changing the word gaps. Without an alignment, the API detects the alignment from
248
+ the source PDF.
249
+
250
+ ```python
251
+ from pdfdancer import TextAlignment, TextOperationDiagnostic, TextReplaceRequest
252
+
253
+ response = pdf.text().replace(
254
+ TextReplaceRequest.literal("<<account_number>>", "BC5502731")
255
+ .alignment(TextAlignment.RIGHT)
256
+ .build()
257
+ )
258
+ if any(e.code == TextOperationDiagnostic.ALIGNMENT_NOT_HONORED for e in response.errors or ()):
259
+ ... # the text of the unit named in the error was not changed; other matches can have changed
260
+ ```
261
+
262
+ - `alignment()` alone uses `reflowWhenSupported` with the `noReflow` profile. You can combine it with
263
+ `reflow_when_supported(profile)` or `require_reflow(profile)` in any order. `layout(...)` keeps an alignment that
264
+ you set with `alignment()`, unless the layout that you pass has its own alignment.
265
+ - A layout with no mode and no profile (for example, `hyphenation_enabled(False)` alone) uses the `noReflow` profile.
266
+ - `replace_with_image(...)` uses a `sourceAnchored` layout. If you do not set a layout, the SDK sets it.
267
+ - `alignment()` is valid only for replace. With `source_anchored()` or `replace_with_image(...)`, `build()` raises
268
+ `ValidationException`. The delete, insert, and style requests reject a layout that has an alignment.
269
+ - If the API cannot apply the alignment (for example, the replacement adds or removes a line, or the profile re-wraps
270
+ the lines), the response has the error code `TextOperationDiagnostic.ALIGNMENT_NOT_HONORED`. The API does not change
271
+ the text of the unit named in the error. Other matches can still change. The SDK does not raise an exception for
272
+ this error. Check `response.errors` together with `response.changed`.
273
+
243
274
  ## Shared Models
244
275
 
245
276
  `Color` requires integral RGBA components in the inclusive range 0–255. Alpha defaults to 255; `BLACK`, `WHITE`, and
@@ -63,6 +63,7 @@ from .text_editing import (
63
63
  PdfAffineTransformBuilder,
64
64
  PdfColorRequest,
65
65
  PdfColorSpace,
66
+ TextAlignment,
66
67
  TextDeleteBuilder,
67
68
  TextDeleteRequest,
68
69
  TextEditChangeDiagnostic,
@@ -163,6 +164,7 @@ __all__ = [
163
164
  "PdfAffineTransformBuilder",
164
165
  "PdfColorRequest",
165
166
  "PdfColorSpace",
167
+ "TextAlignment",
166
168
  "TextDeleteBuilder",
167
169
  "TextDeleteRequest",
168
170
  "TextEditChangeDiagnostic",
@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
18
18
  commit_id: str | None
19
19
  __commit_id__: str | None
20
20
 
21
- __version__ = version = '3.0.2'
22
- __version_tuple__ = version_tuple = (3, 0, 2)
21
+ __version__ = version = '3.0.3'
22
+ __version_tuple__ = version_tuple = (3, 0, 3)
23
23
 
24
24
  __commit_id__ = commit_id = None
@@ -236,11 +236,34 @@ class TextLayoutProfile(Enum):
236
236
  NO_REFLOW = "noReflow"
237
237
 
238
238
 
239
+ class TextAlignment(Enum):
240
+ """Explicit alignment of each edited line. Valid only for text replace.
241
+
242
+ Each edited line keeps its original visible text extent as the reference:
243
+ ``LEFT`` keeps the left edge, ``RIGHT`` keeps the right edge, ``CENTERED``
244
+ keeps the midpoint, and ``JUSTIFIED`` keeps both edges by changing the word
245
+ gaps (the last line of a paragraph stays left-aligned).
246
+ """
247
+
248
+ LEFT = "left"
249
+ RIGHT = "right"
250
+ CENTERED = "centered"
251
+ JUSTIFIED = "justified"
252
+
253
+
239
254
  @dataclass(frozen=True)
240
255
  class TextLayoutRequest:
256
+ """Layout policy of a text edit.
257
+
258
+ An omitted ``mode`` means ``reflowWhenSupported``, as in the API. That mode
259
+ needs a ``profile``. When ``mode`` and ``profile`` are both omitted, the SDK
260
+ uses the ``noReflow`` profile.
261
+ """
262
+
241
263
  mode: Optional[TextLayoutMode] = None
242
264
  profile: Optional[TextLayoutProfile] = None
243
265
  hyphenation_enabled: Optional[bool] = None
266
+ alignment: Optional[TextAlignment] = None
244
267
 
245
268
  @classmethod
246
269
  def source_anchored(cls) -> "TextLayoutRequest":
@@ -257,8 +280,21 @@ class TextLayoutRequest:
257
280
  def with_hyphenation_enabled(self, enabled: bool) -> "TextLayoutRequest":
258
281
  return replace(self, hyphenation_enabled=enabled)
259
282
 
283
+ def with_alignment(self, alignment: TextAlignment) -> "TextLayoutRequest":
284
+ """Set the explicit alignment. Valid only for text replace."""
285
+ return replace(self, alignment=alignment)
286
+
287
+ def _effective_profile(self) -> Optional[TextLayoutProfile]:
288
+ """Return the profile to send. A layout with no mode and no profile gets ``noReflow``."""
289
+ if self.profile is None and self.mode is None:
290
+ return TextLayoutProfile.NO_REFLOW
291
+ return self.profile
292
+
260
293
  def validated(self) -> "TextLayoutRequest":
261
- mode = self.mode or TextLayoutMode.SOURCE_ANCHORED
294
+ # The API treats an omitted mode as reflowWhenSupported.
295
+ mode = self.mode or TextLayoutMode.REFLOW_WHEN_SUPPORTED
296
+ if self.alignment is not None and not isinstance(self.alignment, TextAlignment):
297
+ raise ValidationException("layout.alignment must be a TextAlignment")
262
298
  if mode is TextLayoutMode.SOURCE_ANCHORED and self.profile is not None:
263
299
  raise ValidationException("sourceAnchored layout must not specify profile")
264
300
  if (
@@ -268,13 +304,17 @@ class TextLayoutRequest:
268
304
  raise ValidationException(
269
305
  "layout.hyphenationEnabled is not valid when layout.mode is sourceAnchored"
270
306
  )
307
+ if mode is TextLayoutMode.SOURCE_ANCHORED and self.alignment is not None:
308
+ raise ValidationException(
309
+ "layout.alignment is not valid when layout.mode is sourceAnchored"
310
+ )
271
311
  if (
272
312
  mode
273
313
  in (
274
314
  TextLayoutMode.REFLOW_WHEN_SUPPORTED,
275
315
  TextLayoutMode.REQUIRE_REFLOW,
276
316
  )
277
- and self.profile is None
317
+ and self._effective_profile() is None
278
318
  ):
279
319
  raise ValidationException(
280
320
  f"{mode.value} profile must be one of default, bodyText, noReflow"
@@ -283,15 +323,23 @@ class TextLayoutRequest:
283
323
 
284
324
  def to_dict(self) -> dict[str, Any]:
285
325
  self.validated()
326
+ profile = self._effective_profile()
286
327
  return _without_none(
287
328
  {
288
329
  "mode": self.mode.value if self.mode else None,
289
- "profile": self.profile.value if self.profile else None,
330
+ "profile": profile.value if profile else None,
290
331
  "hyphenationEnabled": self.hyphenation_enabled,
332
+ "alignment": self.alignment.value if self.alignment else None,
291
333
  }
292
334
  )
293
335
 
294
336
 
337
+ def _reject_alignment(layout: Optional[TextLayoutRequest]) -> None:
338
+ """Reject ``layout.alignment`` on operations other than text replace."""
339
+ if layout is not None and layout.alignment is not None:
340
+ raise ValidationException("layout.alignment is valid only for text replace")
341
+
342
+
295
343
  @dataclass(frozen=True)
296
344
  class TextStyleNumericFilterRequest:
297
345
  eq: float
@@ -764,43 +812,52 @@ class TextReplaceRequest:
764
812
  return replace(self, pages=tuple(pages)).validated()
765
813
 
766
814
  def validated(self) -> "TextReplaceRequest":
815
+ """Validate the request.
816
+
817
+ ``replaceWithImage`` needs a ``sourceAnchored`` layout. When ``layout`` is
818
+ ``None``, the returned request has ``TextLayoutRequest.source_anchored()``.
819
+ """
767
820
  _validated_pages(self.pages)
768
821
  self.select.validated()
769
822
  if (self.replace_with is None) == (self.replace_with_image is None):
770
823
  raise ValidationException(
771
824
  "Exactly one of replaceWith or replaceWithImage is required"
772
825
  )
826
+ request = self
773
827
  if self.replace_with_image is not None:
774
828
  self.replace_with_image.validated()
775
829
  if self.style is not None:
776
830
  raise ValidationException("style is not valid with replaceWithImage")
777
- if self.layout and self.layout.mode not in (
778
- None,
779
- TextLayoutMode.SOURCE_ANCHORED,
780
- ):
831
+ if self.layout is not None and self.layout.alignment is not None:
832
+ raise ValidationException(
833
+ "layout.alignment is not valid with replaceWithImage"
834
+ )
835
+ if self.layout is None:
836
+ request = replace(self, layout=TextLayoutRequest.source_anchored())
837
+ elif self.layout.mode is not TextLayoutMode.SOURCE_ANCHORED:
781
838
  raise ValidationException(
782
839
  "replaceWithImage supports only sourceAnchored layout"
783
840
  )
784
841
  if self.style is not None:
785
842
  self.style.validated()
786
- if self.layout is not None:
787
- self.layout.validated()
788
- return self
843
+ if request.layout is not None:
844
+ request.layout.validated()
845
+ return request
789
846
 
790
847
  def to_dict(self) -> dict[str, Any]:
791
- self.validated()
848
+ request = self.validated()
792
849
  return _without_none(
793
850
  {
794
- "pages": list(self.pages) if self.pages is not None else None,
795
- "select": self.select.to_dict(),
796
- "replaceWith": self.replace_with,
851
+ "pages": list(request.pages) if request.pages is not None else None,
852
+ "select": request.select.to_dict(),
853
+ "replaceWith": request.replace_with,
797
854
  "replaceWithImage": (
798
- self.replace_with_image.to_dict()
799
- if self.replace_with_image
855
+ request.replace_with_image.to_dict()
856
+ if request.replace_with_image
800
857
  else None
801
858
  ),
802
- "style": self.style.to_dict() if self.style else None,
803
- "layout": self.layout.to_dict() if self.layout else None,
859
+ "style": request.style.to_dict() if request.style else None,
860
+ "layout": request.layout.to_dict() if request.layout else None,
804
861
  }
805
862
  )
806
863
 
@@ -815,6 +872,44 @@ class TextReplaceBuilder(_SelectorLayoutBuilder, _TextStyleBuilderBase):
815
872
  self._replace_with_image: Optional[TextReplacementImageRequest] = None
816
873
  self._style: Optional[TextStyleSetRequest] = None
817
874
  self._reset_spacing_overrides: Optional[bool] = None
875
+ self._alignment: Optional[TextAlignment] = None
876
+
877
+ def alignment(self, alignment: TextAlignment) -> "TextReplaceBuilder":
878
+ """Align each edited line explicitly. Valid only for text replace.
879
+
880
+ Without a layout, this selects ``reflowWhenSupported`` with the
881
+ ``noReflow`` profile, the API default for an omitted layout. It can be
882
+ combined with ``reflow_when_supported(...)`` and ``require_reflow(...)``
883
+ in any order. ``source_anchored()`` and ``replace_with_image(...)`` are
884
+ rejected at ``build()``.
885
+
886
+ ``layout(...)`` keeps this alignment, unless the layout that it gets has
887
+ its own alignment.
888
+
889
+ The API reports an alignment that it cannot apply as an error with code
890
+ ``TextOperationDiagnostic.ALIGNMENT_NOT_HONORED``. The API then does not
891
+ change the text of the unit named in the error. Other matches can still
892
+ change. The response is returned without an exception. Check
893
+ ``response.errors`` together with ``response.changed``.
894
+ """
895
+ self._alignment = alignment
896
+ return self
897
+
898
+ def layout(self, layout: Optional[TextLayoutRequest]) -> Self:
899
+ super().layout(layout)
900
+ if layout is not None and layout.alignment is not None:
901
+ self._alignment = layout.alignment
902
+ return self
903
+
904
+ def _resolved_layout(self) -> Optional[TextLayoutRequest]:
905
+ layout = super()._resolved_layout()
906
+ if self._alignment is None:
907
+ return layout
908
+ if layout is None:
909
+ layout = TextLayoutRequest.reflow_when_supported(
910
+ TextLayoutProfile.NO_REFLOW
911
+ )
912
+ return replace(layout, alignment=self._alignment)
818
913
 
819
914
  def replace_with(self, value: str) -> "TextReplaceBuilder":
820
915
  self._replace_with, self._replace_with_image = value, None
@@ -858,16 +953,13 @@ class TextReplaceBuilder(_SelectorLayoutBuilder, _TextStyleBuilderBase):
858
953
  if any(value is not None for value in style_values.values())
859
954
  else None
860
955
  )
861
- layout = self._resolved_layout()
862
- if self._replace_with_image is not None and layout is None:
863
- layout = TextLayoutRequest.source_anchored()
864
956
  return TextReplaceRequest(
865
957
  self._pages,
866
958
  self._selector(),
867
959
  self._replace_with,
868
960
  self._replace_with_image,
869
961
  style,
870
- layout,
962
+ self._resolved_layout(),
871
963
  ).validated()
872
964
 
873
965
 
@@ -895,6 +987,7 @@ class TextDeleteRequest:
895
987
  def validated(self) -> "TextDeleteRequest":
896
988
  _validated_pages(self.pages)
897
989
  self.select.validated()
990
+ _reject_alignment(self.layout)
898
991
  if self.layout:
899
992
  self.layout.validated()
900
993
  return self
@@ -1103,6 +1196,7 @@ class TextInsertRequest:
1103
1196
  raise ValidationException(
1104
1197
  "coordinate insertion style.patch requires font and size"
1105
1198
  )
1199
+ _reject_alignment(self.layout)
1106
1200
  if self.layout:
1107
1201
  self.layout.validated()
1108
1202
  return self
@@ -1237,6 +1331,7 @@ class TextStyleRequest:
1237
1331
  if self.style is None:
1238
1332
  raise ValidationException("style must not be null")
1239
1333
  self.style.validated()
1334
+ _reject_alignment(self.layout)
1240
1335
  if self.layout:
1241
1336
  self.layout.validated()
1242
1337
  return self
@@ -1364,6 +1459,12 @@ class TextStyleBuilder(_SelectorLayoutBuilder, _TextStyleBuilderBase):
1364
1459
 
1365
1460
  @dataclass(frozen=True)
1366
1461
  class TextOperationDiagnostic:
1462
+ # Error code of a requested ``layout.alignment`` that the API could not
1463
+ # apply. The API does not change the text of the unit named in the error.
1464
+ # Other matches can still change. No exception is raised; check
1465
+ # ``TextEditResponse.errors`` together with ``TextEditResponse.changed``.
1466
+ ALIGNMENT_NOT_HONORED = "TEXT_ALIGNMENT_NOT_HONORED"
1467
+
1367
1468
  page: Optional[int]
1368
1469
  code: Optional[str]
1369
1470
  message: Optional[str]
@@ -1465,6 +1566,7 @@ class TextEditResponse:
1465
1566
 
1466
1567
  TextLayoutRequest.Mode = TextLayoutMode # type: ignore[attr-defined]
1467
1568
  TextLayoutRequest.Profile = TextLayoutProfile # type: ignore[attr-defined]
1569
+ TextLayoutRequest.Alignment = TextAlignment # type: ignore[attr-defined]
1468
1570
 
1469
1571
 
1470
1572
  __all__ = [
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pdfdancer-client-python
3
- Version: 3.0.2
3
+ Version: 3.0.3
4
4
  Summary: Python client for PDFDancer API
5
5
  Author-email: "The Famous Cat Ltd." <hi@thefamouscat.com>
6
6
  License-Expression: Apache-2.0
@@ -276,6 +276,37 @@ pdf.text().insert(
276
276
  Each mutation returns `TextEditResponse`, including match and change counts, changed page numbers, per-change
277
277
  diagnostics, warnings, and errors.
278
278
 
279
+ ### Explicit alignment
280
+
281
+ Text replace can align each edited line explicitly with `TextAlignment`. Each edited line keeps its original visible
282
+ text extent as the reference: `LEFT` keeps the left edge, `RIGHT` keeps the right edge, `CENTERED` keeps the midpoint,
283
+ and `JUSTIFIED` keeps both edges by changing the word gaps. Without an alignment, the API detects the alignment from
284
+ the source PDF.
285
+
286
+ ```python
287
+ from pdfdancer import TextAlignment, TextOperationDiagnostic, TextReplaceRequest
288
+
289
+ response = pdf.text().replace(
290
+ TextReplaceRequest.literal("<<account_number>>", "BC5502731")
291
+ .alignment(TextAlignment.RIGHT)
292
+ .build()
293
+ )
294
+ if any(e.code == TextOperationDiagnostic.ALIGNMENT_NOT_HONORED for e in response.errors or ()):
295
+ ... # the text of the unit named in the error was not changed; other matches can have changed
296
+ ```
297
+
298
+ - `alignment()` alone uses `reflowWhenSupported` with the `noReflow` profile. You can combine it with
299
+ `reflow_when_supported(profile)` or `require_reflow(profile)` in any order. `layout(...)` keeps an alignment that
300
+ you set with `alignment()`, unless the layout that you pass has its own alignment.
301
+ - A layout with no mode and no profile (for example, `hyphenation_enabled(False)` alone) uses the `noReflow` profile.
302
+ - `replace_with_image(...)` uses a `sourceAnchored` layout. If you do not set a layout, the SDK sets it.
303
+ - `alignment()` is valid only for replace. With `source_anchored()` or `replace_with_image(...)`, `build()` raises
304
+ `ValidationException`. The delete, insert, and style requests reject a layout that has an alignment.
305
+ - If the API cannot apply the alignment (for example, the replacement adds or removes a line, or the profile re-wraps
306
+ the lines), the response has the error code `TextOperationDiagnostic.ALIGNMENT_NOT_HONORED`. The API does not change
307
+ the text of the unit named in the error. Other matches can still change. The SDK does not raise an exception for
308
+ this error. Check `response.errors` together with `response.changed`.
309
+
279
310
  ## Shared Models
280
311
 
281
312
  `Color` requires integral RGBA components in the inclusive range 0–255. Alpha defaults to 255; `BLACK`, `WHITE`, and
@@ -38,4 +38,5 @@ src/pdfdancer_client_python.egg-info/PKG-INFO
38
38
  src/pdfdancer_client_python.egg-info/SOURCES.txt
39
39
  src/pdfdancer_client_python.egg-info/dependency_links.txt
40
40
  src/pdfdancer_client_python.egg-info/requires.txt
41
+ src/pdfdancer_client_python.egg-info/scm_file_list.json
41
42
  src/pdfdancer_client_python.egg-info/top_level.txt