codeocean 0.6.0__tar.gz → 0.7.0__tar.gz

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

@@ -1,6 +1,9 @@
 CHANGELOG
 =========
 
+## 0.7.0 (2025-06-24)
+- [#46](https://github.com/codeocean/codeocean-sdk-python/pull/46) feat: Add API documentation
+
 ## 0.6.0 (2025-06-03)
 - [#44](https://github.com/codeocean/codeocean-sdk-python/pull/44) feat: support for nextflow_profiles in data assets and computations
 - [#43](https://github.com/codeocean/codeocean-sdk-python/pull/43) fix: updates .gitignore to exclude .env

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeocean
-Version: 0.6.0
+Version: 0.7.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.6.0 → codeocean-0.7.0}/pyproject.toml

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

codeocean-0.7.0/src/codeocean/capsule.py

@@ -0,0 +1,281 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field as dataclass_field
+from dataclasses_json import dataclass_json
+from typing import Optional, Iterator
+from requests_toolbelt.sessions import BaseUrlSession
+
+from codeocean.components import Ownership, SortOrder, SearchFilter, Permissions
+from codeocean.computation import Computation
+from codeocean.data_asset import DataAssetAttachParams, DataAssetAttachResults
+from codeocean.enum import StrEnum
+
+
+class CapsuleStatus(StrEnum):
+    """Status of a capsule indicating its release state."""
+
+    NonRelease = "non_release"
+    Release = "release"
+
+
+class CapsuleSortBy(StrEnum):
+    """Fields available for sorting capsule search results."""
+
+    Created = "created"
+    LastAccessed = "last_accessed"
+    Name = "name"
+
+
+@dataclass_json
+@dataclass(frozen=True)
+class OriginalCapsuleInfo:
+    """Information about the original capsule when this capsule is duplicated from
+    another."""
+
+    id: Optional[str] = dataclass_field(
+        default=None,
+        metadata={"description": "Original capsule ID"},
+    )
+    major_version: Optional[int] = dataclass_field(
+        default=None,
+        metadata={"description": "Original capsule major version"},
+    )
+    minor_version: Optional[int] = dataclass_field(
+        default=None,
+        metadata={"description": "Original capsule minor version"},
+    )
+    name: Optional[str] = dataclass_field(
+        default=None,
+        metadata={"description": "Original capsule name"},
+    )
+    created: Optional[int] = dataclass_field(
+        default=None,
+        metadata={"description": "Original capsule creation time (int64 timestamp)"},
+    )
+    public: Optional[bool] = dataclass_field(
+        default=None,
+        metadata={"description": "Indicates whether the original capsule is public"},
+    )
+
+
+@dataclass_json
+@dataclass(frozen=True)
+class Capsule:
+    """Represents a Code Ocean capsule with its metadata and properties."""
+
+    id: str = dataclass_field(
+        metadata={"description": "Capsule ID"},
+    )
+    created: int = dataclass_field(
+        metadata={"description": "Capsule creation time (int64 timestamp)"},
+    )
+    name: str = dataclass_field(
+        metadata={"description": "Capsule display name"},
+    )
+    status: CapsuleStatus = dataclass_field(
+        metadata={"description": "Status of the capsule (non_release or release)"},
+    )
+    owner: str = dataclass_field(
+        metadata={"description": "Capsule owner's ID"},
+    )
+    slug: str = dataclass_field(
+        metadata={"description": "Alternate capsule ID (URL-friendly identifier)"},
+    )
+    article: Optional[dict] = dataclass_field(
+        default=None,
+        metadata={
+            "description": "Capsule article info with URL, ID, DOI, "
+            "citation, state, name, journal_name, and "
+            "publish_time"
+        },
+    )
+    cloned_from_url: Optional[str] = dataclass_field(
+        default=None,
+        metadata={"description": "URL to external Git repository linked to capsule"},
+    )
+    description: Optional[str] = dataclass_field(
+        default=None,
+        metadata={"description": "Capsule description"},
+    )
+    field: Optional[str] = dataclass_field(
+        default=None,
+        metadata={"description": "Capsule research field"},
+    )
+    tags: Optional[list[str]] = dataclass_field(
+        default=None,
+        metadata={"description": "List of tags associated with the capsule"},
+    )
+    original_capsule: Optional[OriginalCapsuleInfo] = dataclass_field(
+        default=None,
+        metadata={
+            "description": "Original capsule info when this capsule is duplicated from another"
+        },
+    )
+    release_capsule: Optional[str] = dataclass_field(
+        default=None,
+        metadata={"description": "Release capsule ID"},
+    )
+    submission: Optional[dict] = dataclass_field(
+        default=None,
+        metadata={
+            "description": "Submission info with timestamp, commit hash, "
+            "verification_capsule, verified status, and "
+            "verified_timestamp"
+        },
+    )
+    versions: Optional[list[dict]] = dataclass_field(
+        default=None,
+        metadata={
+            "description": "Capsule versions with major_version, minor_version, release_time, and DOI"
+        },
+    )
+
+
+@dataclass_json
+@dataclass(frozen=True)
+class CapsuleSearchParams:
+    """Parameters for searching capsules with various filters and pagination
+    options."""
+
+    query: Optional[str] = dataclass_field(
+        default=None,
+        metadata={
+            "description": "Search query in free text or structured format (name:... tag:...)"
+        },
+    )
+    next_token: Optional[str] = dataclass_field(
+        default=None,
+        metadata={
+            "description": "Token for next page of results from previous response"
+        },
+    )
+    offset: Optional[int] = dataclass_field(
+        default=None,
+        metadata={
+            "description": "Starting index for search results (ignored if next_token is set)"
+        },
+    )
+    limit: Optional[int] = dataclass_field(
+        default=None,
+        metadata={
+            "description": "Number of items to return (up to 1000, defaults to 100)"
+        },
+    )
+    sort_field: Optional[CapsuleSortBy] = dataclass_field(
+        default=None,
+        metadata={"description": "Field to sort by (created, name, or last_accessed)"},
+    )
+    sort_order: Optional[SortOrder] = dataclass_field(
+        default=None,
+        metadata={
+            "description": "Sort order ('asc' or 'desc') - must be provided with a sort_field parameter as well!"
+        },
+    )
+    ownership: Optional[Ownership] = dataclass_field(
+        default=None,
+        metadata={
+            "description": "Filter by ownership ('private', 'created' or 'shared') - defaults to all accessible"
+        },
+    )
+    status: Optional[CapsuleStatus] = dataclass_field(
+        default=None,
+        metadata={"description": "Filter by status (release or non_release) - defaults to all"},
+    )
+    favorite: Optional[bool] = dataclass_field(
+        default=None,
+        metadata={"description": "Search only favorite capsules"},
+    )
+    archived: Optional[bool] = dataclass_field(
+        default=None,
+        metadata={"description": "Search only archived capsules"},
+    )
+    filters: Optional[list[SearchFilter]] = dataclass_field(
+        default=None,
+        metadata={
+            "description": "Additional field-level filters for name, description, tags, or custom fields"
+        },
+    )
+
+
+@dataclass_json
+@dataclass(frozen=True)
+class CapsuleSearchResults:
+    """Results from a capsule search operation with pagination support."""
+
+    has_more: bool = dataclass_field(
+        metadata={"description": "Indicates if there are more results available"},
+    )
+    results: list[Capsule] = dataclass_field(
+        metadata={"description": "Array of capsules found matching the search criteria"},
+    )
+    next_token: Optional[str] = dataclass_field(
+        default=None,
+        metadata={"description": "Token for fetching the next page of results"},
+    )
+
+
+@dataclass
+class Capsules:
+    """Client for interacting with Code Ocean capsule APIs."""
+
+    client: BaseUrlSession
+
+    def get_capsule(self, capsule_id: str) -> Capsule:
+        """Retrieve metadata for a specific capsule by its ID."""
+        res = self.client.get(f"capsules/{capsule_id}")
+
+        return Capsule.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"capsules/{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"capsules/{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"capsules/{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"capsules/{capsule_id}/data_assets/",
+            json=data_assets,
+        )
+
+    def search_capsules(self, search_params: CapsuleSearchParams) -> CapsuleSearchResults:
+        """Search for capsules with filtering, sorting, and pagination
+        options."""
+        res = self.client.post("capsules/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.7.0/src/codeocean/components.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+from dataclasses_json import dataclass_json
+from dataclasses import dataclass, field
+from typing import Optional
+
+from codeocean.enum import StrEnum
+
+
+class UserRole(StrEnum):
+    """Role levels for user permissions of Code Ocean resources."""
+
+    Owner = "owner"
+    Editor = "editor"
+    Viewer = "viewer"
+
+
+@dataclass_json
+@dataclass(frozen=True)
+class UserPermissions:
+    """User permission configuration with email and role assignment."""
+
+    email: str = field(
+        metadata={"description": "User email address for permission assignment"},
+    )
+    role: UserRole = field(
+        metadata={
+            "description": "Permission level granted to the user (owner, editor, or viewer)",
+        },
+    )
+
+
+class GroupRole(StrEnum):
+    """Role levels for group permissions of Code Ocean resources."""
+
+    Owner = "owner"
+    Editor = "editor"
+    Viewer = "viewer"
+    Discoverable = "discoverable"
+
+
+@dataclass_json
+@dataclass(frozen=True)
+class GroupPermissions:
+    """Group permission configuration with group identifier and role assignment."""
+
+    group: str = field(
+        metadata={"description": "Group identifier for permission assignment"},
+    )
+    role: GroupRole = field(
+        metadata={
+            "description": "Permission level granted to the group (owner, editor, viewer, or discoverable)",
+        },
+    )
+
+
+class EveryoneRole(StrEnum):
+    """Role levels for public access permissions of Code Ocean resources."""
+
+    Viewer = "viewer"
+    Discoverable = "discoverable"
+    None_ = "none"
+
+
+@dataclass_json
+@dataclass(frozen=True)
+class Permissions:
+    """Complete permission configuration for Code Ocean resources including users, groups, and public access."""
+
+    users: Optional[list[UserPermissions]] = field(
+        default=None,
+        metadata={"description": "List of user-specific permissions"},
+    )
+    groups: Optional[list[GroupPermissions]] = field(
+        default=None,
+        metadata={"description": "List of group-specific permissions"},
+    )
+    everyone: Optional[EveryoneRole] = field(
+        default=None,
+        metadata={"description": "Public access level (viewer, discoverable, or none)"},
+    )
+    share_assets: Optional[bool] = field(
+        default=None,
+        metadata={
+            "description": "Whether to share all related assets (attached data assets and "
+            "pipeline capsules) with added users and groups",
+        },
+    )
+
+
+class SortOrder(StrEnum):
+    """Sort order options for search operations."""
+
+    Ascending = "asc"
+    Descending = "desc"
+
+
+@dataclass_json
+@dataclass(frozen=True)
+class SearchFilterRange:
+    """Numeric range filter for search operations with minimum and maximum values."""
+
+    min: float = field(
+        metadata={"description": "Minimum value for range filter"},
+    )
+    max: float = field(
+        metadata={"description": "Maximum value for range filter"},
+    )
+
+
+@dataclass_json
+@dataclass(frozen=True)
+class SearchFilter:
+    """Search filter configuration for field-level filtering with various value types and range support."""
+
+    key: str = field(
+        metadata={
+            "description": "Field name to filter on (name, description, tags, or custom field key)",
+        },
+    )
+    value: Optional[str | float] = field(
+        default=None,
+        metadata={"description": "Single field value to include/exclude"},
+    )
+    values: Optional[list[str | float]] = field(
+        default=None,
+        metadata={"description": "Multiple field values for inclusion/exclusion"},
+    )
+    range: Optional[SearchFilterRange] = field(
+        default=None,
+        metadata={
+            "description": "Numeric range filter (only one of min/max must be set)",
+        },
+    )
+    exclude: Optional[bool] = field(
+        default=None,
+        metadata={
+            "description": "Whether to include (false) or exclude (true) the specified values",
+        },
+    )
+
+
+class Ownership(StrEnum):
+    """Ownership filter options for search operations."""
+
+    Private = "private"
+    Shared = "shared"
+    Created = "created"