Back to index

python3.2  3.2.2
Public Member Functions | Public Attributes | Static Public Attributes | Private Member Functions
distutils.dist.Distribution Class Reference
Inheritance diagram for distutils.dist.Distribution:
Inheritance graph
[legend]
Collaboration diagram for distutils.dist.Distribution:
Collaboration graph
[legend]

List of all members.

Public Member Functions

def __init__
def get_option_dict
def dump_option_dicts
def find_config_files
def parse_config_files
def parse_command_line
def finalize_options
def handle_display_options
def print_command_list
def print_commands
def get_command_list
def get_command_packages
def get_command_class
def get_command_obj
def reinitialize_command
def announce
def run_commands
def run_command
def has_pure_modules
def has_ext_modules
def has_c_libraries
def has_modules
def has_headers
def has_scripts
def has_data_files
def is_pure

Public Attributes

 verbose
 dry_run
 help
 metadata
 cmdclass
 command_packages
 script_name
 script_args
 command_options
 dist_files
 packages
 package_data
 package_dir
 py_modules
 libraries
 headers
 ext_modules
 ext_package
 include_dirs
 extra_path
 scripts
 data_files
 password
 command_obj
 have_run
 commands

Static Public Attributes

list global_options
string common_usage
list display_options
list display_option_names = [translate_longopt(x[0]) for x in display_options]
dictionary negative_opt = {'quiet': 'verbose'}

Private Member Functions

def _get_toplevel_options
def _parse_command_opts
def _show_help
def _set_command_options

Detailed Description

The core of the Distutils.  Most of the work hiding behind 'setup'
is really done within a Distribution instance, which farms the work out
to the Distutils commands specified on the command line.

Setup scripts will almost never instantiate Distribution directly,
unless the 'setup()' function is totally inadequate to their needs.
However, it is conceivable that a setup script might wish to subclass
Distribution for some specialized purpose, and then pass the subclass
to 'setup()' as the 'distclass' keyword argument.  If so, it is
necessary to respect the expectations that 'setup' has of Distribution.
See the code for 'setup()', in core.py, for details.

Definition at line 27 of file dist.py.


Constructor & Destructor Documentation

def distutils.dist.Distribution.__init__ (   self,
  attrs = None 
)
Construct a new Distribution instance: initialize all the
attributes of a Distribution, and then use 'attrs' (a dictionary
mapping attribute names to values) to assign some of those
attributes their "real" values.  (Any attributes not mentioned in
'attrs' will be assigned to some null value: 0, None, an empty list
or dictionary, etc.)  Most importantly, initialize the
'command_obj' attribute to the empty dictionary; this will be
filled in with real command objects by 'parse_command_line()'.

Definition at line 118 of file dist.py.

