Surface links to Stability Policy (GH-2848)

[etc/vim.git] / src / black / files.py

diff --git a/src/black/files.py b/src/black/files.py
index dfab9f7303962931b729de9bcaf38fd2e20066f2..18c84237bf0ecee74221ca48c25bc62fb995c41b 100644 (file)
--- a/src/black/files.py
+++ b/src/black/files.py
@@ -31,7 +31,7 @@ if TYPE_CHECKING:
 
 
 @lru_cache()
 
 
 @lru_cache()

-def find_project_root(srcs: Sequence[str]) -> Path:
+def find_project_root(srcs: Sequence[str]) -> Tuple[Path, str]:

     """Return a directory containing .git, .hg, or pyproject.toml.
 
     That directory will be a common parent of all files and directories
     """Return a directory containing .git, .hg, or pyproject.toml.
 
     That directory will be a common parent of all files and directories


@@ -39,6 +39,10 @@ def find_project_root(srcs: Sequence[str]) -> Path:
 
     If no directory in the tree contains a marker that would specify it's the
     project root, the root of the file system is returned.
 
     If no directory in the tree contains a marker that would specify it's the
     project root, the root of the file system is returned.

+
+    Returns a two-tuple with the first element as the project root path and
+    the second element as a string describing the method by which the
+    project root was discovered.

     """
     if not srcs:
         srcs = [str(Path.cwd().resolve())]
     """
     if not srcs:
         srcs = [str(Path.cwd().resolve())]


@@ -58,20 +62,20 @@ def find_project_root(srcs: Sequence[str]) -> Path:
 
     for directory in (common_base, *common_base.parents):
         if (directory / ".git").exists():
 
     for directory in (common_base, *common_base.parents):
         if (directory / ".git").exists():

-            return directory
+            return directory, ".git directory"

 
         if (directory / ".hg").is_dir():
 
         if (directory / ".hg").is_dir():

-            return directory
+            return directory, ".hg directory"

 
         if (directory / "pyproject.toml").is_file():
 
         if (directory / "pyproject.toml").is_file():

-            return directory
+            return directory, "pyproject.toml"

 
 

-    return directory
+    return directory, "file system root"

 
 
 def find_pyproject_toml(path_search_start: Tuple[str, ...]) -> Optional[str]:
     """Find the absolute filepath to a pyproject.toml if it exists"""
 
 
 def find_pyproject_toml(path_search_start: Tuple[str, ...]) -> Optional[str]:
     """Find the absolute filepath to a pyproject.toml if it exists"""

-    path_project_root = find_project_root(path_search_start)
+    path_project_root, _ = find_project_root(path_search_start)

     path_pyproject_toml = path_project_root / "pyproject.toml"
     if path_pyproject_toml.is_file():
         return str(path_pyproject_toml)
     path_pyproject_toml = path_project_root / "pyproject.toml"
     if path_pyproject_toml.is_file():
         return str(path_pyproject_toml)


@@ -133,7 +137,9 @@ def get_gitignore(root: Path) -> PathSpec:
 
 
 def normalize_path_maybe_ignore(
 
 
 def normalize_path_maybe_ignore(

-    path: Path, root: Path, report: Report
+    path: Path,
+    root: Path,
+    report: Optional[Report] = None,

 ) -> Optional[str]:
     """Normalize `path`. May return `None` if `path` was ignored.
 
 ) -> Optional[str]:
     """Normalize `path`. May return `None` if `path` was ignored.
 


@@ -143,12 +149,16 @@ def normalize_path_maybe_ignore(
         abspath = path if path.is_absolute() else Path.cwd() / path
         normalized_path = abspath.resolve().relative_to(root).as_posix()
     except OSError as e:
         abspath = path if path.is_absolute() else Path.cwd() / path
         normalized_path = abspath.resolve().relative_to(root).as_posix()
     except OSError as e:

-        report.path_ignored(path, f"cannot be read because {e}")
+        if report:
+            report.path_ignored(path, f"cannot be read because {e}")

         return None
 
     except ValueError:
         if path.is_symlink():
         return None
 
     except ValueError:
         if path.is_symlink():

-            report.path_ignored(path, f"is a symbolic link that points outside {root}")
+            if report:
+                report.path_ignored(
+                    path, f"is a symbolic link that points outside {root}"
+                )

             return None
 
         raise
             return None
 
         raise