Module

readme.detect

Auto-detect project metadata from pyproject.toml, filesystem, and git.

1Class11Functions

Classes

ProjectContext 24 ▼
Template context returned by `detect_project`().

Template context returned bydetect_project().

Attributes

Name Type Description
name str —
version str —
description str —
license str —
python_requires str —
dependencies list[str] —
has_zero_deps bool —
extras dict[str, Any] —
dev_dependencies dict[str, list[str]] —
has_cli bool —
cli_name str | None —
scripts dict[str, str] —
tree dict[str, Any] —
tree_str str —
has_tests bool —
has_docs bool —
has_ci bool —
test_command str —
build_tool str —
install_command str —
repo_url str —
author str —
keywords list[str] —
suggested_preset str —

Functions

walk_tree 3 dict[str, Any] ▼
Walk a directory into a nested dict suitable for tree rendering. Returns a dic…
def walk_tree(root: Path, *, depth: int = 2, ignore: set[str] | None = None) -> dict[str, Any]

Walk a directory into a nested dict suitable for tree rendering.

Returns a dict where keys are directory/file names and values are either nested dicts (for directories) orNone(for files).

Parameters
Name Type Description
root Path
depth int Default:2
ignore set[str] | None Default:None
Returns
dict[str, Any]
_extract_docstring 1 str | None ▼
Extract the first line of a Python file's module docstring.
def _extract_docstring(path: Path) -> str | None
Parameters
Name Type Description
path Path
Returns
str | None
annotate_tree 2 dict[str, Any] ▼
Add first-line docstrings as annotations to Python packages and modules. Modif…
def annotate_tree(root: Path, tree: dict[str, Any]) -> dict[str, Any]

Add first-line docstrings as annotations to Python packages and modules.

Modifies tree in place, adding__annotation__keys to entries that have extractable docstrings. Recurses into subdirectories.

Parameters
Name Type Description
root Path
tree dict[str, Any]
Returns
dict[str, Any]
collapse_tree 1 dict[str, Any] ▼
Collapse directories with too many children for readability. When a directory …
def collapse_tree(tree: dict[str, Any]) -> dict[str, Any]

Collapse directories with too many children for readability.

When a directory has more than_COLLAPSE_THRESHOLDentries, files are replaced with a single... and N filessummary while subdirectories are preserved.

Parameters
Name Type Description
tree dict[str, Any]
Returns
dict[str, Any]
_render_tree 2 str ▼
Render a nested dict as an ASCII tree string. Entries with an ``__annotation__…
def _render_tree(tree: dict[str, Any], prefix: str = '') -> str

Render a nested dict as an ASCII tree string.

Entries with an__annotation__ key get a # commentsuffix.

Parameters
Name Type Description
tree dict[str, Any]
prefix str Default:''
Returns
str
_detect_build_tool 2 tuple[str, str] ▼
Detect build tool and return (tool_name, install_command).
def _detect_build_tool(root: Path, pyproject: dict[str, Any]) -> tuple[str, str]
Parameters
Name Type Description
root Path
pyproject dict[str, Any]
Returns
tuple[str, str]
_detect_test_command 2 str ▼
Detect test framework and return the run command.
def _detect_test_command(root: Path, pyproject: dict[str, Any]) -> str
Parameters
Name Type Description
root Path
pyproject dict[str, Any]
Returns
str
_detect_repo_url 2 str | None ▼
Detect repository URL from pyproject or git remote.
def _detect_repo_url(pyproject: dict[str, Any], root: Path) -> str | None
Parameters
Name Type Description
pyproject dict[str, Any]
root Path
Returns
str | None
_detect_author 2 str | None ▼
Detect author from pyproject or git config.
def _detect_author(pyproject: dict[str, Any], root: Path) -> str | None
Parameters
Name Type Description
pyproject dict[str, Any]
root Path
Returns
str | None
detect_preset 1 str ▼
Auto-detect the best README preset based on project metadata. Priority: 1.…
def detect_preset(ctx: Mapping[str, Any]) -> str

Auto-detect the best README preset based on project metadata.

Priority:

1. Has CLI entrypoints → ``"cli"``
2. Has runtime dependencies → ``"library"``
3. Otherwise → ``"default"``
Parameters
Name Type Description
ctx Mapping[str, Any]
Returns
str
detect_project 2 ProjectContext ▼
Auto-detect project metadata from a directory. Reads ``pyproject.toml``, inspe…
def detect_project(root: Path, *, depth: int = 2) -> ProjectContext

Auto-detect project metadata from a directory.

Readspyproject.toml, inspects the filesystem for build tools, test frameworks, and directory structure, and falls back to git for repo URL and author information.

Parameters
Name Type Description
root Path

Project root directory.
depth int

How many levels deep to walk the directory tree (default 2).

Default:2
Returns
ProjectContext