cursus.core.utils.hybrid_path_resolution

Hybrid Path Resolution System for Cursus.

This module implements the hybrid strategy deployment path resolution system that works across Lambda/MODS bundled, development monorepo, and pip-installed separated deployment scenarios.

The hybrid approach uses two complementary strategies: 1. Package Location Discovery (Primary) - Uses Path(__file__) from cursus package 2. Working Directory Discovery (Fallback) - Uses Path.cwd() for traversal

class HybridResolutionMetrics

Bases: object

Track hybrid resolution performance metrics.

record_strategy_0_success(resolution_time)

Record successful Explicit Project Base Discovery.

record_strategy_1_success(resolution_time)

Record successful Package Location Discovery.

record_strategy_2_success(resolution_time)

Record successful Working Directory Discovery.

record_strategy_3_success(resolution_time)

Record successful Generic Path Discovery.

record_strategy_4_success(resolution_time)

Record successful Default Scripts Discovery.

record_failure(resolution_time)

Record resolution failure.

get_metrics()

Get current performance metrics.

class HybridResolutionConfig

Bases: object

Configuration for hybrid resolution rollout.

static is_hybrid_resolution_enabled()

Check if hybrid resolution is enabled via environment variable.

static get_hybrid_resolution_mode()

Get hybrid resolution mode: ‘full’, ‘fallback_only’, ‘disabled’.

resolve_anchor(anchor)

Normalize a file-or-directory anchor into a project-root path string.

This is the single shared normalizer used by every entry point (the DAG compiler, ExecutionDocumentGenerator, DAGConfigFactory, the scaffold, …) so anchor_file=__file__ and project_root=<dir> collapse to the same project root and resolve identically everywhere.

• A file (e.g. __file__ of the module defining generate_pipeline()) resolves to its parent directory — the project folder.

• A directory (e.g. Path(__file__).parent) resolves to itself.

• A path that does not exist yet but is “file-shaped” (has a suffix) is treated as a file and reduced to its parent, so anchor_file=__file__ works even before the module is materialized on disk.

Parameters:

anchor (str | Path | None) – A file path, a directory path, or None.

Returns:

Absolute path string of the project root, or None if anchor is falsy.

Return type:

str | None

set_project_root(project_root)

Push the project folder for caller-hook (Strategy 0) path resolution.

Accepts either a project directory (Path(__file__).parent) or a file (__file__) — both are normalized to the project root via resolve_anchor(), so callers may push whichever they have on hand.

Parameters:

project_root (str | Path | None) – Path to the user’s project folder or a file inside it (typically Path(__file__).parent or __file__ of the module defining generate_pipeline()), or None to clear it.

get_project_root()

Return the currently pushed project root (caller-hook anchor), or None.

get_hybrid_resolution_metrics()

Get current hybrid resolution performance metrics.

class HybridPathResolver

Bases: object

Hybrid path resolver that works across all deployment scenarios.

This class implements the core hybrid resolution algorithm that uses Package Location Discovery first, then Working Directory Discovery as fallback.

resolve_path(project_root_folder, relative_path)

Hybrid path resolution: Package location first, then working directory discovery.

This method implements the core hybrid resolution algorithm that works across all deployment scenarios: - Lambda/MODS bundled: Package location discovery - Development monorepo: Monorepo structure detection - Pip-installed separated: Working directory discovery fallback

Parameters:

• project_root_folder (str) – Root folder name for the user’s project

• relative_path (str) – Relative path from project root to target directory/file

Returns:

Resolved absolute path if found, None otherwise

Return type:

str | None

resolve_hybrid_path(project_root_folder, relative_path)

Convenience function for hybrid path resolution.

Parameters:

• project_root_folder (str) – Root folder name for the user’s project

• relative_path (str) – Relative path from project root to target

Returns:

Resolved absolute path if found, None otherwise

Return type:

str | None