classiq 0.92.0__py3-none-any.whl → 0.94.0__py3-none-any.whl

classiq/qmod/qfunc.py

@@ -1,6 +1,12 @@
-from typing import Callable, Literal, Optional, Union, overload
-
-from classiq.interface.exceptions import ClassiqInternalError
+import warnings
+from collections.abc import Callable
+from typing import Literal, overload
+
+from classiq.interface.exceptions import (
+    ClassiqDeprecationWarning,
+    ClassiqInternalError,
+    ClassiqValueError,
+)
 
 from classiq.qmod.global_declarative_switch import get_global_declarative_switch
 from classiq.qmod.quantum_callable import QCallable
@@ -21,7 +27,9 @@ def qfunc(
     *,
     external: Literal[True],
     synthesize_separately: Literal[False] = False,
-    unchecked: Optional[list[str]] = None,
+    unchecked: list[str] | None = None,
+    disable_perm_check: bool = False,
+    disable_const_checks: list[str] | bool = False,
 ) -> Callable[[Callable], ExternalQFunc]: ...
 
 
@@ -30,13 +38,19 @@ def qfunc(
     *,
     generative: Literal[False],
     synthesize_separately: bool = False,
-    unchecked: Optional[list[str]] = None,
+    unchecked: list[str] | None = None,
+    disable_perm_check: bool = False,
+    disable_const_checks: list[str] | bool = False,
 ) -> Callable[[Callable], QFunc]: ...
 
 
 @overload
 def qfunc(
-    *, synthesize_separately: bool, unchecked: Optional[list[str]] = None
+    *,
+    synthesize_separately: bool,
+    unchecked: list[str] | None = None,
+    disable_perm_check: bool = False,
+    disable_const_checks: list[str] | bool = False,
 ) -> Callable[[Callable], GenerativeQFunc]: ...
 
 
@@ -44,18 +58,113 @@ def qfunc(
 def qfunc(
     *,
     synthesize_separately: bool = False,
-    unchecked: Optional[list[str]] = None,
+    unchecked: list[str] | None = None,
+    disable_perm_check: bool = False,
+    disable_const_checks: list[str] | bool = False,
 ) -> Callable[[Callable], GenerativeQFunc]: ...
 
 
 def qfunc(
-    func: Optional[Callable] = None,
+    func: Callable | None = None,
+    *,
+    external: bool = False,
+    generative: bool | None = None,
+    synthesize_separately: bool = False,
+    unchecked: list[str] | None = None,
+    disable_perm_check: bool = False,
+    disable_const_checks: list[str] | bool = False,
+) -> Callable[[Callable], QCallable] | QCallable:
+    return _qfunc_inner(
+        func=func,
+        external=external,
+        generative=generative,
+        synthesize_separately=synthesize_separately,
+        unchecked=unchecked,
+        permutation=False,
+        disable_perm_check=disable_perm_check,
+        disable_const_checks=disable_const_checks,
+    )
+
+
+@overload
+def qperm(func: Callable) -> GenerativeQFunc: ...
+
+
+@overload
+def qperm(
+    *,
+    external: Literal[True],
+    synthesize_separately: Literal[False] = False,
+    unchecked: list[str] | None = None,
+    disable_perm_check: bool = False,
+    disable_const_checks: list[str] | bool = False,
+) -> Callable[[Callable], ExternalQFunc]: ...
+
+
+@overload
+def qperm(
+    *,
+    generative: Literal[False],
+    synthesize_separately: bool = False,
+    unchecked: list[str] | None = None,
+    disable_perm_check: bool = False,
+    disable_const_checks: list[str] | bool = False,
+) -> Callable[[Callable], QFunc]: ...
+
+
+@overload
+def qperm(
+    *,
+    synthesize_separately: bool,
+    unchecked: list[str] | None = None,
+    disable_perm_check: bool = False,
+    disable_const_checks: list[str] | bool = False,
+) -> Callable[[Callable], GenerativeQFunc]: ...
+
+
+@overload
+def qperm(
+    *,
+    synthesize_separately: bool = False,
+    unchecked: list[str] | None = None,
+    disable_perm_check: bool = False,
+    disable_const_checks: list[str] | bool = False,
+) -> Callable[[Callable], GenerativeQFunc]: ...
+
+
+def qperm(
+    func: Callable | None = None,
+    *,
+    external: bool = False,
+    generative: bool | None = None,
+    synthesize_separately: bool = False,
+    unchecked: list[str] | None = None,
+    disable_perm_check: bool = False,
+    disable_const_checks: list[str] | bool = False,
+) -> Callable[[Callable], QCallable] | QCallable:
+    return _qfunc_inner(
+        func=func,
+        external=external,
+        generative=generative,
+        synthesize_separately=synthesize_separately,
+        unchecked=unchecked,
+        permutation=True,
+        disable_perm_check=disable_perm_check,
+        disable_const_checks=disable_const_checks,
+    )
+
+
+def _qfunc_inner(
     *,
+    func: Callable | None = None,
     external: bool = False,
-    generative: Optional[bool] = None,
+    generative: bool | None = None,
     synthesize_separately: bool = False,
-    unchecked: Optional[list[str]] = None,
-) -> Union[Callable[[Callable], QCallable], QCallable]:
+    unchecked: list[str] | None = None,
+    permutation: bool = False,
+    disable_perm_check: bool = False,
+    disable_const_checks: list[str] | bool = False,
+) -> Callable[[Callable], QCallable] | QCallable:
     if generative is None:
         generative = True
     if get_global_declarative_switch():
