sinapsis_core 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. sinapsis_core/__init__.py +0 -0
  2. sinapsis_core/agent/__init__.py +5 -0
  3. sinapsis_core/agent/agent.py +362 -0
  4. sinapsis_core/agent/agent_helpers.py +112 -0
  5. sinapsis_core/agent/base_models.py +361 -0
  6. sinapsis_core/agent/builder.py +112 -0
  7. sinapsis_core/agent/profiler_agent.py +117 -0
  8. sinapsis_core/cli/__init__.py +0 -0
  9. sinapsis_core/cli/arg_parser.py +29 -0
  10. sinapsis_core/cli/display_template_info.py +202 -0
  11. sinapsis_core/cli/run_agent_from_config.py +40 -0
  12. sinapsis_core/context_managers/__init__.py +0 -0
  13. sinapsis_core/context_managers/env_var_override_context_manager.py +39 -0
  14. sinapsis_core/context_managers/working_dir_context_manager.py +57 -0
  15. sinapsis_core/data_containers/__init__.py +0 -0
  16. sinapsis_core/data_containers/annotations.py +152 -0
  17. sinapsis_core/data_containers/data_packet.py +364 -0
  18. sinapsis_core/data_containers/model_types/__init__.py +38 -0
  19. sinapsis_core/data_containers/model_types/_asr_base_models.py +39 -0
  20. sinapsis_core/data_containers/model_types/llm_types.py +189 -0
  21. sinapsis_core/exceptions/agent_exceptions.py +2 -0
  22. sinapsis_core/hooks/__init__.py +15 -0
  23. sinapsis_core/hooks/pre_init_hook_registry.py +225 -0
  24. sinapsis_core/template_base/__init__.py +10 -0
  25. sinapsis_core/template_base/base_models.py +59 -0
  26. sinapsis_core/template_base/copy_data_container.py +46 -0
  27. sinapsis_core/template_base/dynamic_template.py +169 -0
  28. sinapsis_core/template_base/dynamic_template_factory.py +454 -0
  29. sinapsis_core/template_base/dynamic_template_helpers/__init__.py +0 -0
  30. sinapsis_core/template_base/dynamic_template_helpers/builder_methods.py +92 -0
  31. sinapsis_core/template_base/dynamic_template_helpers/signature_parser.py +625 -0
  32. sinapsis_core/template_base/empty_data_container.py +23 -0
  33. sinapsis_core/template_base/input_template.py +8 -0
  34. sinapsis_core/template_base/merge_data_flow.py +33 -0
  35. sinapsis_core/template_base/multi_execute_template.py +65 -0
  36. sinapsis_core/template_base/output_template.py +8 -0
  37. sinapsis_core/template_base/split_data_flow.py +50 -0
  38. sinapsis_core/template_base/template.py +292 -0
  39. sinapsis_core/template_base/transfer_data_container.py +13 -0
  40. sinapsis_core/utils/__init__.py +0 -0
  41. sinapsis_core/utils/base_model_updater.py +148 -0
  42. sinapsis_core/utils/doc_string_generator.py +20 -0
  43. sinapsis_core/utils/env_var_keys.py +249 -0
  44. sinapsis_core/utils/env_var_utils.py +6 -0
  45. sinapsis_core/utils/logging_utils.py +53 -0
  46. sinapsis_core-1.0.0.dist-info/METADATA +239 -0
  47. sinapsis_core-1.0.0.dist-info/RECORD +50 -0
  48. sinapsis_core-1.0.0.dist-info/WHEEL +4 -0
  49. sinapsis_core-1.0.0.dist-info/licenses/LICENSE-APACHE +202 -0
  50. sinapsis_core-1.0.0.dist-info/licenses/LICENSE-MIT +21 -0