00118 
00119     def __init__ (self, attrs=None):
00120         """Construct a new Distribution instance: initialize all the
00121         attributes of a Distribution, and then use 'attrs' (a dictionary
00122         mapping attribute names to values) to assign some of those
00123         attributes their "real" values.  (Any attributes not mentioned in
00124         'attrs' will be assigned to some null value: 0, None, an empty list
00125         or dictionary, etc.)  Most importantly, initialize the
00126         'command_obj' attribute to the empty dictionary; this will be
00127         filled in with real command objects by 'parse_command_line()'.
00128         """
00129 
00130         # Default values for our command-line options
00131         self.verbose = 1
00132         self.dry_run = 0
00133         self.help = 0
00134         for attr in self.display_option_names:
00135             setattr(self, attr, 0)
00136 
00137         # Store the distribution meta-data (name, version, author, and so
00138         # forth) in a separate object -- we're getting to have enough
00139         # information here (and enough command-line options) that it's
00140         # worth it.  Also delegate 'get_XXX()' methods to the 'metadata'
00141         # object in a sneaky and underhanded (but efficient!) way.
00142         self.metadata = DistributionMetadata()
00143         for basename in self.metadata._METHOD_BASENAMES:
00144             method_name = "get_" + basename
00145             setattr(self, method_name, getattr(self.metadata, method_name))
00146 
00147         # 'cmdclass' maps command names to class objects, so we
00148         # can 1) quickly figure out which class to instantiate when
00149         # we need to create a new command object, and 2) have a way
00150         # for the setup script to override command classes
00151         self.cmdclass = {}
00152 
00153         # 'command_packages' is a list of packages in which commands
00154         # are searched for.  The factory for command 'foo' is expected
00155         # to be named 'foo' in the module 'foo' in one of the packages
00156         # named here.  This list is searched from the left; an error
00157         # is raised if no named package provides the command being
00158         # searched for.  (Always access using get_command_packages().)
00159         self.command_packages = None
00160 
00161         # 'script_name' and 'script_args' are usually set to sys.argv[0]
00162         # and sys.argv[1:], but they can be overridden when the caller is
00163         # not necessarily a setup script run from the command-line.
00164         self.script_name = None
00165         self.script_args = None
00166 
00167         # 'command_options' is where we store command options between
00168         # parsing them (from config files, the command-line, etc.) and when
00169         # they are actually needed -- ie. when the command in question is
00170         # instantiated.  It is a dictionary of dictionaries of 2-tuples:
00171         #   command_options = { command_name : { option : (source, value) } }
00172         self.command_options = {}
00173 
00174         # 'dist_files' is the list of (command, pyversion, file) that
00175         # have been created by any dist commands run so far. This is
00176         # filled regardless of whether the run is dry or not. pyversion
00177         # gives sysconfig.get_python_version() if the dist file is
00178         # specific to a Python version, 'any' if it is good for all
00179         # Python versions on the target platform, and '' for a source
00180         # file. pyversion should not be used to specify minimum or
00181         # maximum required Python versions; use the metainfo for that
00182         # instead.
00183         self.dist_files = []
00184 
00185         # These options are really the business of various commands, rather
00186         # than of the Distribution itself.  We provide aliases for them in
00187         # Distribution as a convenience to the developer.
00188         self.packages = None
00189         self.package_data = {}
00190         self.package_dir = None
00191         self.py_modules = None
00192         self.libraries = None
00193         self.headers = None
00194         self.ext_modules = None
00195         self.ext_package = None
00196         self.include_dirs = None
00197         self.extra_path = None
00198         self.scripts = None
00199         self.data_files = None
00200         self.password = ''
00201 
00202         # And now initialize bookkeeping stuff that can't be supplied by
00203         # the caller at all.  'command_obj' maps command names to
00204         # Command instances -- that's how we enforce that every command
00205         # class is a singleton.
00206         self.command_obj = {}
00207 
00208         # 'have_run' maps command names to boolean values; it keeps track
00209         # of whether we have actually run a particular command, to make it
00210         # cheap to "run" a command whenever we think we might need to -- if
00211         # it's already been done, no need for expensive filesystem
00212         # operations, we just check the 'have_run' dictionary and carry on.
00213         # It's only safe to query 'have_run' for a command class that has
00214         # been instantiated -- a false value will be inserted when the
00215         # command object is created, and replaced with a true value when
00216         # the command is successfully run.  Thus it's probably best to use
00217         # '.get()' rather than a straight lookup.
00218         self.have_run = {}
00219 
00220         # Now we'll use the attrs dictionary (ultimately, keyword args from
00221         # the setup script) to possibly override any or all of these
00222         # distribution options.
00223 
00224         if attrs:
00225             # Pull out the set of command options and work on them
00226             # specifically.  Note that this order guarantees that aliased
00227             # command options will override any supplied redundantly
00228             # through the general options dictionary.
00229             options = attrs.get('options')
00230             if options is not None:
00231                 del attrs['options']
00232                 for (command, cmd_options) in options.items():
00233                     opt_dict = self.get_option_dict(command)
00234                     for (opt, val) in cmd_options.items():
00235                         opt_dict[opt] = ("setup script", val)
00236 
00237             if 'licence' in attrs:
00238                 attrs['license'] = attrs['licence']
00239                 del attrs['licence']
00240                 msg = "'licence' distribution option is deprecated; use 'license'"
00241                 if warnings is not None:
00242                     warnings.warn(msg)
00243                 else:
00244                     sys.stderr.write(msg + "\n")
00245 
00246             # Now work on the rest of the attributes.  Any attribute that's
00247             # not already defined is invalid!
00248             for (key, val) in attrs.items():
00249                 if hasattr(self.metadata, "set_" + key):
00250                     getattr(self.metadata, "set_" + key)(val)
00251                 elif hasattr(self.metadata, key):
00252                     setattr(self.metadata, key, val)
00253                 elif hasattr(self, key):
00254                     setattr(self, key, val)
00255                 else:
00256                     msg = "Unknown distribution option: %s" % repr(key)
00257                     if warnings is not None:
00258                         warnings.warn(msg)
00259                     else:
00260                         sys.stderr.write(msg + "\n")
00261 
00262         self.finalize_options()

Here is the caller graph for this function:


Member Function Documentation

Return the non-display options recognized at the top level.

This includes options that are recognized *only* at the top
level as well as options recognized for commands.

Definition at line 456 of file dist.py.

00456 
00457     def _get_toplevel_options(self):
00458         """Return the non-display options recognized at the top level.
00459 
00460         This includes options that are recognized *only* at the top
00461         level as well as options recognized for commands.
00462         """
00463         return self.global_options + [
00464             ("command-packages=", None,
00465              "list of packages that provide distutils commands"),
00466             ]

Here is the caller graph for this function:

def distutils.dist.Distribution._parse_command_opts (   self,
  parser,
  args 
) [private]
Parse the command-line options for a single command.
'parser' must be a FancyGetopt instance; 'args' must be the list
of arguments, starting with the current command (whose options
we are about to parse).  Returns a new version of 'args' with
the next command at the front of the list; will be the empty
list if there are no more commands on the command line.  Returns
None if the user asked for help on this command.

Definition at line 467 of file dist.py.

