cocalc-api: fix docstring style, check with pyright as well, fix/ignore missing return types, generate a better README

Author: haraldschilly

src/.claude/settings.json

@@ -15,6 +15,7 @@
       "Bash(git commit:*)",
       "Bash(git push:*)",
       "Bash(grep:*)",
+      "Bash(make:*)",
       "Bash(node:*)",
       "Bash(npm show:*)",
       "Bash(npm view:*)",
@@ -23,18 +24,23 @@
       "Bash(pnpm audit:*)",
       "Bash(pnpm build:*)",
       "Bash(pnpm i18n:*)",
+      "Bash(pnpm i18n:compile:*)",
+      "Bash(pnpm i18n:download:*)",
+      "Bash(pnpm i18n:extract:*)",
+      "Bash(pnpm i18n:upload:*)",
       "Bash(pnpm info:*)",
       "Bash(pnpm list:*)",
       "Bash(pnpm remove:*)",
       "Bash(pnpm run:*)",
       "Bash(pnpm ts-build:*)",
       "Bash(pnpm tsc:*)",
-      "Bash(pnpm view:*)",
       "Bash(pnpm update:*)",
+      "Bash(pnpm view:*)",
       "Bash(pnpm why:*)",
       "Bash(prettier -w:*)",
       "Bash(psql:*)",
       "Bash(python3:*)",
+      "Bash(uv:*)",
       "WebFetch",
       "WebSearch",
       "mcp__cclsp__find_definition",
@@ -43,7 +49,6 @@
       "mcp__github__get_issue_comments",
       "mcp__github__get_pull_request",
       "mcp__github__get_pull_request_comments",
-      "mcp__github__get_pull_request_comments",
       "mcp__github__get_pull_request_status",
       "mcp__github__list_workflow_runs",
       "mcp__github__list_workflows"

src/CLAUDE.md

@@ -222,6 +222,93 @@ Same flow as above, but **before 3. i18n:upload**, delete the key. Only new keys
 - Ignore everything in `node_modules` or `dist` directories
 - Ignore all files not tracked by Git, unless they are newly created files
 
+# CoCalc Python API Client
+
+## Overview
+
+The `python/cocalc-api/` directory contains a Python client library for the CoCalc API, published as the `cocalc-api` package on PyPI.
+
+## Architecture
+
+### Package Structure
+
+- **`src/cocalc_api/`** - Main Python package source code
+  - `__init__.py` - Package exports (Hub, Project classes)
+  - `hub.py` - Hub client for account-level API operations
+  - `project.py` - Project client for project-specific operations
+  - `api_types.py` - TypedDict definitions for API responses
+  - `util.py` - Utility functions and decorators
+
+### Key Classes
+
+#### Hub Client (`hub.py`)
+
+Account-level API client that provides access to:
+
+- **System** - Server ping, user search, account name resolution
+- **Projects** - Project management (create, start, stop, collaborators)
+- **Jupyter** - Global Jupyter kernel execution
+- **Database** - Direct PostgreSQL database queries
+- **Messages** - Send/receive messages between users
+- **Organizations** - Organization management (admin functions)
+- **Sync** - File history and synchronization
+
+#### Project Client (`project.py`)
+
+Project-specific API client for:
+
+- **System** - Project ping, shell command execution, Jupyter execution
+
+### Development Tools
+
+- **Package Manager**: `uv` (modern Python package manager)
+- **Code Formatter**: `yapf` (Python code formatter following Google style)
+- **Code Quality**: `ruff` (linting), `mypy` (type checking), `pyright` (additional type checking)
+- **Documentation**: `mkdocs` with material theme
+- **Testing**: `pytest`
+
+### Development Commands
+
+```bash
+# Setup and 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/
+
+# Code quality checks
+make check    # or: uv run ruff check src/ && uv run mypy src/ && uv run pyright src/
+
+# Documentation
+make serve-docs  # or: uv run mkdocs serve
+make build-docs  # or: uv run mkdocs build
+
+# Publishing
+make publish  # or: uv build && uv publish
+
+# Cleanup
+make clean
+```
+
+### API 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.)
+
+### Authentication
+
+- Supports both account-level and project-specific API keys
+- Account API keys provide full access to all hub functionality
+- Project API keys are limited to project-specific operations
+
+### Connection Endpoints
+
+- **Hub API**: `POST /api/conat/hub` - Account-level operations
+- **Project API**: `POST /api/conat/project` - Project-specific operations
+
 # important-instruction-reminders
 
 Do what has been asked; nothing more, nothing less.

src/python/cocalc-api/Makefile

@@ -5,9 +5,13 @@ install:
 	uv sync --dev
 	uv pip install -e .
 
+format:
+	uv run yapf --in-place --recursive src/
+
 check:
 	uv run ruff check src/
 	uv run mypy src/
+	uv run pyright src/
 
 serve-docs:
 	uv run mkdocs serve

src/python/cocalc-api/README.md

@@ -1,3 +1,168 @@
-https://pypi.org/project/cocalc-api/
+# CoCalc Python API Client
 
-This is a Python package that provides an API client for https://cocalc.com
+[![PyPI version](https://badge.fury.io/py/cocalc-api.svg)](https://pypi.org/project/cocalc-api/)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+
+This is a Python package that provides an API client for [CoCalc](https://cocalc.com), enabling programmatic access to CoCalc's features including project management, Jupyter execution, file operations, messaging, and organization management.
+
+## Installation
+
+```bash
+pip install cocalc-api
+```
+
+## Quick Start
+
+```python
+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
+
+## Authentication
+
+The client supports two types of API keys:
+
+1. **Account API Keys**: Provide full access to all hub functionality
+2. **Project API Keys**: Limited to project-specific operations
+
+Get your API key from [CoCalc Account Settings](https://cocalc.com/settings/account) 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](https://github.com/astral-sh/uv) package manager
+
+### Setup
+
+```bash
+# 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](https://github.com/google/yapf)**: Python code formatter
+- **[Ruff](https://docs.astral.sh/ruff/)**: Fast Python linter
+- **[MyPy](http://mypy-lang.org/)**: Static type checking
+- **[Pyright](https://github.com/microsoft/pyright)**: Additional static type checking
+- **[MkDocs](https://www.mkdocs.org/)**: Documentation generation
+
+### Documentation Standards
+
+All docstrings follow the [Google Style Guide](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) 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:
+```python
+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](LICENSE) file for details.
+
+## Links
+
+- [PyPI Package](https://pypi.org/project/cocalc-api/)
+- [CoCalc Website](https://cocalc.com)
+- [Documentation](https://cocalc.com/api/python)
+- [Source Code](https://github.com/sagemathinc/cocalc/tree/master/src/python/cocalc-api)
+- [Issue Tracker](https://github.com/sagemathinc/cocalc/issues)

src/python/cocalc-api/pyproject.toml

@@ -23,6 +23,17 @@ Issues = "https://github.com/sagemathinc/cocalc/issues"
 python_version = "3.13"
 # strict = true
 # disallow_untyped_defs = true
+# Ignore empty-body errors for decorator-implemented methods
+disable_error_code = ["empty-body"]
+
+[tool.pyright]
+# Ignore return type errors for decorator-implemented methods
+reportReturnType = false
+
+[tool.yapf]
+based_on_style = "pep8"
+column_limit = 150
+indent_width = 4
 
 [tool.ruff]
 line-length = 150
@@ -35,6 +46,8 @@ dev = [
     "mkdocs-material",
     "mkdocstrings[python]",
     "mypy",
+    "pyright",
     "pytest>=8.4.1",
     "ruff>=0.12.11",
+    "yapf",
 ]