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