00467 
00468     def _parse_command_opts(self, parser, args):
00469         """Parse the command-line options for a single command.
00470         'parser' must be a FancyGetopt instance; 'args' must be the list
00471         of arguments, starting with the current command (whose options
00472         we are about to parse).  Returns a new version of 'args' with
00473         the next command at the front of the list; will be the empty
00474         list if there are no more commands on the command line.  Returns
00475         None if the user asked for help on this command.
00476         """
00477         # late import because of mutual dependence between these modules
00478         from distutils.cmd import Command
00479 
00480         # Pull the current command from the head of the command line
00481         command = args[0]
00482         if not command_re.match(command):
00483             raise SystemExit("invalid command name '%s'" % command)
00484         self.commands.append(command)
00485 
00486         # Dig up the command class that implements this command, so we
00487         # 1) know that it's a valid command, and 2) know which options
00488         # it takes.
00489         try:
00490             cmd_class = self.get_command_class(command)
00491         except DistutilsModuleError as msg:
00492             raise DistutilsArgError(msg)
00493 
00494         # Require that the command class be derived from Command -- want
00495         # to be sure that the basic "command" interface is implemented.
00496         if not issubclass(cmd_class, Command):
00497             raise DistutilsClassError(
00498                   "command class %s must subclass Command" % cmd_class)
00499 
00500         # Also make sure that the command object provides a list of its
00501         # known options.
00502         if not (hasattr(cmd_class, 'user_options') and
00503                 isinstance(cmd_class.user_options, list)):
00504             raise DistutilsClassError(("command class %s must provide " +
00505                    "'user_options' attribute (a list of tuples)") % \
00506                   cmd_class)
00507 
00508         # If the command class has a list of negative alias options,
00509         # merge it in with the global negative aliases.
00510         negative_opt = self.negative_opt
00511         if hasattr(cmd_class, 'negative_opt'):
00512             negative_opt = negative_opt.copy()
00513             negative_opt.update(cmd_class.negative_opt)
00514 
00515         # Check for help_options in command class.  They have a different
00516         # format (tuple of four) so we need to preprocess them here.
00517         if (hasattr(cmd_class, 'help_options') and
00518             isinstance(cmd_class.help_options, list)):
00519             help_options = fix_help_options(cmd_class.help_options)
00520         else:
00521             help_options = []
00522 
00523 
00524         # All commands support the global options too, just by adding
00525         # in 'global_options'.
00526         parser.set_option_table(self.global_options +
00527                                 cmd_class.user_options +
00528                                 help_options)
00529         parser.set_negative_aliases(negative_opt)
00530         (args, opts) = parser.getopt(args[1:])
00531         if hasattr(opts, 'help') and opts.help:
00532             self._show_help(parser, display_options=0, commands=[cmd_class])
00533             return
00534 
00535         if (hasattr(cmd_class, 'help_options') and
00536             isinstance(cmd_class.help_options, list)):
00537             help_option_found=0
00538             for (help_option, short, desc, func) in cmd_class.help_options:
00539                 if hasattr(opts, parser.get_attr_name(help_option)):
00540                     help_option_found=1
00541                     if hasattr(func, '__call__'):
00542                         func()
00543                     else:
00544                         raise DistutilsClassError(
00545                             "invalid help function %r for help option '%s': "
00546                             "must be a callable object (function, etc.)"
00547                             % (func, help_option))
00548 
00549             if help_option_found:
00550                 return
00551 
00552         # Put the options from the command-line into their official
00553         # holding pen, the 'command_options' dictionary.
00554         opt_dict = self.get_option_dict(command)
00555         for (name, value) in vars(opts).items():
00556             opt_dict[name] = ("command line", value)
00557 
00558         return args

Here is the call graph for this function:

def distutils.dist.Distribution._set_command_options (   self,
  command_obj,
  option_dict = None 
) [private]
Set the options for 'command_obj' from 'option_dict'.  Basically
this means copying elements of a dictionary ('option_dict') to
attributes of an instance ('command').

'command_obj' must be a Command instance.  If 'option_dict' is not
supplied, uses the standard option dictionary for this command
(from 'self.command_options').

Definition at line 823 of file dist.py.

00823 
00824     def _set_command_options(self, command_obj, option_dict=None):
00825         """Set the options for 'command_obj' from 'option_dict'.  Basically
00826         this means copying elements of a dictionary ('option_dict') to
00827         attributes of an instance ('command').
00828 
00829         'command_obj' must be a Command instance.  If 'option_dict' is not
00830         supplied, uses the standard option dictionary for this command
00831         (from 'self.command_options').
00832         """
00833         command_name = command_obj.get_command_name()
00834         if option_dict is None:
00835             option_dict = self.get_option_dict(command_name)
00836 
00837         if DEBUG:
00838             self.announce("  setting options for '%s' command:" % command_name)
00839         for (option, (source, value)) in option_dict.items():
00840             if DEBUG:
00841                 self.announce("    %s = %s (from %s)" % (option, value,
00842                                                          source))
00843             try:
00844                 bool_opts = [translate_longopt(o)
00845                              for o in command_obj.boolean_options]
00846             except AttributeError:
00847                 bool_opts = []
00848             try:
00849                 neg_opt = command_obj.negative_opt
00850             except AttributeError:
00851                 neg_opt = {}
00852 
00853             try:
00854                 is_string = isinstance(value, str)
00855                 if option in neg_opt and is_string:
00856                     setattr(command_obj, neg_opt[option], not strtobool(value))
00857                 elif option in bool_opts and is_string:
00858                     setattr(command_obj, option, strtobool(value))
00859                 elif hasattr(command_obj, option):
00860                     setattr(command_obj, option, value)
00861                 else:
00862                     raise DistutilsOptionError(
00863                           "error in %s: command '%s' has no such option '%s'"
00864                           % (source, command_name, option))
00865             except ValueError as msg:
00866                 raise DistutilsOptionError(msg)

Here is the call graph for this function:

Here is the caller graph for this function:

def distutils.dist.Distribution._show_help (   self,
  parser,
  global_options = 1,
  display_options = 1,
  commands = [] 
) [private]
Show help for the setup script command-line in the form of
several lists of command-line options.  'parser' should be a
FancyGetopt instance; do not expect it to be returned in the
same state, as its option table will be reset to make it
generate the correct help text.

If 'global_options' is true, lists the global options:
--verbose, --dry-run, etc.  If 'display_options' is true, lists
the "display-only" options: --name, --version, etc.  Finally,
lists per-command help for every command name or command class
in 'commands'.

Definition at line 573 of file dist.py.

