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