# deb-mock API Documentation

This document provides comprehensive documentation for the deb-mock Python API, designed for external tools and integrations.

## Table of Contents

- [Quick Start](#quick-start)
- [API Overview](#api-overview)
- [Configuration](#configuration)
- [Environment Management](#environment-management)
- [Command Execution](#command-execution)
- [Package Building](#package-building)
- [Advanced Features](#advanced-features)
- [Error Handling](#error-handling)
- [Examples](#examples)

## Quick Start

```python
from deb_mock import create_client, MockConfigBuilder

# Create a configuration
config = (MockConfigBuilder()
          .environment("my-build-env")
          .architecture("amd64")
          .suite("trixie")
          .packages(["build-essential", "cmake"])
          .build())

# Create API client
client = create_client(config)

# Create environment
env = client.create_environment("my-build-env")

# Use environment
with client.environment("my-build-env") as env:
    env.install_packages(["ninja-build"])
    result = env.execute(["cmake", "--version"])
    print(f"CMake version: {result.stdout}")

# Build a package
result = client.build_package("/path/to/package.dsc", "my-build-env")
print(f"Build successful: {result['success']}")
```

## API Overview

The deb-mock API consists of several main components:

### Core Classes

- **`MockAPIClient`**: Main API client for high-level operations
- **`MockEnvironment`**: Represents a mock environment
- **`EnvironmentManager`**: Comprehensive environment management
- **`MockConfigBuilder`**: Fluent configuration builder

### Data Classes

- **`EnvironmentInfo`**: Information about a mock environment
- **`BuildResult`**: Result of a build operation

### Convenience Functions

- **`create_client()`**: Create a new API client
- **`create_config()`**: Create a configuration builder
- **`quick_build()`**: Quick build function for simple use cases

## Configuration

### Using MockConfigBuilder

The `MockConfigBuilder` provides a fluent interface for creating configurations:

```python
from deb_mock import MockConfigBuilder

config = (MockConfigBuilder()
          .environment("debian-trixie-amd64")
          .architecture("amd64")
          .suite("trixie")
          .mirror("http://deb.debian.org/debian/")
          .packages(["build-essential", "devscripts"])
          .output_dir("/tmp/build-output")
          .cache_enabled(True)
          .parallel_jobs(4)
          .verbose(True)
          .build())
```

### Configuration Options

| Method | Description | Default |
|--------|-------------|---------|
| `.environment(name)` | Environment name | "bookworm-amd64" |
| `.architecture(arch)` | Target architecture | "amd64" |
| `.suite(suite)` | Debian suite | "bookworm" |
| `.mirror(url)` | Package mirror URL | Debian official |
| `.packages(list)` | Initial packages to install | [] |
| `.output_dir(path)` | Output directory | "./output" |
| `.cache_enabled(bool)` | Enable caching | True |
| `.parallel_jobs(int)` | Number of parallel jobs | 4 |
| `.verbose(bool)` | Verbose output | False |
| `.debug(bool)` | Debug output | False |

### Direct Configuration

You can also create configurations directly:

```python
from deb_mock import Config

config = Config(
    chroot_name="my-env",
    architecture="amd64",
    suite="trixie",
    mirror="http://deb.debian.org/debian/",
    chroot_additional_packages=["build-essential"],
    use_root_cache=True,
    parallel_jobs=4
)
```

## Environment Management

### Creating Environments

```python
from deb_mock import create_client

client = create_client()

# Create environment with specific settings
env = client.create_environment(
    name="build-env",
    arch="amd64",
    suite="trixie",
    packages=["build-essential", "cmake"]
)
```

### Environment Information

```python
# Get environment info
info = env.get_info()
print(f"Environment: {info.name}")
print(f"Architecture: {info.architecture}")
print(f"Suite: {info.suite}")
print(f"Status: {info.status}")
```

### Listing Environments

```python
# List all environments
environments = client.list_environments()
for env_name in environments:
    print(f"Environment: {env_name}")
```

### Removing Environments

```python
# Remove environment
client.remove_environment("build-env")
```

## Command Execution

### Basic Command Execution

```python
# Execute a command
result = env.execute(["ls", "-la", "/usr/bin"])
print(f"Return code: {result.returncode}")
print(f"Output: {result.stdout}")

# Execute string command
result = env.execute("dpkg -l | grep build-essential")
```

### Command Options

```python
# Execute with options
result = env.execute(
    ["apt", "list", "--installed"],
    capture_output=True,
    check=True,
    timeout=30
)
```

### Using Environment Manager

```python
from deb_mock import create_environment_manager

manager = create_environment_manager()

# Execute command in environment
result = manager.execute_command(
    "build-env",
    ["cmake", "--version"],
    capture_output=True
)
```

## Package Building

### Building Single Packages

```python
# Build a package
result = client.build_package(
    source_package="/path/to/package.dsc",
    environment="build-env",
    output_dir="/tmp/build-output"
)

print(f"Build successful: {result['success']}")
print(f"Artifacts: {result['artifacts']}")
```

### Parallel Building

```python
# Build multiple packages in parallel
packages = [
    "/path/to/package1.dsc",
    "/path/to/package2.dsc",
    "/path/to/package3.dsc"
]

results = client.build_parallel(
    packages,
    max_workers=2
)

for i, result in enumerate(results):
    print(f"Package {i+1}: {'Success' if result['success'] else 'Failed'}")
```

### Chain Building

```python
# Build packages in dependency order
chain = [
    "/path/to/base-package.dsc",
    "/path/to/depends-on-base.dsc",
    "/path/to/final-package.dsc"
]

results = client.build_chain(chain)
```

## Advanced Features

### Context Managers

```python
# Use environment context manager
with client.environment("build-env") as env:
    env.install_packages(["cmake", "ninja-build"])
    result = env.execute(["cmake", "--version"])
    # Environment is automatically cleaned up
```

### File Operations

```python
# Copy files into environment
env.copy_in("/local/source", "/build/source")

# Copy files out of environment
env.copy_out("/build/artifacts", "/local/artifacts")
```

### Artifact Collection

```python
from deb_mock import create_environment_manager

manager = create_environment_manager()

# Collect build artifacts
artifacts = manager.collect_artifacts(
    "build-env",
    source_patterns=["*.deb", "*.changes"],
    output_dir="/tmp/artifacts"
)

print(f"Collected {len(artifacts)} artifacts")
```

### Performance Monitoring

```python
# Get cache statistics
cache_stats = client.get_cache_stats()
print(f"Cache stats: {cache_stats}")

# Get performance summary
perf_summary = client.get_performance_summary()
print(f"Performance: {perf_summary}")

# Export metrics
metrics_file = client.export_metrics("/tmp/metrics.json")
print(f"Metrics exported to: {metrics_file}")
```

## Error Handling

### Common Exceptions

```python
from deb_mock.exceptions import ChrootError, ConfigurationError, SbuildError

try:
    env = client.create_environment("test-env")
except ChrootError as e:
    print(f"Chroot error: {e}")
except ConfigurationError as e:
    print(f"Configuration error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")
```

### Environment Validation

```python
# Check if environment exists
if client.environment_exists("test-env"):
    print("Environment exists")
else:
    print("Environment does not exist")
```

### Command Error Handling

```python
# Execute command with error handling
result = env.execute(["invalid-command"], check=False)
if result.returncode != 0:
    print(f"Command failed: {result.stderr}")
```

## Examples

### Complete Build Workflow

```python
from deb_mock import create_client, MockConfigBuilder

# Create configuration
config = (MockConfigBuilder()
          .environment("build-env")
          .architecture("amd64")
          .suite("trixie")
          .packages(["build-essential", "devscripts", "cmake"])
          .cache_enabled(True)
          .parallel_jobs(4)
          .build())

# Create client
client = create_client(config)

try:
    # Create environment
    env = client.create_environment("build-env")
    
    # Use environment
    with client.environment("build-env") as env:
        # Install additional packages
        env.install_packages(["ninja-build", "git"])
        
        # Execute setup commands
        env.execute(["git", "clone", "https://github.com/example/project.git", "/build/project"])
        
        # Build the package
        result = client.build_package("/build/project", "build-env")
        
        if result['success']:
            print("Build successful!")
            print(f"Artifacts: {result['artifacts']}")
        else:
            print("Build failed!")
    
finally:
    # Cleanup
    client.remove_environment("build-env")
```

### Multi-Architecture Building

```python
architectures = ["amd64", "arm64", "armhf"]
packages = ["/path/to/package.dsc"]

for arch in architectures:
    config = (MockConfigBuilder()
              .environment(f"build-{arch}")
              .architecture(arch)
              .suite("trixie")
              .build())
    
    client = create_client(config)
    
    try:
        env = client.create_environment(f"build-{arch}")
        result = client.build_package("/path/to/package.dsc", f"build-{arch}")
        print(f"{arch}: {'Success' if result['success'] else 'Failed'}")
    finally:
        client.remove_environment(f"build-{arch}")
```

### CI/CD Integration

```python
import os
from deb_mock import create_client, MockConfigBuilder

def build_package_in_ci(source_package, arch="amd64", suite="trixie"):
    """Build package in CI environment"""
    
    # Create configuration from environment variables
    config = (MockConfigBuilder()
              .environment(f"ci-build-{arch}")
              .architecture(arch)
              .suite(suite)
              .mirror(os.getenv("DEBIAN_MIRROR", "http://deb.debian.org/debian/"))
              .packages(["build-essential", "devscripts"])
              .output_dir(os.getenv("BUILD_OUTPUT_DIR", "/tmp/build-output"))
              .build())
    
    client = create_client(config)
    
    try:
        # Create environment
        env = client.create_environment(f"ci-build-{arch}")
        
        # Build package
        result = client.build_package(source_package, f"ci-build-{arch}")
        
        return {
            'success': result['success'],
            'artifacts': result['artifacts'],
            'environment': f"ci-build-{arch}"
        }
    
    finally:
        # Cleanup
        client.remove_environment(f"ci-build-{arch}")

# Usage in CI
if __name__ == "__main__":
    result = build_package_in_ci("/workspace/package.dsc")
    if result['success']:
        print("CI build successful!")
    else:
        print("CI build failed!")
        exit(1)
```

## Integration with External Tools

### debian-forge Integration

The deb-mock API is designed to integrate seamlessly with debian-forge:

```python
# Example debian-forge stage using deb-mock
def debian_forge_mock_stage(tree, options):
    from deb_mock import create_client, MockConfigBuilder
    
    # Create mock configuration from debian-forge options
    mock_options = options.get('mock_options', {})
    config = (MockConfigBuilder()
              .environment(mock_options.get('environment', 'debian-trixie'))
              .architecture(mock_options.get('arch', 'amd64'))
              .suite(mock_options.get('suite', 'trixie'))
              .packages(mock_options.get('packages', []))
              .build())
    
    client = create_client(config)
    
    # Create environment
    env_name = f"{config.chroot_name}-{int(time.time())}"
    env = client.create_environment(env_name)
    
    try:
        # Execute build commands
        for command in options.get('commands', []):
            result = env.execute(command)
            if result.returncode != 0:
                raise RuntimeError(f"Command failed: {command}")
        
        # Collect artifacts
        artifacts = client.collect_artifacts(env_name, output_dir=tree)
        
        return 0
    
    finally:
        client.remove_environment(env_name)
```

This API provides a stable, well-documented interface for external tools to integrate with deb-mock for build environment management.