00573 
00574                    commands=[]):
00575         """Show help for the setup script command-line in the form of
00576         several lists of command-line options.  'parser' should be a
00577         FancyGetopt instance; do not expect it to be returned in the
00578         same state, as its option table will be reset to make it
00579         generate the correct help text.
00580 
00581         If 'global_options' is true, lists the global options:
00582         --verbose, --dry-run, etc.  If 'display_options' is true, lists
00583         the "display-only" options: --name, --version, etc.  Finally,
00584         lists per-command help for every command name or command class
00585         in 'commands'.
00586         """
00587         # late import because of mutual dependence between these modules
00588         from distutils.core import gen_usage
00589         from distutils.cmd import Command
00590 
00591         if global_options:
00592             if display_options:
00593                 options = self._get_toplevel_options()
00594             else:
00595                 options = self.global_options
00596             parser.set_option_table(options)
00597             parser.print_help(self.common_usage + "\nGlobal options:")
00598             print('')
00599 
00600         if display_options:
00601             parser.set_option_table(self.display_options)
00602             parser.print_help(
00603                 "Information display options (just display " +
00604                 "information, ignore any commands)")
00605             print('')
00606 
00607         for command in self.commands:
00608             if isinstance(command, type) and issubclass(command, Command):
00609                 klass = command
00610             else:
00611                 klass = self.get_command_class(command)
00612             if (hasattr(klass, 'help_options') and
00613                 isinstance(klass.help_options, list)):
00614                 parser.set_option_table(klass.user_options +
00615                                         fix_help_options(klass.help_options))
00616             else:
00617                 parser.set_option_table(klass.user_options)
00618             parser.print_help("Options for '%s' command:" % klass.__name__)
00619             print('')
00620 
00621         print(gen_usage(self.script_name))

Here is the call graph for this function:

Here is the caller graph for this function:

def distutils.dist.Distribution.announce (   self,
  msg,
  level = log.INFO 
)

Definition at line 908 of file dist.py.

00908 
00909     def announce(self, msg, level=log.INFO):
00910         log.log(level, msg)

Here is the caller graph for this function:

def distutils.dist.Distribution.dump_option_dicts (   self,
  header = None,
  commands = None,
  indent = "" 
)

Definition at line 274 of file dist.py.

00274 
00275     def dump_option_dicts(self, header=None, commands=None, indent=""):
00276         from pprint import pformat
00277 
00278         if commands is None:             # dump all command option dicts
00279             commands = sorted(self.command_options.keys())
00280 
00281         if header is not None:
00282             self.announce(indent + header)
00283             indent = indent + "  "
00284 
00285         if not commands:
00286             self.announce(indent + "no commands known yet")
00287             return
00288 
00289         for cmd_name in commands:
00290             opt_dict = self.command_options.get(cmd_name)
00291             if opt_dict is None:
00292                 self.announce(indent +
00293                               "no option dict for '%s' command" % cmd_name)
00294             else:
00295                 self.announce(indent +
00296                               "option dict for '%s' command:" % cmd_name)
00297                 out = pformat(opt_dict)
00298                 for line in out.split('\n'):
00299                     self.announce(indent + "  " + line)

Here is the call graph for this function:

Set final values for all the options on the Distribution
instance, analogous to the .finalize_options() method of Command
objects.

Definition at line 559 of file dist.py.

00559 
00560     def finalize_options(self):
00561         """Set final values for all the options on the Distribution
00562         instance, analogous to the .finalize_options() method of Command
00563         objects.
00564         """
00565         for attr in ('keywords', 'platforms'):
00566             value = getattr(self.metadata, attr)
00567             if value is None:
00568                 continue
00569             if isinstance(value, str):
00570                 value = [elm.strip() for elm in value.split(',')]
00571                 setattr(self.metadata, attr, value)

Here is the call graph for this function:

Find as many configuration files as should be processed for this
platform, and return a list of filenames in the order in which they
should be parsed.  The filenames returned are guaranteed to exist
(modulo nasty race conditions).

There are three possible config files: distutils.cfg in the
Distutils installation directory (ie. where the top-level
Distutils __inst__.py file lives), a file in the user's home
directory named .pydistutils.cfg on Unix and pydistutils.cfg
on Windows/Mac, and setup.cfg in the current directory.

Reimplemented in distutils.tests.test_dist.TestDistribution.

Definition at line 302 of file dist.py.

00302 
00303     def find_config_files(self):
00304         """Find as many configuration files as should be processed for this
00305         platform, and return a list of filenames in the order in which they
00306         should be parsed.  The filenames returned are guaranteed to exist
00307         (modulo nasty race conditions).
00308 
00309         There are three possible config files: distutils.cfg in the
00310         Distutils installation directory (ie. where the top-level
00311         Distutils __inst__.py file lives), a file in the user's home
00312         directory named .pydistutils.cfg on Unix and pydistutils.cfg
00313         on Windows/Mac, and setup.cfg in the current directory.
00314         """
00315         files = []
00316         check_environ()
00317 
00318         # Where to look for the system-wide Distutils config file
00319         sys_dir = os.path.dirname(sys.modules['distutils'].__file__)
00320 
00321         # Look for the system config file
00322         sys_file = os.path.join(sys_dir, "distutils.cfg")
00323         if os.path.isfile(sys_file):
00324             files.append(sys_file)
00325 
00326         # What to call the per-user config file
00327         if os.name == 'posix':
00328             user_filename = ".pydistutils.cfg"
00329         else:
00330             user_filename = "pydistutils.cfg"
00331 
00332         # And look for the user config file
00333         user_file = os.path.join(os.path.expanduser('~'), user_filename)
00334         if os.path.isfile(user_file):
00335             files.append(user_file)
00336 
00337         # All platforms support local setup.cfg
00338         local_file = "setup.cfg"
00339         if os.path.isfile(local_file):
00340             files.append(local_file)
00341 
00342         return files

Here is the call graph for this function:

Here is the caller graph for this function:

