pdfdancer-client-python 3.0.1__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
@@ -42,6 +42,16 @@ from .models import (
42
42
  Point,
43
43
  Position,
44
44
  PositionMode,
45
+ ReadingUnit,
46
+ ReadingUnitBounds,
47
+ ReadingUnitDocumentAnalysis,
48
+ ReadingUnitMode,
49
+ ReadingUnitPageAnalysis,
50
+ ReadingUnitProvenance,
51
+ ReadingUnitRelationship,
52
+ ReadingUnitRelationshipType,
53
+ ReadingUnitRole,
54
+ ReadingUnitStreamMembership,
45
55
  ShapeType,
46
56
  Size,
47
57
  StandardFonts,
@@ -53,6 +63,7 @@ from .text_editing import (
53
63
  PdfAffineTransformBuilder,
54
64
  PdfColorRequest,
55
65
  PdfColorSpace,
66
+ TextAlignment,
56
67
  TextDeleteBuilder,
57
68
  TextDeleteRequest,
58
69
  TextEditChangeDiagnostic,
@@ -116,6 +127,16 @@ __all__ = [
116
127
  "Point",
117
128
  "StandardFonts",
118
129
  "PageSize",
130
+ "ReadingUnit",
131
+ "ReadingUnitBounds",
132
+ "ReadingUnitDocumentAnalysis",
133
+ "ReadingUnitMode",
134
+ "ReadingUnitPageAnalysis",
135
+ "ReadingUnitProvenance",
136
+ "ReadingUnitRelationship",
137
+ "ReadingUnitRelationshipType",
138
+ "ReadingUnitRole",
139
+ "ReadingUnitStreamMembership",
119
140
  "Orientation",
120
141
  "FontRecommendation",
121
142
  "FontType",
@@ -143,6 +164,7 @@ __all__ = [
143
164
  "PdfAffineTransformBuilder",
144
165
  "PdfColorRequest",
145
166
  "PdfColorSpace",
167
+ "TextAlignment",
146
168
  "TextDeleteBuilder",
147
169
  "TextDeleteRequest",
148
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.1'
22
- __version_tuple__ = version_tuple = (3, 0, 1)
21
+ __version__ = version = '3.0.3'
22
+ __version_tuple__ = version_tuple = (3, 0, 3)
23
23
 
24
24
  __commit_id__ = commit_id = None
pdfdancer/models.py CHANGED
@@ -268,6 +268,119 @@ class ShapeType(Enum):
268
268
  RECT = "RECT" # Rectangular area with width and height
269
269
 
270
270
 
271
+ class ReadingUnitRole(Enum):
272
+ HEADING = "HEADING"
273
+ PARAGRAPH = "PARAGRAPH"
274
+ LIST = "LIST"
275
+ TABLE = "TABLE"
276
+ CAPTION = "CAPTION"
277
+ CALLOUT = "CALLOUT"
278
+ PREFORMATTED_TEXT = "PREFORMATTED_TEXT"
279
+ PAGE_HEADER = "PAGE_HEADER"
280
+ PAGE_FOOTER = "PAGE_FOOTER"
281
+ PAGE_NUMBER = "PAGE_NUMBER"
282
+ FOOTNOTE = "FOOTNOTE"
283
+ WATERMARK = "WATERMARK"
284
+ UNKNOWN = "UNKNOWN"
285
+
286
+ @classmethod
287
+ def from_value(cls, value: Any) -> tuple["ReadingUnitRole", str]:
288
+ raw = value if isinstance(value, str) else "UNKNOWN"
289
+ try:
290
+ return cls(raw), raw
291
+ except ValueError:
292
+ return cls.UNKNOWN, raw
293
+
294
+
295
+ class ReadingUnitRelationshipType(Enum):
296
+ CAPTION_FOR = "CAPTION_FOR"
297
+ HEADING_PARENT_OF = "HEADING_PARENT_OF"
298
+ UNKNOWN = "UNKNOWN"
299
+
300
+ @classmethod
301
+ def from_value(cls, value: Any) -> tuple["ReadingUnitRelationshipType", str]:
302
+ raw = value if isinstance(value, str) else "UNKNOWN"
303
+ try:
304
+ return cls(raw), raw
305
+ except ValueError:
306
+ return cls.UNKNOWN, raw
307
+
308
+
309
+ class ReadingUnitMode(Enum):
310
+ PRIMARY = "PRIMARY"
311
+ UNKNOWN = "UNKNOWN"
312
+
313
+ @classmethod
314
+ def from_value(cls, value: Any) -> tuple["ReadingUnitMode", str]:
315
+ raw = value if isinstance(value, str) else "UNKNOWN"
316
+ try:
317
+ return cls(raw), raw
318
+ except ValueError:
319
+ return cls.UNKNOWN, raw
320
+
321
+
322
+ @dataclass(frozen=True)
323
+ class ReadingUnitBounds:
324
+ x: float
325
+ y: float
326
+ width: float
327
+ height: float
328
+
329
+
330
+ @dataclass(frozen=True)
331
+ class ReadingUnitProvenance:
332
+ page_number: int
333
+ source_element_ids: List[str]
334
+ bounds: ReadingUnitBounds
335
+
336
+
337
+ @dataclass(frozen=True)
338
+ class ReadingUnitStreamMembership:
339
+ included: bool
340
+ order: Optional[int]
341
+
342
+
343
+ @dataclass(frozen=True)
344
+ class ReadingUnitRelationship:
345
+ type: ReadingUnitRelationshipType
346
+ raw_type: str
347
+ target_unit_id: str
348
+
349
+ @classmethod
350
+ def from_dict(cls, data: Mapping[str, Any]) -> "ReadingUnitRelationship":
351
+ relationship_type, raw_type = ReadingUnitRelationshipType.from_value(
352
+ data.get("type")
353
+ )
354
+ return cls(relationship_type, raw_type, str(data.get("targetUnitId", "")))
355
+
356
+
357
+ @dataclass(frozen=True)
358
+ class ReadingUnit:
359
+ id: str
360
+ role: ReadingUnitRole
361
+ raw_role: str
362
+ text: str
363
+ stream: Mapping[str, ReadingUnitStreamMembership]
364
+ provenance: ReadingUnitProvenance
365
+ relationships: List[ReadingUnitRelationship]
366
+
367
+
368
+ @dataclass(frozen=True)
369
+ class ReadingUnitPageAnalysis:
370
+ page_number: int
371
+ mode: ReadingUnitMode
372
+ raw_mode: str
373
+ units: List[ReadingUnit]
374
+
375
+
376
+ @dataclass(frozen=True)
377
+ class ReadingUnitDocumentAnalysis:
378
+ page_count: int
379
+ mode: ReadingUnitMode
380
+ raw_mode: str
381
+ pages: List[ReadingUnitPageAnalysis]
382
+
383
+
271
384
  @dataclass
272
385
  class Point:
273
386
  """Represents a 2D point with x and y coordinates."""
pdfdancer/pdfdancer_v2.py CHANGED
@@ -74,6 +74,15 @@ from .models import (
74
74
  PathObjectRef,
75
75
  Position,
76
76
  PositionMode,
77
+ ReadingUnit,
78
+ ReadingUnitBounds,
79
+ ReadingUnitDocumentAnalysis,
80
+ ReadingUnitMode,
81
+ ReadingUnitPageAnalysis,
82
+ ReadingUnitProvenance,
83
+ ReadingUnitRelationship,
84
+ ReadingUnitRole,
85
+ ReadingUnitStreamMembership,
77
86
  ShapeType,
78
87
  TextObjectRef,
79
88
  )
@@ -721,6 +730,11 @@ class PageClient:
721
730
  def get_snapshot(self, types: Optional[str] = None) -> PageSnapshot:
722
731
  return self.root.get_page_snapshot(self.page_number, types)
723
732
 
733
+ def analyze_reading_units(self) -> ReadingUnitPageAnalysis:
734
+ return cast(
735
+ ReadingUnitPageAnalysis, self.root.analyze_reading_units(self.page_number)
736
+ )
737
+
724
738
  @property
725
739
  def size(self) -> Optional[PageSize]:
726
740
  """Property alias for page size."""
@@ -2480,6 +2494,22 @@ class PDFDancer:
2480
2494
 
2481
2495
  return self._parse_document_snapshot(data)
2482
2496
 
2497
+ def analyze_reading_units(
2498
+ self, page_number: Optional[int] = None
2499
+ ) -> Union[ReadingUnitDocumentAnalysis, ReadingUnitPageAnalysis]:
2500
+ """Analyze the current session PDF, or one one-based page, into reading units."""
2501
+ if page_number is not None:
2502
+ if page_number < 1:
2503
+ raise ValidationException(
2504
+ f"Page number must be >= 1 (1-based indexing), got {page_number}"
2505
+ )
2506
+ response = self._make_request(
2507
+ "GET", f"/pdf/page/{page_number}/reading-units"
2508
+ )
2509
+ return self._parse_reading_unit_page_analysis(response.json())
2510
+ response = self._make_request("GET", "/pdf/document/reading-units")
2511
+ return self._parse_reading_unit_document_analysis(response.json())
2512
+
2483
2513
  def get_page_snapshot(
2484
2514
  self, page_number: int, types: Optional[str] = None
2485
2515
  ) -> PageSnapshot:
@@ -3129,6 +3159,64 @@ class PDFDancer:
3129
3159
 
3130
3160
  return DocumentSnapshot(page_count=page_count, fonts=fonts, pages=pages)
3131
3161
 
3162
+ def _parse_reading_unit_page_analysis(
3163
+ self, data: Mapping[str, Any]
3164
+ ) -> ReadingUnitPageAnalysis:
3165
+ mode, raw_mode = ReadingUnitMode.from_value(data.get("mode"))
3166
+ return ReadingUnitPageAnalysis(
3167
+ page_number=int(data.get("pageNumber", 0)),
3168
+ mode=mode,
3169
+ raw_mode=raw_mode,
3170
+ units=[self._parse_reading_unit(unit) for unit in data.get("units", [])],
3171
+ )
3172
+
3173
+ def _parse_reading_unit_document_analysis(
3174
+ self, data: Mapping[str, Any]
3175
+ ) -> ReadingUnitDocumentAnalysis:
3176
+ mode, raw_mode = ReadingUnitMode.from_value(data.get("mode"))
3177
+ return ReadingUnitDocumentAnalysis(
3178
+ page_count=int(data.get("pageCount", 0)),
3179
+ mode=mode,
3180
+ raw_mode=raw_mode,
3181
+ pages=[
3182
+ self._parse_reading_unit_page_analysis(page)
3183
+ for page in data.get("pages", [])
3184
+ ],
3185
+ )
3186
+
3187
+ def _parse_reading_unit(self, data: Mapping[str, Any]) -> ReadingUnit:
3188
+ role, raw_role = ReadingUnitRole.from_value(data.get("role"))
3189
+ provenance_data = data.get("provenance") or {}
3190
+ bounds_data = provenance_data.get("bounds") or {}
3191
+ stream = {
3192
+ str(mode): ReadingUnitStreamMembership(
3193
+ bool(membership.get("included", False)), membership.get("order")
3194
+ )
3195
+ for mode, membership in (data.get("stream") or {}).items()
3196
+ }
3197
+ provenance = ReadingUnitProvenance(
3198
+ page_number=int(provenance_data.get("pageNumber", 0)),
3199
+ source_element_ids=list(provenance_data.get("sourceElementIds") or []),
3200
+ bounds=ReadingUnitBounds(
3201
+ float(bounds_data.get("x", 0)),
3202
+ float(bounds_data.get("y", 0)),
3203
+ float(bounds_data.get("width", 0)),
3204
+ float(bounds_data.get("height", 0)),
3205
+ ),
3206
+ )
3207
+ return ReadingUnit(
3208
+ id=str(data.get("id", "")),
3209
+ role=role,
3210
+ raw_role=raw_role,
3211
+ text=str(data.get("text", "")),
3212
+ stream=stream,
3213
+ provenance=provenance,
3214
+ relationships=[
3215
+ ReadingUnitRelationship.from_dict(item)
3216
+ for item in data.get("relationships", [])
3217
+ ],
3218
+ )
3219
+
3132
3220
  # Context Manager Support (Python enhancement)
3133
3221
  def __enter__(self) -> "PDFDancer":
3134
3222
  """Context manager entry."""
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.1
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
@@ -36,7 +36,7 @@ Dynamic: license-file
36
36
 
37
37
  # PDFDancer Python Client
38
38
 
39
- This README documents `pdfdancer-client-python` version `3.0.0`.
39
+ This README documents `pdfdancer-client-python` version `3.0.2`.
40
40
 
41
41
  ![PDFDancer logo](media/logo-silver-60h.webp)
42
42
 
@@ -69,7 +69,7 @@ pixel-perfect control from Python. The same API is also available for TypeScript
69
69
  ## Installation
70
70
 
71
71
  ```bash
72
- pip install pdfdancer-client-python==3.0.0
72
+ pip install pdfdancer-client-python==3.0.2
73
73
 
74
74
  # Editable install for local development
75
75
  pip install -e .
@@ -139,6 +139,20 @@ snapshot = first_page.get_snapshot()
139
139
 
140
140
  Page-scoped selectors, text editing, and builders automatically restrict the operation to that page.
141
141
 
142
+ ## Reading Units
143
+
144
+ Reading-unit analysis returns semantically classified text blocks with reading order, source provenance, bounds, and
145
+ relationships. Each call analyzes the current session state and makes a fresh request.
146
+
147
+ ```python
148
+ document_analysis = pdf.analyze_reading_units()
149
+ page_analysis = pdf.page(1).analyze_reading_units()
150
+
151
+ for page in document_analysis.pages:
152
+ for unit in page.units:
153
+ print(unit.role, unit.text)
154
+ ```
155
+
142
156
  ## Selection
143
157
 
144
158
  Document- and page-scoped selectors return typed objects for images, paths, form XObjects, and form fields. Position
@@ -262,6 +276,37 @@ pdf.text().insert(
262
276
  Each mutation returns `TextEditResponse`, including match and change counts, changed page numbers, per-change
263
277
  diagnostics, warnings, and errors.
264
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
+
265
310
  ## Shared Models
266
311
 
267
312
  `Color` requires integral RGBA components in the inclusive range 0–255. Alpha defaults to 255; `BLACK`, `WHITE`, and
@@ -412,8 +457,8 @@ Releases are published automatically to PyPI when a `v*` tag is pushed to GitHub
412
457
 
413
458
  ```bash
414
459
  # Create and push a release tag — GitHub Actions handles the rest
415
- git tag v2.0.0
416
- git push origin v2.0.0
460
+ git tag v3.0.2
461
+ git push origin v3.0.2
417
462
  ```
418
463
 
419
464
  #### Code Quality
@@ -0,0 +1,18 @@
1
+ pdfdancer/__init__.py,sha256=tkZAb51hBgxiXyOub-6Wup3pOCZ16ekGfFcJ6A3pg2E,5011
2
+ pdfdancer/_runtime_version.py,sha256=UIId9w7Jk97tPVOppEJeq4HKVEt3BIMc6jeThKU31k4,825
3
+ pdfdancer/_version.py,sha256=itzW5wQOJlNCDCkbdrCTjhKBHLwDd7CBHhnL-o3GHkM,520
4
+ pdfdancer/exceptions.py,sha256=U6kD3NvcdNt05_OU11Tml5dXGtlodEtYC9zcV4fHXkc,2270
5
+ pdfdancer/fingerprint.py,sha256=eL3PHPgv-knMya7s95RXg3qzzpkAA1aevxqb6tuOb34,3061
6
+ pdfdancer/image_builder.py,sha256=R4ik7ZN-iGWUsy7UHoMvpAEzc_MHquPY9Q27g_zuEtI,2987
7
+ pdfdancer/models.py,sha256=xHMJJFKZhZFPwuoobzCHiuuaW4md4hWQTE4rmeqathE,54316
8
+ pdfdancer/page_builder.py,sha256=2Ll98fkNen7dtlQe_uhYDJPKqqnqMMeOTYlymeWtaII,3528
9
+ pdfdancer/path_builder.py,sha256=znQD3zgBs7u--pQ3OdUJOSvBhBLCm80pdH6Kg0_T-io,28502
10
+ pdfdancer/pdfdancer_v2.py,sha256=GAA4QI9O07VZZNAu2MKcnN2EvroRIeonAwdv53MBiFM,123931
11
+ pdfdancer/text_editing.py,sha256=aM2tifSALNsoYSoR2EnFJzia23hQrGKKUSW31M_nNpA,56593
12
+ pdfdancer/types.py,sha256=Mwr4d1C-pS7kSctgXH0F6LEOu8Q0EFaFAOMjiGlrRaQ,16961
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
 
@@ -1,18 +0,0 @@
1
- pdfdancer/__init__.py,sha256=iD0IWfpLFrPoFQhsZ_fGUpv9fH21QNJchM_23pTtdds,4419
2
- pdfdancer/_runtime_version.py,sha256=UIId9w7Jk97tPVOppEJeq4HKVEt3BIMc6jeThKU31k4,825
3
- pdfdancer/_version.py,sha256=DQj8PXaBgkooJVvjTVd86hfQE03x_PUMKRF3guh3670,520
4
- pdfdancer/exceptions.py,sha256=U6kD3NvcdNt05_OU11Tml5dXGtlodEtYC9zcV4fHXkc,2270
5
- pdfdancer/fingerprint.py,sha256=eL3PHPgv-knMya7s95RXg3qzzpkAA1aevxqb6tuOb34,3061
6
- pdfdancer/image_builder.py,sha256=R4ik7ZN-iGWUsy7UHoMvpAEzc_MHquPY9Q27g_zuEtI,2987
7
- pdfdancer/models.py,sha256=6N-rybJnXo2Y3KrWcBxN0uVq5HxyrVDqMO52lcvW_G4,51558
8
- pdfdancer/page_builder.py,sha256=2Ll98fkNen7dtlQe_uhYDJPKqqnqMMeOTYlymeWtaII,3528
9
- pdfdancer/path_builder.py,sha256=znQD3zgBs7u--pQ3OdUJOSvBhBLCm80pdH6Kg0_T-io,28502
10
- pdfdancer/pdfdancer_v2.py,sha256=8YiMMDeaybPNBpybf9kESwnE48wscdOlk1AcJrDCBSc,120419
11
- pdfdancer/text_editing.py,sha256=iA3n-yWca95ilNJSHMxFirGKhXpl_SGgg2NuuAUVGOQ,51768
12
- pdfdancer/types.py,sha256=Mwr4d1C-pS7kSctgXH0F6LEOu8Q0EFaFAOMjiGlrRaQ,16961
13
- pdfdancer_client_python-3.0.1.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
14
- pdfdancer_client_python-3.0.1.dist-info/licenses/NOTICE,sha256=xaC4l-IChAmtViNDie8ZWzUk0O6XRMyzOl0zLmVZ2HE,232
15
- pdfdancer_client_python-3.0.1.dist-info/METADATA,sha256=oiYBb7IxHTiNZL3ZyIo30Ht0Q9xpzMV_rVrB3_GI-vw,17618
16
- pdfdancer_client_python-3.0.1.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
17
- pdfdancer_client_python-3.0.1.dist-info/top_level.txt,sha256=ICwSVRpcCKrdBF9QlaX9Y0e_N3Nk1p7QVxadGOnbxeY,10
18
- pdfdancer_client_python-3.0.1.dist-info/RECORD,,