revert: Restore deprecated tket-py definitions removed in #1975 (#1978)

#1975 removed two deprecated public symbols from `tket-py`, breaking
downstream users before a deprecation cycle had run its course. This
restores them while keeping that PR's non-breaking drive-by fixes.

### Restored
- `tket.passes.NormalizeGuppy` — deprecated alias of `Normalize`, plus
its `__all__` entry and `test_normalize_guppy_deprecated_alias`.
- `tket.metadata.PytketPhaseExpr` — deprecated metadata key
(`TKET1.phase`), plus its `__all__` entry.

```python
from tket.passes import NormalizeGuppy  # DeprecationWarning: Use `Normalize` instead.
from tket.metadata import PytketPhaseExpr
```

### Kept from #1975
- Doc-example fixes and the added `ExpectedQubitsHint` entry in
`tket.metadata.__all__`.

### Notes
- The `_QSystemLLVMPass` → `QSystemLLVMPass` rename listed in #1975's
description was never actually applied in code, so there is nothing to
revert there.
- Unrelated pre-existing nit, left alone: the `tket/metadata.py` module
docstring example imports `MaxQubitsHint` but uses `ExpectedQubitsHint`.

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: aborgna-q <121866228+aborgna-q@users.noreply.github.com>

Author: Copilot

tket-py/test/test_pass.py

@@ -22,6 +22,7 @@
     InlineFunctions,
     ModifierResolverPass,
     Normalize,
+    NormalizeGuppy,
     PlatformTarget,
     PytketHugrPass,
     QSystemRebasePass,
@@ -292,6 +293,13 @@ def test_normalize_guppy():
     assert normal_circ1.circuit_cost(lambda op: int(op == TketOp.CX)) == 3
 
 
+def test_normalize_guppy_deprecated_alias():
+    with pytest.deprecated_call(match="Use `Normalize` instead"):
+        normalize = NormalizeGuppy()
+
+    assert isinstance(normalize, Normalize)
+
+
 def test_modifier_resolver() -> None:
     normalize = Normalize(resolve_modifiers=False)
     normalize_with_modifier_resolution = Normalize()

tket-py/tket/metadata.py

@@ -28,6 +28,7 @@
 from hugr.metadata import Metadata
 from pydantic import StrictBool, TypeAdapter
 from pydantic.dataclasses import dataclass
+from typing_extensions import deprecated
 
 from ._tket import metadata as _metadata
 
@@ -50,6 +51,7 @@
     "PytketBitRegisterNames",
     "PytketInputParameters",
     "PytketOpGroup",
+    "PytketPhaseExpr",
     "PytketQubit",
     "PytketQubitRegisterNames",
     "RewriteTraceValue",
@@ -197,6 +199,17 @@ def from_json(cls, value: JsonType) -> list[PytketQubit]:
         return _read_pytket_register(cls.KEY, value)
 
 
+@deprecated("Call `used_extensions` on the hugr instead.")
+class PytketPhaseExpr(Metadata[str]):
+    """Metadata key for the serialized pytket global phase expression.
+
+    Deprecated:
+        Use explicit ``tket.global_phase`` operations instead.
+    """
+
+    KEY = "TKET1.phase"
+
+
 def _store_pytket_register(value: list[tuple[str, list[int]]]) -> JsonType:
     return [[name, list(indices)] for name, indices in value]
 

tket-py/tket/passes/__init__.py

@@ -15,6 +15,7 @@
     implement_pass_run,
 )
 from hugr.passes.scope import GlobalScope, PassScope
+from typing_extensions import deprecated
 
 from tket import _state
 
@@ -33,6 +34,7 @@
     "InlineFunctions",
     "ModifierResolverPass",
     "Normalize",
+    "NormalizeGuppy",
     "PassResult",
     "PlatformTarget",
     "PytketHugrPass",
@@ -226,6 +228,11 @@ def _run_tk(self, program: _state.CompilationState) -> _state.CompilationState:
         return program
 
 
+@deprecated("Use `Normalize` instead.")
+class NormalizeGuppy(Normalize):
+    """Deprecated alias for :py:class:`Normalize`."""
+
+
 @cache
 def _cliffordize_matcher() -> RuleMatcher:
     """Build the matcher containing the supported Cliffordize rules."""