def distutils.dist.Distribution.get_command_class (   self,
  command 
)
Return the class that implements the Distutils command named by
'command'.  First we check the 'cmdclass' dictionary; if the
command is mentioned there, we fetch the class object from the
dictionary and return it.  Otherwise we load the command module
("distutils.command." + command) and fetch the command class from
the module.  The loaded class is also stored in 'cmdclass'
to speed future calls to 'get_command_class()'.

Raises DistutilsModuleError if the expected module could not be
found, or if that module does not define the expected class.

Definition at line 758 of file dist.py.

00758 
00759     def get_command_class(self, command):
00760         """Return the class that implements the Distutils command named by
00761         'command'.  First we check the 'cmdclass' dictionary; if the
00762         command is mentioned there, we fetch the class object from the
00763         dictionary and return it.  Otherwise we load the command module
00764         ("distutils.command." + command) and fetch the command class from
00765         the module.  The loaded class is also stored in 'cmdclass'
00766         to speed future calls to 'get_command_class()'.
00767 
00768         Raises DistutilsModuleError if the expected module could not be
00769         found, or if that module does not define the expected class.
00770         """
00771         klass = self.cmdclass.get(command)
00772         if klass:
00773             return klass
00774 
00775         for pkgname in self.get_command_packages():
00776             module_name = "%s.%s" % (pkgname, command)
00777             klass_name = command
00778 
00779             try:
00780                 __import__ (module_name)
00781                 module = sys.modules[module_name]
00782             except ImportError:
00783                 continue
00784 
00785             try:
00786                 klass = getattr(module, klass_name)
00787             except AttributeError:
00788                 raise DistutilsModuleError(
00789                       "invalid command '%s' (no class '%s' in module '%s')"
00790                       % (command, klass_name, module_name))
00791 
00792             self.cmdclass[command] = klass
00793             return klass
00794 
00795         raise DistutilsModuleError("invalid command '%s'" % command)

Here is the call graph for this function:

Here is the caller graph for this function:

Get a list of (command, description) tuples.
The list is divided into "standard commands" (listed in
distutils.command.__all__) and "extra commands" (mentioned in
self.cmdclass, but not a standard command).  The descriptions come
from the command class attribute 'description'.

Definition at line 712 of file dist.py.

00712 
00713     def get_command_list(self):
00714         """Get a list of (command, description) tuples.
00715         The list is divided into "standard commands" (listed in
00716         distutils.command.__all__) and "extra commands" (mentioned in
00717         self.cmdclass, but not a standard command).  The descriptions come
00718         from the command class attribute 'description'.
00719         """
00720         # Currently this is only used on Mac OS, for the Mac-only GUI
00721         # Distutils interface (by Jack Jansen)
00722         import distutils.command
00723         std_commands = distutils.command.__all__
00724         is_std = {}
00725         for cmd in std_commands:
00726             is_std[cmd] = 1
00727 
00728         extra_commands = []
00729         for cmd in self.cmdclass.keys():
00730             if not is_std.get(cmd):
00731                 extra_commands.append(cmd)
00732 
00733         rv = []
00734         for cmd in (std_commands + extra_commands):
00735             klass = self.cmdclass.get(cmd)
00736             if not klass:
00737                 klass = self.get_command_class(cmd)
00738             try:
00739                 description = klass.description
00740             except AttributeError:
00741                 description = "(no description available)"
00742             rv.append((cmd, description))
00743         return rv

Here is the call graph for this function:

def distutils.dist.Distribution.get_command_obj (   self,
  command,
  create = 1 
)
Return the command object for 'command'.  Normally this object
is cached on a previous call to 'get_command_obj()'; if no command
object for 'command' is in the cache, then we either create and
return it (if 'create' is true) or return None.

Definition at line 796 of file dist.py.

00796 
00797     def get_command_obj(self, command, create=1):
00798         """Return the command object for 'command'.  Normally this object
00799         is cached on a previous call to 'get_command_obj()'; if no command
00800         object for 'command' is in the cache, then we either create and
00801         return it (if 'create' is true) or return None.
00802         """
00803         cmd_obj = self.command_obj.get(command)
00804         if not cmd_obj and create:
00805             if DEBUG:
00806                 self.announce("Distribution.get_command_obj(): " \
00807                               "creating '%s' command object" % command)
00808 
00809             klass = self.get_command_class(command)
00810             cmd_obj = self.command_obj[command] = klass(self)
00811             self.have_run[command] = 0
00812 
00813             # Set any options that were supplied in config files
00814             # or on the command line.  (NB. support for error
00815             # reporting is lame here: any errors aren't reported
00816             # until 'finalize_options()' is called, which means
00817             # we won't report the source of the error.)
00818             options = self.command_options.get(command)
00819             if options:
00820                 self._set_command_options(cmd_obj, options)
00821 
00822         return cmd_obj

Here is the call graph for this function:

Here is the caller graph for this function:

Return a list of packages from which commands are loaded.

Definition at line 746 of file dist.py.

00746 
00747     def get_command_packages(self):
00748         """Return a list of packages from which commands are loaded."""
00749         pkgs = self.command_packages
00750         if not isinstance(pkgs, list):
00751             if pkgs is None:
00752                 pkgs = ''
00753             pkgs = [pkg.strip() for pkg in pkgs.split(',') if pkg != '']
00754             if "distutils.command" not in pkgs:
00755                 pkgs.insert(0, "distutils.command")
00756             self.command_packages = pkgs
00757         return pkgs

Here is the caller graph for this function:

def distutils.dist.Distribution.get_option_dict (   self,
  command 
)
Get the option dictionary for a given command.  If that
command's option dictionary hasn't been created yet, then create it
and return the new dictionary; otherwise, return the existing
option dictionary.

