Add stable Python API and comprehensive environment management
- Add MockAPIClient and MockEnvironment for external integration - Implement EnvironmentManager with full lifecycle support - Enhance plugin system with registry and BasePlugin class - Add comprehensive test suite and documentation - Include practical usage examples and plugin development guide
This commit is contained in:
parent
c51819c836
commit
8c585e2e33
9 changed files with 3413 additions and 1267 deletions
396
examples/api_usage_example.py
Normal file
396
examples/api_usage_example.py
Normal file
|
|
@ -0,0 +1,396 @@
|
|||
#!/usr/bin/env python3
|
||||
"""
|
||||
Example usage of deb-mock API
|
||||
|
||||
This script demonstrates how to use the deb-mock API for various
|
||||
build environment management tasks.
|
||||
"""
|
||||
|
||||
import os
|
||||
import sys
|
||||
import tempfile
|
||||
from pathlib import Path
|
||||
|
||||
# Add deb-mock to Python path
|
||||
sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..'))
|
||||
|
||||
from deb_mock.api import MockAPIClient, MockConfigBuilder, create_client, quick_build
|
||||
from deb_mock.environment_manager import EnvironmentManager, create_environment_manager
|
||||
from deb_mock.config import Config
|
||||
|
||||
|
||||
def example_basic_usage():
|
||||
"""Example of basic API usage"""
|
||||
print("=== Basic API Usage Example ===")
|
||||
|
||||
# Create a configuration using the builder
|
||||
config = (MockConfigBuilder()
|
||||
.environment("example-env")
|
||||
.architecture("amd64")
|
||||
.suite("trixie")
|
||||
.mirror("http://deb.debian.org/debian/")
|
||||
.packages(["build-essential", "devscripts", "cmake"])
|
||||
.cache_enabled(True)
|
||||
.parallel_jobs(4)
|
||||
.verbose(True)
|
||||
.build())
|
||||
|
||||
# Create API client
|
||||
client = MockAPIClient(config)
|
||||
|
||||
print(f"Created client with environment: {config.chroot_name}")
|
||||
print(f"Architecture: {config.architecture}")
|
||||
print(f"Suite: {config.suite}")
|
||||
print(f"Mirror: {config.mirror}")
|
||||
print(f"Initial packages: {config.chroot_additional_packages}")
|
||||
|
||||
|
||||
def example_environment_management():
|
||||
"""Example of environment management"""
|
||||
print("\n=== Environment Management Example ===")
|
||||
|
||||
# Create environment manager
|
||||
manager = create_environment_manager()
|
||||
|
||||
# Create a new environment
|
||||
print("Creating environment...")
|
||||
env_info = manager.create_environment(
|
||||
name="test-build-env",
|
||||
arch="amd64",
|
||||
suite="trixie",
|
||||
packages=["build-essential", "cmake", "ninja-build"]
|
||||
)
|
||||
|
||||
print(f"Created environment: {env_info.name}")
|
||||
print(f"Architecture: {env_info.architecture}")
|
||||
print(f"Suite: {env_info.suite}")
|
||||
print(f"Status: {env_info.status}")
|
||||
|
||||
# List all environments
|
||||
print("\nListing all environments...")
|
||||
environments = manager.list_environments()
|
||||
for env in environments:
|
||||
print(f" - {env.name} ({env.architecture}/{env.suite})")
|
||||
|
||||
# Get environment info
|
||||
print(f"\nGetting info for {env_info.name}...")
|
||||
info = manager.get_environment_info(env_info.name)
|
||||
print(f" Status: {info.status}")
|
||||
print(f" Size: {info.size} bytes")
|
||||
print(f" Packages installed: {len(info.packages_installed or [])}")
|
||||
|
||||
|
||||
def example_command_execution():
|
||||
"""Example of command execution in environments"""
|
||||
print("\n=== Command Execution Example ===")
|
||||
|
||||
manager = create_environment_manager()
|
||||
|
||||
# Create environment
|
||||
env_info = manager.create_environment(
|
||||
name="command-test-env",
|
||||
arch="amd64",
|
||||
suite="trixie",
|
||||
packages=["build-essential"]
|
||||
)
|
||||
|
||||
try:
|
||||
# Execute commands
|
||||
print("Executing commands in environment...")
|
||||
|
||||
# List installed packages
|
||||
result = manager.execute_command(
|
||||
env_info.name,
|
||||
["dpkg", "-l", "|", "grep", "build-essential"],
|
||||
capture_output=True
|
||||
)
|
||||
print(f"Build tools check: {result.returncode == 0}")
|
||||
|
||||
# Check system info
|
||||
result = manager.execute_command(
|
||||
env_info.name,
|
||||
["uname", "-a"],
|
||||
capture_output=True
|
||||
)
|
||||
print(f"System info: {result.stdout.strip()}")
|
||||
|
||||
# Check available space
|
||||
result = manager.execute_command(
|
||||
env_info.name,
|
||||
["df", "-h", "/"],
|
||||
capture_output=True
|
||||
)
|
||||
print(f"Disk usage:\n{result.stdout}")
|
||||
|
||||
finally:
|
||||
# Cleanup
|
||||
manager.remove_environment(env_info.name)
|
||||
|
||||
|
||||
def example_package_building():
|
||||
"""Example of package building"""
|
||||
print("\n=== Package Building Example ===")
|
||||
|
||||
client = create_client()
|
||||
|
||||
# Create environment for building
|
||||
env = client.create_environment(
|
||||
name="build-env",
|
||||
arch="amd64",
|
||||
suite="trixie",
|
||||
packages=["build-essential", "devscripts", "debhelper"]
|
||||
)
|
||||
|
||||
try:
|
||||
print(f"Created build environment: {env.name}")
|
||||
|
||||
# Example: Build a simple package (this would need actual source)
|
||||
print("Note: This example shows the API structure.")
|
||||
print("In practice, you would provide a real source package path.")
|
||||
|
||||
# Example build call (commented out as it needs real source)
|
||||
# result = client.build_package("/path/to/package.dsc", "build-env")
|
||||
# print(f"Build result: {result}")
|
||||
|
||||
finally:
|
||||
# Cleanup
|
||||
client.remove_environment(env.name)
|
||||
|
||||
|
||||
def example_context_manager():
|
||||
"""Example of using context managers"""
|
||||
print("\n=== Context Manager Example ===")
|
||||
|
||||
manager = create_environment_manager()
|
||||
|
||||
# Use environment context manager
|
||||
with manager.environment("context-test-env",
|
||||
arch="amd64",
|
||||
suite="trixie",
|
||||
packages=["build-essential"]) as env:
|
||||
|
||||
print(f"Environment active: {env.is_active()}")
|
||||
print(f"Environment name: {env.name}")
|
||||
print(f"Architecture: {env.architecture}")
|
||||
print(f"Suite: {env.suite}")
|
||||
|
||||
# Environment is automatically cleaned up when exiting context
|
||||
print("Environment will be cleaned up automatically")
|
||||
|
||||
print("Context exited, environment cleaned up")
|
||||
|
||||
|
||||
def example_parallel_building():
|
||||
"""Example of parallel building"""
|
||||
print("\n=== Parallel Building Example ===")
|
||||
|
||||
client = create_client()
|
||||
|
||||
# Example source packages (would be real paths in practice)
|
||||
source_packages = [
|
||||
"/path/to/package1.dsc",
|
||||
"/path/to/package2.dsc",
|
||||
"/path/to/package3.dsc"
|
||||
]
|
||||
|
||||
print("Parallel building example:")
|
||||
print(f"Would build {len(source_packages)} packages in parallel")
|
||||
print("Packages:", source_packages)
|
||||
|
||||
# Example parallel build call (commented out as it needs real sources)
|
||||
# results = client.build_parallel(source_packages, max_workers=2)
|
||||
# print(f"Build results: {len(results)} packages processed")
|
||||
|
||||
|
||||
def example_chain_building():
|
||||
"""Example of chain building"""
|
||||
print("\n=== Chain Building Example ===")
|
||||
|
||||
client = create_client()
|
||||
|
||||
# Example dependency chain (would be real paths in practice)
|
||||
chain_packages = [
|
||||
"/path/to/base-package.dsc",
|
||||
"/path/to/depends-on-base.dsc",
|
||||
"/path/to/final-package.dsc"
|
||||
]
|
||||
|
||||
print("Chain building example:")
|
||||
print("Would build packages in dependency order:")
|
||||
for i, pkg in enumerate(chain_packages, 1):
|
||||
print(f" {i}. {pkg}")
|
||||
|
||||
# Example chain build call (commented out as it needs real sources)
|
||||
# results = client.build_chain(chain_packages)
|
||||
# print(f"Chain build results: {len(results)} packages processed")
|
||||
|
||||
|
||||
def example_artifact_collection():
|
||||
"""Example of artifact collection"""
|
||||
print("\n=== Artifact Collection Example ===")
|
||||
|
||||
manager = create_environment_manager()
|
||||
|
||||
# Create environment
|
||||
env_info = manager.create_environment(
|
||||
name="artifact-test-env",
|
||||
arch="amd64",
|
||||
suite="trixie",
|
||||
packages=["build-essential"]
|
||||
)
|
||||
|
||||
try:
|
||||
print(f"Created environment: {env_info.name}")
|
||||
|
||||
# Example artifact collection (would work with real build artifacts)
|
||||
print("Artifact collection example:")
|
||||
print("Would collect artifacts like:")
|
||||
print(" - *.deb files")
|
||||
print(" - *.changes files")
|
||||
print(" - *.buildinfo files")
|
||||
print(" - *.dsc files")
|
||||
print(" - Source tarballs")
|
||||
|
||||
# Example artifact collection call (commented out as it needs real artifacts)
|
||||
# artifacts = manager.collect_artifacts(env_info.name)
|
||||
# print(f"Collected {len(artifacts)} artifacts")
|
||||
|
||||
finally:
|
||||
# Cleanup
|
||||
manager.remove_environment(env_info.name)
|
||||
|
||||
|
||||
def example_performance_monitoring():
|
||||
"""Example of performance monitoring"""
|
||||
print("\n=== Performance Monitoring Example ===")
|
||||
|
||||
client = create_client()
|
||||
|
||||
# Get cache statistics
|
||||
cache_stats = client.get_cache_stats()
|
||||
print(f"Cache statistics: {cache_stats}")
|
||||
|
||||
# Get performance summary (if available)
|
||||
try:
|
||||
perf_summary = client.get_performance_summary()
|
||||
print(f"Performance summary: {perf_summary}")
|
||||
except RuntimeError as e:
|
||||
print(f"Performance monitoring not available: {e}")
|
||||
|
||||
# Export metrics (if available)
|
||||
try:
|
||||
metrics_file = client.export_metrics()
|
||||
print(f"Metrics exported to: {metrics_file}")
|
||||
except RuntimeError as e:
|
||||
print(f"Metrics export not available: {e}")
|
||||
|
||||
|
||||
def example_error_handling():
|
||||
"""Example of error handling"""
|
||||
print("\n=== Error Handling Example ===")
|
||||
|
||||
manager = create_environment_manager()
|
||||
|
||||
# Try to get non-existent environment
|
||||
try:
|
||||
manager.get_environment_info("nonexistent-env")
|
||||
except ValueError as e:
|
||||
print(f"Expected error: {e}")
|
||||
|
||||
# Try to execute command in non-existent environment
|
||||
try:
|
||||
manager.execute_command("nonexistent-env", ["ls"])
|
||||
except ValueError as e:
|
||||
print(f"Expected error: {e}")
|
||||
|
||||
# Try to remove non-existent environment
|
||||
try:
|
||||
manager.remove_environment("nonexistent-env")
|
||||
except ValueError as e:
|
||||
print(f"Expected error: {e}")
|
||||
|
||||
|
||||
def example_configuration_variations():
|
||||
"""Example of different configuration options"""
|
||||
print("\n=== Configuration Variations Example ===")
|
||||
|
||||
# Ubuntu configuration
|
||||
ubuntu_config = (MockConfigBuilder()
|
||||
.environment("ubuntu-jammy-amd64")
|
||||
.architecture("amd64")
|
||||
.suite("jammy")
|
||||
.mirror("http://archive.ubuntu.com/ubuntu/")
|
||||
.packages(["build-essential", "cmake"])
|
||||
.build())
|
||||
|
||||
print("Ubuntu configuration:")
|
||||
print(f" Environment: {ubuntu_config.chroot_name}")
|
||||
print(f" Suite: {ubuntu_config.suite}")
|
||||
print(f" Mirror: {ubuntu_config.mirror}")
|
||||
|
||||
# ARM64 configuration
|
||||
arm64_config = (MockConfigBuilder()
|
||||
.environment("debian-trixie-arm64")
|
||||
.architecture("arm64")
|
||||
.suite("trixie")
|
||||
.mirror("http://deb.debian.org/debian/")
|
||||
.packages(["crossbuild-essential-arm64"])
|
||||
.build())
|
||||
|
||||
print("\nARM64 configuration:")
|
||||
print(f" Environment: {arm64_config.chroot_name}")
|
||||
print(f" Architecture: {arm64_config.architecture}")
|
||||
print(f" Cross-compilation packages: {arm64_config.chroot_additional_packages}")
|
||||
|
||||
# Development configuration
|
||||
dev_config = (MockConfigBuilder()
|
||||
.environment("dev-env")
|
||||
.architecture("amd64")
|
||||
.suite("sid") # Debian unstable
|
||||
.packages(["build-essential", "devscripts", "cmake", "ninja-build", "git"])
|
||||
.cache_enabled(True)
|
||||
.parallel_jobs(8)
|
||||
.verbose(True)
|
||||
.debug(True)
|
||||
.build())
|
||||
|
||||
print("\nDevelopment configuration:")
|
||||
print(f" Environment: {dev_config.chroot_name}")
|
||||
print(f" Suite: {dev_config.suite}")
|
||||
print(f" Packages: {dev_config.chroot_additional_packages}")
|
||||
print(f" Parallel jobs: {dev_config.parallel_jobs}")
|
||||
print(f" Verbose: {dev_config.verbose}")
|
||||
print(f" Debug: {dev_config.debug}")
|
||||
|
||||
|
||||
def main():
|
||||
"""Run all examples"""
|
||||
print("deb-mock API Usage Examples")
|
||||
print("=" * 50)
|
||||
|
||||
try:
|
||||
example_basic_usage()
|
||||
example_environment_management()
|
||||
example_command_execution()
|
||||
example_package_building()
|
||||
example_context_manager()
|
||||
example_parallel_building()
|
||||
example_chain_building()
|
||||
example_artifact_collection()
|
||||
example_performance_monitoring()
|
||||
example_error_handling()
|
||||
example_configuration_variations()
|
||||
|
||||
print("\n" + "=" * 50)
|
||||
print("All examples completed successfully!")
|
||||
print("\nNote: These examples demonstrate the API structure.")
|
||||
print("In practice, you would use real source packages and environments.")
|
||||
|
||||
except Exception as e:
|
||||
print(f"\nError running examples: {e}")
|
||||
import traceback
|
||||
traceback.print_exc()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
Loading…
Add table
Add a link
Reference in a new issue