@@ -0,0 +1,454 @@
1
+ # -*- coding: utf-8 -*-
2
+
3
+ import inspect
4
+
5
+ # from ast import Index
6
+ from typing import Any, Callable, Type, cast
7
+
8
+ from pydantic import BaseModel, ConfigDict, PydanticUserError
9
+
10
+ from sinapsis_core.template_base.dynamic_template import (
11
+ BaseDynamicWrapperTemplate,
12
+ WrapperEntryConfig,
13
+ )
14
+ from sinapsis_core.template_base.dynamic_template_helpers.builder_methods import (
15
+ ArgDictKeywords,
16
+ NoAnnotationError,
17
+ )
18
+ from sinapsis_core.template_base.dynamic_template_helpers.signature_parser import (
19
+ SignatureParser,
20
+ SignatureParserFromDocStr,
21
+ SignatureParserWithMRO,
22
+ )
23
+ from sinapsis_core.utils.logging_utils import sinapsis_logger
24
+
25
+
26
+ class DynamicTemplateFactory:
27
+ """
28
+ Collection of helper methods to build dynamic templates that wrap an existing module, function or class.
29
+ The main interface is `make_dynamic_template`.
30
+
31
+ This class works as a metaclass for dynamic templates. The main difference being that it does not
32
+ implement __new__, and instead the same behaviour is achieved through make_dynamic_template. This
33
+ allows the creation of dynamic templates only when they are imported explicitly. For instance, when
34
+ wrapping a module with multiple attributes, the template for attribute N is only generated if and
35
+ only if it gets imported directly, but the templates for the rest of the attributes are not created.
36
+
37
+ Usage example:
38
+ .. code-block:: python
39
+
40
+ # In foo_module.py
41
+ class FooBase:
42
+ def __init__(self, value: int):
43
+ self.value = value
44
+
45
+ # In ../__init__.py
46
+ from path_to.foo_module import FooBase
47
+ import importlib
48
+
49
+ _module_lookup = {"FooBase": "foobase.base.foo_base"}
50
+
51
+
52
+ def __getattr__(name: str):
53
+ if name in _module_lookup:
54
+ module = importlib.import_module(_module_lookup[name])
55
+ return getattr(module, name)
56
+ raise AttributeError(f"module {__name__} has no attribute {name}")
57
+
58
+
59
+ __all__ = ["FooBase"]
60
+
61
+
62
+ # In templates/dynamic_foo.py
63
+ from sinapsis_core.template_base import Template, TemplateAttributes
64
+ from sinapsis_core.template_base.dynamic_template import BaseDynamicWrapperTemplate, WrapperEntryConfig
65
+ import foo_module
66
+
67
+ class FooDynamicBase(BaseDynamicWrapperTemplate):
68
+ WrapperEntry = WrapperEntryConfig(
69
+ wrapped_object=foo_module,
70
+ )
71
+ UIProperties = UIPropertiesMetadata(category="FooTemplates",
72
+ output_type = OutputTypes.MULTIMODAL)
73
+
74
+ class AttributesBaseModel(TemplateAttributes):
75
+ foo_attribute: str
76
+
77
+ ...
78
+
79
+ def __getattr__(name: str) -> Template:
80
+ if name in FooDynamicBase.WrapperEntry.module_att_names:
81
+ return make_dynamic_template(name, FooDynamicBase)
82
+ raise AttributeError(f"template `{name}` not found in {__name__}")
83
+
84
+ # In templates/__init__.py
85
+ import importlib
86
+ from typing import Callable
87
+
88
+ _root_lib_path = "my_package.templates"
89
+ _template_lookup: dict = {}
90
+ _ADDITIONAL_TEMPLATE_MODULES = [
91
+ f"{_root_lib_path}.dynamic_foo",
92
+ ]
93
+
94
+ for t_module in _ADDITIONAL_TEMPLATE_MODULES:
95
+ _template_lookup |= _import_template_package(t_module)
96
+
97
+ def __getattr__(name: str) -> Callable:
98
+ if name in _template_lookup:
99
+ module = importlib.import_module(_template_lookup[name])
100
+ return getattr(module, name)
101
+ raise AttributeError(f"template `{name}` not found in {_root_lib_path}")
102
+
103
+ __all__ = list(_template_lookup.keys())
104
+
105
+ .. code-block:: yaml
106
+
107
+ # foo_config.yml
108
+ agent:
109
+ name: foo_agent
110
+
111
+ templates:
112
+ - template_name: InputTemplate
113
+ class_name: InputTemplate
114
+ attributes: {}
115
+
116
+ - template_name: FooBaseWrapper
117
+ class_name: FooBaseWrapper
118
+ template_input: InputTemplate
119
+ attributes:
120
+ foo_attribute: string
121
+ foobase_init:
122
+ value: 0
123
+ """
124
+
125
+ CallableSignatureParser: Type[SignatureParser]
126
+
127
+ @classmethod
128
+ def set_parser(cls, base_template: Type[BaseDynamicWrapperTemplate]) -> None:
129
+ """
130
+ Configures the appropriate signature parser based on the base template's configuration settings.
131
+ The parser selection affects how method signatures are analyzed and how type information is extracted.
132
+ The system supports standard signature parsing, docstring-based parsing, and full MRO chain analysis.
133
+
134
+ Args:
135
+ base_template (BaseDynamicWrapperTemplate): Base template class containing parser configuration
136
+ """
137
+ if base_template.WrapperEntry.signature_from_doc_string:
138
+ cls.CallableSignatureParser = SignatureParserFromDocStr
139
+ elif base_template.WrapperEntry.parse_entire_mro:
140
+ cls.CallableSignatureParser = SignatureParserWithMRO
141
+ else:
142
+ cls.CallableSignatureParser = SignatureParser
143
+
144
+ @classmethod
145
+ def make_dynamic_template(
146
+ cls, template_name: str, base_template: Type[BaseDynamicWrapperTemplate]
147
+ ) -> Type[BaseDynamicWrapperTemplate]:
148
+ """
149
+ Creates a new dynamic template class that inherits from the specified base template and wraps the target object.
150
+ This method orchestrates the entire template creation process, including attribute model generation,
151
+ signature analysis, and proper class hierarchy setup.
152
+
153
+ Args:
154
+ template_name (str): Name for the generated template class
155
+ base_template (BaseDynamicWrapperTemplate): Base template class to inherit from
156
+
157
+ Returns:
158
+ BaseDynamicWrapperTemplate: A new template class that inherits from base_template
159
+
160
+ Raises:
161
+ AttributeError: When template creation fails due to missing or invalid type annotations
162
+ """
163
+ cls.set_parser(base_template)
164
+
165
+ try:
166
+ base_atts_class, callable_object = cls._make_attributes_base_model(template_name, base_template)
167
+ except NoAnnotationError as err:
168
+ sinapsis_logger.error(f"Unable to create dynamic template for '{template_name}', error found: {err}")
169
+ # attribute error given this is called from __getattr__
170
+ raise AttributeError(f"Unable to create dynamic template for '{template_name}'")
171
+
172
+ args_dict = {
173
+ BaseDynamicWrapperTemplate.CALLABLE_ATT_NAME: callable_object,
174
+ "AttributesBaseModel": base_atts_class,
175
+ ArgDictKeywords.module: base_template.__module__,
176
+ ArgDictKeywords.annotations: base_template.__annotations__
177
+ | {BaseDynamicWrapperTemplate.CALLABLE_ATT_NAME: Callable},
178
+ ArgDictKeywords.docs: cls._make_template_doc_string(base_template, callable_object),
179
+ }
180
+ return type(template_name, (base_template,), args_dict)
181
+
182
+ @classmethod
183
+ def _make_attributes_base_model(
184
+ cls, template_name: str, base_template: Type[BaseDynamicWrapperTemplate]
185
+ ) -> tuple[Type[BaseModel], Callable]:
186
+ """
187
+ Builds a template's AttributesBaseModel. First, sub BaseModels are built the base_template.WrapperEntry[
188
+ wrapped_object, method_names_to_inspect, additional_callables_to_inspect]. method_names_to_inspect is
189
+ only looked at if wrapped_object is a class object.
190
+ Once all the sub BaseModels are created, AttributesBaseModel is dynamically created as a child class
191
+ of base_template.AttributesBaseModel with the sub BaseModels, if any, as attributes.
192
+
193
+ Notes:
194
+ - Given that sub-base models are created based on inspection of a callables signature,
195
+ if an argument_name is in annotations but not in args_dict, it is made a required attribute.
196
+
197
+ Args:
198
+ template_name (str): Name of the template for which the AttributesBaseModel is built. The base model
199
+ will use f"{template_name}Attributes" as name.
200
+ base_template (BaseDynamicWrapperTemplate): Child class of BaseDynamicWrapperTemplate and must have
201
+ a WrapperEntry with the desired callable to wrap and any other methods.
202
+
203
+ Returns:
204
+ tuple[BaseModel, Callable]: Returns a tuple (attribute_model, callable_object), where
205
+ attribute_model is the generated Pydantic model class for attributes, and callable_object
206
+ is the wrapped object that will be used by the template
207
+
208
+ Raises:
209
+ NoAnnotationError: When required type annotations are missing
210
+ """
211
+ base_atts_class = base_template.AttributesBaseModel
212
+ sub_models_dict, callable_object = cls._make_signature_base_models(template_name, base_template.WrapperEntry)
213
+
214
+ args_dict: dict[str, Any] = {}
215
+
216
+ combined_annotations = {}
217
+ sub_model_doc_strs = ""
218
+ for sub_model_name, sub_model_def in sub_models_dict.items():
219
+ combined_annotations[sub_model_name] = sub_model_def
220
+ sub_model_doc_strs += f"{sub_model_name}{sub_model_def.__doc__}"
221
+
222
+ parent_doc_str = f"{base_atts_class.__doc__ or ''}{sub_model_doc_strs}"
223
+ args_dict[ArgDictKeywords.docs] = parent_doc_str
224
+ args_dict[ArgDictKeywords.module] = base_atts_class.__module__
225
+ args_dict[ArgDictKeywords.annotations] = combined_annotations # + rest
226
+ return (
227
+ cls.__make_pydantic_base_model(f"{template_name}Attributes", args_dict, base_atts_class),
228
+ callable_object,
229
+ )
230
+
231
+ @classmethod
232
+ def _make_sub_attribute_base_models(cls) -> BaseModel: # type:ignore[empty-body]
233
+ """
234
+ Make sub attribute base models for every inspected function, method or class.
235
+ These are to be added to the generated template's AttributesBaseModel.
236
+ """
237
+
238
+ @classmethod
239
+ def _make_template_doc_string(
240
+ cls, base_template: Type[BaseDynamicWrapperTemplate], callable_object: Callable
241
+ ) -> str:
242
+ """Combines documentation from the base template and wrapped object into a comprehensive
243
+ docstring. Handles both class and function documentation, including initialization
244
+ method documentation for classes.
245
+
246
+ Args:
247
+ base_template (BaseDynamicWrapperTemplate): Template class containing base documentation
248
+ callable_object (Callable): Wrapped object whose documentation will be included
249
+
250
+ Returns:
251
+ str: Returns a formatted docstring combining template and wrapped object documentation
252
+ """
253
+ callable_doc_str = (inspect.getdoc(callable_object) or "").replace("\n", "\n >>\t")
254
+ if inspect.isclass(callable_object):
255
+ init_doc_str = getattr(callable_object, ArgDictKeywords.init).__doc__
256
+ if init_doc_str:
257
+ callable_doc_str += init_doc_str.replace("\n", "\n >>\t")
258
+
259
+ base_doc_str = (
260
+ f"{inspect.getdoc(base_template)} \n\n{callable_object.__name__} inherited docs: \n >>\t{callable_doc_str}"
261
+ )
262
+ return base_doc_str
263
+
264
+ @classmethod
265
+ def _make_signature_base_models(
266
+ cls,
267
+ template_name: str,
268
+ wrapper_config: WrapperEntryConfig,
269
+ base_models: dict[str, Type[BaseModel]] | None = None,
270
+ ) -> tuple[dict[str, Type[BaseModel]], Callable]:
271
+ """
272
+ Analyzes callable signatures and generates corresponding Pydantic models for type-safe attribute handling.
273
+ This method processes functions, classes, and modules to create appropriate model structures.
274
+
275
+ Args:
276
+ template_name (str): Name of the template being created
277
+ wrapper_config (WrapperEntryConfig): Configuration for wrapper generation
278
+ base_models (dict[str, BaseModel] | None): Existing base models to extend
279
+
280
+ Returns:
281
+ tuple[dict[str, BaseModel], Callable]: Returns a tuple (base_models, object_to_inspect), where
282
+ base_models is a dictionary mapping attribute names to their corresponding Pydantic models,
283
+ and object_to_inspect is the actual callable object (class, function, or method) that was
284
+ extracted from the wrapper_config and will be wrapped by the template.
285
+
286
+ Raises:
287
+ ValueError: If the object_to_inspect is neither a class nor a function
288
+ """
289
+ if base_models is None:
290
+ base_models = {}
291
+
292
+ object_to_inspect = wrapper_config.wrapped_object
293
+
294
+ if inspect.ismodule(object_to_inspect): # if a module, get the desired specific callable
295
+ object_to_inspect = getattr(object_to_inspect, wrapper_config.strip_suffix(template_name))
296
+
297
+ #######
298
+ if inspect.isclass(object_to_inspect):
299
+ base_models |= cls._make_class_base_models(object_to_inspect, wrapper_config)
300
+
301
+ elif inspect.isfunction(object_to_inspect) or inspect.ismethod(object_to_inspect):
302
+ base_models[object_to_inspect.__name__] = cls._make_single_callable_base_model(
303
+ object_to_inspect, wrapper_config
304
+ )
305
+
306
+ else:
307
+ raise ValueError("Unknown object_to_inspect type")
308
+
309
+ for additional_wrapper_config in wrapper_config.additional_callables_to_inspect:
310
+ return cls._make_signature_base_models(template_name, additional_wrapper_config, base_models)
311
+
312
+ return base_models, object_to_inspect
313
+
314
+ @classmethod
315
+ def _make_single_callable_base_model(
316
+ cls,
317
+ callable_object: Callable,
318
+ wrapped_entry: WrapperEntryConfig,
319
+ # allow_arbitrary_kwargs: bool,
320
+ ) -> type[BaseModel]:
321
+ """
322
+ Creates a Pydantic model for a single callable object by analyzing its signature and type hints.
323
+ This method handles parameter type inference and default value processing.
324
+
325
+ Args:
326
+ callable_object (Callable): Function or method to analyze
327
+ wrapped_entry (WrapperEntryConfig): configuration of the wrapper, where the methods to exclude and the
328
+ flag to allow arbitrary kwargs are set.
329
+
330
+ Returns:
331
+ BaseModel: Generated Pydantic model for the callable parameters
332
+ """
333
+ params_dict, params_type_hints = cls.CallableSignatureParser.parse_callable_signature(callable_object)
334
+
335
+ for exclude_attr in wrapped_entry.exclude_method_attributes:
336
+ params_dict.pop(exclude_attr, None)
337
+ params_type_hints.pop(exclude_attr, None)
338
+
339
+ model_name = f"{callable_object.__name__}Attributes"
340
+ return cls.__make_pydantic_base_model(
341
+ model_name,
342
+ cls.__make_sub_base_model_args(params_dict, params_type_hints, wrapped_entry.allow_arbitrary_kwargs),
343
+ )
344
+
345
+ @classmethod
346
+ def _make_class_base_models(
347
+ cls, class_object: Callable, wrapped_entry: WrapperEntryConfig
348
+ ) -> dict[str, Type[BaseModel]]:
349
+ """
350
+ Generates Pydantic models for a class and its specified methods by analyzing their signatures.
351
+ This method handles initialization parameters and additional method parameters, creating separate
352
+ models for each component while maintaining proper type safety and validation.
353
+
354
+ Args:
355
+ class_object (Callable): Class to analyze and create models for
356
+ wrapped_entry (WrapperEntryConfig): Config of the wrapper object, where the names of the methods
357
+ to inspect and the flags to force init as true an allow arbitrary kwargs are set.
358
+
359
+
360
+ Returns:
361
+ dict[str, BaseModel]: Returns a dictionary where keys are method names and values are
362
+ their corresponding Pydantic models for parameter validation
363
+ """
364
+
365
+ base_models = {}
366
+ object_to_inspect = (
367
+ getattr(class_object, ArgDictKeywords.init) if wrapped_entry.force_init_as_method else class_object
368
+ )
369
+
370
+ base_models[f"{class_object.__name__.lower()}_init"] = cls._make_single_callable_base_model(
371
+ object_to_inspect, wrapped_entry
372
+ )
373
+
374
+ for method_name in wrapped_entry.method_names_to_inspect:
375
+ method_object = getattr(class_object, method_name)
376
+ base_models[method_name] = cls._make_single_callable_base_model(method_object, wrapped_entry)
377
+ return base_models
378
+
379
+ @classmethod
380
+ def _make_atts_base_model_doc_string(cls, params_dict: dict, params_type_hints: dict) -> str:
381
+ """
382
+ Constructs a comprehensive docstring for the generated attribute base model by combining
383
+ parameter information and type hints into a formatted string representation.
384
+
385
+ Args:
386
+ params_dict (dict): Dictionary of parameter names and their default values
387
+ params_type_hints (dict): Dictionary of parameter names and their type annotations
388
+
389
+ Returns:
390
+ str: Formatted docstring containing parameter and type information
391
+ """
392
+ doc_str_lines = []
393
+ for param_name, param_annotation in params_type_hints.items():
394
+ doc_str = f"\t{param_name:30}{param_annotation}"
395
+ if param_name in params_dict:
396
+ doc_str += f": default: {params_dict[param_name]}"
397
+ doc_str_lines.append(doc_str)
398
+ return "".join([f"\n\t{doc_str_line}" for doc_str_line in doc_str_lines])
399
+
400
+ @classmethod
401
+ def __make_sub_base_model_args(
402
+ cls, params_dict: dict, params_type_hints: dict, allow_arbitrary_kwargs: bool
403
+ ) -> dict:
404
+ """
405
+ Prepares the arguments dictionary used for creating a Pydantic sub-model by combining
406
+ parameter information, type hints, and configuration settings into a format suitable
407
+ for dynamic class creation.
408
+
409
+ Args:
410
+ params_dict (dict): Parameter names and default values
411
+ params_type_hints (dict): Parameter names and type annotations
412
+ allow_arbitrary_kwargs (bool): Whether to allow additional keyword arguments
413
+
414
+ Returns:
415
+ dict[str, Any]: Prepared arguments dictionary for Pydantic model creation
416
+ """
417
+ params_dict[ArgDictKeywords.module] = __name__
418
+ params_dict[ArgDictKeywords.annotations] = params_type_hints
419
+ params_dict[ArgDictKeywords.docs] = cls._make_atts_base_model_doc_string(params_dict, params_type_hints)
420
+ if allow_arbitrary_kwargs:
421
+ params_dict["model_config"] = ConfigDict(arbitrary_types_allowed=True, extra="allow")
422
+ return params_dict
423
+
424
+ @classmethod
425
+ def __make_pydantic_base_model(
426
+ cls,
427
+ model_name: str,
428
+ args_dict: dict[str, Any],
429
+ parent_base_model: Type[BaseModel] | None = None,
430
+ ) -> Type[BaseModel]:
431
+ """
432
+ Defines a pydantic base model dynamically. If a parent_base_model is specified, the new base model inherits
433
+ from it. Else it inherits from BaseModel.
434
+ Args:
435
+ model_name (str): Name for the generated model class
436
+ args_dict (dict[str, Any]): Arguments dictionary for model creation
437
+ parent_base_model (BaseModel | None): Optional parent model to inherit from
438
+
439
+ Returns:
440
+ BaseModel: Returns either a new Pydantic model class with the specified configuration,
441
+ or the base BaseModel class if model creation fails
442
+ """
443
+ try:
444
+ dynamic_base_model = type(model_name, (parent_base_model or BaseModel,), args_dict)
445
+ dynamic_base_model = cast(Type[BaseModel], dynamic_base_model)
446
+ return dynamic_base_model
447
+
448
+ except PydanticUserError:
449
+ error_msg = f"Unable to parse some args in: {model_name}."
450
+ sinapsis_logger.warning(error_msg)
451
+ return BaseModel
452
+
453
+
454
+ make_dynamic_template = DynamicTemplateFactory.make_dynamic_template
@@ -0,0 +1,92 @@
1
+ # -*- coding: utf-8 -*-
2
+ import re
3
+ import typing
4
+ from dataclasses import dataclass
5
+
6
+ # we need both to be able to eval string typing annotations
7
+ from typing import * # noqa: F403 undefined-local-with-import-star
8
+
9
+
10
+ @dataclass(frozen=True)
11
+ class ArgDictKeywords:
12
+ module: str = "__module__"
13
+ annotations: str = "__annotations__"
14
+ docs: str = "__doc__"
15
+ attributes: str = "AttributesBaseModel"
16
+ init: str = "__init__"
17
+
18
+
19
+ class NoAnnotationError(Exception):
20
+ pass
21
+
22
+
23
+ def evaluate_str_type_annotation(str_type_annotation: str) -> dict[str, typing.Any] | None:
24
+ """Takes a string representation of a type annotation and attempts to evaluate it
25
+ into a proper typing object using Python's ForwardRef mechanism.
26
+
27
+ Args:
28
+ str_type_annotation (str): String representation of a type annotation
29
+ Example: "List[int]", "Dict[str, Any]", "Optional[str]"
30
+
31
+ Returns:
32
+ dict[str, Any]: The evaluated type annotation object or None if evaluation fails
33
+
34
+ Examples:
35
+ >>> evaluate_str_type_annotation("List[int]")
36
+ typing.List[int]
37
+ >>> evaluate_str_type_annotation("Dict[str, Any]")
38
+ typing.Dict[str, typing.Any]
39
+
40
+ Exceptions:
41
+ NameError or SyntaxError: Internally caught when type cannot be evaluated
42
+
43
+ Limitations:
44
+ - Cannot evaluate custom types not in typing module
45
+ """
46
+ try:
47
+ arg_annotation = typing.ForwardRef(str_type_annotation, is_argument=True, is_class=False)._evaluate(
48
+ globalns=globals(), localns=locals(), recursive_guard=frozenset()
49
+ )
50
+
51
+ except (NameError, SyntaxError):
52
+ arg_annotation = typing.Any
53
+ return arg_annotation
54
+
55
+
56
+ def extract_set_from_docstring_annotation(doc_annotation: typing.Any) -> tuple[str, ...]:
57
+ """Parses docstring annotations that contain sets of options defined in curly braces {},
58
+ cleaning and converting them to a tuple of strings.
59
+
60
+ Args:
61
+ doc_annotation: A docstring containing a set definition in curly braces
62
+ Example: "Options: {'option1', 'option2', 'option3'}"
63
+
64
+ Returns:
65
+ tuple[str, ...]: Cleaned tuple of string options
66
+
67
+ Examples:
68
+ >>> extract_set_from_docstring_annotation("Options: {'red', 'blue', 'green'}")
69
+ ('red', 'blue', 'green')
70
+ >>> extract_set_from_docstring_annotation("{1, 2, 3}")
71
+ ('1', '2', '3')
72
+
73
+ Notes:
74
+ - Strips quotes and whitespace from options
75
+ - Converts all values to strings
76
+ - Maintains order through tuple conversion
77
+
78
+ Limitations:
79
+ - Only processes first set found in docstring
80
+ - Cannot handle nested sets
81
+ - All values are converted to strings
82
+ """
83
+ # Use re.search with a raw string and non-greedy/character class matching
84
+ match = re.search(r"\{([^}]+)\}", str(doc_annotation))
85
+ if not match:
86
+ return ()
87
+
88
+ # Use a list comprehension [...] instead of a set {...} to preserve order
89
+ raw_items = match.group(1).split(",")
90
+ options = tuple(x.strip().strip("'").strip('"') for x in raw_items)
91
+
92
+ return options