codeocean 0.7.0__tar.gz → 0.9.0__tar.gz

{codeocean-0.7.0 → codeocean-0.9.0}/CHANGELOG.md

@@ -1,6 +1,14 @@
 CHANGELOG
 =========
 
+## 0.9.0 (2025-08-05)
+- [#47](https://github.com/codeocean/codeocean-sdk-python/pull/47) feat: add error handling
+
+
+## 0.8.0 (2025-07-11)
+- [#50](https://github.com/codeocean/codeocean-sdk-python/pull/50) feat: Add Min-Server-Version header support
+- [#49](https://github.com/codeocean/codeocean-sdk-python/pull/49) feat: Identify AI agents in API requests
+
 ## 0.7.0 (2025-06-24)
 - [#46](https://github.com/codeocean/codeocean-sdk-python/pull/46) feat: Add API documentation
 

{codeocean-0.7.0 → codeocean-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeocean
-Version: 0.7.0
+Version: 0.9.0
 Summary: Code Ocean Python SDK
 Project-URL: Homepage, https://github.com/codeocean/codeocean-sdk-python
 Project-URL: Issues, https://github.com/codeocean/codeocean-sdk-python/issues

{codeocean-0.7.0 → codeocean-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codeocean"
-version = "0.7.0"
+version = "0.9.0"
 authors = [
   { name="Code Ocean", email="dev@codeocean.com" },
 ]

{codeocean-0.7.0 → codeocean-0.9.0}/src/codeocean/__init__.py

@@ -1 +1,2 @@
 from codeocean.client import CodeOcean  # noqa: F401
+from codeocean.error import Error  # noqa: F401

codeocean-0.9.0/src/codeocean/client.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from requests_toolbelt.adapters.socket_options import TCPKeepAliveAdapter
+from requests_toolbelt.sessions import BaseUrlSession
+from typing import Optional
+from urllib3.util import Retry
+import requests
+
+from codeocean.capsule import Capsules
+from codeocean.computation import Computations
+from codeocean.data_asset import DataAssets
+from codeocean.error import Error
+
+
+@dataclass
+class CodeOcean:
+    """
+    Code Ocean API client.
+
+    This class provides a unified interface to access Code Ocean's API endpoints
+    for managing capsules, pipelines, computations, and data assets.
+
+    Fields:
+        domain: The Code Ocean domain URL (e.g., 'https://codeocean.acme.com')
+        token: Code Ocean API access token
+        retries: Optional retry configuration for failed HTTP requests. Can be an integer
+                (number of retries) or a urllib3.util.Retry object for advanced
+                retry configuration. Defaults to 0 (no retries)
+        agent_id: Optional agent identifier for tracking AI agent API usage on behalf of users
+    """
+
+    domain: str
+    token: str
+    retries: Optional[Retry | int] = 0
+    agent_id: Optional[str] = None
+
+    # Minimum server version required by this SDK
+    MIN_SERVER_VERSION = "3.6.0"
+
+    def __post_init__(self):
+        self.session = BaseUrlSession(base_url=f"{self.domain}/api/v1/")
+        self.session.auth = (self.token, "")
+        self.session.headers.update({
+            "Content-Type": "application/json",
+            "Min-Server-Version": CodeOcean.MIN_SERVER_VERSION,
+        })
+        if self.agent_id:
+            self.session.headers.update({"Agent-Id": self.agent_id})
+        self.session.hooks["response"] = [self._error_handler]
+        self.session.mount(self.domain, TCPKeepAliveAdapter(max_retries=self.retries))
+
+        self.capsules = Capsules(client=self.session)
+        self.computations = Computations(client=self.session)
+        self.data_assets = DataAssets(client=self.session)
+
+    def _error_handler(self, response, *args, **kwargs):
+        try:
+            response.raise_for_status()
+        except requests.HTTPError as err:
+            raise Error(err) from err

codeocean-0.9.0/src/codeocean/error.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import json
+import requests
+
+
+class Error(Exception):
+    """
+    Represents an HTTP error with additional context extracted from the response.
+
+    Attributes:
+        http_err (requests.HTTPError): The HTTP error object.
+        status_code (int): The HTTP status code of the error response.
+        message (str): A message describing the error, extracted from the response body.
+        data (Any): If the response body is json, this attribute contains the json object; otherwise, it is None.
+
+    Args:
+        err (requests.HTTPError): The HTTP error object.
+    """
+    def __init__(self, err: requests.HTTPError):
+        self.http_err = err
+        self.status_code = err.response.status_code
+        self.message = "An error occurred."
+        self.data = None
+
+        try:
+            self.data = err.response.json()
+            if isinstance(self.data, dict):
+                self.message = self.data.get("message", self.message)
+        except Exception:
+            # response wasn't JSON – fall back to text
+            self.message = err.response.text
+
+        super().__init__(self.message)
+
+    def __str__(self) -> str:
+        msg = str(self.http_err)
+        msg += f"\n\nMessage: {self.message}"
+        if self.data:
+            msg += "\n\nData:\n" + json.dumps(self.data, indent=2)
+        return msg

codeocean-0.9.0/tests/test_client.py

@@ -0,0 +1,83 @@
+import unittest
+from unittest.mock import patch
+from urllib3.util import Retry
+
+from codeocean.client import CodeOcean
+
+
+class TestClient(unittest.TestCase):
+    """Test cases for the CodeOcean client class."""
+
+    def setUp(self):
+        """Set up test fixtures."""
+        self.test_domain = "https://codeocean.acme.com"
+        self.test_token = "test_token_123"
+        self.test_agent_id = "test_agent_456"
+
+    def test_basic_init(self):
+        """Test a basic client initialization."""
+        client = CodeOcean(
+            domain=self.test_domain,
+            token=self.test_token,
+        )
+
+        # Verify base URL is set correctly
+        self.assertEqual(client.session.base_url, f"{self.test_domain}/api/v1/")
+
+        # Verify auth is correctly set
+        self.assertEqual(client.session.auth, (self.test_token, ""))
+
+        # Verify the session headers are correctly configured
+        headers = client.session.headers
+        self.assertIn("Content-Type", headers)
+        self.assertEqual(headers["Content-Type"], "application/json")
+        self.assertIn("Min-Server-Version", headers)
+        self.assertEqual(headers["Min-Server-Version"], CodeOcean.MIN_SERVER_VERSION)
+
+    @patch("codeocean.client.TCPKeepAliveAdapter")
+    def test_retry_configuration_types(self, mock_adapter):
+        """Test that both integer and Retry object work for retries parameter."""
+        # Test with integer
+        CodeOcean(
+            domain=self.test_domain,
+            token=self.test_token,
+            retries=5,
+        )
+
+        # Test with Retry object
+        retry_obj = Retry(total=3, backoff_factor=0.3)
+        CodeOcean(
+            domain=self.test_domain,
+            token=self.test_token,
+            retries=retry_obj,
+        )
+
+        # Assert both configurations work
+        self.assertEqual(mock_adapter.call_count, 2)
+        mock_adapter.assert_any_call(max_retries=5)
+        mock_adapter.assert_any_call(max_retries=retry_obj)
+
+    def test_agent_id_header_set_when_provided(self):
+        """Test that Agent-Id header is set when agent_id is provided."""
+        client = CodeOcean(
+            domain=self.test_domain,
+            token=self.test_token,
+            agent_id=self.test_agent_id,
+        )
+
+        # Verify the session headers are correctly configured
+        headers = client.session.headers
+        self.assertIn("Agent-Id", headers)
+        self.assertEqual(headers["Agent-Id"], self.test_agent_id)
+
+    def test_agent_id_header_not_set_when_none(self):
+        """Test that Agent-Id header is not set when agent_id is None."""
+        client = CodeOcean(
+            domain=self.test_domain,
+            token=self.test_token,
+            agent_id=None,
+        )
+
+        # Verify the session headers are correctly configured
+        headers = client.session.headers
+        self.assertNotIn("Agent-Id", headers)

codeocean-0.9.0/tests/test_error.py

@@ -0,0 +1,140 @@
+import unittest
+from unittest.mock import Mock
+import requests
+
+from codeocean.error import Error
+
+
+class TestError(unittest.TestCase):
+    """Test cases for the Error exception class."""
+
+    def test_error_is_exception_subclass(self):
+        """Test that Error is a subclass of Exception."""
+        self.assertTrue(issubclass(Error, Exception))
+
+    def test_error_with_json_dict(self):
+        """Test Error creation with JSON dict response containing message."""
+        # Create mock HTTPError and response
+        mock_response = Mock()
+        mock_response.status_code = 400
+        mock_response.json.return_value = {"message": "Custom error message", "datasets": [{"id": "123", "name": "tv"}]}
+
+        mock_http_error = Mock(spec=requests.HTTPError)
+        mock_http_error.response = mock_response
+
+        # Create Error instance
+        error = Error(mock_http_error)
+
+        # Verify attributes
+        self.assertEqual(error.status_code, 400)
+        self.assertEqual(error.message, "Custom error message")
+        self.assertEqual(error.data, {"message": "Custom error message", "datasets": [{"id": "123", "name": "tv"}]})
+
+    def test_error_with_json_dict_no_message(self):
+        """Test Error creation with JSON dict response without message field."""
+        # Create mock HTTPError and response
+        mock_response = Mock()
+        mock_response.status_code = 500
+        mock_response.json.return_value = {"error": "some other field"}
+
+        mock_http_error = Mock(spec=requests.HTTPError)
+        mock_http_error.response = mock_response
+
+        # Create Error instance
+        error = Error(mock_http_error)
+
+        # Verify attributes
+        self.assertEqual(error.status_code, 500)
+        self.assertEqual(error.message, "An error occurred.")
+        self.assertEqual(error.data, {"error": "some other field"})
+
+    def test_error_with_json_list(self):
+        """Test Error creation with JSON list response."""
+        # Create mock HTTPError and response
+        mock_response = Mock()
+        mock_response.status_code = 403
+        mock_response.json.return_value = [{"field": "error1"}, {"field": "error2"}]
+
+        mock_http_error = Mock(spec=requests.HTTPError)
+        mock_http_error.response = mock_response
+
+        # Create Error instance
+        error = Error(mock_http_error)
+
+        # Verify attributes
+        self.assertEqual(error.status_code, 403)
+        self.assertEqual(error.message, "An error occurred.")
+        self.assertEqual(error.data, [{"field": "error1"}, {"field": "error2"}])
+
+    def test_error_with_non_json_response(self):
+        """Test Error creation when response is not JSON."""
+        # Create mock HTTPError and response
+        mock_response = Mock()
+        mock_response.status_code = 404
+        mock_response.json.side_effect = Exception("Not JSON")
+        mock_response.text = "Page not found"
+
+        mock_http_error = Mock(spec=requests.HTTPError)
+        mock_http_error.response = mock_response
+
+        # Create Error instance
+        error = Error(mock_http_error)
+
+        # Verify attributes
+        self.assertEqual(error.status_code, 404)
+        self.assertEqual(error.message, "Page not found")
+        self.assertIsNone(error.data)
+
+    def test_error_str_method_with_data(self):
+        """Test Error __str__ method when data is present."""
+        # Create mock HTTPError and response
+        mock_response = Mock()
+        mock_response.status_code = 400
+        mock_response.json.return_value = {"message": "Validation failed", "errors": ["field1", "field2"]}
+
+        mock_http_error = Mock(spec=requests.HTTPError)
+        mock_http_error.response = mock_response
+        mock_http_error.__str__ = Mock(return_value="400 Client Error: Bad Request for url: http://example.com")
+
+        # Create Error instance
+        error = Error(mock_http_error)
+
+        # Test __str__ method
+        error_str = str(error)
+
+        # Verify the string contains expected components
+        self.assertEqual(error_str, """400 Client Error: Bad Request for url: http://example.com
+
+Message: Validation failed
+
+Data:
+{
+  "message": "Validation failed",
+  "errors": [
+    "field1",
+    "field2"
+  ]
+}""")
+
+    def test_error_str_method_without_data(self):
+        """Test Error __str__ method when data is None."""
+        # Create mock HTTPError and response
+        mock_response = Mock()
+        mock_response.status_code = 404
+        mock_response.json.side_effect = Exception("Not JSON")
+        mock_response.text = "Page not found"
+
+        mock_http_error = Mock(spec=requests.HTTPError)
+        mock_http_error.response = mock_response
+        mock_http_error.__str__ = Mock(return_value="404 Client Error: Not Found for url: http://example.com")
+
+        # Create Error instance
+        error = Error(mock_http_error)
+
+        # Test __str__ method
+        error_str = str(error)
+
+        # Verify the string contains expected components
+        self.assertEqual(error_str, """404 Client Error: Not Found for url: http://example.com
+
+Message: Page not found""")

codeocean-0.7.0/src/codeocean/client.py

@@ -1,32 +0,0 @@
-from __future__ import annotations
-
-from dataclasses import dataclass
-from requests_toolbelt.adapters.socket_options import TCPKeepAliveAdapter
-from requests_toolbelt.sessions import BaseUrlSession
-from typing import Optional
-from urllib3.util import Retry
-
-from codeocean.capsule import Capsules
-from codeocean.computation import Computations
-from codeocean.data_asset import DataAssets
-
-
-@dataclass
-class CodeOcean:
-
-    domain: str
-    token: str
-    retries: Optional[Retry | int] = 0
-
-    def __post_init__(self):
-        self.session = BaseUrlSession(base_url=f"{self.domain}/api/v1/")
-        self.session.auth = (self.token, "")
-        self.session.headers.update({"Content-Type": "application/json"})
-        self.session.hooks["response"] = [
-            lambda response, *args, **kwargs: response.raise_for_status()
-        ]
-        self.session.mount(self.domain, TCPKeepAliveAdapter(max_retries=self.retries))
-
-        self.capsules = Capsules(client=self.session)
-        self.computations = Computations(client=self.session)
-        self.data_assets = DataAssets(client=self.session)