Back to index

python3.2  3.2.2
Functions | Variables
distutils.core Namespace Reference

Functions

def gen_usage
def setup
def run_setup

Variables

string USAGE
 _setup_stop_after = None
 _setup_distribution = None
tuple setup_keywords
tuple extension_keywords

Detailed Description

distutils.core

The only module that needs to be imported to use the Distutils; provides
the 'setup' function (which is to be called from the setup script).  Also
indirectly provides the Distribution and Command classes, although they are
really defined in distutils.dist and distutils.cmd.

Function Documentation

def distutils.core.gen_usage (   script_name)

Definition at line 33 of file core.py.

00033 
00034 def gen_usage (script_name):
00035     script = os.path.basename(script_name)
00036     return USAGE % vars()
00037 
00038 
# Some mild magic to control the behaviour of 'setup()' from 'run_setup()'.

Here is the caller graph for this function:

def distutils.core.run_setup (   script_name,
  script_args = None,
  stop_after = "run" 
)
Run a setup script in a somewhat controlled environment, and
return the Distribution instance that drives things.  This is useful
if you need to find out the distribution meta-data (passed as
keyword args from 'script' to 'setup()', or the contents of the
config files or command-line.

'script_name' is a file that will be read and run with 'exec()';
'sys.argv[0]' will be replaced with 'script' for the duration of the
call.  'script_args' is a list of strings; if supplied,
'sys.argv[1:]' will be replaced by 'script_args' for the duration of
the call.

'stop_after' tells 'setup()' when to stop processing; possible
values:
  init
    stop after the Distribution instance has been created and
    populated with the keyword arguments to 'setup()'
  config
    stop after config files have been parsed (and their data
    stored in the Distribution instance)
  commandline
    stop after the command-line ('sys.argv[1:]' or 'script_args')
    have been parsed (and the data stored in the Distribution)
  run [default]
    stop after all commands have been run (the same as if 'setup()'
    had been called in the usual way

Returns the Distribution instance, which provides all information
used to drive the Distutils.

Definition at line 172 of file core.py.

00172 
00173 def run_setup (script_name, script_args=None, stop_after="run"):
00174     """Run a setup script in a somewhat controlled environment, and
00175     return the Distribution instance that drives things.  This is useful
00176     if you need to find out the distribution meta-data (passed as
00177     keyword args from 'script' to 'setup()', or the contents of the
00178     config files or command-line.
00179 
00180     'script_name' is a file that will be read and run with 'exec()';
00181     'sys.argv[0]' will be replaced with 'script' for the duration of the
00182     call.  'script_args' is a list of strings; if supplied,
00183     'sys.argv[1:]' will be replaced by 'script_args' for the duration of
00184     the call.
00185 
00186     'stop_after' tells 'setup()' when to stop processing; possible
00187     values:
00188       init
00189         stop after the Distribution instance has been created and
00190         populated with the keyword arguments to 'setup()'
00191       config
00192         stop after config files have been parsed (and their data
00193         stored in the Distribution instance)
00194       commandline
00195         stop after the command-line ('sys.argv[1:]' or 'script_args')
00196         have been parsed (and the data stored in the Distribution)
00197       run [default]
00198         stop after all commands have been run (the same as if 'setup()'
00199         had been called in the usual way
00200 
00201     Returns the Distribution instance, which provides all information
00202     used to drive the Distutils.
00203     """
00204     if stop_after not in ('init', 'config', 'commandline', 'run'):
00205         raise ValueError("invalid value for 'stop_after': %r" % (stop_after,))
00206 
00207     global _setup_stop_after, _setup_distribution
00208     _setup_stop_after = stop_after
00209 
00210     save_argv = sys.argv
00211     g = {'__file__': script_name}
00212     l = {}
00213     try:
00214         try:
00215             sys.argv[0] = script_name
00216             if script_args is not None:
00217                 sys.argv[1:] = script_args
00218             with open(script_name, 'rb') as f:
00219                 exec(f.read(), g, l)
00220         finally:
00221             sys.argv = save_argv
00222             _setup_stop_after = None
00223     except SystemExit:
00224         # Hmm, should we do something if exiting with a non-zero code
00225         # (ie. error)?
00226         pass
00227     except:
00228         raise
00229 
00230     if _setup_distribution is None:
00231         raise RuntimeError(("'distutils.core.setup()' was never called -- "
00232                "perhaps '%s' is not a Distutils setup script?") % \
00233               script_name)
00234 
00235     # I wonder if the setup script's namespace -- g and l -- would be of
00236     # any interest to callers?
00237     #print "_setup_distribution:", _setup_distribution
00238     return _setup_distribution
00239 
00240 # run_setup ()

Here is the caller graph for this function:

def distutils.core.setup (   attrs)
The gateway to the Distutils: do everything your setup script needs
to do, in a highly flexible and user-driven way.  Briefly: create a
Distribution instance; find and parse config files; parse the command
line; run each Distutils command found there, customized by the options
supplied to 'setup()' (as keyword arguments), in config files, and on
the command line.

The Distribution instance might be an instance of a class supplied via
the 'distclass' keyword argument to 'setup'; if no such class is
supplied, then the Distribution class (in dist.py) is instantiated.
All other arguments to 'setup' (except for 'cmdclass') are used to set
attributes of the Distribution instance.

The 'cmdclass' argument, if supplied, is a dictionary mapping command
names to command classes.  Each command encountered on the command line
will be turned into a command class, which is in turn instantiated; any
class found in 'cmdclass' is used in place of the default, which is
(for command 'foo_bar') class 'foo_bar' in module
'distutils.command.foo_bar'.  The command class must provide a
'user_options' attribute which is a list of option specifiers for
'distutils.fancy_getopt'.  Any command-line options between the current
and the next command are used to set attributes of the current command
object.

When the entire command-line has been successfully parsed, calls the
'run()' method on each command object in turn.  This method will be
driven entirely by the Distribution object (which each command object
has a reference to, thanks to its constructor), and the
command-specific options that became attributes of each command
object.

Definition at line 58 of file core.py.

00058 
00059 def setup (**attrs):
00060     """The gateway to the Distutils: do everything your setup script needs
00061     to do, in a highly flexible and user-driven way.  Briefly: create a
00062     Distribution instance; find and parse config files; parse the command
00063     line; run each Distutils command found there, customized by the options
00064     supplied to 'setup()' (as keyword arguments), in config files, and on
00065     the command line.
00066 
00067     The Distribution instance might be an instance of a class supplied via
00068     the 'distclass' keyword argument to 'setup'; if no such class is
00069     supplied, then the Distribution class (in dist.py) is instantiated.
00070     All other arguments to 'setup' (except for 'cmdclass') are used to set
00071     attributes of the Distribution instance.
00072 
00073     The 'cmdclass' argument, if supplied, is a dictionary mapping command
00074     names to command classes.  Each command encountered on the command line
00075     will be turned into a command class, which is in turn instantiated; any
00076     class found in 'cmdclass' is used in place of the default, which is
00077     (for command 'foo_bar') class 'foo_bar' in module
00078     'distutils.command.foo_bar'.  The command class must provide a
00079     'user_options' attribute which is a list of option specifiers for
00080     'distutils.fancy_getopt'.  Any command-line options between the current
00081     and the next command are used to set attributes of the current command
00082     object.
00083 
00084     When the entire command-line has been successfully parsed, calls the
00085     'run()' method on each command object in turn.  This method will be
00086     driven entirely by the Distribution object (which each command object
00087     has a reference to, thanks to its constructor), and the
00088     command-specific options that became attributes of each command
00089     object.
00090     """
00091 
00092     global _setup_stop_after, _setup_distribution
00093 
00094     # Determine the distribution class -- either caller-supplied or
00095     # our Distribution (see below).
00096     klass = attrs.get('distclass')
00097     if klass:
00098         del attrs['distclass']
00099     else:
00100         klass = Distribution
00101 
00102     if 'script_name' not in attrs:
00103         attrs['script_name'] = os.path.basename(sys.argv[0])
00104     if 'script_args'  not in attrs:
00105         attrs['script_args'] = sys.argv[1:]
00106 
00107     # Create the Distribution instance, using the remaining arguments
00108     # (ie. everything except distclass) to initialize it
00109     try:
00110         _setup_distribution = dist = klass(attrs)
00111     except DistutilsSetupError as msg:
00112         if 'name' not in attrs:
00113             raise SystemExit("error in setup command: %s" % msg)
00114         else:
00115             raise SystemExit("error in %s setup command: %s" % \
00116                   (attrs['name'], msg))
00117 
00118     if _setup_stop_after == "init":
00119         return dist
00120 
00121     # Find and parse the config file(s): they will override options from
00122     # the setup script, but be overridden by the command line.
00123     dist.parse_config_files()
00124 
00125     if DEBUG:
00126         print("options (after parsing config files):")
00127         dist.dump_option_dicts()
00128 
00129     if _setup_stop_after == "config":
00130         return dist
00131 
00132     # Parse the command line; any command-line errors are the end user's
00133     # fault, so turn them into SystemExit to suppress tracebacks.
00134     try:
00135         ok = dist.parse_command_line()
00136     except DistutilsArgError as msg:
00137         raise SystemExit(gen_usage(dist.script_name) + "\nerror: %s" % msg)
00138 
00139     if DEBUG:
00140         print("options (after parsing command line):")
00141         dist.dump_option_dicts()
00142 
00143     if _setup_stop_after == "commandline":
00144         return dist
00145 
00146     # And finally, run all the commands found on the command line.
00147     if ok:
00148         try:
00149             dist.run_commands()
00150         except KeyboardInterrupt:
00151             raise SystemExit("interrupted")
00152         except (IOError, os.error) as exc:
00153             error = grok_environment_error(exc)
00154 
00155             if DEBUG:
00156                 sys.stderr.write(error + "\n")
00157                 raise
00158             else:
00159                 raise SystemExit(error)
00160 
00161         except (DistutilsError,
00162                 CCompilerError) as msg:
00163             if DEBUG:
00164                 raise
00165             else:
00166                 raise SystemExit("error: " + str(msg))
00167 
00168     return dist
00169 
00170 # setup ()
00171 

Here is the call graph for this function:

Here is the caller graph for this function:


Variable Documentation

Definition at line 40 of file core.py.

Definition at line 39 of file core.py.

Initial value:
00001 ('name', 'sources', 'include_dirs',
00002                       'define_macros', 'undef_macros',
00003                       'library_dirs', 'libraries', 'runtime_library_dirs',
00004                       'extra_objects', 'extra_compile_args', 'extra_link_args',
00005                       'swig_opts', 'export_symbols', 'depends', 'language')

Definition at line 52 of file core.py.

Initial value:
00001 ('distclass', 'script_name', 'script_args', 'options',
00002                   'name', 'version', 'author', 'author_email',
00003                   'maintainer', 'maintainer_email', 'url', 'license',
00004                   'description', 'long_description', 'keywords',
00005                   'platforms', 'classifiers', 'download_url',
00006                   'requires', 'provides', 'obsoletes',
00007                   )

Definition at line 43 of file core.py.

Initial value:
00001 """\
00002 usage: %(script)s [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
00003    or: %(script)s --help [cmd1 cmd2 ...]
00004    or: %(script)s --help-commands
00005    or: %(script)s cmd --help
00006 """

Definition at line 26 of file core.py.