pig.mapping

This module contains components related to mapping APIs within the PIG system. It includes functionalities for listing APIs, comparing arguments, handling git repositories, and various utilities to support API migration tasks.

api_lst

class pig.mapping.api_lst.GetAllApis(lib, py_path, mapping, typeshed_libs, target_api=None, history=None)

Extracts all APIs from a given library path. :param lib: The name of the library. :type lib: str

Parameters:

  • py_path (Union[str, Path]) – The path to the current Python file.

  • mapping (bool) – A boolean parameter indicating whether to consider self imports.

  • typeshed_libs (list) – A list of libraries available in typeshed.

  • target_api (Union[str, None]) – A tuple containing the original API name and its alias, if any. This is used when extracting specific APIs in the library.

  • history (Union[dict, None]) – A dictionary to keep track of visited files to avoid circular imports. At Initial stage, it is None. It is updated during the recursive visits.

property classes

Returns the list of extracted classes. :return: A list of tuples containing class names and their signatures. :rtype: list

property etcs

Returns the list of extracted miscellaneous items. :return: A list of tuples containing miscellaneous item names and their signatures. :rtype: list

property functions

Returns the list of extracted functions. :return: A list of tuples containing function names and their signatures. :rtype: list

get_signs(node)

Extracts the signatures from the given AST node. :param node: The AST node from which to extract signatures. Can be a class or function node. :type node: Union[ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef]

Returns:

A list of argument names extracted from the node.

Return type:

list[str]

property methods

Returns the list of extracted methods. :return: A list of tuples containing method names and their signatures. :rtype: list

property properties

Returns the list of extracted properties. :return: A list of tuples containing property names and their signatures. :rtype: list

class pig.mapping.api_lst.GetAllApisCython(target_api=None)

Extracts all APIs from a given library path, but in Cython files

Parameters:

target_api (Union[str, None]) – A tuple containing the original API name and its alias, if any. This is used when extracting specific APIs in the library.

property classes

Returns the list of extracted classes. :return: A list of tuples containing class names and their signatures. :rtype: list

property etcs

Returns the list of extracted miscellaneous items. :return: A list of tuples containing miscellaneous item names and their signatures. :rtype: list

property functions

Returns the list of extracted functions. :return: A list of tuples containing function names and their signatures. :rtype: list

get_signs(node)

Extracts the signatures from the given Cython AST node. :param node: The AST node from which to extract signatures. Can be a class or function node. :type node: Union[Nodes.ClassDefNode, Nodes.DefNode, Nodes.CFuncDefNode] :return: A list of argument names extracted from the node. :rtype: list[str]

property methods

Returns the list of extracted methods. :return: A list of tuples containing method names and their signatures. :rtype: list

property properties

Returns the list of extracted properties. :return: A list of tuples containing property names and their signatures. :rtype: list

pig.mapping.api_lst.extract_apis(lib, lib_path, typeshed_path)

Extracts API signatures from the specified library path.

Parameters:

  • libn (str) – A name of the library.

  • libn_path (Union[str, Path]) – A path to the library.

  • typeshed_path (Union[str, Path]) – The path to the typeshed directory.

Returns:

A dictionary mapping file paths to tuples containing sets of API signatures. Each tuple contains sets for classes, properties, functions, methods, and other entities.

Return type:

dict

pig.mapping.api_lst.get_all_apis(lib_path, imp_path, lib, typeshed_libs, py=False, mapping=False)

Extracts all APIs from the specified library path.

Parameters:

  • lib_path (Union[str, Path]) – The path to the library from which to extract APIs.

  • imp_path (str) – The import path corresponding to the library.

  • lib (str) – The name of the library.

  • typeshed_libs (list) – A list of libraries available in typeshed.

  • py (bool) – A boolean parameter indicating whether current file is directory or module. Defaults to False.

  • mapping (bool) – A boolean parameter indicating whether to consider self imports. Defaults to False.

Returns:

A dictionary containing the extracted APIs categorized by their import paths. Detailed type can be found in the extract_apis function.

Return type:

dict

pig.mapping.api_lst.typeshed(lib)

Extracts all APIs from the typeshed library. :param lib: The name of the library. :type lib: str :return: A dictionary containing the extracted APIs categorized by their import paths. Detailed type can be found in the extract_apis function. :rtype: dict

compare_arg

Functions to map similar APIs based on signature information.

pig.mapping.compare_arg.api_mapping(apios, libo, libn, libn_path, argso, top=-1)

Maps APIs from the original library to candidate APIs in the new library based on name and argument similarity.

Parameters:

  • apios (list[str]) – A list of original API names.

  • libo (str) – A name of the original library.

  • libn (str) – A name of the new library.

  • libn_path (Union[str, Path]) – A path to the new library.

  • argso (list) – A list of arguments from the original API.

  • top (int, optional) – An integer specifying the number of top candidates to return. Defaults to -1 (all candidates).

Returns:

A dictionary mapping original APIs to candidate APIs with similarity scores. A key is an original API name, and a value is a set of tuples containing candidate API name, signature, name similarity score, argument similarity score, and file path.

Return type:

dict[str : set[tuple[str, tuple, float, float, str]]]

pig.mapping.compare_arg.compute_greedy_arg_mapping(argso, argsn, libo, libn)

Computes an argument similarity score between two sets of arguments using a greedy matching algorithm.

Parameters:

  • argso (set) – A set of arguments from the original API.

  • argsn (set) – A set of arguments from the new API.

  • libo (str) – A name of the original library.

  • libn (str) – A name of the new library.

Returns:

A normalized similarity score between the two argument sets.

Return type:

float

pig.mapping.compare_arg.compute_string_similarity(word0, word1, libo, libn)

Computes a similarity score between two strings, considering special case.

“:param word1: The first string to compare. :type word1: str :param word2: The second string to compare. :type word2: str :param libo: A name of the original library. :type libo: str :param libn: A name of the new library. :type libn: str

Returns:

A similarity score between the two strings.

Return type:

float

gits

utils

pig.mapping.utils.update_dict(dict1, dict2)

Updates original dictionary with values from another dictionary by summing corresponding tuple elements. :param dict1: The original dictionary to be updated. :type dict1: dict

Parameters:

dict2 (dict) – The dictionary with values to add to the original dictionary.

Returns:

The updated original dictionary with summed tuple values.

Return type:

dict