GitHub Repository: sagemathinc/cocalc
Path: blob/master/src/python/cocalc-api/README.md
⁵⁵⁴⁶ views

CoCalc Python API Client

This is a Python package that provides an API client for CoCalc, enabling programmatic access to CoCalc's features including project management, Jupyter execution, file operations, messaging, and organization management.

Installation

pip install cocalc-api

Quick Start

import cocalc_api

# Initialize hub client with your API key
hub = cocalc_api.Hub(api_key="your-api-key")

# Ping the server
response = hub.system.ping()
print(f"Server time: {response['now']}")

# List your projects
projects = hub.projects.get()
for project in projects:
    print(f"Project: {project['title']} ({project['project_id']})")

Features

Hub Client (Account-Level Operations)

The Hub class provides access to account-level operations:

System: Server ping, user search, account name resolution
Projects: Project management (create, start, stop, add/remove collaborators)
Jupyter: Execute code using Jupyter kernels in any project or anonymously
Database: Direct PostgreSQL database queries for advanced operations
Messages: Send and receive messages between users
Organizations: Manage organizations, users, and temporary access tokens
Sync: Access file edit history and synchronization features

Project Client (Project-Specific Operations)

The Project class provides project-specific operations:

System: Execute shell commands and Jupyter code within a specific project

MCP Server

The CoCalc API includes a Model Context Protocol (MCP) server that allows LLMs (like Claude) to interact with CoCalc projects through a standardized protocol.

For detailed setup instructions and usage guide, see src/cocalc_api/mcp/README.md.

Authentication

The client supports two types of API keys:

Account API Keys: Provide full access to all hub functionality
Project API Keys: Limited to project-specific operations

Get your API key from CoCalc Account Settings under "API Keys".

Architecture

Package Structure

src/cocalc_api/
├── __init__.py          # Package exports (Hub, Project classes)
├── hub.py              # Hub client for account-level operations
├── project.py          # Project client for project-specific operations
├── api_types.py        # TypedDict definitions for API responses
└── util.py             # Utility functions and decorators

Design Patterns

Decorator-based Methods: Uses @api_method() decorator to automatically convert method calls to API requests
TypedDict Responses: All API responses use TypedDict for type safety
Error Handling: Centralized error handling via handle_error() utility
HTTP Client: Uses httpx for HTTP requests with authentication
Nested Namespaces: API organized into logical namespaces (system, projects, jupyter, etc.)

Development

Requirements

Python 3.9+
uv package manager

Setup

# Install dependencies
make install
# or: uv sync --dev && uv pip install -e .

# Format Python code
make format
# or: uv run yapf --in-place --recursive src/

# Run code quality checks
make check
# or: uv run ruff check src/ && uv run mypy src/ && uv run pyright src/

# Serve documentation locally
make serve-docs
# or: uv run mkdocs serve

# Build documentation
make build-docs

Code Quality

This project uses multiple tools for code quality:

YAPF: Python code formatter
Ruff: Fast Python linter
MyPy: Static type checking
Pyright: Additional static type checking
MkDocs: Documentation generation

Documentation Standards

All docstrings follow the Google Style Guide for Python docstrings. This includes:

Clear one-line summary
Detailed description when needed
Properly formatted Args:, Returns:, Raises:, and Examples: sections
Type information consistent with function signatures
Consistent capitalization and punctuation

Example:

def example_function(param1: str, param2: Optional[int] = None) -> dict[str, Any]:
    """
    Brief description of the function.

    Longer description if needed, explaining the function's behavior,
    side effects, or important usage notes.

    Args:
        param1 (str): Description of the first parameter.
        param2 (Optional[int]): Description of the optional parameter.

    Returns:
        dict[str, Any]: Description of the return value.

    Raises:
        ValueError: When this exception might be raised.

    Examples:
        >>> result = example_function("hello", 42)
        >>> print(result)
        {'status': 'success', 'data': 'hello'}
    """

License

MIT License. See the LICENSE file for details.