@@ -66,16 +175,30 @@ def qfunc(
 
         if external:
             _validate_directives(synthesize_separately, unchecked)
-            return ExternalQFunc(func)
+            return ExternalQFunc(func, permutation=permutation)
 
         if generative:
-            qfunc = GenerativeQFunc(func)
+            qfunc = GenerativeQFunc(func, permutation=permutation)
         else:
-            qfunc = QFunc(func)
+            qfunc = QFunc(func, permutation=permutation)
         if synthesize_separately:
             qfunc.update_compilation_metadata(should_synthesize_separately=True)
         if unchecked is not None and len(unchecked) > 0:
-            qfunc.update_compilation_metadata(unchecked=unchecked)
+            nonlocal disable_const_checks
+            if disable_const_checks:
+                raise ClassiqValueError(
+                    "The 'unchecked' parameter is deprecated, please use 'disable_const_checks' only."
+                )
+            warnings.warn(
+                "The 'unchecked' parameter is deprecated and will no longer be supported starting on 2025-10-30 at the earliest. Please use the 'disable_const_checks' instead.",
+                ClassiqDeprecationWarning,
+                stacklevel=2,
+            )
+            disable_const_checks = unchecked
+        if disable_perm_check:
+            qfunc.update_compilation_metadata(disable_perm_check=disable_perm_check)
+        if disable_const_checks:
+            qfunc.update_compilation_metadata(disable_const_checks=disable_const_checks)
         return qfunc
 
     if func is not None:
@@ -84,7 +207,7 @@ def qfunc(
 
 
 def _validate_directives(
-    synthesize_separately: bool, unchecked: Optional[list[str]] = None
+    synthesize_separately: bool, unchecked: list[str] | None = None
 ) -> None:
     error_msg = ""
     if synthesize_separately:

classiq/qmod/qmod_constant.py

@@ -1,6 +1,6 @@
 import inspect
 from dataclasses import is_dataclass
-from typing import TYPE_CHECKING, Any, Optional, cast, get_origin
+from typing import TYPE_CHECKING, Any, cast, get_origin
 
 from classiq.interface.exceptions import ClassiqError, ClassiqValueError
 from classiq.interface.generator.constant import Constant
@@ -25,7 +25,7 @@ QMODULE_ERROR_MESSAGE = (
 
 
 class QConstant(SymbolicExpr):
-    CURRENT_QMODULE: Optional[ModelStateContainer] = None
+    CURRENT_QMODULE: ModelStateContainer | None = None
 
     def __init__(self, name: str, py_type: type, value: Any) -> None:
         super().__init__(name, False)

classiq/qmod/qmod_parameter.py

@@ -1,4 +1,4 @@
-from typing import TYPE_CHECKING, Any, Union
+from typing import TYPE_CHECKING, Any, NoReturn
 
 from classiq.interface.exceptions import ClassiqInternalError, ClassiqValueError
 from classiq.interface.generator.functions.classical_type import (
@@ -41,7 +41,7 @@ class CParamList(CParam):
     def __init__(
         self,
         expr: str,
-        list_type: Union[ClassicalArray, ClassicalTuple],
+        list_type: ClassicalArray | ClassicalTuple,
         qmodule: ModelStateContainer,
     ) -> None:
         super().__init__(expr)
@@ -102,6 +102,9 @@ class CParamList(CParam):
                 return interpret_expression(str(self.len))
         return CParamScalar(f"{self}.len")
 
+    def __iter__(self) -> NoReturn:
+        raise TypeError(f"{type(self).__name__!r} object is not iterable")
+
 
 class CParamStruct(CParam):
     def __init__(

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))
@@ -186,9 +186,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)
@@ -371,9 +371,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 +428,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 +466,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 +480,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 +510,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 +517,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 +530,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 +538,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 +583,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 +592,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 +608,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 +620,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 +651,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 +696,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():
@@ -770,6 +767,13 @@ def get_port_from_type_hint(
     else:
         quantum_type = _to_quantum_type(py_type)
 
+    if modifier is TypeModifier.Permutable:
+        warnings.warn(
+            "The `Permutable` type modifier is deprecated and will no longer be supported starting on 2025-10-30 at the earliest. If the function as a whole is a permutation, use `qperm` instead.",
+            ClassiqDeprecationWarning,
+            stacklevel=1,
+        )
+
     return quantum_type, direction, modifier
 
 
@@ -868,7 +872,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()