djavu-asus/elpy/rpc-venv/lib/python3.11/site-packages/setuptools/__init__.py

   1 """Extensions to the 'distutils' for large or complex distributions"""
   2
   3 import functools
   4 import os
   5 import re
   6 import warnings
   7
   8 import _distutils_hack.override  # noqa: F401
   9
  10 import distutils.core
  11 from distutils.errors import DistutilsOptionError
  12 from distutils.util import convert_path as _convert_path
  13
  14 from ._deprecation_warning import SetuptoolsDeprecationWarning
  15
  16 import setuptools.version
  17 from setuptools.extension import Extension
  18 from setuptools.dist import Distribution
  19 from setuptools.depends import Require
  20 from setuptools.discovery import PackageFinder, PEP420PackageFinder
  21 from . import monkey
  22 from . import logging
  23
  24
  25 __all__ = [
  26     'setup',
  27     'Distribution',
  28     'Command',
  29     'Extension',
  30     'Require',
  31     'SetuptoolsDeprecationWarning',
  32     'find_packages',
  33     'find_namespace_packages',
  34 ]
  35
  36 __version__ = setuptools.version.__version__
  37
  38 bootstrap_install_from = None
  39
  40
  41 find_packages = PackageFinder.find
  42 find_namespace_packages = PEP420PackageFinder.find
  43
  44
  45 def _install_setup_requires(attrs):
  46     # Note: do not use `setuptools.Distribution` directly, as
  47     # our PEP 517 backend patch `distutils.core.Distribution`.
  48     class MinimalDistribution(distutils.core.Distribution):
  49         """
  50         A minimal version of a distribution for supporting the
  51         fetch_build_eggs interface.
  52         """
  53
  54         def __init__(self, attrs):
  55             _incl = 'dependency_links', 'setup_requires'
  56             filtered = {k: attrs[k] for k in set(_incl) & set(attrs)}
  57             super().__init__(filtered)
  58             # Prevent accidentally triggering discovery with incomplete set of attrs
  59             self.set_defaults._disable()
  60
  61         def _get_project_config_files(self, filenames=None):
  62             """Ignore ``pyproject.toml``, they are not related to setup_requires"""
  63             try:
  64                 cfg, toml = super()._split_standard_project_metadata(filenames)
  65                 return cfg, ()
  66             except Exception:
  67                 return filenames, ()
  68
  69         def finalize_options(self):
  70             """
  71             Disable finalize_options to avoid building the working set.
  72             Ref #2158.
  73             """
  74
  75     dist = MinimalDistribution(attrs)
  76
  77     # Honor setup.cfg's options.
  78     dist.parse_config_files(ignore_option_errors=True)
  79     if dist.setup_requires:
  80         _fetch_build_eggs(dist)
  81
  82
  83 def _fetch_build_eggs(dist):
  84     try:
  85         dist.fetch_build_eggs(dist.setup_requires)
  86     except Exception as ex:
  87         msg = """
  88         It is possible a package already installed in your system
  89         contains an version that is invalid according to PEP 440.
  90         You can try `pip install --use-pep517` as a workaround for this problem,
  91         or rely on a new virtual environment.
  92
  93         If the problem refers to a package that is not installed yet,
  94         please contact that package's maintainers or distributors.
  95         """
  96         if "InvalidVersion" in ex.__class__.__name__:
  97             if hasattr(ex, "add_note"):
  98                 ex.add_note(msg)  # PEP 678
  99             else:
 100                 dist.announce(f"\n{msg}\n")
 101         raise
 102
 103
 104 def setup(**attrs):
 105     # Make sure we have any requirements needed to interpret 'attrs'.
 106     logging.configure()
 107     _install_setup_requires(attrs)
 108     return distutils.core.setup(**attrs)
 109
 110
 111 setup.__doc__ = distutils.core.setup.__doc__
 112
 113
 114 _Command = monkey.get_unpatched(distutils.core.Command)
 115
 116
 117 class Command(_Command):
 118     """
 119     Setuptools internal actions are organized using a *command design pattern*.
 120     This means that each action (or group of closely related actions) executed during
 121     the build should be implemented as a ``Command`` subclass.
 122
 123     These commands are abstractions and do not necessarily correspond to a command that
 124     can (or should) be executed via a terminal, in a CLI fashion (although historically
 125     they would).
 126
 127     When creating a new command from scratch, custom defined classes **SHOULD** inherit
 128     from ``setuptools.Command`` and implement a few mandatory methods.
 129     Between these mandatory methods, are listed:
 130
 131     .. method:: initialize_options(self)
 132
 133         Set or (reset) all options/attributes/caches used by the command
 134         to their default values. Note that these values may be overwritten during
 135         the build.
 136
 137     .. method:: finalize_options(self)
 138
 139         Set final values for all options/attributes used by the command.
 140         Most of the time, each option/attribute/cache should only be set if it does not
 141         have any value yet (e.g. ``if self.attr is None: self.attr = val``).
 142
 143     .. method:: run(self)
 144
 145         Execute the actions intended by the command.
 146         (Side effects **SHOULD** only take place when ``run`` is executed,
 147         for example, creating new files or writing to the terminal output).
 148
 149     A useful analogy for command classes is to think of them as subroutines with local
 150     variables called "options".  The options are "declared" in ``initialize_options()``
 151     and "defined" (given their final values, aka "finalized") in ``finalize_options()``,
 152     both of which must be defined by every command class. The "body" of the subroutine,
 153     (where it does all the work) is the ``run()`` method.
 154     Between ``initialize_options()`` and ``finalize_options()``, ``setuptools`` may set
 155     the values for options/attributes based on user's input (or circumstance),
 156     which means that the implementation should be careful to not overwrite values in
 157     ``finalize_options`` unless necessary.
 158
 159     Please note that other commands (or other parts of setuptools) may also overwrite
 160     the values of the command's options/attributes multiple times during the build
 161     process.
 162     Therefore it is important to consistently implement ``initialize_options()`` and
 163     ``finalize_options()``. For example, all derived attributes (or attributes that
 164     depend on the value of other attributes) **SHOULD** be recomputed in
 165     ``finalize_options``.
 166
 167     When overwriting existing commands, custom defined classes **MUST** abide by the
 168     same APIs implemented by the original class. They also **SHOULD** inherit from the
 169     original class.
 170     """
 171
 172     command_consumes_arguments = False
 173
 174     def __init__(self, dist, **kw):
 175         """
 176         Construct the command for dist, updating
 177         vars(self) with any keyword parameters.
 178         """
 179         super().__init__(dist)
 180         vars(self).update(kw)
 181
 182     def _ensure_stringlike(self, option, what, default=None):
 183         val = getattr(self, option)
 184         if val is None:
 185             setattr(self, option, default)
 186             return default
 187         elif not isinstance(val, str):
 188             raise DistutilsOptionError(
 189                 "'%s' must be a %s (got `%s`)" % (option, what, val)
 190             )
 191         return val
 192
 193     def ensure_string_list(self, option):
 194         r"""Ensure that 'option' is a list of strings.  If 'option' is
 195         currently a string, we split it either on /,\s*/ or /\s+/, so
 196         "foo bar baz", "foo,bar,baz", and "foo,   bar baz" all become
 197         ["foo", "bar", "baz"].
 198
 199         ..
 200            TODO: This method seems to be similar to the one in ``distutils.cmd``
 201            Probably it is just here for backward compatibility with old Python versions?
 202
 203         :meta private:
 204         """
 205         val = getattr(self, option)
 206         if val is None:
 207             return
 208         elif isinstance(val, str):
 209             setattr(self, option, re.split(r',\s*|\s+', val))
 210         else:
 211             if isinstance(val, list):
 212                 ok = all(isinstance(v, str) for v in val)
 213             else:
 214                 ok = False
 215             if not ok:
 216                 raise DistutilsOptionError(
 217                     "'%s' must be a list of strings (got %r)" % (option, val)
 218                 )
 219
 220     def reinitialize_command(self, command, reinit_subcommands=0, **kw):
 221         cmd = _Command.reinitialize_command(self, command, reinit_subcommands)
 222         vars(cmd).update(kw)
 223         return cmd
 224
 225
 226 def _find_all_simple(path):
 227     """
 228     Find all files under 'path'
 229     """
 230     results = (
 231         os.path.join(base, file)
 232         for base, dirs, files in os.walk(path, followlinks=True)
 233         for file in files
 234     )
 235     return filter(os.path.isfile, results)
 236
 237
 238 def findall(dir=os.curdir):
 239     """
 240     Find all files under 'dir' and return the list of full filenames.
 241     Unless dir is '.', return full filenames with dir prepended.
 242     """
 243     files = _find_all_simple(dir)
 244     if dir == os.curdir:
 245         make_rel = functools.partial(os.path.relpath, start=dir)
 246         files = map(make_rel, files)
 247     return list(files)
 248
 249
 250 @functools.wraps(_convert_path)
 251 def convert_path(pathname):
 252     from inspect import cleandoc
 253
 254     msg = """
 255     The function `convert_path` is considered internal and not part of the public API.
 256     Its direct usage by 3rd-party packages is considered deprecated and the function
 257     may be removed in the future.
 258     """
 259     warnings.warn(cleandoc(msg), SetuptoolsDeprecationWarning)
 260     return _convert_path(pathname)
 261
 262
 263 class sic(str):
 264     """Treat this string as-is (https://en.wikipedia.org/wiki/Sic)"""
 265
 266
 267 # Apply monkey patches
 268 monkey.patch_all()