fixing some more docstrings (#7530)

* some more docstring fixes

* some more docstring fixes

Author: davidsbatista

haystack/core/component/sockets.py

@@ -83,6 +83,7 @@ def __init__(
     def __setitem__(self, key: str, socket: Union[InputSocket, OutputSocket]):
         """
         Adds a new socket to this Sockets object.
+
         This eases a bit updating the list of sockets after Sockets has been created.
         That should happen only in the `component` decorator.
         """

haystack/core/pipeline/descriptions.py

@@ -14,8 +14,9 @@
 
 def find_pipeline_inputs(graph: networkx.MultiDiGraph) -> Dict[str, List[InputSocket]]:
     """
-    Collect components that have disconnected input sockets. Note that this method returns *ALL* disconnected
-    input sockets, including all such sockets with default values.
+    Collect components that have disconnected input sockets.
+
+    Note that this method returns *ALL* disconnected input sockets, including all such sockets with default values.
     """
     return {
         name: [socket for socket in data.get("input_sockets", {}).values() if not socket.senders or socket.is_variadic]

haystack/core/pipeline/pipeline.py

@@ -76,6 +76,8 @@ def __init__(
 
     def __eq__(self, other) -> bool:
         """
+        Pipeline equality is defined by the equality of their serialized form.
+
         Equal pipelines share every metadata, node and edge, but they're not required to use
         the same node instances: this allows pipeline saved and then loaded back to be equal to themselves.
         """
@@ -108,6 +110,7 @@ def __repr__(self) -> str:
     def to_dict(self) -> Dict[str, Any]:
         """
         Serializes the pipeline to a dictionary.
+
         This is meant to be an intermediate representation but it can be also used to save a pipeline to file.
 
         :returns:
@@ -189,8 +192,7 @@ def from_dict(
 
     def dumps(self, marshaller: Marshaller = DEFAULT_MARSHALLER) -> str:
         """
-        Returns the string representation of this pipeline according to the
-        format dictated by the `Marshaller` in use.
+        Returns the string representation of this pipeline according to the format dictated by the `Marshaller` in use.
 
         :param marshaller:
             The Marshaller used to create the string representation. Defaults to `YamlMarshaller`.
@@ -201,8 +203,7 @@ def dumps(self, marshaller: Marshaller = DEFAULT_MARSHALLER) -> str:
 
     def dump(self, fp: TextIO, marshaller: Marshaller = DEFAULT_MARSHALLER):
         """
-        Writes the string representation of this pipeline to the file-like object
-        passed in the `fp` argument.
+        Writes the string representation of this pipeline to the file-like object passed in the `fp` argument.
 
         :param fp:
             A file-like object ready to be written to.
@@ -240,8 +241,7 @@ def load(
         callbacks: Optional[DeserializationCallbacks] = None,
     ) -> "Pipeline":
         """
-        Creates a `Pipeline` object from the string representation read from the file-like
-        object passed in the `fp` argument.
+        Creates a `Pipeline` object from the string representation read from the file-like object passed in the `fp` argument.
 
         :param data:
             The string representation of the pipeline, can be `str`, `bytes` or `bytearray`.
@@ -506,9 +506,10 @@ def get_component_name(self, instance: Component) -> str:
 
     def inputs(self) -> Dict[str, Dict[str, Any]]:
         """
-        Returns a dictionary containing the inputs of a pipeline. Each key in the dictionary
-        corresponds to a component name, and its value is another dictionary that describes the
-        input sockets of that component, including their types and whether they are optional.
+        Returns a dictionary containing the inputs of a pipeline.
+
+        Each key in the dictionary corresponds to a component name, and its value is another dictionary that describes
+        the input sockets of that component, including their types and whether they are optional.
 
         :returns:
             A dictionary where each key is a pipeline component name and each value is a dictionary of
@@ -528,9 +529,10 @@ def inputs(self) -> Dict[str, Dict[str, Any]]:
 
     def outputs(self) -> Dict[str, Dict[str, Any]]:
         """
-        Returns a dictionary containing the outputs of a pipeline. Each key in the dictionary
-        corresponds to a component name, and its value is another dictionary that describes the
-        output sockets of that component.
+        Returns a dictionary containing the outputs of a pipeline.
+
+        Each key in the dictionary corresponds to a component name, and its value is another dictionary that describes
+        the output sockets of that component.
 
         :returns:
             A dictionary where each key is a pipeline component name and each value is a dictionary of
@@ -573,6 +575,7 @@ def draw(self, path: Path) -> None:
     def walk(self) -> Iterator[Tuple[str, Component]]:
         """
         Visits each component in the pipeline exactly once and yields its name and instance.
+
         No guarantees are provided on the visiting order.
 
         :returns:

haystack/core/pipeline/template.py

@@ -22,8 +22,9 @@ class PredefinedPipeline(Enum):
 
 class PipelineTemplate:
     """
-    The PipelineTemplate class enables the straightforward creation of flexible and configurable pipelines using
-    Jinja2 templated YAML files. Specifically designed to simplify the setup of complex data processing pipelines for
+    The PipelineTemplate class enables the straightforward creation of flexible and configurable pipelines using Jinja2 templated YAML files.
+
+    Specifically designed to simplify the setup of complex data processing pipelines for
     a range of NLP tasks—including question answering, retriever augmented generation (RAG), document indexing, among
     others - PipelineTemplate empowers users to dynamically generate pipeline configurations from templates and
     customize components as necessary. Its design philosophy centers on providing an accessible, yet powerful, tool
@@ -60,7 +61,9 @@ class PipelineTemplate:
 
     def __init__(self, template_content: str):
         """
-        Initialize a PipelineTemplate. Besides calling the constructor directly, a set of utility methods is provided
+        Initialize a PipelineTemplate.
+
+        Besides calling the constructor directly, a set of utility methods is provided
         for conveniently create an instance of `PipelineTemplate` from different sources. See `from_string`,
         `from_file`, `from_predefined` and `from_url`.
 
@@ -93,6 +96,7 @@ def render(self, template_params: Optional[Dict[str, Any]] = None) -> str:
     def from_file(cls, file_path: Union[Path, str]) -> "PipelineTemplate":
         """
         Create a PipelineTemplate from a file.
+
         :param file_path: The path to the file containing the template. Must contain valid Jinja2 syntax.
         :returns: An instance of `PipelineTemplate`.
         """
@@ -103,6 +107,7 @@ def from_file(cls, file_path: Union[Path, str]) -> "PipelineTemplate":
     def from_predefined(cls, predefined_pipeline: PredefinedPipeline) -> "PipelineTemplate":
         """
         Create a PipelineTemplate from a predefined template. See `PredefinedPipeline` for available options.
+
         :param predefined_pipeline: The predefined pipeline to use.
         :returns: An instance of `PipelineTemplate `.
         """

haystack/core/serialization.py

@@ -13,8 +13,7 @@
 @dataclass(frozen=True)
 class DeserializationCallbacks:
     """
-    Callback functions that are invoked in specific
-    stages of the pipeline deserialization process.
+    Callback functions that are invoked in specific stages of the pipeline deserialization process.
 
     :param component_pre_init:
         Invoked just before a component instance is

haystack/telemetry/_environment.py

@@ -16,6 +16,8 @@
 
 def _in_podman() -> bool:
     """
+    Check if the code is running in a Podman container.
+
     Podman run would create the file /run/.containernv, see:
     https://github.com/containers/podman/blob/main/docs/source/markdown/podman-run.1.md.in#L31
     """
@@ -24,6 +26,8 @@ def _in_podman() -> bool:
 
 def _has_dockerenv() -> bool:
     """
+    Check if the code is running in a Docker container.
+
     This might not work anymore at some point (even if it's been a while now), see:
     https://github.com/moby/moby/issues/18355#issuecomment-220484748
     """
@@ -32,16 +36,17 @@ def _has_dockerenv() -> bool:
 
 def _has_docker_cgroup_v1() -> bool:
     """
-    This only works with cgroups v1
+    This only works with cgroups v1.
     """
     path = "/proc/self/cgroup"  # 'self' should be always symlinked to the actual PID
     return os.path.isfile(path) and any("docker" in line for line in open(path))
 
 
 def _has_docker_cgroup_v2() -> bool:
     """
-    cgroups v2 version, inspired from
-    https://github.com/jenkinsci/docker-workflow-plugin/blob/master/src/main/java/org/jenkinsci/plugins/docker/workflow/client/DockerClient.java
+    Check if the code is running in a Docker container using the cgroups v2 version.
+
+    inspired from: https://github.com/jenkinsci/docker-workflow-plugin/blob/master/src/main/java/org/jenkinsci/plugins/docker/workflow/client/DockerClient.java
     """
     path = "/proc/self/mountinfo"  # 'self' should be always symlinked to the actual PID
     return os.path.isfile(path) and any("/docker/containers/" in line for line in open(path))
@@ -61,8 +66,9 @@ def _is_containerized() -> Optional[bool]:
 
 def collect_system_specs() -> Dict[str, Any]:
     """
-    Collects meta data about the setup that is used with Haystack, such as:
-    operating system, python version, Haystack version, transformers version,
+    Collects meta-data about the setup that is used with Haystack.
+
+    Data collected includes: operating system, python version, Haystack version, transformers version,
     pytorch version, number of GPUs, execution environment.
 
     These values are highly unlikely to change during the runtime of the pipeline,