Source code for click_extra.project

# Copyright Kevin Deldycke <kevin@deldycke.com> and contributors.
#
# This program is Free Software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; either version 2
# of the License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
"""Find a local project's entry point and packages from its packaging metadata.

{func}`read_project_scripts` lists the console scripts a project declares,
{func}`entry_point_package` names the top-level package of an entry point, and
{func}`locate_package_root` finds the directory a package imports from, whether
the project uses the flat or the src layout.

{func}`resolve_entry_point` combines them into the one entry point of a project,
under one ambiguity rule. The `wrap` command runs a project directory through
it, and {func}`detect_source_package` finds the package the `convert-to-myst`
command converts. {func}`discover_package_init_files` finds the `__init__.py`
of every package the scripts enter, for the `prebake` commands to bake.
"""

from __future__ import annotations

import logging
from pathlib import Path
from typing import NamedTuple

from .config.formats import ConfigFormat, parse_content

logger = logging.getLogger(__name__)

_SCRIPT_SOURCES = "[project.scripts] in pyproject.toml and console_scripts in setup.cfg"
"""Where {func}`read_project_scripts` looks, named when a project declares none."""


[docs] def read_project_scripts(directory: Path) -> dict[str, str]: """Read the console-script entry points declared by a local project. Inspects PEP 621 `[project.scripts]` in `pyproject.toml` first, then `console_scripts` under `[options.entry_points]` in `setup.cfg`. The dynamic `setup.py` form cannot be parsed statically and is ignored. :param directory: the project root, holding the packaging metadata. :return: a mapping of each console-script name to its `module:function` target. Empty when the project declares none. """ pyproject = directory / "pyproject.toml" if pyproject.is_file(): data = parse_content(ConfigFormat.TOML, pyproject.read_text(encoding="UTF-8")) scripts = data.get("project", {}).get("scripts", {}) if scripts: return {str(name): str(target) for name, target in scripts.items()} setup_cfg = directory / "setup.cfg" if setup_cfg.is_file(): # Deferred import: keeps configparser off the startup path of every CLI. from configparser import ConfigParser parser = ConfigParser() parser.read(setup_cfg, encoding="UTF-8") raw = parser.get("options.entry_points", "console_scripts", fallback="") scripts = {} for line in raw.strip().splitlines(): entry = line.strip() if not entry or "=" not in entry: continue name, _, target = entry.partition("=") scripts[name.strip()] = target.strip() return scripts return {}
[docs] def entry_point_package(target: str) -> str: """The top-level package an entry point target lives in. `orchard.cli:main` and `orchard:main` both answer `orchard`: the module path before the colon, cut at its first dot. :param target: the entry point, as `module:function`. :return: the top-level package name. """ return target.partition(":")[0].split(".", 1)[0]
[docs] def locate_package_root(directory: Path, top_package: str) -> Path | None: """Find which directory must be on `sys.path` to import `top_package`. Handles the two common project layouts: the flat layout (the package sits directly under the project root) and the src layout (under a `src/` subdirectory). A package directory, with or without an `__init__.py`, and a single-module `{top_package}.py` all count. :param directory: the project root. :param top_package: the top-level package name, as {func}`entry_point_package` reads it off an entry point. :return: the directory to prepend to `sys.path`, or `None` when the package cannot be located on disk. """ for root in (directory, directory / "src"): if (root / top_package).is_dir() or (root / f"{top_package}.py").is_file(): return root return None
[docs] class ProjectEntryPoint(NamedTuple): """The console-script entry point a project directory resolves to.""" target: str """The `module:function` target the console scripts name.""" root: Path | None """The directory to put on `sys.path` to import the target, or `None` when its package is not on disk.""" @property def module(self) -> str: """The module path of the target, before its colon.""" return self.target.partition(":")[0] @property def function(self) -> str: """The function name of the target, after its colon.""" return self.target.partition(":")[2] @property def package(self) -> str: """The top-level package of the target, see {func}`entry_point_package`.""" return entry_point_package(self.target)
[docs] def resolve_entry_point(directory: Path) -> ProjectEntryPoint: """Resolve the one console-script entry point of the project in `directory`. Reads the console scripts with {func}`read_project_scripts`, and locates the package of their target with {func}`locate_package_root`. The ambiguity rule: the console scripts must name a single `module:function` target. Several script names for one target, like a long name and its short alias, count as one. Two targets are ambiguous even when they live in one package: nothing tells which function the project means. :param directory: the project root, holding its `pyproject.toml` or `setup.cfg`. :return: the entry point, whose `root` is `None` when its package is not on disk. :raises ValueError: When the project declares no console script, or scripts naming several targets. """ scripts = read_project_scripts(directory) if not scripts: msg = ( f"No console-script entry point found in {directory.resolve()}. Looked" f" for {_SCRIPT_SOURCES}." ) raise ValueError(msg) targets = sorted(set(scripts.values())) if len(targets) > 1: listing = ", ".join( f"{name} = {target}" for name, target in sorted(scripts.items()) ) msg = f"Multiple console scripts in {directory.resolve()}: {listing}." raise ValueError(msg) target = targets[0] return ProjectEntryPoint( target, locate_package_root(directory, entry_point_package(target)) )
[docs] def detect_source_package(directory: Path | None = None) -> Path: """Locate the project's source package from its script entry point. Resolves the entry point with {func}`~click_extra.project.resolve_entry_point`, under its ambiguity rule, and derives the top-level package of its target (`"pkg.cli:main"` gives `pkg`), so the `convert-to-myst` command can run bare from a project root. The package is located under the project root or its `src/` folder, see {func}`~click_extra.project.locate_package_root`, and assumed under the project root when it is in neither. :param directory: The project root, holding its `pyproject.toml` or `setup.cfg`. Defaults to the current working directory. :return: Path of the detected package directory. :raises ValueError: When the project declares no script entry point, or scripts naming several targets. """ if directory is None: directory = Path() try: entry_point = resolve_entry_point(directory) except ValueError as error: msg = ( f"Cannot auto-detect the source directory: {error}" " Specify a directory argument." ) raise ValueError(msg) from error return (entry_point.root or directory) / entry_point.package
[docs] def discover_package_init_files(directory: Path | None = None) -> list[Path]: """Discover the `__init__.py` of each package a project's console scripts enter. Reads the console scripts of the project in `directory` with {func}`read_project_scripts`, takes the top-level package of each entry point and locates it on disk with {func}`locate_package_root`, so a src-layout project resolves like a flat one. :param directory: the project root. `None` reads the current directory. :return: each `__init__.py` found, once, in entry point order. Empty when the project declares no console script, or none of their packages is found. """ if directory is None: directory = Path() scripts = read_project_scripts(directory) if not scripts: logger.warning( "No console script found in %s: looked for %s.", directory, _SCRIPT_SOURCES ) return [] seen: set[Path] = set() paths: list[Path] = [] for target in scripts.values(): package = entry_point_package(target) root = locate_package_root(directory, package) or directory init_path = root / package / "__init__.py" if init_path in seen: continue seen.add(init_path) if init_path.is_file(): paths.append(init_path) else: logger.warning("Package init not found: %s", init_path) return paths