feat: ✨ add path_*() functions (with their verify_*()'ers)

sprout/core/__init__.py

@@ -28,14 +28,19 @@
 # from .delete_resource_properties import *
 # Path -----
 # TODO: Consider having all these in one module.
-# from .path_resources import *
-# from .path_resource import *
-# from .path_resource_raw import *
-# from .path_resource_raw_files import *
-# from .path_resource_data import *
-# from .path_properties import *
-# from .path_package_database import *
-# from .path_package import *
+from .path_package_functions import (
+    path_package,
+    path_package_database,
+    path_package_properties,
+    path_packages,
+)
+from .path_resource_functions import (
+    path_resource,
+    path_resource_data,
+    path_resource_raw,
+    path_resource_raw_files,
+    path_resources,
+)
 from .path_sprout_root import path_sprout_root
 from .properties import (
     ConstraintsProperties,
@@ -92,14 +97,15 @@
     # "delete_resource_data",
     # "delete_resource_properties",
     # Path -----
-    # "path_resources",
-    # "path_resource",
-    # "path_resource_raw",
-    # "path_resource_raw_files",
-    # "path_resource_data",
-    # "path_properties",
-    # "path_package_database",
-    # "path_package",
+    "path_package",
+    "path_package_database",
+    "path_package_properties",
+    "path_packages",
+    "path_resource",
+    "path_resource_data",
+    "path_resource_raw",
+    "path_resource_raw_files",
+    "path_resources",
     "path_sprout_root",
     # Helpers -----
     # "pretty_json",

sprout/core/path_error_context.py

@@ -0,0 +1,49 @@
+from pathlib import Path
+
+from sprout.core.get_ids import get_ids
+from sprout.core.verify_is_dir import verify_is_dir
+from sprout.core.verify_is_file import verify_is_file
+
+
+def verify_is_dir_or_raise_error_with_id_context(path: Path, ids_path: Path):
+    """Verifies if path is a directory or raises error with existing ids.
+
+    Args:
+        path: Path to verify.
+        ids_path: Path to find existing ID's.
+
+    Returns:
+        Path, if path is a directory.
+
+    Raises:
+        NotADirectoryError: If the path is not a directory. The error message
+            includes existing ID's.
+    """
+    try:
+        verify_is_dir(path)
+        return path
+    except NotADirectoryError as e:
+        existing_ids = get_ids(ids_path)
+        raise NotADirectoryError(f"Existing ID's are {existing_ids}") from e
+
+
+def verify_is_file_or_raise_error_with_id_context(path: Path, ids_path: Path):
+    """Verifies if path is a file or raises error with existing ids.
+
+    Args:
+        path: Path to verify.
+        ids_path: Path to find existing ID's.
+
+    Returns:
+        Path, if path is a file.
+
+    Raises:
+        FileNotFoundError: If the path is not a file. The error message
+            includes existing ID's.
+    """
+    try:
+        verify_is_file(path)
+        return path
+    except FileNotFoundError as e:
+        existing_ids = get_ids(ids_path)
+        raise FileNotFoundError(f"Existing ID's are {existing_ids}") from e

sprout/core/path_package_functions.py

@@ -0,0 +1,63 @@
+from pathlib import Path
+
+from sprout.core.path_error_context import (
+    verify_is_dir_or_raise_error_with_id_context,
+    verify_is_file_or_raise_error_with_id_context,
+)
+from sprout.core.path_sprout_root import path_sprout_root
+from sprout.core.verify_is_dir import verify_is_dir
+
+
+def path_package(package_id: int) -> Path:
+    """Gets the absolute path to the specific package folder.
+
+    Args:
+        package_id: The ID of the package to get the folder path for.
+
+    Returns:
+        The absolute path to the package folder.
+    """
+    path = path_sprout_root() / "packages" / str(package_id)
+    return verify_is_dir_or_raise_error_with_id_context(path=path, ids_path=path.parent)
+
+
+def path_package_database(package_id: int) -> Path:
+    """Gets the absolute path to a given package's SQL database.
+
+    Args:
+        package_id: ID of the package.
+
+    Returns:
+        A Path to the package's database.
+    """
+    path = path_sprout_root() / "packages" / str(package_id) / "database.sql"
+    return verify_is_file_or_raise_error_with_id_context(
+        path=path, ids_path=path.parent.parent
+    )
+
+
+def path_package_properties(package_id: int) -> Path:
+    """Gets the absolute path to a given package's properties file.
+
+    Args:
+        package_id: ID of the package.
+
+    Returns:
+        A Path to the properties file.
+    """
+    path = path_sprout_root() / "packages" / str(package_id) / "datapackage.json"
+    return verify_is_file_or_raise_error_with_id_context(
+        path=path, ids_path=path.parent.parent
+    )
+
+
+def path_packages() -> Path:
+    """Gets the absolute path to the packages folder.
+
+    Returns:
+        A Path to the packages folder.
+
+    Raises:
+        NotADirectoryError: If the packages folder doesn't exist.
+    """
+    return verify_is_dir(path_sprout_root() / "packages")

sprout/core/path_resource_functions.py

@@ -0,0 +1,120 @@
+from pathlib import Path
+
+from sprout.core.get_ids import get_ids
+from sprout.core.path_error_context import (
+    verify_is_dir_or_raise_error_with_id_context,
+    verify_is_file_or_raise_error_with_id_context,
+)
+from sprout.core.path_sprout_root import path_sprout_root
+from sprout.core.verify_is_dir import verify_is_dir
+
+
+def path_resource(package_id: int, resource_id: int) -> Path:
+    """Gets the absolute path to a given resource of a given package.
+
+    Args:
+        package_id: ID of the package.
+        resource_id: ID of the resource.
+
+    Returns:
+        A Path to the resource.
+    """
+    path = (
+        path_sprout_root()
+        / "packages"
+        / str(package_id)
+        / "resources"
+        / str(resource_id)
+    )
+    return verify_is_dir_or_raise_error_with_id_context(path=path, ids_path=path.parent)
+
+
+def path_resource_data(package_id: int, resource_id: int) -> Path:
+    """Gets the absolute path to a given resource's data (i.e., parquet) file.
+
+    Args:
+        package_id: ID of the package.
+        resource_id: ID of the resource.
+
+    Returns:
+        A Path to the resource's data file.
+    """
+    path = (
+        path_sprout_root()
+        / "packages"
+        / str(package_id)
+        / "resources"
+        / str(resource_id)
+        / "data.parquet"
+    )
+    return verify_is_file_or_raise_error_with_id_context(
+        path=path, ids_path=path.parent.parent
+    )
+
+
+def path_resource_raw(package_id: int, resource_id: int) -> Path:
+    """Gets the absolute path to a given resource's raw folder.
+
+    Args:
+        package_id: ID of the package.
+        resource_id: ID of the resource.
+
+    Returns:
+        A Path to the resource's raw folder.
+    """
+    path = (
+        path_sprout_root()
+        / "packages"
+        / str(package_id)
+        / "resources"
+        / str(resource_id)
+        / "raw"
+    )
+    return verify_is_dir_or_raise_error_with_id_context(
+        path=path, ids_path=path.parent.parent
+    )
+
+
+def path_resource_raw_files(package_id: int, resource_id: int) -> list[Path]:
+    """Gets the absolute path to the raw files of  a resource.
+
+    Args:
+        package_id: ID of the package.
+        resource_id: ID of the resource.
+
+    Returns:
+        A list of Paths to the raw files of the resource.
+
+    Raises:
+        NotADirectoryError: If the package_id doesn't exist or the resource_id doesn't
+            exist within the package.
+    """
+    path = (
+        path_sprout_root()
+        / "packages"
+        / str(package_id)
+        / "resources"
+        / str(resource_id)
+        / "raw"
+    )
+
+    try:
+        verify_is_dir(path)
+        return [file for file in path.iterdir()]
+    except NotADirectoryError as e:
+        raise NotADirectoryError(
+            f"Existing ID's are {get_ids(path.parent.parent)}"
+        ) from e
+
+
+def path_resources(package_id: int) -> Path:
+    """Gets the absolute path to resources of a given package.
+
+    Args:
+        package_id: ID of the package to get the resource path from."
+
+    Returns:
+        A Path to the resources within the package.
+    """
+    path = path_sprout_root() / "packages" / str(package_id) / "resources"
+    return verify_is_dir_or_raise_error_with_id_context(path, path.parent.parent)

tests/core/directory_structure_setup.py

@@ -0,0 +1,47 @@
+from pathlib import Path
+
+from sprout.core.create_resource_structure import create_resource_structure
+
+
+def create_test_package_structure(root_path: Path, package_id: int) -> Path:
+    """Creates a package file structure (with empty files) for path function tests.
+
+    Args:
+        root_path: Root path to create the package structure.
+        package_id: ID of the package to create.
+
+    Returns:
+        Path of package.
+    """
+    # TODO: Use `create_package_structure()` function here when it's implemented.
+    path_package = root_path / "packages" / str(package_id)
+    path_package.mkdir(parents=True)
+    (path_package / "datapackage.json").touch()
+    (path_package / "database.sql").touch()
+
+    return path_package
+
+
+def create_test_resource_structure(
+    path_package: Path, raw_files: str | list[str]
+) -> list[Path]:
+    """Creates a resource file structure (with empty files) for path function tests.
+
+    Args:
+        path_package: Path to package.$
+        resource_id: ID of the resource to create.
+        raw_files: Name(s) of raw file(s).
+
+    Returns:
+        List with two Paths: one to the resource, one to it's raw directory.
+    """
+    path_resources = path_package / "resources"
+    if not (path_resources).exists():
+        path_resources.mkdir(parents=True)
+
+    path_list_resource = create_resource_structure(path_resources)
+    (path_list_resource[0] / "data.parquet").touch()
+    for raw_file in raw_files:
+        (path_list_resource[1] / raw_file).touch()
+
+    return path_list_resource