Qual exceção devo criar em combinações de argumentos ruins / ilegais no Python?

Eu estava pensando sobre as melhores práticas para indicar combinações de argumentos inválidos em Python. Eu me deparei com algumas situações em que você tem uma função assim:

def import_to_orm(name, save=False, recurse=False):
    """
    :param name: Name of some external entity to import.
    :param save: Save the ORM object before returning.
    :param recurse: Attempt to import associated objects as well. Because you
        need the original object to have a key to relate to, save must be
        `True` for recurse to be `True`.
    :raise BadValueError: If `recurse and not save`.
    :return: The ORM object.
    """
    pass

O único incômodo com isso é que cada pacote tem o seu, geralmente um pouco diferente BadValueError. Eu sei que em Java existe java.lang.IllegalArgumentException- é bem entendido que todos estarão criando seus próprios BadValueErrors em Python ou existe outro método preferido?

Eu apenas aumentaria ValueError , a menos que você precise de uma exceção mais específica.

def import_to_orm(name, save=False, recurse=False):
    if recurse and not save:
        raise ValueError("save must be True if recurse is True")

Não há realmente sentido em fazer class BadValueError(ValueError):pass- sua classe personalizada é idêntica em uso ao ValueError , então por que não usar isso?

Eu herdaria de ValueError

class IllegalArgumentError(ValueError):
    pass

Às vezes, é melhor criar suas próprias exceções, mas herdar de uma embutida, o mais próximo possível do que você deseja.

Se você precisar capturar esse erro específico, é útil ter um nome.

Eu acho que a melhor maneira de lidar com isso é a maneira como o próprio python lida com isso. Python gera um TypeError. Por exemplo:

$ python -c 'print(sum())'
Traceback (most recent call last):
File "<string>", line 1, in <module>
TypeError: sum expected at least 1 arguments, got 0

Nosso desenvolvedor júnior acabou de encontrar esta página em uma pesquisa no google por "argumentos errados de exceção de python" e estou surpreso que a resposta óbvia (para mim) nunca tenha sido sugerida na década desde que essa pergunta foi feita.

Acabei de ver o componente ValueErrorusado nessa situação.

Depende de qual é o problema com os argumentos.

Se o argumento tiver o tipo errado, aumente um TypeError. Por exemplo, quando você obtém uma string em vez de um desses booleanos.

if not isinstance(save, bool):
    raise TypeError(f"Argument save must be of type bool, not {type(save)}")

Note, no entanto, que no Python raramente fazemos verificações como essa. Se o argumento for realmente inválido, alguma função mais profunda provavelmente fará a reclamação por nós. E se verificarmos apenas o valor booleano, talvez algum usuário de código mais tarde a alimente com uma string sabendo que as strings não vazias são sempre True. Isso pode lhe salvar um elenco.

Se os argumentos tiverem valores inválidos, aumente ValueError. Isso parece mais apropriado no seu caso:

if recurse and not save:
    raise ValueError("If recurse is True, save should be True too")

Ou, nesse caso específico, ter um valor True de recurse implica um valor True de save. Como eu consideraria isso uma recuperação de um erro, você também pode reclamar no log.

if recurse and not save:
    logging.warning("Bad arguments in import_to_orm() - if recurse is True, so should save be")
    save = True

Eu não sei se concordo com a herança de ValueError- minha interpretação da documentação é que ValueErroré única deveria ser levantada por builtins ... herdar a partir dele ou elevando-se parece incorreta.

Gerado quando uma operação ou função interna recebe um argumento que tem o tipo certo, mas um valor inadequado, e a situação não é descrita por uma exceção mais precisa, como IndexError.

- documentação ValueError

Concorde com a sugestão de Markus de lançar sua própria exceção, mas o texto da exceção deve esclarecer que o problema está na lista de argumentos, não nos valores individuais dos argumentos. Eu proporia:

class BadCallError(ValueError):
    pass

Usado quando faltam argumentos de palavra-chave necessários para a chamada específica ou valores de argumento individualmente válidos, mas inconsistentes entre si. ValueErrorainda estaria certo quando um argumento específico é do tipo certo, mas está fora do intervalo.

Isso não deveria ser uma exceção padrão no Python?

Em geral, eu gostaria que o estilo Python fosse um pouco mais preciso ao distinguir entradas ruins de uma função (falha do chamador) e resultados ruins dentro da função (minha falha). Portanto, também pode haver um BadArgumentError para distinguir erros de valor nos argumentos dos erros de valor nos locais.