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