ยปCore Development>Code coverage>Lib/distutils/dist.py

Python code coverage for Lib/distutils/dist.py

#countcontent
1n/a"""distutils.dist
2n/a
3n/aProvides the Distribution class, which represents the module distribution
4n/abeing built/installed/distributed.
5n/a"""
6n/a
7n/aimport sys
8n/aimport os
9n/aimport re
10n/afrom email import message_from_file
11n/a
12n/atry:
13n/a import warnings
14n/aexcept ImportError:
15n/a warnings = None
16n/a
17n/afrom distutils.errors import *
18n/afrom distutils.fancy_getopt import FancyGetopt, translate_longopt
19n/afrom distutils.util import check_environ, strtobool, rfc822_escape
20n/afrom distutils import log
21n/afrom distutils.debug import DEBUG
22n/a
23n/a# Regex to define acceptable Distutils command names. This is not *quite*
24n/a# the same as a Python NAME -- I don't allow leading underscores. The fact
25n/a# that they're very similar is no coincidence; the default naming scheme is
26n/a# to look for a Python module named after the command.
27n/acommand_re = re.compile(r'^[a-zA-Z]([a-zA-Z0-9_]*)$')
28n/a
29n/a
30n/aclass Distribution:
31n/a """The core of the Distutils. Most of the work hiding behind 'setup'
32n/a is really done within a Distribution instance, which farms the work out
33n/a to the Distutils commands specified on the command line.
34n/a
35n/a Setup scripts will almost never instantiate Distribution directly,
36n/a unless the 'setup()' function is totally inadequate to their needs.
37n/a However, it is conceivable that a setup script might wish to subclass
38n/a Distribution for some specialized purpose, and then pass the subclass
39n/a to 'setup()' as the 'distclass' keyword argument. If so, it is
40n/a necessary to respect the expectations that 'setup' has of Distribution.
41n/a See the code for 'setup()', in core.py, for details.
42n/a """
43n/a
44n/a # 'global_options' describes the command-line options that may be
45n/a # supplied to the setup script prior to any actual commands.
46n/a # Eg. "./setup.py -n" or "./setup.py --quiet" both take advantage of
47n/a # these global options. This list should be kept to a bare minimum,
48n/a # since every global option is also valid as a command option -- and we
49n/a # don't want to pollute the commands with too many options that they
50n/a # have minimal control over.
51n/a # The fourth entry for verbose means that it can be repeated.
52n/a global_options = [
53n/a ('verbose', 'v', "run verbosely (default)", 1),
54n/a ('quiet', 'q', "run quietly (turns verbosity off)"),
55n/a ('dry-run', 'n', "don't actually do anything"),
56n/a ('help', 'h', "show detailed help message"),
57n/a ('no-user-cfg', None,
58n/a 'ignore pydistutils.cfg in your home directory'),
59n/a ]
60n/a
61n/a # 'common_usage' is a short (2-3 line) string describing the common
62n/a # usage of the setup script.
63n/a common_usage = """\
64n/aCommon commands: (see '--help-commands' for more)
65n/a
66n/a setup.py build will build the package underneath 'build/'
67n/a setup.py install will install the package
68n/a"""
69n/a
70n/a # options that are not propagated to the commands
71n/a display_options = [
72n/a ('help-commands', None,
73n/a "list all available commands"),
74n/a ('name', None,
75n/a "print package name"),
76n/a ('version', 'V',
77n/a "print package version"),
78n/a ('fullname', None,
79n/a "print <package name>-<version>"),
80n/a ('author', None,
81n/a "print the author's name"),
82n/a ('author-email', None,
83n/a "print the author's email address"),
84n/a ('maintainer', None,
85n/a "print the maintainer's name"),
86n/a ('maintainer-email', None,
87n/a "print the maintainer's email address"),
88n/a ('contact', None,
89n/a "print the maintainer's name if known, else the author's"),
90n/a ('contact-email', None,
91n/a "print the maintainer's email address if known, else the author's"),
92n/a ('url', None,
93n/a "print the URL for this package"),
94n/a ('license', None,
95n/a "print the license of the package"),
96n/a ('licence', None,
97n/a "alias for --license"),
98n/a ('description', None,
99n/a "print the package description"),
100n/a ('long-description', None,
101n/a "print the long package description"),
102n/a ('platforms', None,
103n/a "print the list of platforms"),
104n/a ('classifiers', None,
105n/a "print the list of classifiers"),
106n/a ('keywords', None,
107n/a "print the list of keywords"),
108n/a ('provides', None,
109n/a "print the list of packages/modules provided"),
110n/a ('requires', None,
111n/a "print the list of packages/modules required"),
112n/a ('obsoletes', None,
113n/a "print the list of packages/modules made obsolete")
114n/a ]
115n/a display_option_names = [translate_longopt(x[0]) for x in display_options]
116n/a
117n/a # negative options are options that exclude other options
118n/a negative_opt = {'quiet': 'verbose'}
119n/a
120n/a # -- Creation/initialization methods -------------------------------
121n/a
122n/a def __init__(self, attrs=None):
123n/a """Construct a new Distribution instance: initialize all the
124n/a attributes of a Distribution, and then use 'attrs' (a dictionary
125n/a mapping attribute names to values) to assign some of those
126n/a attributes their "real" values. (Any attributes not mentioned in
127n/a 'attrs' will be assigned to some null value: 0, None, an empty list
128n/a or dictionary, etc.) Most importantly, initialize the
129n/a 'command_obj' attribute to the empty dictionary; this will be
130n/a filled in with real command objects by 'parse_command_line()'.
131n/a """
132n/a
133n/a # Default values for our command-line options
134n/a self.verbose = 1
135n/a self.dry_run = 0
136n/a self.help = 0
137n/a for attr in self.display_option_names:
138n/a setattr(self, attr, 0)
139n/a
140n/a # Store the distribution meta-data (name, version, author, and so
141n/a # forth) in a separate object -- we're getting to have enough
142n/a # information here (and enough command-line options) that it's
143n/a # worth it. Also delegate 'get_XXX()' methods to the 'metadata'
144n/a # object in a sneaky and underhanded (but efficient!) way.
145n/a self.metadata = DistributionMetadata()
146n/a for basename in self.metadata._METHOD_BASENAMES:
147n/a method_name = "get_" + basename
148n/a setattr(self, method_name, getattr(self.metadata, method_name))
149n/a
150n/a # 'cmdclass' maps command names to class objects, so we
151n/a # can 1) quickly figure out which class to instantiate when
152n/a # we need to create a new command object, and 2) have a way
153n/a # for the setup script to override command classes
154n/a self.cmdclass = {}
155n/a
156n/a # 'command_packages' is a list of packages in which commands
157n/a # are searched for. The factory for command 'foo' is expected
158n/a # to be named 'foo' in the module 'foo' in one of the packages
159n/a # named here. This list is searched from the left; an error
160n/a # is raised if no named package provides the command being
161n/a # searched for. (Always access using get_command_packages().)
162n/a self.command_packages = None
163n/a
164n/a # 'script_name' and 'script_args' are usually set to sys.argv[0]
165n/a # and sys.argv[1:], but they can be overridden when the caller is
166n/a # not necessarily a setup script run from the command-line.
167n/a self.script_name = None
168n/a self.script_args = None
169n/a
170n/a # 'command_options' is where we store command options between
171n/a # parsing them (from config files, the command-line, etc.) and when
172n/a # they are actually needed -- ie. when the command in question is
173n/a # instantiated. It is a dictionary of dictionaries of 2-tuples:
174n/a # command_options = { command_name : { option : (source, value) } }
175n/a self.command_options = {}
176n/a
177n/a # 'dist_files' is the list of (command, pyversion, file) that
178n/a # have been created by any dist commands run so far. This is
179n/a # filled regardless of whether the run is dry or not. pyversion
180n/a # gives sysconfig.get_python_version() if the dist file is
181n/a # specific to a Python version, 'any' if it is good for all
182n/a # Python versions on the target platform, and '' for a source
183n/a # file. pyversion should not be used to specify minimum or
184n/a # maximum required Python versions; use the metainfo for that
185n/a # instead.
186n/a self.dist_files = []
187n/a
188n/a # These options are really the business of various commands, rather
189n/a # than of the Distribution itself. We provide aliases for them in
190n/a # Distribution as a convenience to the developer.
191n/a self.packages = None
192n/a self.package_data = {}
193n/a self.package_dir = None
194n/a self.py_modules = None
195n/a self.libraries = None
196n/a self.headers = None
197n/a self.ext_modules = None
198n/a self.ext_package = None
199n/a self.include_dirs = None
200n/a self.extra_path = None
201n/a self.scripts = None
202n/a self.data_files = None
203n/a self.password = ''
204n/a
205n/a # And now initialize bookkeeping stuff that can't be supplied by
206n/a # the caller at all. 'command_obj' maps command names to
207n/a # Command instances -- that's how we enforce that every command
208n/a # class is a singleton.
209n/a self.command_obj = {}
210n/a
211n/a # 'have_run' maps command names to boolean values; it keeps track
212n/a # of whether we have actually run a particular command, to make it
213n/a # cheap to "run" a command whenever we think we might need to -- if
214n/a # it's already been done, no need for expensive filesystem
215n/a # operations, we just check the 'have_run' dictionary and carry on.
216n/a # It's only safe to query 'have_run' for a command class that has
217n/a # been instantiated -- a false value will be inserted when the
218n/a # command object is created, and replaced with a true value when
219n/a # the command is successfully run. Thus it's probably best to use
220n/a # '.get()' rather than a straight lookup.
221n/a self.have_run = {}
222n/a
223n/a # Now we'll use the attrs dictionary (ultimately, keyword args from
224n/a # the setup script) to possibly override any or all of these
225n/a # distribution options.
226n/a
227n/a if attrs:
228n/a # Pull out the set of command options and work on them
229n/a # specifically. Note that this order guarantees that aliased
230n/a # command options will override any supplied redundantly
231n/a # through the general options dictionary.
232n/a options = attrs.get('options')
233n/a if options is not None:
234n/a del attrs['options']
235n/a for (command, cmd_options) in options.items():
236n/a opt_dict = self.get_option_dict(command)
237n/a for (opt, val) in cmd_options.items():
238n/a opt_dict[opt] = ("setup script", val)
239n/a
240n/a if 'licence' in attrs:
241n/a attrs['license'] = attrs['licence']
242n/a del attrs['licence']
243n/a msg = "'licence' distribution option is deprecated; use 'license'"
244n/a if warnings is not None:
245n/a warnings.warn(msg)
246n/a else:
247n/a sys.stderr.write(msg + "\n")
248n/a
249n/a # Now work on the rest of the attributes. Any attribute that's
250n/a # not already defined is invalid!
251n/a for (key, val) in attrs.items():
252n/a if hasattr(self.metadata, "set_" + key):
253n/a getattr(self.metadata, "set_" + key)(val)
254n/a elif hasattr(self.metadata, key):
255n/a setattr(self.metadata, key, val)
256n/a elif hasattr(self, key):
257n/a setattr(self, key, val)
258n/a else:
259n/a msg = "Unknown distribution option: %s" % repr(key)
260n/a if warnings is not None:
261n/a warnings.warn(msg)
262n/a else:
263n/a sys.stderr.write(msg + "\n")
264n/a
265n/a # no-user-cfg is handled before other command line args
266n/a # because other args override the config files, and this
267n/a # one is needed before we can load the config files.
268n/a # If attrs['script_args'] wasn't passed, assume false.
269n/a #
270n/a # This also make sure we just look at the global options
271n/a self.want_user_cfg = True
272n/a
273n/a if self.script_args is not None:
274n/a for arg in self.script_args:
275n/a if not arg.startswith('-'):
276n/a break
277n/a if arg == '--no-user-cfg':
278n/a self.want_user_cfg = False
279n/a break
280n/a
281n/a self.finalize_options()
282n/a
283n/a def get_option_dict(self, command):
284n/a """Get the option dictionary for a given command. If that
285n/a command's option dictionary hasn't been created yet, then create it
286n/a and return the new dictionary; otherwise, return the existing
287n/a option dictionary.
288n/a """
289n/a dict = self.command_options.get(command)
290n/a if dict is None:
291n/a dict = self.command_options[command] = {}
292n/a return dict
293n/a
294n/a def dump_option_dicts(self, header=None, commands=None, indent=""):
295n/a from pprint import pformat
296n/a
297n/a if commands is None: # dump all command option dicts
298n/a commands = sorted(self.command_options.keys())
299n/a
300n/a if header is not None:
301n/a self.announce(indent + header)
302n/a indent = indent + " "
303n/a
304n/a if not commands:
305n/a self.announce(indent + "no commands known yet")
306n/a return
307n/a
308n/a for cmd_name in commands:
309n/a opt_dict = self.command_options.get(cmd_name)
310n/a if opt_dict is None:
311n/a self.announce(indent +
312n/a "no option dict for '%s' command" % cmd_name)
313n/a else:
314n/a self.announce(indent +
315n/a "option dict for '%s' command:" % cmd_name)
316n/a out = pformat(opt_dict)
317n/a for line in out.split('\n'):
318n/a self.announce(indent + " " + line)
319n/a
320n/a # -- Config file finding/parsing methods ---------------------------
321n/a
322n/a def find_config_files(self):
323n/a """Find as many configuration files as should be processed for this
324n/a platform, and return a list of filenames in the order in which they
325n/a should be parsed. The filenames returned are guaranteed to exist
326n/a (modulo nasty race conditions).
327n/a
328n/a There are three possible config files: distutils.cfg in the
329n/a Distutils installation directory (ie. where the top-level
330n/a Distutils __inst__.py file lives), a file in the user's home
331n/a directory named .pydistutils.cfg on Unix and pydistutils.cfg
332n/a on Windows/Mac; and setup.cfg in the current directory.
333n/a
334n/a The file in the user's home directory can be disabled with the
335n/a --no-user-cfg option.
336n/a """
337n/a files = []
338n/a check_environ()
339n/a
340n/a # Where to look for the system-wide Distutils config file
341n/a sys_dir = os.path.dirname(sys.modules['distutils'].__file__)
342n/a
343n/a # Look for the system config file
344n/a sys_file = os.path.join(sys_dir, "distutils.cfg")
345n/a if os.path.isfile(sys_file):
346n/a files.append(sys_file)
347n/a
348n/a # What to call the per-user config file
349n/a if os.name == 'posix':
350n/a user_filename = ".pydistutils.cfg"
351n/a else:
352n/a user_filename = "pydistutils.cfg"
353n/a
354n/a # And look for the user config file
355n/a if self.want_user_cfg:
356n/a user_file = os.path.join(os.path.expanduser('~'), user_filename)
357n/a if os.path.isfile(user_file):
358n/a files.append(user_file)
359n/a
360n/a # All platforms support local setup.cfg
361n/a local_file = "setup.cfg"
362n/a if os.path.isfile(local_file):
363n/a files.append(local_file)
364n/a
365n/a if DEBUG:
366n/a self.announce("using config files: %s" % ', '.join(files))
367n/a
368n/a return files
369n/a
370n/a def parse_config_files(self, filenames=None):
371n/a from configparser import ConfigParser
372n/a
373n/a # Ignore install directory options if we have a venv
374n/a if sys.prefix != sys.base_prefix:
375n/a ignore_options = [
376n/a 'install-base', 'install-platbase', 'install-lib',
377n/a 'install-platlib', 'install-purelib', 'install-headers',
378n/a 'install-scripts', 'install-data', 'prefix', 'exec-prefix',
379n/a 'home', 'user', 'root']
380n/a else:
381n/a ignore_options = []
382n/a
383n/a ignore_options = frozenset(ignore_options)
384n/a
385n/a if filenames is None:
386n/a filenames = self.find_config_files()
387n/a
388n/a if DEBUG:
389n/a self.announce("Distribution.parse_config_files():")
390n/a
391n/a parser = ConfigParser()
392n/a for filename in filenames:
393n/a if DEBUG:
394n/a self.announce(" reading %s" % filename)
395n/a parser.read(filename)
396n/a for section in parser.sections():
397n/a options = parser.options(section)
398n/a opt_dict = self.get_option_dict(section)
399n/a
400n/a for opt in options:
401n/a if opt != '__name__' and opt not in ignore_options:
402n/a val = parser.get(section,opt)
403n/a opt = opt.replace('-', '_')
404n/a opt_dict[opt] = (filename, val)
405n/a
406n/a # Make the ConfigParser forget everything (so we retain
407n/a # the original filenames that options come from)
408n/a parser.__init__()
409n/a
410n/a # If there was a "global" section in the config file, use it
411n/a # to set Distribution options.
412n/a
413n/a if 'global' in self.command_options:
414n/a for (opt, (src, val)) in self.command_options['global'].items():
415n/a alias = self.negative_opt.get(opt)
416n/a try:
417n/a if alias:
418n/a setattr(self, alias, not strtobool(val))
419n/a elif opt in ('verbose', 'dry_run'): # ugh!
420n/a setattr(self, opt, strtobool(val))
421n/a else:
422n/a setattr(self, opt, val)
423n/a except ValueError as msg:
424n/a raise DistutilsOptionError(msg)
425n/a
426n/a # -- Command-line parsing methods ----------------------------------
427n/a
428n/a def parse_command_line(self):
429n/a """Parse the setup script's command line, taken from the
430n/a 'script_args' instance attribute (which defaults to 'sys.argv[1:]'
431n/a -- see 'setup()' in core.py). This list is first processed for
432n/a "global options" -- options that set attributes of the Distribution
433n/a instance. Then, it is alternately scanned for Distutils commands
434n/a and options for that command. Each new command terminates the
435n/a options for the previous command. The allowed options for a
436n/a command are determined by the 'user_options' attribute of the
437n/a command class -- thus, we have to be able to load command classes
438n/a in order to parse the command line. Any error in that 'options'
439n/a attribute raises DistutilsGetoptError; any error on the
440n/a command-line raises DistutilsArgError. If no Distutils commands
441n/a were found on the command line, raises DistutilsArgError. Return
442n/a true if command-line was successfully parsed and we should carry
443n/a on with executing commands; false if no errors but we shouldn't
444n/a execute commands (currently, this only happens if user asks for
445n/a help).
446n/a """
447n/a #
448n/a # We now have enough information to show the Macintosh dialog
449n/a # that allows the user to interactively specify the "command line".
450n/a #
451n/a toplevel_options = self._get_toplevel_options()
452n/a
453n/a # We have to parse the command line a bit at a time -- global
454n/a # options, then the first command, then its options, and so on --
455n/a # because each command will be handled by a different class, and
456n/a # the options that are valid for a particular class aren't known
457n/a # until we have loaded the command class, which doesn't happen
458n/a # until we know what the command is.
459n/a
460n/a self.commands = []
461n/a parser = FancyGetopt(toplevel_options + self.display_options)
462n/a parser.set_negative_aliases(self.negative_opt)
463n/a parser.set_aliases({'licence': 'license'})
464n/a args = parser.getopt(args=self.script_args, object=self)
465n/a option_order = parser.get_option_order()
466n/a log.set_verbosity(self.verbose)
467n/a
468n/a # for display options we return immediately
469n/a if self.handle_display_options(option_order):
470n/a return
471n/a while args:
472n/a args = self._parse_command_opts(parser, args)
473n/a if args is None: # user asked for help (and got it)
474n/a return
475n/a
476n/a # Handle the cases of --help as a "global" option, ie.
477n/a # "setup.py --help" and "setup.py --help command ...". For the
478n/a # former, we show global options (--verbose, --dry-run, etc.)
479n/a # and display-only options (--name, --version, etc.); for the
480n/a # latter, we omit the display-only options and show help for
481n/a # each command listed on the command line.
482n/a if self.help:
483n/a self._show_help(parser,
484n/a display_options=len(self.commands) == 0,
485n/a commands=self.commands)
486n/a return
487n/a
488n/a # Oops, no commands found -- an end-user error
489n/a if not self.commands:
490n/a raise DistutilsArgError("no commands supplied")
491n/a
492n/a # All is well: return true
493n/a return True
494n/a
495n/a def _get_toplevel_options(self):
496n/a """Return the non-display options recognized at the top level.
497n/a
498n/a This includes options that are recognized *only* at the top
499n/a level as well as options recognized for commands.
500n/a """
501n/a return self.global_options + [
502n/a ("command-packages=", None,
503n/a "list of packages that provide distutils commands"),
504n/a ]
505n/a
506n/a def _parse_command_opts(self, parser, args):
507n/a """Parse the command-line options for a single command.
508n/a 'parser' must be a FancyGetopt instance; 'args' must be the list
509n/a of arguments, starting with the current command (whose options
510n/a we are about to parse). Returns a new version of 'args' with
511n/a the next command at the front of the list; will be the empty
512n/a list if there are no more commands on the command line. Returns
513n/a None if the user asked for help on this command.
514n/a """
515n/a # late import because of mutual dependence between these modules
516n/a from distutils.cmd import Command
517n/a
518n/a # Pull the current command from the head of the command line
519n/a command = args[0]
520n/a if not command_re.match(command):
521n/a raise SystemExit("invalid command name '%s'" % command)
522n/a self.commands.append(command)
523n/a
524n/a # Dig up the command class that implements this command, so we
525n/a # 1) know that it's a valid command, and 2) know which options
526n/a # it takes.
527n/a try:
528n/a cmd_class = self.get_command_class(command)
529n/a except DistutilsModuleError as msg:
530n/a raise DistutilsArgError(msg)
531n/a
532n/a # Require that the command class be derived from Command -- want
533n/a # to be sure that the basic "command" interface is implemented.
534n/a if not issubclass(cmd_class, Command):
535n/a raise DistutilsClassError(
536n/a "command class %s must subclass Command" % cmd_class)
537n/a
538n/a # Also make sure that the command object provides a list of its
539n/a # known options.
540n/a if not (hasattr(cmd_class, 'user_options') and
541n/a isinstance(cmd_class.user_options, list)):
542n/a msg = ("command class %s must provide "
543n/a "'user_options' attribute (a list of tuples)")
544n/a raise DistutilsClassError(msg % cmd_class)
545n/a
546n/a # If the command class has a list of negative alias options,
547n/a # merge it in with the global negative aliases.
548n/a negative_opt = self.negative_opt
549n/a if hasattr(cmd_class, 'negative_opt'):
550n/a negative_opt = negative_opt.copy()
551n/a negative_opt.update(cmd_class.negative_opt)
552n/a
553n/a # Check for help_options in command class. They have a different
554n/a # format (tuple of four) so we need to preprocess them here.
555n/a if (hasattr(cmd_class, 'help_options') and
556n/a isinstance(cmd_class.help_options, list)):
557n/a help_options = fix_help_options(cmd_class.help_options)
558n/a else:
559n/a help_options = []
560n/a
561n/a # All commands support the global options too, just by adding
562n/a # in 'global_options'.
563n/a parser.set_option_table(self.global_options +
564n/a cmd_class.user_options +
565n/a help_options)
566n/a parser.set_negative_aliases(negative_opt)
567n/a (args, opts) = parser.getopt(args[1:])
568n/a if hasattr(opts, 'help') and opts.help:
569n/a self._show_help(parser, display_options=0, commands=[cmd_class])
570n/a return
571n/a
572n/a if (hasattr(cmd_class, 'help_options') and
573n/a isinstance(cmd_class.help_options, list)):
574n/a help_option_found=0
575n/a for (help_option, short, desc, func) in cmd_class.help_options:
576n/a if hasattr(opts, parser.get_attr_name(help_option)):
577n/a help_option_found=1
578n/a if callable(func):
579n/a func()
580n/a else:
581n/a raise DistutilsClassError(
582n/a "invalid help function %r for help option '%s': "
583n/a "must be a callable object (function, etc.)"
584n/a % (func, help_option))
585n/a
586n/a if help_option_found:
587n/a return
588n/a
589n/a # Put the options from the command-line into their official
590n/a # holding pen, the 'command_options' dictionary.
591n/a opt_dict = self.get_option_dict(command)
592n/a for (name, value) in vars(opts).items():
593n/a opt_dict[name] = ("command line", value)
594n/a
595n/a return args
596n/a
597n/a def finalize_options(self):
598n/a """Set final values for all the options on the Distribution
599n/a instance, analogous to the .finalize_options() method of Command
600n/a objects.
601n/a """
602n/a for attr in ('keywords', 'platforms'):
603n/a value = getattr(self.metadata, attr)
604n/a if value is None:
605n/a continue
606n/a if isinstance(value, str):
607n/a value = [elm.strip() for elm in value.split(',')]
608n/a setattr(self.metadata, attr, value)
609n/a
610n/a def _show_help(self, parser, global_options=1, display_options=1,
611n/a commands=[]):
612n/a """Show help for the setup script command-line in the form of
613n/a several lists of command-line options. 'parser' should be a
614n/a FancyGetopt instance; do not expect it to be returned in the
615n/a same state, as its option table will be reset to make it
616n/a generate the correct help text.
617n/a
618n/a If 'global_options' is true, lists the global options:
619n/a --verbose, --dry-run, etc. If 'display_options' is true, lists
620n/a the "display-only" options: --name, --version, etc. Finally,
621n/a lists per-command help for every command name or command class
622n/a in 'commands'.
623n/a """
624n/a # late import because of mutual dependence between these modules
625n/a from distutils.core import gen_usage
626n/a from distutils.cmd import Command
627n/a
628n/a if global_options:
629n/a if display_options:
630n/a options = self._get_toplevel_options()
631n/a else:
632n/a options = self.global_options
633n/a parser.set_option_table(options)
634n/a parser.print_help(self.common_usage + "\nGlobal options:")
635n/a print('')
636n/a
637n/a if display_options:
638n/a parser.set_option_table(self.display_options)
639n/a parser.print_help(
640n/a "Information display options (just display " +
641n/a "information, ignore any commands)")
642n/a print('')
643n/a
644n/a for command in self.commands:
645n/a if isinstance(command, type) and issubclass(command, Command):
646n/a klass = command
647n/a else:
648n/a klass = self.get_command_class(command)
649n/a if (hasattr(klass, 'help_options') and
650n/a isinstance(klass.help_options, list)):
651n/a parser.set_option_table(klass.user_options +
652n/a fix_help_options(klass.help_options))
653n/a else:
654n/a parser.set_option_table(klass.user_options)
655n/a parser.print_help("Options for '%s' command:" % klass.__name__)
656n/a print('')
657n/a
658n/a print(gen_usage(self.script_name))
659n/a
660n/a def handle_display_options(self, option_order):
661n/a """If there were any non-global "display-only" options
662n/a (--help-commands or the metadata display options) on the command
663n/a line, display the requested info and return true; else return
664n/a false.
665n/a """
666n/a from distutils.core import gen_usage
667n/a
668n/a # User just wants a list of commands -- we'll print it out and stop
669n/a # processing now (ie. if they ran "setup --help-commands foo bar",
670n/a # we ignore "foo bar").
671n/a if self.help_commands:
672n/a self.print_commands()
673n/a print('')
674n/a print(gen_usage(self.script_name))
675n/a return 1
676n/a
677n/a # If user supplied any of the "display metadata" options, then
678n/a # display that metadata in the order in which the user supplied the
679n/a # metadata options.
680n/a any_display_options = 0
681n/a is_display_option = {}
682n/a for option in self.display_options:
683n/a is_display_option[option[0]] = 1
684n/a
685n/a for (opt, val) in option_order:
686n/a if val and is_display_option.get(opt):
687n/a opt = translate_longopt(opt)
688n/a value = getattr(self.metadata, "get_"+opt)()
689n/a if opt in ['keywords', 'platforms']:
690n/a print(','.join(value))
691n/a elif opt in ('classifiers', 'provides', 'requires',
692n/a 'obsoletes'):
693n/a print('\n'.join(value))
694n/a else:
695n/a print(value)
696n/a any_display_options = 1
697n/a
698n/a return any_display_options
699n/a
700n/a def print_command_list(self, commands, header, max_length):
701n/a """Print a subset of the list of all commands -- used by
702n/a 'print_commands()'.
703n/a """
704n/a print(header + ":")
705n/a
706n/a for cmd in commands:
707n/a klass = self.cmdclass.get(cmd)
708n/a if not klass:
709n/a klass = self.get_command_class(cmd)
710n/a try:
711n/a description = klass.description
712n/a except AttributeError:
713n/a description = "(no description available)"
714n/a
715n/a print(" %-*s %s" % (max_length, cmd, description))
716n/a
717n/a def print_commands(self):
718n/a """Print out a help message listing all available commands with a
719n/a description of each. The list is divided into "standard commands"
720n/a (listed in distutils.command.__all__) and "extra commands"
721n/a (mentioned in self.cmdclass, but not a standard command). The
722n/a descriptions come from the command class attribute
723n/a 'description'.
724n/a """
725n/a import distutils.command
726n/a std_commands = distutils.command.__all__
727n/a is_std = {}
728n/a for cmd in std_commands:
729n/a is_std[cmd] = 1
730n/a
731n/a extra_commands = []
732n/a for cmd in self.cmdclass.keys():
733n/a if not is_std.get(cmd):
734n/a extra_commands.append(cmd)
735n/a
736n/a max_length = 0
737n/a for cmd in (std_commands + extra_commands):
738n/a if len(cmd) > max_length:
739n/a max_length = len(cmd)
740n/a
741n/a self.print_command_list(std_commands,
742n/a "Standard commands",
743n/a max_length)
744n/a if extra_commands:
745n/a print()
746n/a self.print_command_list(extra_commands,
747n/a "Extra commands",
748n/a max_length)
749n/a
750n/a def get_command_list(self):
751n/a """Get a list of (command, description) tuples.
752n/a The list is divided into "standard commands" (listed in
753n/a distutils.command.__all__) and "extra commands" (mentioned in
754n/a self.cmdclass, but not a standard command). The descriptions come
755n/a from the command class attribute 'description'.
756n/a """
757n/a # Currently this is only used on Mac OS, for the Mac-only GUI
758n/a # Distutils interface (by Jack Jansen)
759n/a import distutils.command
760n/a std_commands = distutils.command.__all__
761n/a is_std = {}
762n/a for cmd in std_commands:
763n/a is_std[cmd] = 1
764n/a
765n/a extra_commands = []
766n/a for cmd in self.cmdclass.keys():
767n/a if not is_std.get(cmd):
768n/a extra_commands.append(cmd)
769n/a
770n/a rv = []
771n/a for cmd in (std_commands + extra_commands):
772n/a klass = self.cmdclass.get(cmd)
773n/a if not klass:
774n/a klass = self.get_command_class(cmd)
775n/a try:
776n/a description = klass.description
777n/a except AttributeError:
778n/a description = "(no description available)"
779n/a rv.append((cmd, description))
780n/a return rv
781n/a
782n/a # -- Command class/object methods ----------------------------------
783n/a
784n/a def get_command_packages(self):
785n/a """Return a list of packages from which commands are loaded."""
786n/a pkgs = self.command_packages
787n/a if not isinstance(pkgs, list):
788n/a if pkgs is None:
789n/a pkgs = ''
790n/a pkgs = [pkg.strip() for pkg in pkgs.split(',') if pkg != '']
791n/a if "distutils.command" not in pkgs:
792n/a pkgs.insert(0, "distutils.command")
793n/a self.command_packages = pkgs
794n/a return pkgs
795n/a
796n/a def get_command_class(self, command):
797n/a """Return the class that implements the Distutils command named by
798n/a 'command'. First we check the 'cmdclass' dictionary; if the
799n/a command is mentioned there, we fetch the class object from the
800n/a dictionary and return it. Otherwise we load the command module
801n/a ("distutils.command." + command) and fetch the command class from
802n/a the module. The loaded class is also stored in 'cmdclass'
803n/a to speed future calls to 'get_command_class()'.
804n/a
805n/a Raises DistutilsModuleError if the expected module could not be
806n/a found, or if that module does not define the expected class.
807n/a """
808n/a klass = self.cmdclass.get(command)
809n/a if klass:
810n/a return klass
811n/a
812n/a for pkgname in self.get_command_packages():
813n/a module_name = "%s.%s" % (pkgname, command)
814n/a klass_name = command
815n/a
816n/a try:
817n/a __import__(module_name)
818n/a module = sys.modules[module_name]
819n/a except ImportError:
820n/a continue
821n/a
822n/a try:
823n/a klass = getattr(module, klass_name)
824n/a except AttributeError:
825n/a raise DistutilsModuleError(
826n/a "invalid command '%s' (no class '%s' in module '%s')"
827n/a % (command, klass_name, module_name))
828n/a
829n/a self.cmdclass[command] = klass
830n/a return klass
831n/a
832n/a raise DistutilsModuleError("invalid command '%s'" % command)
833n/a
834n/a def get_command_obj(self, command, create=1):
835n/a """Return the command object for 'command'. Normally this object
836n/a is cached on a previous call to 'get_command_obj()'; if no command
837n/a object for 'command' is in the cache, then we either create and
838n/a return it (if 'create' is true) or return None.
839n/a """
840n/a cmd_obj = self.command_obj.get(command)
841n/a if not cmd_obj and create:
842n/a if DEBUG:
843n/a self.announce("Distribution.get_command_obj(): "
844n/a "creating '%s' command object" % command)
845n/a
846n/a klass = self.get_command_class(command)
847n/a cmd_obj = self.command_obj[command] = klass(self)
848n/a self.have_run[command] = 0
849n/a
850n/a # Set any options that were supplied in config files
851n/a # or on the command line. (NB. support for error
852n/a # reporting is lame here: any errors aren't reported
853n/a # until 'finalize_options()' is called, which means
854n/a # we won't report the source of the error.)
855n/a options = self.command_options.get(command)
856n/a if options:
857n/a self._set_command_options(cmd_obj, options)
858n/a
859n/a return cmd_obj
860n/a
861n/a def _set_command_options(self, command_obj, option_dict=None):
862n/a """Set the options for 'command_obj' from 'option_dict'. Basically
863n/a this means copying elements of a dictionary ('option_dict') to
864n/a attributes of an instance ('command').
865n/a
866n/a 'command_obj' must be a Command instance. If 'option_dict' is not
867n/a supplied, uses the standard option dictionary for this command
868n/a (from 'self.command_options').
869n/a """
870n/a command_name = command_obj.get_command_name()
871n/a if option_dict is None:
872n/a option_dict = self.get_option_dict(command_name)
873n/a
874n/a if DEBUG:
875n/a self.announce(" setting options for '%s' command:" % command_name)
876n/a for (option, (source, value)) in option_dict.items():
877n/a if DEBUG:
878n/a self.announce(" %s = %s (from %s)" % (option, value,
879n/a source))
880n/a try:
881n/a bool_opts = [translate_longopt(o)
882n/a for o in command_obj.boolean_options]
883n/a except AttributeError:
884n/a bool_opts = []
885n/a try:
886n/a neg_opt = command_obj.negative_opt
887n/a except AttributeError:
888n/a neg_opt = {}
889n/a
890n/a try:
891n/a is_string = isinstance(value, str)
892n/a if option in neg_opt and is_string:
893n/a setattr(command_obj, neg_opt[option], not strtobool(value))
894n/a elif option in bool_opts and is_string:
895n/a setattr(command_obj, option, strtobool(value))
896n/a elif hasattr(command_obj, option):
897n/a setattr(command_obj, option, value)
898n/a else:
899n/a raise DistutilsOptionError(
900n/a "error in %s: command '%s' has no such option '%s'"
901n/a % (source, command_name, option))
902n/a except ValueError as msg:
903n/a raise DistutilsOptionError(msg)
904n/a
905n/a def reinitialize_command(self, command, reinit_subcommands=0):
906n/a """Reinitializes a command to the state it was in when first
907n/a returned by 'get_command_obj()': ie., initialized but not yet
908n/a finalized. This provides the opportunity to sneak option
909n/a values in programmatically, overriding or supplementing
910n/a user-supplied values from the config files and command line.
911n/a You'll have to re-finalize the command object (by calling
912n/a 'finalize_options()' or 'ensure_finalized()') before using it for
913n/a real.
914n/a
915n/a 'command' should be a command name (string) or command object. If
916n/a 'reinit_subcommands' is true, also reinitializes the command's
917n/a sub-commands, as declared by the 'sub_commands' class attribute (if
918n/a it has one). See the "install" command for an example. Only
919n/a reinitializes the sub-commands that actually matter, ie. those
920n/a whose test predicates return true.
921n/a
922n/a Returns the reinitialized command object.
923n/a """
924n/a from distutils.cmd import Command
925n/a if not isinstance(command, Command):
926n/a command_name = command
927n/a command = self.get_command_obj(command_name)
928n/a else:
929n/a command_name = command.get_command_name()
930n/a
931n/a if not command.finalized:
932n/a return command
933n/a command.initialize_options()
934n/a command.finalized = 0
935n/a self.have_run[command_name] = 0
936n/a self._set_command_options(command)
937n/a
938n/a if reinit_subcommands:
939n/a for sub in command.get_sub_commands():
940n/a self.reinitialize_command(sub, reinit_subcommands)
941n/a
942n/a return command
943n/a
944n/a # -- Methods that operate on the Distribution ----------------------
945n/a
946n/a def announce(self, msg, level=log.INFO):
947n/a log.log(level, msg)
948n/a
949n/a def run_commands(self):
950n/a """Run each command that was seen on the setup script command line.
951n/a Uses the list of commands found and cache of command objects
952n/a created by 'get_command_obj()'.
953n/a """
954n/a for cmd in self.commands:
955n/a self.run_command(cmd)
956n/a
957n/a # -- Methods that operate on its Commands --------------------------
958n/a
959n/a def run_command(self, command):
960n/a """Do whatever it takes to run a command (including nothing at all,
961n/a if the command has already been run). Specifically: if we have
962n/a already created and run the command named by 'command', return
963n/a silently without doing anything. If the command named by 'command'
964n/a doesn't even have a command object yet, create one. Then invoke
965n/a 'run()' on that command object (or an existing one).
966n/a """
967n/a # Already been here, done that? then return silently.
968n/a if self.have_run.get(command):
969n/a return
970n/a
971n/a log.info("running %s", command)
972n/a cmd_obj = self.get_command_obj(command)
973n/a cmd_obj.ensure_finalized()
974n/a cmd_obj.run()
975n/a self.have_run[command] = 1
976n/a
977n/a # -- Distribution query methods ------------------------------------
978n/a
979n/a def has_pure_modules(self):
980n/a return len(self.packages or self.py_modules or []) > 0
981n/a
982n/a def has_ext_modules(self):
983n/a return self.ext_modules and len(self.ext_modules) > 0
984n/a
985n/a def has_c_libraries(self):
986n/a return self.libraries and len(self.libraries) > 0
987n/a
988n/a def has_modules(self):
989n/a return self.has_pure_modules() or self.has_ext_modules()
990n/a
991n/a def has_headers(self):
992n/a return self.headers and len(self.headers) > 0
993n/a
994n/a def has_scripts(self):
995n/a return self.scripts and len(self.scripts) > 0
996n/a
997n/a def has_data_files(self):
998n/a return self.data_files and len(self.data_files) > 0
999n/a
1000n/a def is_pure(self):
1001n/a return (self.has_pure_modules() and
1002n/a not self.has_ext_modules() and
1003n/a not self.has_c_libraries())
1004n/a
1005n/a # -- Metadata query methods ----------------------------------------
1006n/a
1007n/a # If you're looking for 'get_name()', 'get_version()', and so forth,
1008n/a # they are defined in a sneaky way: the constructor binds self.get_XXX
1009n/a # to self.metadata.get_XXX. The actual code is in the
1010n/a # DistributionMetadata class, below.
1011n/a
1012n/aclass DistributionMetadata:
1013n/a """Dummy class to hold the distribution meta-data: name, version,
1014n/a author, and so forth.
1015n/a """
1016n/a
1017n/a _METHOD_BASENAMES = ("name", "version", "author", "author_email",
1018n/a "maintainer", "maintainer_email", "url",
1019n/a "license", "description", "long_description",
1020n/a "keywords", "platforms", "fullname", "contact",
1021n/a "contact_email", "classifiers", "download_url",
1022n/a # PEP 314
1023n/a "provides", "requires", "obsoletes",
1024n/a )
1025n/a
1026n/a def __init__(self, path=None):
1027n/a if path is not None:
1028n/a self.read_pkg_file(open(path))
1029n/a else:
1030n/a self.name = None
1031n/a self.version = None
1032n/a self.author = None
1033n/a self.author_email = None
1034n/a self.maintainer = None
1035n/a self.maintainer_email = None
1036n/a self.url = None
1037n/a self.license = None
1038n/a self.description = None
1039n/a self.long_description = None
1040n/a self.keywords = None
1041n/a self.platforms = None
1042n/a self.classifiers = None
1043n/a self.download_url = None
1044n/a # PEP 314
1045n/a self.provides = None
1046n/a self.requires = None
1047n/a self.obsoletes = None
1048n/a
1049n/a def read_pkg_file(self, file):
1050n/a """Reads the metadata values from a file object."""
1051n/a msg = message_from_file(file)
1052n/a
1053n/a def _read_field(name):
1054n/a value = msg[name]
1055n/a if value == 'UNKNOWN':
1056n/a return None
1057n/a return value
1058n/a
1059n/a def _read_list(name):
1060n/a values = msg.get_all(name, None)
1061n/a if values == []:
1062n/a return None
1063n/a return values
1064n/a
1065n/a metadata_version = msg['metadata-version']
1066n/a self.name = _read_field('name')
1067n/a self.version = _read_field('version')
1068n/a self.description = _read_field('summary')
1069n/a # we are filling author only.
1070n/a self.author = _read_field('author')
1071n/a self.maintainer = None
1072n/a self.author_email = _read_field('author-email')
1073n/a self.maintainer_email = None
1074n/a self.url = _read_field('home-page')
1075n/a self.license = _read_field('license')
1076n/a
1077n/a if 'download-url' in msg:
1078n/a self.download_url = _read_field('download-url')
1079n/a else:
1080n/a self.download_url = None
1081n/a
1082n/a self.long_description = _read_field('description')
1083n/a self.description = _read_field('summary')
1084n/a
1085n/a if 'keywords' in msg:
1086n/a self.keywords = _read_field('keywords').split(',')
1087n/a
1088n/a self.platforms = _read_list('platform')
1089n/a self.classifiers = _read_list('classifier')
1090n/a
1091n/a # PEP 314 - these fields only exist in 1.1
1092n/a if metadata_version == '1.1':
1093n/a self.requires = _read_list('requires')
1094n/a self.provides = _read_list('provides')
1095n/a self.obsoletes = _read_list('obsoletes')
1096n/a else:
1097n/a self.requires = None
1098n/a self.provides = None
1099n/a self.obsoletes = None
1100n/a
1101n/a def write_pkg_info(self, base_dir):
1102n/a """Write the PKG-INFO file into the release tree.
1103n/a """
1104n/a with open(os.path.join(base_dir, 'PKG-INFO'), 'w',
1105n/a encoding='UTF-8') as pkg_info:
1106n/a self.write_pkg_file(pkg_info)
1107n/a
1108n/a def write_pkg_file(self, file):
1109n/a """Write the PKG-INFO format data to a file object.
1110n/a """
1111n/a version = '1.0'
1112n/a if (self.provides or self.requires or self.obsoletes or
1113n/a self.classifiers or self.download_url):
1114n/a version = '1.1'
1115n/a
1116n/a file.write('Metadata-Version: %s\n' % version)
1117n/a file.write('Name: %s\n' % self.get_name())
1118n/a file.write('Version: %s\n' % self.get_version())
1119n/a file.write('Summary: %s\n' % self.get_description())
1120n/a file.write('Home-page: %s\n' % self.get_url())
1121n/a file.write('Author: %s\n' % self.get_contact())
1122n/a file.write('Author-email: %s\n' % self.get_contact_email())
1123n/a file.write('License: %s\n' % self.get_license())
1124n/a if self.download_url:
1125n/a file.write('Download-URL: %s\n' % self.download_url)
1126n/a
1127n/a long_desc = rfc822_escape(self.get_long_description())
1128n/a file.write('Description: %s\n' % long_desc)
1129n/a
1130n/a keywords = ','.join(self.get_keywords())
1131n/a if keywords:
1132n/a file.write('Keywords: %s\n' % keywords)
1133n/a
1134n/a self._write_list(file, 'Platform', self.get_platforms())
1135n/a self._write_list(file, 'Classifier', self.get_classifiers())
1136n/a
1137n/a # PEP 314
1138n/a self._write_list(file, 'Requires', self.get_requires())
1139n/a self._write_list(file, 'Provides', self.get_provides())
1140n/a self._write_list(file, 'Obsoletes', self.get_obsoletes())
1141n/a
1142n/a def _write_list(self, file, name, values):
1143n/a for value in values:
1144n/a file.write('%s: %s\n' % (name, value))
1145n/a
1146n/a # -- Metadata query methods ----------------------------------------
1147n/a
1148n/a def get_name(self):
1149n/a return self.name or "UNKNOWN"
1150n/a
1151n/a def get_version(self):
1152n/a return self.version or "0.0.0"
1153n/a
1154n/a def get_fullname(self):
1155n/a return "%s-%s" % (self.get_name(), self.get_version())
1156n/a
1157n/a def get_author(self):
1158n/a return self.author or "UNKNOWN"
1159n/a
1160n/a def get_author_email(self):
1161n/a return self.author_email or "UNKNOWN"
1162n/a
1163n/a def get_maintainer(self):
1164n/a return self.maintainer or "UNKNOWN"
1165n/a
1166n/a def get_maintainer_email(self):
1167n/a return self.maintainer_email or "UNKNOWN"
1168n/a
1169n/a def get_contact(self):
1170n/a return self.maintainer or self.author or "UNKNOWN"
1171n/a
1172n/a def get_contact_email(self):
1173n/a return self.maintainer_email or self.author_email or "UNKNOWN"
1174n/a
1175n/a def get_url(self):
1176n/a return self.url or "UNKNOWN"
1177n/a
1178n/a def get_license(self):
1179n/a return self.license or "UNKNOWN"
1180n/a get_licence = get_license
1181n/a
1182n/a def get_description(self):
1183n/a return self.description or "UNKNOWN"
1184n/a
1185n/a def get_long_description(self):
1186n/a return self.long_description or "UNKNOWN"
1187n/a
1188n/a def get_keywords(self):
1189n/a return self.keywords or []
1190n/a
1191n/a def get_platforms(self):
1192n/a return self.platforms or ["UNKNOWN"]
1193n/a
1194n/a def get_classifiers(self):
1195n/a return self.classifiers or []
1196n/a
1197n/a def get_download_url(self):
1198n/a return self.download_url or "UNKNOWN"
1199n/a
1200n/a # PEP 314
1201n/a def get_requires(self):
1202n/a return self.requires or []
1203n/a
1204n/a def set_requires(self, value):
1205n/a import distutils.versionpredicate
1206n/a for v in value:
1207n/a distutils.versionpredicate.VersionPredicate(v)
1208n/a self.requires = value
1209n/a
1210n/a def get_provides(self):
1211n/a return self.provides or []
1212n/a
1213n/a def set_provides(self, value):
1214n/a value = [v.strip() for v in value]
1215n/a for v in value:
1216n/a import distutils.versionpredicate
1217n/a distutils.versionpredicate.split_provision(v)
1218n/a self.provides = value
1219n/a
1220n/a def get_obsoletes(self):
1221n/a return self.obsoletes or []
1222n/a
1223n/a def set_obsoletes(self, value):
1224n/a import distutils.versionpredicate
1225n/a for v in value:
1226n/a distutils.versionpredicate.VersionPredicate(v)
1227n/a self.obsoletes = value
1228n/a
1229n/adef fix_help_options(options):
1230n/a """Convert a 4-tuple 'help_options' list as found in various command
1231n/a classes to the 3-tuple form required by FancyGetopt.
1232n/a """
1233n/a new_options = []
1234n/a for help_tuple in options:
1235n/a new_options.append(help_tuple[0:3])
1236n/a return new_options