pdfdancer-client-python 0.2.2__py3-none-any.whl → 0.2.4__py3-none-any.whl

pdfdancer/pdfdancer_v1.py

@@ -6,6 +6,7 @@ Provides session-based PDF manipulation operations with strict validation.
 """
 
 import json
+import os
 from pathlib import Path
 from typing import List, Optional, Union, BinaryIO
 
@@ -116,11 +117,39 @@ class PDFDancer:
     @classmethod
     def open(cls,
              pdf_data: Union[bytes, Path, str, BinaryIO],
-             token: str,
-             base_url: str = "http://localhost:8080",
+             token: Optional[str] = None,
+             base_url: Optional[str] = None,
              timeout: float = 30.0) -> "PDFDancer":
+        """
+        Create a client session, falling back to environment variables when needed.
+
+        Args:
+            pdf_data: PDF payload supplied directly or via filesystem handles.
+            token: Override for the API token; falls back to `PDFDANCER_TOKEN` environement variable.
+            base_url: Override for the API base URL; falls back to `PDFDANCER_BASE_URL`
+                or defaults to `https://api.pdfdancer.com`.
+            timeout: HTTP read timeout in seconds.
+
+        Returns:
+            A ready-to-use `PDFDancer` client instance.
+        """
+        resolved_token = token.strip() if token and token.strip() else None
+        if resolved_token is None:
+            env_token = os.getenv("PDFDANCER_TOKEN")
+            resolved_token = env_token.strip() if env_token and env_token.strip() else None
+
+        if resolved_token is None:
+            raise ValidationException(
+                "Missing PDFDancer API token. Pass a token via the `token` argument "
+                "or set the PDFDANCER_TOKEN environment variable."
+            )
+
+        env_base_url = os.getenv("PDFDANCER_BASE_URL")
+        resolved_base_url = base_url or (env_base_url.strip() if env_base_url and env_base_url.strip() else None)
+        if resolved_base_url is None:
+            resolved_base_url = "https://api.pdfdancer.com"
 
-        return PDFDancer(token, pdf_data, base_url, timeout)
+        return PDFDancer(resolved_token, pdf_data, resolved_base_url, timeout)
 
     def __init__(self, token: str, pdf_data: Union[bytes, Path, str, BinaryIO],
                  base_url: str, read_timeout: float = 0):
@@ -236,6 +265,22 @@ class PDFDancer:
             # If JSON parsing fails, return response content or status
             return response.text or f"HTTP {response.status_code}"
 
+    def _handle_authentication_error(self, response: Optional[requests.Response]) -> None:
+        """
+        Translate authentication failures into a clear, actionable validation error.
+        """
+        if response is None:
+            return
+
+        if response.status_code in (401, 403):
+            details = self._extract_error_message(response)
+            raise ValidationException(
+                "Authentication with the PDFDancer API failed. "
+                "Confirm that your API token is valid, has not expired, and is supplied via "
+                "the `token` argument or the PDFDANCER_TOKEN environment variable. "
+                f"Server response: {details}"
+            )
+
     def _create_session(self) -> str:
         """
         Creates a new PDF processing session by uploading the PDF data.
@@ -251,6 +296,7 @@ class PDFDancer:
                 timeout=self._read_timeout if self._read_timeout > 0 else None
             )
 
+            self._handle_authentication_error(response)
             response.raise_for_status()
             session_id = response.text.strip()
 
@@ -260,6 +306,7 @@ class PDFDancer:
             return session_id
 
         except requests.exceptions.RequestException as e:
+            self._handle_authentication_error(getattr(e, 'response', None))
             error_message = self._extract_error_message(getattr(e, 'response', None))
             raise HttpClientException(f"Failed to create session: {error_message}",
                                       response=getattr(e, 'response', None), cause=e) from None
@@ -293,10 +340,12 @@ class PDFDancer:
                 except (json.JSONDecodeError, KeyError):
                     pass
 
+            self._handle_authentication_error(response)
             response.raise_for_status()
             return response
 
         except requests.exceptions.RequestException as e:
+            self._handle_authentication_error(getattr(e, 'response', None))
             error_message = self._extract_error_message(getattr(e, 'response', None))
             raise HttpClientException(f"API request failed: {error_message}", response=getattr(e, 'response', None),
                                       cause=e) from None
@@ -811,7 +860,7 @@ class PDFDancer:
 
     # Builder Pattern Support
 