Definition at line 263 of file dist.py.

00263 
00264     def get_option_dict(self, command):
00265         """Get the option dictionary for a given command.  If that
00266         command's option dictionary hasn't been created yet, then create it
00267         and return the new dictionary; otherwise, return the existing
00268         option dictionary.
00269         """
00270         dict = self.command_options.get(command)
00271         if dict is None:
00272             dict = self.command_options[command] = {}
00273         return dict

Here is the caller graph for this function:

def distutils.dist.Distribution.handle_display_options (   self,
  option_order 
)
If there were any non-global "display-only" options
(--help-commands or the metadata display options) on the command
line, display the requested info and return true; else return
false.

Definition at line 622 of file dist.py.

00622 
00623     def handle_display_options(self, option_order):
00624         """If there were any non-global "display-only" options
00625         (--help-commands or the metadata display options) on the command
00626         line, display the requested info and return true; else return
00627         false.
00628         """
00629         from distutils.core import gen_usage
00630 
00631         # User just wants a list of commands -- we'll print it out and stop
00632         # processing now (ie. if they ran "setup --help-commands foo bar",
00633         # we ignore "foo bar").
00634         if self.help_commands:
00635             self.print_commands()
00636             print('')
00637             print(gen_usage(self.script_name))
00638             return 1
00639 
00640         # If user supplied any of the "display metadata" options, then
00641         # display that metadata in the order in which the user supplied the
00642         # metadata options.
00643         any_display_options = 0
00644         is_display_option = {}
00645         for option in self.display_options:
00646             is_display_option[option[0]] = 1
00647 
00648         for (opt, val) in option_order:
00649             if val and is_display_option.get(opt):
00650                 opt = translate_longopt(opt)
00651                 value = getattr(self.metadata, "get_"+opt)()
00652                 if opt in ['keywords', 'platforms']:
00653                     print(','.join(value))
00654                 elif opt in ('classifiers', 'provides', 'requires',
00655                              'obsoletes'):
00656                     print('\n'.join(value))
00657                 else:
00658                     print(value)
00659                 any_display_options = 1
00660 
00661         return any_display_options

Here is the call graph for this function:

Definition at line 948 of file dist.py.

00948 
00949     def has_c_libraries(self):
00950         return self.libraries and len(self.libraries) > 0

Here is the caller graph for this function:

Definition at line 960 of file dist.py.

00960 
00961     def has_data_files(self):
00962         return self.data_files and len(self.data_files) > 0

Definition at line 945 of file dist.py.

00945 
00946     def has_ext_modules(self):
00947         return self.ext_modules and len(self.ext_modules) > 0

Here is the caller graph for this function:

Definition at line 954 of file dist.py.

00954 
00955     def has_headers(self):
00956         return self.headers and len(self.headers) > 0

Definition at line 951 of file dist.py.

00951 
00952     def has_modules(self):
00953         return self.has_pure_modules() or self.has_ext_modules()

Here is the call graph for this function:

Definition at line 942 of file dist.py.

00942 
00943     def has_pure_modules(self):
00944         return len(self.packages or self.py_modules or []) > 0

Here is the caller graph for this function:

Definition at line 957 of file dist.py.

00957 
00958     def has_scripts(self):
00959         return self.scripts and len(self.scripts) > 0

Definition at line 963 of file dist.py.

00963 
00964     def is_pure(self):
00965         return (self.has_pure_modules() and
00966                 not self.has_ext_modules() and
00967                 not self.has_c_libraries())

Here is the call graph for this function:

Parse the setup script's command line, taken from the
'script_args' instance attribute (which defaults to 'sys.argv[1:]'
-- see 'setup()' in core.py).  This list is first processed for
"global options" -- options that set attributes of the Distribution
instance.  Then, it is alternately scanned for Distutils commands
and options for that command.  Each new command terminates the
options for the previous command.  The allowed options for a
command are determined by the 'user_options' attribute of the
command class -- thus, we have to be able to load command classes
in order to parse the command line.  Any error in that 'options'
attribute raises DistutilsGetoptError; any error on the
command-line raises DistutilsArgError.  If no Distutils commands
were found on the command line, raises DistutilsArgError.  Return
true if command-line was successfully parsed and we should carry
on with executing commands; false if no errors but we shouldn't
execute commands (currently, this only happens if user asks for
help).

Definition at line 389 of file dist.py.

