utils_api.md
1 --- 2 title: "Utils" 3 id: utils-api 4 description: "Utility functions and classes used across the library." 5 slug: "/utils-api" 6 --- 7 8 <a id="azure"></a> 9 10 ## Module azure 11 12 <a id="azure.default_azure_ad_token_provider"></a> 13 14 #### default\_azure\_ad\_token\_provider 15 16 ```python 17 def default_azure_ad_token_provider() -> str 18 ``` 19 20 Get a Azure AD token using the DefaultAzureCredential and the "https://cognitiveservices.azure.com/.default" scope. 21 22 <a id="jupyter"></a> 23 24 ## Module jupyter 25 26 <a id="jupyter.is_in_jupyter"></a> 27 28 #### is\_in\_jupyter 29 30 ```python 31 def is_in_jupyter() -> bool 32 ``` 33 34 Returns `True` if in Jupyter or Google Colab, `False` otherwise. 35 36 <a id="url_validation"></a> 37 38 ## Module url\_validation 39 40 <a id="url_validation.is_valid_http_url"></a> 41 42 #### is\_valid\_http\_url 43 44 ```python 45 def is_valid_http_url(url: str) -> bool 46 ``` 47 48 Check if a URL is a valid HTTP/HTTPS URL. 49 50 <a id="auth"></a> 51 52 ## Module auth 53 54 <a id="auth.SecretType"></a> 55 56 ### SecretType 57 58 <a id="auth.SecretType.from_str"></a> 59 60 #### SecretType.from\_str 61 62 ```python 63 @staticmethod 64 def from_str(string: str) -> "SecretType" 65 ``` 66 67 Convert a string to a SecretType. 68 69 **Arguments**: 70 71 - `string`: The string to convert. 72 73 <a id="auth.Secret"></a> 74 75 ### Secret 76 77 Encapsulates a secret used for authentication. 78 79 Usage example: 80 ```python 81 from haystack.components.generators import OpenAIGenerator 82 from haystack.utils import Secret 83 84 generator = OpenAIGenerator(api_key=Secret.from_token("<here_goes_your_token>")) 85 ``` 86 87 <a id="auth.Secret.from_token"></a> 88 89 #### Secret.from\_token 90 91 ```python 92 @staticmethod 93 def from_token(token: str) -> "Secret" 94 ``` 95 96 Create a token-based secret. Cannot be serialized. 97 98 **Arguments**: 99 100 - `token`: The token to use for authentication. 101 102 <a id="auth.Secret.from_env_var"></a> 103 104 #### Secret.from\_env\_var 105 106 ```python 107 @staticmethod 108 def from_env_var(env_vars: Union[str, list[str]], 109 *, 110 strict: bool = True) -> "Secret" 111 ``` 112 113 Create an environment variable-based secret. Accepts one or more environment variables. 114 115 Upon resolution, it returns a string token from the first environment variable that is set. 116 117 **Arguments**: 118 119 - `env_vars`: A single environment variable or an ordered list of 120 candidate environment variables. 121 - `strict`: Whether to raise an exception if none of the environment 122 variables are set. 123 124 <a id="auth.Secret.to_dict"></a> 125 126 #### Secret.to\_dict 127 128 ```python 129 def to_dict() -> dict[str, Any] 130 ``` 131 132 Convert the secret to a JSON-serializable dictionary. 133 134 Some secrets may not be serializable. 135 136 **Returns**: 137 138 The serialized policy. 139 140 <a id="auth.Secret.from_dict"></a> 141 142 #### Secret.from\_dict 143 144 ```python 145 @staticmethod 146 def from_dict(dict: dict[str, Any]) -> "Secret" 147 ``` 148 149 Create a secret from a JSON-serializable dictionary. 150 151 **Arguments**: 152 153 - `dict`: The dictionary with the serialized data. 154 155 **Returns**: 156 157 The deserialized secret. 158 159 <a id="auth.Secret.resolve_value"></a> 160 161 #### Secret.resolve\_value 162 163 ```python 164 @abstractmethod 165 def resolve_value() -> Optional[Any] 166 ``` 167 168 Resolve the secret to an atomic value. The semantics of the value is secret-dependent. 169 170 **Returns**: 171 172 The value of the secret, if any. 173 174 <a id="auth.Secret.type"></a> 175 176 #### Secret.type 177 178 ```python 179 @property 180 @abstractmethod 181 def type() -> SecretType 182 ``` 183 184 The type of the secret. 185 186 <a id="auth.deserialize_secrets_inplace"></a> 187 188 #### deserialize\_secrets\_inplace 189 190 ```python 191 def deserialize_secrets_inplace(data: dict[str, Any], 192 keys: Iterable[str], 193 *, 194 recursive: bool = False) -> None 195 ``` 196 197 Deserialize secrets in a dictionary inplace. 198 199 **Arguments**: 200 201 - `data`: The dictionary with the serialized data. 202 - `keys`: The keys of the secrets to deserialize. 203 - `recursive`: Whether to recursively deserialize nested dictionaries. 204 205 <a id="callable_serialization"></a> 206 207 ## Module callable\_serialization 208 209 <a id="callable_serialization.serialize_callable"></a> 210 211 #### serialize\_callable 212 213 ```python 214 def serialize_callable(callable_handle: Callable) -> str 215 ``` 216 217 Serializes a callable to its full path. 218 219 **Arguments**: 220 221 - `callable_handle`: The callable to serialize 222 223 **Returns**: 224 225 The full path of the callable 226 227 <a id="callable_serialization.deserialize_callable"></a> 228 229 #### deserialize\_callable 230 231 ```python 232 def deserialize_callable(callable_handle: str) -> Callable 233 ``` 234 235 Deserializes a callable given its full import path as a string. 236 237 **Arguments**: 238 239 - `callable_handle`: The full path of the callable_handle 240 241 **Raises**: 242 243 - `DeserializationError`: If the callable cannot be found 244 245 **Returns**: 246 247 The callable 248 249 <a id="asynchronous"></a> 250 251 ## Module asynchronous 252 253 <a id="asynchronous.is_callable_async_compatible"></a> 254 255 #### is\_callable\_async\_compatible 256 257 ```python 258 def is_callable_async_compatible(func: Callable) -> bool 259 ``` 260 261 Returns if the given callable is usable inside a component's `run_async` method. 262 263 **Arguments**: 264 265 - `callable`: The callable to check. 266 267 **Returns**: 268 269 True if the callable is compatible, False otherwise. 270 271 <a id="requests_utils"></a> 272 273 ## Module requests\_utils 274 275 <a id="requests_utils.request_with_retry"></a> 276 277 #### request\_with\_retry 278 279 ```python 280 def request_with_retry(attempts: int = 3, 281 status_codes_to_retry: Optional[list[int]] = None, 282 **kwargs: Any) -> requests.Response 283 ``` 284 285 Executes an HTTP request with a configurable exponential backoff retry on failures. 286 287 Usage example: 288 ```python 289 from haystack.utils import request_with_retry 290 291 # Sending an HTTP request with default retry configs 292 res = request_with_retry(method="GET", url="https://example.com") 293 294 # Sending an HTTP request with custom number of attempts 295 res = request_with_retry(method="GET", url="https://example.com", attempts=10) 296 297 # Sending an HTTP request with custom HTTP codes to retry 298 res = request_with_retry(method="GET", url="https://example.com", status_codes_to_retry=[408, 503]) 299 300 # Sending an HTTP request with custom timeout in seconds 301 res = request_with_retry(method="GET", url="https://example.com", timeout=5) 302 303 # Sending an HTTP request with custom authorization handling 304 class CustomAuth(requests.auth.AuthBase): 305 def __call__(self, r): 306 r.headers["authorization"] = "Basic <my_token_here>" 307 return r 308 309 res = request_with_retry(method="GET", url="https://example.com", auth=CustomAuth()) 310 311 # All of the above combined 312 res = request_with_retry( 313 method="GET", 314 url="https://example.com", 315 auth=CustomAuth(), 316 attempts=10, 317 status_codes_to_retry=[408, 503], 318 timeout=5 319 ) 320 321 # Sending a POST request 322 res = request_with_retry(method="POST", url="https://example.com", data={"key": "value"}, attempts=10) 323 324 # Retry all 5xx status codes 325 res = request_with_retry(method="GET", url="https://example.com", status_codes_to_retry=list(range(500, 600))) 326 ``` 327 328 **Arguments**: 329 330 - `attempts`: Maximum number of attempts to retry the request. 331 - `status_codes_to_retry`: List of HTTP status codes that will trigger a retry. 332 When param is `None`, HTTP 408, 418, 429 and 503 will be retried. 333 - `kwargs`: Optional arguments that `request` accepts. 334 335 **Returns**: 336 337 The `Response` object. 338 339 <a id="requests_utils.async_request_with_retry"></a> 340 341 #### async\_request\_with\_retry 342 343 ```python 344 async def async_request_with_retry(attempts: int = 3, 345 status_codes_to_retry: Optional[ 346 list[int]] = None, 347 **kwargs: Any) -> httpx.Response 348 ``` 349 350 Executes an asynchronous HTTP request with a configurable exponential backoff retry on failures. 351 352 Usage example: 353 ```python 354 import asyncio 355 from haystack.utils import async_request_with_retry 356 357 # Sending an async HTTP request with default retry configs 358 async def example(): 359 res = await async_request_with_retry(method="GET", url="https://example.com") 360 return res 361 362 # Sending an async HTTP request with custom number of attempts 363 async def example_with_attempts(): 364 res = await async_request_with_retry(method="GET", url="https://example.com", attempts=10) 365 return res 366 367 # Sending an async HTTP request with custom HTTP codes to retry 368 async def example_with_status_codes(): 369 res = await async_request_with_retry(method="GET", url="https://example.com", status_codes_to_retry=[408, 503]) 370 return res 371 372 # Sending an async HTTP request with custom timeout in seconds 373 async def example_with_timeout(): 374 res = await async_request_with_retry(method="GET", url="https://example.com", timeout=5) 375 return res 376 377 # Sending an async HTTP request with custom headers 378 async def example_with_headers(): 379 headers = {"Authorization": "Bearer <my_token_here>"} 380 res = await async_request_with_retry(method="GET", url="https://example.com", headers=headers) 381 return res 382 383 # All of the above combined 384 async def example_combined(): 385 headers = {"Authorization": "Bearer <my_token_here>"} 386 res = await async_request_with_retry( 387 method="GET", 388 url="https://example.com", 389 headers=headers, 390 attempts=10, 391 status_codes_to_retry=[408, 503], 392 timeout=5 393 ) 394 return res 395 396 # Sending an async POST request 397 async def example_post(): 398 res = await async_request_with_retry( 399 method="POST", 400 url="https://example.com", 401 json={"key": "value"}, 402 attempts=10 403 ) 404 return res 405 406 # Retry all 5xx status codes 407 async def example_5xx(): 408 res = await async_request_with_retry( 409 method="GET", 410 url="https://example.com", 411 status_codes_to_retry=list(range(500, 600)) 412 ) 413 return res 414 ``` 415 416 **Arguments**: 417 418 - `attempts`: Maximum number of attempts to retry the request. 419 - `status_codes_to_retry`: List of HTTP status codes that will trigger a retry. 420 When param is `None`, HTTP 408, 418, 429 and 503 will be retried. 421 - `kwargs`: Optional arguments that `httpx.AsyncClient.request` accepts. 422 423 **Returns**: 424 425 The `httpx.Response` object. 426 427 <a id="filters"></a> 428 429 ## Module filters 430 431 <a id="filters.raise_on_invalid_filter_syntax"></a> 432 433 #### raise\_on\_invalid\_filter\_syntax 434 435 ```python 436 def raise_on_invalid_filter_syntax( 437 filters: Optional[dict[str, Any]] = None) -> None 438 ``` 439 440 Raise an error if the filter syntax is invalid. 441 442 <a id="filters.document_matches_filter"></a> 443 444 #### document\_matches\_filter 445 446 ```python 447 def document_matches_filter(filters: dict[str, Any], 448 document: Union[Document, ByteStream]) -> bool 449 ``` 450 451 Return whether `filters` match the Document or the ByteStream. 452 453 For a detailed specification of the filters, refer to the 454 `DocumentStore.filter_documents()` protocol documentation. 455 456 <a id="misc"></a> 457 458 ## Module misc 459 460 <a id="misc.expand_page_range"></a> 461 462 #### expand\_page\_range 463 464 ```python 465 def expand_page_range(page_range: list[Union[str, int]]) -> list[int] 466 ``` 467 468 Takes a list of page numbers and ranges and expands them into a list of page numbers. 469 470 For example, given a page_range=['1-3', '5', '8', '10-12'] the function will return [1, 2, 3, 5, 8, 10, 11, 12] 471 472 **Arguments**: 473 474 - `page_range`: List of page numbers and ranges 475 476 **Returns**: 477 478 An expanded list of page integers 479 480 <a id="misc.expit"></a> 481 482 #### expit 483 484 ```python 485 def expit( 486 x: Union[float, ndarray[Any, Any]]) -> Union[float, ndarray[Any, Any]] 487 ``` 488 489 Compute logistic sigmoid function. Maps input values to a range between 0 and 1 490 491 **Arguments**: 492 493 - `x`: input value. Can be a scalar or a numpy array. 494 495 <a id="device"></a> 496 497 ## Module device 498 499 <a id="device.DeviceType"></a> 500 501 ### DeviceType 502 503 Represents device types supported by Haystack. 504 505 This also includes devices that are not directly used by models - for example, the disk device is exclusively used 506 in device maps for frameworks that support offloading model weights to disk. 507 508 <a id="device.DeviceType.from_str"></a> 509 510 #### DeviceType.from\_str 511 512 ```python 513 @staticmethod 514 def from_str(string: str) -> "DeviceType" 515 ``` 516 517 Create a device type from a string. 518 519 **Arguments**: 520 521 - `string`: The string to convert. 522 523 **Returns**: 524 525 The device type. 526 527 <a id="device.Device"></a> 528 529 ### Device 530 531 A generic representation of a device. 532 533 **Arguments**: 534 535 - `type`: The device type. 536 - `id`: The optional device id. 537 538 <a id="device.Device.__init__"></a> 539 540 #### Device.\_\_init\_\_ 541 542 ```python 543 def __init__(type: DeviceType, id: Optional[int] = None) 544 ``` 545 546 Create a generic device. 547 548 **Arguments**: 549 550 - `type`: The device type. 551 - `id`: The device id. 552 553 <a id="device.Device.cpu"></a> 554 555 #### Device.cpu 556 557 ```python 558 @staticmethod 559 def cpu() -> "Device" 560 ``` 561 562 Create a generic CPU device. 563 564 **Returns**: 565 566 The CPU device. 567 568 <a id="device.Device.gpu"></a> 569 570 #### Device.gpu 571 572 ```python 573 @staticmethod 574 def gpu(id: int = 0) -> "Device" 575 ``` 576 577 Create a generic GPU device. 578 579 **Arguments**: 580 581 - `id`: The GPU id. 582 583 **Returns**: 584 585 The GPU device. 586 587 <a id="device.Device.disk"></a> 588 589 #### Device.disk 590 591 ```python 592 @staticmethod 593 def disk() -> "Device" 594 ``` 595 596 Create a generic disk device. 597 598 **Returns**: 599 600 The disk device. 601 602 <a id="device.Device.mps"></a> 603 604 #### Device.mps 605 606 ```python 607 @staticmethod 608 def mps() -> "Device" 609 ``` 610 611 Create a generic Apple Metal Performance Shader device. 612 613 **Returns**: 614 615 The MPS device. 616 617 <a id="device.Device.xpu"></a> 618 619 #### Device.xpu 620 621 ```python 622 @staticmethod 623 def xpu() -> "Device" 624 ``` 625 626 Create a generic Intel GPU Optimization device. 627 628 **Returns**: 629 630 The XPU device. 631 632 <a id="device.Device.from_str"></a> 633 634 #### Device.from\_str 635 636 ```python 637 @staticmethod 638 def from_str(string: str) -> "Device" 639 ``` 640 641 Create a generic device from a string. 642 643 **Returns**: 644 645 The device. 646 647 <a id="device.DeviceMap"></a> 648 649 ### DeviceMap 650 651 A generic mapping from strings to devices. 652 653 The semantics of the strings are dependent on target framework. Primarily used to deploy HuggingFace models to 654 multiple devices. 655 656 **Arguments**: 657 658 - `mapping`: Dictionary mapping strings to devices. 659 660 <a id="device.DeviceMap.to_dict"></a> 661 662 #### DeviceMap.to\_dict 663 664 ```python 665 def to_dict() -> dict[str, str] 666 ``` 667 668 Serialize the mapping to a JSON-serializable dictionary. 669 670 **Returns**: 671 672 The serialized mapping. 673 674 <a id="device.DeviceMap.first_device"></a> 675 676 #### DeviceMap.first\_device 677 678 ```python 679 @property 680 def first_device() -> Optional[Device] 681 ``` 682 683 Return the first device in the mapping, if any. 684 685 **Returns**: 686 687 The first device. 688 689 <a id="device.DeviceMap.from_dict"></a> 690 691 #### DeviceMap.from\_dict 692 693 ```python 694 @staticmethod 695 def from_dict(dict: dict[str, str]) -> "DeviceMap" 696 ``` 697 698 Create a generic device map from a JSON-serialized dictionary. 699 700 **Arguments**: 701 702 - `dict`: The serialized mapping. 703 704 **Returns**: 705 706 The generic device map. 707 708 <a id="device.DeviceMap.from_hf"></a> 709 710 #### DeviceMap.from\_hf 711 712 ```python 713 @staticmethod 714 def from_hf( 715 hf_device_map: dict[str, Union[int, str, 716 "torch.device"]]) -> "DeviceMap" 717 ``` 718 719 Create a generic device map from a HuggingFace device map. 720 721 **Arguments**: 722 723 - `hf_device_map`: The HuggingFace device map. 724 725 **Returns**: 726 727 The deserialized device map. 728 729 <a id="device.ComponentDevice"></a> 730 731 ### ComponentDevice 732 733 A representation of a device for a component. 734 735 This can be either a single device or a device map. 736 737 <a id="device.ComponentDevice.from_str"></a> 738 739 #### ComponentDevice.from\_str 740 741 ```python 742 @classmethod 743 def from_str(cls, device_str: str) -> "ComponentDevice" 744 ``` 745 746 Create a component device representation from a device string. 747 748 The device string can only represent a single device. 749 750 **Arguments**: 751 752 - `device_str`: The device string. 753 754 **Returns**: 755 756 The component device representation. 757 758 <a id="device.ComponentDevice.from_single"></a> 759 760 #### ComponentDevice.from\_single 761 762 ```python 763 @classmethod 764 def from_single(cls, device: Device) -> "ComponentDevice" 765 ``` 766 767 Create a component device representation from a single device. 768 769 Disks cannot be used as single devices. 770 771 **Arguments**: 772 773 - `device`: The device. 774 775 **Returns**: 776 777 The component device representation. 778 779 <a id="device.ComponentDevice.from_multiple"></a> 780 781 #### ComponentDevice.from\_multiple 782 783 ```python 784 @classmethod 785 def from_multiple(cls, device_map: DeviceMap) -> "ComponentDevice" 786 ``` 787 788 Create a component device representation from a device map. 789 790 **Arguments**: 791 792 - `device_map`: The device map. 793 794 **Returns**: 795 796 The component device representation. 797 798 <a id="device.ComponentDevice.to_torch"></a> 799 800 #### ComponentDevice.to\_torch 801 802 ```python 803 def to_torch() -> "torch.device" 804 ``` 805 806 Convert the component device representation to PyTorch format. 807 808 Device maps are not supported. 809 810 **Returns**: 811 812 The PyTorch device representation. 813 814 <a id="device.ComponentDevice.to_torch_str"></a> 815 816 #### ComponentDevice.to\_torch\_str 817 818 ```python 819 def to_torch_str() -> str 820 ``` 821 822 Convert the component device representation to PyTorch string format. 823 824 Device maps are not supported. 825 826 **Returns**: 827 828 The PyTorch device string representation. 829 830 <a id="device.ComponentDevice.to_spacy"></a> 831 832 #### ComponentDevice.to\_spacy 833 834 ```python 835 def to_spacy() -> int 836 ``` 837 838 Convert the component device representation to spaCy format. 839 840 Device maps are not supported. 841 842 **Returns**: 843 844 The spaCy device representation. 845 846 <a id="device.ComponentDevice.to_hf"></a> 847 848 #### ComponentDevice.to\_hf 849 850 ```python 851 def to_hf() -> Union[Union[int, str], dict[str, Union[int, str]]] 852 ``` 853 854 Convert the component device representation to HuggingFace format. 855 856 **Returns**: 857 858 The HuggingFace device representation. 859 860 <a id="device.ComponentDevice.update_hf_kwargs"></a> 861 862 #### ComponentDevice.update\_hf\_kwargs 863 864 ```python 865 def update_hf_kwargs(hf_kwargs: dict[str, Any], *, 866 overwrite: bool) -> dict[str, Any] 867 ``` 868 869 Convert the component device representation to HuggingFace format. 870 871 Add them as canonical keyword arguments to the keyword arguments dictionary. 872 873 **Arguments**: 874 875 - `hf_kwargs`: The HuggingFace keyword arguments dictionary. 876 - `overwrite`: Whether to overwrite existing device arguments. 877 878 **Returns**: 879 880 The HuggingFace keyword arguments dictionary. 881 882 <a id="device.ComponentDevice.has_multiple_devices"></a> 883 884 #### ComponentDevice.has\_multiple\_devices 885 886 ```python 887 @property 888 def has_multiple_devices() -> bool 889 ``` 890 891 Whether this component device representation contains multiple devices. 892 893 <a id="device.ComponentDevice.first_device"></a> 894 895 #### ComponentDevice.first\_device 896 897 ```python 898 @property 899 def first_device() -> Optional["ComponentDevice"] 900 ``` 901 902 Return either the single device or the first device in the device map, if any. 903 904 **Returns**: 905 906 The first device. 907 908 <a id="device.ComponentDevice.resolve_device"></a> 909 910 #### ComponentDevice.resolve\_device 911 912 ```python 913 @staticmethod 914 def resolve_device( 915 device: Optional["ComponentDevice"] = None) -> "ComponentDevice" 916 ``` 917 918 Select a device for a component. If a device is specified, it's used. Otherwise, the default device is used. 919 920 **Arguments**: 921 922 - `device`: The provided device, if any. 923 924 **Returns**: 925 926 The resolved device. 927 928 <a id="device.ComponentDevice.to_dict"></a> 929 930 #### ComponentDevice.to\_dict 931 932 ```python 933 def to_dict() -> dict[str, Any] 934 ``` 935 936 Convert the component device representation to a JSON-serializable dictionary. 937 938 **Returns**: 939 940 The dictionary representation. 941 942 <a id="device.ComponentDevice.from_dict"></a> 943 944 #### ComponentDevice.from\_dict 945 946 ```python 947 @classmethod 948 def from_dict(cls, dict: dict[str, Any]) -> "ComponentDevice" 949 ``` 950 951 Create a component device representation from a JSON-serialized dictionary. 952 953 **Arguments**: 954 955 - `dict`: The serialized representation. 956 957 **Returns**: 958 959 The deserialized component device. 960 961 <a id="http_client"></a> 962 963 ## Module http\_client 964 965 <a id="http_client.init_http_client"></a> 966 967 #### init\_http\_client 968 969 ```python 970 def init_http_client( 971 http_client_kwargs: Optional[dict[str, Any]] = None, 972 async_client: bool = False 973 ) -> Union[httpx.Client, httpx.AsyncClient, None] 974 ``` 975 976 Initialize an httpx client based on the http_client_kwargs. 977 978 **Arguments**: 979 980 - `http_client_kwargs`: The kwargs to pass to the httpx client. 981 - `async_client`: Whether to initialize an async client. 982 983 **Returns**: 984 985 A httpx client or an async httpx client. 986 987 <a id="type_serialization"></a> 988 989 ## Module type\_serialization 990 991 <a id="type_serialization.serialize_type"></a> 992 993 #### serialize\_type 994 995 ```python 996 def serialize_type(target: Any) -> str 997 ``` 998 999 Serializes a type or an instance to its string representation, including the module name. 1000 1001 This function handles types, instances of types, and special typing objects. 1002 It assumes that non-typing objects will have a '__name__' attribute. 1003 1004 **Arguments**: 1005 1006 - `target`: The object to serialize, can be an instance or a type. 1007 1008 **Returns**: 1009 1010 The string representation of the type. 1011 1012 <a id="type_serialization.deserialize_type"></a> 1013 1014 #### deserialize\_type 1015 1016 ```python 1017 def deserialize_type(type_str: str) -> Any 1018 ``` 1019 1020 Deserializes a type given its full import path as a string, including nested generic types. 1021 1022 This function will dynamically import the module if it's not already imported 1023 and then retrieve the type object from it. It also handles nested generic types like 1024 `list[dict[int, str]]`. 1025 1026 **Arguments**: 1027 1028 - `type_str`: The string representation of the type's full import path. 1029 1030 **Raises**: 1031 1032 - `DeserializationError`: If the type cannot be deserialized due to missing module or type. 1033 1034 **Returns**: 1035 1036 The deserialized type object. 1037 1038 <a id="type_serialization.thread_safe_import"></a> 1039 1040 #### thread\_safe\_import 1041 1042 ```python 1043 def thread_safe_import(module_name: str) -> ModuleType 1044 ``` 1045 1046 Import a module in a thread-safe manner. 1047 1048 Importing modules in a multi-threaded environment can lead to race conditions. 1049 This function ensures that the module is imported in a thread-safe manner without having impact 1050 on the performance of the import for single-threaded environments. 1051 1052 **Arguments**: 1053 1054 - `module_name`: the module to import 1055 1056 <a id="jinja2_chat_extension"></a> 1057 1058 ## Module jinja2\_chat\_extension 1059 1060 <a id="jinja2_chat_extension.ChatMessageExtension"></a> 1061 1062 ### ChatMessageExtension 1063 1064 A Jinja2 extension for creating structured chat messages with mixed content types. 1065 1066 This extension provides a custom `{% message %}` tag that allows creating chat messages 1067 with different attributes (role, name, meta) and mixed content types (text, images, etc.). 1068 1069 Inspired by [Banks](https://github.com/masci/banks). 1070 1071 **Example**: 1072 1073 ``` 1074 {% message role="system" %} 1075 You are a helpful assistant. You like to talk with {{user_name}}. 1076 {% endmessage %} 1077 1078 {% message role="user" %} 1079 Hello! I am {{user_name}}. Please describe the images. 1080 {% for image in images %} 1081 {{ image | templatize_part }} 1082 {% endfor %} 1083 {% endmessage %} 1084 ``` 1085 1086 ### How it works 1087 1. The `{% message %}` tag is used to define a chat message. 1088 2. The message can contain text and other structured content parts. 1089 3. To include a structured content part in the message, the `| templatize_part` filter is used. 1090 The filter serializes the content part into a JSON string and wraps it in a `<haystack_content_part>` tag. 1091 4. The `_build_chat_message_json` method of the extension parses the message content parts, 1092 converts them into a ChatMessage object and serializes it to a JSON string. 1093 5. The obtained JSON string is usable in the ChatPromptBuilder component, where templates are rendered to actual 1094 ChatMessage objects. 1095 1096 <a id="jinja2_chat_extension.ChatMessageExtension.parse"></a> 1097 1098 #### ChatMessageExtension.parse 1099 1100 ```python 1101 def parse(parser: Any) -> Union[nodes.Node, list[nodes.Node]] 1102 ``` 1103 1104 Parse the message tag and its attributes in the Jinja2 template. 1105 1106 This method handles the parsing of role (mandatory), name (optional), meta (optional) and message body content. 1107 1108 **Arguments**: 1109 1110 - `parser`: The Jinja2 parser instance 1111 1112 **Raises**: 1113 1114 - `TemplateSyntaxError`: If an invalid role is provided 1115 1116 **Returns**: 1117 1118 A CallBlock node containing the parsed message configuration 1119 1120 <a id="jinja2_chat_extension.templatize_part"></a> 1121 1122 #### templatize\_part 1123 1124 ```python 1125 def templatize_part(value: ChatMessageContentT) -> str 1126 ``` 1127 1128 Jinja filter to convert an ChatMessageContentT object into JSON string wrapped in special XML content tags. 1129 1130 **Arguments**: 1131 1132 - `value`: The ChatMessageContentT object to convert 1133 1134 **Raises**: 1135 1136 - `ValueError`: If the value is not an instance of ChatMessageContentT 1137 1138 **Returns**: 1139 1140 A JSON string wrapped in special XML content tags 1141 1142 <a id="jinja2_extensions"></a> 1143 1144 ## Module jinja2\_extensions 1145 1146 <a id="jinja2_extensions.Jinja2TimeExtension"></a> 1147 1148 ### Jinja2TimeExtension 1149 1150 <a id="jinja2_extensions.Jinja2TimeExtension.__init__"></a> 1151 1152 #### Jinja2TimeExtension.\_\_init\_\_ 1153 1154 ```python 1155 def __init__(environment: Environment) 1156 ``` 1157 1158 Initializes the JinjaTimeExtension object. 1159 1160 **Arguments**: 1161 1162 - `environment`: The Jinja2 environment to initialize the extension with. 1163 It provides the context where the extension will operate. 1164 1165 <a id="jinja2_extensions.Jinja2TimeExtension.parse"></a> 1166 1167 #### Jinja2TimeExtension.parse 1168 1169 ```python 1170 def parse(parser: Any) -> Union[nodes.Node, list[nodes.Node]] 1171 ``` 1172 1173 Parse the template expression to determine how to handle the datetime formatting. 1174 1175 **Arguments**: 1176 1177 - `parser`: The parser object that processes the template expressions and manages the syntax tree. 1178 It's used to interpret the template's structure. 1179 1180 <a id="deserialization"></a> 1181 1182 ## Module deserialization 1183 1184 <a id="deserialization.deserialize_document_store_in_init_params_inplace"></a> 1185 1186 #### deserialize\_document\_store\_in\_init\_params\_inplace 1187 1188 ```python 1189 def deserialize_document_store_in_init_params_inplace( 1190 data: dict[str, Any], key: str = "document_store") -> None 1191 ``` 1192 1193 Deserializes a generic document store from the init_parameters of a serialized component in place. 1194 1195 **Arguments**: 1196 1197 - `data`: The dictionary to deserialize from. 1198 - `key`: The key in the `data["init_parameters"]` dictionary where the document store is specified. 1199 1200 **Raises**: 1201 1202 - `DeserializationError`: If the document store is not properly specified in the serialization data or its type cannot be imported. 1203 1204 **Returns**: 1205 1206 The dictionary, with the document store deserialized. 1207 1208 <a id="deserialization.deserialize_chatgenerator_inplace"></a> 1209 1210 #### deserialize\_chatgenerator\_inplace 1211 1212 ```python 1213 def deserialize_chatgenerator_inplace(data: dict[str, Any], 1214 key: str = "chat_generator") -> None 1215 ``` 1216 1217 Deserialize a ChatGenerator in a dictionary inplace. 1218 1219 **Arguments**: 1220 1221 - `data`: The dictionary with the serialized data. 1222 - `key`: The key in the dictionary where the ChatGenerator is stored. 1223 1224 **Raises**: 1225 1226 - `DeserializationError`: If the key is missing in the serialized data, the value is not a dictionary, 1227 the type key is missing, the class cannot be imported, or the class lacks a 'from_dict' method. 1228 1229 <a id="deserialization.deserialize_component_inplace"></a> 1230 1231 #### deserialize\_component\_inplace 1232 1233 ```python 1234 def deserialize_component_inplace(data: dict[str, Any], 1235 key: str = "chat_generator") -> None 1236 ``` 1237 1238 Deserialize a Component in a dictionary inplace. 1239 1240 **Arguments**: 1241 1242 - `data`: The dictionary with the serialized data. 1243 - `key`: The key in the dictionary where the Component is stored. Default is "chat_generator". 1244 1245 **Raises**: 1246 1247 - `DeserializationError`: If the key is missing in the serialized data, the value is not a dictionary, 1248 the type key is missing, the class cannot be imported, or the class lacks a 'from_dict' method. 1249 1250 <a id="base_serialization"></a> 1251 1252 ## Module base\_serialization 1253 1254 <a id="base_serialization.serialize_class_instance"></a> 1255 1256 #### serialize\_class\_instance 1257 1258 ```python 1259 def serialize_class_instance(obj: Any) -> dict[str, Any] 1260 ``` 1261 1262 Serializes an object that has a `to_dict` method into a dictionary. 1263 1264 **Arguments**: 1265 1266 - `obj`: The object to be serialized. 1267 1268 **Raises**: 1269 1270 - `SerializationError`: If the object does not have a `to_dict` method. 1271 1272 **Returns**: 1273 1274 A dictionary representation of the object. 1275 1276 <a id="base_serialization.deserialize_class_instance"></a> 1277 1278 #### deserialize\_class\_instance 1279 1280 ```python 1281 def deserialize_class_instance(data: dict[str, Any]) -> Any 1282 ``` 1283 1284 Deserializes an object from a dictionary representation generated by `auto_serialize_class_instance`. 1285 1286 **Arguments**: 1287 1288 - `data`: The dictionary to deserialize from. 1289 1290 **Raises**: 1291 1292 - `DeserializationError`: If the serialization data is malformed, the class type cannot be imported, or the 1293 class does not have a `from_dict` method. 1294 1295 **Returns**: 1296 1297 The deserialized object. 1298