Skip to content

castlecraft_engineer.abstractions.translator

castlecraft_engineer.abstractions.translator

TranslationError

Bases: Exception

Base exception for errors occurring during translation.

Source code in src/castlecraft_engineer/abstractions/translator.py 
8
9
class TranslationError(Exception):
    """Base exception for errors occurring during translation."""

Translator

Bases: ABC, Generic[Source, Target]

Abstract base class for a Translator. A Translator is responsible for converting an object of a source type to an object of a target type.

Source code in src/castlecraft_engineer/abstractions/translator.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
class Translator(abc.ABC, Generic[Source, Target]):
    """
    Abstract base class for a Translator.
    A Translator is responsible for converting an object of a source type
    to an object of a target type.
    """

    @abc.abstractmethod
    def translate(self, source: Source) -> Target:
        """
        Translates a source object into a target object.

        Args:
            source: The object to translate.

        Returns:
            The translated object of the target type.

        Raises:
            TranslationError: If an error occurs during translation.
        """
        raise NotImplementedError

    async def translate_async(self, source: Source) -> Target:
        """
        Asynchronously translates a source object into a target object.
        By default, this calls the synchronous translate method.
        Subclasses can override this for genuine async translation logic.

        Args:
            source: The object to translate.

        Returns:
            The translated object of the target type.

        Raises:
            TranslationError: If an error occurs during translation.
        """
        # Default implementation for convenience if the translation is inherently sync
        # but needs to be called in an async context.
        # For true async I/O bound translations, this should be overridden.
        try:
            return self.translate(source)
        except TranslationError:
            raise
        except Exception as e:
            # Wrap other exceptions to conform to the expected error type
            raise TranslationError(f"Unhandled error during translation: {e}") from e

translate(source) abstractmethod

Translates a source object into a target object.

Parameters:

Name Type Description Default
source Source

The object to translate.

 required

Returns:

Type Description
Target

The translated object of the target type.

Raises:

Type Description
TranslationError

If an error occurs during translation.
Source code in src/castlecraft_engineer/abstractions/translator.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
@abc.abstractmethod
def translate(self, source: Source) -> Target:
    """
    Translates a source object into a target object.

    Args:
        source: The object to translate.

    Returns:
        The translated object of the target type.

    Raises:
        TranslationError: If an error occurs during translation.
    """
    raise NotImplementedError

translate_async(source) async

Asynchronously translates a source object into a target object. By default, this calls the synchronous translate method. Subclasses can override this for genuine async translation logic.

Parameters:

Name Type Description Default
source Source

The object to translate.

 required

Returns:

Type Description
Target

The translated object of the target type.

Raises:

Type Description
TranslationError

If an error occurs during translation.
Source code in src/castlecraft_engineer/abstractions/translator.py 
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
async def translate_async(self, source: Source) -> Target:
    """
    Asynchronously translates a source object into a target object.
    By default, this calls the synchronous translate method.
    Subclasses can override this for genuine async translation logic.

    Args:
        source: The object to translate.

    Returns:
        The translated object of the target type.

    Raises:
        TranslationError: If an error occurs during translation.
    """
    # Default implementation for convenience if the translation is inherently sync
    # but needs to be called in an async context.
    # For true async I/O bound translations, this should be overridden.
    try:
        return self.translate(source)
    except TranslationError:
        raise
    except Exception as e:
        # Wrap other exceptions to conform to the expected error type
        raise TranslationError(f"Unhandled error during translation: {e}") from e