codeocean 0.12.0__tar.gz → 0.14.0__tar.gz

{codeocean-0.12.0 → codeocean-0.14.0}/CHANGELOG.md

@@ -1,6 +1,14 @@
 CHANGELOG
 =========
 
+## 0.14.0 (2026-01-29)
+- [#66](https://github.com/codeocean/codeocean-sdk-python/pull/66) feat: Code Ocean version 4.2 functionality
+- **Minimum Code Ocean platform version updated to `4.2.0`.**  
+
+## 0.13.0 (2026-01-23)
+- [#64](https://github.com/codeocean/codeocean-sdk-python/pull/64) feat: Code Ocean version 4.1 functionality
+- **Minimum Code Ocean platform version updated to `4.1.0`.**  
+
 ## 0.12.0 (2025-10-20)
 - [#61](https://github.com/codeocean/codeocean-sdk-python/pull/61) feat: add search_pipelines method
 

{codeocean-0.12.0 → codeocean-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeocean
-Version: 0.12.0
+Version: 0.14.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.12.0 → codeocean-0.14.0}/RELEASE.md

@@ -3,6 +3,7 @@
 1. Open a PR with the following changes:
     1. Bump the version in [pyproject.toml](pyproject.toml).
     1. Update the [CHANGELOG.md](CHANGELOG.md).
+    1. If the change requires a newer Code Ocean server version, update `MIN_SERVER_VERSION` in [client.py](src/codeocean/client.py).
     1. Commit the updates with the message `Bump version to X.Y.Z`.
 1. Merge the PR.
 1. Locally, sync your clone with GitHub:

{codeocean-0.12.0 → codeocean-0.14.0}/examples/run_pipeline.py

@@ -1,16 +1,8 @@
 import os
 
 from codeocean import CodeOcean
-from codeocean.computation import RunParams
-from codeocean.data_asset import (
-    DataAssetParams,
-    DataAssetsRunParam,
-    PipelineProcessParams,
-    Source,
-    ComputationSource,
-    Target,
-    AWSS3Target,
-)
+from codeocean.computation import RunParams, DataAssetsRunParam, PipelineProcessParams
+from codeocean.data_asset import DataAssetParams, Source, ComputationSource, Target, AWSS3Target
 
 
 # Create the client using your domain and API token.
@@ -38,7 +30,7 @@ run_params = RunParams(
     ],
 )
 
-computation = client.computations.run_capsule(run_params)
+computation = client.computations.run_pipeline(run_params)
 
 # Wait for pipeline to finish.
 

{codeocean-0.12.0 → codeocean-0.14.0}/pyproject.toml

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

codeocean-0.14.0/src/codeocean/capsule.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from requests_toolbelt.sessions import BaseUrlSession
+from typing import Optional, Iterator
+
+from codeocean.models.capsule import (
+    Capsule,
+    CapsuleSearchParams,
+    CapsuleSearchResults,
+    AppPanel,
+)
+# Re-exports for backward compatibility
+from codeocean.models.capsule import (  # noqa: F401
+    CapsuleStatus,
+    CapsuleSortBy,
+    OriginalCapsuleInfo,
+    AppPanelDataAssetKind,
+    AppPanelParameterType,
+    AppPanelCategories,
+    AppPanelParameters,
+    AppPanelGeneral,
+    AppPanelDataAsset,
+    AppPanelResult,
+    AppPanelProcess,
+)
+from codeocean.models.components import Permissions
+from codeocean.models.computation import Computation
+from codeocean.models.data_asset import DataAssetAttachParams, DataAssetAttachResults
+
+
+@dataclass
+class Capsules:
+    """Client for interacting with Code Ocean capsule APIs."""
+
+    client: BaseUrlSession
+    _route: str = "capsules"
+
+    def get_capsule(self, capsule_id: str) -> Capsule:
+        """Retrieve metadata for a specific capsule by its ID."""
+        res = self.client.get(f"{self._route}/{capsule_id}")
+
+        return Capsule.from_dict(res.json())
+
+    def delete_capsule(self, capsule_id: str):
+        """Delete a capsule permanently."""
+        self.client.delete(f"{self._route}/{capsule_id}")
+
+    def get_capsule_app_panel(self, capsule_id: str, version: Optional[int] = None) -> AppPanel:
+        """Retrieve app panel information for a specific capsule by its ID."""
+        res = self.client.get(f"{self._route}/{capsule_id}/app_panel", params={"version": version} if version else None)
+
+        return AppPanel.from_dict(res.json())
+
+    def list_computations(self, capsule_id: str) -> list[Computation]:
+        """Get all computations associated with a specific capsule."""
+        res = self.client.get(f"{self._route}/{capsule_id}/computations")
+
+        return [Computation.from_dict(c) for c in res.json()]
+
+    def update_permissions(self, capsule_id: str, permissions: Permissions):
+        """Update permissions for a capsule."""
+        self.client.post(
+            f"{self._route}/{capsule_id}/permissions",
+            json=permissions.to_dict(),
+        )
+
+    def attach_data_assets(
+        self,
+        capsule_id: str,
+        attach_params: list[DataAssetAttachParams],
+    ) -> list[DataAssetAttachResults]:
+        """Attach one or more data assets to a capsule with optional mount paths."""
+        res = self.client.post(
+            f"{self._route}/{capsule_id}/data_assets",
+            json=[j.to_dict() for j in attach_params],
+        )
+
+        return [DataAssetAttachResults.from_dict(c) for c in res.json()]
+
+    def detach_data_assets(self, capsule_id: str, data_assets: list[str]):
+        """Detach one or more data assets from a capsule by their IDs."""
+        self.client.delete(
+            f"{self._route}/{capsule_id}/data_assets/",
+            json=data_assets,
+        )
+
+    def archive_capsule(self, capsule_id: str, archive: bool):
+        """Archive or unarchive a capsule to control its visibility and accessibility."""
+        self.client.patch(
+            f"{self._route}/{capsule_id}/archive",
+            params={"archive": archive},
+        )
+
+    def search_capsules(self, search_params: CapsuleSearchParams) -> CapsuleSearchResults:
+        """Search for capsules with filtering, sorting, and pagination
+        options."""
+        res = self.client.post(f"{self._route}/search", json=search_params.to_dict())
+
+        return CapsuleSearchResults.from_dict(res.json())
+
+    def search_capsules_iterator(self, search_params: CapsuleSearchParams) -> Iterator[Capsule]:
+        """Iterate through all capsules matching search criteria with automatic pagination."""
+        params = search_params.to_dict()
+        while True:
+            response = self.search_capsules(search_params=CapsuleSearchParams(**params))
+
+            for result in response.results:
+                yield result
+
+            if not response.has_more:
+                return
+
+            params["next_token"] = response.next_token

{codeocean-0.12.0 → codeocean-0.14.0}/src/codeocean/client.py

@@ -12,6 +12,7 @@ from codeocean.computation import Computations
 from codeocean.custom_metadata import CustomMetadataSchema
 from codeocean.data_asset import DataAssets
 from codeocean.error import Error
+from codeocean.pipeline import Pipelines
 
 
 @dataclass
@@ -37,7 +38,7 @@ class CodeOcean:
     agent_id: Optional[str] = None
 
     # Minimum server version required by this SDK
-    MIN_SERVER_VERSION = "4.0.0"
+    MIN_SERVER_VERSION = "4.2.0"
 
     def __post_init__(self):
         self.session = BaseUrlSession(base_url=f"{self.domain}/api/v1/")
@@ -55,6 +56,7 @@ class CodeOcean:
         self.computations = Computations(client=self.session)
         self.custom_metadata = CustomMetadataSchema(client=self.session)
         self.data_assets = DataAssets(client=self.session)
+        self.pipelines = Pipelines(client=self.session)
 
     def _error_handler(self, response, *args, **kwargs):
         try:

codeocean-0.14.0/src/codeocean/computation.py

@@ -0,0 +1,164 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from requests_toolbelt.sessions import BaseUrlSession
+from typing import Optional
+from time import sleep, time
+from warnings import warn
+
+from codeocean.models.computation import Computation, ComputationState, RunParams
+# Re-exports for backward compatibility
+from codeocean.models.computation import (  # noqa: F401
+    ComputationEndStatus,
+    Param,
+    PipelineProcess,
+    InputDataAsset,
+    DataAssetsRunParam,
+    NamedRunParam,
+    PipelineProcessParams,
+)
+from codeocean.models.data_asset import DataAssetAttachParams, DataAssetAttachResults
+from codeocean.models.folder import FileURLs, Folder, DownloadFileURL
+
+
+@dataclass
+class Computations:
+    """Client for interacting with Code Ocean computation APIs."""
+
+    client: BaseUrlSession
+
+    def get_computation(self, computation_id: str) -> Computation:
+        """Retrieve metadata and status information for a specific computation by its ID."""
+        res = self.client.get(f"computations/{computation_id}")
+
+        return Computation.from_dict(res.json())
+
+    def run_capsule(self, run_params: RunParams) -> Computation:
+        """
+        Execute a capsule or pipeline with specified parameters and data assets.
+
+        For capsule execution: Set run_params.capsule_id and optionally provide data_assets,
+        parameters, or named_parameters.
+
+        For pipeline execution: Set run_params.pipeline_id and optionally provide data_assets,
+        processes (with process-specific parameters), and nextflow_profile configuration.
+
+        """
+        res = self.client.post("computations", json=run_params.to_dict())
+
+        return Computation.from_dict(res.json())
+
+    # Alias for run_capsule
+    run_pipeline = run_capsule
+
+    def wait_until_completed(
+        self,
+        computation: Computation,
+        polling_interval: float = 5,
+        timeout: Optional[float] = None,
+    ) -> Computation:
+        """
+        Poll a computation until it reaches 'Completed' or 'Failed' state with configurable timing.
+
+        Args:
+            computation: The computation object to monitor
+            polling_interval: Time between status checks in seconds (minimum 5 seconds)
+            timeout: Maximum time to wait in seconds, or None for no timeout
+
+        Returns:
+            Updated computation object once completed or failed
+
+        Raises:
+            ValueError: If polling_interval < 5 or timeout constraints are violated
+            TimeoutError: If computation doesn't complete within the timeout period
+        """
+        if polling_interval < 5:
+            raise ValueError(
+                f"Polling interval {polling_interval} should be greater than or equal to 5"
+            )
+        if timeout is not None and timeout < polling_interval:
+            raise ValueError(
+                f"Timeout {timeout} should be greater than or equal to polling interval {polling_interval}"
+            )
+        if timeout is not None and timeout < 0:
+            raise ValueError(
+                f"Timeout {timeout} should be greater than or equal to 0 (seconds), or None"
+            )
+        t0 = time()
+        while True:
+            comp = self.get_computation(computation.id)
+
+            if comp.state in [ComputationState.Completed, ComputationState.Failed]:
+                return comp
+
+            if timeout is not None and (time() - t0) > timeout:
+                raise TimeoutError(
+                    f"Computation {computation.id} did not complete within {timeout} seconds"
+                )
+
+            sleep(polling_interval)
+
+    def attach_data_assets(
+        self,
+        computation_id: str,
+        attach_params: list[DataAssetAttachParams],
+    ) -> list[DataAssetAttachResults]:
+        """Attach one or more data assets to a cloud workstation session computation."""
+        res = self.client.post(
+            f"computations/{computation_id}/data_assets",
+            json=[j.to_dict() for j in attach_params],
+        )
+        return [DataAssetAttachResults.from_dict(c) for c in res.json()]
+
+    def detach_data_assets(self, computation_id: str, data_assets: list[str]):
+        """Detach one or more data assets from a cloud workstation session computation by their IDs."""
+        self.client.delete(
+            f"computations/{computation_id}/data_assets/",
+            json=data_assets,
+        )
+
+    def list_computation_results(self, computation_id: str, path: str = "") -> Folder:
+        """List result files and folders generated by a computation
+        at the specified path. Empty path retrieves the /results root folder."""
+        data = {
+            "path": path,
+        }
+
+        res = self.client.post(f"computations/{computation_id}/results", json=data)
+
+        return Folder.from_dict(res.json())
+
+    def get_result_file_download_url(self, computation_id: str, path: str) -> DownloadFileURL:
+        """[DEPRECATED] Generate a download URL for a specific result file from a computation.
+
+        Deprecated: Use get_result_file_urls instead.
+        """
+        warn(
+            "get_result_file_download_url is deprecated and will be removed in a future release. "
+            "Use get_result_file_urls instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        res = self.client.get(
+            f"computations/{computation_id}/results/download_url",
+            params={"path": path},
+        )
+
+        return DownloadFileURL.from_dict(res.json())
+
+    def get_result_file_urls(self, computation_id: str, path: str) -> FileURLs:
+        """Generate view and download URLs for a specific result file from a computation."""
+        res = self.client.get(
+            f"computations/{computation_id}/results/urls",
+            params={"path": path},
+        )
+
+        return FileURLs.from_dict(res.json())
+
+    def delete_computation(self, computation_id: str):
+        """Delete a computation and stop it if currently running."""
+        self.client.delete(f"computations/{computation_id}")
+
+    def rename_computation(self, computation_id: str, name: str):
+        """Rename an existing computation with a new display name."""
+        self.client.patch(f"computations/{computation_id}", params={"name": name})

codeocean-0.14.0/src/codeocean/data_asset.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from requests_toolbelt.sessions import BaseUrlSession
+from time import sleep, time
+from typing import Iterator
+from warnings import warn
+
+from codeocean.models.components import Permissions
+from codeocean.models.data_asset import (
+    DataAsset,
+    DataAssetState,
+    DataAssetUpdateParams,
+    DataAssetParams,
+    DataAssetSearchParams,
+    DataAssetSearchResults,
+    TransferDataParams,
+)
+# Re-exports for backward compatibility
+from codeocean.models.data_asset import (  # noqa: F401
+    DataAssetType,
+    DataAssetOrigin,
+    Provenance,
+    SourceBucket,
+    AppParameter,
+    ResultsInfo,
+    Source,
+    AWSS3Source,
+    GCPCloudStorageSource,
+    ComputationSource,
+    CloudWorkstationSource,
+    Target,
+    AWSS3Target,
+    DataAssetAttachParams,
+    DataAssetAttachResults,
+    DataAssetSortBy,
+    DataAssetSearchOrigin,
+    ContainedDataAsset,
+)
+from codeocean.models.folder import FileURLs, Folder, DownloadFileURL
+
+
+@dataclass
+class DataAssets:
+    """Client for interacting with Code Ocean data asset APIs."""
+
+    client: BaseUrlSession
+
+    def get_data_asset(self, data_asset_id: str) -> DataAsset:
+        """Retrieve metadata for a specific data asset by its ID."""
+        res = self.client.get(f"data_assets/{data_asset_id}")
+
+        return DataAsset.from_dict(res.json())
+
+    def update_metadata(self, data_asset_id: str, update_params: DataAssetUpdateParams) -> DataAsset:
+        """
+        Update metadata for a data asset including name, description, tags, mount,
+        and custom metadata.
+
+        Supports updating various metadata types:
+        - Basic metadata: name (display name), description (free text description)
+        - Organization: tags (keywords for searching), mount (default mount folder path)
+        - Custom metadata: admin-defined custom fields with user-set values according to
+            deployment configuration
+            (string, number, or date fields in unix epoch format)
+        """
+        res = self.client.put(
+            f"data_assets/{data_asset_id}",
+            json=update_params.to_dict(),
+        )
+
+        return DataAsset.from_dict(res.json())
+
+    def create_data_asset(self, data_asset_params: DataAssetParams) -> DataAsset:
+        """
+        Create a new data asset from various sources including S3 buckets,
+        computation results, or combined assets.
+
+        Data assets are versioned, immutable collections of files that serve as inputs
+        or outputs for computational workflows in Code Ocean. Internal data assets
+        store files within Code Ocean's infrastructure, while external data assets
+        reference files in external storage (S3/GCP) without copying.
+
+        Supports creating data assets from AWS S3, GCP Cloud Storage, computation
+        results, or combining existing data assets. Returns confirmation of creation
+        request validity, not success, as creation takes time. Use wait_until_ready()
+        to monitor creation progress.
+
+        """
+        res = self.client.post("data_assets", json=data_asset_params.to_dict())
+
+        return DataAsset.from_dict(res.json())
+
+    def wait_until_ready(
+        self,
+        data_asset: DataAsset,
+        polling_interval: float = 5,
+        timeout: float | None = None,
+    ) -> DataAsset:
+        """
+        Poll a data asset until it reaches 'Ready' or 'Failed' state with configurable
+        timing.
+
+        Args:
+            data_asset: The data asset object to monitor
+            polling_interval: Time between status checks in seconds
+                (minimum 5 seconds)
+            timeout: Maximum time to wait in seconds, or None for no timeout
+
+        Returns:
+            Updated data asset object once ready or failed
+
+        Raises:
+            ValueError: If polling_interval < 5 or timeout constraints are violated
+            TimeoutError: If data asset doesn't become ready within timeout period
+        """
+        if polling_interval < 5:
+            raise ValueError(
+                f"Polling interval {polling_interval} should be greater than or equal to 5"
+            )
+        if timeout is not None and timeout < polling_interval:
+            raise ValueError(
+                f"Timeout {timeout} should be greater than or equal to polling interval {polling_interval}"
+            )
+        if timeout is not None and timeout < 0:
+            raise ValueError(
+                f"Timeout {timeout} should be greater than or equal to 0 (seconds), or None"
+            )
+        t0 = time()
+        while True:
+            da = self.get_data_asset(data_asset.id)
+
+            if da.state in [DataAssetState.Ready, DataAssetState.Failed]:
+                return da
+
+            if timeout is not None and (time() - t0) > timeout:
+                raise TimeoutError(
+                    f"Data asset {data_asset.id} was not ready within {timeout} seconds"
+                )
+
+            sleep(polling_interval)
+
+    def delete_data_asset(self, data_asset_id: str):
+        """Delete a data asset permanently."""
+        self.client.delete(f"data_assets/{data_asset_id}")
+
+    def update_permissions(self, data_asset_id: str, permissions: Permissions):
+        """Update permissions for a data asset to control user and group access."""
+        self.client.post(
+            f"data_assets/{data_asset_id}/permissions",
+            json=permissions.to_dict(),
+        )
+
+    def archive_data_asset(self, data_asset_id: str, archive: bool):
+        """Archive or unarchive a data asset to control its visibility and accessibility."""
+        self.client.patch(
+            f"data_assets/{data_asset_id}/archive",
+            params={"archive": archive},
+        )
+
+    def search_data_assets(self, search_params: DataAssetSearchParams) -> DataAssetSearchResults:
+        """Search for data assets with filtering, sorting, and pagination options."""
+        res = self.client.post("data_assets/search", json=search_params.to_dict())
+
+        return DataAssetSearchResults.from_dict(res.json())
+
+    def search_data_assets_iterator(self, search_params: DataAssetSearchParams) -> Iterator[DataAsset]:
+        """
+        Iterate through all data assets matching search criteria with
+        automatic pagination.
+        """
+        params = search_params.to_dict()
+        while True:
+            response = self.search_data_assets(
+                search_params=DataAssetSearchParams(**params),
+            )
+
+            for result in response.results:
+                yield result
+
+            if not response.has_more:
+                return
+
+            params["next_token"] = response.next_token
+
+    def list_data_asset_files(self, data_asset_id: str, path: str = "") -> Folder:
+        """
+        List files and folders within an internal data asset at the specified path.
+        Empty path retrieves root level contents.
+        """
+        data = {
+            "path": path,
+        }
+
+        res = self.client.post(f"data_assets/{data_asset_id}/files", json=data)
+
+        return Folder.from_dict(res.json())
+
+    def get_data_asset_file_download_url(self, data_asset_id: str, path: str) -> DownloadFileURL:
+        """(Deprecated) Generate a download URL for a specific file from an internal data asset.
+
+        Deprecated: Use get_data_asset_file_urls instead.
+        """
+        warn(
+            "get_data_asset_file_download_url is deprecated and will be removed in a future release. "
+            "Use get_data_asset_file_urls instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        res = self.client.get(
+            f"data_assets/{data_asset_id}/files/download_url",
+            params={"path": path},
+        )
+
+        return DownloadFileURL.from_dict(res.json())
+
+    def get_data_asset_file_urls(self, data_asset_id: str, path: str) -> FileURLs:
+        """Generate view and download URLs for a specific file from an internal data asset."""
+        res = self.client.get(
+            f"data_assets/{data_asset_id}/files/urls",
+            params={"path": path},
+        )
+
+        return FileURLs.from_dict(res.json())
+
+    def transfer_data_asset(self, data_asset_id: str, transfer_params: TransferDataParams):
+        """
+        Transfer a data asset's files to a different S3 storage location (Admin only).
+
+        Can convert internal data assets to external or change storage location of
+        external data assets. Maintains provenance for result data assets. Use
+        force=True when transferring data assets used by release pipelines.
+        """
+        self.client.post(
+            f"data_assets/{data_asset_id}/transfer",
+            json=transfer_params.to_dict(),
+        )

codeocean-0.14.0/src/codeocean/models/__init__.py

@@ -0,0 +1 @@
+"""Models for Code Ocean SDK."""