deb-mock/docs/API.md

# Deb-Mock API Reference

## Overview

This document provides a comprehensive reference for the `deb-mock` API, including all classes, methods, and their usage. The API is designed to be intuitive and follows Python best practices.

## Table of Contents

1. [Core Classes](#core-classes)
2. [Configuration](#configuration)
3. [Chroot Management](#chroot-management)
4. [Cache Management](#cache-management)
5. [Sbuild Integration](#sbuild-integration)
6. [Plugin System](#plugin-system)
7. [Performance Monitoring](#performance-monitoring)
8. [Benchmarking](#benchmarking)
9. [Exceptions](#exceptions)
10. [CLI Interface](#cli-interface)
11. [Examples](#examples)

## Core Classes

### DebMock

The main class that orchestrates the build process.

```python
from deb_mock.core import DebMock

# Initialize with configuration
deb_mock = DebMock(config)

# Build a package
result = deb_mock.build("package-name", "source-path")

# Get status
status = deb_mock.get_status()

# Cleanup
deb_mock.cleanup()
```

#### Methods

##### `__init__(config)`

Initialize a new DebMock instance.

**Parameters:**
- `config`: Configuration object or path to config file

**Example:**
```python
from deb_mock.config import Config

config = Config.from_file("deb-mock.yaml")
deb_mock = DebMock(config)
```

##### `build(package_name, source_path, **kwargs)`

Build a package from source.

**Parameters:**
- `package_name`: Name of the package to build
- `source_path`: Path to the source package
- `**kwargs`: Additional build options

**Options:**
- `chroot_name`: Custom chroot name
- `keep_chroot`: Whether to keep chroot after build
- `parallel`: Enable parallel building
- `clean_cache`: Clean cache before building

**Returns:**
- `BuildResult`: Object containing build results

**Example:**
```python
result = deb_mock.build(
    "my-package",
    "/path/to/source",
    chroot_name="custom-chroot",
    keep_chroot=True,
    parallel=True
)

print(f"Build successful: {result.success}")
print(f"Build duration: {result.duration:.2f}s")
print(f"Output files: {result.output_files}")
```

##### `build_chain(packages, **kwargs)`

Build multiple packages sequentially.

**Parameters:**
- `packages`: List of package specifications
- `**kwargs`: Additional build options

**Example:**
```python
packages = [
    {"name": "package1", "source": "/path/to/pkg1"},
    {"name": "package2", "source": "/path/to/pkg2"},
    {"name": "package3", "source": "/path/to/pkg3"}
]

results = deb_mock.build_chain(packages, parallel=False)
```

##### `build_parallel(packages, **kwargs)`

Build multiple packages in parallel.

**Parameters:**
- `packages`: List of package specifications
- `**kwargs**: Additional build options

**Example:**
```python
packages = [
    {"name": "package1", "source": "/path/to/pkg1"},
    {"name": "package2", "source": "/path/to/pkg2"},
    {"name": "package3", "source": "/path/to/pkg3"}
]

results = deb_mock.build_parallel(packages, max_workers=4)
```

##### `get_status()`

Get current status of the deb-mock instance.

**Returns:**
- `dict`: Status information

**Example:**
```python
status = deb_mock.get_status()
print(f"Active chroots: {status['chroot_manager']['chroots']}")
print(f"Cache status: {status['cache_manager']['caches']}")
print(f"Performance monitoring: {status['performance_monitor']['enabled']}")
```

##### `cleanup()`

Clean up resources and temporary files.

**Example:**
```python
deb_mock.cleanup()
```

## Configuration

### Config

Configuration management class.

```python
from deb_mock.config import Config

# Load from file
config = Config.from_file("deb-mock.yaml")

# Load from dictionary
config = Config.from_dict({
    "chroot": {"suite": "trixie", "architecture": "amd64"},
    "cache": {"enabled": True}
})

# Access configuration values
suite = config.chroot.suite
cache_enabled = config.cache.enabled
```

#### Configuration Schema

```yaml
chroot:
  base_dir: /var/lib/deb-mock/chroots
  suite: trixie
  architecture: amd64
  mirror: http://deb.debian.org/debian/
  components: [main, contrib, non-free]

cache:
  enabled: true
  base_dir: /var/cache/deb-mock
  ccache_size_mb: 2048
  root_cache_size_mb: 5120
  package_cache_size_mb: 1024

sbuild:
  enabled: true
  user: sbuild
  group: sbuild
  chroot_suffix: -sbuild
  build_user: buildd

performance:
  enable_performance_monitoring: true
  performance_metrics_dir: ./performance-metrics
  performance_retention_days: 30
  performance_auto_optimization: true
  performance_benchmark_iterations: 10
  performance_reporting: true

plugins:
  enabled: true
  plugin_dir: ./plugins
  auto_load: true

parallel:
  enabled: true
  max_parallel_builds: 4
  max_parallel_chroots: 8

mounts:
  proc: true
  sys: true
  dev: true
  tmpfs: true
  bind_mounts:
    - source: /var/cache/apt/archives
      target: /var/cache/apt/archives
      options: [ro]
  overlay_mounts:
    - source: /var/cache/deb-mock/overlay
      target: /var/cache/deb-mock/overlay

uid_management:
  enabled: true
  create_users: true
  copy_host_users: true
  privilege_escalation: true
```

## Chroot Management

### ChrootManager

Manages chroot environments for builds.

```python
from deb_mock.chroot import ChrootManager

chroot_manager = ChrootManager(config)

# Create a new chroot
chroot = chroot_manager.create_chroot("trixie-amd64")

# List existing chroots
chroots = chroot_manager.list_chroots()

# Clean up chroot
chroot_manager.cleanup_chroot("trixie-amd64")
```

#### Methods

##### `create_chroot(name, suite=None, architecture=None)`

Create a new chroot environment.

**Parameters:**
- `name`: Name for the chroot
- `suite`: Debian suite (defaults to config)
- `architecture`: Architecture (defaults to config)

**Returns:**
- `Chroot`: Chroot instance

**Example:**
```python
chroot = chroot_manager.create_chroot(
    "trixie-amd64",
    suite="trixie",
    architecture="amd64"
)
```

##### `get_chroot(name)`

Get an existing chroot by name.

**Parameters:**
- `name`: Chroot name

**Returns:**
- `Chroot`: Chroot instance or None

**Example:**
```python
chroot = chroot_manager.get_chroot("trixie-amd64")
if chroot:
    print(f"Chroot exists: {chroot.path}")
```

##### `list_chroots()`

List all available chroots.

**Returns:**
- `list`: List of chroot names

**Example:**
```python
chroots = chroot_manager.list_chroots()
for chroot_name in chroots:
    print(f"Available chroot: {chroot_name}")
```

##### `cleanup_chroot(name)`

Remove a chroot environment.

**Parameters:**
- `name`: Chroot name

**Example:**
```python
chroot_manager.cleanup_chroot("trixie-amd64")
```

## Cache Management

### CacheManager

Manages build caches for improved performance.

```python
from deb_mock.cache import CacheManager

cache_manager = CacheManager(config)

# Create cache
cache = cache_manager.create_cache("package-name")

# Restore cache
success = cache_manager.restore_cache("package-name")

# Clean cache
cache_manager.clean_cache("package-name")
```

#### Methods

##### `create_cache(package_name)`

Create a cache for a package.

**Parameters:**
- `package_name`: Name of the package

**Returns:**
- `Cache`: Cache instance

**Example:**
```python
cache = cache_manager.create_cache("my-package")
```

##### `restore_cache(package_name)`

Restore cache for a package.

**Parameters:**
- `package_name`: Name of the package

**Returns:**
- `bool`: True if restoration was successful

**Example:**
```python
if cache_manager.restore_cache("my-package"):
    print("Cache restored successfully")
else:
    print("Cache restoration failed")
```

##### `clean_cache(package_name)`

Clean cache for a package.

**Parameters:**
- `package_name`: Name of the package

**Example:**
```python
cache_manager.clean_cache("my-package")
```

## Sbuild Integration

### SbuildWrapper

Wrapper for sbuild integration.

```python
from deb_mock.sbuild import SbuildWrapper

sbuild = SbuildWrapper(config)

# Check sbuild availability
if sbuild.is_available():
    print("Sbuild is available")
else:
    print("Sbuild is not available")

# Build a package
result = sbuild.build_package("source.dsc", chroot_name="trixie-amd64")
```

#### Methods

##### `is_available()`

Check if sbuild is available and properly configured.

**Returns:**
- `bool`: True if sbuild is available

**Example:**
```python
if sbuild.is_available():
    print("Sbuild is ready to use")
else:
    print("Sbuild needs configuration")
```

##### `build_package(source_path, chroot_name=None, **kwargs)`

Build a package using sbuild.

**Parameters:**
- `source_path`: Path to source package
- `chroot_name`: Chroot to use for building
- `**kwargs`: Additional build options

**Returns:**
- `SbuildResult`: Build result

**Example:**
```python
result = sbuild.build_package(
    "/path/to/package.dsc",
    chroot_name="trixie-amd64",
    verbose=True
)

if result.success:
    print(f"Build successful: {result.output_files}")
else:
    print(f"Build failed: {result.error}")
```

##### `update_chroot(chroot_name)`

Update a chroot with latest packages.

**Parameters:**
- `chroot_name`: Name of the chroot to update

**Returns:**
- `bool`: True if update was successful

**Example:**
```python
if sbuild.update_chroot("trixie-amd64"):
    print("Chroot updated successfully")
```

## Plugin System

### PluginManager

Manages plugins and their lifecycle.

```python
from deb_mock.plugin import PluginManager

plugin_manager = PluginManager(config)

# Load plugins
plugin_manager.load_plugins()

# Get plugin information
plugins = plugin_manager.list_plugins()

# Enable/disable plugins
plugin_manager.enable_plugin("ccache_plugin")
plugin_manager.disable_plugin("debug_plugin")
```

#### Methods

##### `load_plugins()`

Load all available plugins.

**Example:**
```python
plugin_manager.load_plugins()
print(f"Loaded {len(plugin_manager.plugins)} plugins")
```

##### `list_plugins()`

List all available plugins.

**Returns:**
- `list`: List of plugin information

**Example:**
```python
plugins = plugin_manager.list_plugins()
for plugin in plugins:
    print(f"Plugin: {plugin['name']} - Status: {plugin['status']}")
```

##### `enable_plugin(plugin_name)`

Enable a specific plugin.

**Parameters:**
- `plugin_name`: Name of the plugin to enable

**Returns:**
- `bool`: True if plugin was enabled

**Example:**
```python
if plugin_manager.enable_plugin("ccache_plugin"):
    print("CCache plugin enabled")
```

##### `disable_plugin(plugin_name)`

Disable a specific plugin.

**Parameters:**
- `plugin_name`: Name of the plugin to disable

**Returns:**
- `bool`: True if plugin was disabled

**Example:**
```python
if plugin_manager.disable_plugin("debug_plugin"):
    print("Debug plugin disabled")
```

### BasePlugin

Base class for creating custom plugins.

```python
from deb_mock.plugin import BasePlugin, HookStages

class MyCustomPlugin(BasePlugin):
    name = "my_custom_plugin"
    version = "1.0.0"
    description = "A custom plugin for deb-mock"
    
    def __init__(self):
        super().__init__()
        self.register_hook(HookStages.PRE_BUILD, self.pre_build_hook)
        self.register_hook(HookStages.POST_BUILD, self.post_build_hook)
    
    def pre_build_hook(self, context):
        print("Pre-build hook executed")
        return context
    
    def post_build_hook(self, context):
        print("Post-build hook executed")
        return context
```

#### Hook Stages

- `PRE_CHROOT_CREATE`: Before chroot creation
- `POST_CHROOT_CREATE`: After chroot creation
- `PRE_BUILD`: Before build starts
- `POST_BUILD`: After build completes
- `PRE_CACHE_RESTORE`: Before cache restoration
- `POST_CACHE_RESTORE`: After cache restoration
- `PRE_CLEANUP`: Before cleanup
- `POST_CLEANUP`: After cleanup

## Performance Monitoring

### PerformanceMonitor

Monitors and tracks performance metrics.

```python
from deb_mock.performance import PerformanceMonitor

monitor = PerformanceMonitor(config)

# Start monitoring
monitor.start_monitoring()

# Monitor an operation
with monitor.monitor_operation("build_operation"):
    # Your operation here
    pass

# Get performance summary
summary = monitor.get_performance_summary()
```

#### Methods

##### `start_monitoring()`

Start system monitoring.

**Example:**
```python
monitor.start_monitoring()
```

##### `stop_monitoring()`

Stop system monitoring.

**Example:**
```python
monitor.stop_monitoring()
```

##### `monitor_operation(operation_name)`

Context manager for monitoring operations.

**Parameters:**
- `operation_name`: Name of the operation to monitor

**Example:**
```python
with monitor.monitor_operation("package_build"):
    # Build operation
    result = build_package()
```

##### `get_performance_summary()`

Get a summary of performance metrics.

**Returns:**
- `dict`: Performance summary

**Example:**
```python
summary = monitor.get_performance_summary()
print(f"Total operations: {summary['total_operations']}")
print(f"Average duration: {summary['average_duration']:.2f}s")
```

##### `create_build_profile(build_id, package_name, architecture, suite)`

Create a build performance profile.

**Parameters:**
- `build_id`: Unique build identifier
- `package_name`: Name of the package
- `architecture`: Build architecture
- `suite`: Debian suite

**Returns:**
- `BuildProfile`: Build profile instance

**Example:**
```python
profile = monitor.create_build_profile(
    "build-123",
    "my-package",
    "amd64",
    "trixie"
)
```

### PerformanceOptimizer

Provides optimization suggestions based on performance data.

```python
from deb_mock.performance import PerformanceOptimizer

optimizer = PerformanceOptimizer(config)

# Analyze build performance
analysis = optimizer.analyze_build_performance(profile)

# Get optimization suggestions
suggestions = optimizer.get_optimization_suggestions(profile)
```

#### Methods

##### `analyze_build_performance(profile)`

Analyze build performance for optimization opportunities.

**Parameters:**
- `profile`: BuildProfile instance

**Returns:**
- `dict`: Performance analysis

**Example:**
```python
analysis = optimizer.analyze_build_performance(profile)
print(f"Optimization score: {analysis['optimization_score']}")
```

##### `get_optimization_suggestions(profile)`

Get optimization suggestions for a build profile.

**Parameters:**
- `profile`: BuildProfile instance

**Returns:**
- `list`: List of optimization suggestions

**Example:**
```python
suggestions = optimizer.get_optimization_suggestions(profile)
for suggestion in suggestions:
    print(f"Suggestion: {suggestion}")
```

### PerformanceReporter

Generates performance reports and visualizations.

```python
from deb_mock.performance import PerformanceReporter

reporter = PerformanceReporter(config)

# Generate performance report
report_path = reporter.generate_performance_report(monitor)

# Generate build profile report
profile_report = reporter.generate_build_profile_report(profile)
```

#### Methods

##### `generate_performance_report(monitor, output_file=None)`

Generate a comprehensive performance report.

**Parameters:**
- `monitor`: PerformanceMonitor instance
- `output_file`: Output file path (optional)

**Returns:**
- `str`: Path to generated report

**Example:**
```python
report_path = reporter.generate_performance_report(monitor)
print(f"Report generated: {report_path}")
```

##### `generate_build_profile_report(profile, output_file=None)`

Generate a build profile report.

**Parameters:**
- `profile`: BuildProfile instance
- `output_file`: Output file path (optional)

**Returns:**
- `str`: Path to generated report

**Example:**
```python
profile_report = reporter.generate_build_profile_report(profile)
print(f"Profile report generated: {profile_report}")
```

## Benchmarking

### BenchmarkRunner

Runs performance benchmarks for operations.

```python
from deb_mock.benchmarking import BenchmarkRunner

runner = BenchmarkRunner(config)

# Run a benchmark
result = runner.run_benchmark(
    "build_benchmark",
    build_function,
    iterations=20
)

# Compare benchmarks
comparison = runner.compare_benchmarks(["benchmark1", "benchmark2"])
```

#### Methods

##### `run_benchmark(benchmark_name, operation_func, **kwargs)`

Run a benchmark for a specific operation.

**Parameters:**
- `benchmark_name`: Name of the benchmark
- `operation_func`: Function to benchmark
- `**kwargs`: Benchmark configuration

**Returns:**
- `BenchmarkResult`: Benchmark result

**Example:**
```python
def build_operation():
    # Build operation to benchmark
    pass

result = runner.run_benchmark(
    "build_benchmark",
    build_operation,
    iterations=50,
    parallel_runs=4
)

print(f"Average duration: {result.average_duration:.3f}s")
print(f"Standard deviation: {result.standard_deviation:.3f}s")
```

##### `compare_benchmarks(benchmark_names)`

Compare multiple benchmark results.

**Parameters:**
- `benchmark_names`: List of benchmark names to compare

**Returns:**
- `dict`: Comparison results

**Example:**
```python
comparison = runner.compare_benchmarks(["quick", "standard", "comprehensive"])
print(f"Fastest benchmark: {comparison['analysis']['fastest_benchmark']}")
print(f"Most stable: {comparison['analysis']['most_stable_benchmark']}")
```

## Exceptions

### DebMockError

Base exception for deb-mock errors.

```python
from deb_mock.exceptions import DebMockError

try:
    # Some operation
    pass
except DebMockError as e:
    print(f"Deb-mock error: {e}")
```

### ChrootError

Exception raised for chroot-related errors.

```python
from deb_mock.exceptions import ChrootError

try:
    chroot_manager.create_chroot("invalid-name")
except ChrootError as e:
    print(f"Chroot error: {e}")
```

### CacheError

Exception raised for cache-related errors.

```python
from deb_mock.exceptions import CacheError

try:
    cache_manager.restore_cache("package-name")
except CacheError as e:
    print(f"Cache error: {e}")
```

### PerformanceError

Exception raised for performance monitoring errors.

```python
from deb_mock.exceptions import PerformanceError

try:
    monitor.start_monitoring()
except PerformanceError as e:
    print(f"Performance error: {e}")
```

### PluginError

Exception raised for plugin-related errors.

```python
from deb_mock.exceptions import PluginError

try:
    plugin_manager.load_plugins()
except PluginError as e:
    print(f"Plugin error: {e}")
```

## CLI Interface

The `deb-mock` command-line interface provides access to all functionality.

### Basic Commands

```bash
# Get help
deb-mock --help

# Show version
deb-mock --version

# Show status
deb-mock status

# Build a package
deb-mock build package-name source-path

# List chroots
deb-mock list-chroots

# Create chroot
deb-mock create-chroot --suite trixie --architecture amd64

# Cleanup
deb-mock cleanup
```

### Performance Commands

```bash
# Performance summary
deb-mock performance-summary

# Performance report
deb-mock performance-report

# Run benchmark
deb-mock benchmark --template standard

# Performance analysis
deb-mock performance-analysis
```

### Plugin Commands

```bash
# List plugins
deb-mock plugin list

# Enable plugin
deb-mock plugin enable ccache_plugin

# Disable plugin
deb-mock plugin disable debug_plugin

# Plugin info
deb-mock plugin info ccache_plugin
```

### Sbuild Commands

```bash
# Check sbuild status
deb-mock sbuild status

# Update chroot
deb-mock sbuild update-chroot trixie-amd64

# Build package
deb-mock sbuild build-package source.dsc
```

## Examples

### Complete Build Example

```python
from deb_mock.core import DebMock
from deb_mock.config import Config

# Load configuration
config = Config.from_file("deb-mock.yaml")

# Initialize deb-mock
deb_mock = DebMock(config)

try:
    # Build a package
    result = deb_mock.build(
        "my-package",
        "/path/to/source",
        chroot_name="trixie-amd64",
        parallel=True
    )
    
    if result.success:
        print(f"Build successful in {result.duration:.2f}s")
        print(f"Output files: {result.output_files}")
    else:
        print(f"Build failed: {result.error}")
        
finally:
    # Cleanup
    deb_mock.cleanup()
```

### Performance Monitoring Example

```python
from deb_mock.performance import PerformanceMonitor, PerformanceReporter

monitor = PerformanceMonitor(config)
reporter = PerformanceReporter(config)

# Start monitoring
monitor.start_monitoring()

try:
    # Monitor build operation
    with monitor.monitor_operation("package_build"):
        # Build operation
        result = build_package()
    
    # Generate performance report
    report_path = reporter.generate_performance_report(monitor)
    print(f"Performance report: {report_path}")
    
finally:
    # Stop monitoring
    monitor.stop_monitoring()
```

### Plugin Development Example

```python
from deb_mock.plugin import BasePlugin, HookStages

class BuildNotificationPlugin(BasePlugin):
    name = "build_notification"
    version = "1.0.0"
    description = "Sends notifications on build completion"
    
    def __init__(self):
        super().__init__()
        self.register_hook(HookStages.POST_BUILD, self.notify_build_complete)
    
    def notify_build_complete(self, context):
        if context.get('build_success'):
            print(f"✅ Build completed successfully for {context['package_name']}")
        else:
            print(f"❌ Build failed for {context['package_name']}")
        return context

# Plugin will be automatically loaded if placed in plugin directory
```

### Benchmarking Example

```python
from deb_mock.benchmarking import BenchmarkRunner

runner = BenchmarkRunner(config)

def build_operation():
    # Simulate build operation
    import time
    time.sleep(1)
    return {"success": True}

# Run comprehensive benchmark
result = runner.run_benchmark(
    "build_benchmark",
    build_operation,
    iterations=100,
    parallel_runs=4
)

print(f"Benchmark completed:")
print(f"  Iterations: {result.iterations}")
print(f"  Average duration: {result.average_duration:.3f}s")
print(f"  Standard deviation: {result.standard_deviation:.3f}s")
print(f"  Performance stability: {result.analysis['performance_stability']}")
```

## Conclusion

This API reference provides comprehensive coverage of all `deb-mock` functionality. For additional examples and advanced usage patterns, refer to the main documentation and plugin examples.

The API is designed to be intuitive and follows Python best practices, making it easy to integrate `deb-mock` into existing build systems and workflows.