3 Provides the Distribution class, which represents the module distribution
4 being built/installed/distributed.
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
22 # Encoding used for the PKG-INFO files
23 PKG_INFO_ENCODING
= 'utf-8'
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_]*)$')
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.
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.
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"),
60 'ignore pydistutils.cfg in your home directory'),
63 # 'common_usage' is a short (2-3 line) string describing the common
64 # usage of the setup script.
66 Common commands: (see '--help-commands' for more)
68 setup.py build will build the package underneath 'build/'
69 setup.py install will install the package
72 # options that are not propagated to the commands
74 ('help-commands', None,
75 "list all available commands"),
77 "print package name"),
79 "print package version"),
81 "print <package name>-<version>"),
83 "print the author's name"),
84 ('author-email', None,
85 "print the author's email address"),
87 "print the maintainer's name"),
88 ('maintainer-email', None,
89 "print the maintainer's email address"),
91 "print the maintainer's name if known, else the author's"),
92 ('contact-email', None,
93 "print the maintainer's email address if known, else the author's"),
95 "print the URL for this package"),
97 "print the license of the package"),
99 "alias for --license"),
100 ('description', None,
101 "print the package description"),
102 ('long-description', None,
103 "print the long package description"),
105 "print the list of platforms"),
106 ('classifiers', None,
107 "print the list of classifiers"),
109 "print the list of keywords"),
111 "print the list of packages/modules provided"),
113 "print the list of packages/modules required"),
115 "print the list of packages/modules made obsolete")
117 display_option_names
= map(lambda x
: translate_longopt(x
[0]),
120 # negative options are options that exclude other options
121 negative_opt
= {'quiet': 'verbose'}
124 # -- Creation/initialization methods -------------------------------
126 def __init__ (self
, attrs
=None):
127 """Construct a new Distribution instance: initialize all the
128 attributes of a Distribution, and then use 'attrs' (a dictionary
129 mapping attribute names to values) to assign some of those
130 attributes their "real" values. (Any attributes not mentioned in
131 'attrs' will be assigned to some null value: 0, None, an empty list
132 or dictionary, etc.) Most importantly, initialize the
133 'command_obj' attribute to the empty dictionary; this will be
134 filled in with real command objects by 'parse_command_line()'.
137 # Default values for our command-line options
141 for attr
in self
.display_option_names
:
142 setattr(self
, attr
, 0)
144 # Store the distribution meta-data (name, version, author, and so
145 # forth) in a separate object -- we're getting to have enough
146 # information here (and enough command-line options) that it's
147 # worth it. Also delegate 'get_XXX()' methods to the 'metadata'
148 # object in a sneaky and underhanded (but efficient!) way.
149 self
.metadata
= DistributionMetadata()
150 for basename
in self
.metadata
._METHOD
_BASENAMES
:
151 method_name
= "get_" + basename
152 setattr(self
, method_name
, getattr(self
.metadata
, method_name
))
154 # 'cmdclass' maps command names to class objects, so we
155 # can 1) quickly figure out which class to instantiate when
156 # we need to create a new command object, and 2) have a way
157 # for the setup script to override command classes
160 # 'command_packages' is a list of packages in which commands
161 # are searched for. The factory for command 'foo' is expected
162 # to be named 'foo' in the module 'foo' in one of the packages
163 # named here. This list is searched from the left; an error
164 # is raised if no named package provides the command being
165 # searched for. (Always access using get_command_packages().)
166 self
.command_packages
= None
168 # 'script_name' and 'script_args' are usually set to sys.argv[0]
169 # and sys.argv[1:], but they can be overridden when the caller is
170 # not necessarily a setup script run from the command-line.
171 self
.script_name
= None
172 self
.script_args
= None
174 # 'command_options' is where we store command options between
175 # parsing them (from config files, the command-line, etc.) and when
176 # they are actually needed -- ie. when the command in question is
177 # instantiated. It is a dictionary of dictionaries of 2-tuples:
178 # command_options = { command_name : { option : (source, value) } }
179 self
.command_options
= {}
181 # 'dist_files' is the list of (command, pyversion, file) that
182 # have been created by any dist commands run so far. This is
183 # filled regardless of whether the run is dry or not. pyversion
184 # gives sysconfig.get_python_version() if the dist file is
185 # specific to a Python version, 'any' if it is good for all
186 # Python versions on the target platform, and '' for a source
187 # file. pyversion should not be used to specify minimum or
188 # maximum required Python versions; use the metainfo for that
192 # These options are really the business of various commands, rather
193 # than of the Distribution itself. We provide aliases for them in
194 # Distribution as a convenience to the developer.
196 self
.package_data
= {}
197 self
.package_dir
= None
198 self
.py_modules
= None
199 self
.libraries
= None
201 self
.ext_modules
= None
202 self
.ext_package
= None
203 self
.include_dirs
= None
204 self
.extra_path
= None
206 self
.data_files
= None
209 # And now initialize bookkeeping stuff that can't be supplied by
210 # the caller at all. 'command_obj' maps command names to
211 # Command instances -- that's how we enforce that every command
212 # class is a singleton.
213 self
.command_obj
= {}
215 # 'have_run' maps command names to boolean values; it keeps track
216 # of whether we have actually run a particular command, to make it
217 # cheap to "run" a command whenever we think we might need to -- if
218 # it's already been done, no need for expensive filesystem
219 # operations, we just check the 'have_run' dictionary and carry on.
220 # It's only safe to query 'have_run' for a command class that has
221 # been instantiated -- a false value will be inserted when the
222 # command object is created, and replaced with a true value when
223 # the command is successfully run. Thus it's probably best to use
224 # '.get()' rather than a straight lookup.
227 # Now we'll use the attrs dictionary (ultimately, keyword args from
228 # the setup script) to possibly override any or all of these
229 # distribution options.
232 # Pull out the set of command options and work on them
233 # specifically. Note that this order guarantees that aliased
234 # command options will override any supplied redundantly
235 # through the general options dictionary.
236 options
= attrs
.get('options')
237 if options
is not None:
239 for (command
, cmd_options
) in options
.items():
240 opt_dict
= self
.get_option_dict(command
)
241 for (opt
, val
) in cmd_options
.items():
242 opt_dict
[opt
] = ("setup script", val
)
244 if 'licence' in attrs
:
245 attrs
['license'] = attrs
['licence']
247 msg
= "'licence' distribution option is deprecated; use 'license'"
248 if warnings
is not None:
251 sys
.stderr
.write(msg
+ "\n")
253 # Now work on the rest of the attributes. Any attribute that's
254 # not already defined is invalid!
255 for (key
, val
) in attrs
.items():
256 if hasattr(self
.metadata
, "set_" + key
):
257 getattr(self
.metadata
, "set_" + key
)(val
)
258 elif hasattr(self
.metadata
, key
):
259 setattr(self
.metadata
, key
, val
)
260 elif hasattr(self
, key
):
261 setattr(self
, key
, val
)
263 msg
= "Unknown distribution option: %s" % repr(key
)
264 if warnings
is not None:
267 sys
.stderr
.write(msg
+ "\n")
269 # no-user-cfg is handled before other command line args
270 # because other args override the config files, and this
271 # one is needed before we can load the config files.
272 # If attrs['script_args'] wasn't passed, assume false.
274 # This also make sure we just look at the global options
275 self
.want_user_cfg
= True
277 if self
.script_args
is not None:
278 for arg
in self
.script_args
:
279 if not arg
.startswith('-'):
281 if arg
== '--no-user-cfg':
282 self
.want_user_cfg
= False
285 self
.finalize_options()
287 def get_option_dict(self
, command
):
288 """Get the option dictionary for a given command. If that
289 command's option dictionary hasn't been created yet, then create it
290 and return the new dictionary; otherwise, return the existing
293 dict = self
.command_options
.get(command
)
295 dict = self
.command_options
[command
] = {}
298 def dump_option_dicts(self
, header
=None, commands
=None, indent
=""):
299 from pprint
import pformat
301 if commands
is None: # dump all command option dicts
302 commands
= self
.command_options
.keys()
305 if header
is not None:
306 self
.announce(indent
+ header
)
307 indent
= indent
+ " "
310 self
.announce(indent
+ "no commands known yet")
313 for cmd_name
in commands
:
314 opt_dict
= self
.command_options
.get(cmd_name
)
316 self
.announce(indent
+
317 "no option dict for '%s' command" % cmd_name
)
319 self
.announce(indent
+
320 "option dict for '%s' command:" % cmd_name
)
321 out
= pformat(opt_dict
)
322 for line
in out
.split('\n'):
323 self
.announce(indent
+ " " + line
)
325 # -- Config file finding/parsing methods ---------------------------
327 def find_config_files(self
):
328 """Find as many configuration files as should be processed for this
329 platform, and return a list of filenames in the order in which they
330 should be parsed. The filenames returned are guaranteed to exist
331 (modulo nasty race conditions).
333 There are three possible config files: distutils.cfg in the
334 Distutils installation directory (ie. where the top-level
335 Distutils __inst__.py file lives), a file in the user's home
336 directory named .pydistutils.cfg on Unix and pydistutils.cfg
337 on Windows/Mac; and setup.cfg in the current directory.
339 The file in the user's home directory can be disabled with the
340 --no-user-cfg option.
345 # Where to look for the system-wide Distutils config file
346 sys_dir
= os
.path
.dirname(sys
.modules
['distutils'].__file
__)
348 # Look for the system config file
349 sys_file
= os
.path
.join(sys_dir
, "distutils.cfg")
350 if os
.path
.isfile(sys_file
):
351 files
.append(sys_file
)
353 # What to call the per-user config file
354 if os
.name
== 'posix':
355 user_filename
= ".pydistutils.cfg"
357 user_filename
= "pydistutils.cfg"
359 # And look for the user config file
360 if self
.want_user_cfg
:
361 user_file
= os
.path
.join(os
.path
.expanduser('~'), user_filename
)
362 if os
.path
.isfile(user_file
):
363 files
.append(user_file
)
365 # All platforms support local setup.cfg
366 local_file
= "setup.cfg"
367 if os
.path
.isfile(local_file
):
368 files
.append(local_file
)
371 self
.announce("using config files: %s" % ', '.join(files
))
375 def parse_config_files(self
, filenames
=None):
376 from ConfigParser
import ConfigParser
378 if filenames
is None:
379 filenames
= self
.find_config_files()
382 self
.announce("Distribution.parse_config_files():")
384 parser
= ConfigParser()
385 for filename
in filenames
:
387 self
.announce(" reading %s" % filename
)
388 parser
.read(filename
)
389 for section
in parser
.sections():
390 options
= parser
.options(section
)
391 opt_dict
= self
.get_option_dict(section
)
394 if opt
!= '__name__':
395 val
= parser
.get(section
,opt
)
396 opt
= opt
.replace('-', '_')
397 opt_dict
[opt
] = (filename
, val
)
399 # Make the ConfigParser forget everything (so we retain
400 # the original filenames that options come from)
403 # If there was a "global" section in the config file, use it
404 # to set Distribution options.
406 if 'global' in self
.command_options
:
407 for (opt
, (src
, val
)) in self
.command_options
['global'].items():
408 alias
= self
.negative_opt
.get(opt
)
411 setattr(self
, alias
, not strtobool(val
))
412 elif opt
in ('verbose', 'dry_run'): # ugh!
413 setattr(self
, opt
, strtobool(val
))
415 setattr(self
, opt
, val
)
416 except ValueError, msg
:
417 raise DistutilsOptionError
, msg
419 # -- Command-line parsing methods ----------------------------------
421 def parse_command_line(self
):
422 """Parse the setup script's command line, taken from the
423 'script_args' instance attribute (which defaults to 'sys.argv[1:]'
424 -- see 'setup()' in core.py). This list is first processed for
425 "global options" -- options that set attributes of the Distribution
426 instance. Then, it is alternately scanned for Distutils commands
427 and options for that command. Each new command terminates the
428 options for the previous command. The allowed options for a
429 command are determined by the 'user_options' attribute of the
430 command class -- thus, we have to be able to load command classes
431 in order to parse the command line. Any error in that 'options'
432 attribute raises DistutilsGetoptError; any error on the
433 command-line raises DistutilsArgError. If no Distutils commands
434 were found on the command line, raises DistutilsArgError. Return
435 true if command-line was successfully parsed and we should carry
436 on with executing commands; false if no errors but we shouldn't
437 execute commands (currently, this only happens if user asks for
441 # We now have enough information to show the Macintosh dialog
442 # that allows the user to interactively specify the "command line".
444 toplevel_options
= self
._get
_toplevel
_options
()
446 # We have to parse the command line a bit at a time -- global
447 # options, then the first command, then its options, and so on --
448 # because each command will be handled by a different class, and
449 # the options that are valid for a particular class aren't known
450 # until we have loaded the command class, which doesn't happen
451 # until we know what the command is.
454 parser
= FancyGetopt(toplevel_options
+ self
.display_options
)
455 parser
.set_negative_aliases(self
.negative_opt
)
456 parser
.set_aliases({'licence': 'license'})
457 args
= parser
.getopt(args
=self
.script_args
, object=self
)
458 option_order
= parser
.get_option_order()
459 log
.set_verbosity(self
.verbose
)
461 # for display options we return immediately
462 if self
.handle_display_options(option_order
):
465 args
= self
._parse
_command
_opts
(parser
, args
)
466 if args
is None: # user asked for help (and got it)
469 # Handle the cases of --help as a "global" option, ie.
470 # "setup.py --help" and "setup.py --help command ...". For the
471 # former, we show global options (--verbose, --dry-run, etc.)
472 # and display-only options (--name, --version, etc.); for the
473 # latter, we omit the display-only options and show help for
474 # each command listed on the command line.
476 self
._show
_help
(parser
,
477 display_options
=len(self
.commands
) == 0,
478 commands
=self
.commands
)
481 # Oops, no commands found -- an end-user error
482 if not self
.commands
:
483 raise DistutilsArgError
, "no commands supplied"
485 # All is well: return true
488 def _get_toplevel_options(self
):
489 """Return the non-display options recognized at the top level.
491 This includes options that are recognized *only* at the top
492 level as well as options recognized for commands.
494 return self
.global_options
+ [
495 ("command-packages=", None,
496 "list of packages that provide distutils commands"),
499 def _parse_command_opts(self
, parser
, args
):
500 """Parse the command-line options for a single command.
501 'parser' must be a FancyGetopt instance; 'args' must be the list
502 of arguments, starting with the current command (whose options
503 we are about to parse). Returns a new version of 'args' with
504 the next command at the front of the list; will be the empty
505 list if there are no more commands on the command line. Returns
506 None if the user asked for help on this command.
508 # late import because of mutual dependence between these modules
509 from distutils
.cmd
import Command
511 # Pull the current command from the head of the command line
513 if not command_re
.match(command
):
514 raise SystemExit, "invalid command name '%s'" % command
515 self
.commands
.append(command
)
517 # Dig up the command class that implements this command, so we
518 # 1) know that it's a valid command, and 2) know which options
521 cmd_class
= self
.get_command_class(command
)
522 except DistutilsModuleError
, msg
:
523 raise DistutilsArgError
, msg
525 # Require that the command class be derived from Command -- want
526 # to be sure that the basic "command" interface is implemented.
527 if not issubclass(cmd_class
, Command
):
528 raise DistutilsClassError
, \
529 "command class %s must subclass Command" % cmd_class
531 # Also make sure that the command object provides a list of its
533 if not (hasattr(cmd_class
, 'user_options') and
534 isinstance(cmd_class
.user_options
, list)):
535 raise DistutilsClassError
, \
536 ("command class %s must provide " +
537 "'user_options' attribute (a list of tuples)") % \
540 # If the command class has a list of negative alias options,
541 # merge it in with the global negative aliases.
542 negative_opt
= self
.negative_opt
543 if hasattr(cmd_class
, 'negative_opt'):
544 negative_opt
= negative_opt
.copy()
545 negative_opt
.update(cmd_class
.negative_opt
)
547 # Check for help_options in command class. They have a different
548 # format (tuple of four) so we need to preprocess them here.
549 if (hasattr(cmd_class
, 'help_options') and
550 isinstance(cmd_class
.help_options
, list)):
551 help_options
= fix_help_options(cmd_class
.help_options
)
556 # All commands support the global options too, just by adding
557 # in 'global_options'.
558 parser
.set_option_table(self
.global_options
+
559 cmd_class
.user_options
+
561 parser
.set_negative_aliases(negative_opt
)
562 (args
, opts
) = parser
.getopt(args
[1:])
563 if hasattr(opts
, 'help') and opts
.help:
564 self
._show
_help
(parser
, display_options
=0, commands
=[cmd_class
])
567 if (hasattr(cmd_class
, 'help_options') and
568 isinstance(cmd_class
.help_options
, list)):
570 for (help_option
, short
, desc
, func
) in cmd_class
.help_options
:
571 if hasattr(opts
, parser
.get_attr_name(help_option
)):
573 if hasattr(func
, '__call__'):
576 raise DistutilsClassError(
577 "invalid help function %r for help option '%s': "
578 "must be a callable object (function, etc.)"
579 % (func
, help_option
))
581 if help_option_found
:
584 # Put the options from the command-line into their official
585 # holding pen, the 'command_options' dictionary.
586 opt_dict
= self
.get_option_dict(command
)
587 for (name
, value
) in vars(opts
).items():
588 opt_dict
[name
] = ("command line", value
)
592 def finalize_options(self
):
593 """Set final values for all the options on the Distribution
594 instance, analogous to the .finalize_options() method of Command
597 for attr
in ('keywords', 'platforms'):
598 value
= getattr(self
.metadata
, attr
)
601 if isinstance(value
, str):
602 value
= [elm
.strip() for elm
in value
.split(',')]
603 setattr(self
.metadata
, attr
, value
)
605 def _show_help(self
, parser
, global_options
=1, display_options
=1,
607 """Show help for the setup script command-line in the form of
608 several lists of command-line options. 'parser' should be a
609 FancyGetopt instance; do not expect it to be returned in the
610 same state, as its option table will be reset to make it
611 generate the correct help text.
613 If 'global_options' is true, lists the global options:
614 --verbose, --dry-run, etc. If 'display_options' is true, lists
615 the "display-only" options: --name, --version, etc. Finally,
616 lists per-command help for every command name or command class
619 # late import because of mutual dependence between these modules
620 from distutils
.core
import gen_usage
621 from distutils
.cmd
import Command
625 options
= self
._get
_toplevel
_options
()
627 options
= self
.global_options
628 parser
.set_option_table(options
)
629 parser
.print_help(self
.common_usage
+ "\nGlobal options:")
633 parser
.set_option_table(self
.display_options
)
635 "Information display options (just display " +
636 "information, ignore any commands)")
639 for command
in self
.commands
:
640 if isinstance(command
, type) and issubclass(command
, Command
):
643 klass
= self
.get_command_class(command
)
644 if (hasattr(klass
, 'help_options') and
645 isinstance(klass
.help_options
, list)):
646 parser
.set_option_table(klass
.user_options
+
647 fix_help_options(klass
.help_options
))
649 parser
.set_option_table(klass
.user_options
)
650 parser
.print_help("Options for '%s' command:" % klass
.__name
__)
653 print(gen_usage(self
.script_name
))
655 def handle_display_options(self
, option_order
):
656 """If there were any non-global "display-only" options
657 (--help-commands or the metadata display options) on the command
658 line, display the requested info and return true; else return
661 from distutils
.core
import gen_usage
663 # User just wants a list of commands -- we'll print it out and stop
664 # processing now (ie. if they ran "setup --help-commands foo bar",
665 # we ignore "foo bar").
666 if self
.help_commands
:
667 self
.print_commands()
669 print(gen_usage(self
.script_name
))
672 # If user supplied any of the "display metadata" options, then
673 # display that metadata in the order in which the user supplied the
675 any_display_options
= 0
676 is_display_option
= {}
677 for option
in self
.display_options
:
678 is_display_option
[option
[0]] = 1
680 for (opt
, val
) in option_order
:
681 if val
and is_display_option
.get(opt
):
682 opt
= translate_longopt(opt
)
683 value
= getattr(self
.metadata
, "get_"+opt
)()
684 if opt
in ['keywords', 'platforms']:
685 print(','.join(value
))
686 elif opt
in ('classifiers', 'provides', 'requires',
688 print('\n'.join(value
))
691 any_display_options
= 1
693 return any_display_options
695 def print_command_list(self
, commands
, header
, max_length
):
696 """Print a subset of the list of all commands -- used by
702 klass
= self
.cmdclass
.get(cmd
)
704 klass
= self
.get_command_class(cmd
)
706 description
= klass
.description
707 except AttributeError:
708 description
= "(no description available)"
710 print(" %-*s %s" % (max_length
, cmd
, description
))
712 def print_commands(self
):
713 """Print out a help message listing all available commands with a
714 description of each. The list is divided into "standard commands"
715 (listed in distutils.command.__all__) and "extra commands"
716 (mentioned in self.cmdclass, but not a standard command). The
717 descriptions come from the command class attribute
720 import distutils
.command
721 std_commands
= distutils
.command
.__all
__
723 for cmd
in std_commands
:
727 for cmd
in self
.cmdclass
.keys():
728 if not is_std
.get(cmd
):
729 extra_commands
.append(cmd
)
732 for cmd
in (std_commands
+ extra_commands
):
733 if len(cmd
) > max_length
:
734 max_length
= len(cmd
)
736 self
.print_command_list(std_commands
,
741 self
.print_command_list(extra_commands
,
745 def get_command_list(self
):
746 """Get a list of (command, description) tuples.
747 The list is divided into "standard commands" (listed in
748 distutils.command.__all__) and "extra commands" (mentioned in
749 self.cmdclass, but not a standard command). The descriptions come
750 from the command class attribute 'description'.
752 # Currently this is only used on Mac OS, for the Mac-only GUI
753 # Distutils interface (by Jack Jansen)
755 import distutils
.command
756 std_commands
= distutils
.command
.__all
__
758 for cmd
in std_commands
:
762 for cmd
in self
.cmdclass
.keys():
763 if not is_std
.get(cmd
):
764 extra_commands
.append(cmd
)
767 for cmd
in (std_commands
+ extra_commands
):
768 klass
= self
.cmdclass
.get(cmd
)
770 klass
= self
.get_command_class(cmd
)
772 description
= klass
.description
773 except AttributeError:
774 description
= "(no description available)"
775 rv
.append((cmd
, description
))
778 # -- Command class/object methods ----------------------------------
780 def get_command_packages(self
):
781 """Return a list of packages from which commands are loaded."""
782 pkgs
= self
.command_packages
783 if not isinstance(pkgs
, list):
786 pkgs
= [pkg
.strip() for pkg
in pkgs
.split(',') if pkg
!= '']
787 if "distutils.command" not in pkgs
:
788 pkgs
.insert(0, "distutils.command")
789 self
.command_packages
= pkgs
792 def get_command_class(self
, command
):
793 """Return the class that implements the Distutils command named by
794 'command'. First we check the 'cmdclass' dictionary; if the
795 command is mentioned there, we fetch the class object from the
796 dictionary and return it. Otherwise we load the command module
797 ("distutils.command." + command) and fetch the command class from
798 the module. The loaded class is also stored in 'cmdclass'
799 to speed future calls to 'get_command_class()'.
801 Raises DistutilsModuleError if the expected module could not be
802 found, or if that module does not define the expected class.
804 klass
= self
.cmdclass
.get(command
)
808 for pkgname
in self
.get_command_packages():
809 module_name
= "%s.%s" % (pkgname
, command
)
813 __import__ (module_name
)
814 module
= sys
.modules
[module_name
]
819 klass
= getattr(module
, klass_name
)
820 except AttributeError:
821 raise DistutilsModuleError
, \
822 "invalid command '%s' (no class '%s' in module '%s')" \
823 % (command
, klass_name
, module_name
)
825 self
.cmdclass
[command
] = klass
828 raise DistutilsModuleError("invalid command '%s'" % command
)
831 def get_command_obj(self
, command
, create
=1):
832 """Return the command object for 'command'. Normally this object
833 is cached on a previous call to 'get_command_obj()'; if no command
834 object for 'command' is in the cache, then we either create and
835 return it (if 'create' is true) or return None.
837 cmd_obj
= self
.command_obj
.get(command
)
838 if not cmd_obj
and create
:
840 self
.announce("Distribution.get_command_obj(): " \
841 "creating '%s' command object" % command
)
843 klass
= self
.get_command_class(command
)
844 cmd_obj
= self
.command_obj
[command
] = klass(self
)
845 self
.have_run
[command
] = 0
847 # Set any options that were supplied in config files
848 # or on the command line. (NB. support for error
849 # reporting is lame here: any errors aren't reported
850 # until 'finalize_options()' is called, which means
851 # we won't report the source of the error.)
852 options
= self
.command_options
.get(command
)
854 self
._set
_command
_options
(cmd_obj
, options
)
858 def _set_command_options(self
, command_obj
, option_dict
=None):
859 """Set the options for 'command_obj' from 'option_dict'. Basically
860 this means copying elements of a dictionary ('option_dict') to
861 attributes of an instance ('command').
863 'command_obj' must be a Command instance. If 'option_dict' is not
864 supplied, uses the standard option dictionary for this command
865 (from 'self.command_options').
867 command_name
= command_obj
.get_command_name()
868 if option_dict
is None:
869 option_dict
= self
.get_option_dict(command_name
)
872 self
.announce(" setting options for '%s' command:" % command_name
)
873 for (option
, (source
, value
)) in option_dict
.items():
875 self
.announce(" %s = %s (from %s)" % (option
, value
,
878 bool_opts
= map(translate_longopt
, command_obj
.boolean_options
)
879 except AttributeError:
882 neg_opt
= command_obj
.negative_opt
883 except AttributeError:
887 is_string
= isinstance(value
, str)
888 if option
in neg_opt
and is_string
:
889 setattr(command_obj
, neg_opt
[option
], not strtobool(value
))
890 elif option
in bool_opts
and is_string
:
891 setattr(command_obj
, option
, strtobool(value
))
892 elif hasattr(command_obj
, option
):
893 setattr(command_obj
, option
, value
)
895 raise DistutilsOptionError
, \
896 ("error in %s: command '%s' has no such option '%s'"
897 % (source
, command_name
, option
))
898 except ValueError, msg
:
899 raise DistutilsOptionError
, msg
901 def reinitialize_command(self
, command
, reinit_subcommands
=0):
902 """Reinitializes a command to the state it was in when first
903 returned by 'get_command_obj()': ie., initialized but not yet
904 finalized. This provides the opportunity to sneak option
905 values in programmatically, overriding or supplementing
906 user-supplied values from the config files and command line.
907 You'll have to re-finalize the command object (by calling
908 'finalize_options()' or 'ensure_finalized()') before using it for
911 'command' should be a command name (string) or command object. If
912 'reinit_subcommands' is true, also reinitializes the command's
913 sub-commands, as declared by the 'sub_commands' class attribute (if
914 it has one). See the "install" command for an example. Only
915 reinitializes the sub-commands that actually matter, ie. those
916 whose test predicates return true.
918 Returns the reinitialized command object.
920 from distutils
.cmd
import Command
921 if not isinstance(command
, Command
):
922 command_name
= command
923 command
= self
.get_command_obj(command_name
)
925 command_name
= command
.get_command_name()
927 if not command
.finalized
:
929 command
.initialize_options()
930 command
.finalized
= 0
931 self
.have_run
[command_name
] = 0
932 self
._set
_command
_options
(command
)
934 if reinit_subcommands
:
935 for sub
in command
.get_sub_commands():
936 self
.reinitialize_command(sub
, reinit_subcommands
)
940 # -- Methods that operate on the Distribution ----------------------
942 def announce(self
, msg
, level
=log
.INFO
):
945 def run_commands(self
):
946 """Run each command that was seen on the setup script command line.
947 Uses the list of commands found and cache of command objects
948 created by 'get_command_obj()'.
950 for cmd
in self
.commands
:
951 self
.run_command(cmd
)
953 # -- Methods that operate on its Commands --------------------------
955 def run_command(self
, command
):
956 """Do whatever it takes to run a command (including nothing at all,
957 if the command has already been run). Specifically: if we have
958 already created and run the command named by 'command', return
959 silently without doing anything. If the command named by 'command'
960 doesn't even have a command object yet, create one. Then invoke
961 'run()' on that command object (or an existing one).
963 # Already been here, done that? then return silently.
964 if self
.have_run
.get(command
):
967 log
.info("running %s", command
)
968 cmd_obj
= self
.get_command_obj(command
)
969 cmd_obj
.ensure_finalized()
971 self
.have_run
[command
] = 1
974 # -- Distribution query methods ------------------------------------
976 def has_pure_modules(self
):
977 return len(self
.packages
or self
.py_modules
or []) > 0
979 def has_ext_modules(self
):
980 return self
.ext_modules
and len(self
.ext_modules
) > 0
982 def has_c_libraries(self
):
983 return self
.libraries
and len(self
.libraries
) > 0
985 def has_modules(self
):
986 return self
.has_pure_modules() or self
.has_ext_modules()
988 def has_headers(self
):
989 return self
.headers
and len(self
.headers
) > 0
991 def has_scripts(self
):
992 return self
.scripts
and len(self
.scripts
) > 0
994 def has_data_files(self
):
995 return self
.data_files
and len(self
.data_files
) > 0
998 return (self
.has_pure_modules() and
999 not self
.has_ext_modules() and
1000 not self
.has_c_libraries())
1002 # -- Metadata query methods ----------------------------------------
1004 # If you're looking for 'get_name()', 'get_version()', and so forth,
1005 # they are defined in a sneaky way: the constructor binds self.get_XXX
1006 # to self.metadata.get_XXX. The actual code is in the
1007 # DistributionMetadata class, below.
1009 class DistributionMetadata
:
1010 """Dummy class to hold the distribution meta-data: name, version,
1011 author, and so forth.
1014 _METHOD_BASENAMES
= ("name", "version", "author", "author_email",
1015 "maintainer", "maintainer_email", "url",
1016 "license", "description", "long_description",
1017 "keywords", "platforms", "fullname", "contact",
1018 "contact_email", "license", "classifiers",
1021 "provides", "requires", "obsoletes",
1024 def __init__ (self
):
1028 self
.author_email
= None
1029 self
.maintainer
= None
1030 self
.maintainer_email
= None
1033 self
.description
= None
1034 self
.long_description
= None
1035 self
.keywords
= None
1036 self
.platforms
= None
1037 self
.classifiers
= None
1038 self
.download_url
= None
1040 self
.provides
= None
1041 self
.requires
= None
1042 self
.obsoletes
= None
1044 def write_pkg_info(self
, base_dir
):
1045 """Write the PKG-INFO file into the release tree.
1047 pkg_info
= open( os
.path
.join(base_dir
, 'PKG-INFO'), 'w')
1048 self
.write_pkg_file(pkg_info
)
1051 def write_pkg_file(self
, file):
1052 """Write the PKG-INFO format data to a file object.
1055 if self
.provides
or self
.requires
or self
.obsoletes
:
1058 self
._write
_field
(file, 'Metadata-Version', version
)
1059 self
._write
_field
(file, 'Name', self
.get_name())
1060 self
._write
_field
(file, 'Version', self
.get_version())
1061 self
._write
_field
(file, 'Summary', self
.get_description())
1062 self
._write
_field
(file, 'Home-page', self
.get_url())
1063 self
._write
_field
(file, 'Author', self
.get_contact())
1064 self
._write
_field
(file, 'Author-email', self
.get_contact_email())
1065 self
._write
_field
(file, 'License', self
.get_license())
1066 if self
.download_url
:
1067 self
._write
_field
(file, 'Download-URL', self
.download_url
)
1069 long_desc
= rfc822_escape(self
.get_long_description())
1070 self
._write
_field
(file, 'Description', long_desc
)
1072 keywords
= ','.join(self
.get_keywords())
1074 self
._write
_field
(file, 'Keywords', keywords
)
1076 self
._write
_list
(file, 'Platform', self
.get_platforms())
1077 self
._write
_list
(file, 'Classifier', self
.get_classifiers())
1080 self
._write
_list
(file, 'Requires', self
.get_requires())
1081 self
._write
_list
(file, 'Provides', self
.get_provides())
1082 self
._write
_list
(file, 'Obsoletes', self
.get_obsoletes())
1084 def _write_field(self
, file, name
, value
):
1085 if isinstance(value
, unicode):
1086 value
= value
.encode(PKG_INFO_ENCODING
)
1089 file.write('%s: %s\n' % (name
, value
))
1091 def _write_list (self
, file, name
, values
):
1092 for value
in values
:
1093 self
._write
_field
(file, name
, value
)
1095 # -- Metadata query methods ----------------------------------------
1098 return self
.name
or "UNKNOWN"
1100 def get_version(self
):
1101 return self
.version
or "0.0.0"
1103 def get_fullname(self
):
1104 return "%s-%s" % (self
.get_name(), self
.get_version())
1106 def get_author(self
):
1107 return self
.author
or "UNKNOWN"
1109 def get_author_email(self
):
1110 return self
.author_email
or "UNKNOWN"
1112 def get_maintainer(self
):
1113 return self
.maintainer
or "UNKNOWN"
1115 def get_maintainer_email(self
):
1116 return self
.maintainer_email
or "UNKNOWN"
1118 def get_contact(self
):
1119 return self
.maintainer
or self
.author
or "UNKNOWN"
1121 def get_contact_email(self
):
1122 return self
.maintainer_email
or self
.author_email
or "UNKNOWN"
1125 return self
.url
or "UNKNOWN"
1127 def get_license(self
):
1128 return self
.license
or "UNKNOWN"
1129 get_licence
= get_license
1131 def get_description(self
):
1132 return self
.description
or "UNKNOWN"
1134 def get_long_description(self
):
1135 return self
.long_description
or "UNKNOWN"
1137 def get_keywords(self
):
1138 return self
.keywords
or []
1140 def get_platforms(self
):
1141 return self
.platforms
or ["UNKNOWN"]
1143 def get_classifiers(self
):
1144 return self
.classifiers
or []
1146 def get_download_url(self
):
1147 return self
.download_url
or "UNKNOWN"
1150 def get_requires(self
):
1151 return self
.requires
or []
1153 def set_requires(self
, value
):
1154 import distutils
.versionpredicate
1156 distutils
.versionpredicate
.VersionPredicate(v
)
1157 self
.requires
= value
1159 def get_provides(self
):
1160 return self
.provides
or []
1162 def set_provides(self
, value
):
1163 value
= [v
.strip() for v
in value
]
1165 import distutils
.versionpredicate
1166 distutils
.versionpredicate
.split_provision(v
)
1167 self
.provides
= value
1169 def get_obsoletes(self
):
1170 return self
.obsoletes
or []
1172 def set_obsoletes(self
, value
):
1173 import distutils
.versionpredicate
1175 distutils
.versionpredicate
.VersionPredicate(v
)
1176 self
.obsoletes
= value
1178 def fix_help_options(options
):
1179 """Convert a 4-tuple 'help_options' list as found in various command
1180 classes to the 3-tuple form required by FancyGetopt.
1183 for help_tuple
in options
:
1184 new_options
.append(help_tuple
[0:3])