classiq 0.93.0__py3-none-any.whl → 0.99.0__py3-none-any.whl

classiq/qmod/qmod_variable.py

@@ -1,5 +1,6 @@
 import abc
 import sys
+import warnings
 from collections.abc import Iterator, Mapping
 from contextlib import contextmanager
 from typing import (  # type: ignore[attr-defined]
@@ -10,10 +11,8 @@ from typing import (  # type: ignore[attr-defined]
     Generic,
     Literal,
     NoReturn,
-    Optional,
     Protocol,
     TypeVar,
-    Union,
     _GenericAlias,
     cast,
     get_args,
@@ -24,6 +23,7 @@ from typing import (  # type: ignore[attr-defined]
 from typing_extensions import ParamSpec, Self, _AnnotatedAlias
 
 from classiq.interface.exceptions import (
+    ClassiqDeprecationWarning,
     ClassiqInternalError,
     ClassiqNotImplementedError,
     ClassiqValueError,
@@ -109,9 +109,9 @@ class QVar(Symbolic):
 
     def __init__(
         self,
-        origin: Union[None, str, HandleBinding] = None,
+        origin: None | str | HandleBinding = None,
         *,
-        expr_str: Optional[str] = None,
+        expr_str: str | None = None,
         depth: int = 2,
     ) -> None:
         name = _infer_variable_name(origin, self.CONSTRUCTOR_DEPTH)
@@ -141,9 +141,9 @@ class QVar(Symbolic):
     @abc.abstractmethod
     def to_qvar(
         cls,
-        origin: Union[str, HandleBinding],
+        origin: str | HandleBinding,
         type_hint: Any,
-        expr_str: Optional[str],
+        expr_str: str | None,
     ) -> Self:
         raise NotImplementedError()
 
@@ -151,7 +151,7 @@ class QVar(Symbolic):
         return self._expr_str
 
     @property
-    def size(self) -> Union[CParamScalar, int]:
+    def size(self) -> CParamScalar | int:
         if is_generative_mode():
             with generative_mode_context(False):
                 return interpret_expression(str(self.size))
@@ -176,9 +176,6 @@ Input = Annotated[_Q, PortDeclarationDirection.Input]
 Const = Annotated[
     _Q, TypeModifier.Const
 ]  # A constant variable, up to a phase dependent on the computational basis state
-Permutable = Annotated[
-    _Q, TypeModifier.Permutable
-]  # A permutable ("quantum free") variable, up to a phase dependent on the computational basis state
 
 
 class QScalar(QVar, SymbolicExpr):
@@ -186,9 +183,9 @@ class QScalar(QVar, SymbolicExpr):
 
     def __init__(
         self,
-        origin: Union[None, str, HandleBinding] = None,
+        origin: None | str | HandleBinding = None,
         *,
-        _expr_str: Optional[str] = None,
+        _expr_str: str | None = None,
         depth: int = 2,
     ) -> None:
         origin = _infer_variable_name(origin, self.CONSTRUCTOR_DEPTH)
@@ -260,6 +257,13 @@ class QScalar(QVar, SymbolicExpr):
         return self
 
     def __imul__(self, other: Any) -> Self:
+        warnings.warn(
+            "The '*=' operator is deprecated and will no longer be supported "
+            "starting on 2025-12-03 at the earliest. Use the 'assign_amplitude_table' "
+            "function instead",
+            ClassiqDeprecationWarning,
+            stacklevel=2,
+        )
         if not isinstance(other, SYMBOLIC_TYPES):
             raise ClassiqValueError(
                 f"Invalid argument {str(other)!r} for out of ampltiude encoding operation"
@@ -371,9 +375,9 @@ class QBit(QScalar):
     @classmethod
     def to_qvar(
         cls,
-        origin: Union[str, HandleBinding],
+        origin: str | HandleBinding,
         type_hint: Any,
-        expr_str: Optional[str],
+        expr_str: str | None,
     ) -> "QBit":
         return QBit(origin, _expr_str=expr_str)
 
@@ -428,11 +432,11 @@ class QNum(Generic[_P], QScalar):
 
     def __init__(
         self,
-        name: Union[None, str, HandleBinding] = None,
-        size: Union[int, CInt, Expression, SymbolicExpr, None] = None,
-        is_signed: Union[bool, CBool, Expression, SymbolicExpr, None] = None,
-        fraction_digits: Union[int, CInt, Expression, SymbolicExpr, None] = None,
-        _expr_str: Optional[str] = None,
+        name: None | str | HandleBinding = None,
+        size: int | CInt | Expression | SymbolicExpr | None = None,
+        is_signed: bool | CBool | Expression | SymbolicExpr | None = None,
+        fraction_digits: int | CInt | Expression | SymbolicExpr | None = None,
+        _expr_str: str | None = None,
     ):
         if size is None and (is_signed is not None or fraction_digits is not None):
             raise ClassiqValueError(
@@ -466,9 +470,9 @@ class QNum(Generic[_P], QScalar):
     @classmethod
     def to_qvar(
         cls,
-        origin: Union[str, HandleBinding],
+        origin: str | HandleBinding,
         type_hint: Any,
-        expr_str: Optional[str],
+        expr_str: str | None,
     ) -> "QNum":
         return QNum(origin, *_get_qnum_attributes(type_hint), _expr_str=expr_str)
 
@@ -480,14 +484,14 @@ class QNum(Generic[_P], QScalar):
         )
 
     @property
-    def fraction_digits(self) -> Union[CParamScalar, int]:
+    def fraction_digits(self) -> CParamScalar | int:
         if is_generative_mode():
             with generative_mode_context(False):
                 return interpret_expression(str(self.fraction_digits))
         return CParamScalar(f"{self}.fraction_digits")
 
     @property
-    def is_signed(self) -> Union[CParamScalar, bool]:
+    def is_signed(self) -> CParamScalar | bool:
         if is_generative_mode():
             with generative_mode_context(False):
                 return interpret_expression(str(self.is_signed))
@@ -510,12 +514,6 @@ class QNum(Generic[_P], QScalar):
             fraction_places=self.fraction_digits,
         )
 
-    # Support comma-separated generic args in older Python versions
-    if sys.version_info[0:2] < (3, 10):
-
-        def __class_getitem__(cls, args) -> _GenericAlias:
-            return _GenericAlias(cls, args)
-
 
 class QArray(ArrayBase[_P], QVar, NonSymbolicExpr):
     CONSTRUCTOR_DEPTH: int = 3
@@ -523,10 +521,10 @@ class QArray(ArrayBase[_P], QVar, NonSymbolicExpr):
     # TODO [CAD-18620]: improve type hints
     def __init__(
         self,
-        name: Union[None, str, HandleBinding] = None,
-        element_type: Union[_GenericAlias, QuantumType] = QBit,
-        length: Optional[Union[int, CInt, SymbolicExpr, Expression]] = None,
-        _expr_str: Optional[str] = None,
+        name: None | str | HandleBinding = None,
+        element_type: _GenericAlias | QuantumType = QBit,
+        length: int | CInt | SymbolicExpr | Expression | None = None,
+        _expr_str: str | None = None,
     ) -> None:
         self._element_type = element_type
         self._length = (
@@ -536,7 +534,7 @@ class QArray(ArrayBase[_P], QVar, NonSymbolicExpr):
         )
         super().__init__(name, expr_str=_expr_str)
 
-    def __getitem__(self, key: Union[slice, int, SymbolicExpr]) -> Any:
+    def __getitem__(self, key: slice | int | SymbolicExpr) -> Any:
         return (
             self._get_slice(key) if isinstance(key, slice) else self._get_subscript(key)
         )
@@ -544,7 +542,7 @@ class QArray(ArrayBase[_P], QVar, NonSymbolicExpr):
     def __setitem__(self, *args: Any) -> None:
         pass
 
-    def _get_subscript(self, index: Union[slice, int, SymbolicExpr]) -> Any:
+    def _get_subscript(self, index: slice | int | SymbolicExpr) -> Any:
         if isinstance(index, SymbolicExpr) and index.is_quantum:
             raise ClassiqValueError("Non-classical parameter for slicing")
 
@@ -589,7 +587,7 @@ class QArray(ArrayBase[_P], QVar, NonSymbolicExpr):
     else:
 
         @property
-        def len(self) -> Union[CParamScalar, int]:
+        def len(self) -> CParamScalar | int:
             if is_generative_mode():
                 with generative_mode_context(False):
                     return interpret_expression(str(self.len))
@@ -598,9 +596,9 @@ class QArray(ArrayBase[_P], QVar, NonSymbolicExpr):
     @classmethod
     def to_qvar(
         cls,
-        origin: Union[str, HandleBinding],
+        origin: str | HandleBinding,
         type_hint: Any,
-        expr_str: Optional[str],
+        expr_str: str | None,
     ) -> "QArray":
         return QArray(origin, *_get_qarray_attributes(type_hint), _expr_str=expr_str)
 
@@ -614,6 +612,9 @@ class QArray(ArrayBase[_P], QVar, NonSymbolicExpr):
             length=self._length,
         )
 
+    def __iter__(self) -> NoReturn:
+        raise TypeError(f"{type(self).__name__!r} object is not iterable")
+
 
 class QStruct(QVar):
     CONSTRUCTOR_DEPTH: int = 2
@@ -623,10 +624,10 @@ class QStruct(QVar):
 
     def __init__(
         self,
-        origin: Union[None, str, HandleBinding] = None,
-        _struct_name: Optional[str] = None,
-        _fields: Optional[Mapping[str, QVar]] = None,
-        _expr_str: Optional[str] = None,
+        origin: None | str | HandleBinding = None,
+        _struct_name: str | None = None,
+        _fields: Mapping[str, QVar] | None = None,
+        _expr_str: str | None = None,
     ) -> None:
         _register_qstruct(type(self), qmodule=QMODULE)
         name = _infer_variable_name(origin, self.CONSTRUCTOR_DEPTH)
@@ -654,9 +655,9 @@ class QStruct(QVar):
     @classmethod
     def to_qvar(
         cls,
-        origin: Union[str, HandleBinding],
+        origin: str | HandleBinding,
         type_hint: Any,
-        expr_str: Optional[str],
+        expr_str: str | None,
     ) -> "QStruct":
         field_types = {
             field_name: (_get_root_type(field_type), field_type)
@@ -699,7 +700,7 @@ def create_qvar_from_quantum_type(quantum_type: ConcreteQuantumType, name: str)
 
 
 def _create_qvar_for_qtype(
-    qtype: QuantumType, origin: HandleBinding, expr_str: Optional[str] = None
+    qtype: QuantumType, origin: HandleBinding, expr_str: str | None = None
 ) -> QVar:
     # prevent addition to local handles, since this is used for ports
     with _no_current_expandable():
@@ -868,7 +869,7 @@ def _get_quantum_struct(type_hint: type[QStruct]) -> Struct:
 
 def _register_qstruct(
     type_hint: type[QStruct], *, qmodule: ModelStateContainer
-) -> Optional[QStructDeclaration]:
+) -> QStructDeclaration | None:
     struct_name = type_hint.__name__
     if type_hint is QStruct:
         return None

classiq/qmod/quantum_callable.py

@@ -1,13 +1,10 @@
 import sys
 from abc import ABC, abstractmethod
-from typing import (  # type: ignore[attr-defined]
+from typing import (
     TYPE_CHECKING,
     Any,
     ClassVar,
     Generic,
-    Optional,
-    Union,
-    _GenericAlias,
 )
 
 from typing_extensions import ParamSpec
@@ -39,13 +36,13 @@ class QExpandableInterface(ABC):
         self,
         name: str,
         qtype: QuantumType,
-        source_ref: Optional[SourceReference] = None,
+        source_ref: SourceReference | None = None,
     ) -> None:
         raise NotImplementedError()
 
 
 class QCallable(Generic[P], ABC):
-    CURRENT_EXPANDABLE: ClassVar[Optional[QExpandableInterface]] = None
+    CURRENT_EXPANDABLE: ClassVar[QExpandableInterface | None] = None
     FRAME_DEPTH = 1
 
     @suppress_return_value
@@ -62,12 +59,6 @@ class QCallable(Generic[P], ABC):
     def func_decl(self) -> AnonQuantumFunctionDeclaration:
         raise NotImplementedError
 
-    # Support comma-separated generic args in older Python versions
-    if sys.version_info[0:2] < (3, 10):
-
-        def __class_getitem__(cls, args) -> _GenericAlias:
-            return _GenericAlias(cls, args)
-
     @abstractmethod
     def create_quantum_function_call(
         self, source_ref_: SourceReference, *args: Any, **kwargs: Any
@@ -81,5 +72,19 @@ class QCallableList(QCallable, Generic[P], ABC):
         @property
         def len(self) -> int: ...
 
-        def __getitem__(self, key: Union[slice, int, CInt]) -> "QTerminalCallable":
+        def __getitem__(self, key: slice | int | CInt) -> "QTerminalCallable":
+            raise NotImplementedError()
+
+
+class QPerm(QCallable, Generic[P], ABC):
+    pass
+
+
+class QPermList(QCallable, Generic[P], ABC):
+    if TYPE_CHECKING:
+
+        @property
+        def len(self) -> int: ...
+
+        def __getitem__(self, key: slice | int | CInt) -> "QTerminalCallable":
             raise NotImplementedError()

classiq/qmod/quantum_expandable.py

@@ -1,15 +1,13 @@
 import inspect
 from abc import ABC
-from collections.abc import Generator, Iterable
+from collections.abc import Callable, Generator, Iterable
 from dataclasses import is_dataclass
 from enum import Enum as PythonEnum
 from types import TracebackType
 from typing import (
     TYPE_CHECKING,
     Any,
-    Callable,
     ClassVar,
-    Optional,
     Union,
     cast,
     overload,
@@ -56,7 +54,11 @@ from classiq.interface.model.variable_declaration_statement import (
 )
 from classiq.interface.source_reference import SourceReference
 
-from classiq.qmod.generative import generative_mode_context, is_generative_mode
+from classiq.qmod.generative import (
+    generative_mode_context,
+    interpret_expression,
+    is_generative_mode,
+)
 from classiq.qmod.global_declarative_switch import get_global_declarative_switch
 from classiq.qmod.model_state_container import QMODULE, ModelStateContainer
 from classiq.qmod.qmod_constant import QConstant
@@ -107,9 +109,9 @@ class QExpandable(QCallable, QExpandableInterface, ABC):
 
     def __exit__(
         self,
-        exc_type: Optional[type[BaseException]],
-        exc_val: Optional[BaseException],
-        exc_tb: Optional[TracebackType],
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
     ) -> None:
         assert QExpandable.STACK.pop() is self
         QCallable.CURRENT_EXPANDABLE = (
@@ -125,14 +127,14 @@ class QExpandable(QCallable, QExpandableInterface, ABC):
             with self, generative_mode_context(False):
                 self._py_callable(*self._get_positional_args())
 
-    def infer_rename_params(self) -> Optional[list[str]]:
+    def infer_rename_params(self) -> list[str] | None:
         return None
 
     def add_local_handle(
         self,
         name: str,
         qtype: QuantumType,
-        source_ref: Optional[SourceReference] = None,
+        source_ref: SourceReference | None = None,
     ) -> None:
         self.append_statement_to_body(
             VariableDeclarationStatement(
@@ -219,8 +221,8 @@ class QTerminalCallable(QCallable):
     def __init__(
         self,
         decl: QuantumFunctionDeclaration,
-        param_idx: Optional[int] = None,
-        index_: Optional[Union[int, CParamScalar]] = None,
+        param_idx: int | None = None,
+        index_: int | CParamScalar | None = None,
     ) -> None:
         pass
 
@@ -229,22 +231,22 @@ class QTerminalCallable(QCallable):
         self,
         decl: AnonQuantumFunctionDeclaration,
         param_idx: int,
-        index_: Optional[Union[int, CParamScalar]] = None,
+        index_: int | CParamScalar | None = None,
     ) -> None:
         pass
 
     def __init__(
         self,
         decl: AnonQuantumFunctionDeclaration,
-        param_idx: Optional[int] = None,
-        index_: Optional[Union[int, CParamScalar]] = None,
+        param_idx: int | None = None,
+        index_: int | CParamScalar | None = None,
     ) -> None:
         self._decl = self._override_decl_name(decl, param_idx)
         self._index = index_
 
     @staticmethod
     def _override_decl_name(
-        decl: AnonQuantumFunctionDeclaration, param_idx: Optional[int]
+        decl: AnonQuantumFunctionDeclaration, param_idx: int | None
     ) -> QuantumFunctionDeclaration:
         if (
             not isinstance(QCallable.CURRENT_EXPANDABLE, QLambdaFunction)
@@ -260,7 +262,7 @@ class QTerminalCallable(QCallable):
             isinstance(self._decl, AnonQuantumOperandDeclaration) and self._decl.is_list
         )
 
-    def __getitem__(self, key: Union[slice, int, CInt]) -> "QTerminalCallable":
+    def __getitem__(self, key: slice | int | CInt) -> "QTerminalCallable":
         if not self.is_list:
             raise ClassiqValueError("Cannot index a non-list operand")
         if isinstance(key, slice):
@@ -287,6 +289,9 @@ class QTerminalCallable(QCallable):
         def len(self) -> CParamScalar:
             if not self.is_list:
                 raise ClassiqValueError("Cannot get length of a non-list operand")
+            if is_generative_mode():
+                with generative_mode_context(False):
+                    return interpret_expression(str(self.len))
             return CParamScalar(f"{self.func_decl.name}.len")
 
     @property
@@ -315,25 +320,25 @@ class QTerminalCallable(QCallable):
 @overload
 def prepare_arg(
     arg_decl: AnonPositionalArg,
-    val: Union[QCallable, Callable[..., None]],
-    func_name: Optional[str],
+    val: QCallable | Callable[..., None],
+    func_name: str | None,
     param_name: str,
 ) -> QuantumLambdaFunction: ...
 
 
 @overload
 def prepare_arg(
-    arg_decl: AnonPositionalArg, val: Any, func_name: Optional[str], param_name: str
+    arg_decl: AnonPositionalArg, val: Any, func_name: str | None, param_name: str
 ) -> ArgValue: ...
 
 
 def prepare_arg(
-    arg_decl: AnonPositionalArg, val: Any, func_name: Optional[str], param_name: str
+    arg_decl: AnonPositionalArg, val: Any, func_name: str | None, param_name: str
 ) -> ArgValue:
     from classiq.qmod.quantum_function import BaseQFunc, GenerativeQFunc, QFunc
 
     if get_global_declarative_switch() and isinstance(val, GenerativeQFunc):
-        val = QFunc(val._py_callable)
+        val = QFunc(val._py_callable, permutation=val.permutation)
     if isinstance(val, BaseQFunc):
         val.add_function_dependencies()
     if isinstance(val, GenerativeQFunc):
@@ -391,7 +396,7 @@ def prepare_arg(
 
 
 def _validate_classical_arg(
-    arg: Any, arg_decl: AnonClassicalParameterDeclaration, func_name: Optional[str]
+    arg: Any, arg_decl: AnonClassicalParameterDeclaration, func_name: str | None
 ) -> None:
     is_native_or_compatible_type = (
         not isinstance(
@@ -504,8 +509,8 @@ def _validate_argument_names(
 
 def _create_quantum_function_call(
     decl_: QuantumFunctionDeclaration,
-    index_: Optional[Union[CParamScalar, int]] = None,
-    source_ref_: Optional[SourceReference] = None,
+    index_: CParamScalar | int | None = None,
+    source_ref_: SourceReference | None = None,
     *args: Any,
     **kwargs: Any,
 ) -> QuantumFunctionCall:
@@ -513,7 +518,7 @@ def _create_quantum_function_call(
     _validate_argument_names(decl_, arg_list, kwargs)
     prepared_args = _prepare_args(decl_, arg_list, kwargs)
 
-    function_ident: Union[str, OperandIdentifier] = decl_.name
+    function_ident: str | OperandIdentifier = decl_.name
     if index_ is not None:
         function_ident = OperandIdentifier(
             index=Expression(expr=str(index_)), name=function_ident
@@ -541,7 +546,7 @@ def _is_legal_iterable_element(arg: Any) -> bool:
     return True
 
 
-def _try_preparing_handles_list(val: Any) -> Optional[HandlesList]:
+def _try_preparing_handles_list(val: Any) -> HandlesList | None:
     if not isinstance(val, list):
         return None
     items = [