Add python-dotenv dependency and refine retry/pending logic

- Add python-dotenv to both PDM and uv dev dependencies so
  tests/client_test.py can run standalone without ModuleNotFoundError
- Fix pre-commit default Python version from python3.9 to python3
- Refine structure_file pending detection: only set pending=True on
  2xx responses (POST 422 indicates setup errors, not queued work)
- Fix trailing newlines in utils.py and sample.env
- Update tests to match new 422 pending behavior and fix docstring
  formatting

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: muhammad-ali-e

.pre-commit-config.yaml

@@ -4,7 +4,7 @@
 # - Added pkgs feature flag auto generated code to flake8 exclude list
 # Force all unspecified python hooks to run python 3.10
 default_language_version:
-  python: python3.9
+  python: python3
 default_stages:
   - commit
 repos:

pyproject.toml

@@ -31,6 +31,7 @@ test = [
     "pytest-dotenv>=0.5.2",
     "pytest-cov>=5.0.0",
     "pytest-md-report>=0.6.2",
+    "python-dotenv>=1.0.0",
 ]
 lint = [
     "autopep8~=2.0.2",
@@ -78,3 +79,8 @@ test.help = "Runs pytests for Unstract client"
 [build-system]
 requires = ["pdm-backend"]
 build-backend = "pdm.backend"
+
+[dependency-groups]
+dev = [
+    "python-dotenv>=1.0.0",
+]

src/unstract/api_deployments/client.py

@@ -357,15 +357,19 @@ def structure_file(self, file_paths: list[str]) -> dict:
         }
 
         # Check if the status is pending or if it's successful but lacks a result.
-        # Per the Unstract Status API migration guide (Option 1), we determine
-        # pending state from the response body alone, ignoring the HTTP status
-        # code — the server currently returns 422 for PENDING/EXECUTING.
-        if execution_status in self.in_progress_statuses or (
-            execution_status == "SUCCESS" and not extraction_result
-        ):
-            obj_to_return.update(
-                {"status_check_api_endpoint": status_api_endpoint, "pending": True}
-            )
+        # The POST endpoint returns 200 for successful queuing (including
+        # PENDING/EXECUTING) and 422 only on setup errors — guard against
+        # incorrectly polling after an error response.
+        if 200 <= response.status_code < 300:
+            if execution_status in self.in_progress_statuses or (
+                execution_status == "SUCCESS" and not extraction_result
+            ):
+                obj_to_return.update(
+                    {
+                        "status_check_api_endpoint": status_api_endpoint,
+                        "pending": True,
+                    }
+                )
 
         return obj_to_return
 

src/unstract/api_deployments/utils.py

@@ -19,4 +19,4 @@ def redact_key(api_key: str, reveal_length=4) -> str:
         redacted_length = max(len(api_key) - reveal_length, 0)
         revealed_part = api_key[:reveal_length]
         redacted_part = "x" * redacted_length
-        return revealed_part + redacted_part
+        return revealed_part + redacted_part

tests/sample.env

@@ -1,3 +1,3 @@
 API_URL="http://localhost:8000/deployment/api/<org_id>/<api_name>/"
 UNSTRACT_API_DEPLOYMENT_KEY="your-api-key-without-bearer-prefix"
-TEST_FILES="/path/to/test1.pdf,/path/to/test2.pdf"
+TEST_FILES="/path/to/test1.pdf,/path/to/test2.pdf"

tests/test_retry.py

@@ -331,7 +331,9 @@ class TestTimeoutPassed:
     @patch("unstract.api_deployments.client.requests.request")
     def test_no_default_timeout_set(self, mock_request, client):
         """api_timeout is a server-side parameter, not an HTTP socket timeout.
-        _request_with_retry should NOT inject a default timeout kwarg."""
+
+        _request_with_retry should NOT inject a default timeout kwarg.
+        """
         mock_request.return_value = _mock_response(200)
         client._request_with_retry("GET", "https://api.example.com/test")
         _, kwargs = mock_request.call_args
@@ -476,7 +478,8 @@ def test_422_with_executing_status_sets_pending_true(self, mock_request, client)
 
     @patch("unstract.api_deployments.client.requests.request")
     def test_422_with_pending_status_sets_pending_true(self, mock_request, client):
-        """HTTP 422 with PENDING body status — still detected via body check."""
+        """HTTP 422 with PENDING body status — still detected via body
+        check."""
         mock_request.return_value = _mock_response(
             422, json_data={"status": "PENDING", "error": "", "message": ""}
         )
@@ -591,12 +594,20 @@ def test_structure_file_sync_mode_default_timeout(self, mock_post, tmp_path):
         assert mock_post.call_count == 1
 
 
-# ── structure_file: 422 + PENDING sets pending=True ──
+# ── structure_file: POST 422 does NOT set pending ──
+# The POST endpoint returns 200 for successful queuing (PENDING/EXECUTING)
+# and 422 only on setup errors. A 422 should never trigger polling.
 
 
-class TestStructureFilePendingOn422:
+class TestStructureFile422DoesNotSetPending:
     @patch("unstract.api_deployments.client.requests.post")
-    def test_422_pending_sets_pending_true(self, mock_post, tmp_path):
+    def test_422_pending_does_not_set_pending(self, mock_post, tmp_path):
+        """POST 422 with PENDING status should NOT set pending=True.
+
+        The POST endpoint returns 422 only on setup errors, so the
+        client must not start polling even if execution_status says
+        PENDING.
+        """
         test_file = tmp_path / "test.pdf"
         test_file.write_bytes(b"fake pdf content")
 
@@ -618,12 +629,16 @@ def test_422_pending_sets_pending_true(self, mock_post, tmp_path):
             },
         )
         result = c.structure_file([str(test_file)])
-        assert result["pending"] is True
-        assert result["status_check_api_endpoint"] == "/api/status/abc"
+        assert result["pending"] is False
         assert result["status_code"] == 422
 
     @patch("unstract.api_deployments.client.requests.post")
-    def test_422_executing_sets_pending_true(self, mock_post, tmp_path):
+    def test_422_executing_does_not_set_pending(self, mock_post, tmp_path):
+        """POST 422 with EXECUTING status should NOT set pending=True.
+
+        Same rationale as above — 422 from POST means a setup error, not
+        a legitimately queued execution.
+        """
         test_file = tmp_path / "test.pdf"
         test_file.write_bytes(b"fake pdf content")
 
@@ -645,12 +660,12 @@ def test_422_executing_sets_pending_true(self, mock_post, tmp_path):
             },
         )
         result = c.structure_file([str(test_file)])
-        assert result["pending"] is True
+        assert result["pending"] is False
         assert result["status_code"] == 422
 
     @patch("unstract.api_deployments.client.requests.post")
-    def test_200_pending_still_works(self, mock_post, tmp_path):
-        """Existing behaviour: 200 + PENDING also sets pending=True."""
+    def test_200_pending_sets_pending_true(self, mock_post, tmp_path):
+        """POST 200 + PENDING correctly sets pending=True for polling."""
         test_file = tmp_path / "test.pdf"
         test_file.write_bytes(b"fake pdf content")