00389 
00390     def parse_command_line(self):
00391         """Parse the setup script's command line, taken from the
00392         'script_args' instance attribute (which defaults to 'sys.argv[1:]'
00393         -- see 'setup()' in core.py).  This list is first processed for
00394         "global options" -- options that set attributes of the Distribution
00395         instance.  Then, it is alternately scanned for Distutils commands
00396         and options for that command.  Each new command terminates the
00397         options for the previous command.  The allowed options for a
00398         command are determined by the 'user_options' attribute of the
00399         command class -- thus, we have to be able to load command classes
00400         in order to parse the command line.  Any error in that 'options'
00401         attribute raises DistutilsGetoptError; any error on the
00402         command-line raises DistutilsArgError.  If no Distutils commands
00403         were found on the command line, raises DistutilsArgError.  Return
00404         true if command-line was successfully parsed and we should carry
00405         on with executing commands; false if no errors but we shouldn't
00406         execute commands (currently, this only happens if user asks for
00407         help).
00408         """
00409         #
00410         # We now have enough information to show the Macintosh dialog
00411         # that allows the user to interactively specify the "command line".
00412         #
00413         toplevel_options = self._get_toplevel_options()
00414 
00415         # We have to parse the command line a bit at a time -- global
00416         # options, then the first command, then its options, and so on --
00417         # because each command will be handled by a different class, and
00418         # the options that are valid for a particular class aren't known
00419         # until we have loaded the command class, which doesn't happen
00420         # until we know what the command is.
00421 
00422         self.commands = []
00423         parser = FancyGetopt(toplevel_options + self.display_options)
00424         parser.set_negative_aliases(self.negative_opt)
00425         parser.set_aliases({'licence': 'license'})
00426         args = parser.getopt(args=self.script_args, object=self)
00427         option_order = parser.get_option_order()
00428         log.set_verbosity(self.verbose)
00429 
00430         # for display options we return immediately
00431         if self.handle_display_options(option_order):
00432             return
00433         while args:
00434             args = self._parse_command_opts(parser, args)
00435             if args is None:            # user asked for help (and got it)
00436                 return
00437 
00438         # Handle the cases of --help as a "global" option, ie.
00439         # "setup.py --help" and "setup.py --help command ...".  For the
00440         # former, we show global options (--verbose, --dry-run, etc.)
00441         # and display-only options (--name, --version, etc.); for the
00442         # latter, we omit the display-only options and show help for
00443         # each command listed on the command line.
00444         if self.help:
00445             self._show_help(parser,
00446                             display_options=len(self.commands) == 0,
00447                             commands=self.commands)
00448             return
00449 
00450         # Oops, no commands found -- an end-user error
00451         if not self.commands:
00452             raise DistutilsArgError("no commands supplied")
00453 
00454         # All is well: return true
00455         return True

Here is the call graph for this function:

def distutils.dist.Distribution.parse_config_files (   self,
  filenames = None 
)

Definition at line 343 of file dist.py.

00343 
00344     def parse_config_files(self, filenames=None):
00345         from configparser import ConfigParser
00346 
00347         if filenames is None:
00348             filenames = self.find_config_files()
00349 
00350         if DEBUG:
00351             self.announce("Distribution.parse_config_files():")
00352 
00353         parser = ConfigParser()
00354         for filename in filenames:
00355             if DEBUG:
00356                 self.announce("  reading %s" % filename)
00357             parser.read(filename)
00358             for section in parser.sections():
00359                 options = parser.options(section)
00360                 opt_dict = self.get_option_dict(section)
00361 
00362                 for opt in options:
00363                     if opt != '__name__':
00364                         val = parser.get(section,opt)
00365                         opt = opt.replace('-', '_')
00366                         opt_dict[opt] = (filename, val)
00367 
00368             # Make the ConfigParser forget everything (so we retain
00369             # the original filenames that options come from)
00370             parser.__init__()
00371 
00372         # If there was a "global" section in the config file, use it
00373         # to set Distribution options.
00374 
00375         if 'global' in self.command_options:
00376             for (opt, (src, val)) in self.command_options['global'].items():
00377                 alias = self.negative_opt.get(opt)
00378                 try:
00379                     if alias:
00380                         setattr(self, alias, not strtobool(val))
00381                     elif opt in ('verbose', 'dry_run'): # ugh!
00382                         setattr(self, opt, strtobool(val))
00383                     else:
00384                         setattr(self, opt, val)
00385                 except ValueError as msg:
00386                     raise DistutilsOptionError(msg)

Here is the call graph for this function:

def distutils.dist.Distribution.print_command_list (   self,
  commands,
  header,
  max_length 
)
Print a subset of the list of all commands -- used by
'print_commands()'.

Definition at line 662 of file dist.py.

00662 
00663     def print_command_list(self, commands, header, max_length):
00664         """Print a subset of the list of all commands -- used by
00665         'print_commands()'.
00666         """
00667         print(header + ":")
00668 
00669         for cmd in commands:
00670             klass = self.cmdclass.get(cmd)
00671             if not klass:
00672                 klass = self.get_command_class(cmd)
00673             try:
00674                 description = klass.description
00675             except AttributeError:
00676                 description = "(no description available)"
00677 
00678             print("  %-*s  %s" % (max_length, cmd, description))

Here is the call graph for this function:

Here is the caller graph for this function:

Print out a help message listing all available commands with a
description of each.  The list is divided into "standard commands"
(listed in distutils.command.__all__) and "extra commands"
(mentioned in self.cmdclass, but not a standard command).  The
descriptions come from the command class attribute
'description'.

Definition at line 679 of file dist.py.

00679 
00680     def print_commands(self):
00681         """Print out a help message listing all available commands with a
00682         description of each.  The list is divided into "standard commands"
00683         (listed in distutils.command.__all__) and "extra commands"
00684         (mentioned in self.cmdclass, but not a standard command).  The
00685         descriptions come from the command class attribute
00686         'description'.
00687         """
00688         import distutils.command
00689         std_commands = distutils.command.__all__
00690         is_std = {}
00691         for cmd in std_commands:
00692             is_std[cmd] = 1
00693 
00694         extra_commands = []
00695         for cmd in self.cmdclass.keys():
00696             if not is_std.get(cmd):
00697                 extra_commands.append(cmd)
00698 
00699         max_length = 0
00700         for cmd in (std_commands + extra_commands):
00701             if len(cmd) > max_length:
00702                 max_length = len(cmd)
00703 
00704         self.print_command_list(std_commands,
00705                                 "Standard commands",
00706                                 max_length)
00707         if extra_commands:
00708             print()
00709             self.print_command_list(extra_commands,
00710                                     "Extra commands",
00711                                     max_length)

Here is the call graph for this function:

Here is the caller graph for this function:

