Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/lib/python3.8/site-packages/setuptools/discovery.py @ 68:5028fdace37b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 16:23:26 -0400
parents
children
rev   line source
jpayne@68 1 """Automatic discovery of Python modules and packages (for inclusion in the
jpayne@68 2 distribution) and other config values.
jpayne@68 3
jpayne@68 4 For the purposes of this module, the following nomenclature is used:
jpayne@68 5
jpayne@68 6 - "src-layout": a directory representing a Python project that contains a "src"
jpayne@68 7 folder. Everything under the "src" folder is meant to be included in the
jpayne@68 8 distribution when packaging the project. Example::
jpayne@68 9
jpayne@68 10 .
jpayne@68 11 ├── tox.ini
jpayne@68 12 ├── pyproject.toml
jpayne@68 13 └── src/
jpayne@68 14 └── mypkg/
jpayne@68 15 ├── __init__.py
jpayne@68 16 ├── mymodule.py
jpayne@68 17 └── my_data_file.txt
jpayne@68 18
jpayne@68 19 - "flat-layout": a Python project that does not use "src-layout" but instead
jpayne@68 20 have a directory under the project root for each package::
jpayne@68 21
jpayne@68 22 .
jpayne@68 23 ├── tox.ini
jpayne@68 24 ├── pyproject.toml
jpayne@68 25 └── mypkg/
jpayne@68 26 ├── __init__.py
jpayne@68 27 ├── mymodule.py
jpayne@68 28 └── my_data_file.txt
jpayne@68 29
jpayne@68 30 - "single-module": a project that contains a single Python script direct under
jpayne@68 31 the project root (no directory used)::
jpayne@68 32
jpayne@68 33 .
jpayne@68 34 ├── tox.ini
jpayne@68 35 ├── pyproject.toml
jpayne@68 36 └── mymodule.py
jpayne@68 37
jpayne@68 38 """
jpayne@68 39
jpayne@68 40 from __future__ import annotations
jpayne@68 41
jpayne@68 42 import itertools
jpayne@68 43 import os
jpayne@68 44 from collections.abc import Iterator
jpayne@68 45 from fnmatch import fnmatchcase
jpayne@68 46 from glob import glob
jpayne@68 47 from pathlib import Path
jpayne@68 48 from typing import TYPE_CHECKING, Iterable, Mapping
jpayne@68 49
jpayne@68 50 import _distutils_hack.override # noqa: F401
jpayne@68 51
jpayne@68 52 from ._path import StrPath
jpayne@68 53
jpayne@68 54 from distutils import log
jpayne@68 55 from distutils.util import convert_path
jpayne@68 56
jpayne@68 57 if TYPE_CHECKING:
jpayne@68 58 from setuptools import Distribution
jpayne@68 59
jpayne@68 60 chain_iter = itertools.chain.from_iterable
jpayne@68 61
jpayne@68 62
jpayne@68 63 def _valid_name(path: StrPath) -> bool:
jpayne@68 64 # Ignore invalid names that cannot be imported directly
jpayne@68 65 return os.path.basename(path).isidentifier()
jpayne@68 66
jpayne@68 67
jpayne@68 68 class _Filter:
jpayne@68 69 """
jpayne@68 70 Given a list of patterns, create a callable that will be true only if
jpayne@68 71 the input matches at least one of the patterns.
jpayne@68 72 """
jpayne@68 73
jpayne@68 74 def __init__(self, *patterns: str):
jpayne@68 75 self._patterns = dict.fromkeys(patterns)
jpayne@68 76
jpayne@68 77 def __call__(self, item: str) -> bool:
jpayne@68 78 return any(fnmatchcase(item, pat) for pat in self._patterns)
jpayne@68 79
jpayne@68 80 def __contains__(self, item: str) -> bool:
jpayne@68 81 return item in self._patterns
jpayne@68 82
jpayne@68 83
jpayne@68 84 class _Finder:
jpayne@68 85 """Base class that exposes functionality for module/package finders"""
jpayne@68 86
jpayne@68 87 ALWAYS_EXCLUDE: tuple[str, ...] = ()
jpayne@68 88 DEFAULT_EXCLUDE: tuple[str, ...] = ()
jpayne@68 89
jpayne@68 90 @classmethod
jpayne@68 91 def find(
jpayne@68 92 cls,
jpayne@68 93 where: StrPath = '.',
jpayne@68 94 exclude: Iterable[str] = (),
jpayne@68 95 include: Iterable[str] = ('*',),
jpayne@68 96 ) -> list[str]:
jpayne@68 97 """Return a list of all Python items (packages or modules, depending on
jpayne@68 98 the finder implementation) found within directory 'where'.
jpayne@68 99
jpayne@68 100 'where' is the root directory which will be searched.
jpayne@68 101 It should be supplied as a "cross-platform" (i.e. URL-style) path;
jpayne@68 102 it will be converted to the appropriate local path syntax.
jpayne@68 103
jpayne@68 104 'exclude' is a sequence of names to exclude; '*' can be used
jpayne@68 105 as a wildcard in the names.
jpayne@68 106 When finding packages, 'foo.*' will exclude all subpackages of 'foo'
jpayne@68 107 (but not 'foo' itself).
jpayne@68 108
jpayne@68 109 'include' is a sequence of names to include.
jpayne@68 110 If it's specified, only the named items will be included.
jpayne@68 111 If it's not specified, all found items will be included.
jpayne@68 112 'include' can contain shell style wildcard patterns just like
jpayne@68 113 'exclude'.
jpayne@68 114 """
jpayne@68 115
jpayne@68 116 exclude = exclude or cls.DEFAULT_EXCLUDE
jpayne@68 117 return list(
jpayne@68 118 cls._find_iter(
jpayne@68 119 convert_path(str(where)),
jpayne@68 120 _Filter(*cls.ALWAYS_EXCLUDE, *exclude),
jpayne@68 121 _Filter(*include),
jpayne@68 122 )
jpayne@68 123 )
jpayne@68 124
jpayne@68 125 @classmethod
jpayne@68 126 def _find_iter(
jpayne@68 127 cls, where: StrPath, exclude: _Filter, include: _Filter
jpayne@68 128 ) -> Iterator[str]:
jpayne@68 129 raise NotImplementedError
jpayne@68 130
jpayne@68 131
jpayne@68 132 class PackageFinder(_Finder):
jpayne@68 133 """
jpayne@68 134 Generate a list of all Python packages found within a directory
jpayne@68 135 """
jpayne@68 136
jpayne@68 137 ALWAYS_EXCLUDE = ("ez_setup", "*__pycache__")
jpayne@68 138
jpayne@68 139 @classmethod
jpayne@68 140 def _find_iter(
jpayne@68 141 cls, where: StrPath, exclude: _Filter, include: _Filter
jpayne@68 142 ) -> Iterator[str]:
jpayne@68 143 """
jpayne@68 144 All the packages found in 'where' that pass the 'include' filter, but
jpayne@68 145 not the 'exclude' filter.
jpayne@68 146 """
jpayne@68 147 for root, dirs, files in os.walk(str(where), followlinks=True):
jpayne@68 148 # Copy dirs to iterate over it, then empty dirs.
jpayne@68 149 all_dirs = dirs[:]
jpayne@68 150 dirs[:] = []
jpayne@68 151
jpayne@68 152 for dir in all_dirs:
jpayne@68 153 full_path = os.path.join(root, dir)
jpayne@68 154 rel_path = os.path.relpath(full_path, where)
jpayne@68 155 package = rel_path.replace(os.path.sep, '.')
jpayne@68 156
jpayne@68 157 # Skip directory trees that are not valid packages
jpayne@68 158 if '.' in dir or not cls._looks_like_package(full_path, package):
jpayne@68 159 continue
jpayne@68 160
jpayne@68 161 # Should this package be included?
jpayne@68 162 if include(package) and not exclude(package):
jpayne@68 163 yield package
jpayne@68 164
jpayne@68 165 # Early pruning if there is nothing else to be scanned
jpayne@68 166 if f"{package}*" in exclude or f"{package}.*" in exclude:
jpayne@68 167 continue
jpayne@68 168
jpayne@68 169 # Keep searching subdirectories, as there may be more packages
jpayne@68 170 # down there, even if the parent was excluded.
jpayne@68 171 dirs.append(dir)
jpayne@68 172
jpayne@68 173 @staticmethod
jpayne@68 174 def _looks_like_package(path: StrPath, _package_name: str) -> bool:
jpayne@68 175 """Does a directory look like a package?"""
jpayne@68 176 return os.path.isfile(os.path.join(path, '__init__.py'))
jpayne@68 177
jpayne@68 178
jpayne@68 179 class PEP420PackageFinder(PackageFinder):
jpayne@68 180 @staticmethod
jpayne@68 181 def _looks_like_package(_path: StrPath, _package_name: str) -> bool:
jpayne@68 182 return True
jpayne@68 183
jpayne@68 184
jpayne@68 185 class ModuleFinder(_Finder):
jpayne@68 186 """Find isolated Python modules.
jpayne@68 187 This function will **not** recurse subdirectories.
jpayne@68 188 """
jpayne@68 189
jpayne@68 190 @classmethod
jpayne@68 191 def _find_iter(
jpayne@68 192 cls, where: StrPath, exclude: _Filter, include: _Filter
jpayne@68 193 ) -> Iterator[str]:
jpayne@68 194 for file in glob(os.path.join(where, "*.py")):
jpayne@68 195 module, _ext = os.path.splitext(os.path.basename(file))
jpayne@68 196
jpayne@68 197 if not cls._looks_like_module(module):
jpayne@68 198 continue
jpayne@68 199
jpayne@68 200 if include(module) and not exclude(module):
jpayne@68 201 yield module
jpayne@68 202
jpayne@68 203 _looks_like_module = staticmethod(_valid_name)
jpayne@68 204
jpayne@68 205
jpayne@68 206 # We have to be extra careful in the case of flat layout to not include files
jpayne@68 207 # and directories not meant for distribution (e.g. tool-related)
jpayne@68 208
jpayne@68 209
jpayne@68 210 class FlatLayoutPackageFinder(PEP420PackageFinder):
jpayne@68 211 _EXCLUDE = (
jpayne@68 212 "ci",
jpayne@68 213 "bin",
jpayne@68 214 "debian",
jpayne@68 215 "doc",
jpayne@68 216 "docs",
jpayne@68 217 "documentation",
jpayne@68 218 "manpages",
jpayne@68 219 "news",
jpayne@68 220 "newsfragments",
jpayne@68 221 "changelog",
jpayne@68 222 "test",
jpayne@68 223 "tests",
jpayne@68 224 "unit_test",
jpayne@68 225 "unit_tests",
jpayne@68 226 "example",
jpayne@68 227 "examples",
jpayne@68 228 "scripts",
jpayne@68 229 "tools",
jpayne@68 230 "util",
jpayne@68 231 "utils",
jpayne@68 232 "python",
jpayne@68 233 "build",
jpayne@68 234 "dist",
jpayne@68 235 "venv",
jpayne@68 236 "env",
jpayne@68 237 "requirements",
jpayne@68 238 # ---- Task runners / Build tools ----
jpayne@68 239 "tasks", # invoke
jpayne@68 240 "fabfile", # fabric
jpayne@68 241 "site_scons", # SCons
jpayne@68 242 # ---- Other tools ----
jpayne@68 243 "benchmark",
jpayne@68 244 "benchmarks",
jpayne@68 245 "exercise",
jpayne@68 246 "exercises",
jpayne@68 247 "htmlcov", # Coverage.py
jpayne@68 248 # ---- Hidden directories/Private packages ----
jpayne@68 249 "[._]*",
jpayne@68 250 )
jpayne@68 251
jpayne@68 252 DEFAULT_EXCLUDE = tuple(chain_iter((p, f"{p}.*") for p in _EXCLUDE))
jpayne@68 253 """Reserved package names"""
jpayne@68 254
jpayne@68 255 @staticmethod
jpayne@68 256 def _looks_like_package(_path: StrPath, package_name: str) -> bool:
jpayne@68 257 names = package_name.split('.')
jpayne@68 258 # Consider PEP 561
jpayne@68 259 root_pkg_is_valid = names[0].isidentifier() or names[0].endswith("-stubs")
jpayne@68 260 return root_pkg_is_valid and all(name.isidentifier() for name in names[1:])
jpayne@68 261
jpayne@68 262
jpayne@68 263 class FlatLayoutModuleFinder(ModuleFinder):
jpayne@68 264 DEFAULT_EXCLUDE = (
jpayne@68 265 "setup",
jpayne@68 266 "conftest",
jpayne@68 267 "test",
jpayne@68 268 "tests",
jpayne@68 269 "example",
jpayne@68 270 "examples",
jpayne@68 271 "build",
jpayne@68 272 # ---- Task runners ----
jpayne@68 273 "toxfile",
jpayne@68 274 "noxfile",
jpayne@68 275 "pavement",
jpayne@68 276 "dodo",
jpayne@68 277 "tasks",
jpayne@68 278 "fabfile",
jpayne@68 279 # ---- Other tools ----
jpayne@68 280 "[Ss][Cc]onstruct", # SCons
jpayne@68 281 "conanfile", # Connan: C/C++ build tool
jpayne@68 282 "manage", # Django
jpayne@68 283 "benchmark",
jpayne@68 284 "benchmarks",
jpayne@68 285 "exercise",
jpayne@68 286 "exercises",
jpayne@68 287 # ---- Hidden files/Private modules ----
jpayne@68 288 "[._]*",
jpayne@68 289 )
jpayne@68 290 """Reserved top-level module names"""
jpayne@68 291
jpayne@68 292
jpayne@68 293 def _find_packages_within(root_pkg: str, pkg_dir: StrPath) -> list[str]:
jpayne@68 294 nested = PEP420PackageFinder.find(pkg_dir)
jpayne@68 295 return [root_pkg] + [".".join((root_pkg, n)) for n in nested]
jpayne@68 296
jpayne@68 297
jpayne@68 298 class ConfigDiscovery:
jpayne@68 299 """Fill-in metadata and options that can be automatically derived
jpayne@68 300 (from other metadata/options, the file system or conventions)
jpayne@68 301 """
jpayne@68 302
jpayne@68 303 def __init__(self, distribution: Distribution):
jpayne@68 304 self.dist = distribution
jpayne@68 305 self._called = False
jpayne@68 306 self._disabled = False
jpayne@68 307 self._skip_ext_modules = False
jpayne@68 308
jpayne@68 309 def _disable(self):
jpayne@68 310 """Internal API to disable automatic discovery"""
jpayne@68 311 self._disabled = True
jpayne@68 312
jpayne@68 313 def _ignore_ext_modules(self):
jpayne@68 314 """Internal API to disregard ext_modules.
jpayne@68 315
jpayne@68 316 Normally auto-discovery would not be triggered if ``ext_modules`` are set
jpayne@68 317 (this is done for backward compatibility with existing packages relying on
jpayne@68 318 ``setup.py`` or ``setup.cfg``). However, ``setuptools`` can call this function
jpayne@68 319 to ignore given ``ext_modules`` and proceed with the auto-discovery if
jpayne@68 320 ``packages`` and ``py_modules`` are not given (e.g. when using pyproject.toml
jpayne@68 321 metadata).
jpayne@68 322 """
jpayne@68 323 self._skip_ext_modules = True
jpayne@68 324
jpayne@68 325 @property
jpayne@68 326 def _root_dir(self) -> StrPath:
jpayne@68 327 # The best is to wait until `src_root` is set in dist, before using _root_dir.
jpayne@68 328 return self.dist.src_root or os.curdir
jpayne@68 329
jpayne@68 330 @property
jpayne@68 331 def _package_dir(self) -> dict[str, str]:
jpayne@68 332 if self.dist.package_dir is None:
jpayne@68 333 return {}
jpayne@68 334 return self.dist.package_dir
jpayne@68 335
jpayne@68 336 def __call__(
jpayne@68 337 self, force: bool = False, name: bool = True, ignore_ext_modules: bool = False
jpayne@68 338 ):
jpayne@68 339 """Automatically discover missing configuration fields
jpayne@68 340 and modifies the given ``distribution`` object in-place.
jpayne@68 341
jpayne@68 342 Note that by default this will only have an effect the first time the
jpayne@68 343 ``ConfigDiscovery`` object is called.
jpayne@68 344
jpayne@68 345 To repeatedly invoke automatic discovery (e.g. when the project
jpayne@68 346 directory changes), please use ``force=True`` (or create a new
jpayne@68 347 ``ConfigDiscovery`` instance).
jpayne@68 348 """
jpayne@68 349 if force is False and (self._called or self._disabled):
jpayne@68 350 # Avoid overhead of multiple calls
jpayne@68 351 return
jpayne@68 352
jpayne@68 353 self._analyse_package_layout(ignore_ext_modules)
jpayne@68 354 if name:
jpayne@68 355 self.analyse_name() # depends on ``packages`` and ``py_modules``
jpayne@68 356
jpayne@68 357 self._called = True
jpayne@68 358
jpayne@68 359 def _explicitly_specified(self, ignore_ext_modules: bool) -> bool:
jpayne@68 360 """``True`` if the user has specified some form of package/module listing"""
jpayne@68 361 ignore_ext_modules = ignore_ext_modules or self._skip_ext_modules
jpayne@68 362 ext_modules = not (self.dist.ext_modules is None or ignore_ext_modules)
jpayne@68 363 return (
jpayne@68 364 self.dist.packages is not None
jpayne@68 365 or self.dist.py_modules is not None
jpayne@68 366 or ext_modules
jpayne@68 367 or hasattr(self.dist, "configuration")
jpayne@68 368 and self.dist.configuration
jpayne@68 369 # ^ Some projects use numpy.distutils.misc_util.Configuration
jpayne@68 370 )
jpayne@68 371
jpayne@68 372 def _analyse_package_layout(self, ignore_ext_modules: bool) -> bool:
jpayne@68 373 if self._explicitly_specified(ignore_ext_modules):
jpayne@68 374 # For backward compatibility, just try to find modules/packages
jpayne@68 375 # when nothing is given
jpayne@68 376 return True
jpayne@68 377
jpayne@68 378 log.debug(
jpayne@68 379 "No `packages` or `py_modules` configuration, performing "
jpayne@68 380 "automatic discovery."
jpayne@68 381 )
jpayne@68 382
jpayne@68 383 return (
jpayne@68 384 self._analyse_explicit_layout()
jpayne@68 385 or self._analyse_src_layout()
jpayne@68 386 # flat-layout is the trickiest for discovery so it should be last
jpayne@68 387 or self._analyse_flat_layout()
jpayne@68 388 )
jpayne@68 389
jpayne@68 390 def _analyse_explicit_layout(self) -> bool:
jpayne@68 391 """The user can explicitly give a package layout via ``package_dir``"""
jpayne@68 392 package_dir = self._package_dir.copy() # don't modify directly
jpayne@68 393 package_dir.pop("", None) # This falls under the "src-layout" umbrella
jpayne@68 394 root_dir = self._root_dir
jpayne@68 395
jpayne@68 396 if not package_dir:
jpayne@68 397 return False
jpayne@68 398
jpayne@68 399 log.debug(f"`explicit-layout` detected -- analysing {package_dir}")
jpayne@68 400 pkgs = chain_iter(
jpayne@68 401 _find_packages_within(pkg, os.path.join(root_dir, parent_dir))
jpayne@68 402 for pkg, parent_dir in package_dir.items()
jpayne@68 403 )
jpayne@68 404 self.dist.packages = list(pkgs)
jpayne@68 405 log.debug(f"discovered packages -- {self.dist.packages}")
jpayne@68 406 return True
jpayne@68 407
jpayne@68 408 def _analyse_src_layout(self) -> bool:
jpayne@68 409 """Try to find all packages or modules under the ``src`` directory
jpayne@68 410 (or anything pointed by ``package_dir[""]``).
jpayne@68 411
jpayne@68 412 The "src-layout" is relatively safe for automatic discovery.
jpayne@68 413 We assume that everything within is meant to be included in the
jpayne@68 414 distribution.
jpayne@68 415
jpayne@68 416 If ``package_dir[""]`` is not given, but the ``src`` directory exists,
jpayne@68 417 this function will set ``package_dir[""] = "src"``.
jpayne@68 418 """
jpayne@68 419 package_dir = self._package_dir
jpayne@68 420 src_dir = os.path.join(self._root_dir, package_dir.get("", "src"))
jpayne@68 421 if not os.path.isdir(src_dir):
jpayne@68 422 return False
jpayne@68 423
jpayne@68 424 log.debug(f"`src-layout` detected -- analysing {src_dir}")
jpayne@68 425 package_dir.setdefault("", os.path.basename(src_dir))
jpayne@68 426 self.dist.package_dir = package_dir # persist eventual modifications
jpayne@68 427 self.dist.packages = PEP420PackageFinder.find(src_dir)
jpayne@68 428 self.dist.py_modules = ModuleFinder.find(src_dir)
jpayne@68 429 log.debug(f"discovered packages -- {self.dist.packages}")
jpayne@68 430 log.debug(f"discovered py_modules -- {self.dist.py_modules}")
jpayne@68 431 return True
jpayne@68 432
jpayne@68 433 def _analyse_flat_layout(self) -> bool:
jpayne@68 434 """Try to find all packages and modules under the project root.
jpayne@68 435
jpayne@68 436 Since the ``flat-layout`` is more dangerous in terms of accidentally including
jpayne@68 437 extra files/directories, this function is more conservative and will raise an
jpayne@68 438 error if multiple packages or modules are found.
jpayne@68 439
jpayne@68 440 This assumes that multi-package dists are uncommon and refuse to support that
jpayne@68 441 use case in order to be able to prevent unintended errors.
jpayne@68 442 """
jpayne@68 443 log.debug(f"`flat-layout` detected -- analysing {self._root_dir}")
jpayne@68 444 return self._analyse_flat_packages() or self._analyse_flat_modules()
jpayne@68 445
jpayne@68 446 def _analyse_flat_packages(self) -> bool:
jpayne@68 447 self.dist.packages = FlatLayoutPackageFinder.find(self._root_dir)
jpayne@68 448 top_level = remove_nested_packages(remove_stubs(self.dist.packages))
jpayne@68 449 log.debug(f"discovered packages -- {self.dist.packages}")
jpayne@68 450 self._ensure_no_accidental_inclusion(top_level, "packages")
jpayne@68 451 return bool(top_level)
jpayne@68 452
jpayne@68 453 def _analyse_flat_modules(self) -> bool:
jpayne@68 454 self.dist.py_modules = FlatLayoutModuleFinder.find(self._root_dir)
jpayne@68 455 log.debug(f"discovered py_modules -- {self.dist.py_modules}")
jpayne@68 456 self._ensure_no_accidental_inclusion(self.dist.py_modules, "modules")
jpayne@68 457 return bool(self.dist.py_modules)
jpayne@68 458
jpayne@68 459 def _ensure_no_accidental_inclusion(self, detected: list[str], kind: str):
jpayne@68 460 if len(detected) > 1:
jpayne@68 461 from inspect import cleandoc
jpayne@68 462
jpayne@68 463 from setuptools.errors import PackageDiscoveryError
jpayne@68 464
jpayne@68 465 msg = f"""Multiple top-level {kind} discovered in a flat-layout: {detected}.
jpayne@68 466
jpayne@68 467 To avoid accidental inclusion of unwanted files or directories,
jpayne@68 468 setuptools will not proceed with this build.
jpayne@68 469
jpayne@68 470 If you are trying to create a single distribution with multiple {kind}
jpayne@68 471 on purpose, you should not rely on automatic discovery.
jpayne@68 472 Instead, consider the following options:
jpayne@68 473
jpayne@68 474 1. set up custom discovery (`find` directive with `include` or `exclude`)
jpayne@68 475 2. use a `src-layout`
jpayne@68 476 3. explicitly set `py_modules` or `packages` with a list of names
jpayne@68 477
jpayne@68 478 To find more information, look for "package discovery" on setuptools docs.
jpayne@68 479 """
jpayne@68 480 raise PackageDiscoveryError(cleandoc(msg))
jpayne@68 481
jpayne@68 482 def analyse_name(self):
jpayne@68 483 """The packages/modules are the essential contribution of the author.
jpayne@68 484 Therefore the name of the distribution can be derived from them.
jpayne@68 485 """
jpayne@68 486 if self.dist.metadata.name or self.dist.name:
jpayne@68 487 # get_name() is not reliable (can return "UNKNOWN")
jpayne@68 488 return
jpayne@68 489
jpayne@68 490 log.debug("No `name` configuration, performing automatic discovery")
jpayne@68 491
jpayne@68 492 name = (
jpayne@68 493 self._find_name_single_package_or_module()
jpayne@68 494 or self._find_name_from_packages()
jpayne@68 495 )
jpayne@68 496 if name:
jpayne@68 497 self.dist.metadata.name = name
jpayne@68 498
jpayne@68 499 def _find_name_single_package_or_module(self) -> str | None:
jpayne@68 500 """Exactly one module or package"""
jpayne@68 501 for field in ('packages', 'py_modules'):
jpayne@68 502 items = getattr(self.dist, field, None) or []
jpayne@68 503 if items and len(items) == 1:
jpayne@68 504 log.debug(f"Single module/package detected, name: {items[0]}")
jpayne@68 505 return items[0]
jpayne@68 506
jpayne@68 507 return None
jpayne@68 508
jpayne@68 509 def _find_name_from_packages(self) -> str | None:
jpayne@68 510 """Try to find the root package that is not a PEP 420 namespace"""
jpayne@68 511 if not self.dist.packages:
jpayne@68 512 return None
jpayne@68 513
jpayne@68 514 packages = remove_stubs(sorted(self.dist.packages, key=len))
jpayne@68 515 package_dir = self.dist.package_dir or {}
jpayne@68 516
jpayne@68 517 parent_pkg = find_parent_package(packages, package_dir, self._root_dir)
jpayne@68 518 if parent_pkg:
jpayne@68 519 log.debug(f"Common parent package detected, name: {parent_pkg}")
jpayne@68 520 return parent_pkg
jpayne@68 521
jpayne@68 522 log.warn("No parent package detected, impossible to derive `name`")
jpayne@68 523 return None
jpayne@68 524
jpayne@68 525
jpayne@68 526 def remove_nested_packages(packages: list[str]) -> list[str]:
jpayne@68 527 """Remove nested packages from a list of packages.
jpayne@68 528
jpayne@68 529 >>> remove_nested_packages(["a", "a.b1", "a.b2", "a.b1.c1"])
jpayne@68 530 ['a']
jpayne@68 531 >>> remove_nested_packages(["a", "b", "c.d", "c.d.e.f", "g.h", "a.a1"])
jpayne@68 532 ['a', 'b', 'c.d', 'g.h']
jpayne@68 533 """
jpayne@68 534 pkgs = sorted(packages, key=len)
jpayne@68 535 top_level = pkgs[:]
jpayne@68 536 size = len(pkgs)
jpayne@68 537 for i, name in enumerate(reversed(pkgs)):
jpayne@68 538 if any(name.startswith(f"{other}.") for other in top_level):
jpayne@68 539 top_level.pop(size - i - 1)
jpayne@68 540
jpayne@68 541 return top_level
jpayne@68 542
jpayne@68 543
jpayne@68 544 def remove_stubs(packages: list[str]) -> list[str]:
jpayne@68 545 """Remove type stubs (:pep:`561`) from a list of packages.
jpayne@68 546
jpayne@68 547 >>> remove_stubs(["a", "a.b", "a-stubs", "a-stubs.b.c", "b", "c-stubs"])
jpayne@68 548 ['a', 'a.b', 'b']
jpayne@68 549 """
jpayne@68 550 return [pkg for pkg in packages if not pkg.split(".")[0].endswith("-stubs")]
jpayne@68 551
jpayne@68 552
jpayne@68 553 def find_parent_package(
jpayne@68 554 packages: list[str], package_dir: Mapping[str, str], root_dir: StrPath
jpayne@68 555 ) -> str | None:
jpayne@68 556 """Find the parent package that is not a namespace."""
jpayne@68 557 packages = sorted(packages, key=len)
jpayne@68 558 common_ancestors = []
jpayne@68 559 for i, name in enumerate(packages):
jpayne@68 560 if not all(n.startswith(f"{name}.") for n in packages[i + 1 :]):
jpayne@68 561 # Since packages are sorted by length, this condition is able
jpayne@68 562 # to find a list of all common ancestors.
jpayne@68 563 # When there is divergence (e.g. multiple root packages)
jpayne@68 564 # the list will be empty
jpayne@68 565 break
jpayne@68 566 common_ancestors.append(name)
jpayne@68 567
jpayne@68 568 for name in common_ancestors:
jpayne@68 569 pkg_path = find_package_path(name, package_dir, root_dir)
jpayne@68 570 init = os.path.join(pkg_path, "__init__.py")
jpayne@68 571 if os.path.isfile(init):
jpayne@68 572 return name
jpayne@68 573
jpayne@68 574 return None
jpayne@68 575
jpayne@68 576
jpayne@68 577 def find_package_path(
jpayne@68 578 name: str, package_dir: Mapping[str, str], root_dir: StrPath
jpayne@68 579 ) -> str:
jpayne@68 580 """Given a package name, return the path where it should be found on
jpayne@68 581 disk, considering the ``package_dir`` option.
jpayne@68 582
jpayne@68 583 >>> path = find_package_path("my.pkg", {"": "root/is/nested"}, ".")
jpayne@68 584 >>> path.replace(os.sep, "/")
jpayne@68 585 './root/is/nested/my/pkg'
jpayne@68 586
jpayne@68 587 >>> path = find_package_path("my.pkg", {"my": "root/is/nested"}, ".")
jpayne@68 588 >>> path.replace(os.sep, "/")
jpayne@68 589 './root/is/nested/pkg'
jpayne@68 590
jpayne@68 591 >>> path = find_package_path("my.pkg", {"my.pkg": "root/is/nested"}, ".")
jpayne@68 592 >>> path.replace(os.sep, "/")
jpayne@68 593 './root/is/nested'
jpayne@68 594
jpayne@68 595 >>> path = find_package_path("other.pkg", {"my.pkg": "root/is/nested"}, ".")
jpayne@68 596 >>> path.replace(os.sep, "/")
jpayne@68 597 './other/pkg'
jpayne@68 598 """
jpayne@68 599 parts = name.split(".")
jpayne@68 600 for i in range(len(parts), 0, -1):
jpayne@68 601 # Look backwards, the most specific package_dir first
jpayne@68 602 partial_name = ".".join(parts[:i])
jpayne@68 603 if partial_name in package_dir:
jpayne@68 604 parent = package_dir[partial_name]
jpayne@68 605 return os.path.join(root_dir, parent, *parts[i:])
jpayne@68 606
jpayne@68 607 parent = package_dir.get("") or ""
jpayne@68 608 return os.path.join(root_dir, *parent.split("/"), *parts)
jpayne@68 609
jpayne@68 610
jpayne@68 611 def construct_package_dir(packages: list[str], package_path: StrPath) -> dict[str, str]:
jpayne@68 612 parent_pkgs = remove_nested_packages(packages)
jpayne@68 613 prefix = Path(package_path).parts
jpayne@68 614 return {pkg: "/".join([*prefix, *pkg.split(".")]) for pkg in parent_pkgs}