From 9df2d1bfe1ca8d675d3cbe78d7e998585e0546a8 Mon Sep 17 00:00:00 2001 From: Ronald Oussoren Date: Fri, 8 Dec 2023 13:37:11 +0100 Subject: [PATCH 1/3] gh-105912: document gotcha with using os.fork on macOS Using ``fork(2)`` on macOS when also using higher-level system APIs in the parent proces can crash on macOS because those system APIs are not written to handle this usage pattern. There's nothing we can do about this other than documenting the problem. --- Doc/library/os.rst | 10 ++++++++++ Doc/library/pty.rst | 3 +++ Doc/library/urllib.request.rst | 8 ++++++++ 3 files changed, 21 insertions(+) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index fe573f188ab066..f361820b7fab1f 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -4373,6 +4373,11 @@ written in Python, such as a mail server's external command delivery program. If you use TLS sockets in an application calling ``fork()``, see the warning in the :mod:`ssl` documentation. + .. warning:: + + On macOS the use of this function is unsafe when mixed with using + higher-level system APIs, and that includes using :mod:`urllib.request`. + .. versionchanged:: 3.8 Calling ``fork()`` in a subinterpreter is no longer supported (:exc:`RuntimeError` is raised). @@ -4412,6 +4417,11 @@ written in Python, such as a mail server's external command delivery program. .. audit-event:: os.forkpty "" os.forkpty + .. warning:: + + On macOS the use of this function is unsafe when mixed with using + higher-level system APIs, and that includes using :mod:`urllib.request`. + .. versionchanged:: 3.12 If Python is able to detect that your process has multiple threads, this now raises a :exc:`DeprecationWarning`. See the diff --git a/Doc/library/pty.rst b/Doc/library/pty.rst index af9378464edb9f..bd2f5ed45cb8b4 100644 --- a/Doc/library/pty.rst +++ b/Doc/library/pty.rst @@ -33,6 +33,9 @@ The :mod:`pty` module defines the following functions: file descriptor connected to the child's controlling terminal (and also to the child's standard input and output). + .. warning:: On macOS the use of this function is unsafe when mixed with using + higher-level system APIs, and that includes using :mod:`urllib.request`. + .. function:: openpty() diff --git a/Doc/library/urllib.request.rst b/Doc/library/urllib.request.rst index bf3af1bef0714c..436ee4d28ce647 100644 --- a/Doc/library/urllib.request.rst +++ b/Doc/library/urllib.request.rst @@ -21,6 +21,14 @@ authentication, redirections, cookies and more. The `Requests package `_ is recommended for a higher-level HTTP client interface. +.. warning:: + + On macOS it is unsafe to use this module in programs using + :func:`os.fork` because the :func:`getproxies` implementation for + macOS uses a higher-level system API. Set the environement variable + ``no_proxy`` to ``*`` to avoid this problem + (e.g. ``os.environ["no_proxy"] = "*"``). + .. include:: ../includes/wasm-notavail.rst The :mod:`urllib.request` module defines the following functions: From 38c88d6a8c11ab0ad694aaccafbecc4ebf1bd0b5 Mon Sep 17 00:00:00 2001 From: Ronald Oussoren Date: Fri, 8 Dec 2023 13:48:31 +0100 Subject: [PATCH 2/3] Fix lint warning --- Doc/library/urllib.request.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/urllib.request.rst b/Doc/library/urllib.request.rst index 436ee4d28ce647..9459c9ed5ce347 100644 --- a/Doc/library/urllib.request.rst +++ b/Doc/library/urllib.request.rst @@ -26,7 +26,7 @@ authentication, redirections, cookies and more. On macOS it is unsafe to use this module in programs using :func:`os.fork` because the :func:`getproxies` implementation for macOS uses a higher-level system API. Set the environement variable - ``no_proxy`` to ``*`` to avoid this problem + ``no_proxy`` to ``*`` to avoid this problem (e.g. ``os.environ["no_proxy"] = "*"``). .. include:: ../includes/wasm-notavail.rst From 1ed39620d4a6085f7f214d22ab2b5493ff6d83ec Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Wed, 13 Dec 2023 11:54:27 -0800 Subject: [PATCH 3/3] Update Doc/library/urllib.request.rst --- Doc/library/urllib.request.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/urllib.request.rst b/Doc/library/urllib.request.rst index 9459c9ed5ce347..fe5fa3b10c2093 100644 --- a/Doc/library/urllib.request.rst +++ b/Doc/library/urllib.request.rst @@ -25,7 +25,7 @@ authentication, redirections, cookies and more. On macOS it is unsafe to use this module in programs using :func:`os.fork` because the :func:`getproxies` implementation for - macOS uses a higher-level system API. Set the environement variable + macOS uses a higher-level system API. Set the environment variable ``no_proxy`` to ``*`` to avoid this problem (e.g. ``os.environ["no_proxy"] = "*"``).