Deriving BaseException for custom error enums

[ChristopherRabotin]

Hi there,

My library is used both in Rust and in Python, so many functions return, e.g., Result<f64, EpochError>. In Rust, the errors use the snafu crate. For Python, PyO3 converts the EpochError directly into an exception (because EpochError has a convert impl to PyErr). So far, so good.

However, in Python, the only way to catch an error from my library is with a generic try/except, e.g.:

try:
    Epoch("2024-05-32 00:00:00")
except Exception as e: # Bare
    print(e)

This works, but idiomatic Python recommends that a specific exception be caught instead of just Exception.

Is there a way to derive BaseException for my EpochError enum? I tried using create_exception but that creates a string based exception, which would require me to drop snafu entirely, and more generally to drop the ability to handle custom errors in the same way in Python and in Rust. Is my only alternative to implement from_object_raw as is done in the create_exception macro?

Thanks

[ChristopherRabotin]

I don't think that just implementing that function is sufficient.

impl DurationError {
    fn type_object_raw(py: Python<'_>) -> *mut PyTypeObject {
        static TYPE_OBJECT: GILOnceCell<Py<PyType>> = GILOnceCell::new();

        TYPE_OBJECT
            .get_or_init(py, || {
                PyErr::new_type_bound(
                    py,
                    "hifitime.DurationError",
                    Some("mydoc"),
                    Some(&py.get_type_bound::<DurationError>()),
                    None,
                )
                .expect("Failed to initialize new exception type.")
            })
            .as_ptr() as *mut PyTypeObject
    }
}

#[pymethods]
impl Duration {
    fn test_raise(&self) -> Result<(), DurationError> {
        Err(DurationError::Overflow)
    }
}

>>> from hifitime import Duration, DurationError
>>> Duration.MIN().test_raise
<built-in method test_raise of hifitime.Duration object at 0x7f0dcd2fdda0>
>>> Duration.MIN().test_raise()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
Exception: Overflow
>>> try:
...  Duration.MIN().test_raise()
... except DurationError as e:
...  print(e)
... 
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
Exception: Overflow

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "<stdin>", line 3, in <module>
TypeError: catching classes that do not inherit from BaseException is not allowed
>>> 

[Icxolu]

I think you want to expose a custom exception type and use that while converting you library error into PyErr. Perhaps you can do something like this:

// your library error type
pub enum EpochError { ... }

// The exception type that gets exposed to Python
// alternativly the `create_exception!` macro should also work
#[pyclass]
#[pyo3(name = "EpochError", extends = PyBaseException)] // or PyException
pub struct PyEpochError {}

#[pymethods]
impl PyEpochError {
    #[new]
    #[pyo3(signature = (*_args, **_kwargs))]
    fn new(_args: Bound<'_, PyTuple>, _kwargs: Option<Bound<'_, PyDict>>) -> Self {
        Self {}
    }
}

// convert you library error into a PyErr using the custom exception type
impl From<EpochError> for PyErr {
    fn from(value: EpochError) -> Self {
       // example: use the display impl as error msg
       PyErr::new::<PyEpochError, _>(value.to_string())
    }
}

This should allow you to catch the specific exception from Python

try:
    some_function_that_raises_epoch_error()
except EpochError:
    pass

PyException should be used for normal Python exceptions, since it can be caught by using except Exception. PyBaseException is meant for more fatal errors and is an indication that the program should exit (for example pyo3s PanicException).

[ChristopherRabotin]

Excellent, thank you, that worked exactly as I was hoping!

[austin362667]

This is a super to-the-point answer, thank you two!

[ChristopherRabotin]

One small change I made: Instead of #[pyo3(name = "EpochError", extends = PyBaseException)], I extended PyException directly, as #[pyo3(name = "EpochError", extends = PyException)]. This is because from what I can tell PyException is a super class of PyBaseException, so my custom errors could not be caught with Python's standard except Exception and had to be caught with except BaseException.

The fix is here nyx-space/hifitime#315.

[austin362667]

Thanks! That's helpful.

[Icxolu]

Yep, it's generally advisable to subclass PyException. I only used PyBaseException in the example because it was mentioned in the question. I put a short note in my answer above.