Handle None vs NotImplemented correctly in decompose protocol

[daxfohl]

Handle None return values consistently with other protocols, to mean that any fallback option should be skipped (xref #1655). This allows us to remove the redundant implementations and eliminate redundant executions of the same logic during decomposition, as well as prevent potential bugs where an important aspect of the context could be ignored.

Fixes #7535

Additionally fixes #7384 since DecompositionContext is never None anymore after the removal of the redundant implementations.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.50%. Comparing base (c7f10ac) to head (c6e836f).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #7553      +/-   ##
==========================================
- Coverage   97.50%   97.50%   -0.01%     
==========================================
  Files        1103     1103              
  Lines       99640    99661      +21     
==========================================
+ Hits        97154    97174      +20     
- Misses       2486     2487       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[dstrain115]

I suppose this is fine, but does it change any behavior? I am a bit worried since decompose is very sensitive to some workflows, so I want to be sure we are not messing anyone up or causing backwards incompatibilities.

[daxfohl]

It doesn't change behavior of any of the gates in cirq; it just prevents cirq from executing the same decomposition handlers twice unnecessarily. For gates defined outside of cirq, it would only change behavior if the gate had a _decompose_with_context_ that returns None and also has a _decompose_ that is expected to handle cases where _decompose_with_context_ returns None. That seems like a weird way to implement anything, but, Hyrum's Law.

In such a case, the simplest fix would be to change that gate's _decompose_with_context_ to return NotImplemented instead of None, since NotImplemented preserves the fallback behavior.

[daxfohl]

The last commit also updated the type signatures of the handler functions since DecompositionContext is never None anymore (fixing #7384). It did not change any logic.