Add "traverse_to_file" to paths.py

Author: domdfcoding

domdf_python_tools/paths.py

@@ -68,12 +68,16 @@
 		"WindowsPathPlus",
 		"in_directory",
 		"_P",
+		"traverse_to_file",
 		]
 
 newline_default = object()
-_P = TypeVar("_P", bound=pathlib.PurePath)
+
+_P = TypeVar("_P", bound=pathlib.Path)
 """
 .. versionadded:: 0.11.0
+
+.. versionchanged:: 1.7.0  Now bound to :class:`pathlib.Path`.
 """
 
 
@@ -768,3 +772,28 @@ def is_mount(self):  # pragma: no cover
 		"""
 
 		raise NotImplementedError("Path.is_mount() is unsupported on this system")
+
+
+def traverse_to_file(base_directory: _P, *filename: PathLike, height: int = -1) -> _P:
+	r"""
+	Traverse the parents of the given directory until the desired file is found.
+
+	:param base_directory: The directory to start searching from
+	:param \*filename: The filename(s) to search for
+	:param height: The maximum height to traverse to.
+
+	.. versionadded:: 1.6.0
+	"""
+
+	if not filename:
+		raise TypeError("traverse_to_file expected 2 or more arguments, got 1")
+
+	for level, directory in enumerate((base_directory, *base_directory.parents)):
+		if height > 0 and ((level - 1) > height):
+			break
+
+		for file in filename:
+			if (directory / file).is_file():
+				return directory
+
+	raise FileNotFoundError(f"'{filename[0]!s}' not found in {base_directory}")

tests/test_paths.py

@@ -21,7 +21,7 @@
 
 # this package
 from domdf_python_tools import paths
-from domdf_python_tools.paths import PathPlus, clean_writer, copytree, in_directory
+from domdf_python_tools.paths import PathPlus, clean_writer, copytree, in_directory, traverse_to_file
 from domdf_python_tools.testing import not_pypy, not_windows
 
 
@@ -614,3 +614,36 @@ def test_in_directory(tmp_pathplus):
 		assert str(os.getcwd()) == str(tmpdir)
 
 	assert os.getcwd() == cwd
+
+
+@pytest.mark.parametrize(
+		"location, expected",
+		[
+				("foo.yml", ''),
+				("foo/foo.yml", "foo"),
+				("foo/bar/foo.yml", "foo/bar"),
+				("foo/bar/baz/foo.yml", "foo/bar/baz"),
+				]
+		)
+def test_traverse_to_file(tmp_pathplus, location, expected):
+	(tmp_pathplus / location).parent.maybe_make(parents=True)
+	(tmp_pathplus / location).touch()
+	assert traverse_to_file(tmp_pathplus / "foo" / "bar" / "baz", "foo.yml") == tmp_pathplus / expected
+
+
+# TODO: height
+
+
+def test_traverse_to_file_errors(tmp_pathplus):
+	(tmp_pathplus / "foo/bar/baz").parent.maybe_make(parents=True)
+	if os.sep == '/':
+		with pytest.raises(FileNotFoundError, match="'foo.yml' not found in .*/foo/bar/baz"):
+			traverse_to_file(tmp_pathplus / "foo" / "bar" / "baz", "foo.yml")
+	elif os.sep == '\\':
+		with pytest.raises(FileNotFoundError, match=r"'foo.yml' not found in .*\\foo\\bar\\baz"):
+			traverse_to_file(tmp_pathplus / "foo" / "bar" / "baz", "foo.yml")
+	else:
+		raise NotImplementedError
+
+	with pytest.raises(TypeError, match="traverse_to_file expected 2 or more arguments, got 1"):
+		traverse_to_file(tmp_pathplus)