From 0db95fb7bd130efbcfd9ec88c8d0b24f88706349 Mon Sep 17 00:00:00 2001 From: Madeesh Kannan Date: Wed, 6 Mar 2024 16:11:17 +0100 Subject: [PATCH] docs: `haystack.utils` docfixes (#7318) --- docs/pydoc/config/utils_api.yml | 4 ++-- haystack/utils/auth.py | 1 - haystack/utils/filters.py | 4 +++- haystack/utils/jupyter.py | 11 +++-------- haystack/utils/requests_utils.py | 23 ++++++++++++----------- haystack/utils/type_serialization.py | 21 +++++++++++++-------- 6 files changed, 33 insertions(+), 31 deletions(-) diff --git a/docs/pydoc/config/utils_api.yml b/docs/pydoc/config/utils_api.yml index e5550bfc5..2f6f4d80b 100644 --- a/docs/pydoc/config/utils_api.yml +++ b/docs/pydoc/config/utils_api.yml @@ -14,9 +14,9 @@ processors: - type: crossref renderer: type: haystack_pydoc_tools.renderers.ReadmePreviewRenderer - excerpt: Utils API + excerpt: Utility functions and classes used across the library. category_slug: haystack-api - title: Utils API + title: Utils slug: utils-api order: 153 markdown: diff --git a/haystack/utils/auth.py b/haystack/utils/auth.py index c8ba48369..81289dbda 100644 --- a/haystack/utils/auth.py +++ b/haystack/utils/auth.py @@ -31,7 +31,6 @@ class Secret(ABC): from haystack.utils import Secret generator = OpenAIGenerator(api_key=Secret.from_token("")) - ... ``` """ diff --git a/haystack/utils/filters.py b/haystack/utils/filters.py index 13ee16db8..ff99dae7f 100644 --- a/haystack/utils/filters.py +++ b/haystack/utils/filters.py @@ -11,7 +11,9 @@ from haystack.errors import FilterError def document_matches_filter(filters: Dict[str, Any], document: Document) -> bool: """ Return whether `filters` match the Document. - For a detailed specification of the filters, refer to the DocumentStore.filter_documents() protocol documentation. + + For a detailed specification of the filters, refer to the + `DocumentStore.filter_documents()` protocol documentation. """ if "field" in filters: return _comparison_condition(filters, document) diff --git a/haystack/utils/jupyter.py b/haystack/utils/jupyter.py index 3c4ffdc6c..95de65b79 100644 --- a/haystack/utils/jupyter.py +++ b/haystack/utils/jupyter.py @@ -5,15 +5,10 @@ def is_in_jupyter() -> bool: """ - Utility function to easily check if we are in a Jupyter or Google Colab environment. - - Inspired by: - https://github.com/explosion/spaCy/blob/e1249d3722765aaca56f538e830add7014d20e2a/spacy/util.py#L1079 - - Returns True if in Jupyter or Google Colab, False otherwise + Returns `True` if in Jupyter or Google Colab, `False` otherwise. """ - # - # + # Inspired by: + # https://github.com/explosion/spaCy/blob/e1249d3722765aaca56f538e830add7014d20e2a/spacy/util.py#L1079 try: # We don't need to import `get_ipython` as it's always present in Jupyter notebooks if get_ipython().__class__.__name__ == "ZMQInteractiveShell": # type: ignore[name-defined] diff --git a/haystack/utils/requests_utils.py b/haystack/utils/requests_utils.py index 7d2248765..c8716d6a9 100644 --- a/haystack/utils/requests_utils.py +++ b/haystack/utils/requests_utils.py @@ -11,18 +11,9 @@ def request_with_retry( attempts: int = 3, status_codes_to_retry: Optional[List[int]] = None, **kwargs ) -> requests.Response: """ - request_with_retry is a simple wrapper function that executes an HTTP request - with a configurable exponential backoff retry on failures. + Executes an HTTP request with a configurable exponential backoff retry on failures. - All kwargs will be passed to ``requests.request``, so it accepts the same arguments. - - :param attempts: Maximum number of attempts to retry the request. - :param status_codes_to_retry: List of HTTP status codes that will trigger a retry. When param is `None`, HTTP 408, 418, 429 and 503 will be retried. - :param **kwargs: Optional arguments that ``request`` takes. - :return: :class:`Response ` object - - - Usage examples: + Usage example: ```python from haystack.utils import request_with_retry @@ -62,6 +53,16 @@ def request_with_retry( # Retry all 5xx status codes res = request_with_retry(method="GET", url="https://example.com", status_codes_to_retry=list(range(500, 600))) ``` + + :param attempts: + Maximum number of attempts to retry the request. + :param status_codes_to_retry: + List of HTTP status codes that will trigger a retry. + When param is `None`, HTTP 408, 418, 429 and 503 will be retried. + :param kwargs: + Optional arguments that `request` accepts. + :returns: + The `Response` object. """ if status_codes_to_retry is None: diff --git a/haystack/utils/type_serialization.py b/haystack/utils/type_serialization.py index 5d16554b9..0e133c010 100644 --- a/haystack/utils/type_serialization.py +++ b/haystack/utils/type_serialization.py @@ -14,10 +14,12 @@ def serialize_type(target: Any) -> str: It assumes that non-typing objects will have a '__name__' attribute and raises an error if a type cannot be serialized. - :param target: The object to serialize, can be an instance or a type. - :type target: Any - :return: The string representation of the type. - :raises ValueError: If the type cannot be serialized. + :param target: + The object to serialize, can be an instance or a type. + :return: + The string representation of the type. + :raises ValueError: + If the type cannot be serialized. """ # If the target is a string and contains a dot, treat it as an already serialized type if isinstance(target, str) and "." in target: @@ -57,11 +59,14 @@ def deserialize_type(type_str: str) -> Any: Deserializes a type given its full import path as a string, including nested generic types. This function will dynamically import the module if it's not already imported - and then retrieve the type object from it. It also handles nested generic types like 'typing.List[typing.Dict[int, str]]'. + and then retrieve the type object from it. It also handles nested generic types like `typing.List[typing.Dict[int, str]]`. - :param type_str: The string representation of the type's full import path. - :return: The deserialized type object. - :raises DeserializationError: If the type cannot be deserialized due to missing module or type. + :param type_str: + The string representation of the type's full import path. + :returns: + The deserialized type object. + :raises DeserializationError: + If the type cannot be deserialized due to missing module or type. """ def parse_generic_args(args_str):