Utility

This module contains various objects needed in the rest of the algobattle package. In particular, the exception classes and the Encodable base classes.

algobattle.util.Role

Bases: StrEnum

Indicates whether the role of a program is to generate or to solve instances.

Source code in src/algobattle/util.py

class Role(StrEnum):
    """Indicates whether the role of a program is to generate or to solve instances."""

    generator = "generator"
    solver = "solver"

algobattle.util.BaseModel

Bases: BaseModel

Base class for all pydantic models.

Source code in src/algobattle/util.py

class BaseModel(PydandticBaseModel):
    """Base class for all pydantic models."""

    model_config = ConfigDict(extra="forbid", from_attributes=True, hide_input_in_errors=True)

algobattle.util.Encodable

Bases: EncodableBase, ABC

Represents data that docker containers can interact with.

Source code in src/algobattle/util.py

class Encodable(EncodableBase, ABC):
    """Represents data that docker containers can interact with."""

    @classmethod
    @abstractmethod
    def decode(cls, source: Path, max_size: int, role: Role) -> Self:
        """Decodes the data found at the given path into a python object.

        Args:
            source: Path to data that can be used to construct an instance of this class. May either point to a folder
                or a single file. The expected type of path should be consistent with the result of :meth:`.encode`.
            max_size: Maximum size the current battle allows.
            role: Role of the program that generated this data.

        Raises:
            EncodingError: If the data cannot be decoded into an instance.

        Returns:
            The decoded object.
        """
        raise NotImplementedError

decode(source, max_size, role) abstractmethod classmethod

Decodes the data found at the given path into a python object.

Parameters:

Name	Type	Description	Default
source	Path	Path to data that can be used to construct an instance of this class. May either point to a folder or a single file. The expected type of path should be consistent with the result of :meth:.encode.	required
max_size	int	Maximum size the current battle allows.	required
role	Role	Role of the program that generated this data.	required

Raises:

Type	Description
EncodingError	If the data cannot be decoded into an instance.

Returns:

Type	Description
Self	The decoded object.

Source code in src/algobattle/util.py

@classmethod
@abstractmethod
def decode(cls, source: Path, max_size: int, role: Role) -> Self:
    """Decodes the data found at the given path into a python object.

    Args:
        source: Path to data that can be used to construct an instance of this class. May either point to a folder
            or a single file. The expected type of path should be consistent with the result of :meth:`.encode`.
        max_size: Maximum size the current battle allows.
        role: Role of the program that generated this data.

    Raises:
        EncodingError: If the data cannot be decoded into an instance.

    Returns:
        The decoded object.
    """
    raise NotImplementedError

algobattle.util.EncodableModel

Bases: EncodableModelBase, ABC

Problem data that can easily be encoded into and decoded from json files.

Source code in src/algobattle/util.py

class EncodableModel(EncodableModelBase, ABC):
    """Problem data that can easily be encoded into and decoded from json files."""

    @classmethod
    def decode(cls, source: Path, max_size: int, role: Role) -> Self:
        """Uses pydantic to create a python object from a `.json` file."""
        return cls._decode(cls, source, max_size=max_size, role=role)

decode(source, max_size, role) classmethod

Uses pydantic to create a python object from a .json file.

Source code in src/algobattle/util.py

@classmethod
def decode(cls, source: Path, max_size: int, role: Role) -> Self:
    """Uses pydantic to create a python object from a `.json` file."""
    return cls._decode(cls, source, max_size=max_size, role=role)

algobattle.util.AlgobattleBaseException

Bases: Exception

Base exception class for errors used by the algobattle package.

Source code in src/algobattle/util.py

class AlgobattleBaseException(Exception):
    """Base exception class for errors used by the algobattle package."""

    def __init__(
        self,
        message: LiteralString,
        *,
        detail: str | list[str] | list[dict[str, Any]] | None = None,
    ) -> None:
        """Base exception class for errors used by the algobattle package.

        Args:
            message: Simple error message that can always be displayed.
            detail: More detailed error message that may include sensitive information.
        """
        self.message = message
        self.detail = detail
        super().__init__()

__init__(message, *, detail=None)

Base exception class for errors used by the algobattle package.

Parameters:

Name	Type	Description	Default
message	LiteralString	Simple error message that can always be displayed.	required
detail	str | list[str] | list[dict[str, Any]] | None	More detailed error message that may include sensitive information.	None

Source code in src/algobattle/util.py

