venv/lib/python3.11/site-packages/setuptools/_distutils/core.py

   1 """distutils.core
   2
   3 The only module that needs to be imported to use the Distutils; provides
   4 the 'setup' function (which is to be called from the setup script).  Also
   5 indirectly provides the Distribution and Command classes, although they are
   6 really defined in distutils.dist and distutils.cmd.
   7 """
   8
   9 import os
  10 import sys
  11 import tokenize
  12
  13 from .debug import DEBUG
  14 from .errors import (
  15     DistutilsSetupError,
  16     DistutilsError,
  17     CCompilerError,
  18     DistutilsArgError,
  19 )
  20
  21 # Mainly import these so setup scripts can "from distutils.core import" them.
  22 from .dist import Distribution
  23 from .cmd import Command
  24 from .config import PyPIRCCommand
  25 from .extension import Extension
  26
  27
  28 __all__ = ['Distribution', 'Command', 'PyPIRCCommand', 'Extension', 'setup']
  29
  30 # This is a barebones help message generated displayed when the user
  31 # runs the setup script with no arguments at all.  More useful help
  32 # is generated with various --help options: global help, list commands,
  33 # and per-command help.
  34 USAGE = """\
  35 usage: %(script)s [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
  36    or: %(script)s --help [cmd1 cmd2 ...]
  37    or: %(script)s --help-commands
  38    or: %(script)s cmd --help
  39 """
  40
  41
  42 def gen_usage(script_name):
  43     script = os.path.basename(script_name)
  44     return USAGE % locals()
  45
  46
  47 # Some mild magic to control the behaviour of 'setup()' from 'run_setup()'.
  48 _setup_stop_after = None
  49 _setup_distribution = None
  50
  51 # Legal keyword arguments for the setup() function
  52 setup_keywords = (
  53     'distclass',
  54     'script_name',
  55     'script_args',
  56     'options',
  57     'name',
  58     'version',
  59     'author',
  60     'author_email',
  61     'maintainer',
  62     'maintainer_email',
  63     'url',
  64     'license',
  65     'description',
  66     'long_description',
  67     'keywords',
  68     'platforms',
  69     'classifiers',
  70     'download_url',
  71     'requires',
  72     'provides',
  73     'obsoletes',
  74 )
  75
  76 # Legal keyword arguments for the Extension constructor
  77 extension_keywords = (
  78     'name',
  79     'sources',
  80     'include_dirs',
  81     'define_macros',
  82     'undef_macros',
  83     'library_dirs',
  84     'libraries',
  85     'runtime_library_dirs',
  86     'extra_objects',
  87     'extra_compile_args',
  88     'extra_link_args',
  89     'swig_opts',
  90     'export_symbols',
  91     'depends',
  92     'language',
  93 )
  94
  95
  96 def setup(**attrs):  # noqa: C901
  97     """The gateway to the Distutils: do everything your setup script needs
  98     to do, in a highly flexible and user-driven way.  Briefly: create a
  99     Distribution instance; find and parse config files; parse the command
 100     line; run each Distutils command found there, customized by the options
 101     supplied to 'setup()' (as keyword arguments), in config files, and on
 102     the command line.
 103
 104     The Distribution instance might be an instance of a class supplied via
 105     the 'distclass' keyword argument to 'setup'; if no such class is
 106     supplied, then the Distribution class (in dist.py) is instantiated.
 107     All other arguments to 'setup' (except for 'cmdclass') are used to set
 108     attributes of the Distribution instance.
 109
 110     The 'cmdclass' argument, if supplied, is a dictionary mapping command
 111     names to command classes.  Each command encountered on the command line
 112     will be turned into a command class, which is in turn instantiated; any
 113     class found in 'cmdclass' is used in place of the default, which is
 114     (for command 'foo_bar') class 'foo_bar' in module
 115     'distutils.command.foo_bar'.  The command class must provide a
 116     'user_options' attribute which is a list of option specifiers for
 117     'distutils.fancy_getopt'.  Any command-line options between the current
 118     and the next command are used to set attributes of the current command
 119     object.
 120
 121     When the entire command-line has been successfully parsed, calls the
 122     'run()' method on each command object in turn.  This method will be
 123     driven entirely by the Distribution object (which each command object
 124     has a reference to, thanks to its constructor), and the
 125     command-specific options that became attributes of each command
 126     object.
 127     """
 128
 129     global _setup_stop_after, _setup_distribution
 130
 131     # Determine the distribution class -- either caller-supplied or
 132     # our Distribution (see below).
 133     klass = attrs.get('distclass')
 134     if klass:
 135         attrs.pop('distclass')
 136     else:
 137         klass = Distribution
 138
 139     if 'script_name' not in attrs:
 140         attrs['script_name'] = os.path.basename(sys.argv[0])
 141     if 'script_args' not in attrs:
 142         attrs['script_args'] = sys.argv[1:]
 143
 144     # Create the Distribution instance, using the remaining arguments
 145     # (ie. everything except distclass) to initialize it
 146     try:
 147         _setup_distribution = dist = klass(attrs)
 148     except DistutilsSetupError as msg:
 149         if 'name' not in attrs:
 150             raise SystemExit("error in setup command: %s" % msg)
 151         else:
 152             raise SystemExit("error in {} setup command: {}".format(attrs['name'], msg))
 153
 154     if _setup_stop_after == "init":
 155         return dist
 156
 157     # Find and parse the config file(s): they will override options from
 158     # the setup script, but be overridden by the command line.
 159     dist.parse_config_files()
 160
 161     if DEBUG:
 162         print("options (after parsing config files):")
 163         dist.dump_option_dicts()
 164
 165     if _setup_stop_after == "config":
 166         return dist
 167
 168     # Parse the command line and override config files; any
 169     # command-line errors are the end user's fault, so turn them into
 170     # SystemExit to suppress tracebacks.
 171     try:
 172         ok = dist.parse_command_line()
 173     except DistutilsArgError as msg:
 174         raise SystemExit(gen_usage(dist.script_name) + "\nerror: %s" % msg)
 175
 176     if DEBUG:
 177         print("options (after parsing command line):")
 178         dist.dump_option_dicts()
 179
 180     if _setup_stop_after == "commandline":
 181         return dist
 182
 183     # And finally, run all the commands found on the command line.
 184     if ok:
 185         return run_commands(dist)
 186
 187     return dist
 188
 189
 190 # setup ()
 191
 192
 193 def run_commands(dist):
 194     """Given a Distribution object run all the commands,
 195     raising ``SystemExit`` errors in the case of failure.
 196
 197     This function assumes that either ``sys.argv`` or ``dist.script_args``
 198     is already set accordingly.
 199     """
 200     try:
 201         dist.run_commands()
 202     except KeyboardInterrupt:
 203         raise SystemExit("interrupted")
 204     except OSError as exc:
 205         if DEBUG:
 206             sys.stderr.write("error: {}\n".format(exc))
 207             raise
 208         else:
 209             raise SystemExit("error: {}".format(exc))
 210
 211     except (DistutilsError, CCompilerError) as msg:
 212         if DEBUG:
 213             raise
 214         else:
 215             raise SystemExit("error: " + str(msg))
 216
 217     return dist
 218
 219
 220 def run_setup(script_name, script_args=None, stop_after="run"):
 221     """Run a setup script in a somewhat controlled environment, and
 222     return the Distribution instance that drives things.  This is useful
 223     if you need to find out the distribution meta-data (passed as
 224     keyword args from 'script' to 'setup()', or the contents of the
 225     config files or command-line.
 226
 227     'script_name' is a file that will be read and run with 'exec()';
 228     'sys.argv[0]' will be replaced with 'script' for the duration of the
 229     call.  'script_args' is a list of strings; if supplied,
 230     'sys.argv[1:]' will be replaced by 'script_args' for the duration of
 231     the call.
 232
 233     'stop_after' tells 'setup()' when to stop processing; possible
 234     values:
 235       init
 236         stop after the Distribution instance has been created and
 237         populated with the keyword arguments to 'setup()'
 238       config
 239         stop after config files have been parsed (and their data
 240         stored in the Distribution instance)
 241       commandline
 242         stop after the command-line ('sys.argv[1:]' or 'script_args')
 243         have been parsed (and the data stored in the Distribution)
 244       run [default]
 245         stop after all commands have been run (the same as if 'setup()'
 246         had been called in the usual way
 247
 248     Returns the Distribution instance, which provides all information
 249     used to drive the Distutils.
 250     """
 251     if stop_after not in ('init', 'config', 'commandline', 'run'):
 252         raise ValueError("invalid value for 'stop_after': {!r}".format(stop_after))
 253
 254     global _setup_stop_after, _setup_distribution
 255     _setup_stop_after = stop_after
 256
 257     save_argv = sys.argv.copy()
 258     g = {'__file__': script_name, '__name__': '__main__'}
 259     try:
 260         try:
 261             sys.argv[0] = script_name
 262             if script_args is not None:
 263                 sys.argv[1:] = script_args
 264             # tokenize.open supports automatic encoding detection
 265             with tokenize.open(script_name) as f:
 266                 code = f.read().replace(r'\r\n', r'\n')
 267                 exec(code, g)
 268         finally:
 269             sys.argv = save_argv
 270             _setup_stop_after = None
 271     except SystemExit:
 272         # Hmm, should we do something if exiting with a non-zero code
 273         # (ie. error)?
 274         pass
 275
 276     if _setup_distribution is None:
 277         raise RuntimeError(
 278             (
 279                 "'distutils.core.setup()' was never called -- "
 280                 "perhaps '%s' is not a Distutils setup script?"
 281             )
 282             % script_name
 283         )
 284
 285     # I wonder if the setup script's namespace -- g and l -- would be of
 286     # any interest to callers?
 287     # print "_setup_distribution:", _setup_distribution
 288     return _setup_distribution
 289
 290
 291 # run_setup ()