Python code coverage for Lib/packaging/tests/support.py

#	count	content
1	n/a	"""Support code for packaging test cases.
2	n/a
3	n/a	*This module should not be considered public: its content and API may
4	n/a	change in incompatible ways.*
5	n/a
6	n/a	A few helper classes are provided: LoggingCatcher, TempdirManager and
7	n/a	EnvironRestorer. They are written to be used as mixins::
8	n/a
9	n/a	from packaging.tests import unittest
10	n/a	from packaging.tests.support import LoggingCatcher
11	n/a
12	n/a	class SomeTestCase(LoggingCatcher, unittest.TestCase):
13	n/a	...
14	n/a
15	n/a	If you need to define a setUp method on your test class, you have to
16	n/a	call the mixin class' setUp method or it won't work (same thing for
17	n/a	tearDown):
18	n/a
19	n/a	def setUp(self):
20	n/a	super(SomeTestCase, self).setUp()
21	n/a	... # other setup code
22	n/a
23	n/a	Also provided is a DummyCommand class, useful to mock commands in the
24	n/a	tests of another command that needs them, for example to fake
25	n/a	compilation in build_ext (this requires that the mock build_ext command
26	n/a	be injected into the distribution object's command_obj dictionary).
27	n/a
28	n/a	For tests that need to compile an extension module, use the
29	n/a	copy_xxmodule_c and fixup_build_ext functions.
30	n/a
31	n/a	Each class or function has a docstring to explain its purpose and usage.
32	n/a	Existing tests should also be used as examples.
33	n/a	"""
34	n/a
35	n/a	import os
36	n/a	import sys
37	n/a	import shutil
38	n/a	import logging
39	n/a	import weakref
40	n/a	import tempfile
41	n/a	import sysconfig
42	n/a
43	n/a	from packaging.dist import Distribution
44	n/a	from packaging.util import resolve_name
45	n/a	from packaging.command import set_command, _COMMANDS
46	n/a
47	n/a	from packaging.tests import unittest
48	n/a	from test.support import requires_zlib, unlink
49	n/a
50	n/a	# define __all__ to make pydoc more useful
51	n/a	__all__ = [
52	n/a	# TestCase mixins
53	n/a	'LoggingCatcher', 'TempdirManager', 'EnvironRestorer',
54	n/a	# mocks
55	n/a	'DummyCommand', 'TestDistribution', 'Inputs',
56	n/a	# misc. functions and decorators
57	n/a	'fake_dec', 'create_distribution', 'use_command',
58	n/a	'copy_xxmodule_c', 'fixup_build_ext',
59	n/a	'skip_2to3_optimize',
60	n/a	# imported from this module for backport purposes
61	n/a	'unittest', 'requires_zlib', 'skip_unless_symlink',
62	n/a	]
63	n/a
64	n/a
65	n/a	logger = logging.getLogger('packaging')
66	n/a	logger2to3 = logging.getLogger('RefactoringTool')
67	n/a
68	n/a
69	n/a	class _TestHandler(logging.handlers.BufferingHandler):
70	n/a	# stolen and adapted from test.support
71	n/a
72	n/a	def __init__(self):
73	n/a	super(_TestHandler, self).__init__(0)
74	n/a	self.setLevel(logging.DEBUG)
75	n/a
76	n/a	def shouldFlush(self):
77	n/a	return False
78	n/a
79	n/a	def emit(self, record):
80	n/a	self.buffer.append(record)
81	n/a
82	n/a
83	n/a	class LoggingCatcher:
84	n/a	"""TestCase-compatible mixin to receive logging calls.
85	n/a
86	n/a	Upon setUp, instances of this classes get a BufferingHandler that's
87	n/a	configured to record all messages logged to the 'packaging' logger.
88	n/a
89	n/a	Use get_logs to retrieve messages and self.loghandler.flush to discard
90	n/a	them. get_logs automatically flushes the logs, unless you pass
91	n/a	flush=False, for example to make multiple calls to the method with
92	n/a	different level arguments. If your test calls some code that generates
93	n/a	logging message and then you don't call get_logs, you will need to flush
94	n/a	manually before testing other code in the same test_* method, otherwise
95	n/a	get_logs in the next lines will see messages from the previous lines.
96	n/a	See example in test_command_check.
97	n/a	"""
98	n/a
99	n/a	def setUp(self):
100	n/a	super(LoggingCatcher, self).setUp()
101	n/a	self.loghandler = handler = _TestHandler()
102	n/a	self._old_levels = logger.level, logger2to3.level
103	n/a	logger.addHandler(handler)
104	n/a	logger.setLevel(logging.DEBUG) # we want all messages
105	n/a	logger2to3.setLevel(logging.CRITICAL) # we don't want 2to3 messages
106	n/a
107	n/a	def tearDown(self):
108	n/a	handler = self.loghandler
109	n/a	# All this is necessary to properly shut down the logging system and
110	n/a	# avoid a regrtest complaint. Thanks to Vinay Sajip for the help.
111	n/a	handler.close()
112	n/a	logger.removeHandler(handler)
113	n/a	for ref in weakref.getweakrefs(handler):
114	n/a	logging._removeHandlerRef(ref)
115	n/a	del self.loghandler
116	n/a	logger.setLevel(self._old_levels[0])
117	n/a	logger2to3.setLevel(self._old_levels[1])
118	n/a	super(LoggingCatcher, self).tearDown()
119	n/a
120	n/a	def get_logs(self, level=logging.WARNING, flush=True):
121	n/a	"""Return all log messages with given level.
122	n/a
123	n/a	level defaults to logging.WARNING.
124	n/a
125	n/a	For log calls with arguments (i.e. logger.info('bla bla %r', arg)),
126	n/a	the messages will be formatted before being returned (e.g. "bla bla
127	n/a	'thing'").
128	n/a
129	n/a	Returns a list. Automatically flushes the loghandler after being
130	n/a	called, unless flush is False (this is useful to get e.g. all
131	n/a	warnings then all info messages).
132	n/a	"""
133	n/a	messages = [log.getMessage() for log in self.loghandler.buffer
134	n/a	if log.levelno == level]
135	n/a	if flush:
136	n/a	self.loghandler.flush()
137	n/a	return messages
138	n/a
139	n/a
140	n/a	class TempdirManager:
141	n/a	"""TestCase-compatible mixin to create temporary directories and files.
142	n/a
143	n/a	Directories and files created in a test_* method will be removed after it
144	n/a	has run.
145	n/a	"""
146	n/a
147	n/a	def setUp(self):
148	n/a	super(TempdirManager, self).setUp()
149	n/a	self._olddir = os.getcwd()
150	n/a	self._basetempdir = tempfile.mkdtemp()
151	n/a	self._files = []
152	n/a
153	n/a	def tearDown(self):
154	n/a	for handle, name in self._files:
155	n/a	handle.close()
156	n/a	unlink(name)
157	n/a
158	n/a	os.chdir(self._olddir)
159	n/a	shutil.rmtree(self._basetempdir)
160	n/a	super(TempdirManager, self).tearDown()
161	n/a
162	n/a	def mktempfile(self):
163	n/a	"""Create a read-write temporary file and return it."""
164	n/a	fd, fn = tempfile.mkstemp(dir=self._basetempdir)
165	n/a	os.close(fd)
166	n/a	fp = open(fn, 'w+')
167	n/a	self._files.append((fp, fn))
168	n/a	return fp
169	n/a
170	n/a	def mkdtemp(self):
171	n/a	"""Create a temporary directory and return its path."""
172	n/a	d = tempfile.mkdtemp(dir=self._basetempdir)
173	n/a	return d
174	n/a
175	n/a	def write_file(self, path, content='xxx', encoding=None):
176	n/a	"""Write a file at the given path.
177	n/a
178	n/a	path can be a string, a tuple or a list; if it's a tuple or list,
179	n/a	os.path.join will be used to produce a path.
180	n/a	"""
181	n/a	if isinstance(path, (list, tuple)):
182	n/a	path = os.path.join(*path)
183	n/a	with open(path, 'w', encoding=encoding) as f:
184	n/a	f.write(content)
185	n/a
186	n/a	def create_dist(self, **kw):
187	n/a	"""Create a stub distribution object and files.
188	n/a
189	n/a	This function creates a Distribution instance (use keyword arguments
190	n/a	to customize it) and a temporary directory with a project structure
191	n/a	(currently an empty directory).
192	n/a
193	n/a	It returns the path to the directory and the Distribution instance.
194	n/a	You can use self.write_file to write any file in that
195	n/a	directory, e.g. setup scripts or Python modules.
196	n/a	"""
197	n/a	if 'name' not in kw:
198	n/a	kw['name'] = 'foo'
199	n/a	tmp_dir = self.mkdtemp()
200	n/a	project_dir = os.path.join(tmp_dir, kw['name'])
201	n/a	os.mkdir(project_dir)
202	n/a	dist = Distribution(attrs=kw)
203	n/a	return project_dir, dist
204	n/a
205	n/a	def assertIsFile(self, *args):
206	n/a	path = os.path.join(*args)
207	n/a	dirname = os.path.dirname(path)
208	n/a	file = os.path.basename(path)
209	n/a	if os.path.isdir(dirname):
210	n/a	files = os.listdir(dirname)
211	n/a	msg = "%s not found in %s: %s" % (file, dirname, files)
212	n/a	assert os.path.isfile(path), msg
213	n/a	else:
214	n/a	raise AssertionError(
215	n/a	'%s not found. %s does not exist' % (file, dirname))
216	n/a
217	n/a	def assertIsNotFile(self, *args):
218	n/a	path = os.path.join(*args)
219	n/a	self.assertFalse(os.path.isfile(path), "%r exists" % path)
220	n/a
221	n/a
222	n/a	class EnvironRestorer:
223	n/a	"""TestCase-compatible mixin to restore or delete environment variables.
224	n/a
225	n/a	The variables to restore (or delete if they were not originally present)
226	n/a	must be explicitly listed in self.restore_environ. It's better to be
227	n/a	aware of what we're modifying instead of saving and restoring the whole
228	n/a	environment.
229	n/a	"""
230	n/a
231	n/a	def setUp(self):
232	n/a	super(EnvironRestorer, self).setUp()
233	n/a	self._saved = []
234	n/a	self._added = []
235	n/a	for key in self.restore_environ:
236	n/a	if key in os.environ:
237	n/a	self._saved.append((key, os.environ[key]))
238	n/a	else:
239	n/a	self._added.append(key)
240	n/a
241	n/a	def tearDown(self):
242	n/a	for key, value in self._saved:
243	n/a	os.environ[key] = value
244	n/a	for key in self._added:
245	n/a	os.environ.pop(key, None)
246	n/a	super(EnvironRestorer, self).tearDown()
247	n/a
248	n/a
249	n/a	class DummyCommand:
250	n/a	"""Class to store options for retrieval via set_undefined_options().
251	n/a
252	n/a	Useful for mocking one dependency command in the tests for another
253	n/a	command, see e.g. the dummy build command in test_build_scripts.
254	n/a	"""
255	n/a	# XXX does not work with dist.reinitialize_command, which typechecks
256	n/a	# and wants a finalized attribute
257	n/a
258	n/a	def __init__(self, **kwargs):
259	n/a	for kw, val in kwargs.items():
260	n/a	setattr(self, kw, val)
261	n/a
262	n/a	def ensure_finalized(self):
263	n/a	pass
264	n/a
265	n/a
266	n/a	class TestDistribution(Distribution):
267	n/a	"""Distribution subclasses that avoids the default search for
268	n/a	configuration files.
269	n/a
270	n/a	The ._config_files attribute must be set before
271	n/a	.parse_config_files() is called.
272	n/a	"""
273	n/a
274	n/a	def find_config_files(self):
275	n/a	return self._config_files
276	n/a
277	n/a
278	n/a	class Inputs:
279	n/a	"""Fakes user inputs."""
280	n/a	# TODO document usage
281	n/a	# TODO use context manager or something for auto cleanup
282	n/a
283	n/a	def __init__(self, *answers):
284	n/a	self.answers = answers
285	n/a	self.index = 0
286	n/a
287	n/a	def __call__(self, prompt=''):
288	n/a	try:
289	n/a	return self.answers[self.index]
290	n/a	finally:
291	n/a	self.index += 1
292	n/a
293	n/a
294	n/a	def create_distribution(configfiles=()):
295	n/a	"""Prepares a distribution with given config files parsed."""
296	n/a	d = TestDistribution()
297	n/a	d.config.find_config_files = d.find_config_files
298	n/a	d._config_files = configfiles
299	n/a	d.parse_config_files()
300	n/a	d.parse_command_line()
301	n/a	return d
302	n/a
303	n/a
304	n/a	def use_command(testcase, fullname):
305	n/a	"""Register command at fullname for the duration of a test."""
306	n/a	set_command(fullname)
307	n/a	# XXX maybe set_command should return the class object
308	n/a	name = resolve_name(fullname).get_command_name()
309	n/a	# XXX maybe we need a public API to remove commands
310	n/a	testcase.addCleanup(_COMMANDS.__delitem__, name)
311	n/a
312	n/a
313	n/a	def fake_dec(args, *kw):
314	n/a	"""Fake decorator"""
315	n/a	def _wrap(func):
316	n/a	def __wrap(args, *kw):
317	n/a	return func(args, *kw)
318	n/a	return __wrap
319	n/a	return _wrap
320	n/a
321	n/a
322	n/a	def copy_xxmodule_c(directory):
323	n/a	"""Helper for tests that need the xxmodule.c source file.
324	n/a
325	n/a	Example use:
326	n/a
327	n/a	def test_compile(self):
328	n/a	copy_xxmodule_c(self.tmpdir)
329	n/a	self.assertIn('xxmodule.c', os.listdir(self.tmpdir))
330	n/a
331	n/a	If the source file can be found, it will be copied to directory. If not,
332	n/a	the test will be skipped. Errors during copy are not caught.
333	n/a	"""
334	n/a	filename = _get_xxmodule_path()
335	n/a	if filename is None:
336	n/a	raise unittest.SkipTest('cannot find xxmodule.c')
337	n/a	shutil.copy(filename, directory)
338	n/a
339	n/a
340	n/a	def _get_xxmodule_path():
341	n/a	if sysconfig.is_python_build():
342	n/a	srcdir = sysconfig.get_config_var('projectbase')
343	n/a	path = os.path.join(os.getcwd(), srcdir, 'Modules', 'xxmodule.c')
344	n/a	else:
345	n/a	path = os.path.join(os.path.dirname(__file__), 'xxmodule.c')
346	n/a	if os.path.exists(path):
347	n/a	return path
348	n/a
349	n/a
350	n/a	def fixup_build_ext(cmd):
351	n/a	"""Function needed to make build_ext tests pass.
352	n/a
353	n/a	When Python was built with --enable-shared on Unix, -L. is not enough to
354	n/a	find libpython<blah>.so, because regrtest runs in a tempdir, not in the
355	n/a	source directory where the .so lives. (Mac OS X embeds absolute paths
356	n/a	to shared libraries into executables, so the fixup is a no-op on that
357	n/a	platform.)
358	n/a
359	n/a	When Python was built with in debug mode on Windows, build_ext commands
360	n/a	need their debug attribute set, and it is not done automatically for
361	n/a	some reason.
362	n/a
363	n/a	This function handles both of these things, and also fixes
364	n/a	cmd.distribution.include_dirs if the running Python is an uninstalled
365	n/a	build. Example use:
366	n/a
367	n/a	cmd = build_ext(dist)
368	n/a	support.fixup_build_ext(cmd)
369	n/a	cmd.ensure_finalized()
370	n/a	"""
371	n/a	if os.name == 'nt':
372	n/a	cmd.debug = sys.executable.endswith('_d.exe')
373	n/a	elif sysconfig.get_config_var('Py_ENABLE_SHARED'):
374	n/a	# To further add to the shared builds fun on Unix, we can't just add
375	n/a	# library_dirs to the Extension() instance because that doesn't get
376	n/a	# plumbed through to the final compiler command.
377	n/a	runshared = sysconfig.get_config_var('RUNSHARED')
378	n/a	if runshared is None:
379	n/a	cmd.library_dirs = ['.']
380	n/a	else:
381	n/a	if sys.platform == 'darwin':
382	n/a	cmd.library_dirs = []
383	n/a	else:
384	n/a	name, equals, value = runshared.partition('=')
385	n/a	cmd.library_dirs = value.split(os.pathsep)
386	n/a
387	n/a	# Allow tests to run with an uninstalled Python
388	n/a	if sysconfig.is_python_build():
389	n/a	pysrcdir = sysconfig.get_config_var('projectbase')
390	n/a	cmd.distribution.include_dirs.append(os.path.join(pysrcdir, 'Include'))
391	n/a
392	n/a
393	n/a	try:
394	n/a	from test.support import skip_unless_symlink
395	n/a	except ImportError:
396	n/a	skip_unless_symlink = unittest.skip(
397	n/a	'requires test.support.skip_unless_symlink')
398	n/a
399	n/a	skip_2to3_optimize = unittest.skipIf(sys.flags.optimize,
400	n/a	"2to3 doesn't work under -O")