pdfdancer-client-python 0.2.17__py3-none-any.whl → 0.2.19__py3-none-any.whl

pdfdancer/__init__.py

@@ -13,14 +13,18 @@ from .exceptions import (
 from .models import (
     ObjectRef, Position, ObjectType, Font, Color, Image, BoundingRect, Paragraph, FormFieldRef, TextObjectRef,
     PageRef, PositionMode, ShapeType, Point, StandardFonts, PageSize, Orientation, TextStatus, FontRecommendation,
-    FontType
+    FontType, PathSegment, Line, Bezier, Path
 )
 from .paragraph_builder import ParagraphBuilder
+from .path_builder import PathBuilder, LineBuilder, BezierBuilder
 
 __version__ = "1.0.0"
 __all__ = [
     "PDFDancer",
     "ParagraphBuilder",
+    "PathBuilder",
+    "LineBuilder",
+    "BezierBuilder",
     "ObjectRef",
     "Position",
     "ObjectType",
@@ -41,6 +45,10 @@ __all__ = [
     "TextStatus",
     "FontRecommendation",
     "FontType",
+    "PathSegment",
+    "Line",
+    "Bezier",
+    "Path",
     "PdfDancerException",
     "FontNotFoundException",
     "ValidationException",

pdfdancer/exceptions.py

@@ -5,7 +5,7 @@ Mirrors the Java client exception hierarchy.
 
 from typing import Optional
 
-import requests
+import httpx
 
 
 class PdfDancerException(Exception):
@@ -32,10 +32,10 @@ class FontNotFoundException(PdfDancerException):
 class HttpClientException(PdfDancerException):
     """
     Exception raised for HTTP client errors during API communication.
-    Wraps requests exceptions and HTTP errors from the API.
+    Wraps httpx exceptions and HTTP errors from the API.
     """
 
-    def __init__(self, message: str, response: Optional[requests.Response] = None, cause: Optional[Exception] = None):
+    def __init__(self, message: str, response: Optional[httpx.Response] = None, cause: Optional[Exception] = None):
         super().__init__(message, cause)
         self.response = response
         self.status_code = response.status_code if response else None

pdfdancer/fingerprint.py

@@ -0,0 +1,121 @@
+import hashlib
+import locale
+import os
+import platform
+import socket
+import uuid
+from datetime import datetime
+from pathlib import Path
+
+
+class Fingerprint:
+    """Generates a fingerprint hash for API request identification."""
+
+    _SALT_FILE = Path.home() / ".pdfdancer" / "fingerprint.salt"
+
+    @classmethod
+    def generate(cls) -> str:
+        """Generate X-Fingerprint header value.
+
+        Returns:
+            SHA256 hash of fingerprint components
+        """
+        ip_hash = cls._get_local_ip()
+        uid_hash = cls._get_uid()
+        os_type = platform.system()
+        sdk_language = "python"
+        timezone = cls._get_timezone()
+        locale_str = cls._get_locale()
+        domain_hash = cls._get_hostname()
+        install_salt = cls._get_or_create_salt()
+
+        fingerprint_data = (
+                ip_hash +
+                uid_hash +
+                os_type +
+                sdk_language +
+                timezone +
+                locale_str +
+                domain_hash +
+                install_salt
+        )
+
+        return cls._hash(fingerprint_data)
+
+    @classmethod
+    def _get_local_ip(cls) -> str:
+        """Get local IP address."""
+        try:
+            return socket.gethostbyname(socket.gethostname())
+        except Exception:
+            return "unknown"
+
+    @classmethod
+    def _get_uid(cls) -> str:
+        """Get user login name."""
+        try:
+            return os.getlogin()
+        except Exception:
+            return "unknown"
+
+    @classmethod
+    def _get_timezone(cls) -> str:
+        """Get timezone name."""
+        try:
+            tz = datetime.now().astimezone().tzinfo
+            timezone_name = getattr(tz, 'key', str(tz))
+            return timezone_name
+        except Exception:
+            return "unknown"
+
+    @classmethod
+    def _get_locale(cls) -> str:
+        """Get default locale."""
+        try:
+            loc = locale.getlocale()[0]
+            return loc if loc else "en_US"
+        except Exception:
+            return "unknown"
+
+    @classmethod
+    def _get_hostname(cls) -> str:
+        """Get local hostname."""
+        try:
+            return socket.gethostname()
+        except Exception:
+            return "unknown"
+
+    @classmethod
+    def _get_or_create_salt(cls) -> str:
+        """Get or create persistent install salt.
+
+        Returns:
+            UUID string used as install salt
+        """
+        if cls._SALT_FILE.exists():
+            try:
+                return cls._SALT_FILE.read_text().strip()
+            except Exception:
+                pass
+
+        # Create salt file
+        salt = str(uuid.uuid4())
+        try:
+            cls._SALT_FILE.parent.mkdir(parents=True, exist_ok=True)
+            cls._SALT_FILE.write_text(salt)
+        except Exception:
+            pass
+
+        return salt
+
+    @classmethod
+    def _hash(cls, value: str) -> str:
+        """Generate SHA256 hash of value.
+
+        Args:
+            value: String to hash
+
+        Returns:
+            Hexadecimal SHA256 hash
+        """
+        return hashlib.sha256(value.encode('utf-8')).hexdigest()

pdfdancer/models.py

@@ -164,6 +164,8 @@ class ObjectType(Enum):
     TEXT_FIELD = "TEXT_FIELD"
     CHECK_BOX = "CHECK_BOX"
     RADIO_BUTTON = "RADIO_BUTTON"
+    BUTTON = "BUTTON"
+    DROPDOWN = "DROPDOWN"
 
 
 class PositionMode(Enum):
@@ -309,10 +311,15 @@ class ObjectRef:
 
     def to_dict(self) -> dict:
         """Convert to dictionary for JSON serialization."""
+        # Normalize type back to API format (API uses "CHECKBOX" not "CHECK_BOX")
+        type_value = self.type.value
+        if type_value == "CHECK_BOX":
+            type_value = "CHECKBOX"
+
         return {
             "internalId": self.internal_id,
             "position": FindRequest._position_to_dict(self.position),
-            "type": self.type.value
+            "type": type_value
         }
 
 
@@ -341,6 +348,117 @@ class Font:
             raise ValueError(f"Font size must be positive, got {self.size}")
 
 
+@dataclass
+class PathSegment:
+    """
+    Abstract base class for individual path segments within vector paths.
+    This class provides common properties for path elements including stroke and fill colors,
+    line width, and positioning. Concrete subclasses implement specific geometric shapes
+    like lines, curves, and bezier segments.
+    """
+    stroke_color: Optional[Color] = None
+    fill_color: Optional[Color] = None
+    stroke_width: Optional[float] = None
+    dash_array: Optional[List[float]] = None
+    dash_phase: Optional[float] = None
+
+    def get_stroke_color(self) -> Optional[Color]:
+        """Color used for drawing the segment's outline or stroke."""
+        return self.stroke_color
+
+    def get_fill_color(self) -> Optional[Color]:
+        """Color used for filling the segment's interior area (if applicable)."""
+        return self.fill_color
+
+    def get_stroke_width(self) -> Optional[float]:
+        """Width of the stroke line in PDF coordinate units."""
+        return self.stroke_width
+
+    def get_dash_array(self) -> Optional[List[float]]:
+        """Dash pattern for stroking the path segment. Null or empty means solid line."""
+        return self.dash_array
+
+    def get_dash_phase(self) -> Optional[float]:
+        """Dash phase (offset) into the dash pattern in user space units."""
+        return self.dash_phase
+
+
+@dataclass
+class Line(PathSegment):
+    """
+    Represents a straight line path segment between two points.
+    This class defines a linear path element connecting two coordinate points,
+    commonly used in vector graphics and geometric shapes within PDF documents.
+    """
+    p0: Optional[Point] = None
+    p1: Optional[Point] = None
+
+    def get_p0(self) -> Optional[Point]:
+        """Returns the starting point of this line segment."""
+        return self.p0
+
+    def get_p1(self) -> Optional[Point]:
+        """Returns the ending point of this line segment."""
+        return self.p1
+
+
+@dataclass
+class Bezier(PathSegment):
+    """
+    Represents a cubic Bezier curve path segment defined by four control points.
+    This class implements a cubic Bezier curve with start point, two control points,
+    and end point, providing smooth curved path segments for complex vector graphics.
+    """
+    p0: Optional[Point] = None
+    p1: Optional[Point] = None
+    p2: Optional[Point] = None
+    p3: Optional[Point] = None
+
+    def get_p0(self) -> Optional[Point]:
+        """Returns the starting point p0 of this Bezier segment."""
+        return self.p0
+
+    def get_p1(self) -> Optional[Point]:
+        """Returns the first control point p1 of this Bezier segment."""
+        return self.p1
+
+    def get_p2(self) -> Optional[Point]:
+        """Returns the second control point p2 of this Bezier segment."""
+        return self.p2
+
+    def get_p3(self) -> Optional[Point]:
+        """Returns the ending point p3 of this Bezier segment."""
+        return self.p3
+
+
+@dataclass
+class Path:
+    """
+    Represents a complex vector path consisting of multiple path segments.
+    This class encapsulates vector graphics data within PDF documents, composed of
+    various path elements like lines, curves, and shapes.
+    """
+    position: Optional[Position] = None
+    path_segments: Optional[List[PathSegment]] = None
+    even_odd_fill: Optional[bool] = None
+
+    def get_position(self) -> Optional[Position]:
+        """Returns the position of this path."""
+        return self.position
+
+    def set_position(self, position: Position) -> None:
+        """Sets the position of this path."""
+        self.position = position
+
+    def get_path_segments(self) -> Optional[List[PathSegment]]:
+        """Returns the list of path segments that compose this path."""
+        return self.path_segments
+
+    def get_even_odd_fill(self) -> Optional[bool]:
+        """Returns whether even-odd fill rule should be used (true) or nonzero (false)."""
+        return self.even_odd_fill
+
+
 @dataclass
 class Image:
     """
@@ -428,12 +546,9 @@ class DeleteRequest:
 
     def to_dict(self) -> dict:
         """Convert to dictionary for JSON serialization."""
+        # Use ObjectRef.to_dict() to ensure proper type normalization
         return {
-            "objectRef": {
-                "internalId": self.object_ref.internal_id,
-                "position": FindRequest._position_to_dict(self.object_ref.position),
-                "type": self.object_ref.type.value
-            }
+            "objectRef": self.object_ref.to_dict()
         }
 
 
@@ -446,12 +561,9 @@ class MoveRequest:
     def to_dict(self) -> dict:
         """Convert to dictionary for JSON serialization."""
         # Server API expects the new coordinates under 'newPosition'
+        # Use ObjectRef.to_dict() to ensure proper type normalization
         return {
-            "objectRef": {
-                "internalId": self.object_ref.internal_id,
-                "position": FindRequest._position_to_dict(self.object_ref.position),
-                "type": self.object_ref.type.value
-            },
+            "objectRef": self.object_ref.to_dict(),
             "newPosition": FindRequest._position_to_dict(self.position)
         }
 
@@ -487,7 +599,26 @@ class AddRequest:
     def _object_to_dict(self, obj: Any) -> dict:
         """Convert PDF object to dictionary for JSON serialization."""
         import base64
-        if isinstance(obj, Image):
+        from .models import Path as PathModel, Line, Bezier, PathSegment
+
+        if isinstance(obj, PathModel):
+            # Serialize Path object
+            segments = []
+            if obj.path_segments:
+                for seg in obj.path_segments:
+                    seg_dict = self._segment_to_dict(seg)
+                    # Include per-segment position to satisfy backend validation (matches Java client)
+                    if obj.position:
+                        seg_dict["position"] = FindRequest._position_to_dict(obj.position)
+                    segments.append(seg_dict)
+
+            return {
+                "type": "PATH",
+                "position": FindRequest._position_to_dict(obj.position) if obj.position else None,
+                "pathSegments": segments if segments else None,
+                "evenOddFill": obj.even_odd_fill
+            }
+        elif isinstance(obj, Image):
             size = None
             if obj.width is not None and obj.height is not None:
                 size = {"width": obj.width, "height": obj.height}
@@ -538,6 +669,61 @@ class AddRequest:
         else:
             raise ValueError(f"Unsupported object type: {type(obj)}")
 
+    def _segment_to_dict(self, segment: 'PathSegment') -> dict:
+        """Convert a PathSegment (Line or Bezier) to dictionary for JSON serialization."""
+        from .models import Line, Bezier
+
+        result = {}
+
+        # Add common PathSegment properties
+        if segment.stroke_color:
+            result["strokeColor"] = {
+                "red": segment.stroke_color.r,
+                "green": segment.stroke_color.g,
+                "blue": segment.stroke_color.b,
+                "alpha": segment.stroke_color.a
+            }
+
+        if segment.fill_color:
+            result["fillColor"] = {
+                "red": segment.fill_color.r,
+                "green": segment.fill_color.g,
+                "blue": segment.fill_color.b,
+                "alpha": segment.fill_color.a
+            }
+
+        if segment.stroke_width is not None:
+            result["strokeWidth"] = segment.stroke_width
+
+        if segment.dash_array:
+            result["dashArray"] = segment.dash_array
+
+        if segment.dash_phase is not None:
+            result["dashPhase"] = segment.dash_phase
+
+        # Add segment-specific properties
+        if isinstance(segment, Line):
+            result["type"] = "LINE"
+            result["segmentType"] = "LINE"
+            if segment.p0:
+                result["p0"] = {"x": segment.p0.x, "y": segment.p0.y}
+            if segment.p1:
+                result["p1"] = {"x": segment.p1.x, "y": segment.p1.y}
+
+        elif isinstance(segment, Bezier):
+            result["type"] = "BEZIER"
+            result["segmentType"] = "BEZIER"
+            if segment.p0:
+                result["p0"] = {"x": segment.p0.x, "y": segment.p0.y}
+            if segment.p1:
+                result["p1"] = {"x": segment.p1.x, "y": segment.p1.y}
+            if segment.p2:
+                result["p2"] = {"x": segment.p2.x, "y": segment.p2.y}
+            if segment.p3:
+                result["p3"] = {"x": segment.p3.x, "y": segment.p3.y}
+
+        return result
+
 
 @dataclass
 class ModifyRequest:
@@ -547,12 +733,9 @@ class ModifyRequest:
 
     def to_dict(self) -> dict:
         """Convert to dictionary for JSON serialization."""
+        # Use ObjectRef.to_dict() to ensure proper type normalization
         return {
-            "ref": {
-                "internalId": self.object_ref.internal_id,
-                "position": FindRequest._position_to_dict(self.object_ref.position),
-                "type": self.object_ref.type.value
-            },
+            "ref": self.object_ref.to_dict(),
             "newObject": AddRequest(None)._object_to_dict(self.new_object)
         }
 
@@ -565,12 +748,9 @@ class ModifyTextRequest:
 
     def to_dict(self) -> dict:
         """Convert to dictionary for JSON serialization."""
+        # Use ObjectRef.to_dict() to ensure proper type normalization
         return {
-            "ref": {
-                "internalId": self.object_ref.internal_id,
-                "position": FindRequest._position_to_dict(self.object_ref.position),
-                "type": self.object_ref.type.value
-            },
+            "ref": self.object_ref.to_dict(),
             "newTextLine": self.new_text
         }
 
@@ -582,12 +762,9 @@ class ChangeFormFieldRequest:
 
     def to_dict(self) -> dict:
         """Convert to dictionary for JSON serialization."""
+        # Use ObjectRef.to_dict() to ensure proper type normalization
         return {
-            "ref": {
-                "internalId": self.object_ref.internal_id,
-                "position": FindRequest._position_to_dict(self.object_ref.position),
-                "type": self.object_ref.type.value
-            },
+            "ref": self.object_ref.to_dict(),
             "value": self.value
         }
 
@@ -753,3 +930,42 @@ class CommandResult:
     @classmethod
     def empty(cls, command_name: str, element_id: str | None) -> 'CommandResult':
         return CommandResult(command_name=command_name, element_id=element_id, message=None, success=True, warning=None)
+
+
+@dataclass
+class PageSnapshot:
+    """
+    Snapshot of a single page containing all elements and page metadata.
+    """
+    page_ref: PageRef
+    elements: List[ObjectRef]
+
+    def get_page_ref(self) -> PageRef:
+        """Get the page reference."""
+        return self.page_ref
+
+    def get_elements(self) -> List[ObjectRef]:
+        """Get the list of elements on this page."""
+        return self.elements
+
+
+@dataclass
+class DocumentSnapshot:
+    """
+    Snapshot of the entire document containing all pages and font information.
+    """
+    page_count: int
+    fonts: List[FontRecommendation]
+    pages: List[PageSnapshot]
+
+    def get_page_count(self) -> int:
+        """Get the total number of pages."""
+        return self.page_count
+
+    def get_fonts(self) -> List[FontRecommendation]:
+        """Get the list of fonts used in the document."""
+        return self.fonts
+
+    def get_pages(self) -> List[PageSnapshot]:
+        """Get the list of page snapshots."""
+        return self.pages