PR #1527: Clearer Errors When Misusing Guppy Objects in comptime()

Today, I wanted to share another Quantinuum Guppy contribution: improving error messages when developers misuse compile-time evaluation.

The problem: When developers tried to call Guppy functions or types inside comptime() (which evaluates as plain Python), they’d get a raw Python traceback with a generic message like “Type angle may only be called in a Guppy context.” This gave no guidance on what was actually wrong or how to fix it.

The root cause: Guppy’s error handling system was being overridden during compile-time evaluation, causing proper error messages to be replaced with raw Python exceptions.

The fix: In PR #1527, I added a dedicated error diagnostic that clearly explains the problem: “Cannot use a Guppy object in a comptime expression.” The error now includes helpful context explaining that comptime expressions are evaluated as plain Python, and Guppy functions/types require a Guppy context. I also fixed the exception handling to preserve Guppy’s error formatting.

Why this matters: Good error messages can mean the difference between fixing a bug in 5 minutes versus spending hours trying to understand what went wrong. When developers are learning the distinction between compile-time Python code and runtime quantum code, clear error messages help them build the right mental model faster.

As always, I appreciate the Guppy contributors at Quantinuum for their help and collaboration.

For more technical details, refer to PR #1527.