feat: ✨ add path_readme() (#1100)

## Description

This PR adds a `path_readme()` which was referred to in a TODO item in
#810
This function will probably have to be rewritten a bit when we fully
switch to the “local-first” approach, but I thought it made sense to add
it now, so we don’t forget about it.

<!-- Select quick/in-depth as necessary -->
This PR needs a quick review.

## Checklist

- [X] Added or updated tests
- [X] Ran `just run-all`

---------

Co-authored-by: Luke W. Johnston <lwjohnst86@users.noreply.github.com>

src/seedcase_sprout/core/__init__.py

@@ -20,6 +20,7 @@
     path_package,
     path_packages,
     path_properties,
+    path_readme,
 )
 from .path_resource_functions import (
     path_resource,
@@ -89,8 +90,9 @@
     # "delete_resource_properties",
     # Path -----
     "path_package",
-    "path_properties",
     "path_packages",
+    "path_properties",
+    "path_readme",
     "path_resource",
     "path_resource_data",
     "path_resource_raw",

src/seedcase_sprout/core/path_package_functions.py

@@ -116,3 +116,38 @@ def path_packages() -> Path:
     """
     path = path_sprout_global() / "packages"
     return create_dir(path) if not path.exists() else check_is_dir(path)
+
+
+def path_readme(package_id: int) -> Path:
+    """Get the path to the README file for the specified package.
+
+    Args:
+        package_id: The ID of the package.
+
+    Returns:
+        The absolute path to the README file.
+
+    Examples:
+        ```{python}
+        import os
+        import tempfile
+
+        import seedcase_sprout.core as sp
+
+        # Create a temporary directory for the example
+        with tempfile.TemporaryDirectory() as temp_dir:
+            os.environ["SPROUT_GLOBAL"] = temp_dir
+
+            # Create a package structure first
+            sp.create_package_properties(
+                properties=sp.example_package_properties(),
+                path=sp.path_packages()
+            )
+
+            # TODO: Need to modify after revising to "local-first"
+            # Get the path to the package README
+            # sp.path_readme(package_id=1)
+        ```
+    """
+    path = path_package(package_id=package_id) / "README.md"
+    return check_is_file(path)

tests/core/directory_structure_setup.py

@@ -17,6 +17,7 @@ def create_test_package_structure(global_path: Path, package_id: int) -> Path:
     path_package = global_path / "packages" / str(package_id)
     path_package.mkdir(parents=True)
     (path_package / "datapackage.json").touch()
+    (path_package / "README.md").touch()
 
     return path_package
 

tests/core/test_path_package_functions.py

@@ -6,6 +6,7 @@
     path_package,
     path_packages,
     path_properties,
+    path_readme,
 )
 from tests.core.directory_structure_setup import (
     create_test_package_structure,
@@ -27,6 +28,7 @@ def tmp_sprout_global(monkeypatch, tmp_path):
     [
         (path_package, "packages/1"),
         (path_properties, "packages/1/datapackage.json"),
+        (path_readme, "packages/1/README.md"),
     ],
 )
 def test_path_package_functions_return_expected_path(
@@ -39,7 +41,7 @@ def test_path_package_functions_return_expected_path(
 
 @mark.parametrize(
     "function",
-    [path_package, path_properties],
+    [path_package, path_properties, path_readme],
 )
 def test_path_package_functions_raise_error_if_package_id_does_not_exist(
     tmp_sprout_global, function