¿Qué excepción debo plantear en combinaciones de argumentos malos / ilegales en Python?

Me preguntaba sobre las mejores prácticas para indicar combinaciones de argumentos no válidos en Python. Me he encontrado con algunas situaciones en las que tienes una función como esta:

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

La única molestia con esto es que cada paquete tiene el suyo, generalmente ligeramente diferente BadValueError. Sé que en Java existe java.lang.IllegalArgumentException, ¿se entiende bien que todos crearán sus propios BadValueErrors en Python o hay otro método preferido?

Simplemente aumentaría ValueError , a menos que necesite una excepción más 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")

Realmente no tiene sentido hacerlo class BadValueError(ValueError):pass: su clase personalizada es idéntica en uso a ValueError , entonces, ¿por qué no usar eso?

Yo heredaría de ValueError

class IllegalArgumentError(ValueError):
    pass

A veces es mejor crear sus propias excepciones, pero heredar de uno incorporado, que es lo más parecido posible a lo que desea.

Si necesita detectar ese error específico, es útil tener un nombre.

Creo que la mejor manera de manejar esto es la forma en que Python lo maneja. Python plantea un TypeError. Por ejemplo:

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

Nuestro desarrollador junior acaba de encontrar esta página en una búsqueda en Google de "argumentos erróneos de excepción de Python" y me sorprende que la respuesta obvia (para mí) nunca se sugirió en la década desde que se hizo esta pregunta.

Sobre todo acabo de ver el builtin ValueErrorutilizado en esta situación.

Depende de cuál sea el problema con los argumentos.

Si el argumento tiene el tipo incorrecto, genere un TypeError. Por ejemplo, cuando obtienes una cadena en lugar de uno de esos booleanos.

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

Sin embargo, tenga en cuenta que en Python rara vez hacemos verificaciones como esta. Si el argumento realmente no es válido, alguna función más profunda probablemente se quejará por nosotros. Y si solo verificamos el valor booleano, tal vez algún usuario de código luego lo alimente con una cadena sabiendo que las cadenas no vacías son siempre verdaderas. Podría ahorrarle un yeso.

Si los argumentos tienen valores no válidos, aumente ValueError. Esto parece más apropiado en su caso:

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

O en este caso específico, tener un valor Verdadero de recurrencia implica un valor Verdadero de guardar. Como consideraría esto una recuperación de un error, es posible que también desee quejarse en el registro.

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

No estoy seguro estoy de acuerdo con la herencia de ValueError- mi interpretación de la documentación es que ValueErrorse sólo se supone para ser criados por órdenes internas ... heredando de o elevándola a sí mismo parece incorrecta.

Se genera cuando una operación o función incorporada recibe un argumento que tiene el tipo correcto pero un valor inapropiado, y la situación no se describe con una excepción más precisa como IndexError.

- Documentación de ValueError

De acuerdo con la sugerencia de Markus de lanzar su propia excepción, pero el texto de la excepción debería aclarar que el problema está en la lista de argumentos, no en los valores de los argumentos individuales. Yo propondría:

class BadCallError(ValueError):
    pass

Se usa cuando faltan argumentos de palabras clave que fueron necesarios para la llamada específica, o los valores de argumento son válidos individualmente pero inconsistentes entre sí. ValueErrorseguiría siendo correcto cuando un argumento específico es del tipo correcto pero está fuera de rango.

¿No debería ser esta una excepción estándar en Python?

En general, me gustaría que el estilo de Python sea un poco más preciso al distinguir las entradas incorrectas de una función (culpa del llamante) de los malos resultados dentro de la función (mi culpa). Por lo tanto, también puede haber un BadArgumentError para distinguir los errores de valor en los argumentos de los errores de valor en los locales.