cursus.core.utils.generic_path_discovery

Generic Path Discovery Algorithm for Project Folders.

This module implements a multi-directional recursive search algorithm to find uniquely named project folders across different directory structures. It serves as a robust fallback for path resolution when other strategies fail.

The algorithm searches both upward and downward from multiple reference points, making it suitable for complex nested project structures.

find_project_folder_generic(project_root_folder, max_depth_up=5, max_depth_down=3, reference_points=None)

Generic algorithm to find a uniquely named project folder.

Searches from multiple reference points in both upward and downward directions, using recursive traversal to handle nested directory structures.

Parameters:

• project_root_folder (str) – Name or path of project folder (e.g., “atoz_xgboost” or “projects/atoz_xgboost”)

• max_depth_up (int) – Maximum levels to search upward (default: 5)

• max_depth_down (int) – Maximum levels to search downward (default: 3)

• reference_points (List[Path] | None) – Optional list of starting points for search. If None, uses [Path.cwd(), cursus_package_root]

Returns:

Absolute path to project folder if found, None otherwise

Return type:

Path | None

Example

>>> find_project_folder_generic("atoz_xgboost")
PosixPath('/Users/user/workspace/projects/atoz_xgboost')

>>> find_project_folder_generic("projects/atoz_xgboost")
PosixPath('/Users/user/workspace/projects/atoz_xgboost')

class GenericPathDiscoveryMetrics

Bases: object

Track generic path discovery performance metrics.

record_success(search_time)

Record successful path discovery.

record_failure(search_time)

Record failed path discovery.

get_metrics()

Get current performance metrics.

get_generic_discovery_metrics()

Get current generic path discovery performance metrics.