Skip to content

Presenter Contract

presenter_contract

Presentation adapter contract for the ForgingBlocks framework.

Defines PresenterPort, the structural protocol that every presentation
adapter must satisfy. In hexagonal-architecture terms it is the primary port
through which the application delivers its output to the outside world.

Responsibilities
  • Define a uniform contract for presenting application responses.
  • Define a uniform contract for presenting application errors.
  • Remain free of any transport or rendering concern.
Non-Responsibilities
  • Rendering to a specific medium (HTML, JSON, terminal, etc.).
  • Transport or I/O logic.
  • Parsing or validating user input.

PresenterPort

Bases: InboundPort[ResponseType, None], Protocol

Structural protocol for presentation adapters.

A PresenterPort receives an application response and renders it
to the outside world. It also provides a dedicated method for
presenting errors so that implementations can apply consistent
formatting.

Class Type Parameters:

Name Bound or Constraints Description Default
ResponseType

The type of the response object produced by the
application layer (use case / query handler).

 required

Example::

class CliPresenter(PresenterPort[MyUseCaseOutput]):
    def present(self, response: MyUseCaseOutput) -> None:
        print(f"Result: {response.summary}")

    def present_error(self, error: object) -> None:
        print(f"Error: {error}", file=sys.stderr)
Source code in src/forging_blocks/presentation/presenter_contract.py 
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
60
61
62
63
64
65
66
67
68
69
70
71
72
@runtime_checkable
class PresenterPort[ResponseType](InboundPort[ResponseType, None], Protocol):
    """Structural protocol for presentation adapters.

    A ``PresenterPort`` receives an application response and renders it
    to the outside world. It also provides a dedicated method for
    presenting errors so that implementations can apply consistent
    formatting.

    Type Parameters:
        ResponseType: The type of the response object produced by the
            application layer (use case / query handler).

    Example::

        class CliPresenter(PresenterPort[MyUseCaseOutput]):
            def present(self, response: MyUseCaseOutput) -> None:
                print(f"Result: {response.summary}")

            def present_error(self, error: object) -> None:
                print(f"Error: {error}", file=sys.stderr)
    """

    def present(self, response: ResponseType) -> None:
        """Render a successful application response.

        Args:
            response: The response object produced by the application
                layer after a successful operation.

        Notes:
            Implementations must not raise exceptions from this method
            for normal error handling — use ``present_error`` for that.
        """
        ...

    def present_error(self, error: object) -> None:
        """Render an application-level error.

        Args:
            error: An error object — may be a framework ``Error``, a
                ``Result.Err``, a plain ``Exception``, or any other
                error representation the application produces.

        Notes:
            This method exists so that error formatting is a first-class
            concern of the presentation contract, rather than being
            handled via exceptions or ad-hoc logic.
        """
        ...

present(response: ResponseType) -> None

Render a successful application response.

Parameters:

Name Type Description Default
response ResponseType

The response object produced by the application
layer after a successful operation.

 required
Notes

Implementations must not raise exceptions from this method
for normal error handling — use present_error for that.

Source code in src/forging_blocks/presentation/presenter_contract.py 
46
47
48
49
50
51
52
53
54
55
56
57
def present(self, response: ResponseType) -> None:
    """Render a successful application response.

    Args:
        response: The response object produced by the application
            layer after a successful operation.

    Notes:
        Implementations must not raise exceptions from this method
        for normal error handling — use ``present_error`` for that.
    """
    ...

present_error(error: object) -> None

Render an application-level error.

Parameters:

Name Type Description Default
error object

An error object — may be a framework Error, a
Result.Err, a plain Exception, or any other
error representation the application produces.

 required
Notes

This method exists so that error formatting is a first-class
concern of the presentation contract, rather than being
handled via exceptions or ad-hoc logic.

Source code in src/forging_blocks/presentation/presenter_contract.py 
59
60
61
62
63
64
65
66
67
68
69
70
71
72
def present_error(self, error: object) -> None:
    """Render an application-level error.

    Args:
        error: An error object — may be a framework ``Error``, a
            ``Result.Err``, a plain ``Exception``, or any other
            error representation the application produces.

    Notes:
        This method exists so that error formatting is a first-class
        concern of the presentation contract, rather than being
        handled via exceptions or ad-hoc logic.
    """
    ...