Windows Shell Automation Utility

Build a Python utility that automates interactions with Windows shell components by creating and controlling COM objects. The utility focuses on creating COM objects and accessing their properties.

Requirements

Implement a module that provides the following functionality:

1. Create Shell Application: Initialize a new Windows Shell Application COM object
2. Connect to Running Instance: Attach to an already-running shell application instance if available
3. Browse Folders: Open special Windows folders using folder identifiers
4. Access Properties: Extract folder properties like title and path from COM objects

The module should handle errors gracefully when COM objects cannot be created or accessed.

@generates

API

def create_shell_object():
    """
    Create and return a new Windows Shell Application COM object.

    Returns:
        COM object representing Shell.Application

    Raises:
        RuntimeError: If the COM object cannot be created
    """
    pass

def get_active_shell_object():
    """
    Connect to an already-running Windows Shell Application COM object.

    Returns:
        COM object representing active Shell.Application, or None if not found
    """
    pass

def browse_folder(shell_obj, folder_id):
    """
    Browse to a special shell folder using the shell object.

    Args:
        shell_obj: Shell.Application COM object
        folder_id: Integer identifying the special folder (e.g., 0 for Desktop)

    Returns:
        Folder COM object representing the browsed folder

    Raises:
        RuntimeError: If folder cannot be accessed
    """
    pass

def get_folder_title(folder_obj):
    """
    Get the title of a shell folder object.

    Args:
        folder_obj: Folder COM object

    Returns:
        String containing the folder title
    """
    pass

Test Cases

• Creates a new Shell.Application COM object successfully @test
• Connects to an active Shell.Application instance when one exists @test
• Browses to Desktop folder (folder_id=0) and retrieves folder object @test
• Extracts folder title property correctly @test
• Handles errors gracefully when COM object creation fails @test

Dependencies { .dependencies }

comtypes { .dependency }

Provides COM interoperability for Windows automation.