Dominando Exceções Customizadas em Python: Guia Prático

Exceções Customizadas em Python

Neste tutorial, você aprenderá como definir exceções personalizadas adaptadas às suas necessidades, ilustradas com exemplos práticos.

Python fornece muitas exceções built-in que sinalizam erros quando programa encontra condições inesperadas. No entanto, há momentos em que as built-ins não descrevem precisamente o problema encontrado. Nesses casos, você pode criar seus próprios tipos de exceção customizados para tornar código mais claro e fácil de manter.

Criando Exceções Customizadas

Definir exceção customizada em Python é direto: crie nova classe que herde da built-in Exception (ou uma de suas subclasses). A maioria das exceções padrão deriva de Exception, então sua classe customizada integrará perfeitamente com sistema de tratamento de erros do Python.

> >>> class CustomError(Exception):
...     pass
...
> >>> raise CustomError
Traceback (most recent call last):
... __main__.CustomError
> >>> raise CustomError("An error occurred")
Traceback (most recent call last):
... __main__.CustomError: An error occurred

Aqui, CustomError é exceção user-defined que herda de Exception. Pode ser levantada com raise e mensagem opcional. Em projetos grandes, prática comum é colocar todas exceções customizadas em módulo dedicado (ex.: exceptions.py ou errors.py) para fácil localização e manutenção.

Exemplo: Exceção User-Defined em Python

O programa a seguir demonstra como exceções customizadas podem guiar entrada do usuário. Ele solicita repetidamente número até adivinhar valor armazenado. Programa dá dica — se palpite muito alto ou baixo — levantando exceção personalizada.

# define exceções user-defined Python
class Error(Exception):
    """Classe base para outras exceções"""
    pass
class ValueTooSmallError(Error):
    """Levantada quando valor de entrada é muito pequeno"""
    pass
class ValueTooLargeError(Error):
    """Levantada quando valor de entrada é muito grande"""
    pass
# número alvo
number = 10
# continuar perguntando até acertar
while True:
    try:
        i_num = int(input("Enter a number: "))
        if i_num < number:
            raise ValueTooSmallError
        elif i_num > number:
            raise ValueTooLargeError
        break
    except ValueTooSmallError:
        print("This value is too small, try again!")
        print()
    except ValueTooLargeError:
        print("This value is too large, try again!")
        print()
print("Congratulations! You guessed it correctly.")

Execução de exemplo:

Enter a number: 12 This value is too large, try again! Enter a number: 0 This value is too small, try again! Enter a number: 8 This value is too small, try again! Enter a number: 10 Congratulations! You guessed it correctly.

Neste exemplo, classe base Error fornece ancestral comum para dois tipos de erro específicos. Essa abordagem mantém hierarquia de exceções clara e permite capturar todos erros relacionados com único except Error se desejado.

Personalizando Classes de Exceção

Exceções customizadas também podem armazenar dados adicionais ou apresentar mensagens mais informativas. Isso requer sobrescrever __init__ e opcionalmente __str__. O seguinte ilustra cenário de validação de salário.

class SalaryNotInRangeError(Exception):
    """Exceção levantada para erros no salário de entrada.
    Attributes:
        salary -- salário de entrada que causou erro
        message -- explicação do erro
    """
    def __init__(self, salary, message="Salary is not in (5000, 15000) range"):
        self.salary = salary
        self.message = message
        super().__init__(self.message)
salary = int(input("Enter salary amount: "))
if not 5000 < salary < 15000:
    raise SalaryNotInRangeError(salary)

Saída

Enter salary amount: 2000 Traceback (most recent call last): File "<string>", line 17, in <module> raise SalaryNotInRangeError(salary) __main__.SalaryNotInRangeError: Salary is not in (5000, 15000) range

Ao sobrescrever __init__, exceção pode carregar valor ofensivo. Se quiser representação string customizada, sobrescreva __str__ como mostrado abaixo:

class SalaryNotInRangeError(Exception):
    """Exceção levantada para erros no salário de entrada.
    Attributes:
        salary -- salário de entrada que causou erro
        message -- explicação do erro
    """
    def __init__(self, salary, message="Salary is not in (5000, 15000) range"):
        self.salary = salary
        self.message = message
        super().__init__(self.message)
    def __str__(self):
        return f'{self.salary} → {self.message}'
salary = int(input("Enter salary amount: "))
if not 5000 < salary < 15000:
    raise SalaryNotInRangeError(salary)

Saída

Enter salary amount: 2000 Traceback (most recent call last): File "/home/user/untitled.py", line 20, in <module> raise SalaryNotInRangeError(salary) __main__.SalaryNotInRangeError: 2000 → Salary is not in (5000, 15000) range

Para aprofundamento em padrões de tratamento de exceções, consulte Python Exception Handling.

Para aprender mais sobre design de aplicações robustas, explore Python Object-Oriented Programming.