-    def paragraph_builder(self) -> 'ParagraphBuilder':
+    def _paragraph_builder(self) -> 'ParagraphBuilder':
         """
         Creates a new ParagraphBuilder for fluent paragraph construction.
         Returns:

{pdfdancer_client_python-0.2.2.dist-info → pdfdancer_client_python-0.2.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pdfdancer-client-python
-Version: 0.2.2
+Version: 0.2.4
 Summary: Python client for PDFDancer API
 Author-email: "The Famous Cat Ltd." <hi@thefamouscat.com>
 License: MIT
@@ -63,7 +63,7 @@ client._delete(paragraphs[0])
 client._move(images[0], Position.at_page_coordinates(0, 100, 200))
 
 # Builder pattern (mirrors Java ParagraphBuilder)
-paragraph = (client.paragraph_builder()
+paragraph = (client._paragraph_builder()
              .from_string("Hello World")
              .with_font(Font("Arial", 12))
              .with_color(Color(255, 0, 0))
@@ -141,25 +141,26 @@ result = client.modify_text_line(ref, "new text")
 ```
 
 ### Builder Pattern
+
 ```python
 # Java: client.paragraphBuilder()
-builder = client.paragraph_builder()
+builder = client._paragraph_builder()
 
 # Fluent interface (mirrors Java ParagraphBuilder)
 paragraph = (builder
-    .from_string("Text content")           # Java: fromString()
-    .with_font(Font("Arial", 12))          # Java: withFont()
-    .with_color(Color(255, 0, 0))          # Java: withColor()
-    .with_line_spacing(1.5)                # Java: withLineSpacing()
-    .with_position(position)               # Java: withPosition()
-    .build())                              # Java: build()
+             .from_string("Text content")  # Java: fromString()
+             .with_font(Font("Arial", 12))  # Java: withFont()
+             .with_color(Color(255, 0, 0))  # Java: withColor()
+             .with_line_spacing(1.5)  # Java: withLineSpacing()
+             .with_position(position)  # Java: withPosition()
+             .build())  # Java: build()
 
 # Font file registration (Java: withFont(File, double))
 paragraph = (builder
-    .with_font_file("custom.ttf", 14.0)    # Java: withFont(File, double)
-    .from_string("Custom font text")
-    .with_position(position)
-    .build())
+             .with_font_file("custom.ttf", 14.0)  # Java: withFont(File, double)
+             .from_string("Custom font text")
+             .with_position(position)
+             .build())
 ```
 
 ### Position API

{pdfdancer_client_python-0.2.2.dist-info → pdfdancer_client_python-0.2.4.dist-info}/RECORD

@@ -3,9 +3,9 @@ pdfdancer/exceptions.py,sha256=Y5zwNVZprsv2hvKX304cXWobJt11nrEhCzLklu2wiO8,1567
 pdfdancer/image_builder.py,sha256=Omxc2LcieJ1MbvWBXR5_sfia--eAucTUe0KWgr22HYo,842
 pdfdancer/models.py,sha256=SmkKScr47uVs6FCWUAVIg6rucYrYHvbIxZngyA50XyI,15498
 pdfdancer/paragraph_builder.py,sha256=bAfwX9U2YT1UGX9EKkPnGYvGK3SQP3X1ocxlgyLE_rU,8872
-pdfdancer/pdfdancer_v1.py,sha256=Jsr1ZnqUoeNd3So-9ZhygDdwXSCN-m3G_9HUZ3cU_Cc,33196
+pdfdancer/pdfdancer_v1.py,sha256=Pgv-2L0pYQdOUVK2nUntrGB6hCDKUOMWHYuN8loBM3Q,35540
 pdfdancer/types.py,sha256=lcYnqCFgnrGpplSPCxKh3X9AZ3-9t-lJqMH5ZLew_I4,8188
-pdfdancer_client_python-0.2.2.dist-info/METADATA,sha256=5XM20sBrcRra-BCRaJZL1L4bKgVzvmdOjdM1CmkwSCw,9242
-pdfdancer_client_python-0.2.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pdfdancer_client_python-0.2.2.dist-info/top_level.txt,sha256=ICwSVRpcCKrdBF9QlaX9Y0e_N3Nk1p7QVxadGOnbxeY,10
-pdfdancer_client_python-0.2.2.dist-info/RECORD,,
+pdfdancer_client_python-0.2.4.dist-info/METADATA,sha256=a-sAoRCXslorLigW0Vxbmhqzg5krpQ3b9WpHyi_8FM8,9253
+pdfdancer_client_python-0.2.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pdfdancer_client_python-0.2.4.dist-info/top_level.txt,sha256=ICwSVRpcCKrdBF9QlaX9Y0e_N3Nk1p7QVxadGOnbxeY,10
+pdfdancer_client_python-0.2.4.dist-info/RECORD,,