Python code coverage for Lib/packaging/dist.py

#	count	content
1	n/a	"""Class representing the project being built/installed/etc."""
2	n/a
3	n/a	import os
4	n/a	import re
5	n/a
6	n/a	from packaging import logger
7	n/a	from packaging.util import strtobool, resolve_name
8	n/a	from packaging.config import Config
9	n/a	from packaging.errors import (PackagingOptionError, PackagingArgError,
10	n/a	PackagingModuleError, PackagingClassError)
11	n/a	from packaging.command import get_command_class, STANDARD_COMMANDS
12	n/a	from packaging.command.cmd import Command
13	n/a	from packaging.metadata import Metadata
14	n/a	from packaging.fancy_getopt import FancyGetopt
15	n/a
16	n/a	# Regex to define acceptable Packaging command names. This is not quite
17	n/a	# the same as a Python name -- leading underscores are not allowed. The fact
18	n/a	# that they're very similar is no coincidence: the default naming scheme is
19	n/a	# to look for a Python module named after the command.
20	n/a	command_re = re.compile(r'^[a-zA-Z]([a-zA-Z0-9_]*)$')
21	n/a
22	n/a	USAGE = """\
23	n/a	usage: %(script)s [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
24	n/a	or: %(script)s --help [cmd1 cmd2 ...]
25	n/a	or: %(script)s --help-commands
26	n/a	or: %(script)s cmd --help
27	n/a	"""
28	n/a
29	n/a
30	n/a	def gen_usage(script_name):
31	n/a	script = os.path.basename(script_name)
32	n/a	return USAGE % {'script': script}
33	n/a
34	n/a
35	n/a	class Distribution:
36	n/a	"""Class used to represent a project and work with it.
37	n/a
38	n/a	Most of the work hiding behind 'pysetup run' is really done within a
39	n/a	Distribution instance, which farms the work out to the commands
40	n/a	specified on the command line.
41	n/a	"""
42	n/a
43	n/a	# 'global_options' describes the command-line options that may be
44	n/a	# supplied to the setup script prior to any actual commands.
45	n/a	# Eg. "pysetup run -n" or "pysetup run --dry-run" both take advantage of
46	n/a	# these global options. This list should be kept to a bare minimum,
47	n/a	# since every global option is also valid as a command option -- and we
48	n/a	# don't want to pollute the commands with too many options that they
49	n/a	# have minimal control over.
50	n/a	global_options = [
51	n/a	('dry-run', 'n', "don't actually do anything"),
52	n/a	('help', 'h', "show detailed help message"),
53	n/a	('no-user-cfg', None, 'ignore pydistutils.cfg in your home directory'),
54	n/a	]
55	n/a
56	n/a	# 'common_usage' is a short (2-3 line) string describing the common
57	n/a	# usage of the setup script.
58	n/a	common_usage = """\
59	n/a	Common commands: (see '--help-commands' for more)
60	n/a
61	n/a	pysetup run build will build the project underneath 'build/'
62	n/a	pysetup run install will install the project
63	n/a	"""
64	n/a
65	n/a	# options that are not propagated to the commands
66	n/a	display_options = [
67	n/a	('help-commands', None,
68	n/a	"list all available commands"),
69	n/a	('use-2to3', None,
70	n/a	"use 2to3 to make source python 3.x compatible"),
71	n/a	('convert-2to3-doctests', None,
72	n/a	"use 2to3 to convert doctests in separate text files"),
73	n/a	]
74	n/a	display_option_names = [x[0].replace('-', '_') for x in display_options]
75	n/a
76	n/a	# negative options are options that exclude other options
77	n/a	negative_opt = {}
78	n/a
79	n/a	# -- Creation/initialization methods -------------------------------
80	n/a	def __init__(self, attrs=None):
81	n/a	"""Construct a new Distribution instance: initialize all the
82	n/a	attributes of a Distribution, and then use 'attrs' (a dictionary
83	n/a	mapping attribute names to values) to assign some of those
84	n/a	attributes their "real" values. (Any attributes not mentioned in
85	n/a	'attrs' will be assigned to some null value: 0, None, an empty list
86	n/a	or dictionary, etc.) Most importantly, initialize the
87	n/a	'command_obj' attribute to the empty dictionary; this will be
88	n/a	filled in with real command objects by 'parse_command_line()'.
89	n/a	"""
90	n/a
91	n/a	# Default values for our command-line options
92	n/a	self.dry_run = False
93	n/a	self.help = False
94	n/a	for attr in self.display_option_names:
95	n/a	setattr(self, attr, False)
96	n/a
97	n/a	# Store the configuration
98	n/a	self.config = Config(self)
99	n/a
100	n/a	# Store the distribution metadata (name, version, author, and so
101	n/a	# forth) in a separate object -- we're getting to have enough
102	n/a	# information here (and enough command-line options) that it's
103	n/a	# worth it.
104	n/a	self.metadata = Metadata()
105	n/a
106	n/a	# 'cmdclass' maps command names to class objects, so we
107	n/a	# can 1) quickly figure out which class to instantiate when
108	n/a	# we need to create a new command object, and 2) have a way
109	n/a	# for the setup script to override command classes
110	n/a	self.cmdclass = {}
111	n/a
112	n/a	# 'script_name' and 'script_args' are usually set to sys.argv[0]
113	n/a	# and sys.argv[1:], but they can be overridden when the caller is
114	n/a	# not necessarily a setup script run from the command line.
115	n/a	self.script_name = None
116	n/a	self.script_args = None
117	n/a
118	n/a	# 'command_options' is where we store command options between
119	n/a	# parsing them (from config files, the command line, etc.) and when
120	n/a	# they are actually needed -- ie. when the command in question is
121	n/a	# instantiated. It is a dictionary of dictionaries of 2-tuples:
122	n/a	# command_options = { command_name : { option : (source, value) } }
123	n/a	self.command_options = {}
124	n/a
125	n/a	# 'dist_files' is the list of (command, pyversion, file) that
126	n/a	# have been created by any dist commands run so far. This is
127	n/a	# filled regardless of whether the run is dry or not. pyversion
128	n/a	# gives sysconfig.get_python_version() if the dist file is
129	n/a	# specific to a Python version, 'any' if it is good for all
130	n/a	# Python versions on the target platform, and '' for a source
131	n/a	# file. pyversion should not be used to specify minimum or
132	n/a	# maximum required Python versions; use the metainfo for that
133	n/a	# instead.
134	n/a	self.dist_files = []
135	n/a
136	n/a	# These options are really the business of various commands, rather
137	n/a	# than of the Distribution itself. We provide aliases for them in
138	n/a	# Distribution as a convenience to the developer.
139	n/a	self.packages = []
140	n/a	self.package_data = {}
141	n/a	self.package_dir = None
142	n/a	self.py_modules = []
143	n/a	self.libraries = []
144	n/a	self.headers = []
145	n/a	self.ext_modules = []
146	n/a	self.ext_package = None
147	n/a	self.include_dirs = []
148	n/a	self.extra_path = None
149	n/a	self.scripts = []
150	n/a	self.data_files = {}
151	n/a	self.password = ''
152	n/a	self.use_2to3 = False
153	n/a	self.convert_2to3_doctests = []
154	n/a	self.extra_files = []
155	n/a
156	n/a	# And now initialize bookkeeping stuff that can't be supplied by
157	n/a	# the caller at all. 'command_obj' maps command names to
158	n/a	# Command instances -- that's how we enforce that every command
159	n/a	# class is a singleton.
160	n/a	self.command_obj = {}
161	n/a
162	n/a	# 'have_run' maps command names to boolean values; it keeps track
163	n/a	# of whether we have actually run a particular command, to make it
164	n/a	# cheap to "run" a command whenever we think we might need to -- if
165	n/a	# it's already been done, no need for expensive filesystem
166	n/a	# operations, we just check the 'have_run' dictionary and carry on.
167	n/a	# It's only safe to query 'have_run' for a command class that has
168	n/a	# been instantiated -- a false value will be inserted when the
169	n/a	# command object is created, and replaced with a true value when
170	n/a	# the command is successfully run. Thus it's probably best to use
171	n/a	# '.get()' rather than a straight lookup.
172	n/a	self.have_run = {}
173	n/a
174	n/a	# Now we'll use the attrs dictionary (ultimately, keyword args from
175	n/a	# the setup script) to possibly override any or all of these
176	n/a	# distribution options.
177	n/a
178	n/a	if attrs is not None:
179	n/a	# Pull out the set of command options and work on them
180	n/a	# specifically. Note that this order guarantees that aliased
181	n/a	# command options will override any supplied redundantly
182	n/a	# through the general options dictionary.
183	n/a	options = attrs.get('options')
184	n/a	if options is not None:
185	n/a	del attrs['options']
186	n/a	for command, cmd_options in options.items():
187	n/a	opt_dict = self.get_option_dict(command)
188	n/a	for opt, val in cmd_options.items():
189	n/a	opt_dict[opt] = ("setup script", val)
190	n/a
191	n/a	# Now work on the rest of the attributes. Any attribute that's
192	n/a	# not already defined is invalid!
193	n/a	for key, val in attrs.items():
194	n/a	if self.metadata.is_metadata_field(key):
195	n/a	self.metadata[key] = val
196	n/a	elif hasattr(self, key):
197	n/a	setattr(self, key, val)
198	n/a	else:
199	n/a	logger.warning(
200	n/a	'unknown argument given to Distribution: %r', key)
201	n/a
202	n/a	# no-user-cfg is handled before other command line args
203	n/a	# because other args override the config files, and this
204	n/a	# one is needed before we can load the config files.
205	n/a	# If attrs['script_args'] wasn't passed, assume false.
206	n/a	#
207	n/a	# This also make sure we just look at the global options
208	n/a	self.want_user_cfg = True
209	n/a
210	n/a	if self.script_args is not None:
211	n/a	for arg in self.script_args:
212	n/a	if not arg.startswith('-'):
213	n/a	break
214	n/a	if arg == '--no-user-cfg':
215	n/a	self.want_user_cfg = False
216	n/a	break
217	n/a
218	n/a	self.finalize_options()
219	n/a
220	n/a	def get_option_dict(self, command):
221	n/a	"""Get the option dictionary for a given command. If that
222	n/a	command's option dictionary hasn't been created yet, then create it
223	n/a	and return the new dictionary; otherwise, return the existing
224	n/a	option dictionary.
225	n/a	"""
226	n/a	d = self.command_options.get(command)
227	n/a	if d is None:
228	n/a	d = self.command_options[command] = {}
229	n/a	return d
230	n/a
231	n/a	def get_fullname(self, filesafe=False):
232	n/a	return self.metadata.get_fullname(filesafe)
233	n/a
234	n/a	def dump_option_dicts(self, header=None, commands=None, indent=""):
235	n/a	from pprint import pformat
236	n/a
237	n/a	if commands is None: # dump all command option dicts
238	n/a	commands = sorted(self.command_options)
239	n/a
240	n/a	if header is not None:
241	n/a	logger.info(indent + header)
242	n/a	indent = indent + " "
243	n/a
244	n/a	if not commands:
245	n/a	logger.info(indent + "no commands known yet")
246	n/a	return
247	n/a
248	n/a	for cmd_name in commands:
249	n/a	opt_dict = self.command_options.get(cmd_name)
250	n/a	if opt_dict is None:
251	n/a	logger.info(indent + "no option dict for %r command",
252	n/a	cmd_name)
253	n/a	else:
254	n/a	logger.info(indent + "option dict for %r command:", cmd_name)
255	n/a	out = pformat(opt_dict)
256	n/a	for line in out.split('\n'):
257	n/a	logger.info(indent + " " + line)
258	n/a
259	n/a	# -- Config file finding/parsing methods ---------------------------
260	n/a	# XXX to be removed
261	n/a	def parse_config_files(self, filenames=None):
262	n/a	return self.config.parse_config_files(filenames)
263	n/a
264	n/a	def find_config_files(self):
265	n/a	return self.config.find_config_files()
266	n/a
267	n/a	# -- Command-line parsing methods ----------------------------------
268	n/a
269	n/a	def parse_command_line(self):
270	n/a	"""Parse the setup script's command line, taken from the
271	n/a	'script_args' instance attribute (which defaults to 'sys.argv[1:]'
272	n/a	-- see 'setup()' in run.py). This list is first processed for
273	n/a	"global options" -- options that set attributes of the Distribution
274	n/a	instance. Then, it is alternately scanned for Packaging commands
275	n/a	and options for that command. Each new command terminates the
276	n/a	options for the previous command. The allowed options for a
277	n/a	command are determined by the 'user_options' attribute of the
278	n/a	command class -- thus, we have to be able to load command classes
279	n/a	in order to parse the command line. Any error in that 'options'
280	n/a	attribute raises PackagingGetoptError; any error on the
281	n/a	command line raises PackagingArgError. If no Packaging commands
282	n/a	were found on the command line, raises PackagingArgError. Return
283	n/a	true if command line was successfully parsed and we should carry
284	n/a	on with executing commands; false if no errors but we shouldn't
285	n/a	execute commands (currently, this only happens if user asks for
286	n/a	help).
287	n/a	"""
288	n/a	#
289	n/a	# We now have enough information to show the Macintosh dialog
290	n/a	# that allows the user to interactively specify the "command line".
291	n/a	#
292	n/a	toplevel_options = self._get_toplevel_options()
293	n/a
294	n/a	# We have to parse the command line a bit at a time -- global
295	n/a	# options, then the first command, then its options, and so on --
296	n/a	# because each command will be handled by a different class, and
297	n/a	# the options that are valid for a particular class aren't known
298	n/a	# until we have loaded the command class, which doesn't happen
299	n/a	# until we know what the command is.
300	n/a
301	n/a	self.commands = []
302	n/a	parser = FancyGetopt(toplevel_options + self.display_options)
303	n/a	parser.set_negative_aliases(self.negative_opt)
304	n/a	args = parser.getopt(args=self.script_args, object=self)
305	n/a	option_order = parser.get_option_order()
306	n/a
307	n/a	# for display options we return immediately
308	n/a	if self.handle_display_options(option_order):
309	n/a	return
310	n/a
311	n/a	while args:
312	n/a	args = self._parse_command_opts(parser, args)
313	n/a	if args is None: # user asked for help (and got it)
314	n/a	return
315	n/a
316	n/a	# Handle the cases of --help as a "global" option, ie.
317	n/a	# "pysetup run --help" and "pysetup run --help command ...". For the
318	n/a	# former, we show global options (--dry-run, etc.)
319	n/a	# and display-only options (--name, --version, etc.); for the
320	n/a	# latter, we omit the display-only options and show help for
321	n/a	# each command listed on the command line.
322	n/a	if self.help:
323	n/a	self._show_help(parser,
324	n/a	display_options=len(self.commands) == 0,
325	n/a	commands=self.commands)
326	n/a	return
327	n/a
328	n/a	return True
329	n/a
330	n/a	def _get_toplevel_options(self):
331	n/a	"""Return the non-display options recognized at the top level.
332	n/a
333	n/a	This includes options that are recognized only at the top
334	n/a	level as well as options recognized for commands.
335	n/a	"""
336	n/a	return self.global_options
337	n/a
338	n/a	def _parse_command_opts(self, parser, args):
339	n/a	"""Parse the command-line options for a single command.
340	n/a	'parser' must be a FancyGetopt instance; 'args' must be the list
341	n/a	of arguments, starting with the current command (whose options
342	n/a	we are about to parse). Returns a new version of 'args' with
343	n/a	the next command at the front of the list; will be the empty
344	n/a	list if there are no more commands on the command line. Returns
345	n/a	None if the user asked for help on this command.
346	n/a	"""
347	n/a	# Pull the current command from the head of the command line
348	n/a	command = args[0]
349	n/a	if not command_re.match(command):
350	n/a	raise SystemExit("invalid command name %r" % command)
351	n/a	self.commands.append(command)
352	n/a
353	n/a	# Dig up the command class that implements this command, so we
354	n/a	# 1) know that it's a valid command, and 2) know which options
355	n/a	# it takes.
356	n/a	try:
357	n/a	cmd_class = get_command_class(command)
358	n/a	except PackagingModuleError as msg:
359	n/a	raise PackagingArgError(msg)
360	n/a
361	n/a	# XXX We want to push this in packaging.command
362	n/a	#
363	n/a	# Require that the command class be derived from Command -- want
364	n/a	# to be sure that the basic "command" interface is implemented.
365	n/a	for meth in ('initialize_options', 'finalize_options', 'run'):
366	n/a	if hasattr(cmd_class, meth):
367	n/a	continue
368	n/a	raise PackagingClassError(
369	n/a	'command %r must implement %r' % (cmd_class, meth))
370	n/a
371	n/a	# Also make sure that the command object provides a list of its
372	n/a	# known options.
373	n/a	if not (hasattr(cmd_class, 'user_options') and
374	n/a	isinstance(cmd_class.user_options, list)):
375	n/a	raise PackagingClassError(
376	n/a	"command class %s must provide "
377	n/a	"'user_options' attribute (a list of tuples)" % cmd_class)
378	n/a
379	n/a	# If the command class has a list of negative alias options,
380	n/a	# merge it in with the global negative aliases.
381	n/a	negative_opt = self.negative_opt
382	n/a	if hasattr(cmd_class, 'negative_opt'):
383	n/a	negative_opt = negative_opt.copy()
384	n/a	negative_opt.update(cmd_class.negative_opt)
385	n/a
386	n/a	# Check for help_options in command class. They have a different
387	n/a	# format (tuple of four) so we need to preprocess them here.
388	n/a	if (hasattr(cmd_class, 'help_options') and
389	n/a	isinstance(cmd_class.help_options, list)):
390	n/a	help_options = cmd_class.help_options[:]
391	n/a	else:
392	n/a	help_options = []
393	n/a
394	n/a	# All commands support the global options too, just by adding
395	n/a	# in 'global_options'.
396	n/a	parser.set_option_table(self.global_options +
397	n/a	cmd_class.user_options +
398	n/a	help_options)
399	n/a	parser.set_negative_aliases(negative_opt)
400	n/a	args, opts = parser.getopt(args[1:])
401	n/a	if hasattr(opts, 'help') and opts.help:
402	n/a	self._show_help(parser, display_options=False,
403	n/a	commands=[cmd_class])
404	n/a	return
405	n/a
406	n/a	if (hasattr(cmd_class, 'help_options') and
407	n/a	isinstance(cmd_class.help_options, list)):
408	n/a	help_option_found = False
409	n/a	for help_option, short, desc, func in cmd_class.help_options:
410	n/a	if hasattr(opts, help_option.replace('-', '_')):
411	n/a	help_option_found = True
412	n/a	if callable(func):
413	n/a	func()
414	n/a	else:
415	n/a	raise PackagingClassError(
416	n/a	"invalid help function %r for help option %r: "
417	n/a	"must be a callable object (function, etc.)"
418	n/a	% (func, help_option))
419	n/a
420	n/a	if help_option_found:
421	n/a	return
422	n/a
423	n/a	# Put the options from the command line into their official
424	n/a	# holding pen, the 'command_options' dictionary.
425	n/a	opt_dict = self.get_option_dict(command)
426	n/a	for name, value in vars(opts).items():
427	n/a	opt_dict[name] = ("command line", value)
428	n/a
429	n/a	return args
430	n/a
431	n/a	def finalize_options(self):
432	n/a	"""Set final values for all the options on the Distribution
433	n/a	instance, analogous to the .finalize_options() method of Command
434	n/a	objects.
435	n/a	"""
436	n/a	if getattr(self, 'convert_2to3_doctests', None):
437	n/a	self.convert_2to3_doctests = [os.path.join(p)
438	n/a	for p in self.convert_2to3_doctests]
439	n/a	else:
440	n/a	self.convert_2to3_doctests = []
441	n/a
442	n/a	def _show_help(self, parser, global_options=True, display_options=True,
443	n/a	commands=[]):
444	n/a	"""Show help for the setup script command line in the form of
445	n/a	several lists of command-line options. 'parser' should be a
446	n/a	FancyGetopt instance; do not expect it to be returned in the
447	n/a	same state, as its option table will be reset to make it
448	n/a	generate the correct help text.
449	n/a
450	n/a	If 'global_options' is true, lists the global options:
451	n/a	--dry-run, etc. If 'display_options' is true, lists
452	n/a	the "display-only" options: --help-commands. Finally,
453	n/a	lists per-command help for every command name or command class
454	n/a	in 'commands'.
455	n/a	"""
456	n/a	if global_options:
457	n/a	if display_options:
458	n/a	options = self._get_toplevel_options()
459	n/a	else:
460	n/a	options = self.global_options
461	n/a	parser.set_option_table(options)
462	n/a	parser.print_help(self.common_usage + "\nGlobal options:")
463	n/a	print()
464	n/a
465	n/a	if display_options:
466	n/a	parser.set_option_table(self.display_options)
467	n/a	parser.print_help(
468	n/a	"Information display options (just display " +
469	n/a	"information, ignore any commands)")
470	n/a	print()
471	n/a
472	n/a	for command in self.commands:
473	n/a	if isinstance(command, type) and issubclass(command, Command):
474	n/a	cls = command
475	n/a	else:
476	n/a	cls = get_command_class(command)
477	n/a	if (hasattr(cls, 'help_options') and
478	n/a	isinstance(cls.help_options, list)):
479	n/a	parser.set_option_table(cls.user_options + cls.help_options)
480	n/a	else:
481	n/a	parser.set_option_table(cls.user_options)
482	n/a	parser.print_help("Options for %r command:" % cls.__name__)
483	n/a	print()
484	n/a
485	n/a	print(gen_usage(self.script_name))
486	n/a
487	n/a	def handle_display_options(self, option_order):
488	n/a	"""If there were any non-global "display-only" options
489	n/a	(--help-commands) on the command line, display the requested info and
490	n/a	return true; else return false.
491	n/a	"""
492	n/a	# User just wants a list of commands -- we'll print it out and stop
493	n/a	# processing now (ie. if they ran "setup --help-commands foo bar",
494	n/a	# we ignore "foo bar").
495	n/a	if self.help_commands:
496	n/a	self.print_commands()
497	n/a	print()
498	n/a	print(gen_usage(self.script_name))
499	n/a	return True
500	n/a
501	n/a	# If user supplied any of the "display metadata" options, then
502	n/a	# display that metadata in the order in which the user supplied the
503	n/a	# metadata options.
504	n/a	any_display_options = False
505	n/a	is_display_option = set()
506	n/a	for option in self.display_options:
507	n/a	is_display_option.add(option[0])
508	n/a
509	n/a	for opt, val in option_order:
510	n/a	if val and opt in is_display_option:
511	n/a	opt = opt.replace('-', '_')
512	n/a	value = self.metadata[opt]
513	n/a	if opt in ('keywords', 'platform'):
514	n/a	print(','.join(value))
515	n/a	elif opt in ('classifier', 'provides', 'requires',
516	n/a	'obsoletes'):
517	n/a	print('\n'.join(value))
518	n/a	else:
519	n/a	print(value)
520	n/a	any_display_options = True
521	n/a
522	n/a	return any_display_options
523	n/a
524	n/a	def print_command_list(self, commands, header, max_length):
525	n/a	"""Print a subset of the list of all commands -- used by
526	n/a	'print_commands()'.
527	n/a	"""
528	n/a	print(header + ":")
529	n/a
530	n/a	for cmd in commands:
531	n/a	cls = self.cmdclass.get(cmd) or get_command_class(cmd)
532	n/a	description = getattr(cls, 'description',
533	n/a	'(no description available)')
534	n/a
535	n/a	print(" %-*s %s" % (max_length, cmd, description))
536	n/a
537	n/a	def _get_command_groups(self):
538	n/a	"""Helper function to retrieve all the command class names divided
539	n/a	into standard commands (listed in
540	n/a	packaging.command.STANDARD_COMMANDS) and extra commands (given in
541	n/a	self.cmdclass and not standard commands).
542	n/a	"""
543	n/a	extra_commands = [cmd for cmd in self.cmdclass
544	n/a	if cmd not in STANDARD_COMMANDS]
545	n/a	return STANDARD_COMMANDS, extra_commands
546	n/a
547	n/a	def print_commands(self):
548	n/a	"""Print out a help message listing all available commands with a
549	n/a	description of each. The list is divided into standard commands
550	n/a	(listed in packaging.command.STANDARD_COMMANDS) and extra commands
551	n/a	(given in self.cmdclass and not standard commands). The
552	n/a	descriptions come from the command class attribute
553	n/a	'description'.
554	n/a	"""
555	n/a	std_commands, extra_commands = self._get_command_groups()
556	n/a	max_length = 0
557	n/a	for cmd in (std_commands + extra_commands):
558	n/a	if len(cmd) > max_length:
559	n/a	max_length = len(cmd)
560	n/a
561	n/a	self.print_command_list(std_commands,
562	n/a	"Standard commands",
563	n/a	max_length)
564	n/a	if extra_commands:
565	n/a	print()
566	n/a	self.print_command_list(extra_commands,
567	n/a	"Extra commands",
568	n/a	max_length)
569	n/a
570	n/a	# -- Command class/object methods ----------------------------------
571	n/a
572	n/a	def get_command_obj(self, command, create=True):
573	n/a	"""Return the command object for 'command'. Normally this object
574	n/a	is cached on a previous call to 'get_command_obj()'; if no command
575	n/a	object for 'command' is in the cache, then we either create and
576	n/a	return it (if 'create' is true) or return None.
577	n/a	"""
578	n/a	cmd_obj = self.command_obj.get(command)
579	n/a	if not cmd_obj and create:
580	n/a	logger.debug("Distribution.get_command_obj(): "
581	n/a	"creating %r command object", command)
582	n/a
583	n/a	cls = get_command_class(command)
584	n/a	cmd_obj = self.command_obj[command] = cls(self)
585	n/a	self.have_run[command] = 0
586	n/a
587	n/a	# Set any options that were supplied in config files or on the
588	n/a	# command line. (XXX support for error reporting is suboptimal
589	n/a	# here: errors aren't reported until finalize_options is called,
590	n/a	# which means we won't report the source of the error.)
591	n/a	options = self.command_options.get(command)
592	n/a	if options:
593	n/a	self._set_command_options(cmd_obj, options)
594	n/a
595	n/a	return cmd_obj
596	n/a
597	n/a	def _set_command_options(self, command_obj, option_dict=None):
598	n/a	"""Set the options for 'command_obj' from 'option_dict'. Basically
599	n/a	this means copying elements of a dictionary ('option_dict') to
600	n/a	attributes of an instance ('command').
601	n/a
602	n/a	'command_obj' must be a Command instance. If 'option_dict' is not
603	n/a	supplied, uses the standard option dictionary for this command
604	n/a	(from 'self.command_options').
605	n/a	"""
606	n/a	command_name = command_obj.get_command_name()
607	n/a	if option_dict is None:
608	n/a	option_dict = self.get_option_dict(command_name)
609	n/a
610	n/a	logger.debug(" setting options for %r command:", command_name)
611	n/a
612	n/a	for option, (source, value) in option_dict.items():
613	n/a	logger.debug(" %s = %s (from %s)", option, value, source)
614	n/a	try:
615	n/a	bool_opts = [x.replace('-', '_')
616	n/a	for x in command_obj.boolean_options]
617	n/a	except AttributeError:
618	n/a	bool_opts = []
619	n/a	try:
620	n/a	neg_opt = command_obj.negative_opt
621	n/a	except AttributeError:
622	n/a	neg_opt = {}
623	n/a
624	n/a	try:
625	n/a	is_string = isinstance(value, str)
626	n/a	if option in neg_opt and is_string:
627	n/a	setattr(command_obj, neg_opt[option], not strtobool(value))
628	n/a	elif option in bool_opts and is_string:
629	n/a	setattr(command_obj, option, strtobool(value))
630	n/a	elif hasattr(command_obj, option):
631	n/a	setattr(command_obj, option, value)
632	n/a	else:
633	n/a	raise PackagingOptionError(
634	n/a	"error in %s: command %r has no such option %r" %
635	n/a	(source, command_name, option))
636	n/a	except ValueError as msg:
637	n/a	raise PackagingOptionError(msg)
638	n/a
639	n/a	def reinitialize_command(self, command, reinit_subcommands=False):
640	n/a	"""Reinitializes a command to the state it was in when first
641	n/a	returned by 'get_command_obj()': i.e., initialized but not yet
642	n/a	finalized. This provides the opportunity to sneak option
643	n/a	values in programmatically, overriding or supplementing
644	n/a	user-supplied values from the config files and command line.
645	n/a	You'll have to re-finalize the command object (by calling
646	n/a	'finalize_options()' or 'ensure_finalized()') before using it for
647	n/a	real.
648	n/a
649	n/a	'command' should be a command name (string) or command object. If
650	n/a	'reinit_subcommands' is true, also reinitializes the command's
651	n/a	sub-commands, as declared by the 'sub_commands' class attribute (if
652	n/a	it has one). See the "install_dist" command for an example. Only
653	n/a	reinitializes the sub-commands that actually matter, i.e. those
654	n/a	whose test predicate return true.
655	n/a
656	n/a	Returns the reinitialized command object. It will be the same
657	n/a	object as the one stored in the self.command_obj attribute.
658	n/a	"""
659	n/a	if not isinstance(command, Command):
660	n/a	command_name = command
661	n/a	command = self.get_command_obj(command_name)
662	n/a	else:
663	n/a	command_name = command.get_command_name()
664	n/a
665	n/a	if not command.finalized:
666	n/a	return command
667	n/a
668	n/a	command.initialize_options()
669	n/a	self.have_run[command_name] = 0
670	n/a	command.finalized = False
671	n/a	self._set_command_options(command)
672	n/a
673	n/a	if reinit_subcommands:
674	n/a	for sub in command.get_sub_commands():
675	n/a	self.reinitialize_command(sub, reinit_subcommands)
676	n/a
677	n/a	return command
678	n/a
679	n/a	# -- Methods that operate on the Distribution ----------------------
680	n/a
681	n/a	def run_commands(self):
682	n/a	"""Run each command that was seen on the setup script command line.
683	n/a	Uses the list of commands found and cache of command objects
684	n/a	created by 'get_command_obj()'.
685	n/a	"""
686	n/a	for cmd in self.commands:
687	n/a	self.run_command(cmd)
688	n/a
689	n/a	# -- Methods that operate on its Commands --------------------------
690	n/a
691	n/a	def run_command(self, command, options=None):
692	n/a	"""Do whatever it takes to run a command (including nothing at all,
693	n/a	if the command has already been run). Specifically: if we have
694	n/a	already created and run the command named by 'command', return
695	n/a	silently without doing anything. If the command named by 'command'
696	n/a	doesn't even have a command object yet, create one. Then invoke
697	n/a	'run()' on that command object (or an existing one).
698	n/a	"""
699	n/a	# Already been here, done that? then return silently.
700	n/a	if self.have_run.get(command):
701	n/a	return
702	n/a
703	n/a	if options is not None:
704	n/a	self.command_options[command] = options
705	n/a
706	n/a	cmd_obj = self.get_command_obj(command)
707	n/a	cmd_obj.ensure_finalized()
708	n/a	self.run_command_hooks(cmd_obj, 'pre_hook')
709	n/a	logger.info("running %s", command)
710	n/a	cmd_obj.run()
711	n/a	self.run_command_hooks(cmd_obj, 'post_hook')
712	n/a	self.have_run[command] = 1
713	n/a
714	n/a	def run_command_hooks(self, cmd_obj, hook_kind):
715	n/a	"""Run hooks registered for that command and phase.
716	n/a
717	n/a	cmd_obj is a finalized command object; hook_kind is either
718	n/a	'pre_hook' or 'post_hook'.
719	n/a	"""
720	n/a	if hook_kind not in ('pre_hook', 'post_hook'):
721	n/a	raise ValueError('invalid hook kind: %r' % hook_kind)
722	n/a
723	n/a	hooks = getattr(cmd_obj, hook_kind, None)
724	n/a
725	n/a	if hooks is None:
726	n/a	return
727	n/a
728	n/a	for hook in hooks.values():
729	n/a	if isinstance(hook, str):
730	n/a	try:
731	n/a	hook_obj = resolve_name(hook)
732	n/a	except ImportError as e:
733	n/a	raise PackagingModuleError(e)
734	n/a	else:
735	n/a	hook_obj = hook
736	n/a
737	n/a	if not callable(hook_obj):
738	n/a	raise PackagingOptionError('hook %r is not callable' % hook)
739	n/a
740	n/a	logger.info('running %s %s for command %s',
741	n/a	hook_kind, hook, cmd_obj.get_command_name())
742	n/a	hook_obj(cmd_obj)
743	n/a
744	n/a	# -- Distribution query methods ------------------------------------
745	n/a	def has_pure_modules(self):
746	n/a	return len(self.packages or self.py_modules or []) > 0
747	n/a
748	n/a	def has_ext_modules(self):
749	n/a	return self.ext_modules and len(self.ext_modules) > 0
750	n/a
751	n/a	def has_c_libraries(self):
752	n/a	return self.libraries and len(self.libraries) > 0
753	n/a
754	n/a	def has_modules(self):
755	n/a	return self.has_pure_modules() or self.has_ext_modules()
756	n/a
757	n/a	def has_headers(self):
758	n/a	return self.headers and len(self.headers) > 0
759	n/a
760	n/a	def has_scripts(self):
761	n/a	return self.scripts and len(self.scripts) > 0
762	n/a
763	n/a	def has_data_files(self):
764	n/a	return self.data_files and len(self.data_files) > 0
765	n/a
766	n/a	def is_pure(self):
767	n/a	return (self.has_pure_modules() and
768	n/a	not self.has_ext_modules() and
769	n/a	not self.has_c_libraries())