chore!: shorten get workspace func name and update docstrings in top …

…level mod

examples/sandbox/alex/config.py

@@ -4,7 +4,7 @@
 
 import cdf
 
-workspace = cdf.get_workspace_from_path(__file__).unwrap()
+workspace = cdf.get_workspace(__file__).unwrap()
 
 config = sqlmesh.Config.model_validate(
     dict(

examples/sandbox/alex/publishers/httpbin_publisher.py

@@ -4,7 +4,7 @@
 
 import cdf
 
-w = cdf.get_workspace_from_path(__file__).unwrap()
+w = cdf.get_workspace(__file__).unwrap()
 context = w.to_transform_context("local")
 
 df = context.fetchdf("SELECT * FROM mart.zips")

examples/sandbox/alex/scripts/nested/hello_script.py

@@ -1,5 +1,5 @@
 import cdf
 
-w = cdf.get_workspace_from_path(__file__).unwrap()
+w = cdf.get_workspace(__file__).unwrap()
 
 print(f"Hello, world from {w.name}!")

src/cdf/__init__.py

@@ -21,6 +21,15 @@ def find_nearest(path: PathLike = ".") -> Project:
     """Find the nearest project.
 
     Recursively searches for a project file in the parent directories.
+
+    Args:
+        path (PathLike, optional): The path to start searching from. Defaults to ".".
+
+    Raises:
+        FileNotFoundError: If no project is found.
+
+    Returns:
+        Project: The nearest project.
     """
     project = None
     path = Path(path).resolve()
@@ -37,6 +46,13 @@ def is_main(name: t.Optional[str] = None) -> bool:
     """Check if the current module is being run as the main program in cdf context.
 
     Also injects a hook in debug mode to allow dropping into user code via pdb.
+
+    Args:
+        name (str, optional): The name of the module to check. If None, the calling module is
+            checked. The most idiomatic usage is to pass `__name__` to check the current module.
+
+    Returns:
+        bool: True if the current module is the main program in cdf context.
     """
     frame = sys._getframe(1)
 
@@ -56,7 +72,14 @@ def debug_hook(etype, value, tb) -> None:
 
 
 def get_active_project() -> Project:
-    """Get the active project."""
+    """Get the active project.
+
+    Raises:
+        ValueError: If no valid project is found in the context.
+
+    Returns:
+        Project: The active project.
+    """
     obj = context.active_project.get()
     if isinstance(obj, Project):
         return obj
@@ -65,8 +88,15 @@ def get_active_project() -> Project:
     raise ValueError("No valid project found in context.")
 
 
-def get_workspace_from_path(path: PathLike) -> M.Result[Workspace, Exception]:
-    """Get a workspace from a path."""
+def get_workspace(path: PathLike = ".") -> M.Result[Workspace, Exception]:
+    """Get a workspace from a path.
+
+    Args:
+        path (PathLike, optional): The path to get the workspace from. Defaults to ".".
+
+    Returns:
+        M.Result[Workspace, Exception]: The workspace or an error.
+    """
     return find_nearest(path).bind(lambda p: p.get_workspace_from_path(path))
 
 
@@ -92,7 +122,7 @@ def transform_connection(type_: str, /, **kwargs) -> ConnectionConfig:
     "load_project",
     "find_nearest",
     "get_active_project",
-    "get_workspace_from_path",
+    "get_workspace",
     "logger",
     "with_config",
     "inject_config",

src/cdf/local.py

@@ -1,7 +1,5 @@
-from . import find_nearest, get_workspace_from_path
+from . import find_nearest, get_workspace
 
 settings = (
-    get_workspace_from_path(".")
-    .unwrap_or(find_nearest(".").unwrap())
-    .configuration.maps[0]
+    get_workspace(".").unwrap_or(find_nearest(".").unwrap()).configuration.maps[0]
 )