How to use Custom Error Messages

[hx2A]

@marcovicci @tabreturn @villares here is the info on custom error messages.

Consider this code:

def setup():
    py5.size(400, 400)
    py5.background(0)


def foo(x):
    return x / 0
    

def draw():
    py5.rect(py5.mouse_x, py5.mouse_y, 10, 10)
    
    if py5.frame_count == 300:
        py5.println(foo(10))

That should throw a ZeroDivisionError exception:

py5 encountered an error in your code:File "/tmp/ipykernel_180358/1249226541.py", line 14, in draw
    10   def draw():
    11       py5.rect(py5.mouse_x, py5.mouse_y, 10, 10)
    12       
    13       if py5.frame_count == 300:
--> 14           py5.println(foo(10))

File "/tmp/ipykernel_180358/1249226541.py", line 7, in foo
    6    def foo(x):
--> 7        return x / 0
    ..................................................
     x = 10
    ..................................................

ZeroDivisionError: division by zero

What if you want to change "division by zero" to something more helpful?

You would do this:

py5.register_exception_msg('ZeroDivisionError', "attempting to divide by zero, which a computer cannot do. try adding a check to see if the denominator is zero before dividing")

The exception becomes:

py5 encountered an error in your code:File "/tmp/ipykernel_180358/1249226541.py", line 14, in draw
    10   def draw():
    11       py5.rect(py5.mouse_x, py5.mouse_y, 10, 10)
    12       
    13       if py5.frame_count == 300:
--> 14           py5.println(foo(10))

File "/tmp/ipykernel_180358/1249226541.py", line 7, in foo
    6    def foo(x):
--> 7        return x / 0
    ..................................................
     x = 10
    ..................................................

ZeroDivisionError: attempting to divide by zero, which a computer cannot do. try adding a check to see if the denominator is zero before dividing

The second parameter to py5.register_exception_msg() doesn't have to be a string. It can also be a callable. Maybe you want your exception message to depend on Python's exception message in some way.

def handle_zerodivisionerror(exc_type_name, exc_msg, py5info):
    print(exc_type_name)
    print(exc_msg)
    print(py5info)
    
    return exc_msg

py5.register_exception_msg('ZeroDivisionError', handle_zerodivisionerror)

Now the exception becomes:

py5 encountered an error in your code:File "/tmp/ipykernel_180358/1249226541.py", line 14, in draw
    10   def draw():
    11       py5.rect(py5.mouse_x, py5.mouse_y, 10, 10)
    12       
    13       if py5.frame_count == 300:
--> 14           py5.println(foo(10))

File "/tmp/ipykernel_180358/1249226541.py", line 7, in foo
    6    def foo(x):
--> 7        return x / 0
    ..................................................
     x = 10
    ..................................................

ZeroDivisionError: division by zero

ZeroDivisionError
division by zero
[]

The callable feature is not that useful for this situation but it is needed for py5's type errors. Observe that the final py5info parameter is an empty list.

def handle_typeerror(exc_type_name, exc_msg, py5info):
    print(exc_type_name)
    print(exc_msg)
    print(py5info)
    
    return exc_msg

py5.register_exception_msg('TypeError', handle_typeerror)

Now if I change the code to this:

def setup():
    py5.size(400, 400)
    py5.background(0)


def foo(x):
    py5.stroke_weight('throw an error')
    

def draw():
    py5.rect(py5.mouse_x, py5.mouse_y, 10, 10)
    
    if py5.frame_count == 300:
        py5.println(foo(10))

The exception becomes:

py5 encountered an error in your code:File "/tmp/ipykernel_180358/662210640.py", line 15, in draw
    11   def draw():
    12       py5.rect(py5.mouse_x, py5.mouse_y, 10, 10)
    13       
    14       if py5.frame_count == 300:
--> 15           py5.println(foo(10))

File "/tmp/ipykernel_180358/662210640.py", line 7, in foo
    6    def foo(x):
--> 7        py5.stroke_weight('throw an error')
    8        return x / 0

TypeError: No matching overloads found for processing.core.PApplet.strokeWeight(str), options are:
	public void processing.core.PApplet.strokeWeight(float)


TypeError
No matching overloads found for processing.core.PApplet.strokeWeight(str), options are:
	public void processing.core.PApplet.strokeWeight(float)


[(('__init__.py',), 'stroke_weight'), (('sketch.py',), 'stroke_weight')]

You can see this is JPype's Java exception. We want to present the user with an exception that makes more sense to a Python programmer. The final py5info parameter contains info from the call stack that py5 can use to figure out the correct signature for the method that triggered the exception.

py5 encountered an error in your code:File "/tmp/ipykernel_181414/662210640.py", line 15, in draw
    11   def draw():
    12       py5.rect(py5.mouse_x, py5.mouse_y, 10, 10)
    13       
    14       if py5.frame_count == 300:
--> 15           py5.println(foo(10))

File "/tmp/ipykernel_181414/662210640.py", line 7, in foo
    6    def foo(x):
--> 7        py5.stroke_weight('throw an error')
    8        return x / 0

TypeError: The parameter types (str) are invalid for method stroke_weight.
Your parameters must match the following signature:
 * stroke_weight(weight: float, /) -> None

The code for that is in py5/custom_exceptions.py. Make note of py5.reference.METHOD_SIGNATURES_LOOKUP, which is a dict containing metadata that py5 uses for information about itself.

Finally, py5 will by default remove its own nonsense from the stack trace. If you want to turn that off, you do that with this:

py5.prune_tracebacks(False)

[tabreturn]

Thanks, @hx2A. That's a great explanation (something to even include in the advanced tutorials)?

[hx2A]

You are welcome! Yes, I can repurpose this into a tutorial. I think it would be most helpful for educators who want to provide specialized help for their students, kind of like p5's friendly error system.