Custom Stages

Create custom stages by subclassing Stage and registering with the registry.

Creating a Stage

from uptimer.stages.base import Stage, CheckResult, Status
from uptimer.stages.registry import register_stage


@register_stage
class MyStage(Stage):
    """My custom stage."""

    name = "my-stage"
    description = "My custom health check"

    def check(self, url: str, verbose: bool = False) -> CheckResult:
        """Perform the check."""
        # Your check logic here
        return CheckResult(
            status=Status.UP,
            url=url,
            message="OK",
            elapsed_ms=100.0,
            details={"custom": "data"},
        )

Stage Base Class

Stage

Bases: ABC

Base class for all stages.

Source code in src/uptimer/stages/base.py

class Stage(ABC):
    """Base class for all stages."""

    name: str = "base"
    description: str = "Base stage"

    # Whether this stage makes HTTP requests (vs transforms data)
    is_network_stage: bool = True

    @abstractmethod
    def check(self, url: str, verbose: bool = False, context: CheckContext | None = None) -> CheckResult:
        """Perform the check and return result.

        Args:
            url: URL to check
            verbose: Whether to include verbose output
            context: Optional context from previous stages

        Returns:
            CheckResult with status, message, and details
        """
        pass

Functions

check(url, verbose=False, context=None) abstractmethod

Perform the check and return result.

Parameters:

Name	Type	Description	Default
url	str	URL to check	required
verbose	bool	Whether to include verbose output	False
context	CheckContext | None	Optional context from previous stages	None

Returns:

Type	Description
CheckResult	CheckResult with status, message, and details

Source code in src/uptimer/stages/base.py

@abstractmethod
def check(self, url: str, verbose: bool = False, context: CheckContext | None = None) -> CheckResult:
    """Perform the check and return result.

    Args:
        url: URL to check
        verbose: Whether to include verbose output
        context: Optional context from previous stages

    Returns:
        CheckResult with status, message, and details
    """
    pass

CheckResult

CheckResult dataclass

Result of a check.

Source code in src/uptimer/stages/base.py

@dataclass
class CheckResult:
    """Result of a check."""

    status: Status
    url: str
    message: str
    elapsed_ms: float = 0.0
    details: dict[str, Any] = field(default_factory=lambda: {})

Status Enum

Status

Bases: Enum

Check result status.

Source code in src/uptimer/stages/base.py

class Status(Enum):
    """Check result status."""

    UP = "up"
    DEGRADED = "degraded"
    DOWN = "down"

Registry Functions

register_stage

Register a stage class with the registry.

from uptimer.stages.registry import register_stage

@register_stage
class MyStage(Stage):
    ...

get_stage

Get a stage class by name.

from uptimer.stages.registry import get_stage

stage_class = get_stage("http")
stage = stage_class()
result = stage.check("https://example.com")

list_stages

List all registered stage names.

from uptimer.stages.registry import list_stages

names = list_stages()  # ["http", "my-stage"]