Remove .marker example and add .here example

Author: jayqi

README.md

@@ -4,9 +4,9 @@
 
 Simple and short code examples to find the root directory of your project in different ways. This can be useful in projects where you are reading or writing data to directories inside your project directory. All examples return a [`pathlib.Path`](https://docs.python.org/3/library/pathlib.html) object.
 
-All code in this repository is licensed under the [MIT No Attribution (MIT-0) License](./LICENSE) and can be used without attribution.
+To use, just copy and paste one of the examples into your project. Make any adjustments as needed or desired. These examples are all fairly straightforward and generally have no external dependencies. All code in this repository is licensed under the [MIT No Attribution (MIT-0) License](./LICENSE) and can be used without attribution.
 
-If for some reason you prefer a take on a dependency instead of copy-pasting a small amount of code, see these packages: [pyprojroot](https://github.com/chendaniely/pyprojroot), [rootpath](https://github.com/grimen/python-rootpath)
+If for some reason you prefer to take on a dependency or to have a function resolve a bunch of criteria automagically, see these packages as alternatives: [pyprojroot](https://github.com/chendaniely/pyprojroot), [rootpath](https://github.com/grimen/python-rootpath)
 
 ## Cookbook
 
@@ -20,6 +20,8 @@ Table of contents:
 
 ### Find pyproject.toml file
 
+[`pyproject.toml`](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/) is a modern standard configuration file for packaging metadata and tools configuration. It's typically in the project root directory of Python projects.
+
 ```python
 from pathlib import Path
 
@@ -37,6 +39,8 @@ def proj_root_from_pyproject_toml() -> Path:
 
 ### Find pyproject.toml file matching project name
 
+If you're in a monorepo with multiple Python packages, you may want to find the specific intended `pyproject.toml` file by matching on its contents.
+
 ```python
 from pathlib import Path
 import tomllib
@@ -78,6 +82,8 @@ def proj_root_from_pyproject_toml() -> Path:
 
 ### Find .git directory
 
+If using Git as your version control system, there will be a `.git` directory in your project root.
+
 ```python
 from pathlib import Path
 
@@ -93,41 +99,42 @@ def proj_root_from_git() -> Path:
 ```
 
 
-### Find a specific file containing a specific value
+### Find a .here file
+
+Popularized by R's [here](https://here.r-lib.org/) package, some project root detection tools support finding a file named `.here`.
 
 ```python
 from pathlib import Path
 
 
-def proj_root_from_marker_file() -> Path:
-    """Find the nearest parent directory containing a file '.marker' whose contents are
-    'value'."""
-    marker_file_name = ".marker"
-    marker_contents = "value"
+def proj_root_from_here_file() -> Path:
+    """Find the nearest parent directory containing a file '.here'."""
     current_dir = Path.cwd()
     while current_dir.parent != current_dir:
-        if (current_dir / marker_file_name).exists():
-            if (current_dir / marker_file_name).read_text().strip() == marker_contents:
-                return current_dir
+        if (current_dir / ".here").exists():
+            return current_dir
         current_dir = current_dir.parent
-    raise RuntimeError(
-        f"{marker_file_name} containing '{marker_contents}' "
-        "not found in any parent directories."
-    )
+    raise RuntimeError("'.here' file not found in any parent directories.")
 ```
 
 
 ### Read from environment variable
 
+Environment variables are a good way specify configuration values that vary between running environments.
+
 ```python
 import os
 from pathlib import Path
 
 
 def proj_root_from_env_var() -> Path:
-    """Get the project root directory from an environment variable."""
+    """Get the project root directory from an environment variable. It must be an
+    absolute path."""
     proj_root = os.environ.get("PROJ_ROOT")
     if not proj_root:
         raise RuntimeError("PROJ_ROOT environment variable is not set.")
-    return Path(proj_root)
+    path = Path(proj_root)
+    if not path.is_absolute():
+        raise RuntimeError("PROJ_ROOT must be an absolute path.")
+    return path
 ```

src/_README.md.template

@@ -4,9 +4,9 @@
 
 Simple and short code examples to find the root directory of your project in different ways. This can be useful in projects where you are reading or writing data to directories inside your project directory. All examples return a [`pathlib.Path`](https://docs.python.org/3/library/pathlib.html) object.
 
-All code in this repository is licensed under the [MIT No Attribution (MIT-0) License](./LICENSE) and can be used without attribution.
+To use, just copy and paste one of the examples into your project. Make any adjustments as needed or desired. These examples are all fairly straightforward and generally have no external dependencies. All code in this repository is licensed under the [MIT No Attribution (MIT-0) License](./LICENSE) and can be used without attribution.
 
-If for some reason you prefer a take on a dependency instead of copy-pasting a small amount of code, see these packages: [pyprojroot](https://github.com/chendaniely/pyprojroot), [rootpath](https://github.com/grimen/python-rootpath)
+If for some reason you prefer to take on a dependency or to have a function resolve a bunch of criteria automagically, see these packages as alternatives: [pyprojroot](https://github.com/chendaniely/pyprojroot), [rootpath](https://github.com/grimen/python-rootpath)
 
 ## Cookbook
 
@@ -20,10 +20,14 @@ Table of contents:
 
 ### Find pyproject.toml file
 
+[`pyproject.toml`](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/) is a modern standard configuration file for packaging metadata and tools configuration. It's typically in the project root directory of Python projects.
+
 {find_pyproject_toml}
 
 ### Find pyproject.toml file matching project name
 
+If you're in a monorepo with multiple Python packages, you may want to find the specific intended `pyproject.toml` file by matching on its contents.
+
 {find_pyproject_toml_project_name}
 
 > [!TIP]
@@ -44,12 +48,18 @@ Table of contents:
 
 ### Find .git directory
 
+If using Git as your version control system, there will be a `.git` directory in your project root.
+
 {find_git}
 
-### Find a specific file containing a specific value
+### Find a .here file
 
-{find_marker_file}
+Popularized by R's [here](https://here.r-lib.org/) package, some project root detection tools support finding a file named `.here`.
+
+{find_here_file}
 
 ### Read from environment variable
 
+Environment variables are a good way specify configuration values that vary between running environments.
+
 {read_from_env_var}

src/examples/find_here_file.py

@@ -0,0 +1,11 @@
+from pathlib import Path
+
+
+def proj_root_from_here_file() -> Path:
+    """Find the nearest parent directory containing a file '.here'."""
+    current_dir = Path.cwd()
+    while current_dir.parent != current_dir:
+        if (current_dir / ".here").exists():
+            return current_dir
+        current_dir = current_dir.parent
+    raise RuntimeError("'.here' file not found in any parent directories.")

src/examples/find_marker_file.py

@@ -3,8 +3,12 @@
 
 
 def proj_root_from_env_var() -> Path:
-    """Get the project root directory from an environment variable."""
+    """Get the project root directory from an environment variable. It must be an
+    absolute path."""
     proj_root = os.environ.get("PROJ_ROOT")
     if not proj_root:
         raise RuntimeError("PROJ_ROOT environment variable is not set.")
-    return Path(proj_root)
+    path = Path(proj_root)
+    if not path.is_absolute():
+        raise RuntimeError("PROJ_ROOT must be an absolute path.")
+    return path

src/examples/read_from_env_var.py

@@ -0,0 +1,35 @@
+import pytest
+
+from examples.find_here_file import proj_root_from_here_file
+
+
+def test_find_here_current_wd(tmp_path, monkeypatch):
+    here_path = tmp_path / ".here"
+    here_path.touch()
+
+    monkeypatch.chdir(tmp_path)
+
+    assert proj_root_from_here_file() == tmp_path
+
+
+def test_find_here_in_parents(tmp_path, monkeypatch):
+    here_path = tmp_path / ".here"
+    here_path.touch()
+
+    subdir = tmp_path / "subdir"
+    subdir.mkdir()
+    monkeypatch.chdir(tmp_path / "subdir")
+    assert proj_root_from_here_file() == tmp_path
+
+    subsubdir = subdir / "subsubdir"
+    subsubdir.mkdir()
+    monkeypatch.chdir(subsubdir)
+    assert proj_root_from_here_file() == tmp_path
+
+
+def test_find_here_not_found(tmp_path, monkeypatch):
+    subdir = tmp_path / "subdir"
+    subdir.mkdir()
+    monkeypatch.chdir(subdir)
+    with pytest.raises(RuntimeError):
+        proj_root_from_here_file()