Python code coverage for Lib/distutils/core.py

#	count	content
1	n/a	"""distutils.core
2	n/a
3	n/a	The only module that needs to be imported to use the Distutils; provides
4	n/a	the 'setup' function (which is to be called from the setup script). Also
5	n/a	indirectly provides the Distribution and Command classes, although they are
6	n/a	really defined in distutils.dist and distutils.cmd.
7	n/a	"""
8	n/a
9	n/a	import os
10	n/a	import sys
11	n/a
12	n/a	from distutils.debug import DEBUG
13	n/a	from distutils.errors import *
14	n/a
15	n/a	# Mainly import these so setup scripts can "from distutils.core import" them.
16	n/a	from distutils.dist import Distribution
17	n/a	from distutils.cmd import Command
18	n/a	from distutils.config import PyPIRCCommand
19	n/a	from distutils.extension import Extension
20	n/a
21	n/a	# This is a barebones help message generated displayed when the user
22	n/a	# runs the setup script with no arguments at all. More useful help
23	n/a	# is generated with various --help options: global help, list commands,
24	n/a	# and per-command help.
25	n/a	USAGE = """\
26	n/a	usage: %(script)s [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
27	n/a	or: %(script)s --help [cmd1 cmd2 ...]
28	n/a	or: %(script)s --help-commands
29	n/a	or: %(script)s cmd --help
30	n/a	"""
31	n/a
32	n/a	def gen_usage (script_name):
33	n/a	script = os.path.basename(script_name)
34	n/a	return USAGE % vars()
35	n/a
36	n/a
37	n/a	# Some mild magic to control the behaviour of 'setup()' from 'run_setup()'.
38	n/a	_setup_stop_after = None
39	n/a	_setup_distribution = None
40	n/a
41	n/a	# Legal keyword arguments for the setup() function
42	n/a	setup_keywords = ('distclass', 'script_name', 'script_args', 'options',
43	n/a	'name', 'version', 'author', 'author_email',
44	n/a	'maintainer', 'maintainer_email', 'url', 'license',
45	n/a	'description', 'long_description', 'keywords',
46	n/a	'platforms', 'classifiers', 'download_url',
47	n/a	'requires', 'provides', 'obsoletes',
48	n/a	)
49	n/a
50	n/a	# Legal keyword arguments for the Extension constructor
51	n/a	extension_keywords = ('name', 'sources', 'include_dirs',
52	n/a	'define_macros', 'undef_macros',
53	n/a	'library_dirs', 'libraries', 'runtime_library_dirs',
54	n/a	'extra_objects', 'extra_compile_args', 'extra_link_args',
55	n/a	'swig_opts', 'export_symbols', 'depends', 'language')
56	n/a
57	n/a	def setup (**attrs):
58	n/a	"""The gateway to the Distutils: do everything your setup script needs
59	n/a	to do, in a highly flexible and user-driven way. Briefly: create a
60	n/a	Distribution instance; find and parse config files; parse the command
61	n/a	line; run each Distutils command found there, customized by the options
62	n/a	supplied to 'setup()' (as keyword arguments), in config files, and on
63	n/a	the command line.
64	n/a
65	n/a	The Distribution instance might be an instance of a class supplied via
66	n/a	the 'distclass' keyword argument to 'setup'; if no such class is
67	n/a	supplied, then the Distribution class (in dist.py) is instantiated.
68	n/a	All other arguments to 'setup' (except for 'cmdclass') are used to set
69	n/a	attributes of the Distribution instance.
70	n/a
71	n/a	The 'cmdclass' argument, if supplied, is a dictionary mapping command
72	n/a	names to command classes. Each command encountered on the command line
73	n/a	will be turned into a command class, which is in turn instantiated; any
74	n/a	class found in 'cmdclass' is used in place of the default, which is
75	n/a	(for command 'foo_bar') class 'foo_bar' in module
76	n/a	'distutils.command.foo_bar'. The command class must provide a
77	n/a	'user_options' attribute which is a list of option specifiers for
78	n/a	'distutils.fancy_getopt'. Any command-line options between the current
79	n/a	and the next command are used to set attributes of the current command
80	n/a	object.
81	n/a
82	n/a	When the entire command-line has been successfully parsed, calls the
83	n/a	'run()' method on each command object in turn. This method will be
84	n/a	driven entirely by the Distribution object (which each command object
85	n/a	has a reference to, thanks to its constructor), and the
86	n/a	command-specific options that became attributes of each command
87	n/a	object.
88	n/a	"""
89	n/a
90	n/a	global _setup_stop_after, _setup_distribution
91	n/a
92	n/a	# Determine the distribution class -- either caller-supplied or
93	n/a	# our Distribution (see below).
94	n/a	klass = attrs.get('distclass')
95	n/a	if klass:
96	n/a	del attrs['distclass']
97	n/a	else:
98	n/a	klass = Distribution
99	n/a
100	n/a	if 'script_name' not in attrs:
101	n/a	attrs['script_name'] = os.path.basename(sys.argv[0])
102	n/a	if 'script_args' not in attrs:
103	n/a	attrs['script_args'] = sys.argv[1:]
104	n/a
105	n/a	# Create the Distribution instance, using the remaining arguments
106	n/a	# (ie. everything except distclass) to initialize it
107	n/a	try:
108	n/a	_setup_distribution = dist = klass(attrs)
109	n/a	except DistutilsSetupError as msg:
110	n/a	if 'name' not in attrs:
111	n/a	raise SystemExit("error in setup command: %s" % msg)
112	n/a	else:
113	n/a	raise SystemExit("error in %s setup command: %s" % \
114	n/a	(attrs['name'], msg))
115	n/a
116	n/a	if _setup_stop_after == "init":
117	n/a	return dist
118	n/a
119	n/a	# Find and parse the config file(s): they will override options from
120	n/a	# the setup script, but be overridden by the command line.
121	n/a	dist.parse_config_files()
122	n/a
123	n/a	if DEBUG:
124	n/a	print("options (after parsing config files):")
125	n/a	dist.dump_option_dicts()
126	n/a
127	n/a	if _setup_stop_after == "config":
128	n/a	return dist
129	n/a
130	n/a	# Parse the command line and override config files; any
131	n/a	# command-line errors are the end user's fault, so turn them into
132	n/a	# SystemExit to suppress tracebacks.
133	n/a	try:
134	n/a	ok = dist.parse_command_line()
135	n/a	except DistutilsArgError as msg:
136	n/a	raise SystemExit(gen_usage(dist.script_name) + "\nerror: %s" % msg)
137	n/a
138	n/a	if DEBUG:
139	n/a	print("options (after parsing command line):")
140	n/a	dist.dump_option_dicts()
141	n/a
142	n/a	if _setup_stop_after == "commandline":
143	n/a	return dist
144	n/a
145	n/a	# And finally, run all the commands found on the command line.
146	n/a	if ok:
147	n/a	try:
148	n/a	dist.run_commands()
149	n/a	except KeyboardInterrupt:
150	n/a	raise SystemExit("interrupted")
151	n/a	except OSError as exc:
152	n/a	if DEBUG:
153	n/a	sys.stderr.write("error: %s\n" % (exc,))
154	n/a	raise
155	n/a	else:
156	n/a	raise SystemExit("error: %s" % (exc,))
157	n/a
158	n/a	except (DistutilsError,
159	n/a	CCompilerError) as msg:
160	n/a	if DEBUG:
161	n/a	raise
162	n/a	else:
163	n/a	raise SystemExit("error: " + str(msg))
164	n/a
165	n/a	return dist
166	n/a
167	n/a	# setup ()
168	n/a
169	n/a
170	n/a	def run_setup (script_name, script_args=None, stop_after="run"):
171	n/a	"""Run a setup script in a somewhat controlled environment, and
172	n/a	return the Distribution instance that drives things. This is useful
173	n/a	if you need to find out the distribution meta-data (passed as
174	n/a	keyword args from 'script' to 'setup()', or the contents of the
175	n/a	config files or command-line.
176	n/a
177	n/a	'script_name' is a file that will be read and run with 'exec()';
178	n/a	'sys.argv[0]' will be replaced with 'script' for the duration of the
179	n/a	call. 'script_args' is a list of strings; if supplied,
180	n/a	'sys.argv[1:]' will be replaced by 'script_args' for the duration of
181	n/a	the call.
182	n/a
183	n/a	'stop_after' tells 'setup()' when to stop processing; possible
184	n/a	values:
185	n/a	init
186	n/a	stop after the Distribution instance has been created and
187	n/a	populated with the keyword arguments to 'setup()'
188	n/a	config
189	n/a	stop after config files have been parsed (and their data
190	n/a	stored in the Distribution instance)
191	n/a	commandline
192	n/a	stop after the command-line ('sys.argv[1:]' or 'script_args')
193	n/a	have been parsed (and the data stored in the Distribution)
194	n/a	run [default]
195	n/a	stop after all commands have been run (the same as if 'setup()'
196	n/a	had been called in the usual way
197	n/a
198	n/a	Returns the Distribution instance, which provides all information
199	n/a	used to drive the Distutils.
200	n/a	"""
201	n/a	if stop_after not in ('init', 'config', 'commandline', 'run'):
202	n/a	raise ValueError("invalid value for 'stop_after': %r" % (stop_after,))
203	n/a
204	n/a	global _setup_stop_after, _setup_distribution
205	n/a	_setup_stop_after = stop_after
206	n/a
207	n/a	save_argv = sys.argv.copy()
208	n/a	g = {'__file__': script_name}
209	n/a	try:
210	n/a	try:
211	n/a	sys.argv[0] = script_name
212	n/a	if script_args is not None:
213	n/a	sys.argv[1:] = script_args
214	n/a	with open(script_name, 'rb') as f:
215	n/a	exec(f.read(), g)
216	n/a	finally:
217	n/a	sys.argv = save_argv
218	n/a	_setup_stop_after = None
219	n/a	except SystemExit:
220	n/a	# Hmm, should we do something if exiting with a non-zero code
221	n/a	# (ie. error)?
222	n/a	pass
223	n/a
224	n/a	if _setup_distribution is None:
225	n/a	raise RuntimeError(("'distutils.core.setup()' was never called -- "
226	n/a	"perhaps '%s' is not a Distutils setup script?") % \
227	n/a	script_name)
228	n/a
229	n/a	# I wonder if the setup script's namespace -- g and l -- would be of
230	n/a	# any interest to callers?
231	n/a	#print "_setup_distribution:", _setup_distribution
232	n/a	return _setup_distribution
233	n/a
234	n/a	# run_setup ()