Lib/distutils/dist.py

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