From 8097d96e03bf9af0560b7a10b0c607014f983f82 Mon Sep 17 00:00:00 2001 From: sharktide Date: Thu, 6 Mar 2025 10:42:43 -0500 Subject: [PATCH 01/17] gh-130902 Add optional socket shutdown to HTTPConnection.close Similar to gh-130862 but for http library --- Lib/http/client.py | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/Lib/http/client.py b/Lib/http/client.py index 33a858d34ae1ba..4b51c32843956b 100644 --- a/Lib/http/client.py +++ b/Lib/http/client.py @@ -1012,19 +1012,37 @@ def connect(self): if self._tunnel_host: self._tunnel() - def close(self): - """Close the connection to the HTTP server.""" + def close(self, shutdown=False): self.__state = _CS_IDLE try: sock = self.sock if sock: self.sock = None - sock.close() # close it manually... there may be other refs + if shutdown: + try: + sock.shutdown(socket.SHUT_RDWR) + except OSError as e: + print(f"Socket shutdown error: {e}", file=sys.stderr) + except Exception as e: + print(f"Unexpected error during socket shutdown: {e}", file=sys.stderr) + try: + sock.close() + except OSError as e: + print(f"Socket close error: {e}", file=sys.stderr) + except Exception as e: + print(f"Unexpected error during socket close: {e}", file=sys.stderr) finally: response = self.__response if response: self.__response = None - response.close() + try: + response.close() + except OSError as e: + print(f"Response close error: {e}", file=sys.stderr) + except Exception as e: + print(f"Unexpected error during response close: {e}", file=sys.stderr) + + def send(self, data): """Send 'data' to the server. From 1c819a6383208fce270345b2b6705e9c3a6a2e09 Mon Sep 17 00:00:00 2001 From: "blurb-it[bot]" <43283697+blurb-it[bot]@users.noreply.github.com> Date: Thu, 6 Mar 2025 16:31:12 +0000 Subject: [PATCH 02/17] =?UTF-8?q?=F0=9F=93=9C=F0=9F=A4=96=20Added=20by=20b?= =?UTF-8?q?lurb=5Fit.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../Library/2025-03-06-16-31-08.gh-issue-130902.mHAtcq.rst | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 Misc/NEWS.d/next/Library/2025-03-06-16-31-08.gh-issue-130902.mHAtcq.rst diff --git a/Misc/NEWS.d/next/Library/2025-03-06-16-31-08.gh-issue-130902.mHAtcq.rst b/Misc/NEWS.d/next/Library/2025-03-06-16-31-08.gh-issue-130902.mHAtcq.rst new file mode 100644 index 00000000000000..016cda11b5ed71 --- /dev/null +++ b/Misc/NEWS.d/next/Library/2025-03-06-16-31-08.gh-issue-130902.mHAtcq.rst @@ -0,0 +1,4 @@ +Issue: :gh:`130902` + + +Modified close(self) method of HTTPConnection class to include an optional socket shutdown similar to gh-130850. Includes error handling. As mentioned, it adds an optional shutdown param to the close method, keeping existing programs working, but adding an extra feature to new programs that offers improvements. From d98c28ec1ba0870d640ac710d3cba383a47b0eba Mon Sep 17 00:00:00 2001 From: sharktide Date: Thu, 6 Mar 2025 11:34:55 -0500 Subject: [PATCH 03/17] Update client.py --- Lib/http/client.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/Lib/http/client.py b/Lib/http/client.py index 4b51c32843956b..9372048498d91e 100644 --- a/Lib/http/client.py +++ b/Lib/http/client.py @@ -1042,8 +1042,6 @@ def close(self, shutdown=False): except Exception as e: print(f"Unexpected error during response close: {e}", file=sys.stderr) - - def send(self, data): """Send 'data' to the server. ``data`` can be a string object, a bytes object, an array object, a From 3d8c39f850de1c1e83292237ce7d88974ba818ed Mon Sep 17 00:00:00 2001 From: sharktide Date: Thu, 6 Mar 2025 11:43:22 -0500 Subject: [PATCH 04/17] Update client.py --- Lib/http/client.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Lib/http/client.py b/Lib/http/client.py index 9372048498d91e..fe3fe05244f443 100644 --- a/Lib/http/client.py +++ b/Lib/http/client.py @@ -1040,8 +1040,7 @@ def close(self, shutdown=False): except OSError as e: print(f"Response close error: {e}", file=sys.stderr) except Exception as e: - print(f"Unexpected error during response close: {e}", file=sys.stderr) - + print(f"Unexpected error during response close: {e}", file=sys.stderr) def send(self, data): """Send 'data' to the server. ``data`` can be a string object, a bytes object, an array object, a From 1484782e35e4a912eba0cf98bb3d4ce62ce4881a Mon Sep 17 00:00:00 2001 From: sharktide Date: Thu, 6 Mar 2025 11:51:33 -0500 Subject: [PATCH 05/17] Update client.py --- Lib/http/client.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Lib/http/client.py b/Lib/http/client.py index fe3fe05244f443..df743641117864 100644 --- a/Lib/http/client.py +++ b/Lib/http/client.py @@ -1040,7 +1040,8 @@ def close(self, shutdown=False): except OSError as e: print(f"Response close error: {e}", file=sys.stderr) except Exception as e: - print(f"Unexpected error during response close: {e}", file=sys.stderr) + print(f"Unexpected error during response close: {e}", file=sys.stderr) + def send(self, data): """Send 'data' to the server. ``data`` can be a string object, a bytes object, an array object, a From 750f86489110bb081d20dbb4ae4218b77fb0f182 Mon Sep 17 00:00:00 2001 From: sharktide Date: Thu, 6 Mar 2025 11:59:32 -0500 Subject: [PATCH 06/17] Update client.py --- Lib/http/client.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Lib/http/client.py b/Lib/http/client.py index df743641117864..fd92904cbfc910 100644 --- a/Lib/http/client.py +++ b/Lib/http/client.py @@ -1041,7 +1041,7 @@ def close(self, shutdown=False): print(f"Response close error: {e}", file=sys.stderr) except Exception as e: print(f"Unexpected error during response close: {e}", file=sys.stderr) - + def send(self, data): """Send 'data' to the server. ``data`` can be a string object, a bytes object, an array object, a From 563afb958d75c8aec90accbfb3613d12b8d15ac4 Mon Sep 17 00:00:00 2001 From: sharktide Date: Fri, 7 Mar 2025 14:02:04 -0500 Subject: [PATCH 07/17] Update Misc/NEWS.d/next/Library/2025-03-06-16-31-08.gh-issue-130902.mHAtcq.rst Co-authored-by: Kanishk Pachauri --- .../next/Library/2025-03-06-16-31-08.gh-issue-130902.mHAtcq.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Misc/NEWS.d/next/Library/2025-03-06-16-31-08.gh-issue-130902.mHAtcq.rst b/Misc/NEWS.d/next/Library/2025-03-06-16-31-08.gh-issue-130902.mHAtcq.rst index 016cda11b5ed71..74b7c134bdea00 100644 --- a/Misc/NEWS.d/next/Library/2025-03-06-16-31-08.gh-issue-130902.mHAtcq.rst +++ b/Misc/NEWS.d/next/Library/2025-03-06-16-31-08.gh-issue-130902.mHAtcq.rst @@ -1,4 +1,4 @@ Issue: :gh:`130902` -Modified close(self) method of HTTPConnection class to include an optional socket shutdown similar to gh-130850. Includes error handling. As mentioned, it adds an optional shutdown param to the close method, keeping existing programs working, but adding an extra feature to new programs that offers improvements. +Modifies the :func:`HTTPConnection.close` of :class:`HTTPConnection` to include an optional socket ``shutdown``, improving functionality with error handling. From 7f0e156cc96f8988e58483d53b6ca89b87d99136 Mon Sep 17 00:00:00 2001 From: sharktide Date: Fri, 7 Mar 2025 14:37:58 -0500 Subject: [PATCH 08/17] Update test_httplib.py --- Lib/test/test_httplib.py | 74 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) diff --git a/Lib/test/test_httplib.py b/Lib/test/test_httplib.py index 75b748aee05940..c1b44632d52cd4 100644 --- a/Lib/test/test_httplib.py +++ b/Lib/test/test_httplib.py @@ -1,12 +1,15 @@ import enum import errno from http import client, HTTPStatus +from http.client import HTTPConnection import io +from io import StringIO import itertools import os import array import re import socket +import sys import threading import unittest @@ -16,6 +19,7 @@ from test import support from test.support import os_helper from test.support import socket_helper +from unittest.mock import MagicMock support.requires_working_socket(module=True) @@ -2525,5 +2529,75 @@ def _create_connection(address, timeout=None, source_address=None): self.assertTrue(sock.file_closed) + +class TestHTTPSocketShutdown(TestCase): + def test_close_with_shutdown(self): + mock_socket = MagicMock() + mock_socket.close = MagicMock() + mock_socket.shutdown = MagicMock() + connection = HTTPConnection('www.example.com') + connection.sock = mock_socket + original_stderr = sys.stderr + sys.stderr = StringIO() + try: + connection.close(shutdown=True) + mock_socket.shutdown.assert_called_once_with(2) # SHUT_RDWR + mock_socket.close.assert_called_once() + error_output = sys.stderr.getvalue() + self.assertEqual(error_output, "") + finally: + sys.stderr = original_stderr + + def test_close_without_shutdown(self): + mock_socket = MagicMock() + mock_socket.close = MagicMock() + mock_socket.shutdown = MagicMock() + connection = HTTPConnection('www.example.com') + connection.sock = mock_socket + original_stderr = sys.stderr + sys.stderr = StringIO() + try: + connection.close(shutdown=False) + mock_socket.shutdown.assert_not_called() + mock_socket.close.assert_called_once() + error_output = sys.stderr.getvalue() + self.assertEqual(error_output, "") + finally: + sys.stderr = original_stderr + + def test_close_shutdown_error(self): + mock_socket = MagicMock() + mock_socket.close = MagicMock() + mock_socket.shutdown = MagicMock(side_effect=OSError("Shutdown error")) + connection = HTTPConnection('www.example.com') + connection.sock = mock_socket + original_stderr = sys.stderr + sys.stderr = StringIO() + try: + connection.close(shutdown=True) + mock_socket.shutdown.assert_called_once_with(2) # SHUT_RDWR + mock_socket.close.assert_called_once() + error_output = sys.stderr.getvalue() + self.assertIn("Socket shutdown error: Shutdown error", error_output) + finally: + sys.stderr = original_stderr + + def test_close_unexpected_error(self): + mock_socket = MagicMock() + mock_socket.close = MagicMock() + mock_socket.shutdown = MagicMock(side_effect=Exception("Unexpected error")) + connection = HTTPConnection('www.example.com') + connection.sock = mock_socket + original_stderr = sys.stderr + sys.stderr = StringIO() + try: + connection.close(shutdown=True) + mock_socket.shutdown.assert_called_once_with(2) # SHUT_RDWR + mock_socket.close.assert_called_once() + error_output = sys.stderr.getvalue() + self.assertIn("Unexpected error during socket shutdown: Unexpected error", error_output) + finally: + sys.stderr = original_stderr + if __name__ == '__main__': unittest.main(verbosity=2) From bee6c39c5b19928a98d63f7e45d1e90c707d6b5d Mon Sep 17 00:00:00 2001 From: sharktide Date: Fri, 7 Mar 2025 15:05:28 -0500 Subject: [PATCH 09/17] gh-130902 @Mr-Sunglasses removed function and class refs from news entry to avoid docs build error --- .../next/Library/2025-03-06-16-31-08.gh-issue-130902.mHAtcq.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Misc/NEWS.d/next/Library/2025-03-06-16-31-08.gh-issue-130902.mHAtcq.rst b/Misc/NEWS.d/next/Library/2025-03-06-16-31-08.gh-issue-130902.mHAtcq.rst index 74b7c134bdea00..67d50536973238 100644 --- a/Misc/NEWS.d/next/Library/2025-03-06-16-31-08.gh-issue-130902.mHAtcq.rst +++ b/Misc/NEWS.d/next/Library/2025-03-06-16-31-08.gh-issue-130902.mHAtcq.rst @@ -1,4 +1,4 @@ Issue: :gh:`130902` -Modifies the :func:`HTTPConnection.close` of :class:`HTTPConnection` to include an optional socket ``shutdown``, improving functionality with error handling. +Modifies the ``HTTPConnection.close`` of ``HTTPConnection`` to include an optional socket ``shutdown``, improving functionality with error handling. From 07a22625e526f7c5c17a6483b472242704c05f4c Mon Sep 17 00:00:00 2001 From: sharktide Date: Fri, 7 Mar 2025 15:08:12 -0500 Subject: [PATCH 10/17] Update Misc/NEWS.d/next/Library/2025-03-06-16-31-08.gh-issue-130902.mHAtcq.rst Co-authored-by: Kanishk Pachauri --- .../next/Library/2025-03-06-16-31-08.gh-issue-130902.mHAtcq.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Misc/NEWS.d/next/Library/2025-03-06-16-31-08.gh-issue-130902.mHAtcq.rst b/Misc/NEWS.d/next/Library/2025-03-06-16-31-08.gh-issue-130902.mHAtcq.rst index 67d50536973238..cc30ee97c63a82 100644 --- a/Misc/NEWS.d/next/Library/2025-03-06-16-31-08.gh-issue-130902.mHAtcq.rst +++ b/Misc/NEWS.d/next/Library/2025-03-06-16-31-08.gh-issue-130902.mHAtcq.rst @@ -1,4 +1,4 @@ Issue: :gh:`130902` -Modifies the ``HTTPConnection.close`` of ``HTTPConnection`` to include an optional socket ``shutdown``, improving functionality with error handling. +Modifies the :meth:`http.client.HTTPConnection.close` of :class:`http.client.HTTPConnection` to include an optional socket ``shutdown``, improving functionality with error handling. From 365e6a409bad7a92e89260281413bfb97e8db642 Mon Sep 17 00:00:00 2001 From: sharktide Date: Fri, 7 Mar 2025 16:35:12 -0500 Subject: [PATCH 11/17] gh-130902 @Mr-Sunglasses update documentation for http socket close --- Doc/library/socket.rst | 31 +++++++++++++++++++------------ 1 file changed, 19 insertions(+), 12 deletions(-) diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index 67f3074e63c3c6..ae62647a35bd66 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -1485,28 +1485,35 @@ to sockets. .. availability:: not WASI. -.. method:: socket.close() +.. method:: socket.close(shutdown=False) - Mark the socket closed. The underlying system resource (e.g. a file - descriptor) is also closed when all file objects from :meth:`makefile` - are closed. Once that happens, all future operations on the socket - object will fail. The remote end will receive no more data (after - queued data is flushed). + Mark the socket closed. The underlying system resource (e.g., a file descriptor) is also + closed when all file objects from :meth:`makefile` are closed. Once that happens, all future + operations on the socket object will fail. The remote end will receive no more data + (after queued data is flushed). - Sockets are automatically closed when they are garbage-collected, but - it is recommended to :meth:`close` them explicitly, or to use a + If the `shutdown` parameter is set to ``True``, the socket will first be + shut down before closing, ensuring that no further data can be sent or received. + This is useful for properly releasing resources and preventing issues like lingering + connections or reset by peer (RST) errors in some network conditions. If the parameter is + ommited or set to false, the function will continue its normal behavior + + Sockets are automatically closed when they are garbage-collected, but + it is recommended to :meth:`close` them explicitly, or to use a :keyword:`with` statement around them. + .. versionadded:: 3.14 + Added an optional `shutdown` parameter to allow explicit socket shutdown before closing. + .. versionchanged:: 3.6 :exc:`OSError` is now raised if an error occurs when the underlying :c:func:`close` call is made. .. note:: - :meth:`close` releases the resource associated with a connection but - does not necessarily close the connection immediately. If you want - to close the connection in a timely fashion, call :meth:`shutdown` - before :meth:`close`. + :meth:`close` releases the resource associated with a connection + but does not necessarily close the connection immediately. If you want to close the connection in a timely fashion, call :meth:`shutdown` before :meth:`close`, or use this function with the shutdown parameter like this + ``socket.close(shutdown=True) .. method:: socket.connect(address) From 120e8fceed7e039540ffd433bfd5002b4cea41ce Mon Sep 17 00:00:00 2001 From: sharktide Date: Fri, 7 Mar 2025 16:38:32 -0500 Subject: [PATCH 12/17] gh-130902 @Mr-Sunglasses fix typo in update docs --- Doc/library/socket.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index ae62647a35bd66..f77e1bf35dde7f 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -1513,7 +1513,7 @@ to sockets. :meth:`close` releases the resource associated with a connection but does not necessarily close the connection immediately. If you want to close the connection in a timely fashion, call :meth:`shutdown` before :meth:`close`, or use this function with the shutdown parameter like this - ``socket.close(shutdown=True) + ``socket.close(shutdown=True)`` .. method:: socket.connect(address) From 6324b648ce41a6ded244ecf517cf72006fb3d27c Mon Sep 17 00:00:00 2001 From: sharktide Date: Fri, 7 Mar 2025 16:41:58 -0500 Subject: [PATCH 13/17] Update socket.rst --- Doc/library/socket.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index f77e1bf35dde7f..4c391fd4980817 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -1512,8 +1512,9 @@ to sockets. .. note:: :meth:`close` releases the resource associated with a connection - but does not necessarily close the connection immediately. If you want to close the connection in a timely fashion, call :meth:`shutdown` before :meth:`close`, or use this function with the shutdown parameter like this - ``socket.close(shutdown=True)`` + but does not necessarily close the connection immediately. If you want to close the connection in a + timely fashion, call :meth:`shutdown` before :meth:`close`, or + use this function with the shutdown parameter like this ``socket.close(shutdown=True)`` .. method:: socket.connect(address) From 88a3d96be9bcab96a1e742e35ffbb3f6b69074f7 Mon Sep 17 00:00:00 2001 From: sharktide Date: Fri, 7 Mar 2025 16:45:35 -0500 Subject: [PATCH 14/17] Update socket.rst --- Doc/library/socket.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index 4c391fd4980817..4d7401d9901ddf 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -1492,7 +1492,7 @@ to sockets. operations on the socket object will fail. The remote end will receive no more data (after queued data is flushed). - If the `shutdown` parameter is set to ``True``, the socket will first be + If the ``shutdown`` parameter is set to ``True``, the socket will first be shut down before closing, ensuring that no further data can be sent or received. This is useful for properly releasing resources and preventing issues like lingering connections or reset by peer (RST) errors in some network conditions. If the parameter is @@ -1503,7 +1503,7 @@ to sockets. :keyword:`with` statement around them. .. versionadded:: 3.14 - Added an optional `shutdown` parameter to allow explicit socket shutdown before closing. + Added an optional ``shutdown`` parameter to allow explicit socket shutdown before closing. .. versionchanged:: 3.6 :exc:`OSError` is now raised if an error occurs when the underlying From 52cd353d4234ca8a809ec0606de9159b9d21b797 Mon Sep 17 00:00:00 2001 From: sharktide Date: Fri, 7 Mar 2025 16:49:17 -0500 Subject: [PATCH 15/17] gh-130902 @Mr-Sunglasses removed trailing whitespace from docs --- Doc/library/socket.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index 4d7401d9901ddf..3a2dc7052ca8f1 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -1489,17 +1489,17 @@ to sockets. Mark the socket closed. The underlying system resource (e.g., a file descriptor) is also closed when all file objects from :meth:`makefile` are closed. Once that happens, all future - operations on the socket object will fail. The remote end will receive no more data + operations on the socket object will fail. The remote end will receive no more data (after queued data is flushed). - If the ``shutdown`` parameter is set to ``True``, the socket will first be - shut down before closing, ensuring that no further data can be sent or received. - This is useful for properly releasing resources and preventing issues like lingering + If the ``shutdown`` parameter is set to ``True``, the socket will first be + shut down before closing, ensuring that no further data can be sent or received. + This is useful for properly releasing resources and preventing issues like lingering connections or reset by peer (RST) errors in some network conditions. If the parameter is ommited or set to false, the function will continue its normal behavior - Sockets are automatically closed when they are garbage-collected, but - it is recommended to :meth:`close` them explicitly, or to use a + Sockets are automatically closed when they are garbage-collected, but + it is recommended to :meth:`close` them explicitly, or to use a :keyword:`with` statement around them. .. versionadded:: 3.14 @@ -1511,8 +1511,8 @@ to sockets. .. note:: - :meth:`close` releases the resource associated with a connection - but does not necessarily close the connection immediately. If you want to close the connection in a + :meth:`close` releases the resource associated with a connection + but does not necessarily close the connection immediately. If you want to close the connection in a timely fashion, call :meth:`shutdown` before :meth:`close`, or use this function with the shutdown parameter like this ``socket.close(shutdown=True)`` From 26a9b4d776aa215971f0fba88c84ed8d1158755d Mon Sep 17 00:00:00 2001 From: sharktide Date: Fri, 7 Mar 2025 16:55:52 -0500 Subject: [PATCH 16/17] gh-130902 @Mr-Sunglasses add/update docstring in client.py Updated the docstring of the close method of the HTTPConnection class to reflect optional shutdown parameter in http/client.py --- Lib/http/client.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Lib/http/client.py b/Lib/http/client.py index fd92904cbfc910..3ad3c270cb91e6 100644 --- a/Lib/http/client.py +++ b/Lib/http/client.py @@ -1013,6 +1013,10 @@ def connect(self): self._tunnel() def close(self, shutdown=False): + """Close the connection to the HTTP server. + :param shutdown: If True, perform an explicit shutdown of the socket before closing. Defaults to False. + :type shutdown: bool, optional + """ self.__state = _CS_IDLE try: sock = self.sock From bfff327d99205869140ba75d61fafcb5e51a2e2b Mon Sep 17 00:00:00 2001 From: sharktide Date: Sat, 8 Mar 2025 12:35:00 -0500 Subject: [PATCH 17/17] gh-130902 @Mr-Sunglasses update Doc/library/socket.rst Par suggestion Co-authored-by: Kanishk Pachauri --- Doc/library/socket.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index 3a2dc7052ca8f1..c8b84e66a747fa 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -1494,7 +1494,7 @@ to sockets. If the ``shutdown`` parameter is set to ``True``, the socket will first be shut down before closing, ensuring that no further data can be sent or received. - This is useful for properly releasing resources and preventing issues like lingering + This is useful for properly releasing resources and preventing issues like persistent connections or reset by peer (RST) errors in some network conditions. If the parameter is ommited or set to false, the function will continue its normal behavior