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.

Classes

MergeMatch

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

Functions

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

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, 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 (pathlib.Path) – the path to the firmware stub-file to enrich

  • docstub_path – the path to the file containing the doc-stubs

  • 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

  • target_path (pathlib.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