def distutils.dist.Distribution.reinitialize_command (   self,
  command,
  reinit_subcommands = 0 
)
Reinitializes a command to the state it was in when first
returned by 'get_command_obj()': ie., initialized but not yet
finalized.  This provides the opportunity to sneak option
values in programmatically, overriding or supplementing
user-supplied values from the config files and command line.
You'll have to re-finalize the command object (by calling
'finalize_options()' or 'ensure_finalized()') before using it for
real.

'command' should be a command name (string) or command object.  If
'reinit_subcommands' is true, also reinitializes the command's
sub-commands, as declared by the 'sub_commands' class attribute (if
it has one).  See the "install" command for an example.  Only
reinitializes the sub-commands that actually matter, ie. those
whose test predicates return true.

Returns the reinitialized command object.

Definition at line 867 of file dist.py.

00867 
00868     def reinitialize_command(self, command, reinit_subcommands=0):
00869         """Reinitializes a command to the state it was in when first
00870         returned by 'get_command_obj()': ie., initialized but not yet
00871         finalized.  This provides the opportunity to sneak option
00872         values in programmatically, overriding or supplementing
00873         user-supplied values from the config files and command line.
00874         You'll have to re-finalize the command object (by calling
00875         'finalize_options()' or 'ensure_finalized()') before using it for
00876         real.
00877 
00878         'command' should be a command name (string) or command object.  If
00879         'reinit_subcommands' is true, also reinitializes the command's
00880         sub-commands, as declared by the 'sub_commands' class attribute (if
00881         it has one).  See the "install" command for an example.  Only
00882         reinitializes the sub-commands that actually matter, ie. those
00883         whose test predicates return true.
00884 
00885         Returns the reinitialized command object.
00886         """
00887         from distutils.cmd import Command
00888         if not isinstance(command, Command):
00889             command_name = command
00890             command = self.get_command_obj(command_name)
00891         else:
00892             command_name = command.get_command_name()
00893 
00894         if not command.finalized:
00895             return command
00896         command.initialize_options()
00897         command.finalized = 0
00898         self.have_run[command_name] = 0
00899         self._set_command_options(command)
00900 
00901         if reinit_subcommands:
00902             for sub in command.get_sub_commands():
00903                 self.reinitialize_command(sub, reinit_subcommands)
00904 
00905         return command

Here is the call graph for this function:

Here is the caller graph for this function:

def distutils.dist.Distribution.run_command (   self,
  command 
)
Do whatever it takes to run a command (including nothing at all,
if the command has already been run).  Specifically: if we have
already created and run the command named by 'command', return
silently without doing anything.  If the command named by 'command'
doesn't even have a command object yet, create one.  Then invoke
'run()' on that command object (or an existing one).

Definition at line 921 of file dist.py.

00921 
00922     def run_command(self, command):
00923         """Do whatever it takes to run a command (including nothing at all,
00924         if the command has already been run).  Specifically: if we have
00925         already created and run the command named by 'command', return
00926         silently without doing anything.  If the command named by 'command'
00927         doesn't even have a command object yet, create one.  Then invoke
00928         'run()' on that command object (or an existing one).
00929         """
00930         # Already been here, done that? then return silently.
00931         if self.have_run.get(command):
00932             return
00933 
00934         log.info("running %s", command)
00935         cmd_obj = self.get_command_obj(command)
00936         cmd_obj.ensure_finalized()
00937         cmd_obj.run()
00938         self.have_run[command] = 1
00939 

Here is the call graph for this function:

Here is the caller graph for this function:

Run each command that was seen on the setup script command line.
Uses the list of commands found and cache of command objects
created by 'get_command_obj()'.

Definition at line 911 of file dist.py.

00911 
00912     def run_commands(self):
00913         """Run each command that was seen on the setup script command line.
00914         Uses the list of commands found and cache of command objects
00915         created by 'get_command_obj()'.
00916         """
00917         for cmd in self.commands:
00918             self.run_command(cmd)

Here is the call graph for this function:


Member Data Documentation

Definition at line 150 of file dist.py.

Definition at line 205 of file dist.py.

Definition at line 171 of file dist.py.

Definition at line 158 of file dist.py.

Definition at line 421 of file dist.py.

Initial value:
"""\
Common commands: (see '--help-commands' for more)

  setup.py build      will build the package underneath 'build/'
  setup.py install    will install the package
"""

Definition at line 58 of file dist.py.

Definition at line 198 of file dist.py.

list distutils.dist.Distribution.display_option_names = [translate_longopt(x[0]) for x in display_options] [static]

Definition at line 110 of file dist.py.

Definition at line 66 of file dist.py.

Definition at line 182 of file dist.py.

Definition at line 131 of file dist.py.

Definition at line 193 of file dist.py.

Definition at line 194 of file dist.py.

Definition at line 196 of file dist.py.

Initial value:
[('verbose', 'v', "run verbosely (default)", 1),
                      ('quiet', 'q', "run quietly (turns verbosity off)"),
                      ('dry-run', 'n', "don't actually do anything"),
                      ('help', 'h', "show detailed help message"),
                     ]

Definition at line 50 of file dist.py.

Definition at line 217 of file dist.py.

Definition at line 192 of file dist.py.

Definition at line 132 of file dist.py.

Definition at line 195 of file dist.py.

Definition at line 191 of file dist.py.

Definition at line 141 of file dist.py.

Definition at line 113 of file dist.py.

Definition at line 188 of file dist.py.

Definition at line 189 of file dist.py.

Definition at line 187 of file dist.py.

Definition at line 199 of file dist.py.

Definition at line 190 of file dist.py.

Definition at line 164 of file dist.py.

Definition at line 163 of file dist.py.

Definition at line 197 of file dist.py.

Definition at line 130 of file dist.py.


The documentation for this class was generated from the following file: