Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/lib/python3.8/site-packages/setuptools/discovery.py @ 69:33d812a61356

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