Errors

Modelo de erro: valores imutáveis, não exceções.

py_return_success_or_error.errors.app_error

Base opcional para os erros de domínio da aplicação.

AppError dataclass

Bases: ABC

Base abstrata para erros de domínio, modelados como valores.

Diferente de exceções, um AppError é imutável, tem igualdade por valor e trafega dentro de Failure — nunca é lançado. Cada feature declara os seus casos concretos herdando desta base e os agrupa numa união fechada::

@dataclass(frozen=True)
class Offline(AppError):
    ...

@dataclass(frozen=True)
class ConnectionTimeout(AppError):
    ...

type CheckConnectionError = Offline | ConnectionTimeout | ErrorGeneric

Herdar de AppError é conveniência, não obrigação: TError pode ser qualquer tipo. A base só fornece message, igualdade por valor e :meth:with_message.

Attributes:

Name	Type	Description
message	str	Descrição do erro.

Source code in src/py_return_success_or_error/errors/app_error.py

@dataclass(frozen=True)
class AppError(ABC):
    """Base abstrata para erros de domínio, modelados como **valores**.

    Diferente de exceções, um ``AppError`` é imutável, tem igualdade por
    valor e trafega dentro de ``Failure`` — nunca é lançado. Cada feature
    declara os seus casos concretos herdando desta base e os agrupa numa
    união fechada::

        @dataclass(frozen=True)
        class Offline(AppError):
            ...

        @dataclass(frozen=True)
        class ConnectionTimeout(AppError):
            ...

        type CheckConnectionError = Offline | ConnectionTimeout | ErrorGeneric

    Herdar de ``AppError`` é **conveniência, não obrigação**: ``TError``
    pode ser qualquer tipo. A base só fornece ``message``, igualdade por
    valor e :meth:`with_message`.

    Attributes:
        message: Descrição do erro.
    """

    message: str

    def __post_init__(self) -> None:
        if type(self) is AppError:
            raise TypeError(
                'AppError é abstrata; declare um caso concreto da feature.'
            )

    def with_message(self, message: str) -> Self:
        """Devolve uma **nova** instância com ``message`` substituída.

        Preserva o tipo concreto e os demais campos.

        Args:
            message: A nova mensagem.

        Returns:
            Nova instância do mesmo tipo concreto.
        """
        return replace(self, message=message)

with_message(message)

Devolve uma nova instância com message substituída.

Preserva o tipo concreto e os demais campos.

Parameters:

Name	Type	Description	Default
message	str	A nova mensagem.	required

Returns:

Type	Description
Self	Nova instância do mesmo tipo concreto.

Source code in src/py_return_success_or_error/errors/app_error.py

def with_message(self, message: str) -> Self:
    """Devolve uma **nova** instância com ``message`` substituída.

    Preserva o tipo concreto e os demais campos.

    Args:
        message: A nova mensagem.

    Returns:
        Nova instância do mesmo tipo concreto.
    """
    return replace(self, message=message)

py_return_success_or_error.errors.error_generic

Erro genérico pronto para o caso "inesperado".

ErrorGeneric dataclass

Bases: AppError

Caso de erro pronto para falhas inesperadas (bugs, exceções).

Inclua-o na união fechada da feature como o "caso catch-all" e devolva-o em on_unexpected/map_error quando não houver caso mais específico::

type MinhaFeatureError = RegraVioladaError | ErrorGeneric

Source code in src/py_return_success_or_error/errors/error_generic.py

@final
@dataclass(frozen=True)
class ErrorGeneric(AppError):
    """Caso de erro pronto para falhas **inesperadas** (bugs, exceções).

    Inclua-o na união fechada da feature como o "caso catch-all" e
    devolva-o em ``on_unexpected``/``map_error`` quando não houver caso
    mais específico::

        type MinhaFeatureError = RegraVioladaError | ErrorGeneric
    """

    def __str__(self) -> str:
        return f'ErrorGeneric - {self.message}'