def __init__(
    self,
    message: LiteralString,
    *,
    detail: str | list[str] | list[dict[str, Any]] | None = None,
) -> None:
    """Base exception class for errors used by the algobattle package.

    Args:
        message: Simple error message that can always be displayed.
        detail: More detailed error message that may include sensitive information.
    """
    self.message = message
    self.detail = detail
    super().__init__()

algobattle.util.EncodingError

Bases: AlgobattleBaseException

Indicates that the given data could not be encoded or decoded properly.

Source code in src/algobattle/util.py

class EncodingError(AlgobattleBaseException):
    """Indicates that the given data could not be encoded or decoded properly."""

algobattle.util.ValidationError

Bases: AlgobattleBaseException

Indicates that the decoded problem instance or solution is invalid.

Source code in src/algobattle/util.py

class ValidationError(AlgobattleBaseException):
    """Indicates that the decoded problem instance or solution is invalid."""

algobattle.util.BuildError

Bases: AlgobattleBaseException

Indicates that the build process could not be completed successfully.

Source code in src/algobattle/util.py

class BuildError(AlgobattleBaseException):
    """Indicates that the build process could not be completed successfully."""

algobattle.util.ExecutionError

Bases: AlgobattleBaseException

Indicates that the program could not be executed successfully.

Source code in src/algobattle/util.py

class ExecutionError(AlgobattleBaseException):
    """Indicates that the program could not be executed successfully."""

    def __init__(
        self, message: LiteralString, *, detail: str | None = None, runtime: float
    ) -> None:
        """Indicates that the program could not be executed successfully.

        Args:
            message: Simple error message that can always be displayed.
            runtime: Runtime of the program in seconds until the error occured.
            detail: More detailed error message that may include sensitive information.
        """
        self.runtime = runtime
        super().__init__(message, detail=detail)

__init__(message, *, detail=None, runtime)

Indicates that the program could not be executed successfully.

Parameters:

Name	Type	Description	Default
message	LiteralString	Simple error message that can always be displayed.	required
runtime	float	Runtime of the program in seconds until the error occured.	required
detail	str | None	More detailed error message that may include sensitive information.	None

Source code in src/algobattle/util.py

def __init__(
    self, message: LiteralString, *, detail: str | None = None, runtime: float
) -> None:
    """Indicates that the program could not be executed successfully.

    Args:
        message: Simple error message that can always be displayed.
        runtime: Runtime of the program in seconds until the error occured.
        detail: More detailed error message that may include sensitive information.
    """
    self.runtime = runtime
    super().__init__(message, detail=detail)

algobattle.util.ExecutionTimeout

Bases: ExecutionError

Indicates that the program ran into the timeout.

Source code in src/algobattle/util.py

class ExecutionTimeout(ExecutionError):
    """Indicates that the program ran into the timeout."""

algobattle.util.DockerError

Bases: AlgobattleBaseException

Indicates that an issue with the docker daemon occured.

Source code in src/algobattle/util.py

class DockerError(AlgobattleBaseException):
    """Indicates that an issue with the docker daemon occured."""

algobattle.util.ExceptionInfo

Bases: BaseModel

Details about an exception that was raised.

Source code in src/algobattle/util.py

class ExceptionInfo(BaseModel):
    """Details about an exception that was raised."""

    type: str
    message: str
    detail: str | list[str] | list[dict[str, Any]] | None = None

    @classmethod
    def from_exception(cls, error: Exception) -> Self:
        """Constructs an instance from a raised exception."""
        if isinstance(error, AlgobattleBaseException):
            return cls(
                type=error.__class__.__name__,
                message=error.message,
                detail=error.detail,
            )
        elif isinstance(error, PydanticValidationError):
            return cls(
                type=error.__class__.__name__,
                message=str(error),
                detail=str(error.errors(include_input=True, include_url=False)),
            )
        else:
            return cls(
                type=error.__class__.__name__,
                message="Unknown exception occurred.",
                detail=format_exception(error),
            )

from_exception(error) classmethod

Constructs an instance from a raised exception.

Source code in src/algobattle/util.py

@classmethod
def from_exception(cls, error: Exception) -> Self:
    """Constructs an instance from a raised exception."""
    if isinstance(error, AlgobattleBaseException):
        return cls(
            type=error.__class__.__name__,
            message=error.message,
            detail=error.detail,
        )
    elif isinstance(error, PydanticValidationError):
        return cls(
            type=error.__class__.__name__,
            message=str(error),
            detail=str(error.errors(include_input=True, include_url=False)),
        )
    else:
        return cls(
            type=error.__class__.__name__,
            message="Unknown exception occurred.",
            detail=format_exception(error),
        )