pdfdancer-client-python 3.0.2__py3-none-any.whl → 3.0.3__py3-none-any.whl

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.
pdfdancer/__init__.py CHANGED
@@ -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",
pdfdancer/_version.py CHANGED
@@ -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
pdfdancer/text_editing.py CHANGED
@@ -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
@@ -1,6 +1,6 @@
1
- pdfdancer/__init__.py,sha256=T6UkNQSaErDTqEJUi7EDhMRF1hhETuX-RE_7ucdW8k0,4971
1
+ pdfdancer/__init__.py,sha256=tkZAb51hBgxiXyOub-6Wup3pOCZ16ekGfFcJ6A3pg2E,5011
2
2
  pdfdancer/_runtime_version.py,sha256=UIId9w7Jk97tPVOppEJeq4HKVEt3BIMc6jeThKU31k4,825
3
- pdfdancer/_version.py,sha256=IS0JGNPBtDUZ6jdRad-5XG8y5N-886r_Fw6pVepeFlQ,520
3
+ pdfdancer/_version.py,sha256=itzW5wQOJlNCDCkbdrCTjhKBHLwDd7CBHhnL-o3GHkM,520
4
4
  pdfdancer/exceptions.py,sha256=U6kD3NvcdNt05_OU11Tml5dXGtlodEtYC9zcV4fHXkc,2270
5
5
  pdfdancer/fingerprint.py,sha256=eL3PHPgv-knMya7s95RXg3qzzpkAA1aevxqb6tuOb34,3061
6
6
  pdfdancer/image_builder.py,sha256=R4ik7ZN-iGWUsy7UHoMvpAEzc_MHquPY9Q27g_zuEtI,2987
@@ -8,11 +8,11 @@ pdfdancer/models.py,sha256=xHMJJFKZhZFPwuoobzCHiuuaW4md4hWQTE4rmeqathE,54316
8
8
  pdfdancer/page_builder.py,sha256=2Ll98fkNen7dtlQe_uhYDJPKqqnqMMeOTYlymeWtaII,3528
9
9
  pdfdancer/path_builder.py,sha256=znQD3zgBs7u--pQ3OdUJOSvBhBLCm80pdH6Kg0_T-io,28502
10
10
  pdfdancer/pdfdancer_v2.py,sha256=GAA4QI9O07VZZNAu2MKcnN2EvroRIeonAwdv53MBiFM,123931
11
- pdfdancer/text_editing.py,sha256=iA3n-yWca95ilNJSHMxFirGKhXpl_SGgg2NuuAUVGOQ,51768
11
+ pdfdancer/text_editing.py,sha256=aM2tifSALNsoYSoR2EnFJzia23hQrGKKUSW31M_nNpA,56593
12
12
  pdfdancer/types.py,sha256=Mwr4d1C-pS7kSctgXH0F6LEOu8Q0EFaFAOMjiGlrRaQ,16961
13
- pdfdancer_client_python-3.0.2.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
14
- pdfdancer_client_python-3.0.2.dist-info/licenses/NOTICE,sha256=xaC4l-IChAmtViNDie8ZWzUk0O6XRMyzOl0zLmVZ2HE,232
15
- pdfdancer_client_python-3.0.2.dist-info/METADATA,sha256=yQ7Ms-e10HbluHhUUy6Qx1jmFP_n_rdPbrgbUfrrOw8,18058
16
- pdfdancer_client_python-3.0.2.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
17
- pdfdancer_client_python-3.0.2.dist-info/top_level.txt,sha256=ICwSVRpcCKrdBF9QlaX9Y0e_N3Nk1p7QVxadGOnbxeY,10
18
- pdfdancer_client_python-3.0.2.dist-info/RECORD,,
13
+ pdfdancer_client_python-3.0.3.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
14
+ pdfdancer_client_python-3.0.3.dist-info/licenses/NOTICE,sha256=xaC4l-IChAmtViNDie8ZWzUk0O6XRMyzOl0zLmVZ2HE,232
15
+ pdfdancer_client_python-3.0.3.dist-info/METADATA,sha256=0TXbLto61uTE9M6QfX_xjT_fWLux5B8DMsCYLXeMGxs,20061
16
+ pdfdancer_client_python-3.0.3.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
17
+ pdfdancer_client_python-3.0.3.dist-info/top_level.txt,sha256=ICwSVRpcCKrdBF9QlaX9Y0e_N3Nk1p7QVxadGOnbxeY,10
18
+ pdfdancer_client_python-3.0.3.dist-info/RECORD,,
@@ -1,5 +1,5 @@
1
1
  Wheel-Version: 1.0
2
- Generator: setuptools (83.0.0)
2
+ Generator: setuptools (84.2.1)
3
3
  Root-Is-Purelib: true
4
4
  Tag: py3-none-any
5
5