API Reference¶

This section contains the complete API reference for VSCode Sockpuppet, automatically generated from the Python source code docstrings.

Core Classes¶

Client & Connection¶

VSCodeClient - Main client for connecting to VS Code

UI & Windows¶

Window - Window operations, messages, dialogs
Editor - Text editor operations and decorations
Webview - Custom HTML panels

Documents & Files¶

TextDocument - Document access and text operations
Workspace - Workspace folders, files, configuration
FileSystem - File system operations

Events & Monitoring¶

Events - Event subscription system
FileWatcher - File system watching

UI Components¶

Terminal - Terminal management
Tabs - Tab and tab group management
StatusBar - Status bar items
Progress - Progress indicators

Development Tools¶

Diagnostics - Problem reporting and language features
Configuration - Settings and configuration

Type Definitions¶

Types - TypedDict definitions for API structures

API Design Principles¶

1. Mirror VS Code API¶

The Python API closely mirrors the official VS Code Extension API, making it familiar to VS Code extension developers.

# VS Code Extension API (TypeScript)
vscode.window.showInformationMessage("Hello!");

# VSCode Sockpuppet (Python) 
vscode.window.show_information_message("Hello!")

2. Pythonic Conventions¶

snake_case naming instead of camelCase
Properties instead of getters
Context managers for resource management
Type hints throughout

3. Type Safety¶

Full type hints with TypedDict for options:

from vscode_sockpuppet import QuickPickOptions

options: QuickPickOptions = {
    "placeHolder": "Select an option",
    "canPickMany": False
}
result = vscode.window.show_quick_pick(["A", "B", "C"], options)

4. Event System¶

VS Code-style event subscriptions:

# Subscribe to editor changes
def on_change(editor):
    print(f"Now editing: {editor.document.file_name}")

vscode.window.on_did_change_active_text_editor(on_change)

Common Patterns¶

Context Manager¶

Always use the context manager for automatic cleanup:

with VSCodeClient() as vscode:
    # Your code here
    pass
# Connection automatically closed

Error Handling¶

Methods return None when operations fail or are dismissed:

result = vscode.window.show_quick_pick(["A", "B", "C"])
if result is None:
    print("User dismissed the picker")
else:
    print(f"Selected: {result}")

Async Operations¶

Most operations are synchronous, but events use callbacks:

def handle_save(doc):
    print(f"Saved: {doc.file_name}")

vscode.workspace.on_did_save_text_document(handle_save)

Next Steps¶

Browse the individual API pages for detailed documentation
Check out Examples for practical use cases
Read the Development Guide to contribute