We are currently solving the following issue within our repository. Here is the issue text:
--- BEGIN ISSUE ---
How to implement a "watcher" thread as suggested by the documentation?
The documentation of the [`timeout`](https://urllib3.readthedocs.io/en/latest/reference/urllib3.util.html#module-urllib3.util.timeout) module says:

> If your goal is to cut off any request after a set amount of wall clock time, consider having a second “watcher” thread to cut off a slow request.

How would that work?

It seems like it is [strongly discouraged or even impossible](https://stackoverflow.com/questions/323972/is-there-any-way-to-kill-a-thread) to kill a thread in Python, so what would that watcher thread do?

If it is not possible to write a watcher thread in Python, the documentation shouldn't suggest to do it.

--- END ISSUE ---

Below are some code segments, each from a relevant file. One or more of these files may contain bugs.
--- BEGIN FILES ---
Path: `src/urllib3/util/timeout.py`
Content:
```
1 from __future__ import annotations
2 
3 import time
4 import typing
5 from enum import Enum
6 from socket import getdefaulttimeout
7 
8 from ..exceptions import TimeoutStateError
9 
10 if typing.TYPE_CHECKING:
11     from typing import Final
12 
13 
14 class _TYPE_DEFAULT(Enum):
15     # This value should never be passed to socket.settimeout() so for safety we use a -1.
16     # socket.settimout() raises a ValueError for negative values.
17     token = -1
18 
19 
20 _DEFAULT_TIMEOUT: Final[_TYPE_DEFAULT] = _TYPE_DEFAULT.token
21 
22 _TYPE_TIMEOUT = typing.Optional[typing.Union[float, _TYPE_DEFAULT]]
23 
24 
25 class Timeout:
26     """Timeout configuration.
27 
28     Timeouts can be defined as a default for a pool:
29 
30     .. code-block:: python
31 
32         import urllib3
33 
34         timeout = urllib3.util.Timeout(connect=2.0, read=7.0)
35 
36         http = urllib3.PoolManager(timeout=timeout)
37 
38         resp = http.request("GET", "https://example.com/")
39 
40         print(resp.status)
41 
42     Or per-request (which overrides the default for the pool):
43 
44     .. code-block:: python
45 
46        response = http.request("GET", "https://example.com/", timeout=Timeout(10))
47 
48     Timeouts can be disabled by setting all the parameters to ``None``:
49 
50     .. code-block:: python
51 
52        no_timeout = Timeout(connect=None, read=None)
53        response = http.request("GET", "https://example.com/", timeout=no_timeout)
54 
55 
56     :param total:
57         This combines the connect and read timeouts into one; the read timeout
58         will be set to the time leftover from the connect attempt. In the
59         event that both a connect timeout and a total are specified, or a read
60         timeout and a total are specified, the shorter timeout will be applied.
61 
62         Defaults to None.
63 
64     :type total: int, float, or None
65 
66     :param connect:
67         The maximum amount of time (in seconds) to wait for a connection
68         attempt to a server to succeed. Omitting the parameter will default the
69         connect timeout to the system default, probably `the global default
70         timeout in socket.py
71         <http://hg.python.org/cpython/file/603b4d593758/Lib/socket.py#l535>`_.
72         None will set an infinite timeout for connection attempts.
73 
74     :type connect: int, float, or None
75 
76     :param read:
77         The maximum amount of time (in seconds) to wait between consecutive
78         read operations for a response from the server. Omitting the parameter
79         will default the read timeout to the system default, probably `the
80         global default timeout in socket.py
81         <http://hg.python.org/cpython/file/603b4d593758/Lib/socket.py#l535>`_.
82         None will set an infinite timeout.
83 
84     :type read: int, float, or None
85 
86     .. note::
87 
88         Many factors can affect the total amount of time for urllib3 to return
89         an HTTP response.
90 
91         For example, Python's DNS resolver does not obey the timeout specified
92         on the socket. Other factors that can affect total request time include
93         high CPU load, high swap, the program running at a low priority level,
94         or other behaviors.
95 
96         In addition, the read and total timeouts only measure the time between
97         read operations on the socket connecting the client and the server,
98         not the total amount of time for the request to return a complete
99         response. For most requests, the timeout is raised because the server
100         has not sent the first byte in the specified time. This is not always
101         the case; if a server streams one byte every fifteen seconds, a timeout
102         of 20 seconds will not trigger, even though the request will take
103         several minutes to complete.
104 
105         If your goal is to cut off any request after a set amount of wall clock
106         time, consider having a second "watcher" thread to cut off a slow
107         request.
108     """
109 
110     #: A sentinel object representing the default timeout value
111     DEFAULT_TIMEOUT: _TYPE_TIMEOUT = _DEFAULT_TIMEOUT
112 
113     def __init__(
114         self,
115         total: _TYPE_TIMEOUT = None,
116         connect: _TYPE_TIMEOUT = _DEFAULT_TIMEOUT,
117         read: _TYPE_TIMEOUT = _DEFAULT_TIMEOUT,
118     ) -> None:
119         self._connect = self._validate_timeout(connect, "connect")
120         self._read = self._validate_timeout(read, "read")
121         self.total = self._validate_timeout(total, "total")
122         self._start_connect: float | None = None
123 
124     def __repr__(self) -> str:
125         return f"{type(self).__name__}(connect={self._connect!r}, read={self._read!r}, total={self.total!r})"
126 
127     # __str__ provided for backwards compatibility
128     __str__ = __repr__
129 
130     @staticmethod
131     def resolve_default_timeout(timeout: _TYPE_TIMEOUT) -> float | None:
132         return getdefaulttimeout() if timeout is _DEFAULT_TIMEOUT else timeout
133 
134     @classmethod
135     def _validate_timeout(cls, value: _TYPE_TIMEOUT, name: str) -> _TYPE_TIMEOUT:
136         """Check that a timeout attribute is valid.
137 
138         :param value: The timeout value to validate
139         :param name: The name of the timeout attribute to validate. This is
140             used to specify in error messages.
141         :return: The validated and casted version of the given value.
142         :raises ValueError: If it is a numeric value less than or equal to
143             zero, or the type is not an integer, float, or None.
144         """
145         if value is None or value is _DEFAULT_TIMEOUT:
146             return value
147 
148         if isinstance(value, bool):
149             raise ValueError(
150                 "Timeout cannot be a boolean value. It must "
151                 "be an int, float or None."
152             )
153         try:
154             float(value)
155         except (TypeError, ValueError):
156             raise ValueError(
157                 "Timeout value %s was %s, but it must be an "
158                 "int, float or None." % (name, value)
159             ) from None
160 
161         try:
162             if value <= 0:
163                 raise ValueError(
164                     "Attempted to set %s timeout to %s, but the "
165                     "timeout cannot be set to a value less "
166                     "than or equal to 0." % (name, value)
167                 )
168         except TypeError:
169             raise ValueError(
170                 "Timeout value %s was %s, but it must be an "
171                 "int, float or None." % (name, value)
172             ) from None
173 
174         return value
175 
176     @classmethod
177     def from_float(cls, timeout: _TYPE_TIMEOUT) -> Timeout:
178         """Create a new Timeout from a legacy timeout value.
179 
180         The timeout value used by httplib.py sets the same timeout on the
181         connect(), and recv() socket requests. This creates a :class:`Timeout`
182         object that sets the individual timeouts to the ``timeout`` value
183         passed to this function.
184 
185         :param timeout: The legacy timeout value.
186         :type timeout: integer, float, :attr:`urllib3.util.Timeout.DEFAULT_TIMEOUT`, or None
187         :return: Timeout object
188         :rtype: :class:`Timeout`
189         """
190         return Timeout(read=timeout, connect=timeout)
191 
192     def clone(self) -> Timeout:
193         """Create a copy of the timeout object
194 
195         Timeout properties are stored per-pool but each request needs a fresh
196         Timeout object to ensure each one has its own start/stop configured.
197 
198         :return: a copy of the timeout object
199         :rtype: :class:`Timeout`
200         """
201         # We can't use copy.deepcopy because that will also create a new object
202         # for _GLOBAL_DEFAULT_TIMEOUT, which socket.py uses as a sentinel to
203         # detect the user default.
204         return Timeout(connect=self._connect, read=self._read, total=self.total)
205 
206     def start_connect(self) -> float:
207         """Start the timeout clock, used during a connect() attempt
208 
209         :raises urllib3.exceptions.TimeoutStateError: if you attempt
210             to start a timer that has been started already.
211         """
212         if self._start_connect is not None:
213             raise TimeoutStateError("Timeout timer has already been started.")
214         self._start_connect = time.monotonic()
215         return self._start_connect
216 
217     def get_connect_duration(self) -> float:
218         """Gets the time elapsed since the call to :meth:`start_connect`.
219 
220         :return: Elapsed time in seconds.
221         :rtype: float
222         :raises urllib3.exceptions.TimeoutStateError: if you attempt
223             to get duration for a timer that hasn't been started.
224         """
225         if self._start_connect is None:
226             raise TimeoutStateError(
227                 "Can't get connect duration for timer that has not started."
228             )
229         return time.monotonic() - self._start_connect
230 
231     @property
232     def connect_timeout(self) -> _TYPE_TIMEOUT:
233         """Get the value to use when setting a connection timeout.
234 
235         This will be a positive float or integer, the value None
236         (never timeout), or the default system timeout.
237 
238         :return: Connect timeout.
239         :rtype: int, float, :attr:`Timeout.DEFAULT_TIMEOUT` or None
240         """
241         if self.total is None:
242             return self._connect
243 
244         if self._connect is None or self._connect is _DEFAULT_TIMEOUT:
245             return self.total
246 
247         return min(self._connect, self.total)  # type: ignore[type-var]
248 
249     @property
250     def read_timeout(self) -> float | None:
251         """Get the value for the read timeout.
252 
253         This assumes some time has elapsed in the connection timeout and
254         computes the read timeout appropriately.
255 
256         If self.total is set, the read timeout is dependent on the amount of
257         time taken by the connect timeout. If the connection time has not been
258         established, a :exc:`~urllib3.exceptions.TimeoutStateError` will be
259         raised.
260 
261         :return: Value to use for the read timeout.
262         :rtype: int, float or None
263         :raises urllib3.exceptions.TimeoutStateError: If :meth:`start_connect`
264             has not yet been called on this object.
265         """
266         if (
267             self.total is not None
268             and self.total is not _DEFAULT_TIMEOUT
269             and self._read is not None
270             and self._read is not _DEFAULT_TIMEOUT
271         ):
272             # In case the connect timeout has not yet been established.
273             if self._start_connect is None:
274                 return self._read
275             return max(0, min(self.total - self.get_connect_duration(), self._read))
276         elif self.total is not None and self.total is not _DEFAULT_TIMEOUT:
277             return max(0, self.total - self.get_connect_duration())
278         else:
279             return self.resolve_default_timeout(self._read)
280
```
--- END FILES ---

Please first localize the bug based on the issue statement, and then generate a patch according to the `git diff` format fenced by three backticks.

Here is an example:

```diff
diff --git a/examples/server_async.py b/examples/server_async.py
--- a/examples/server_async.py
+++ b/examples/server_async.py
@@ -313,4 +313,4 @@
 
 
 if __name__ == "__main__":
-    asyncio.run(run_async_server("."), debug=True)
+    asyncio.run(run_async_server(), debug=True)
diff --git a/examples/server_sync.py b/examples/server_sync.py
--- a/examples/server_sync.py
+++ b/examples/server_sync.py
@@ -313,5 +313,5 @@
 
 
 if __name__ == "__main__":
-    server = run_sync_server(".")
+    server = run_sync_server()
     server.shutdown()

```

diff --git a/src/urllib3/util/timeout.py b/src/urllib3/util/timeout.py
--- a/src/urllib3/util/timeout.py
+++ b/src/urllib3/util/timeout.py
@@ -101,10 +101,6 @@
         the case; if a server streams one byte every fifteen seconds, a timeout
         of 20 seconds will not trigger, even though the request will take
         several minutes to complete.
-
-        If your goal is to cut off any request after a set amount of wall clock
-        time, consider having a second "watcher" thread to cut off a slow
-        request.
     """
 
     #: A sentinel object representing the default timeout value

{"golden_diff": "diff --git a/src/urllib3/util/timeout.py b/src/urllib3/util/timeout.py\n--- a/src/urllib3/util/timeout.py\n+++ b/src/urllib3/util/timeout.py\n@@ -101,10 +101,6 @@\n         the case; if a server streams one byte every fifteen seconds, a timeout\n         of 20 seconds will not trigger, even though the request will take\n         several minutes to complete.\n-\n-        If your goal is to cut off any request after a set amount of wall clock\n-        time, consider having a second \"watcher\" thread to cut off a slow\n-        request.\n     \"\"\"\n \n     #: A sentinel object representing the default timeout value\n", "issue": "How to implement a \"watcher\" thread as suggested by the documentation?\nThe documentation of the [`timeout`](https://urllib3.readthedocs.io/en/latest/reference/urllib3.util.html#module-urllib3.util.timeout) module says:\r\n\r\n> If your goal is to cut off any request after a set amount of wall clock time, consider having a second \u201cwatcher\u201d thread to cut off a slow request.\r\n\r\nHow would that work?\r\n\r\nIt seems like it is [strongly discouraged or even impossible](https://stackoverflow.com/questions/323972/is-there-any-way-to-kill-a-thread) to kill a thread in Python, so what would that watcher thread do?\r\n\r\nIf it is not possible to write a watcher thread in Python, the documentation shouldn't suggest to do it.\n", "before_files": [{"content": "from __future__ import annotations\n\nimport time\nimport typing\nfrom enum import Enum\nfrom socket import getdefaulttimeout\n\nfrom ..exceptions import TimeoutStateError\n\nif typing.TYPE_CHECKING:\n    from typing import Final\n\n\nclass _TYPE_DEFAULT(Enum):\n    # This value should never be passed to socket.settimeout() so for safety we use a -1.\n    # socket.settimout() raises a ValueError for negative values.\n    token = -1\n\n\n_DEFAULT_TIMEOUT: Final[_TYPE_DEFAULT] = _TYPE_DEFAULT.token\n\n_TYPE_TIMEOUT = typing.Optional[typing.Union[float, _TYPE_DEFAULT]]\n\n\nclass Timeout:\n    \"\"\"Timeout configuration.\n\n    Timeouts can be defined as a default for a pool:\n\n    .. code-block:: python\n\n        import urllib3\n\n        timeout = urllib3.util.Timeout(connect=2.0, read=7.0)\n\n        http = urllib3.PoolManager(timeout=timeout)\n\n        resp = http.request(\"GET\", \"https://example.com/\")\n\n        print(resp.status)\n\n    Or per-request (which overrides the default for the pool):\n\n    .. code-block:: python\n\n       response = http.request(\"GET\", \"https://example.com/\", timeout=Timeout(10))\n\n    Timeouts can be disabled by setting all the parameters to ``None``:\n\n    .. code-block:: python\n\n       no_timeout = Timeout(connect=None, read=None)\n       response = http.request(\"GET\", \"https://example.com/\", timeout=no_timeout)\n\n\n    :param total:\n        This combines the connect and read timeouts into one; the read timeout\n        will be set to the time leftover from the connect attempt. In the\n        event that both a connect timeout and a total are specified, or a read\n        timeout and a total are specified, the shorter timeout will be applied.\n\n        Defaults to None.\n\n    :type total: int, float, or None\n\n    :param connect:\n        The maximum amount of time (in seconds) to wait for a connection\n        attempt to a server to succeed. Omitting the parameter will default the\n        connect timeout to the system default, probably `the global default\n        timeout in socket.py\n        <http://hg.python.org/cpython/file/603b4d593758/Lib/socket.py#l535>`_.\n        None will set an infinite timeout for connection attempts.\n\n    :type connect: int, float, or None\n\n    :param read:\n        The maximum amount of time (in seconds) to wait between consecutive\n        read operations for a response from the server. Omitting the parameter\n        will default the read timeout to the system default, probably `the\n        global default timeout in socket.py\n        <http://hg.python.org/cpython/file/603b4d593758/Lib/socket.py#l535>`_.\n        None will set an infinite timeout.\n\n    :type read: int, float, or None\n\n    .. note::\n\n        Many factors can affect the total amount of time for urllib3 to return\n        an HTTP response.\n\n        For example, Python's DNS resolver does not obey the timeout specified\n        on the socket. Other factors that can affect total request time include\n        high CPU load, high swap, the program running at a low priority level,\n        or other behaviors.\n\n        In addition, the read and total timeouts only measure the time between\n        read operations on the socket connecting the client and the server,\n        not the total amount of time for the request to return a complete\n        response. For most requests, the timeout is raised because the server\n        has not sent the first byte in the specified time. This is not always\n        the case; if a server streams one byte every fifteen seconds, a timeout\n        of 20 seconds will not trigger, even though the request will take\n        several minutes to complete.\n\n        If your goal is to cut off any request after a set amount of wall clock\n        time, consider having a second \"watcher\" thread to cut off a slow\n        request.\n    \"\"\"\n\n    #: A sentinel object representing the default timeout value\n    DEFAULT_TIMEOUT: _TYPE_TIMEOUT = _DEFAULT_TIMEOUT\n\n    def __init__(\n        self,\n        total: _TYPE_TIMEOUT = None,\n        connect: _TYPE_TIMEOUT = _DEFAULT_TIMEOUT,\n        read: _TYPE_TIMEOUT = _DEFAULT_TIMEOUT,\n    ) -> None:\n        self._connect = self._validate_timeout(connect, \"connect\")\n        self._read = self._validate_timeout(read, \"read\")\n        self.total = self._validate_timeout(total, \"total\")\n        self._start_connect: float | None = None\n\n    def __repr__(self) -> str:\n        return f\"{type(self).__name__}(connect={self._connect!r}, read={self._read!r}, total={self.total!r})\"\n\n    # __str__ provided for backwards compatibility\n    __str__ = __repr__\n\n    @staticmethod\n    def resolve_default_timeout(timeout: _TYPE_TIMEOUT) -> float | None:\n        return getdefaulttimeout() if timeout is _DEFAULT_TIMEOUT else timeout\n\n    @classmethod\n    def _validate_timeout(cls, value: _TYPE_TIMEOUT, name: str) -> _TYPE_TIMEOUT:\n        \"\"\"Check that a timeout attribute is valid.\n\n        :param value: The timeout value to validate\n        :param name: The name of the timeout attribute to validate. This is\n            used to specify in error messages.\n        :return: The validated and casted version of the given value.\n        :raises ValueError: If it is a numeric value less than or equal to\n            zero, or the type is not an integer, float, or None.\n        \"\"\"\n        if value is None or value is _DEFAULT_TIMEOUT:\n            return value\n\n        if isinstance(value, bool):\n            raise ValueError(\n                \"Timeout cannot be a boolean value. It must \"\n                \"be an int, float or None.\"\n            )\n        try:\n            float(value)\n        except (TypeError, ValueError):\n            raise ValueError(\n                \"Timeout value %s was %s, but it must be an \"\n                \"int, float or None.\" % (name, value)\n            ) from None\n\n        try:\n            if value <= 0:\n                raise ValueError(\n                    \"Attempted to set %s timeout to %s, but the \"\n                    \"timeout cannot be set to a value less \"\n                    \"than or equal to 0.\" % (name, value)\n                )\n        except TypeError:\n            raise ValueError(\n                \"Timeout value %s was %s, but it must be an \"\n                \"int, float or None.\" % (name, value)\n            ) from None\n\n        return value\n\n    @classmethod\n    def from_float(cls, timeout: _TYPE_TIMEOUT) -> Timeout:\n        \"\"\"Create a new Timeout from a legacy timeout value.\n\n        The timeout value used by httplib.py sets the same timeout on the\n        connect(), and recv() socket requests. This creates a :class:`Timeout`\n        object that sets the individual timeouts to the ``timeout`` value\n        passed to this function.\n\n        :param timeout: The legacy timeout value.\n        :type timeout: integer, float, :attr:`urllib3.util.Timeout.DEFAULT_TIMEOUT`, or None\n        :return: Timeout object\n        :rtype: :class:`Timeout`\n        \"\"\"\n        return Timeout(read=timeout, connect=timeout)\n\n    def clone(self) -> Timeout:\n        \"\"\"Create a copy of the timeout object\n\n        Timeout properties are stored per-pool but each request needs a fresh\n        Timeout object to ensure each one has its own start/stop configured.\n\n        :return: a copy of the timeout object\n        :rtype: :class:`Timeout`\n        \"\"\"\n        # We can't use copy.deepcopy because that will also create a new object\n        # for _GLOBAL_DEFAULT_TIMEOUT, which socket.py uses as a sentinel to\n        # detect the user default.\n        return Timeout(connect=self._connect, read=self._read, total=self.total)\n\n    def start_connect(self) -> float:\n        \"\"\"Start the timeout clock, used during a connect() attempt\n\n        :raises urllib3.exceptions.TimeoutStateError: if you attempt\n            to start a timer that has been started already.\n        \"\"\"\n        if self._start_connect is not None:\n            raise TimeoutStateError(\"Timeout timer has already been started.\")\n        self._start_connect = time.monotonic()\n        return self._start_connect\n\n    def get_connect_duration(self) -> float:\n        \"\"\"Gets the time elapsed since the call to :meth:`start_connect`.\n\n        :return: Elapsed time in seconds.\n        :rtype: float\n        :raises urllib3.exceptions.TimeoutStateError: if you attempt\n            to get duration for a timer that hasn't been started.\n        \"\"\"\n        if self._start_connect is None:\n            raise TimeoutStateError(\n                \"Can't get connect duration for timer that has not started.\"\n            )\n        return time.monotonic() - self._start_connect\n\n    @property\n    def connect_timeout(self) -> _TYPE_TIMEOUT:\n        \"\"\"Get the value to use when setting a connection timeout.\n\n        This will be a positive float or integer, the value None\n        (never timeout), or the default system timeout.\n\n        :return: Connect timeout.\n        :rtype: int, float, :attr:`Timeout.DEFAULT_TIMEOUT` or None\n        \"\"\"\n        if self.total is None:\n            return self._connect\n\n        if self._connect is None or self._connect is _DEFAULT_TIMEOUT:\n            return self.total\n\n        return min(self._connect, self.total)  # type: ignore[type-var]\n\n    @property\n    def read_timeout(self) -> float | None:\n        \"\"\"Get the value for the read timeout.\n\n        This assumes some time has elapsed in the connection timeout and\n        computes the read timeout appropriately.\n\n        If self.total is set, the read timeout is dependent on the amount of\n        time taken by the connect timeout. If the connection time has not been\n        established, a :exc:`~urllib3.exceptions.TimeoutStateError` will be\n        raised.\n\n        :return: Value to use for the read timeout.\n        :rtype: int, float or None\n        :raises urllib3.exceptions.TimeoutStateError: If :meth:`start_connect`\n            has not yet been called on this object.\n        \"\"\"\n        if (\n            self.total is not None\n            and self.total is not _DEFAULT_TIMEOUT\n            and self._read is not None\n            and self._read is not _DEFAULT_TIMEOUT\n        ):\n            # In case the connect timeout has not yet been established.\n            if self._start_connect is None:\n                return self._read\n            return max(0, min(self.total - self.get_connect_duration(), self._read))\n        elif self.total is not None and self.total is not _DEFAULT_TIMEOUT:\n            return max(0, self.total - self.get_connect_duration())\n        else:\n            return self.resolve_default_timeout(self._read)\n", "path": "src/urllib3/util/timeout.py"}], "after_files": [{"content": "from __future__ import annotations\n\nimport time\nimport typing\nfrom enum import Enum\nfrom socket import getdefaulttimeout\n\nfrom ..exceptions import TimeoutStateError\n\nif typing.TYPE_CHECKING:\n    from typing import Final\n\n\nclass _TYPE_DEFAULT(Enum):\n    # This value should never be passed to socket.settimeout() so for safety we use a -1.\n    # socket.settimout() raises a ValueError for negative values.\n    token = -1\n\n\n_DEFAULT_TIMEOUT: Final[_TYPE_DEFAULT] = _TYPE_DEFAULT.token\n\n_TYPE_TIMEOUT = typing.Optional[typing.Union[float, _TYPE_DEFAULT]]\n\n\nclass Timeout:\n    \"\"\"Timeout configuration.\n\n    Timeouts can be defined as a default for a pool:\n\n    .. code-block:: python\n\n        import urllib3\n\n        timeout = urllib3.util.Timeout(connect=2.0, read=7.0)\n\n        http = urllib3.PoolManager(timeout=timeout)\n\n        resp = http.request(\"GET\", \"https://example.com/\")\n\n        print(resp.status)\n\n    Or per-request (which overrides the default for the pool):\n\n    .. code-block:: python\n\n       response = http.request(\"GET\", \"https://example.com/\", timeout=Timeout(10))\n\n    Timeouts can be disabled by setting all the parameters to ``None``:\n\n    .. code-block:: python\n\n       no_timeout = Timeout(connect=None, read=None)\n       response = http.request(\"GET\", \"https://example.com/\", timeout=no_timeout)\n\n\n    :param total:\n        This combines the connect and read timeouts into one; the read timeout\n        will be set to the time leftover from the connect attempt. In the\n        event that both a connect timeout and a total are specified, or a read\n        timeout and a total are specified, the shorter timeout will be applied.\n\n        Defaults to None.\n\n    :type total: int, float, or None\n\n    :param connect:\n        The maximum amount of time (in seconds) to wait for a connection\n        attempt to a server to succeed. Omitting the parameter will default the\n        connect timeout to the system default, probably `the global default\n        timeout in socket.py\n        <http://hg.python.org/cpython/file/603b4d593758/Lib/socket.py#l535>`_.\n        None will set an infinite timeout for connection attempts.\n\n    :type connect: int, float, or None\n\n    :param read:\n        The maximum amount of time (in seconds) to wait between consecutive\n        read operations for a response from the server. Omitting the parameter\n        will default the read timeout to the system default, probably `the\n        global default timeout in socket.py\n        <http://hg.python.org/cpython/file/603b4d593758/Lib/socket.py#l535>`_.\n        None will set an infinite timeout.\n\n    :type read: int, float, or None\n\n    .. note::\n\n        Many factors can affect the total amount of time for urllib3 to return\n        an HTTP response.\n\n        For example, Python's DNS resolver does not obey the timeout specified\n        on the socket. Other factors that can affect total request time include\n        high CPU load, high swap, the program running at a low priority level,\n        or other behaviors.\n\n        In addition, the read and total timeouts only measure the time between\n        read operations on the socket connecting the client and the server,\n        not the total amount of time for the request to return a complete\n        response. For most requests, the timeout is raised because the server\n        has not sent the first byte in the specified time. This is not always\n        the case; if a server streams one byte every fifteen seconds, a timeout\n        of 20 seconds will not trigger, even though the request will take\n        several minutes to complete.\n    \"\"\"\n\n    #: A sentinel object representing the default timeout value\n    DEFAULT_TIMEOUT: _TYPE_TIMEOUT = _DEFAULT_TIMEOUT\n\n    def __init__(\n        self,\n        total: _TYPE_TIMEOUT = None,\n        connect: _TYPE_TIMEOUT = _DEFAULT_TIMEOUT,\n        read: _TYPE_TIMEOUT = _DEFAULT_TIMEOUT,\n    ) -> None:\n        self._connect = self._validate_timeout(connect, \"connect\")\n        self._read = self._validate_timeout(read, \"read\")\n        self.total = self._validate_timeout(total, \"total\")\n        self._start_connect: float | None = None\n\n    def __repr__(self) -> str:\n        return f\"{type(self).__name__}(connect={self._connect!r}, read={self._read!r}, total={self.total!r})\"\n\n    # __str__ provided for backwards compatibility\n    __str__ = __repr__\n\n    @staticmethod\n    def resolve_default_timeout(timeout: _TYPE_TIMEOUT) -> float | None:\n        return getdefaulttimeout() if timeout is _DEFAULT_TIMEOUT else timeout\n\n    @classmethod\n    def _validate_timeout(cls, value: _TYPE_TIMEOUT, name: str) -> _TYPE_TIMEOUT:\n        \"\"\"Check that a timeout attribute is valid.\n\n        :param value: The timeout value to validate\n        :param name: The name of the timeout attribute to validate. This is\n            used to specify in error messages.\n        :return: The validated and casted version of the given value.\n        :raises ValueError: If it is a numeric value less than or equal to\n            zero, or the type is not an integer, float, or None.\n        \"\"\"\n        if value is None or value is _DEFAULT_TIMEOUT:\n            return value\n\n        if isinstance(value, bool):\n            raise ValueError(\n                \"Timeout cannot be a boolean value. It must \"\n                \"be an int, float or None.\"\n            )\n        try:\n            float(value)\n        except (TypeError, ValueError):\n            raise ValueError(\n                \"Timeout value %s was %s, but it must be an \"\n                \"int, float or None.\" % (name, value)\n            ) from None\n\n        try:\n            if value <= 0:\n                raise ValueError(\n                    \"Attempted to set %s timeout to %s, but the \"\n                    \"timeout cannot be set to a value less \"\n                    \"than or equal to 0.\" % (name, value)\n                )\n        except TypeError:\n            raise ValueError(\n                \"Timeout value %s was %s, but it must be an \"\n                \"int, float or None.\" % (name, value)\n            ) from None\n\n        return value\n\n    @classmethod\n    def from_float(cls, timeout: _TYPE_TIMEOUT) -> Timeout:\n        \"\"\"Create a new Timeout from a legacy timeout value.\n\n        The timeout value used by httplib.py sets the same timeout on the\n        connect(), and recv() socket requests. This creates a :class:`Timeout`\n        object that sets the individual timeouts to the ``timeout`` value\n        passed to this function.\n\n        :param timeout: The legacy timeout value.\n        :type timeout: integer, float, :attr:`urllib3.util.Timeout.DEFAULT_TIMEOUT`, or None\n        :return: Timeout object\n        :rtype: :class:`Timeout`\n        \"\"\"\n        return Timeout(read=timeout, connect=timeout)\n\n    def clone(self) -> Timeout:\n        \"\"\"Create a copy of the timeout object\n\n        Timeout properties are stored per-pool but each request needs a fresh\n        Timeout object to ensure each one has its own start/stop configured.\n\n        :return: a copy of the timeout object\n        :rtype: :class:`Timeout`\n        \"\"\"\n        # We can't use copy.deepcopy because that will also create a new object\n        # for _GLOBAL_DEFAULT_TIMEOUT, which socket.py uses as a sentinel to\n        # detect the user default.\n        return Timeout(connect=self._connect, read=self._read, total=self.total)\n\n    def start_connect(self) -> float:\n        \"\"\"Start the timeout clock, used during a connect() attempt\n\n        :raises urllib3.exceptions.TimeoutStateError: if you attempt\n            to start a timer that has been started already.\n        \"\"\"\n        if self._start_connect is not None:\n            raise TimeoutStateError(\"Timeout timer has already been started.\")\n        self._start_connect = time.monotonic()\n        return self._start_connect\n\n    def get_connect_duration(self) -> float:\n        \"\"\"Gets the time elapsed since the call to :meth:`start_connect`.\n\n        :return: Elapsed time in seconds.\n        :rtype: float\n        :raises urllib3.exceptions.TimeoutStateError: if you attempt\n            to get duration for a timer that hasn't been started.\n        \"\"\"\n        if self._start_connect is None:\n            raise TimeoutStateError(\n                \"Can't get connect duration for timer that has not started.\"\n            )\n        return time.monotonic() - self._start_connect\n\n    @property\n    def connect_timeout(self) -> _TYPE_TIMEOUT:\n        \"\"\"Get the value to use when setting a connection timeout.\n\n        This will be a positive float or integer, the value None\n        (never timeout), or the default system timeout.\n\n        :return: Connect timeout.\n        :rtype: int, float, :attr:`Timeout.DEFAULT_TIMEOUT` or None\n        \"\"\"\n        if self.total is None:\n            return self._connect\n\n        if self._connect is None or self._connect is _DEFAULT_TIMEOUT:\n            return self.total\n\n        return min(self._connect, self.total)  # type: ignore[type-var]\n\n    @property\n    def read_timeout(self) -> float | None:\n        \"\"\"Get the value for the read timeout.\n\n        This assumes some time has elapsed in the connection timeout and\n        computes the read timeout appropriately.\n\n        If self.total is set, the read timeout is dependent on the amount of\n        time taken by the connect timeout. If the connection time has not been\n        established, a :exc:`~urllib3.exceptions.TimeoutStateError` will be\n        raised.\n\n        :return: Value to use for the read timeout.\n        :rtype: int, float or None\n        :raises urllib3.exceptions.TimeoutStateError: If :meth:`start_connect`\n            has not yet been called on this object.\n        \"\"\"\n        if (\n            self.total is not None\n            and self.total is not _DEFAULT_TIMEOUT\n            and self._read is not None\n            and self._read is not _DEFAULT_TIMEOUT\n        ):\n            # In case the connect timeout has not yet been established.\n            if self._start_connect is None:\n                return self._read\n            return max(0, min(self.total - self.get_connect_duration(), self._read))\n        elif self.total is not None and self.total is not _DEFAULT_TIMEOUT:\n            return max(0, self.total - self.get_connect_duration())\n        else:\n            return self.resolve_default_timeout(self._read)\n", "path": "src/urllib3/util/timeout.py"}]}