Debian Codegraph @

Lib/test/support/__init__.py

raw
1 """Supporting definitions for the Python regression tests."""
2
3 if __name__ != 'test.support':
4 raise ImportError('support must be imported from the test package')
5
6 import annotationlib
7 import contextlib
8 import functools
9 import inspect
10 import logging
11 import _opcode
12 import os
13 import re
14 import stat
15 import sys
16 import sysconfig
17 import textwrap
18 import time
19 import types
20 import unittest
21 import warnings
22
23
24 __all__ = [
25 # globals
26 "PIPE_MAX_SIZE", "verbose", "max_memuse", "use_resources", "failfast",
27 # exceptions
28 "Error", "TestFailed", "TestDidNotRun", "ResourceDenied",
29 # io
30 "record_original_stdout", "get_original_stdout", "captured_stdout",
31 "captured_stdin", "captured_stderr", "captured_output",
32 # unittest
33 "is_resource_enabled", "get_resource_value", "requires", "requires_resource",
34 "requires_freebsd_version",
35 "requires_gil_enabled", "requires_linux_version", "requires_mac_ver",
36 "check_syntax_error",
37 "requires_gzip", "requires_bz2", "requires_lzma", "requires_zstd",
38 "bigmemtest", "bigaddrspacetest", "cpython_only", "get_attribute",
39 "requires_IEEE_754", "requires_zlib",
40 "has_fork_support", "requires_fork",
41 "has_subprocess_support", "requires_subprocess",
42 "has_socket_support", "requires_working_socket",
43 "anticipate_failure", "load_package_tests", "detect_api_mismatch",
44 "check__all__", "skip_if_buggy_ucrt_strfptime",
45 "check_disallow_instantiation", "check_sanitizer", "skip_if_sanitizer",
46 "requires_limited_api", "requires_specialization", "thread_unsafe",
47 "skip_if_unlimited_stack_size",
48 # sys
49 "MS_WINDOWS", "is_jython", "is_android", "is_emscripten", "is_wasi",
50 "is_apple_mobile", "check_impl_detail", "unix_shell", "setswitchinterval",
51 "support_remote_exec_only",
52 # os
53 "get_pagesize",
54 # network
55 "open_urlresource",
56 # processes
57 "reap_children",
58 # miscellaneous
59 "run_with_locale", "swap_item", "findfile", "infinite_recursion",
60 "swap_attr", "Matcher", "set_memlimit", "SuppressCrashReport", "sortdict",
61 "run_with_tz", "PGO", "missing_compiler_executable",
62 "ALWAYS_EQ", "NEVER_EQ", "LARGEST", "SMALLEST",
63 "LOOPBACK_TIMEOUT", "INTERNET_TIMEOUT", "SHORT_TIMEOUT", "LONG_TIMEOUT",
64 "Py_DEBUG", "exceeds_recursion_limit", "skip_on_s390x",
65 "requires_jit_enabled",
66 "requires_jit_disabled",
67 "force_not_colorized",
68 "force_not_colorized_test_class",
69 "make_clean_env",
70 "BrokenIter",
71 "in_systemd_nspawn_sync_suppressed",
72 "run_no_yield_async_fn", "run_yielding_async_fn", "async_yield",
73 "reset_code", "on_github_actions"
74 ]
75
76
77 # Timeout in seconds for tests using a network server listening on the network
78 # local loopback interface like 127.0.0.1.
79 #
80 # The timeout is long enough to prevent test failure: it takes into account
81 # that the client and the server can run in different threads or even different
82 # processes.
83 #
84 # The timeout should be long enough for connect(), recv() and send() methods
85 # of socket.socket.
86 LOOPBACK_TIMEOUT = 10.0
87
88 # Timeout in seconds for network requests going to the internet. The timeout is
89 # short enough to prevent a test to wait for too long if the internet request
90 # is blocked for whatever reason.
91 #
92 # Usually, a timeout using INTERNET_TIMEOUT should not mark a test as failed,
93 # but skip the test instead: see transient_internet().
94 INTERNET_TIMEOUT = 60.0
95
96 # Timeout in seconds to mark a test as failed if the test takes "too long".
97 #
98 # The timeout value depends on the regrtest --timeout command line option.
99 #
100 # If a test using SHORT_TIMEOUT starts to fail randomly on slow buildbots, use
101 # LONG_TIMEOUT instead.
102 SHORT_TIMEOUT = 30.0
103
104 # Timeout in seconds to detect when a test hangs.
105 #
106 # It is long enough to reduce the risk of test failure on the slowest Python
107 # buildbots. It should not be used to mark a test as failed if the test takes
108 # "too long". The timeout value depends on the regrtest --timeout command line
109 # option.
110 LONG_TIMEOUT = 5 * 60.0
111
112 # TEST_HOME_DIR refers to the top level directory of the "test" package
113 # that contains Python's regression test suite
114 TEST_SUPPORT_DIR = os.path.dirname(os.path.abspath(__file__))
115 TEST_HOME_DIR = os.path.dirname(TEST_SUPPORT_DIR)
116 STDLIB_DIR = os.path.dirname(TEST_HOME_DIR)
117 REPO_ROOT = os.path.dirname(STDLIB_DIR)
118
119
120 class Error(Exception):
121 """Base class for regression test exceptions."""
122
123 class TestFailed(Error):
124 """Test failed."""
125 def __init__(self, msg, *args, stats=None):
126 self.msg = msg
127 self.stats = stats
128 super().__init__(msg, *args)
129
130 def __str__(self):
131 return self.msg
132
133 class TestFailedWithDetails(TestFailed):
134 """Test failed."""
135 def __init__(self, msg, errors, failures, stats):
136 self.errors = errors
137 self.failures = failures
138 super().__init__(msg, errors, failures, stats=stats)
139
140 class TestDidNotRun(Error):
141 """Test did not run any subtests."""
142
143 class ResourceDenied(unittest.SkipTest):
144 """Test skipped because it requested a disallowed resource.
145
146 This is raised when a test calls requires() for a resource that
147 has not be enabled. It is used to distinguish between expected
148 and unexpected skips.
149 """
150
151 def anticipate_failure(condition):
152 """Decorator to mark a test that is known to be broken in some cases
153
154 Any use of this decorator should have a comment identifying the
155 associated tracker issue.
156 """
157 if condition:
158 return unittest.expectedFailure
159 return lambda f: f
160
161 def load_package_tests(pkg_dir, loader, standard_tests, pattern):
162 """Generic load_tests implementation for simple test packages.
163
164 Most packages can implement load_tests using this function as follows:
165
166 def load_tests(*args):
167 return load_package_tests(os.path.dirname(__file__), *args)
168 """
169 if pattern is None:
170 pattern = "test*"
171 top_dir = STDLIB_DIR
172 package_tests = loader.discover(start_dir=pkg_dir,
173 top_level_dir=top_dir,
174 pattern=pattern)
175 standard_tests.addTests(package_tests)
176 return standard_tests
177
178
179 def get_attribute(obj, name):
180 """Get an attribute, raising SkipTest if AttributeError is raised."""
181 try:
182 attribute = getattr(obj, name)
183 except AttributeError:
184 raise unittest.SkipTest("object %r has no attribute %r" % (obj, name))
185 else:
186 return attribute
187
188 verbose = 1 # Flag set to 0 by regrtest.py
189 use_resources = None # Flag set to {} by regrtest.py
190 max_memuse = 0 # Disable bigmem tests (they will still be run with
191 # small sizes, to make sure they work.)
192 real_max_memuse = 0
193 junit_xml_list = None # list of testsuite XML elements
194 failfast = False
195
196 # _original_stdout is meant to hold stdout at the time regrtest began.
197 # This may be "the real" stdout, or IDLE's emulation of stdout, or whatever.
198 # The point is to have some flavor of stdout the user can actually see.
199 _original_stdout = None
200 def record_original_stdout(stdout):
201 global _original_stdout
202 _original_stdout = stdout
203
204 def get_original_stdout():
205 return _original_stdout or sys.stdout
206
207
208 def _force_run(path, func, *args):
209 try:
210 return func(*args)
211 except FileNotFoundError as err:
212 # chmod() won't fix a missing file.
213 if verbose >= 2:
214 print('%s: %s' % (err.__class__.__name__, err))
215 raise
216 except OSError as err:
217 if verbose >= 2:
218 print('%s: %s' % (err.__class__.__name__, err))
219 print('re-run %s%r' % (func.__name__, args))
220 os.chmod(path, stat.S_IRWXU)
221 return func(*args)
222
223
224 # Check whether a gui is actually available
225 def _is_gui_available():
226 if hasattr(_is_gui_available, 'result'):
227 return _is_gui_available.result
228 import platform
229 reason = None
230 if sys.platform.startswith('win') and platform.win32_is_iot():
231 reason = "gui is not available on Windows IoT Core"
232 elif sys.platform.startswith('win'):
233 # if Python is running as a service (such as the buildbot service),
234 # gui interaction may be disallowed
235 import ctypes
236 import ctypes.wintypes
237 UOI_FLAGS = 1
238 WSF_VISIBLE = 0x0001
239 class USEROBJECTFLAGS(ctypes.Structure):
240 _fields_ = [("fInherit", ctypes.wintypes.BOOL),
241 ("fReserved", ctypes.wintypes.BOOL),
242 ("dwFlags", ctypes.wintypes.DWORD)]
243 dll = ctypes.windll.user32
244 h = dll.GetProcessWindowStation()
245 if not h:
246 raise ctypes.WinError()
247 uof = USEROBJECTFLAGS()
248 needed = ctypes.wintypes.DWORD()
249 res = dll.GetUserObjectInformationW(h,
250 UOI_FLAGS,
251 ctypes.byref(uof),
252 ctypes.sizeof(uof),
253 ctypes.byref(needed))
254 if not res:
255 raise ctypes.WinError()
256 if not bool(uof.dwFlags & WSF_VISIBLE):
257 reason = "gui not available (WSF_VISIBLE flag not set)"
258 elif sys.platform == 'darwin':
259 # The Aqua Tk implementations on OS X can abort the process if
260 # being called in an environment where a window server connection
261 # cannot be made, for instance when invoked by a buildbot or ssh
262 # process not running under the same user id as the current console
263 # user. To avoid that, raise an exception if the window manager
264 # connection is not available.
265 import subprocess
266 try:
267 rc = subprocess.run(["launchctl", "managername"],
268 capture_output=True, check=True)
269 managername = rc.stdout.decode("utf-8").strip()
270 except subprocess.CalledProcessError:
271 reason = "unable to detect macOS launchd job manager"
272 else:
273 if managername != "Aqua":
274 reason = f"{managername=} -- can only run in a macOS GUI session"
275
276 # check on every platform whether tkinter can actually do anything
277 if not reason:
278 try:
279 from tkinter import Tk
280 root = Tk()
281 root.withdraw()
282 root.update()
283 root.destroy()
284 except Exception as e:
285 err_string = str(e)
286 if len(err_string) > 50:
287 err_string = err_string[:50] + ' [...]'
288 reason = 'Tk unavailable due to {}: {}'.format(type(e).__name__,
289 err_string)
290
291 _is_gui_available.reason = reason
292 _is_gui_available.result = not reason
293
294 return _is_gui_available.result
295
296 def is_resource_enabled(resource):
297 """Test whether a resource is enabled.
298
299 Known resources are set by regrtest.py. If not running under regrtest.py,
300 all resources are assumed enabled unless use_resources has been set.
301 """
302 return use_resources is None or resource in use_resources
303
304 def get_resource_value(resource):
305 """Test whether a resource is enabled.
306
307 Known resources are set by regrtest.py. If not running under regrtest.py,
308 all resources are assumed enabled unless use_resources has been set.
309 """
310 if use_resources is None:
311 return None
312 return use_resources.get(resource)
313
314 def requires(resource, msg=None):
315 """Raise ResourceDenied if the specified resource is not available."""
316 if not is_resource_enabled(resource):
317 if msg is None:
318 msg = "Use of the %r resource not enabled" % resource
319 raise ResourceDenied(msg)
320 if resource in {"network", "urlfetch"} and not has_socket_support:
321 raise ResourceDenied("No socket support")
322 if resource == 'gui' and not _is_gui_available():
323 raise ResourceDenied(_is_gui_available.reason)
324
325 def _get_kernel_version(sysname="Linux"):
326 import platform
327 if platform.system() != sysname:
328 return None
329 version_txt = platform.release().split('-', 1)[0]
330 try:
331 return tuple(map(int, version_txt.split('.')))
332 except ValueError:
333 return None
334
335 def _requires_unix_version(sysname, min_version):
336 """Decorator raising SkipTest if the OS is `sysname` and the version is less
337 than `min_version`.
338
339 For example, @_requires_unix_version('FreeBSD', (7, 2)) raises SkipTest if
340 the FreeBSD version is less than 7.2.
341 """
342 import platform
343 min_version_txt = '.'.join(map(str, min_version))
344 version_txt = platform.release().split('-', 1)[0]
345 if platform.system() == sysname:
346 try:
347 version = tuple(map(int, version_txt.split('.')))
348 except ValueError:
349 skip = False
350 else:
351 skip = version < min_version
352 else:
353 skip = False
354
355 return unittest.skipIf(
356 skip,
357 f"{sysname} version {min_version_txt} or higher required, not "
358 f"{version_txt}"
359 )
360
361
362 def requires_freebsd_version(*min_version):
363 """Decorator raising SkipTest if the OS is FreeBSD and the FreeBSD version is
364 less than `min_version`.
365
366 For example, @requires_freebsd_version(7, 2) raises SkipTest if the FreeBSD
367 version is less than 7.2.
368 """
369 return _requires_unix_version('FreeBSD', min_version)
370
371 def requires_linux_version(*min_version):
372 """Decorator raising SkipTest if the OS is Linux and the Linux version is
373 less than `min_version`.
374
375 For example, @requires_linux_version(2, 6, 32) raises SkipTest if the Linux
376 version is less than 2.6.32.
377 """
378 return _requires_unix_version('Linux', min_version)
379
380 def requires_mac_ver(*min_version):
381 """Decorator raising SkipTest if the OS is Mac OS X and the OS X
382 version if less than min_version.
383
384 For example, @requires_mac_ver(10, 5) raises SkipTest if the OS X version
385 is lesser than 10.5.
386 """
387 def decorator(func):
388 @functools.wraps(func)
389 def wrapper(*args, **kw):
390 if sys.platform == 'darwin':
391 import platform
392 version_txt = platform.mac_ver()[0]
393 try:
394 version = tuple(map(int, version_txt.split('.')))
395 except ValueError:
396 pass
397 else:
398 if version < min_version:
399 min_version_txt = '.'.join(map(str, min_version))
400 raise unittest.SkipTest(
401 "Mac OS X %s or higher required, not %s"
402 % (min_version_txt, version_txt))
403 return func(*args, **kw)
404 wrapper.min_version = min_version
405 return wrapper
406 return decorator
407
408
409 def thread_unsafe(reason):
410 """Mark a test as not thread safe. When the test runner is run with
411 --parallel-threads=N, the test will be run in a single thread."""
412 def decorator(test_item):
413 test_item.__unittest_thread_unsafe__ = True
414 # the reason is not currently used
415 test_item.__unittest_thread_unsafe__why__ = reason
416 return test_item
417 if isinstance(reason, types.FunctionType):
418 test_item = reason
419 reason = ''
420 return decorator(test_item)
421 return decorator
422
423
424 def skip_if_buildbot(reason=None):
425 """Decorator raising SkipTest if running on a buildbot."""
426 import getpass
427 if not reason:
428 reason = 'not suitable for buildbots'
429 try:
430 isbuildbot = getpass.getuser().lower() == 'buildbot'
431 except (KeyError, OSError) as err:
432 logging.getLogger(__name__).warning('getpass.getuser() failed %s.', err, exc_info=err)
433 isbuildbot = False
434 return unittest.skipIf(isbuildbot, reason)
435
436 def check_sanitizer(*, address=False, memory=False, ub=False, thread=False,
437 function=True):
438 """Returns True if Python is compiled with sanitizer support"""
439 if not (address or memory or ub or thread):
440 raise ValueError('At least one of address, memory, ub or thread must be True')
441
442
443 cflags = sysconfig.get_config_var('CFLAGS') or ''
444 config_args = sysconfig.get_config_var('CONFIG_ARGS') or ''
445 memory_sanitizer = (
446 '-fsanitize=memory' in cflags or
447 '--with-memory-sanitizer' in config_args
448 )
449 address_sanitizer = (
450 '-fsanitize=address' in cflags or
451 '--with-address-sanitizer' in config_args
452 )
453 ub_sanitizer = (
454 '-fsanitize=undefined' in cflags or
455 '--with-undefined-behavior-sanitizer' in config_args
456 )
457 thread_sanitizer = (
458 '-fsanitize=thread' in cflags or
459 '--with-thread-sanitizer' in config_args
460 )
461 function_sanitizer = (
462 '-fsanitize=function' in cflags
463 )
464 return (
465 (memory and memory_sanitizer) or
466 (address and address_sanitizer) or
467 (ub and ub_sanitizer) or
468 (thread and thread_sanitizer) or
469 (function and function_sanitizer)
470 )
471
472
473 def skip_if_sanitizer(reason=None, *, address=False, memory=False, ub=False, thread=False):
474 """Decorator raising SkipTest if running with a sanitizer active."""
475 if not reason:
476 reason = 'not working with sanitizers active'
477 skip = check_sanitizer(address=address, memory=memory, ub=ub, thread=thread)
478 return unittest.skipIf(skip, reason)
479
480 # gh-89363: True if fork() can hang if Python is built with Address Sanitizer
481 # (ASAN): libasan race condition, dead lock in pthread_create().
482 HAVE_ASAN_FORK_BUG = check_sanitizer(address=True)
483
484
485 def set_sanitizer_env_var(env, option):
486 for name in ('ASAN_OPTIONS', 'MSAN_OPTIONS', 'UBSAN_OPTIONS', 'TSAN_OPTIONS'):
487 if name in env:
488 env[name] += f':{option}'
489 else:
490 env[name] = option
491
492
493 def system_must_validate_cert(f):
494 """Skip the test on TLS certificate validation failures."""
495 @functools.wraps(f)
496 def dec(*args, **kwargs):
497 try:
498 f(*args, **kwargs)
499 except OSError as e:
500 if "CERTIFICATE_VERIFY_FAILED" in str(e):
501 raise unittest.SkipTest("system does not contain "
502 "necessary certificates")
503 raise
504 return dec
505
506 # A constant likely larger than the underlying OS pipe buffer size, to
507 # make writes blocking.
508 # Windows limit seems to be around 512 B, and many Unix kernels have a
509 # 64 KiB pipe buffer size or 16 * PAGE_SIZE: take a few megs to be sure.
510 # (see issue #17835 for a discussion of this number).
511 PIPE_MAX_SIZE = 4 * 1024 * 1024 + 1
512
513 # A constant likely larger than the underlying OS socket buffer size, to make
514 # writes blocking.
515 # The socket buffer sizes can usually be tuned system-wide (e.g. through sysctl
516 # on Linux), or on a per-socket basis (SO_SNDBUF/SO_RCVBUF). See issue #18643
517 # for a discussion of this number.
518 SOCK_MAX_SIZE = 16 * 1024 * 1024 + 1
519
520 # decorator for skipping tests on non-IEEE 754 platforms
521 requires_IEEE_754 = unittest.skipUnless(
522 float.__getformat__("double").startswith("IEEE"),
523 "test requires IEEE 754 doubles")
524
525 def requires_zlib(reason='requires zlib'):
526 try:
527 import zlib
528 except ImportError:
529 zlib = None
530 return unittest.skipUnless(zlib, reason)
531
532 def requires_gzip(reason='requires gzip'):
533 try:
534 import gzip
535 except ImportError:
536 gzip = None
537 return unittest.skipUnless(gzip, reason)
538
539 def requires_bz2(reason='requires bz2'):
540 try:
541 import bz2
542 except ImportError:
543 bz2 = None
544 return unittest.skipUnless(bz2, reason)
545
546 def requires_lzma(reason='requires lzma'):
547 try:
548 import lzma
549 except ImportError:
550 lzma = None
551 return unittest.skipUnless(lzma, reason)
552
553 def requires_zstd(reason='requires zstd'):
554 try:
555 from compression import zstd
556 except ImportError:
557 zstd = None
558 return unittest.skipUnless(zstd, reason)
559
560 def has_no_debug_ranges():
561 try:
562 import _testcapi
563 except ImportError:
564 raise unittest.SkipTest("_testinternalcapi required")
565 return not _testcapi.config_get('code_debug_ranges')
566
567 def requires_debug_ranges(reason='requires co_positions / debug_ranges'):
568 try:
569 skip = has_no_debug_ranges()
570 except unittest.SkipTest as e:
571 skip = True
572 reason = e.args[0] if e.args else reason
573 return unittest.skipIf(skip, reason)
574
575
576 MS_WINDOWS = (sys.platform == 'win32')
577
578 # Is not actually used in tests, but is kept for compatibility.
579 is_jython = sys.platform.startswith('java')
580
581 is_android = sys.platform == "android"
582
583 def skip_android_selinux(name):
584 return unittest.skipIf(
585 sys.platform == "android", f"Android blocks {name} with SELinux"
586 )
587
588 if sys.platform not in {"win32", "vxworks", "ios", "tvos", "watchos"}:
589 unix_shell = '/system/bin/sh' if is_android else '/bin/sh'
590 else:
591 unix_shell = None
592
593 # wasm32-emscripten and -wasi are POSIX-like but do not
594 # have subprocess or fork support.
595 is_emscripten = sys.platform == "emscripten"
596 is_wasi = sys.platform == "wasi"
597
598 # Use is_wasm32 as a generic check for WebAssembly platforms.
599 is_wasm32 = is_emscripten or is_wasi
600
601 def skip_emscripten_stack_overflow():
602 return unittest.skipIf(is_emscripten, "Exhausts stack on Emscripten")
603
604 def skip_wasi_stack_overflow():
605 return unittest.skipIf(is_wasi, "Exhausts stack on WASI")
606
607 is_apple_mobile = sys.platform in {"ios", "tvos", "watchos"}
608 is_apple = is_apple_mobile or sys.platform == "darwin"
609
610 has_fork_support = hasattr(os, "fork") and not (
611 # WASM and Apple mobile platforms do not support subprocesses.
612 is_emscripten
613 or is_wasi
614 or is_apple_mobile
615
616 # Although Android supports fork, it's unsafe to call it from Python because
617 # all Android apps are multi-threaded.
618 or is_android
619 )
620
621 def requires_fork():
622 return unittest.skipUnless(has_fork_support, "requires working os.fork()")
623
624 has_subprocess_support = not (
625 # WASM and Apple mobile platforms do not support subprocesses.
626 is_emscripten
627 or is_wasi
628 or is_apple_mobile
629
630 # Although Android supports subproceses, they're almost never useful in
631 # practice (see PEP 738). And most of the tests that use them are calling
632 # sys.executable, which won't work when Python is embedded in an Android app.
633 or is_android
634 )
635
636 def requires_subprocess():
637 """Used for subprocess, os.spawn calls, fd inheritance"""
638 return unittest.skipUnless(has_subprocess_support, "requires subprocess support")
639
640 # Emscripten's socket emulation and WASI sockets have limitations.
641 has_socket_support = not (
642 is_emscripten
643 or is_wasi
644 )
645
646 def requires_working_socket(*, module=False):
647 """Skip tests or modules that require working sockets
648
649 Can be used as a function/class decorator or to skip an entire module.
650 """
651 msg = "requires socket support"
652 if module:
653 if not has_socket_support:
654 raise unittest.SkipTest(msg)
655 else:
656 return unittest.skipUnless(has_socket_support, msg)
657
658 # Does strftime() support glibc extension like '%4Y'?
659 has_strftime_extensions = False
660 if sys.platform != "win32":
661 # bpo-47037: Windows debug builds crash with "Debug Assertion Failed"
662 try:
663 has_strftime_extensions = time.strftime("%4Y") != "%4Y"
664 except ValueError:
665 pass
666
667 # Define the URL of a dedicated HTTP server for the network tests.
668 # The URL must use clear-text HTTP: no redirection to encrypted HTTPS.
669 TEST_HTTP_URL = "http://www.pythontest.net"
670
671 # Set by libregrtest/main.py so we can skip tests that are not
672 # useful for PGO
673 PGO = False
674
675 # Set by libregrtest/main.py if we are running the extended (time consuming)
676 # PGO task. If this is True, PGO is also True.
677 PGO_EXTENDED = False
678
679 # TEST_DATA_DIR is used as a target download location for remote resources
680 TEST_DATA_DIR = os.path.join(TEST_HOME_DIR, "data")
681
682
683 def darwin_malloc_err_warning(test_name):
684 """Assure user that loud errors generated by macOS libc's malloc are
685 expected."""
686 if sys.platform != 'darwin':
687 return
688
689 import shutil
690 msg = ' NOTICE '
691 detail = (f'{test_name} may generate "malloc can\'t allocate region"\n'
692 'warnings on macOS systems. This behavior is known. Do not\n'
693 'report a bug unless tests are also failing.\n'
694 'See https://github.com/python/cpython/issues/85100')
695
696 padding, _ = shutil.get_terminal_size()
697 print(msg.center(padding, '-'))
698 print(detail)
699 print('-' * padding)
700
701
702 def findfile(filename, subdir=None):
703 """Try to find a file on sys.path or in the test directory. If it is not
704 found the argument passed to the function is returned (this does not
705 necessarily signal failure; could still be the legitimate path).
706
707 Setting *subdir* indicates a relative path to use to find the file
708 rather than looking directly in the path directories.
709 """
710 if os.path.isabs(filename):
711 return filename
712 if subdir is not None:
713 filename = os.path.join(subdir, filename)
714 path = [TEST_HOME_DIR] + sys.path
715 for dn in path:
716 fn = os.path.join(dn, filename)
717 if os.path.exists(fn): return fn
718 return filename
719
720
721 def sortdict(dict):
722 "Like repr(dict), but in sorted order."
723 items = sorted(dict.items())
724 reprpairs = ["%r: %r" % pair for pair in items]
725 withcommas = ", ".join(reprpairs)
726 return "{%s}" % withcommas
727
728
729 def run_code(code: str, extra_names: dict[str, object] | None = None) -> dict[str, object]:
730 """Run a piece of code after dedenting it, and return its global namespace."""
731 ns = {}
732 if extra_names:
733 ns.update(extra_names)
734 exec(textwrap.dedent(code), ns)
735 return ns
736
737
738 def check_syntax_error(testcase, statement, errtext='', *, lineno=None, offset=None):
739 with testcase.assertRaisesRegex(SyntaxError, errtext) as cm:
740 compile(statement, '<test string>', 'exec')
741 err = cm.exception
742 testcase.assertIsNotNone(err.lineno)
743 if lineno is not None:
744 testcase.assertEqual(err.lineno, lineno)
745 testcase.assertIsNotNone(err.offset)
746 if offset is not None:
747 testcase.assertEqual(err.offset, offset)
748
749
750 def open_urlresource(url, *args, **kw):
751 import urllib.request, urllib.parse
752 from .os_helper import unlink
753 try:
754 import gzip
755 except ImportError:
756 gzip = None
757
758 check = kw.pop('check', None)
759
760 filename = urllib.parse.urlparse(url)[2].split('/')[-1] # '/': it's URL!
761
762 fn = os.path.join(TEST_DATA_DIR, filename)
763
764 def check_valid_file(fn):
765 f = open(fn, *args, **kw)
766 if check is None:
767 return f
768 elif check(f):
769 f.seek(0)
770 return f
771 f.close()
772
773 if os.path.exists(fn):
774 f = check_valid_file(fn)
775 if f is not None:
776 return f
777 unlink(fn)
778
779 # Verify the requirement before downloading the file
780 requires('urlfetch')
781
782 if verbose:
783 print('\tfetching %s ...' % url, file=get_original_stdout())
784 opener = urllib.request.build_opener()
785 if gzip:
786 opener.addheaders.append(('Accept-Encoding', 'gzip'))
787 f = opener.open(url, timeout=INTERNET_TIMEOUT)
788 if gzip and f.headers.get('Content-Encoding') == 'gzip':
789 f = gzip.GzipFile(fileobj=f)
790 try:
791 with open(fn, "wb") as out:
792 s = f.read()
793 while s:
794 out.write(s)
795 s = f.read()
796 finally:
797 f.close()
798
799 f = check_valid_file(fn)
800 if f is not None:
801 return f
802 raise TestFailed('invalid resource %r' % fn)
803
804
805 @contextlib.contextmanager
806 def captured_output(stream_name):
807 """Return a context manager used by captured_stdout/stdin/stderr
808 that temporarily replaces the sys stream *stream_name* with a StringIO."""
809 import io
810 orig_stdout = getattr(sys, stream_name)
811 setattr(sys, stream_name, io.StringIO())
812 try:
813 yield getattr(sys, stream_name)
814 finally:
815 setattr(sys, stream_name, orig_stdout)
816
817 def captured_stdout():
818 """Capture the output of sys.stdout:
819
820 with captured_stdout() as stdout:
821 print("hello")
822 self.assertEqual(stdout.getvalue(), "hello\\n")
823 """
824 return captured_output("stdout")
825
826 def captured_stderr():
827 """Capture the output of sys.stderr:
828
829 with captured_stderr() as stderr:
830 print("hello", file=sys.stderr)
831 self.assertEqual(stderr.getvalue(), "hello\\n")
832 """
833 return captured_output("stderr")
834
835 def captured_stdin():
836 """Capture the input to sys.stdin:
837
838 with captured_stdin() as stdin:
839 stdin.write('hello\\n')
840 stdin.seek(0)
841 # call test code that consumes from sys.stdin
842 captured = input()
843 self.assertEqual(captured, "hello")
844 """
845 return captured_output("stdin")
846
847
848 def gc_collect():
849 """Force as many objects as possible to be collected.
850
851 In non-CPython implementations of Python, this is needed because timely
852 deallocation is not guaranteed by the garbage collector. (Even in CPython
853 this can be the case in case of reference cycles.) This means that __del__
854 methods may be called later than expected and weakrefs may remain alive for
855 longer than expected. This function tries its best to force all garbage
856 objects to disappear.
857 """
858 import gc
859 gc.collect()
860 gc.collect()
861 gc.collect()
862
863 @contextlib.contextmanager
864 def disable_gc():
865 import gc
866 have_gc = gc.isenabled()
867 gc.disable()
868 try:
869 yield
870 finally:
871 if have_gc:
872 gc.enable()
873
874 @contextlib.contextmanager
875 def gc_threshold(*args):
876 import gc
877 old_threshold = gc.get_threshold()
878 gc.set_threshold(*args)
879 try:
880 yield
881 finally:
882 gc.set_threshold(*old_threshold)
883
884 def python_is_optimized():
885 """Find if Python was built with optimizations."""
886 cflags = sysconfig.get_config_var('PY_CFLAGS') or ''
887 final_opt = ""
888 for opt in cflags.split():
889 if opt.startswith('-O'):
890 final_opt = opt
891 if sysconfig.get_config_var("CC") == "gcc":
892 non_opts = ('', '-O0', '-Og')
893 else:
894 non_opts = ('', '-O0')
895 return final_opt not in non_opts
896
897
898 def check_cflags_pgo():
899 # Check if Python was built with ./configure --enable-optimizations:
900 # with Profile Guided Optimization (PGO).
901 cflags_nodist = sysconfig.get_config_var('PY_CFLAGS_NODIST') or ''
902 pgo_options = [
903 # GCC
904 '-fprofile-use',
905 # clang: -fprofile-instr-use=code.profclangd
906 '-fprofile-instr-use',
907 # ICC
908 "-prof-use",
909 ]
910 PGO_PROF_USE_FLAG = sysconfig.get_config_var('PGO_PROF_USE_FLAG')
911 if PGO_PROF_USE_FLAG:
912 pgo_options.append(PGO_PROF_USE_FLAG)
913 return any(option in cflags_nodist for option in pgo_options)
914
915
916 def check_bolt_optimized():
917 # Always return false, if the platform is WASI,
918 # because BOLT optimization does not support WASM binary.
919 if is_wasi:
920 return False
921 config_args = sysconfig.get_config_var('CONFIG_ARGS') or ''
922 return '--enable-bolt' in config_args
923
924
925 Py_GIL_DISABLED = bool(sysconfig.get_config_var('Py_GIL_DISABLED'))
926
927 def requires_gil_enabled(msg="needs the GIL enabled"):
928 """Decorator for skipping tests on the free-threaded build."""
929 return unittest.skipIf(Py_GIL_DISABLED, msg)
930
931 def expected_failure_if_gil_disabled():
932 """Expect test failure if the GIL is disabled."""
933 if Py_GIL_DISABLED:
934 return unittest.expectedFailure
935 return lambda test_case: test_case
936
937 if Py_GIL_DISABLED:
938 _header = 'PHBBInP'
939 else:
940 _header = 'nP'
941 _align = '0n'
942 _vheader = _header + 'n'
943
944 def calcobjsize(fmt):
945 import struct
946 return struct.calcsize(_header + fmt + _align)
947
948 def calcvobjsize(fmt):
949 import struct
950 return struct.calcsize(_vheader + fmt + _align)
951
952
953 _TPFLAGS_STATIC_BUILTIN = 1<<1
954 _TPFLAGS_DISALLOW_INSTANTIATION = 1<<7
955 _TPFLAGS_IMMUTABLETYPE = 1<<8
956 _TPFLAGS_HEAPTYPE = 1<<9
957 _TPFLAGS_BASETYPE = 1<<10
958 _TPFLAGS_READY = 1<<12
959 _TPFLAGS_READYING = 1<<13
960 _TPFLAGS_HAVE_GC = 1<<14
961 _TPFLAGS_BASE_EXC_SUBCLASS = 1<<30
962 _TPFLAGS_TYPE_SUBCLASS = 1<<31
963
964 def check_sizeof(test, o, size):
965 try:
966 import _testinternalcapi
967 except ImportError:
968 raise unittest.SkipTest("_testinternalcapi required")
969 result = sys.getsizeof(o)
970 # add GC header size
971 if ((type(o) == type) and (o.__flags__ & _TPFLAGS_HEAPTYPE) or\
972 ((type(o) != type) and (type(o).__flags__ & _TPFLAGS_HAVE_GC))):
973 size += _testinternalcapi.SIZEOF_PYGC_HEAD
974 msg = 'wrong size for %s: got %d, expected %d' \
975 % (type(o), result, size)
976 test.assertEqual(result, size, msg)
977
978 def subTests(arg_names, arg_values, /, *, _do_cleanups=False):
979 """Run multiple subtests with different parameters.
980 """
981 single_param = False
982 if isinstance(arg_names, str):
983 arg_names = arg_names.replace(',',' ').split()
984 if len(arg_names) == 1:
985 single_param = True
986 arg_values = tuple(arg_values)
987 def decorator(func):
988 if isinstance(func, type):
989 raise TypeError('subTests() can only decorate methods, not classes')
990 @functools.wraps(func)
991 def wrapper(self, /, *args, **kwargs):
992 for values in arg_values:
993 if single_param:
994 values = (values,)
995 subtest_kwargs = dict(zip(arg_names, values))
996 with self.subTest(**subtest_kwargs):
997 func(self, *args, **kwargs, **subtest_kwargs)
998 if _do_cleanups:
999 self.doCleanups()
1000 return wrapper
1001 return decorator
1002
1003 #=======================================================================
1004 # Decorator/context manager for running a code in a different locale,
1005 # correctly resetting it afterwards.
1006
1007 @contextlib.contextmanager
1008 def run_with_locale(catstr, *locales):
1009 try:
1010 import locale
1011 category = getattr(locale, catstr)
1012 orig_locale = locale.setlocale(category)
1013 except AttributeError:
1014 # if the test author gives us an invalid category string
1015 raise
1016 except Exception:
1017 # cannot retrieve original locale, so do nothing
1018 locale = orig_locale = None
1019 if '' not in locales:
1020 raise unittest.SkipTest('no locales')
1021 else:
1022 for loc in locales:
1023 try:
1024 locale.setlocale(category, loc)
1025 break
1026 except locale.Error:
1027 pass
1028 else:
1029 if '' not in locales:
1030 raise unittest.SkipTest(f'no locales {locales}')
1031
1032 try:
1033 yield
1034 finally:
1035 if locale and orig_locale:
1036 locale.setlocale(category, orig_locale)
1037
1038 #=======================================================================
1039 # Decorator for running a function in multiple locales (if they are
1040 # availasble) and resetting the original locale afterwards.
1041
1042 def run_with_locales(catstr, *locales):
1043 def deco(func):
1044 @functools.wraps(func)
1045 def wrapper(self, /, *args, **kwargs):
1046 dry_run = '' in locales
1047 try:
1048 import locale
1049 category = getattr(locale, catstr)
1050 orig_locale = locale.setlocale(category)
1051 except AttributeError:
1052 # if the test author gives us an invalid category string
1053 raise
1054 except Exception:
1055 # cannot retrieve original locale, so do nothing
1056 pass
1057 else:
1058 try:
1059 for loc in locales:
1060 with self.subTest(locale=loc):
1061 try:
1062 locale.setlocale(category, loc)
1063 except locale.Error:
1064 self.skipTest(f'no locale {loc!r}')
1065 else:
1066 dry_run = False
1067 func(self, *args, **kwargs)
1068 finally:
1069 locale.setlocale(category, orig_locale)
1070 if dry_run:
1071 # no locales available, so just run the test
1072 # with the current locale
1073 with self.subTest(locale=None):
1074 func(self, *args, **kwargs)
1075 return wrapper
1076 return deco
1077
1078 #=======================================================================
1079 # Decorator for running a function in a specific timezone, correctly
1080 # resetting it afterwards.
1081
1082 def run_with_tz(tz):
1083 def decorator(func):
1084 def inner(*args, **kwds):
1085 try:
1086 tzset = time.tzset
1087 except AttributeError:
1088 raise unittest.SkipTest("tzset required")
1089 if 'TZ' in os.environ:
1090 orig_tz = os.environ['TZ']
1091 else:
1092 orig_tz = None
1093 os.environ['TZ'] = tz
1094 tzset()
1095
1096 # now run the function, resetting the tz on exceptions
1097 try:
1098 return func(*args, **kwds)
1099 finally:
1100 if orig_tz is None:
1101 del os.environ['TZ']
1102 else:
1103 os.environ['TZ'] = orig_tz
1104 time.tzset()
1105
1106 inner.__name__ = func.__name__
1107 inner.__doc__ = func.__doc__
1108 return inner
1109 return decorator
1110
1111 #=======================================================================
1112 # Big-memory-test support. Separate from 'resources' because memory use
1113 # should be configurable.
1114
1115 # Some handy shorthands. Note that these are used for byte-limits as well
1116 # as size-limits, in the various bigmem tests
1117 _1M = 1024*1024
1118 _1G = 1024 * _1M
1119 _2G = 2 * _1G
1120 _4G = 4 * _1G
1121
1122 MAX_Py_ssize_t = sys.maxsize
1123
1124 def _parse_memlimit(limit: str) -> int:
1125 sizes = {
1126 'k': 1024,
1127 'm': _1M,
1128 'g': _1G,
1129 't': 1024*_1G,
1130 }
1131 m = re.match(r'(\d+(?:\.\d+)?) (K|M|G|T)b?$', limit,
1132 re.IGNORECASE | re.VERBOSE)
1133 if m is None:
1134 raise ValueError(f'Invalid memory limit: {limit!r}')
1135 return int(float(m.group(1)) * sizes[m.group(2).lower()])
1136
1137 def set_memlimit(limit: str) -> None:
1138 global max_memuse
1139 global real_max_memuse
1140 memlimit = _parse_memlimit(limit)
1141 if memlimit < _2G - 1:
1142 raise ValueError(f'Memory limit {limit!r} too low to be useful')
1143
1144 real_max_memuse = memlimit
1145 memlimit = min(memlimit, MAX_Py_ssize_t)
1146 max_memuse = memlimit
1147
1148
1149 class _MemoryWatchdog:
1150 """An object which periodically watches the process' memory consumption
1151 and prints it out.
1152 """
1153
1154 def __init__(self):
1155 self.procfile = '/proc/{pid}/statm'.format(pid=os.getpid())
1156 self.started = False
1157
1158 def start(self):
1159 import warnings
1160 try:
1161 f = open(self.procfile, 'r')
1162 except OSError as e:
1163 logging.getLogger(__name__).warning('/proc not available for stats: %s', e, exc_info=e)
1164 sys.stderr.flush()
1165 return
1166
1167 import subprocess
1168 with f:
1169 watchdog_script = findfile("memory_watchdog.py")
1170 self.mem_watchdog = subprocess.Popen([sys.executable, watchdog_script],
1171 stdin=f,
1172 stderr=subprocess.DEVNULL)
1173 self.started = True
1174
1175 def stop(self):
1176 if self.started:
1177 self.mem_watchdog.terminate()
1178 self.mem_watchdog.wait()
1179
1180
1181 def bigmemtest(size, memuse, dry_run=True):
1182 """Decorator for bigmem tests.
1183
1184 'size' is a requested size for the test (in arbitrary, test-interpreted
1185 units.) 'memuse' is the number of bytes per unit for the test, or a good
1186 estimate of it. For example, a test that needs two byte buffers, of 4 GiB
1187 each, could be decorated with @bigmemtest(size=_4G, memuse=2).
1188
1189 The 'size' argument is normally passed to the decorated test method as an
1190 extra argument. If 'dry_run' is true, the value passed to the test method
1191 may be less than the requested value. If 'dry_run' is false, it means the
1192 test doesn't support dummy runs when -M is not specified.
1193 """
1194 def decorator(f):
1195 def wrapper(self):
1196 size = wrapper.size
1197 memuse = wrapper.memuse
1198 if not real_max_memuse:
1199 maxsize = 5147
1200 else:
1201 maxsize = size
1202
1203 if ((real_max_memuse or not dry_run)
1204 and real_max_memuse < maxsize * memuse):
1205 raise unittest.SkipTest(
1206 "not enough memory: %.1fG minimum needed"
1207 % (size * memuse / (1024 ** 3)))
1208
1209 if real_max_memuse and verbose:
1210 print()
1211 print(" ... expected peak memory use: {peak:.1f}G"
1212 .format(peak=size * memuse / (1024 ** 3)))
1213 watchdog = _MemoryWatchdog()
1214 watchdog.start()
1215 else:
1216 watchdog = None
1217
1218 try:
1219 return f(self, maxsize)
1220 finally:
1221 if watchdog:
1222 watchdog.stop()
1223
1224 wrapper.size = size
1225 wrapper.memuse = memuse
1226 return wrapper
1227 return decorator
1228
1229 def bigaddrspacetest(f):
1230 """Decorator for tests that fill the address space."""
1231 def wrapper(self):
1232 if max_memuse < MAX_Py_ssize_t:
1233 if MAX_Py_ssize_t >= 2**63 - 1 and max_memuse >= 2**31:
1234 raise unittest.SkipTest(
1235 "not enough memory: try a 32-bit build instead")
1236 else:
1237 raise unittest.SkipTest(
1238 "not enough memory: %.1fG minimum needed"
1239 % (MAX_Py_ssize_t / (1024 ** 3)))
1240 else:
1241 return f(self)
1242 return wrapper
1243
1244 #=======================================================================
1245 # unittest integration.
1246
1247 def _id(obj):
1248 return obj
1249
1250 def requires_resource(resource):
1251 if resource == 'gui' and not _is_gui_available():
1252 return unittest.skip(_is_gui_available.reason)
1253 if is_resource_enabled(resource):
1254 return _id
1255 else:
1256 return unittest.skip("resource {0!r} is not enabled".format(resource))
1257
1258 def cpython_only(test):
1259 """
1260 Decorator for tests only applicable on CPython.
1261 """
1262 return impl_detail(cpython=True)(test)
1263
1264 def impl_detail(msg=None, **guards):
1265 if check_impl_detail(**guards):
1266 return _id
1267 if msg is None:
1268 guardnames, default = _parse_guards(guards)
1269 if default:
1270 msg = "implementation detail not available on {0}"
1271 else:
1272 msg = "implementation detail specific to {0}"
1273 guardnames = sorted(guardnames.keys())
1274 msg = msg.format(' or '.join(guardnames))
1275 return unittest.skip(msg)
1276
1277 def _parse_guards(guards):
1278 # Returns a tuple ({platform_name: run_me}, default_value)
1279 if not guards:
1280 return ({'cpython': True}, False)
1281 is_true = list(guards.values())[0]
1282 assert list(guards.values()) == [is_true] * len(guards) # all True or all False
1283 return (guards, not is_true)
1284
1285 # Use the following check to guard CPython's implementation-specific tests --
1286 # or to run them only on the implementation(s) guarded by the arguments.
1287 def check_impl_detail(**guards):
1288 """This function returns True or False depending on the host platform.
1289 Examples:
1290 if check_impl_detail(): # only on CPython (default)
1291 if check_impl_detail(jython=True): # only on Jython
1292 if check_impl_detail(cpython=False): # everywhere except on CPython
1293 """
1294 guards, default = _parse_guards(guards)
1295 return guards.get(sys.implementation.name, default)
1296
1297
1298 def no_tracing(func):
1299 """Decorator to temporarily turn off tracing for the duration of a test."""
1300 trace_wrapper = func
1301 if hasattr(sys, 'gettrace'):
1302 @functools.wraps(func)
1303 def trace_wrapper(*args, **kwargs):
1304 original_trace = sys.gettrace()
1305 try:
1306 sys.settrace(None)
1307 return func(*args, **kwargs)
1308 finally:
1309 sys.settrace(original_trace)
1310
1311 coverage_wrapper = trace_wrapper
1312 if 'test.cov' in sys.modules: # -Xpresite=test.cov used
1313 cov = sys.monitoring.COVERAGE_ID
1314 @functools.wraps(func)
1315 def coverage_wrapper(*args, **kwargs):
1316 original_events = sys.monitoring.get_events(cov)
1317 try:
1318 sys.monitoring.set_events(cov, 0)
1319 return trace_wrapper(*args, **kwargs)
1320 finally:
1321 sys.monitoring.set_events(cov, original_events)
1322
1323 return coverage_wrapper
1324
1325
1326 def no_rerun(reason):
1327 """Skip rerunning for a particular test.
1328
1329 WARNING: Use this decorator with care; skipping rerunning makes it
1330 impossible to find reference leaks. Provide a clear reason for skipping the
1331 test using the 'reason' parameter.
1332 """
1333 def deco(func):
1334 assert not isinstance(func, type), func
1335 _has_run = False
1336 def wrapper(self):
1337 nonlocal _has_run
1338 if _has_run:
1339 self.skipTest(reason)
1340 func(self)
1341 _has_run = True
1342 return wrapper
1343 return deco
1344
1345
1346 def refcount_test(test):
1347 """Decorator for tests which involve reference counting.
1348
1349 To start, the decorator does not run the test if is not run by CPython.
1350 After that, any trace function is unset during the test to prevent
1351 unexpected refcounts caused by the trace function.
1352
1353 """
1354 return no_tracing(cpython_only(test))
1355
1356
1357 def requires_limited_api(test):
1358 try:
1359 import _testcapi # noqa: F401
1360 import _testlimitedcapi # noqa: F401
1361 except ImportError:
1362 return unittest.skip('needs _testcapi and _testlimitedcapi modules')(test)
1363 return test
1364
1365
1366 # Windows build doesn't support --disable-test-modules feature, so there's no
1367 # 'TEST_MODULES' var in config
1368 TEST_MODULES_ENABLED = (sysconfig.get_config_var('TEST_MODULES') or 'yes') == 'yes'
1369
1370 def requires_specialization(test):
1371 return unittest.skipUnless(
1372 _opcode.ENABLE_SPECIALIZATION, "requires specialization")(test)
1373
1374
1375 def requires_specialization_ft(test):
1376 return unittest.skipUnless(
1377 _opcode.ENABLE_SPECIALIZATION_FT, "requires specialization")(test)
1378
1379
1380 def reset_code(f: types.FunctionType) -> types.FunctionType:
1381 """Clear all specializations, local instrumentation, and JIT code for the given function."""
1382 f.__code__ = f.__code__.replace()
1383 return f
1384
1385 on_github_actions = "GITHUB_ACTIONS" in os.environ
1386
1387 #=======================================================================
1388 # Check for the presence of docstrings.
1389
1390 # Rather than trying to enumerate all the cases where docstrings may be
1391 # disabled, we just check for that directly
1392
1393 def _check_docstrings():
1394 """Just used to check if docstrings are enabled"""
1395
1396 MISSING_C_DOCSTRINGS = (check_impl_detail() and
1397 sys.platform != 'win32' and
1398 not sysconfig.get_config_var('WITH_DOC_STRINGS'))
1399
1400 HAVE_PY_DOCSTRINGS = _check_docstrings.__doc__ is not None
1401 HAVE_DOCSTRINGS = (HAVE_PY_DOCSTRINGS and not MISSING_C_DOCSTRINGS)
1402
1403 requires_docstrings = unittest.skipUnless(HAVE_DOCSTRINGS,
1404 "test requires docstrings")
1405
1406
1407 #=======================================================================
1408 # Support for saving and restoring the imported modules.
1409
1410 def flush_std_streams():
1411 if sys.stdout is not None:
1412 sys.stdout.flush()
1413 if sys.stderr is not None:
1414 sys.stderr.flush()
1415
1416
1417 def print_warning(msg):
1418 # bpo-45410: Explicitly flush stdout to keep logs in order
1419 flush_std_streams()
1420 stream = print_warning.orig_stderr
1421 for line in msg.splitlines():
1422 print(f"Warning -- {line}", file=stream)
1423 stream.flush()
1424
1425 # bpo-39983: Store the original sys.stderr at Python startup to be able to
1426 # log warnings even if sys.stderr is captured temporarily by a test.
1427 print_warning.orig_stderr = sys.stderr
1428
1429
1430 # Flag used by saved_test_environment of test.libregrtest.save_env,
1431 # to check if a test modified the environment. The flag should be set to False
1432 # before running a new test.
1433 #
1434 # For example, threading_helper.threading_cleanup() sets the flag is the function fails
1435 # to cleanup threads.
1436 environment_altered = False
1437
1438 def reap_children():
1439 """Use this function at the end of test_main() whenever sub-processes
1440 are started. This will help ensure that no extra children (zombies)
1441 stick around to hog resources and create problems when looking
1442 for refleaks.
1443 """
1444 global environment_altered
1445
1446 # Need os.waitpid(-1, os.WNOHANG): Windows is not supported
1447 if not (hasattr(os, 'waitpid') and hasattr(os, 'WNOHANG')):
1448 return
1449 elif not has_subprocess_support:
1450 return
1451
1452 # Reap all our dead child processes so we don't leave zombies around.
1453 # These hog resources and might be causing some of the buildbots to die.
1454 while True:
1455 try:
1456 # Read the exit status of any child process which already completed
1457 pid, status = os.waitpid(-1, os.WNOHANG)
1458 except OSError:
1459 break
1460
1461 if pid == 0:
1462 break
1463
1464 print_warning(f"reap_children() reaped child process {pid}")
1465 environment_altered = True
1466
1467
1468 @contextlib.contextmanager
1469 def swap_attr(obj, attr, new_val):
1470 """Temporary swap out an attribute with a new object.
1471
1472 Usage:
1473 with swap_attr(obj, "attr", 5):
1474 ...
1475
1476 This will set obj.attr to 5 for the duration of the with: block,
1477 restoring the old value at the end of the block. If `attr` doesn't
1478 exist on `obj`, it will be created and then deleted at the end of the
1479 block.
1480
1481 The old value (or None if it doesn't exist) will be assigned to the
1482 target of the "as" clause, if there is one.
1483 """
1484 if hasattr(obj, attr):
1485 real_val = getattr(obj, attr)
1486 setattr(obj, attr, new_val)
1487 try:
1488 yield real_val
1489 finally:
1490 setattr(obj, attr, real_val)
1491 else:
1492 setattr(obj, attr, new_val)
1493 try:
1494 yield
1495 finally:
1496 if hasattr(obj, attr):
1497 delattr(obj, attr)
1498
1499 @contextlib.contextmanager
1500 def swap_item(obj, item, new_val):
1501 """Temporary swap out an item with a new object.
1502
1503 Usage:
1504 with swap_item(obj, "item", 5):
1505 ...
1506
1507 This will set obj["item"] to 5 for the duration of the with: block,
1508 restoring the old value at the end of the block. If `item` doesn't
1509 exist on `obj`, it will be created and then deleted at the end of the
1510 block.
1511
1512 The old value (or None if it doesn't exist) will be assigned to the
1513 target of the "as" clause, if there is one.
1514 """
1515 if item in obj:
1516 real_val = obj[item]
1517 obj[item] = new_val
1518 try:
1519 yield real_val
1520 finally:
1521 obj[item] = real_val
1522 else:
1523 obj[item] = new_val
1524 try:
1525 yield
1526 finally:
1527 if item in obj:
1528 del obj[item]
1529
1530 def args_from_interpreter_flags():
1531 """Return a list of command-line arguments reproducing the current
1532 settings in sys.flags and sys.warnoptions."""
1533 import subprocess
1534 return subprocess._args_from_interpreter_flags()
1535
1536 def optim_args_from_interpreter_flags():
1537 """Return a list of command-line arguments reproducing the current
1538 optimization settings in sys.flags."""
1539 import subprocess
1540 return subprocess._optim_args_from_interpreter_flags()
1541
1542
1543 class Matcher(object):
1544
1545 _partial_matches = ('msg', 'message')
1546
1547 def matches(self, d, **kwargs):
1548 """
1549 Try to match a single dict with the supplied arguments.
1550
1551 Keys whose values are strings and which are in self._partial_matches
1552 will be checked for partial (i.e. substring) matches. You can extend
1553 this scheme to (for example) do regular expression matching, etc.
1554 """
1555 result = True
1556 for k in kwargs:
1557 v = kwargs[k]
1558 dv = d.get(k)
1559 if not self.match_value(k, dv, v):
1560 result = False
1561 break
1562 return result
1563
1564 def match_value(self, k, dv, v):
1565 """
1566 Try to match a single stored value (dv) with a supplied value (v).
1567 """
1568 if type(v) != type(dv):
1569 result = False
1570 elif type(dv) is not str or k not in self._partial_matches:
1571 result = (v == dv)
1572 else:
1573 result = dv.find(v) >= 0
1574 return result
1575
1576
1577 _buggy_ucrt = None
1578 def skip_if_buggy_ucrt_strfptime(test):
1579 """
1580 Skip decorator for tests that use buggy strptime/strftime
1581
1582 If the UCRT bugs are present time.localtime().tm_zone will be
1583 an empty string, otherwise we assume the UCRT bugs are fixed
1584
1585 See bpo-37552 [Windows] strptime/strftime return invalid
1586 results with UCRT version 17763.615
1587 """
1588 import locale
1589 global _buggy_ucrt
1590 if _buggy_ucrt is None:
1591 if(sys.platform == 'win32' and
1592 locale.getencoding() == 'cp65001' and
1593 time.localtime().tm_zone == ''):
1594 _buggy_ucrt = True
1595 else:
1596 _buggy_ucrt = False
1597 return unittest.skip("buggy MSVC UCRT strptime/strftime")(test) if _buggy_ucrt else test
1598
1599 class PythonSymlink:
1600 """Creates a symlink for the current Python executable"""
1601 def __init__(self, link=None):
1602 from .os_helper import TESTFN
1603
1604 self.link = link or os.path.abspath(TESTFN)
1605 self._linked = []
1606 self.real = os.path.realpath(sys.executable)
1607 self._also_link = []
1608
1609 self._env = None
1610
1611 self._platform_specific()
1612
1613 if sys.platform == "win32":
1614 def _platform_specific(self):
1615 import glob
1616 import _winapi
1617
1618 if os.path.lexists(self.real) and not os.path.exists(self.real):
1619 # App symlink appears to not exist, but we want the
1620 # real executable here anyway
1621 self.real = _winapi.GetModuleFileName(0)
1622
1623 dll = _winapi.GetModuleFileName(sys.dllhandle)
1624 src_dir = os.path.dirname(dll)
1625 dest_dir = os.path.dirname(self.link)
1626 self._also_link.append((
1627 dll,
1628 os.path.join(dest_dir, os.path.basename(dll))
1629 ))
1630 for runtime in glob.glob(os.path.join(glob.escape(src_dir), "vcruntime*.dll")):
1631 self._also_link.append((
1632 runtime,
1633 os.path.join(dest_dir, os.path.basename(runtime))
1634 ))
1635
1636 self._env = {k.upper(): os.getenv(k) for k in os.environ}
1637 self._env["PYTHONHOME"] = os.path.dirname(self.real)
1638 if sysconfig.is_python_build():
1639 self._env["PYTHONPATH"] = STDLIB_DIR
1640 else:
1641 def _platform_specific(self):
1642 pass
1643
1644 def __enter__(self):
1645 os.symlink(self.real, self.link)
1646 self._linked.append(self.link)
1647 for real, link in self._also_link:
1648 os.symlink(real, link)
1649 self._linked.append(link)
1650 return self
1651
1652 def __exit__(self, exc_type, exc_value, exc_tb):
1653 for link in self._linked:
1654 try:
1655 os.remove(link)
1656 except IOError as ex:
1657 if verbose:
1658 print("failed to clean up {}: {}".format(link, ex))
1659
1660 def _call(self, python, args, env, returncode):
1661 import subprocess
1662 cmd = [python, *args]
1663 p = subprocess.Popen(cmd, stdout=subprocess.PIPE,
1664 stderr=subprocess.PIPE, env=env)
1665 r = p.communicate()
1666 if p.returncode != returncode:
1667 if verbose:
1668 print(repr(r[0]))
1669 print(repr(r[1]), file=sys.stderr)
1670 raise RuntimeError(
1671 'unexpected return code: {0} (0x{0:08X})'.format(p.returncode))
1672 return r
1673
1674 def call_real(self, *args, returncode=0):
1675 return self._call(self.real, args, None, returncode)
1676
1677 def call_link(self, *args, returncode=0):
1678 return self._call(self.link, args, self._env, returncode)
1679
1680
1681 def skip_if_pgo_task(test):
1682 """Skip decorator for tests not run in (non-extended) PGO task"""
1683 ok = not PGO or PGO_EXTENDED
1684 msg = "Not run for (non-extended) PGO task"
1685 return test if ok else unittest.skip(msg)(test)
1686
1687
1688 def skip_if_unlimited_stack_size(test):
1689 """Skip decorator for tests not run when an unlimited stack size is configured.
1690
1691 Tests using support.infinite_recursion([...]) may otherwise run into
1692 an infinite loop, running until the memory on the system is filled and
1693 crashing due to OOM.
1694
1695 See https://github.com/python/cpython/issues/143460.
1696 """
1697 if is_emscripten or is_wasi or os.name == "nt":
1698 return test
1699
1700 import resource
1701 curlim, maxlim = resource.getrlimit(resource.RLIMIT_STACK)
1702 unlimited_stack_size_cond = curlim == maxlim and curlim in (-1, 0xFFFF_FFFF_FFFF_FFFF)
1703 reason = "Not run due to unlimited stack size"
1704 return unittest.skipIf(unlimited_stack_size_cond, reason)(test)
1705
1706
1707 def detect_api_mismatch(ref_api, other_api, *, ignore=()):
1708 """Returns the set of items in ref_api not in other_api, except for a
1709 defined list of items to be ignored in this check.
1710
1711 By default this skips private attributes beginning with '_' but
1712 includes all magic methods, i.e. those starting and ending in '__'.
1713 """
1714 missing_items = set(dir(ref_api)) - set(dir(other_api))
1715 if ignore:
1716 missing_items -= set(ignore)
1717 missing_items = set(m for m in missing_items
1718 if not m.startswith('_') or m.endswith('__'))
1719 return missing_items
1720
1721
1722 def check__all__(test_case, module, name_of_module=None, extra=(),
1723 not_exported=()):
1724 """Assert that the __all__ variable of 'module' contains all public names.
1725
1726 The module's public names (its API) are detected automatically based on
1727 whether they match the public name convention and were defined in
1728 'module'.
1729
1730 The 'name_of_module' argument can specify (as a string or tuple thereof)
1731 what module(s) an API could be defined in order to be detected as a
1732 public API. One case for this is when 'module' imports part of its public
1733 API from other modules, possibly a C backend (like 'csv' and its '_csv').
1734
1735 The 'extra' argument can be a set of names that wouldn't otherwise be
1736 automatically detected as "public", like objects without a proper
1737 '__module__' attribute. If provided, it will be added to the
1738 automatically detected ones.
1739
1740 The 'not_exported' argument can be a set of names that must not be treated
1741 as part of the public API even though their names indicate otherwise.
1742
1743 Usage:
1744 import bar
1745 import foo
1746 import unittest
1747 from test import support
1748
1749 class MiscTestCase(unittest.TestCase):
1750 def test__all__(self):
1751 support.check__all__(self, foo)
1752
1753 class OtherTestCase(unittest.TestCase):
1754 def test__all__(self):
1755 extra = {'BAR_CONST', 'FOO_CONST'}
1756 not_exported = {'baz'} # Undocumented name.
1757 # bar imports part of its API from _bar.
1758 support.check__all__(self, bar, ('bar', '_bar'),
1759 extra=extra, not_exported=not_exported)
1760
1761 """
1762
1763 if name_of_module is None:
1764 name_of_module = (module.__name__, )
1765 elif isinstance(name_of_module, str):
1766 name_of_module = (name_of_module, )
1767
1768 expected = set(extra)
1769
1770 for name in dir(module):
1771 if name.startswith('_') or name in not_exported:
1772 continue
1773 obj = getattr(module, name)
1774 if (getattr(obj, '__module__', None) in name_of_module or
1775 (not hasattr(obj, '__module__') and
1776 not isinstance(obj, types.ModuleType))):
1777 expected.add(name)
1778 test_case.assertCountEqual(module.__all__, expected)
1779
1780
1781 def suppress_msvcrt_asserts(verbose=False):
1782 try:
1783 import msvcrt
1784 except ImportError:
1785 return
1786
1787 msvcrt.SetErrorMode(msvcrt.SEM_FAILCRITICALERRORS
1788 | msvcrt.SEM_NOALIGNMENTFAULTEXCEPT
1789 | msvcrt.SEM_NOGPFAULTERRORBOX
1790 | msvcrt.SEM_NOOPENFILEERRORBOX)
1791
1792 # CrtSetReportMode() is only available in debug build
1793 if hasattr(msvcrt, 'CrtSetReportMode'):
1794 for m in [msvcrt.CRT_WARN, msvcrt.CRT_ERROR, msvcrt.CRT_ASSERT]:
1795 if verbose:
1796 msvcrt.CrtSetReportMode(m, msvcrt.CRTDBG_MODE_FILE)
1797 msvcrt.CrtSetReportFile(m, msvcrt.CRTDBG_FILE_STDERR)
1798 else:
1799 msvcrt.CrtSetReportMode(m, 0)
1800
1801
1802 class SuppressCrashReport:
1803 """Try to prevent a crash report from popping up.
1804
1805 On Windows, don't display the Windows Error Reporting dialog. On UNIX,
1806 disable the creation of coredump file.
1807 """
1808 old_value = None
1809 old_modes = None
1810
1811 def __enter__(self):
1812 """On Windows, disable Windows Error Reporting dialogs using
1813 SetErrorMode() and CrtSetReportMode().
1814
1815 On UNIX, try to save the previous core file size limit, then set
1816 soft limit to 0.
1817 """
1818 if sys.platform.startswith('win'):
1819 # see http://msdn.microsoft.com/en-us/library/windows/desktop/ms680621.aspx
1820 try:
1821 import msvcrt
1822 except ImportError:
1823 return
1824
1825 self.old_value = msvcrt.GetErrorMode()
1826
1827 msvcrt.SetErrorMode(self.old_value | msvcrt.SEM_NOGPFAULTERRORBOX)
1828
1829 # bpo-23314: Suppress assert dialogs in debug builds.
1830 # CrtSetReportMode() is only available in debug build.
1831 if hasattr(msvcrt, 'CrtSetReportMode'):
1832 self.old_modes = {}
1833 for report_type in [msvcrt.CRT_WARN,
1834 msvcrt.CRT_ERROR,
1835 msvcrt.CRT_ASSERT]:
1836 old_mode = msvcrt.CrtSetReportMode(report_type,
1837 msvcrt.CRTDBG_MODE_FILE)
1838 old_file = msvcrt.CrtSetReportFile(report_type,
1839 msvcrt.CRTDBG_FILE_STDERR)
1840 self.old_modes[report_type] = old_mode, old_file
1841
1842 else:
1843 try:
1844 import resource
1845 self.resource = resource
1846 except ImportError:
1847 self.resource = None
1848 if self.resource is not None:
1849 try:
1850 self.old_value = self.resource.getrlimit(self.resource.RLIMIT_CORE)
1851 self.resource.setrlimit(self.resource.RLIMIT_CORE,
1852 (0, self.old_value[1]))
1853 except (ValueError, OSError):
1854 pass
1855
1856 if sys.platform == 'darwin':
1857 import subprocess
1858 # Check if the 'Crash Reporter' on OSX was configured
1859 # in 'Developer' mode and warn that it will get triggered
1860 # when it is.
1861 #
1862 # This assumes that this context manager is used in tests
1863 # that might trigger the next manager.
1864 cmd = ['/usr/bin/defaults', 'read',
1865 'com.apple.CrashReporter', 'DialogType']
1866 proc = subprocess.Popen(cmd,
1867 stdout=subprocess.PIPE,
1868 stderr=subprocess.PIPE)
1869 with proc:
1870 stdout = proc.communicate()[0]
1871 if stdout.strip() == b'developer':
1872 print("this test triggers the Crash Reporter, "
1873 "that is intentional", end='', flush=True)
1874
1875 return self
1876
1877 def __exit__(self, *ignore_exc):
1878 """Restore Windows ErrorMode or core file behavior to initial value."""
1879 if self.old_value is None:
1880 return
1881
1882 if sys.platform.startswith('win'):
1883 import msvcrt
1884 msvcrt.SetErrorMode(self.old_value)
1885
1886 if self.old_modes:
1887 for report_type, (old_mode, old_file) in self.old_modes.items():
1888 msvcrt.CrtSetReportMode(report_type, old_mode)
1889 msvcrt.CrtSetReportFile(report_type, old_file)
1890 else:
1891 if self.resource is not None:
1892 try:
1893 self.resource.setrlimit(self.resource.RLIMIT_CORE, self.old_value)
1894 except (ValueError, OSError):
1895 pass
1896
1897
1898 def patch(test_instance, object_to_patch, attr_name, new_value):
1899 """Override 'object_to_patch'.'attr_name' with 'new_value'.
1900
1901 Also, add a cleanup procedure to 'test_instance' to restore
1902 'object_to_patch' value for 'attr_name'.
1903 The 'attr_name' should be a valid attribute for 'object_to_patch'.
1904
1905 """
1906 # check that 'attr_name' is a real attribute for 'object_to_patch'
1907 # will raise AttributeError if it does not exist
1908 getattr(object_to_patch, attr_name)
1909
1910 # keep a copy of the old value
1911 attr_is_local = False
1912 try:
1913 old_value = object_to_patch.__dict__[attr_name]
1914 except (AttributeError, KeyError):
1915 old_value = getattr(object_to_patch, attr_name, None)
1916 else:
1917 attr_is_local = True
1918
1919 # restore the value when the test is done
1920 def cleanup():
1921 if attr_is_local:
1922 setattr(object_to_patch, attr_name, old_value)
1923 else:
1924 delattr(object_to_patch, attr_name)
1925
1926 test_instance.addCleanup(cleanup)
1927
1928 # actually override the attribute
1929 setattr(object_to_patch, attr_name, new_value)
1930
1931
1932 @contextlib.contextmanager
1933 def patch_list(orig):
1934 """Like unittest.mock.patch.dict, but for lists."""
1935 try:
1936 saved = orig[:]
1937 yield
1938 finally:
1939 orig[:] = saved
1940
1941
1942 def run_in_subinterp(code):
1943 """
1944 Run code in a subinterpreter. Raise unittest.SkipTest if the tracemalloc
1945 module is enabled.
1946 """
1947 _check_tracemalloc()
1948 try:
1949 import _testcapi
1950 except ImportError:
1951 raise unittest.SkipTest("requires _testcapi")
1952 return _testcapi.run_in_subinterp(code)
1953
1954
1955 def run_in_subinterp_with_config(code, *, own_gil=None, **config):
1956 """
1957 Run code in a subinterpreter. Raise unittest.SkipTest if the tracemalloc
1958 module is enabled.
1959 """
1960 _check_tracemalloc()
1961 try:
1962 import _testinternalcapi
1963 except ImportError:
1964 raise unittest.SkipTest("requires _testinternalcapi")
1965 if own_gil is not None:
1966 assert 'gil' not in config, (own_gil, config)
1967 config['gil'] = 'own' if own_gil else 'shared'
1968 else:
1969 gil = config['gil']
1970 if gil == 0:
1971 config['gil'] = 'default'
1972 elif gil == 1:
1973 config['gil'] = 'shared'
1974 elif gil == 2:
1975 config['gil'] = 'own'
1976 elif not isinstance(gil, str):
1977 raise NotImplementedError(gil)
1978 config = types.SimpleNamespace(**config)
1979 return _testinternalcapi.run_in_subinterp_with_config(code, config)
1980
1981
1982 def _check_tracemalloc():
1983 # Issue #10915, #15751: PyGILState_*() functions don't work with
1984 # sub-interpreters, the tracemalloc module uses these functions internally
1985 try:
1986 import tracemalloc
1987 except ImportError:
1988 pass
1989 else:
1990 if tracemalloc.is_tracing():
1991 raise unittest.SkipTest("run_in_subinterp() cannot be used "
1992 "if tracemalloc module is tracing "
1993 "memory allocations")
1994
1995
1996 def check_free_after_iterating(test, iter, cls, args=()):
1997 done = False
1998 def wrapper():
1999 class A(cls):
2000 def __del__(self):
2001 nonlocal done
2002 done = True
2003 try:
2004 next(it)
2005 except StopIteration:
2006 pass
2007
2008 it = iter(A(*args))
2009 # Issue 26494: Shouldn't crash
2010 test.assertRaises(StopIteration, next, it)
2011
2012 wrapper()
2013 # The sequence should be deallocated just after the end of iterating
2014 gc_collect()
2015 test.assertTrue(done)
2016
2017
2018 def missing_compiler_executable(cmd_names=[]):
2019 """Check if the compiler components used to build the interpreter exist.
2020
2021 Check for the existence of the compiler executables whose names are listed
2022 in 'cmd_names' or all the compiler executables when 'cmd_names' is empty
2023 and return the first missing executable or None when none is found
2024 missing.
2025
2026 """
2027 from setuptools._distutils import ccompiler, sysconfig
2028 from setuptools import errors
2029 import shutil
2030
2031 compiler = ccompiler.new_compiler()
2032 sysconfig.customize_compiler(compiler)
2033 if compiler.compiler_type == "msvc":
2034 # MSVC has no executables, so check whether initialization succeeds
2035 try:
2036 compiler.initialize()
2037 except errors.PlatformError:
2038 return "msvc"
2039 for name in compiler.executables:
2040 if cmd_names and name not in cmd_names:
2041 continue
2042 cmd = getattr(compiler, name)
2043 if cmd_names:
2044 assert cmd is not None, \
2045 "the '%s' executable is not configured" % name
2046 elif not cmd:
2047 continue
2048 if shutil.which(cmd[0]) is None:
2049 return cmd[0]
2050
2051
2052 _old_android_emulator = None
2053 def setswitchinterval(interval):
2054 # Setting a very low gil interval on the Android emulator causes python
2055 # to hang (issue #26939).
2056 minimum_interval = 1e-4 # 100 us
2057 if is_android and interval < minimum_interval:
2058 global _old_android_emulator
2059 if _old_android_emulator is None:
2060 import platform
2061 av = platform.android_ver()
2062 _old_android_emulator = av.is_emulator and av.api_level < 24
2063 if _old_android_emulator:
2064 interval = minimum_interval
2065 return sys.setswitchinterval(interval)
2066
2067
2068 def get_pagesize():
2069 """Get size of a page in bytes."""
2070 try:
2071 page_size = os.sysconf('SC_PAGESIZE')
2072 except (ValueError, AttributeError):
2073 try:
2074 page_size = os.sysconf('SC_PAGE_SIZE')
2075 except (ValueError, AttributeError):
2076 page_size = 4096
2077 return page_size
2078
2079
2080 @contextlib.contextmanager
2081 def disable_faulthandler():
2082 import faulthandler
2083
2084 # use sys.__stderr__ instead of sys.stderr, since regrtest replaces
2085 # sys.stderr with a StringIO which has no file descriptor when a test
2086 # is run with -W/--verbose3.
2087 fd = sys.__stderr__.fileno()
2088
2089 is_enabled = faulthandler.is_enabled()
2090 try:
2091 faulthandler.disable()
2092 yield
2093 finally:
2094 if is_enabled:
2095 faulthandler.enable(file=fd, all_threads=True)
2096
2097
2098 class SaveSignals:
2099 """
2100 Save and restore signal handlers.
2101
2102 This class is only able to save/restore signal handlers registered
2103 by the Python signal module: see bpo-13285 for "external" signal
2104 handlers.
2105 """
2106
2107 def __init__(self):
2108 import signal
2109 self.signal = signal
2110 self.signals = signal.valid_signals()
2111 # SIGKILL and SIGSTOP signals cannot be ignored nor caught
2112 for signame in ('SIGKILL', 'SIGSTOP'):
2113 try:
2114 signum = getattr(signal, signame)
2115 except AttributeError:
2116 continue
2117 self.signals.remove(signum)
2118 self.handlers = {}
2119
2120 def save(self):
2121 for signum in self.signals:
2122 handler = self.signal.getsignal(signum)
2123 if handler is None:
2124 # getsignal() returns None if a signal handler was not
2125 # registered by the Python signal module,
2126 # and the handler is not SIG_DFL nor SIG_IGN.
2127 #
2128 # Ignore the signal: we cannot restore the handler.
2129 continue
2130 self.handlers[signum] = handler
2131
2132 def restore(self):
2133 for signum, handler in self.handlers.items():
2134 self.signal.signal(signum, handler)
2135
2136
2137 def with_pymalloc():
2138 try:
2139 import _testcapi
2140 except ImportError:
2141 raise unittest.SkipTest("requires _testcapi")
2142 return _testcapi.WITH_PYMALLOC and not Py_GIL_DISABLED
2143
2144
2145 def with_mimalloc():
2146 try:
2147 import _testcapi
2148 except ImportError:
2149 raise unittest.SkipTest("requires _testcapi")
2150 return _testcapi.WITH_MIMALLOC
2151
2152
2153 class _ALWAYS_EQ:
2154 """
2155 Object that is equal to anything.
2156 """
2157 def __eq__(self, other):
2158 return True
2159 def __ne__(self, other):
2160 return False
2161
2162 ALWAYS_EQ = _ALWAYS_EQ()
2163
2164 class _NEVER_EQ:
2165 """
2166 Object that is not equal to anything.
2167 """
2168 def __eq__(self, other):
2169 return False
2170 def __ne__(self, other):
2171 return True
2172 def __hash__(self):
2173 return 1
2174
2175 NEVER_EQ = _NEVER_EQ()
2176
2177 @functools.total_ordering
2178 class _LARGEST:
2179 """
2180 Object that is greater than anything (except itself).
2181 """
2182 def __eq__(self, other):
2183 return isinstance(other, _LARGEST)
2184 def __lt__(self, other):
2185 return False
2186
2187 LARGEST = _LARGEST()
2188
2189 @functools.total_ordering
2190 class _SMALLEST:
2191 """
2192 Object that is less than anything (except itself).
2193 """
2194 def __eq__(self, other):
2195 return isinstance(other, _SMALLEST)
2196 def __gt__(self, other):
2197 return False
2198
2199 SMALLEST = _SMALLEST()
2200
2201 def maybe_get_event_loop_policy():
2202 """Return the global event loop policy if one is set, else return None."""
2203 import asyncio.events
2204 return asyncio.events._event_loop_policy
2205
2206 # Helpers for testing hashing.
2207 NHASHBITS = sys.hash_info.width # number of bits in hash() result
2208 assert NHASHBITS in (32, 64)
2209
2210 # Return mean and sdev of number of collisions when tossing nballs balls
2211 # uniformly at random into nbins bins. By definition, the number of
2212 # collisions is the number of balls minus the number of occupied bins at
2213 # the end.
2214 def collision_stats(nbins, nballs):
2215 n, k = nbins, nballs
2216 # prob a bin empty after k trials = (1 - 1/n)**k
2217 # mean # empty is then n * (1 - 1/n)**k
2218 # so mean # occupied is n - n * (1 - 1/n)**k
2219 # so collisions = k - (n - n*(1 - 1/n)**k)
2220 #
2221 # For the variance:
2222 # n*(n-1)*(1-2/n)**k + meanempty - meanempty**2 =
2223 # n*(n-1)*(1-2/n)**k + meanempty * (1 - meanempty)
2224 #
2225 # Massive cancellation occurs, and, e.g., for a 64-bit hash code
2226 # 1-1/2**64 rounds uselessly to 1.0. Rather than make heroic (and
2227 # error-prone) efforts to rework the naive formulas to avoid those,
2228 # we use the `decimal` module to get plenty of extra precision.
2229 #
2230 # Note: the exact values are straightforward to compute with
2231 # rationals, but in context that's unbearably slow, requiring
2232 # multi-million bit arithmetic.
2233 import decimal
2234 with decimal.localcontext() as ctx:
2235 bits = n.bit_length() * 2 # bits in n**2
2236 # At least that many bits will likely cancel out.
2237 # Use that many decimal digits instead.
2238 ctx.prec = max(bits, 30)
2239 dn = decimal.Decimal(n)
2240 p1empty = ((dn - 1) / dn) ** k
2241 meanempty = n * p1empty
2242 occupied = n - meanempty
2243 collisions = k - occupied
2244 var = dn*(dn-1)*((dn-2)/dn)**k + meanempty * (1 - meanempty)
2245 return float(collisions), float(var.sqrt())
2246
2247
2248 class catch_unraisable_exception:
2249 """
2250 Context manager catching unraisable exception using sys.unraisablehook.
2251
2252 Storing the exception value (cm.unraisable.exc_value) creates a reference
2253 cycle. The reference cycle is broken explicitly when the context manager
2254 exits.
2255
2256 Storing the object (cm.unraisable.object) can resurrect it if it is set to
2257 an object which is being finalized. Exiting the context manager clears the
2258 stored object.
2259
2260 Usage:
2261
2262 with support.catch_unraisable_exception() as cm:
2263 # code creating an "unraisable exception"
2264 ...
2265
2266 # check the unraisable exception: use cm.unraisable
2267 ...
2268
2269 # cm.unraisable attribute no longer exists at this point
2270 # (to break a reference cycle)
2271 """
2272
2273 def __init__(self):
2274 self.unraisable = None
2275 self._old_hook = None
2276
2277 def _hook(self, unraisable):
2278 # Storing unraisable.object can resurrect an object which is being
2279 # finalized. Storing unraisable.exc_value creates a reference cycle.
2280 self.unraisable = unraisable
2281
2282 def __enter__(self):
2283 self._old_hook = sys.unraisablehook
2284 sys.unraisablehook = self._hook
2285 return self
2286
2287 def __exit__(self, *exc_info):
2288 sys.unraisablehook = self._old_hook
2289 del self.unraisable
2290
2291
2292 def wait_process(pid, *, exitcode, timeout=None):
2293 """
2294 Wait until process pid completes and check that the process exit code is
2295 exitcode.
2296
2297 Raise an AssertionError if the process exit code is not equal to exitcode.
2298
2299 If the process runs longer than timeout seconds (LONG_TIMEOUT by default),
2300 kill the process (if signal.SIGKILL is available) and raise an
2301 AssertionError. The timeout feature is not available on Windows.
2302 """
2303 if os.name != "nt":
2304 import signal
2305
2306 if timeout is None:
2307 timeout = LONG_TIMEOUT
2308
2309 start_time = time.monotonic()
2310 for _ in sleeping_retry(timeout, error=False):
2311 pid2, status = os.waitpid(pid, os.WNOHANG)
2312 if pid2 != 0:
2313 break
2314 # rety: the process is still running
2315 else:
2316 try:
2317 os.kill(pid, signal.SIGKILL)
2318 os.waitpid(pid, 0)
2319 except OSError:
2320 # Ignore errors like ChildProcessError or PermissionError
2321 pass
2322
2323 dt = time.monotonic() - start_time
2324 raise AssertionError(f"process {pid} is still running "
2325 f"after {dt:.1f} seconds")
2326 else:
2327 # Windows implementation: don't support timeout :-(
2328 pid2, status = os.waitpid(pid, 0)
2329
2330 exitcode2 = os.waitstatus_to_exitcode(status)
2331 if exitcode2 != exitcode:
2332 raise AssertionError(f"process {pid} exited with code {exitcode2}, "
2333 f"but exit code {exitcode} is expected")
2334
2335 # sanity check: it should not fail in practice
2336 if pid2 != pid:
2337 raise AssertionError(f"pid {pid2} != pid {pid}")
2338
2339 def skip_if_broken_multiprocessing_synchronize():
2340 """
2341 Skip tests if the multiprocessing.synchronize module is missing, if there
2342 is no available semaphore implementation, or if creating a lock raises an
2343 OSError (on Linux only).
2344 """
2345 from .import_helper import import_module
2346
2347 # Skip tests if the _multiprocessing extension is missing.
2348 import_module('_multiprocessing')
2349
2350 # Skip tests if there is no available semaphore implementation:
2351 # multiprocessing.synchronize requires _multiprocessing.SemLock.
2352 synchronize = import_module('multiprocessing.synchronize')
2353
2354 if sys.platform == "linux":
2355 try:
2356 # bpo-38377: On Linux, creating a semaphore fails with OSError
2357 # if the current user does not have the permission to create
2358 # a file in /dev/shm/ directory.
2359 import multiprocessing
2360 synchronize.Lock(ctx=multiprocessing.get_context('fork'))
2361 # The explicit fork mp context is required in order for
2362 # TestResourceTracker.test_resource_tracker_reused to work.
2363 # synchronize creates a new multiprocessing.resource_tracker
2364 # process at module import time via the above call in that
2365 # scenario. Awkward. This enables gh-84559. No code involved
2366 # should have threads at that point so fork() should be safe.
2367
2368 except OSError as exc:
2369 raise unittest.SkipTest(f"broken multiprocessing SemLock: {exc!r}")
2370
2371
2372 def check_disallow_instantiation(testcase, tp, *args, **kwds):
2373 """
2374 Check that given type cannot be instantiated using *args and **kwds.
2375
2376 See bpo-43916: Add Py_TPFLAGS_DISALLOW_INSTANTIATION type flag.
2377 """
2378 mod = tp.__module__
2379 name = tp.__name__
2380 if mod != 'builtins':
2381 qualname = f"{mod}.{name}"
2382 else:
2383 qualname = f"{name}"
2384 msg = f"cannot create '{re.escape(qualname)}' instances"
2385 testcase.assertRaisesRegex(TypeError, msg, tp, *args, **kwds)
2386 testcase.assertRaisesRegex(TypeError, msg, tp.__new__, tp, *args, **kwds)
2387
2388 def get_recursion_depth():
2389 """Get the recursion depth of the caller function.
2390
2391 In the __main__ module, at the module level, it should be 1.
2392 """
2393 try:
2394 import _testinternalcapi
2395 depth = _testinternalcapi.get_recursion_depth()
2396 except (ImportError, RecursionError) as exc:
2397 # sys._getframe() + frame.f_back implementation.
2398 try:
2399 depth = 0
2400 frame = sys._getframe()
2401 while frame is not None:
2402 depth += 1
2403 frame = frame.f_back
2404 finally:
2405 # Break any reference cycles.
2406 frame = None
2407
2408 # Ignore get_recursion_depth() frame.
2409 return max(depth - 1, 1)
2410
2411 def get_recursion_available():
2412 """Get the number of available frames before RecursionError.
2413
2414 It depends on the current recursion depth of the caller function and
2415 sys.getrecursionlimit().
2416 """
2417 limit = sys.getrecursionlimit()
2418 depth = get_recursion_depth()
2419 return limit - depth
2420
2421 @contextlib.contextmanager
2422 def set_recursion_limit(limit):
2423 """Temporarily change the recursion limit."""
2424 original_limit = sys.getrecursionlimit()
2425 try:
2426 sys.setrecursionlimit(limit)
2427 yield
2428 finally:
2429 sys.setrecursionlimit(original_limit)
2430
2431 def infinite_recursion(max_depth=None):
2432 if max_depth is None:
2433 # Pick a number large enough to cause problems
2434 # but not take too long for code that can handle
2435 # very deep recursion.
2436 max_depth = 20_000
2437 elif max_depth < 3:
2438 raise ValueError(f"max_depth must be at least 3, got {max_depth}")
2439 depth = get_recursion_depth()
2440 depth = max(depth - 1, 1) # Ignore infinite_recursion() frame.
2441 limit = depth + max_depth
2442 return set_recursion_limit(limit)
2443
2444 def ignore_deprecations_from(module: str, *, like: str) -> object:
2445 token = object()
2446 warnings.filterwarnings(
2447 "ignore",
2448 category=DeprecationWarning,
2449 module=module,
2450 message=like + fr"(?#support{id(token)})",
2451 )
2452 return token
2453
2454 def clear_ignored_deprecations(*tokens: object) -> None:
2455 if not tokens:
2456 raise ValueError("Provide token or tokens returned by ignore_deprecations_from")
2457
2458 new_filters = []
2459 old_filters = warnings._get_filters()
2460 endswith = tuple(rf"(?#support{id(token)})" for token in tokens)
2461 for action, message, category, module, lineno in old_filters:
2462 if action == "ignore" and category is DeprecationWarning:
2463 if isinstance(message, re.Pattern):
2464 msg = message.pattern
2465 else:
2466 msg = message or ""
2467 if msg.endswith(endswith):
2468 continue
2469 new_filters.append((action, message, category, module, lineno))
2470 if old_filters != new_filters:
2471 old_filters[:] = new_filters
2472 warnings._filters_mutated()
2473
2474
2475 # Skip a test if venv with pip is known to not work.
2476 def requires_venv_with_pip():
2477 # ensurepip requires zlib to open ZIP archives (.whl binary wheel packages)
2478 try:
2479 import zlib # noqa: F401
2480 except ImportError:
2481 return unittest.skipIf(True, "venv: ensurepip requires zlib")
2482
2483 # bpo-26610: pip/pep425tags.py requires ctypes.
2484 # gh-92820: setuptools/windows_support.py uses ctypes (setuptools 58.1).
2485 try:
2486 import ctypes
2487 except ImportError:
2488 ctypes = None
2489 return unittest.skipUnless(ctypes, 'venv: pip requires ctypes')
2490
2491
2492 @functools.cache
2493 def _findwheel(pkgname):
2494 """Try to find a wheel with the package specified as pkgname.
2495
2496 If set, the wheels are searched for in WHEEL_PKG_DIR (see ensurepip).
2497 Otherwise, they are searched for in the test directory.
2498 """
2499 wheel_dir = sysconfig.get_config_var('WHEEL_PKG_DIR') or os.path.join(
2500 TEST_HOME_DIR, 'wheeldata',
2501 )
2502 filenames = os.listdir(wheel_dir)
2503 filenames = sorted(filenames, reverse=True) # approximate "newest" first
2504 for filename in filenames:
2505 # filename is like 'setuptools-{version}-py3-none-any.whl'
2506 if not filename.endswith(".whl"):
2507 continue
2508 prefix = pkgname + '-'
2509 if filename.startswith(prefix):
2510 return os.path.join(wheel_dir, filename)
2511 raise FileNotFoundError(f"No wheel for {pkgname} found in {wheel_dir}")
2512
2513
2514 # Context manager that creates a virtual environment, install setuptools in it,
2515 # and returns the paths to the venv directory and the python executable
2516 @contextlib.contextmanager
2517 def setup_venv_with_pip_setuptools(venv_dir):
2518 import subprocess
2519 from .os_helper import temp_cwd
2520
2521 def run_command(cmd):
2522 if verbose:
2523 import shlex
2524 print()
2525 print('Run:', ' '.join(map(shlex.quote, cmd)))
2526 subprocess.run(cmd, check=True)
2527 else:
2528 subprocess.run(cmd,
2529 stdout=subprocess.PIPE,
2530 stderr=subprocess.STDOUT,
2531 check=True)
2532
2533 with temp_cwd() as temp_dir:
2534 # Create virtual environment to get setuptools
2535 cmd = [sys.executable, '-X', 'dev', '-m', 'venv', venv_dir]
2536 run_command(cmd)
2537
2538 venv = os.path.join(temp_dir, venv_dir)
2539
2540 # Get the Python executable of the venv
2541 python_exe = os.path.basename(sys.executable)
2542 if sys.platform == 'win32':
2543 python = os.path.join(venv, 'Scripts', python_exe)
2544 else:
2545 python = os.path.join(venv, 'bin', python_exe)
2546
2547 cmd = (python, '-X', 'dev',
2548 '-m', 'pip', 'install',
2549 _findwheel('setuptools'),
2550 )
2551 run_command(cmd)
2552
2553 yield python
2554
2555
2556 # True if Python is built with the Py_DEBUG macro defined: if
2557 # Python is built in debug mode (./configure --with-pydebug).
2558 Py_DEBUG = hasattr(sys, 'gettotalrefcount')
2559
2560
2561 def late_deletion(obj):
2562 """
2563 Keep a Python alive as long as possible.
2564
2565 Create a reference cycle and store the cycle in an object deleted late in
2566 Python finalization. Try to keep the object alive until the very last
2567 garbage collection.
2568
2569 The function keeps a strong reference by design. It should be called in a
2570 subprocess to not mark a test as "leaking a reference".
2571 """
2572
2573 # Late CPython finalization:
2574 # - finalize_interp_clear()
2575 # - _PyInterpreterState_Clear(): Clear PyInterpreterState members
2576 # (ex: codec_search_path, before_forkers)
2577 # - clear os.register_at_fork() callbacks
2578 # - clear codecs.register() callbacks
2579
2580 ref_cycle = [obj]
2581 ref_cycle.append(ref_cycle)
2582
2583 # Store a reference in PyInterpreterState.codec_search_path
2584 import codecs
2585 def search_func(encoding):
2586 return None
2587 search_func.reference = ref_cycle
2588 codecs.register(search_func)
2589
2590 if hasattr(os, 'register_at_fork'):
2591 # Store a reference in PyInterpreterState.before_forkers
2592 def atfork_func():
2593 pass
2594 atfork_func.reference = ref_cycle
2595 os.register_at_fork(before=atfork_func)
2596
2597
2598 def busy_retry(timeout, err_msg=None, /, *, error=True):
2599 """
2600 Run the loop body until "break" stops the loop.
2601
2602 After *timeout* seconds, raise an AssertionError if *error* is true,
2603 or just stop if *error is false.
2604
2605 Example:
2606
2607 for _ in support.busy_retry(support.SHORT_TIMEOUT):
2608 if check():
2609 break
2610
2611 Example of error=False usage:
2612
2613 for _ in support.busy_retry(support.SHORT_TIMEOUT, error=False):
2614 if check():
2615 break
2616 else:
2617 raise RuntimeError('my custom error')
2618
2619 """
2620 if timeout <= 0:
2621 raise ValueError("timeout must be greater than zero")
2622
2623 start_time = time.monotonic()
2624 deadline = start_time + timeout
2625
2626 while True:
2627 yield
2628
2629 if time.monotonic() >= deadline:
2630 break
2631
2632 if error:
2633 dt = time.monotonic() - start_time
2634 msg = f"timeout ({dt:.1f} seconds)"
2635 if err_msg:
2636 msg = f"{msg}: {err_msg}"
2637 raise AssertionError(msg)
2638
2639
2640 def sleeping_retry(timeout, err_msg=None, /,
2641 *, init_delay=0.010, max_delay=1.0, error=True):
2642 """
2643 Wait strategy that applies exponential backoff.
2644
2645 Run the loop body until "break" stops the loop. Sleep at each loop
2646 iteration, but not at the first iteration. The sleep delay is doubled at
2647 each iteration (up to *max_delay* seconds).
2648
2649 See busy_retry() documentation for the parameters usage.
2650
2651 Example raising an exception after SHORT_TIMEOUT seconds:
2652
2653 for _ in support.sleeping_retry(support.SHORT_TIMEOUT):
2654 if check():
2655 break
2656
2657 Example of error=False usage:
2658
2659 for _ in support.sleeping_retry(support.SHORT_TIMEOUT, error=False):
2660 if check():
2661 break
2662 else:
2663 raise RuntimeError('my custom error')
2664 """
2665
2666 delay = init_delay
2667 for _ in busy_retry(timeout, err_msg, error=error):
2668 yield
2669
2670 time.sleep(delay)
2671 delay = min(delay * 2, max_delay)
2672
2673
2674 class Stopwatch:
2675 """Context manager to roughly time a CPU-bound operation.
2676
2677 Disables GC. Uses perf_counter, which is a clock with the highest
2678 available resolution. It is chosen even though it does include
2679 time elapsed during sleep and is system-wide, because the
2680 resolution of process_time is too coarse on Windows and
2681 process_time does not exist everywhere (for example, WASM).
2682
2683 Note:
2684 - This *includes* time spent in other threads/processes.
2685 - Some systems only have a coarse resolution; check
2686 stopwatch.clock_info.resolution when using the results.
2687
2688 Usage:
2689
2690 with Stopwatch() as stopwatch:
2691 ...
2692 elapsed = stopwatch.seconds
2693 resolution = stopwatch.clock_info.resolution
2694 """
2695 def __enter__(self):
2696 get_time = time.perf_counter
2697 clock_info = time.get_clock_info('perf_counter')
2698 self.context = disable_gc()
2699 self.context.__enter__()
2700 self.get_time = get_time
2701 self.clock_info = clock_info
2702 self.start_time = get_time()
2703 return self
2704
2705 def __exit__(self, *exc):
2706 try:
2707 end_time = self.get_time()
2708 finally:
2709 result = self.context.__exit__(*exc)
2710 self.seconds = end_time - self.start_time
2711 return result
2712
2713
2714 @contextlib.contextmanager
2715 def adjust_int_max_str_digits(max_digits):
2716 """Temporarily change the integer string conversion length limit."""
2717 current = sys.get_int_max_str_digits()
2718 try:
2719 sys.set_int_max_str_digits(max_digits)
2720 yield
2721 finally:
2722 sys.set_int_max_str_digits(current)
2723
2724
2725 def exceeds_recursion_limit():
2726 """For recursion tests, easily exceeds default recursion limit."""
2727 return 150_000
2728
2729
2730 # Windows doesn't have os.uname() but it doesn't support s390x.
2731 is_s390x = hasattr(os, 'uname') and os.uname().machine == 's390x'
2732 skip_on_s390x = unittest.skipIf(is_s390x, 'skipped on s390x')
2733
2734 Py_TRACE_REFS = hasattr(sys, 'getobjects')
2735
2736 _JIT_ENABLED = sys._jit.is_enabled()
2737 requires_jit_enabled = unittest.skipUnless(_JIT_ENABLED, "requires JIT enabled")
2738 requires_jit_disabled = unittest.skipIf(_JIT_ENABLED, "requires JIT disabled")
2739
2740
2741 _BASE_COPY_SRC_DIR_IGNORED_NAMES = frozenset({
2742 # SRC_DIR/.git
2743 '.git',
2744 # ignore all __pycache__/ sub-directories
2745 '__pycache__',
2746 })
2747
2748 # Ignore function for shutil.copytree() to copy the Python source code.
2749 def copy_python_src_ignore(path, names):
2750 ignored = _BASE_COPY_SRC_DIR_IGNORED_NAMES
2751 if os.path.basename(path) == 'Doc':
2752 ignored |= {
2753 # SRC_DIR/Doc/build/
2754 'build',
2755 # SRC_DIR/Doc/venv/
2756 'venv',
2757 }
2758
2759 # check if we are at the root of the source code
2760 elif 'Modules' in names:
2761 ignored |= {
2762 # SRC_DIR/build/
2763 'build',
2764 }
2765 return ignored
2766
2767
2768 # XXX Move this to the inspect module?
2769 def walk_class_hierarchy(top, *, topdown=True):
2770 # This is based on the logic in os.walk().
2771 assert isinstance(top, type), repr(top)
2772 stack = [top]
2773 while stack:
2774 top = stack.pop()
2775 if isinstance(top, tuple):
2776 yield top
2777 continue
2778
2779 subs = type(top).__subclasses__(top)
2780 if topdown:
2781 # Yield before subclass traversal if going top down.
2782 yield top, subs
2783 # Traverse into subclasses.
2784 for sub in reversed(subs):
2785 stack.append(sub)
2786 else:
2787 # Yield after subclass traversal if going bottom up.
2788 stack.append((top, subs))
2789 # Traverse into subclasses.
2790 for sub in reversed(subs):
2791 stack.append(sub)
2792
2793
2794 def iter_builtin_types():
2795 # First try the explicit route.
2796 try:
2797 import _testinternalcapi
2798 except ImportError:
2799 _testinternalcapi = None
2800 if _testinternalcapi is not None:
2801 yield from _testinternalcapi.get_static_builtin_types()
2802 return
2803
2804 # Fall back to making a best-effort guess.
2805 if hasattr(object, '__flags__'):
2806 # Look for any type object with the Py_TPFLAGS_STATIC_BUILTIN flag set.
2807 import datetime
2808 seen = set()
2809 for cls, subs in walk_class_hierarchy(object):
2810 if cls in seen:
2811 continue
2812 seen.add(cls)
2813 if not (cls.__flags__ & _TPFLAGS_STATIC_BUILTIN):
2814 # Do not walk its subclasses.
2815 subs[:] = []
2816 continue
2817 yield cls
2818 else:
2819 # Fall back to a naive approach.
2820 seen = set()
2821 for obj in __builtins__.values():
2822 if not isinstance(obj, type):
2823 continue
2824 cls = obj
2825 # XXX?
2826 if cls.__module__ != 'builtins':
2827 continue
2828 if cls == ExceptionGroup:
2829 # It's a heap type.
2830 continue
2831 if cls in seen:
2832 continue
2833 seen.add(cls)
2834 yield cls
2835
2836
2837 # XXX Move this to the inspect module?
2838 def iter_name_in_mro(cls, name):
2839 """Yield matching items found in base.__dict__ across the MRO.
2840
2841 The descriptor protocol is not invoked.
2842
2843 list(iter_name_in_mro(cls, name))[0] is roughly equivalent to
2844 find_name_in_mro() in Objects/typeobject.c (AKA PyType_Lookup()).
2845
2846 inspect.getattr_static() is similar.
2847 """
2848 # This can fail if "cls" is weird.
2849 for base in inspect._static_getmro(cls):
2850 # This can fail if "base" is weird.
2851 ns = inspect._get_dunder_dict_of_class(base)
2852 try:
2853 obj = ns[name]
2854 except KeyError:
2855 continue
2856 yield obj, base
2857
2858
2859 # XXX Move this to the inspect module?
2860 def find_name_in_mro(cls, name, default=inspect._sentinel):
2861 for res in iter_name_in_mro(cls, name):
2862 # Return the first one.
2863 return res
2864 if default is not inspect._sentinel:
2865 return default, None
2866 raise AttributeError(name)
2867
2868
2869 # XXX The return value should always be exactly the same...
2870 def identify_type_slot_wrappers():
2871 try:
2872 import _testinternalcapi
2873 except ImportError:
2874 _testinternalcapi = None
2875 if _testinternalcapi is not None:
2876 names = {n: None for n in _testinternalcapi.identify_type_slot_wrappers()}
2877 return list(names)
2878 else:
2879 raise NotImplementedError
2880
2881
2882 def iter_slot_wrappers(cls):
2883 def is_slot_wrapper(name, value):
2884 if not isinstance(value, types.WrapperDescriptorType):
2885 assert not repr(value).startswith('<slot wrapper '), (cls, name, value)
2886 return False
2887 assert repr(value).startswith('<slot wrapper '), (cls, name, value)
2888 assert callable(value), (cls, name, value)
2889 assert name.startswith('__') and name.endswith('__'), (cls, name, value)
2890 return True
2891
2892 try:
2893 attrs = identify_type_slot_wrappers()
2894 except NotImplementedError:
2895 attrs = None
2896 if attrs is not None:
2897 for attr in sorted(attrs):
2898 obj, base = find_name_in_mro(cls, attr, None)
2899 if obj is not None and is_slot_wrapper(attr, obj):
2900 yield attr, base is cls
2901 return
2902
2903 # Fall back to a naive best-effort approach.
2904
2905 ns = vars(cls)
2906 unused = set(ns)
2907 for name in dir(cls):
2908 if name in ns:
2909 unused.remove(name)
2910
2911 try:
2912 value = getattr(cls, name)
2913 except AttributeError:
2914 # It's as though it weren't in __dir__.
2915 assert name in ('__annotate__', '__annotations__', '__abstractmethods__'), (cls, name)
2916 if name in ns and is_slot_wrapper(name, ns[name]):
2917 unused.add(name)
2918 continue
2919
2920 if not name.startswith('__') or not name.endswith('__'):
2921 assert not is_slot_wrapper(name, value), (cls, name, value)
2922 if not is_slot_wrapper(name, value):
2923 if name in ns:
2924 assert not is_slot_wrapper(name, ns[name]), (cls, name, value, ns[name])
2925 else:
2926 if name in ns:
2927 assert ns[name] is value, (cls, name, value, ns[name])
2928 yield name, True
2929 else:
2930 yield name, False
2931
2932 for name in unused:
2933 value = ns[name]
2934 if is_slot_wrapper(cls, name, value):
2935 yield name, True
2936
2937
2938 @contextlib.contextmanager
2939 def force_color(color: bool):
2940 import _colorize
2941 from .os_helper import EnvironmentVarGuard
2942
2943 with (
2944 swap_attr(_colorize, "can_colorize", lambda *, file=None: color),
2945 EnvironmentVarGuard() as env,
2946 ):
2947 env.unset("FORCE_COLOR", "NO_COLOR", "PYTHON_COLORS")
2948 env.set("FORCE_COLOR" if color else "NO_COLOR", "1")
2949 yield
2950
2951
2952 def force_colorized(func):
2953 """Force the terminal to be colorized."""
2954 @functools.wraps(func)
2955 def wrapper(*args, **kwargs):
2956 with force_color(True):
2957 return func(*args, **kwargs)
2958 return wrapper
2959
2960
2961 def force_not_colorized(func):
2962 """Force the terminal NOT to be colorized."""
2963 @functools.wraps(func)
2964 def wrapper(*args, **kwargs):
2965 with force_color(False):
2966 return func(*args, **kwargs)
2967 return wrapper
2968
2969
2970 def force_colorized_test_class(cls):
2971 """Force the terminal to be colorized for the entire test class."""
2972 original_setUpClass = cls.setUpClass
2973
2974 @classmethod
2975 @functools.wraps(cls.setUpClass)
2976 def new_setUpClass(cls):
2977 cls.enterClassContext(force_color(True))
2978 original_setUpClass()
2979
2980 cls.setUpClass = new_setUpClass
2981 return cls
2982
2983
2984 def force_not_colorized_test_class(cls):
2985 """Force the terminal NOT to be colorized for the entire test class."""
2986 original_setUpClass = cls.setUpClass
2987
2988 @classmethod
2989 @functools.wraps(cls.setUpClass)
2990 def new_setUpClass(cls):
2991 cls.enterClassContext(force_color(False))
2992 original_setUpClass()
2993
2994 cls.setUpClass = new_setUpClass
2995 return cls
2996
2997
2998 def make_clean_env() -> dict[str, str]:
2999 clean_env = os.environ.copy()
3000 for k in clean_env.copy():
3001 if k.startswith("PYTHON"):
3002 clean_env.pop(k)
3003 clean_env.pop("FORCE_COLOR", None)
3004 clean_env.pop("NO_COLOR", None)
3005 return clean_env
3006
3007
3008 WINDOWS_STATUS = {
3009 0xC0000005: "STATUS_ACCESS_VIOLATION",
3010 0xC00000FD: "STATUS_STACK_OVERFLOW",
3011 0xC000013A: "STATUS_CONTROL_C_EXIT",
3012 }
3013
3014 def get_signal_name(exitcode):
3015 import signal
3016
3017 if exitcode < 0:
3018 signum = -exitcode
3019 try:
3020 return signal.Signals(signum).name
3021 except ValueError:
3022 pass
3023
3024 # Shell exit code (ex: WASI build)
3025 if 128 < exitcode < 256:
3026 signum = exitcode - 128
3027 try:
3028 return signal.Signals(signum).name
3029 except ValueError:
3030 pass
3031
3032 try:
3033 return WINDOWS_STATUS[exitcode]
3034 except KeyError:
3035 pass
3036
3037 # Format Windows exit status as hexadecimal
3038 if 0xC0000000 <= exitcode:
3039 return f"0x{exitcode:X}"
3040
3041 return None
3042
3043 class BrokenIter:
3044 def __init__(self, init_raises=False, next_raises=False, iter_raises=False):
3045 if init_raises:
3046 1/0
3047 self.next_raises = next_raises
3048 self.iter_raises = iter_raises
3049
3050 def __next__(self):
3051 if self.next_raises:
3052 1/0
3053
3054 def __iter__(self):
3055 if self.iter_raises:
3056 1/0
3057 return self
3058
3059
3060 def in_systemd_nspawn_sync_suppressed() -> bool:
3061 """
3062 Test whether the test suite is runing in systemd-nspawn
3063 with ``--suppress-sync=true``.
3064
3065 This can be used to skip tests that rely on ``fsync()`` calls
3066 and similar not being intercepted.
3067 """
3068
3069 if not hasattr(os, "O_SYNC"):
3070 return False
3071
3072 try:
3073 with open("/run/systemd/container", "rb") as fp:
3074 if fp.read().rstrip() != b"systemd-nspawn":
3075 return False
3076 except FileNotFoundError:
3077 return False
3078
3079 # If systemd-nspawn is used, O_SYNC flag will immediately
3080 # trigger EINVAL. Otherwise, ENOENT will be given instead.
3081 import errno
3082 try:
3083 fd = os.open(__file__, os.O_RDONLY | os.O_SYNC)
3084 except OSError as err:
3085 if err.errno == errno.EINVAL:
3086 return True
3087 else:
3088 os.close(fd)
3089
3090 return False
3091
3092 def run_no_yield_async_fn(async_fn, /, *args, **kwargs):
3093 coro = async_fn(*args, **kwargs)
3094 try:
3095 coro.send(None)
3096 except StopIteration as e:
3097 return e.value
3098 else:
3099 raise AssertionError("coroutine did not complete")
3100 finally:
3101 coro.close()
3102
3103
3104 @types.coroutine
3105 def async_yield(v):
3106 return (yield v)
3107
3108
3109 def run_yielding_async_fn(async_fn, /, *args, **kwargs):
3110 coro = async_fn(*args, **kwargs)
3111 try:
3112 while True:
3113 try:
3114 coro.send(None)
3115 except StopIteration as e:
3116 return e.value
3117 finally:
3118 coro.close()
3119
3120
3121 def is_libssl_fips_mode():
3122 try:
3123 from _hashlib import get_fips_mode # ask _hashopenssl.c
3124 except ImportError:
3125 return False # more of a maybe, unless we add this to the _ssl module.
3126 return get_fips_mode() != 0
3127
3128 def _supports_remote_attaching():
3129 PROCESS_VM_READV_SUPPORTED = False
3130
3131 try:
3132 from _remote_debugging import PROCESS_VM_READV_SUPPORTED
3133 except ImportError:
3134 pass
3135
3136 return PROCESS_VM_READV_SUPPORTED
3137
3138 def _support_remote_exec_only_impl():
3139 if not sys.is_remote_debug_enabled():
3140 return unittest.skip("Remote debugging is not enabled")
3141 if sys.platform not in ("darwin", "linux", "win32"):
3142 return unittest.skip("Test only runs on Linux, Windows and macOS")
3143 if sys.platform == "linux" and not _supports_remote_attaching():
3144 return unittest.skip("Test only runs on Linux with process_vm_readv support")
3145 return _id
3146
3147 def support_remote_exec_only(test):
3148 return _support_remote_exec_only_impl()(test)
3149
3150 class EqualToForwardRef:
3151 """Helper to ease use of annotationlib.ForwardRef in tests.
3152
3153 This checks only attributes that can be set using the constructor.
3154
3155 """
3156
3157 def __init__(
3158 self,
3159 arg,
3160 *,
3161 module=None,
3162 owner=None,
3163 is_class=False,
3164 ):
3165 self.__forward_arg__ = arg
3166 self.__forward_is_class__ = is_class
3167 self.__forward_module__ = module
3168 self.__owner__ = owner
3169
3170 def __eq__(self, other):
3171 if not isinstance(other, (EqualToForwardRef, annotationlib.ForwardRef)):
3172 return NotImplemented
3173 return (
3174 self.__forward_arg__ == other.__forward_arg__
3175 and self.__forward_module__ == other.__forward_module__
3176 and self.__forward_is_class__ == other.__forward_is_class__
3177 and self.__owner__ == other.__owner__
3178 )
3179
3180 def __repr__(self):
3181 extra = []
3182 if self.__forward_module__ is not None:
3183 extra.append(f", module={self.__forward_module__!r}")
3184 if self.__forward_is_class__:
3185 extra.append(", is_class=True")
3186 if self.__owner__ is not None:
3187 extra.append(f", owner={self.__owner__!r}")
3188 return f"EqualToForwardRef({self.__forward_arg__!r}{''.join(extra)})"
3189
3190
3191 _linked_to_musl = None
3192 def linked_to_musl():
3193 """
3194 Report if the Python executable is linked to the musl C library.
3195
3196 Return False if we don't think it is, or a version triple otherwise.
3197 """
3198 # This is can be a relatively expensive check, so we use a cache.
3199 global _linked_to_musl
3200 if _linked_to_musl is not None:
3201 return _linked_to_musl
3202
3203 # emscripten (at least as far as we're concerned) and wasi use musl,
3204 # but platform doesn't know how to get the version, so set it to zero.
3205 if is_wasm32:
3206 _linked_to_musl = (0, 0, 0)
3207 return _linked_to_musl
3208
3209 # On all other non-linux platforms assume no musl.
3210 if sys.platform != 'linux':
3211 _linked_to_musl = False
3212 return _linked_to_musl
3213
3214 # On linux, we'll depend on the platform module to do the check, so new
3215 # musl platforms should add support in that module if possible.
3216 import platform
3217 lib, version = platform.libc_ver()
3218 if lib != 'musl':
3219 _linked_to_musl = False
3220 return _linked_to_musl
3221 _linked_to_musl = tuple(map(int, version.split('.')))
3222 return _linked_to_musl
3223
3224
3225 def control_characters_c0() -> list[str]:
3226 """Returns a list of C0 control characters as strings.
3227 C0 control characters defined as the byte range 0x00-0x1F, and 0x7F.
3228 """
3229 return [chr(c) for c in range(0x00, 0x20)] + ["\x7F"]
3230
3231
3232 STATUS_DLL_INIT_FAILED = 0xC0000142
3233 def skip_on_low_desktop_heap_memory_subprocess(returncode):
3234 if sys.platform not in ('win32', 'cygwin'):
3235 return
3236 # On Windows, STATUS_DLL_INIT_FAILED is a generic error code that could
3237 # come from any of the DLLs being loaded when a new Python process is
3238 # created. In practice, it's likely a memory allocation failure in the
3239 # desktop heap memory which caused the DLL init failure, especially on
3240 # process created with CREATE_NEW_CONSOLE creation flag. See the article:
3241 # https://learn.microsoft.com/en-us/troubleshoot/windows-server/performance/desktop-heap-limitation-out-of-memory
3242 if returncode == STATUS_DLL_INIT_FAILED:
3243 raise unittest.SkipTest('gh-150436: DLL init failed, likely because '
3244 'of low desktop heap memory')