stark-engine 4.5.2__tar.gz → 4.5.4__tar.gz

{stark_engine-4.5.2 → stark_engine-4.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stark-engine
-Version: 4.5.2
+Version: 4.5.4
 Summary: S.T.A.R.K - Speech and Text Algorithmic Recognition Kit. Modern framework for creating powerfull voice assistants.
 License: CC BY-NC-SA 4.0
 License-File: LICENSE.md

{stark_engine-4.5.2 → stark_engine-4.5.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "stark-engine"
-version = "4.5.2"
+version = "4.5.4"
 description = "S.T.A.R.K - Speech and Text Algorithmic Recognition Kit. Modern framework for creating powerfull voice assistants."
 authors = ["MarkParker5 <mark@parker-programs.com>"]
 license = "CC BY-NC-SA 4.0"

{stark_engine-4.5.2 → stark_engine-4.5.4}/stark/core/parsing.py

@@ -3,16 +3,16 @@ from __future__ import annotations
 import re
 from abc import ABC
 from dataclasses import dataclass, field
-from typing import AsyncGenerator
+from typing import AsyncGenerator, NamedTuple
 
 from stark.core.patterns.pattern import Pattern
 from stark.core.patterns.rules import rules_list
 from stark.core.types import Object
 from stark.core.types.string import String
+from stark.core.types.union import Union, _all_subclasses
 from stark.core.types.word import Word
 from stark.general.cache import alru_cache
-from typing import NamedTuple
-
+from stark.general.feature_flags import FeatureFlag, get_flag
 from stark.general.localisation import LanguageCode, LocaleString, Localizer
 from stark.models.transcription_string import Correction
 from stark.tools.common.span import Span
@@ -22,6 +22,7 @@ class CorrectionMatch(NamedTuple):
     span: Span
     correction: Correction
 
+
 type ObjectType = type[Object]
 
 
@@ -104,6 +105,7 @@ class PatternParser:
 
     def __init__(self, localizer: Localizer | None = None):
         self.parameter_types_by_name = {}
+        self._registering: set[str] = set()  # cycle guard for recursive register_parameter_type
         self.localizer = localizer
         self.register_parameter_type(Word)
         self.register_parameter_type(String)
@@ -114,19 +116,38 @@ class PatternParser:
         parser: ObjectParser | None = None,
         # TODO: consider adding lang parameter
     ):
-        assert issubclass(object_type, Object), (
-            f'Can`t add parameter type "{object_type.__name__}": it is not a subclass of Object'
-        )
-        exists_type = self.parameter_types_by_name.get(object_type.__name__)
-        assert exists_type is None, (
-            f"Duplicate parameter type: can`t add parameter type '{object_type.__name__}' because it already exists"
-        )
-        resolved_parser = parser or ObjectParser()
-        resolved_parser.localizer = self.localizer
-        self.parameter_types_by_name[object_type.__name__] = RegisteredParameterType(
-            name=object_type.__name__, type=object_type, parser=resolved_parser
-        )
-        self._validate_localizer_keys(object_type)
+        name = object_type.__name__
+        # Idempotent: skip if already registered or currently being registered (cycle guard).
+        if name in self.parameter_types_by_name or name in self._registering:
+            return
+        self._registering.add(name)
+        try:
+            assert issubclass(object_type, Object), f'Can`t add parameter type "{name}": it is not a subclass of Object'
+            # Resolve deps. Union types declare members explicitly in _types;
+            # everything else declares deps implicitly via parameter annotations in the pattern.
+            if issubclass(object_type, Union) and hasattr(object_type, "_types"):
+                deps = object_type._types
+            else:
+                # Evaluate the pattern first — it may create new classes (e.g. any_subclass calls).
+                # Build known AFTER so those new classes are visible by name.
+                pattern = object_type.pattern
+                known = {cls.__name__: cls for cls in _all_subclasses(Object)}
+                deps = [known[p.type_name] for p in pattern.parameters.values() if p.type_name in known]
+            # Register each dep before the type itself (depth-first, handles transitive deps).
+            for dep in deps:
+                self.register_parameter_type(dep)
+            exists_type = self.parameter_types_by_name.get(name)
+            assert exists_type is None, (
+                f"Duplicate parameter type: can`t add parameter type '{name}' because it already exists"
+            )
+            resolved_parser = parser or ObjectParser()
+            resolved_parser.localizer = self.localizer
+            self.parameter_types_by_name[name] = RegisteredParameterType(
+                name=name, type=object_type, parser=resolved_parser
+            )
+            self._validate_localizer_keys(object_type)
+        finally:
+            self._registering.discard(name)
 
     def _validate_localizer_keys(self, object_type: ObjectType):
         for pattern in object_type.patterns.values():
@@ -172,7 +193,7 @@ class PatternParser:
             string = from_string._with(object_pattern_match.substring)  # TODO: review _with usage
 
             parser: ObjectParser = self.parameter_types_by_name[object_type.__name__].parser
-            obj = object_type(string)  # temp/default value, may be overridden by did_parse
+            obj = object_type()  # object_type(string)  # temp/default value, may be overridden by did_parse
 
             matched_subparams = object_pattern_match.parameters
             assert matched_subparams.keys() <= {p.name for p in pattern.parameters.values() if not p.optional}
@@ -184,16 +205,19 @@ class PatternParser:
             try:
                 substring = await self._did_parse(obj, parser, string)
             except ParseError:
-                logger.debug(f"Failed to parse object {object_type} with parser {parser} from '{string}'")
+                logger.debug(f"Failed to parse object {object_type!r} with parser {parser!r} from '{string}'")
                 continue  # skip an try the next match candidate
 
-            assert substring.strip(), ValueError(f"Parsed substring must not be empty. Object: {obj}, Parser: {parser}")
-            assert substring in string, ValueError(
-                f"Parsed substring must be a part of the original string. There is no {substring} in {string}. Object: {obj}, Parser: {parser}"
+            assert substring.strip(), ValueError(
+                f"Parsed substring must not be empty. Object: {obj!r}, Parser: {parser!r}"
             )
-            assert obj.value is not None, ValueError(
-                f"Parsed object {obj} must have a `value` property set in did_parse method. Object: {obj}, Parser: {parser}"
+            assert substring in string, ValueError(
+                f"Parsed substring must be a part of the original string. There is no '{substring}' in '{string}'. Object: {obj!r}, Parser: {parser!r}"
             )
+            if not get_flag(FeatureFlag.TYPE_NO_REQUIRED_VALUE):
+                assert obj.value is not None, ValueError(
+                    f"Parsed object {obj!r} must have a `value` property set at the time did_parse method returns. Object: {obj!r}, Parser: {parser!r}"
+                )
 
             yield ParseResult(obj, substring)
 
@@ -441,10 +465,17 @@ class PatternParser:
 
         # parse the object
         try:
+            from stark.core.types.union import Union
+
             parse_result = await self.parse_object(parameter_reg_type.type, from_string=raw_param_substr)
+            parsed_obj = parse_result.obj
+            if isinstance(parsed_obj, Union) and getattr(type(parsed_obj), "_transparent", False):
+                # Transparent Unions (MakeUnion / | / any_subclass) are unwrapped to the branch.
+                # Named Union subclasses (class Foo(Union)) are kept as-is — caller uses .value.
+                parsed_obj = parsed_obj.value
             return ParameterMatch(  # take the first match (the only in most cases)
                 name=param.name,
-                parsed_obj=parse_result.obj,
+                parsed_obj=parsed_obj,
                 parsed_substr=parse_result.substring,
             )
         except ParseError as e:

{stark_engine-4.5.2 → stark_engine-4.5.4}/stark/core/types/__init__.py

@@ -1,4 +1,5 @@
 from .object import Object
+from .union import MakeUnion, Union, any_subclass
 from .slots import SlotsParser
 from .string import String
 from .word import Word

{stark_engine-4.5.2 → stark_engine-4.5.4}/stark/core/types/object.py

@@ -1,18 +1,45 @@
 from __future__ import annotations
 
 import copy
-from abc import ABC
-from typing import Any
+from abc import ABCMeta
 
 from stark.core.patterns.pattern import Pattern
 from stark.general.classproperty import classproperty
 from stark.general.localisation import LocaleString
 
 
+class UnionMeta(ABCMeta):
+    """Metaclass that makes | on Object subclasses produce a STARK Union subclass instead of types.UnionType."""
+
+    def __call__(cls, *args, **kwargs):
+        from stark.core.types.union import Union
+
+        if cls is Union:
+            raise TypeError("Union cannot be instantiated directly; subclass it or use | syntax or  MakeUnion")
+        return super().__call__(*args, **kwargs)
+
+    def __or__(cls, other: type) -> type:
+        from stark.core.types.union import MakeUnion
+
+        if isinstance(other, type) and issubclass(other, Object):
+            return MakeUnion(cls, other)
+        return type.__or__(cls, other)  # fall through to types.UnionType for X | None etc.
+
+    def __ror__(cls, other: type) -> type:
+        from stark.core.types.union import MakeUnion
+
+        if isinstance(other, type) and issubclass(other, Object):
+            return MakeUnion(other, cls)
+        return type.__ror__(cls, other)
+
+    def __format__(cls, spec) -> str:
+        return cls.__name__
+
+
 # TODO: review programmable init vs did_parse
 # TODO: consider storing parsing metadata here like substr and span
-class Object[T](ABC):
-    value: T
+class Object[T](metaclass=UnionMeta):
+    value: T = None
 
     @classproperty
     def pattern(cls) -> Pattern:
@@ -32,9 +59,13 @@ class Object[T](ABC):
         """
         return False  # TODO: review default behavior
 
-    def __init__(self, value: Any):
-        """Just init with wrapped value."""
-        self.value = value
+    def __init__(self, *args, **kwargs):
+        """Init with wrapped value, if provided. Otherwise leave `value` untouched so a static
+        value set at class declaration time (e.g. `value = "foo"`) survives instantiation."""
+        if "value" in kwargs:
+            self.value = kwargs["value"]
+        elif args:
+            self.value = args[0]
 
     async def did_parse(self, from_string: LocaleString) -> str:
         """
@@ -51,6 +82,8 @@ class Object[T](ABC):
         Raises:
             ParseError: if parsing failed.
         """
+        if not self.value:
+            self.value = from_string
         return from_string
 
     def copy(self) -> Object:

stark_engine-4.5.4/stark/core/types/union.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from stark.core.patterns.pattern import Pattern
+from stark.core.types.object import Object, UnionMeta
+from stark.general.classproperty import classproperty
+
+
+def MakeUnion(*types: type[Object]) -> type:
+    cls = UnionMeta("_".join(t.__name__ for t in types), (Union,), {"_types": list(types)})
+    cls._transparent = True  # PatternParser unwraps to branch when used as a typed parameter
+    return cls
+
+
+def any_subclass(cls: type[Object]) -> type[Union]:
+    """Returns a Union of all current concrete subclasses of cls.
+
+    Result is cached on the base class so the same class object is returned on every call —
+    required for stable type registration (the parser keys on class name and object identity).
+    Discovered at first call time, so subclasses defined before the pattern is first accessed
+    (i.e., at parse time) are included automatically.
+    """
+    cache_attr = f"_any_subclass_{cls.__name__}"
+    if not hasattr(cls, cache_attr):
+        u = MakeUnion(*_all_subclasses(cls))
+        u.__name__ = f"Any{cls.__name__}"  # no | — Pattern syntax treats | as OR
+        setattr(cls, cache_attr, u)
+    return getattr(cls, cache_attr)
+
+
+def _all_subclasses(cls):
+    for sub in cls.__subclasses__():
+        yield sub
+        yield from _all_subclasses(sub)
+
+
+class Union(Object):
+    """Base for union types. Use as superclass or combine with | / MakeUnion.
+
+    self.value  — the matched branch Object instance
+    self.value.value  — the inner parsed value
+    type(self.value)  — the matched branch type
+
+    After PatternParser unwraps Union parameters, callers receive the concrete branch
+    directly — isinstance, type(), and attribute access all work against the real class.
+    """
+
+    _types: list[type[Object]]
+    value: Object
+
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        if "pattern" in cls.__dict__ or "patterns" in cls.__dict__:
+            raise TypeError(f"{cls.__name__}: Union subclasses may not override 'pattern'")
+
+    @classproperty
+    def pattern(cls) -> Pattern:
+        return Pattern("(" + "|".join(f"$m{n}:{t.__name__}" for n, t in enumerate(cls._types, 1)) + ")")
+
+    async def did_parse(self, from_string) -> str:
+        from stark.core.parsing import ParseError
+        for k, v in self.__dict__.items():
+            if k.startswith("m") and v is not None:
+                self.value = v  # branch Object, not v.value
+                return from_string
+        raise ParseError("Union: no branch matched")

{stark_engine-4.5.2 → stark_engine-4.5.4}/stark/general/feature_flags.py

@@ -5,11 +5,13 @@ from enum import StrEnum
 class FeatureFlag(StrEnum):
     ENABLE_VOICE_CLI = "STARK_ENABLE_VOICE_CLI"
     ENABLE_MULTILANG_MATRIX = "STARK_ENABLE_MULTILANG_MATRIX"
+    TYPE_NO_REQUIRED_VALUE = "STARK_TYPE_NO_REQUIRED_VALUE"
 
 
 _DEFAULTS: dict[FeatureFlag, str] = {
     FeatureFlag.ENABLE_VOICE_CLI: "0",
     FeatureFlag.ENABLE_MULTILANG_MATRIX: "1",
+    FeatureFlag.TYPE_NO_REQUIRED_VALUE: "0",
 }
 
 

{stark_engine-4.5.2 → stark_engine-4.5.4}/stark/tools/sliding_window_parser.py

@@ -131,4 +131,4 @@ async def sliding_window_parse[T](
         return results
 
     # If no valid window is found, raise an error.
-    raise ParseError(f"No valid window found using parser={parser} in phrase={phrase}")
+    raise ParseError(f"No valid window found using parser={parser!r} in phrase='{phrase}'")