python-sdk/pkg/hanzo-async

hanzo-async

Unified async I/O for Hanzo AI - high-performance with uvloop fallback.

Features

• Automatic uvloop configuration - Falls back to asyncio on Windows
• Async file I/O - Read, write, append with aiofiles
• Async path operations - exists, is_file, mkdir, etc.
• Async subprocess execution - run_command, run_shell
• Consistent patterns - Same API across all Hanzo packages

Installation

pip install hanzo-async

# With uvloop support (recommended for macOS/Linux)
pip install hanzo-async[uvloop]

Quick Start

from hanzo_async import (
    # Loop configuration
    configure_loop,
    using_uvloop,

    # File operations
    read_file,
    write_file,
    read_json,
    write_json,

    # Path operations
    path_exists,
    is_file,
    is_dir,
    mkdir,

    # Process operations
    run_command,
    run_shell,
)

# Check if using uvloop
if using_uvloop():
    print("Using uvloop for high-performance async")

# Async file operations
async def example():
    # Read/write files
    content = await read_file("/path/to/file.txt")
    await write_file("/path/to/output.txt", content)

    # JSON handling
    data = await read_json("/path/to/config.json")
    data["updated"] = True
    await write_json("/path/to/config.json", data)

    # Path operations
    if await path_exists("/path/to/file"):
        if await is_file("/path/to/file"):
            await unlink("/path/to/file")

    await mkdir("/path/to/new/dir", parents=True, exist_ok=True)

    # Run commands
    stdout, stderr, code = await run_command("ls", "-la")
    stdout, stderr, code = await run_shell("echo $HOME && pwd")

API Reference

Loop Configuration

• configure_loop() - Configure uvloop (auto-called on import)
• using_uvloop() - Check if uvloop is active
• get_loop() - Get current event loop

File Operations

• read_file(path) - Read file content
• write_file(path, content) - Write content to file
• append_file(path, content) - Append to file
• read_json(path) - Read and parse JSON
• write_json(path, data) - Write JSON to file
• read_lines(path) - Read file as lines
• write_lines(path, lines) - Write lines to file
• read_bytes(path) - Read file as bytes
• write_bytes(path, content) - Write bytes to file

Path Operations

• path_exists(path) - Check if path exists
• is_file(path) - Check if path is file
• is_dir(path) - Check if path is directory
• mkdir(path, parents=False, exist_ok=False) - Create directory
• rmdir(path) - Remove empty directory
• unlink(path, missing_ok=False) - Remove file
• stat(path) - Get file/directory stats
• listdir(path) - List directory contents
• glob(pattern, root_dir=None, recursive=False) - Find files
• rename(src, dst) - Rename/move file
• copy(src, dst) - Copy file
• copytree(src, dst) - Copy directory tree
• rmtree(path) - Remove directory tree

Process Operations

• run_command(*args) - Run command with args
• run_shell(command) - Run shell command
• check_command(command) - Check if command exists
• which(command) - Find command path
• start_background(*args) - Start background process

Why hanzo-async?

1. Consistent async patterns - All Hanzo packages use the same I/O patterns
2. High performance - uvloop provides 2-4x faster async on Unix
3. Automatic fallback - Works on Windows with standard asyncio
4. No event loop blocking - All operations are truly async
5. Easy to use - Simple function-based API

License

MIT