stubber.codemod.enrich

Enrich firmware stubs by copying docstrings and parameter information from doc-stubs or python source code. Both (.py or .pyi) files are supported.

Attributes

_ENRICH_CACHE

ENRICH_CACHE_VERSION

_NO_CHANGE

_VOLATILE_TOKEN

_VOLATILE_PATTERNS

Classes

MergeMatch

A match between a target and source file to merge docstrings and typehints

Functions

_mask_volatile(→ Tuple[str, Dict[str, str]])

Replace per-board volatile lines with stable placeholders.

_restore_volatile(→ str)

Restore the original volatile lines that _mask_volatile replaced.

_enrich_cache_key(→ str)

Build a content-based cache key for a merge transform (one or more sources).

_run_merge_transform(→ Optional[str])

Run the (expensive) libcst merge transform and return the new code, or None.

_cached_merge_transform(→ Optional[str])

Run _run_merge_transform, transparently caching the result on disk.

clear_enrich_cache(→ int)

Clear the enrich cache. Returns the number of removed entries.

enrich_cache_stats(→ Dict[str, Any])

Return simple statistics about the enrich cache.

package_from_path(→ str)

Given a target and source path, return the package name based on the path.

upackage_equal(→ Tuple[bool, int])

Compare package names, return True if they are equal, ignoring an _ or u-prefix and case

source_target_candidates(...)

Given a target and source path, return a list of tuples of (target, source, package name) that are candidates for merging.

enrich_file(→ collections.abc.Generator[str, None, None])

Enrich firmware stubs using the doc-stubs in another folder.

merge_candidates(→ List[MergeMatch])

Generate a list of merge candidates for the source and target folders.

enrich_folder(→ int)

Enrich a folder containing firmware stubs using the doc-stubs in another folder.

guess_port_from_path(→ str)

Guess the port name from the folder contents.

Module Contents

stubber.codemod.enrich._ENRICH_CACHE = 'enrich'
stubber.codemod.enrich.ENRICH_CACHE_VERSION = '9'
stubber.codemod.enrich._NO_CHANGE = '\x00__enrich_no_change__\x00'
stubber.codemod.enrich._VOLATILE_TOKEN = '__ENRICH_VOLATILE_{}__'
stubber.codemod.enrich._VOLATILE_PATTERNS
stubber.codemod.enrich._mask_volatile(text: str) → Tuple[str, Dict[str, str]]

Replace per-board volatile lines with stable placeholders.

Returns the masked text and a mapping of placeholder -> original line so the original lines can be restored in the transform output.

Parameters:

text (str)

Return type:

Tuple[str, Dict[str, str]]

stubber.codemod.enrich._restore_volatile(text: str, restore: Dict[str, str]) → str

Restore the original volatile lines that _mask_volatile replaced.

Parameters:
Return type:

str

stubber.codemod.enrich._enrich_cache_key(source_texts: List[str], target_text: str, module_name: str, copy_params: bool, copy_docstr: bool, copy_returns: bool) → str

Build a content-based cache key for a merge transform (one or more sources).

Parameters:

  • source_texts (List[str])

  • target_text (str)

  • module_name (str)

  • copy_params (bool)

  • copy_docstr (bool)

  • copy_returns (bool)

Return type:

str

stubber.codemod.enrich._run_merge_transform(source_paths: List[pathlib.Path], target_text: str, module_name: str, filename: str, copy_params: bool, copy_docstr: bool, copy_returns: bool) → str | None

Run the (expensive) libcst merge transform and return the new code, or None.

All source_paths are merged into the target in a single transform pass, which avoids re-parsing the (potentially large) target once per source doc-stub.

Parameters:
Return type:

Optional[str]

stubber.codemod.enrich._cached_merge_transform(source_paths: List[pathlib.Path], target_text: str, module_name: str, filename: str, copy_params: bool, copy_docstr: bool, copy_returns: bool) → str | None

Run _run_merge_transform, transparently caching the result on disk.

Parameters:
Return type:

Optional[str]

stubber.codemod.enrich.clear_enrich_cache() → int

Clear the enrich cache. Returns the number of removed entries.

Return type:

int

stubber.codemod.enrich.enrich_cache_stats() → Dict[str, Any]

Return simple statistics about the enrich cache.

Return type:

Dict[str, Any]

class stubber.codemod.enrich.MergeMatch

A match between a target and source file to merge docstrings and typehints

target: pathlib.Path
source: pathlib.Path
target_pkg: str
source_pkg: str
is_match: bool
stubber.codemod.enrich.package_from_path(target: pathlib.Path, source: pathlib.Path | None = None) → str

Given a target and source path, return the package name based on the path.

Parameters:
Return type:

str

stubber.codemod.enrich.upackage_equal(src: str, target: str) → Tuple[bool, int]

Compare package names, return True if they are equal, ignoring an _ or u-prefix and case

Parameters:
Return type:

Tuple[bool, int]

stubber.codemod.enrich.source_target_candidates(source: pathlib.Path, target: pathlib.Path, ext: str | None = None) → collections.abc.Generator[MergeMatch, None, None]

Given a target and source path, return a list of tuples of (target, source, package name) that are candidates for merging. Goal is to match the target and source files based on the package name, to avoid mismatched merges of docstrings and typehints

Returns a generator of tuples of (target, source, target_package, source_package, is_partial_match)

Parameters:
Return type:

collections.abc.Generator[MergeMatch, None, None]

stubber.codemod.enrich.enrich_file(source_path: pathlib.Path | List[pathlib.Path], target_path: pathlib.Path, diff: bool = False, write_back: bool = False, copy_params: bool = False, copy_docstr: bool = False, copy_returns: bool = False) → collections.abc.Generator[str, None, None]

Enrich firmware stubs using the doc-stubs in another folder. Both (.py or .pyi) files are supported. Both source an target files must exist, and are assumed to match. Any matching of source and target files should be done before calling this function.

Parameters:

  • source_path (Union[pathlib.Path, List[pathlib.Path]]) – the path (or list of paths) to the doc-stub file(s) to enrich from. When several paths are given they are merged into the target in a single pass.

  • target_path (pathlib.Path) – the path to the firmware stub-file to enrich

  • diff (bool) – if True, return the diff between the original and the enriched source file

  • write_back (bool) – if True, write the enriched source file back to the source_path

  • copy_params (bool)

  • copy_docstr (bool)

  • copy_returns (bool)

Return type:

collections.abc.Generator[str, None, None]

Returns: - None or a string containing the diff between the original and the enriched source file

stubber.codemod.enrich.merge_candidates(source_folder: pathlib.Path, target_folder: pathlib.Path) → List[MergeMatch]

Generate a list of merge candidates for the source and target folders. Each target is matched with exactly one source file.

Parameters:
Return type:

List[MergeMatch]

stubber.codemod.enrich.enrich_folder(source_folder: pathlib.Path, target_folder: pathlib.Path, show_diff: bool = False, write_back: bool = False, require_docstub: bool = False, copy_params: bool = False, ext: str | None = None, copy_docstr: bool = False, copy_returns: bool = False) → int

Enrich a folder containing firmware stubs using the doc-stubs in another folder.

Returns the number of files enriched.

Parameters:
Return type:

int

stubber.codemod.enrich.guess_port_from_path(folder: pathlib.Path) → str

Guess the port name from the folder contents. ( could also be done based on the path name)

Parameters:

folder (pathlib.Path)

Return type:

str