How to create a StateChanger. useful for when creating a StateChanger
This guide explains how to implement a new StateChanger for the DevBox framework.
Create your StateChanger in: devbox/state_changers/<name>.py
Use snake_case for the filename (e.g., home_brew.py, create_or_replace_file.py).
import hashlib # For generating checksums
from devbox.change_result import ChangeResult
from devbox.change_status import ChangeStatus
from devbox.state_changer import StateChanger
from devbox.target import Target
from devbox.target_lock import TargetLock
from devbox.utils.devbox_log import DevBoxLog
class MyStateChanger(StateChanger):
"""Brief description of what this state changer does."""
def __init__(self, my_param: str, log: DevBoxLog) -> None:
"""Initialize the state changer.
Args:
my_param: Description of parameter.
log: The logger instance for logging operations.
"""
self.my_param = my_param
self.log = log
def __repr__(self) -> str:
"""Return a string representation for traceable logging."""
return f"MyStateChanger({self.my_param})"
def get_name(self) -> str:
"""Return the name of this state changer."""
return f"MyStateChanger({self.my_param})"
def get_locks(self) -> list[TargetLock]:
"""Return the target locks for this state changer."""
checksum = hashlib.sha256(self.my_param.encode()).hexdigest()
description = f"Description of what is being locked: {self.my_param}"
target = Target(
name=self.my_param,
checksum=checksum,
description=description,
)
target_lock = TargetLock(
target=target,
timeout_s=30, # Adjust based on expected operation time
)
return [target_lock]
def change(self) -> ChangeResult:
"""Apply the state change."""
self.log.info_from(self, f"Starting operation for: {self.my_param}")
try:
# Perform the actual change here
self.log.info_from(self, f"Operation completed successfully")
return ChangeResult(
ChangeStatus.SUCCESS,
f"Successfully completed: {self.my_param}",
)
except Exception as e:
self.log.error_from(self, f"Operation failed: {e}")
return ChangeResult(
ChangeStatus.FAILED,
f"Failed: {self.my_param}: {e}",
)
def undo(self) -> ChangeResult:
"""Undo the state change."""
self.log.info_from(self, f"Undoing operation for: {self.my_param}")
# Implement undo logic or return WARN if not implemented
return ChangeResult(
ChangeStatus.WARN,
f"Undo not implemented for: {self.my_param}",
)
def is_changed(self) -> bool:
"""Check if the state has already been changed."""
self.log.info_from(self, f"Checking state for: {self.my_param}")
# Return True if already in desired state, False otherwise
is_applied = False # Replace with actual check
if is_applied:
self.log.info_from(self, f"Already applied: {self.my_param}")
else:
self.log.info_from(self, f"Not yet applied: {self.my_param}")
return is_applied
devbox/state_changers/__init__.pyfrom devbox.state_changers.my_state_changer import MyStateChanger
__all__ = ["CreateOrReplaceFile", "HomeBrew", "MyStateChanger"]
devbox/container.pyfrom devbox.state_changers.my_state_changer import MyStateChanger
# In the Container class:
my_state_changer_factory = providers.Factory(
MyStateChanger,
log=log,
)
self.log.info_from(self, "message")self.log.error_from(self, "message")self.log.warn_from(self, "message")__repr____repr__ for traceable loggingClassName(key_identifier)[ClassName(id)]: messageChangeResult from change() and undo()ChangeStatus.SUCCESS - Operation completed successfullyChangeStatus.FAILED - Operation failedChangeStatus.WARN - Operation has warnings (e.g., undo not implemented)timeout_s in TargetLock based on expected operation durationFor state changers that interact with external systems (like HomeBrew), use subprocess:
import subprocess
def is_changed(self) -> bool:
result = subprocess.run(
["some-command", "check", self.my_param],
capture_output=True,
text=True,
)
return result.returncode == 0
For file operations, use pathlib:
from pathlib import Path
def is_changed(self) -> bool:
if not self.path.exists():
return False
return self.path.read_text() == self.expected_content