From 12c21641013c5dd21357929367ab3d72640f78db Mon Sep 17 00:00:00 2001
From: piyush0049 <piyushjoshi81204@gmail.com>
Date: Tue, 16 Jun 2026 20:28:11 +0530
Subject: [PATCH] docs: add reference documentation for docker.utils module

Signed-off-by: piyush0049 <piyushjoshi81204@gmail.com>
---
 docker/utils/utils.py | 40 ++++++++++++++++++++++++++++++++++++++--
 docs/index.rst        |  1 +
 docs/utils.rst        |  8 ++++++++
 3 files changed, 47 insertions(+), 2 deletions(-)
 create mode 100644 docs/utils.rst

diff --git a/docker/utils/utils.py b/docker/utils/utils.py
index f36a3afb89..25ca3f5537 100644
--- a/docker/utils/utils.py
+++ b/docker/utils/utils.py
@@ -351,6 +351,25 @@ def parse_devices(devices):
 
 
 def kwargs_from_env(environment=None):
+    """
+    Configure client arguments based on the environment variables.
+
+    Reads environment variables like ``DOCKER_HOST``, ``DOCKER_CERT_PATH``, and
+    ``DOCKER_TLS_VERIFY`` to configure communication with the Docker daemon.
+
+    Args:
+        environment (dict, optional): A dictionary representing the environment
+            variables to use. Defaults to ``os.environ``.
+
+    Returns:
+        dict: A dictionary of configuration options (e.g., ``base_url``,
+        ``tls``) that can be passed as keyword arguments to instantiate
+        a :py:class:`~docker.client.DockerClient` or :py:class:`~docker.api.client.APIClient`.
+
+    Example:
+        >>> kwargs = docker.utils.kwargs_from_env()
+        >>> client = docker.DockerClient(**kwargs)
+    """
     if not environment:
         environment = os.environ
     host = environment.get('DOCKER_HOST')
@@ -457,8 +476,25 @@ def normalize_links(links):
 
 def parse_env_file(env_file):
     """
-    Reads a line-separated environment file.
-    The format of each line should be "key=value".
+    Parse a line-separated environment file.
+
+    Reads a file containing ``KEY=VALUE`` environment variable pairs, ignoring
+    comments (lines starting with ``#``) and empty lines, and returns them as a
+    dictionary.
+
+    Args:
+        env_file (str): Path to the environment file.
+
+    Returns:
+        dict: A dictionary mapping environment variable names to their values.
+
+    Raises:
+        docker.errors.DockerException: If a line in the environment file
+            is malformed (does not contain a ``=`` character).
+
+    Example:
+        >>> env_vars = docker.utils.parse_env_file('path/to/.env')
+        >>> client.containers.run('ubuntu', environment=env_vars)
     """
     environment = {}
 
diff --git a/docs/index.rst b/docs/index.rst
index 93b30d4a07..3630fc3e16 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -92,5 +92,6 @@ That's just a taste of what you can do with the Docker SDK for Python. For more,
   volumes
   api
   tls
+  utils
   user_guides/index
   change-log
diff --git a/docs/utils.rst b/docs/utils.rst
new file mode 100644
index 0000000000..8fa924d962
--- /dev/null
+++ b/docs/utils.rst
@@ -0,0 +1,8 @@
+Utilities
+=========
+
+.. py:module:: docker.utils
+
+.. autofunction:: kwargs_from_env
+
+.. autofunction:: parse_env_file