Exclude patterns (no tests, no docs)

Author: hukkin

src/mdformat/_cli.py

@@ -5,6 +5,7 @@
 import contextlib
 import itertools
 import logging
+import os.path
 from pathlib import Path
 import shutil
 import sys
@@ -52,12 +53,26 @@ def run(cli_args: Sequence[str]) -> int:  # noqa: C901
     renderer_warning_printer = RendererWarningPrinter()
     for path in file_paths:
         try:
-            toml_opts = read_toml_opts(path.parent if path else Path.cwd())
+            toml_opts, toml_path = read_toml_opts(path.parent if path else Path.cwd())
         except InvalidConfError as e:
             print_error(str(e))
             return 1
         opts: Mapping = {**DEFAULT_OPTS, **toml_opts, **cli_opts}
 
+        if sys.version_info >= (3, 13):
+            if is_excluded(path, opts["exclude"], toml_path, "exclude" in cli_opts):
+                continue
+        else:
+            if "exclude" in toml_opts:
+                print_error(
+                    "'exclude' patterns are only available on Python 3.13+.",
+                    paragraphs=[
+                        "Please remove the 'exclude' list from your .mdformat.toml"
+                        " or upgrade Python version."
+                    ],
+                )
+                return 1
+
         if path:
             path_str = str(path)
             # Unlike `path.read_text(encoding="utf-8")`, this preserves
@@ -157,6 +172,12 @@ def make_arg_parser(
         choices=("lf", "crlf", "keep"),
         help="output file line ending mode (default: lf)",
     )
+    if sys.version_info >= (3, 13):
+        parser.add_argument(
+            "--exclude",
+            action="append",
+            help="exclude files that match the pattern (multiple allowed)",
+        )
     for plugin in parser_extensions.values():
         if hasattr(plugin, "add_cli_options"):
             plugin.add_cli_options(parser)
@@ -173,7 +194,7 @@ def __init__(self, path: Path):
 def resolve_file_paths(path_strings: Iterable[str]) -> list[None | Path]:
     """Resolve pathlib.Path objects from filepath strings.
 
-    Convert path strings to pathlib.Path objects. Resolve symlinks.
+    Convert path strings to pathlib.Path objects.
     Check that all paths are either files, directories or stdin. If not,
     raise InvalidPath. Resolve directory paths to a list of file paths
     (ending with ".md").
@@ -184,23 +205,48 @@ def resolve_file_paths(path_strings: Iterable[str]) -> list[None | Path]:
             file_paths.append(None)
             continue
         path_obj = Path(path_str)
-        path_obj = _resolve_path(path_obj)
+        path_obj = _normalize_path(path_obj)
         if path_obj.is_dir():
             for p in path_obj.glob("**/*.md"):
-                p = _resolve_path(p)
-                file_paths.append(p)
-        else:
+                if p.is_file():
+                    p = _normalize_path(p)
+                    file_paths.append(p)
+        elif path_obj.is_file():
             file_paths.append(path_obj)
+        else:
+            raise InvalidPath(path_obj)
     return file_paths
 
 
-def _resolve_path(path: Path) -> Path:
-    """Resolve path.
+def is_excluded(
+    path: Path | None, patterns: list[str], toml_path: Path | None, excludes_from_cli: bool
+) -> bool:
+    if not path:
+        return False
+
+    if not excludes_from_cli and toml_path:
+        exclude_root = toml_path.parent
+    else:
+        exclude_root = Path.cwd()
+
+    try:
+        relative_path = path.relative_to(exclude_root)
+    except ValueError:
+        return False
+
+    return any(relative_path.full_match(pattern) for pattern in patterns)
+
+
+def _normalize_path(path: Path) -> Path:
+    """Normalize path.
 
-    Resolve symlinks. Raise `InvalidPath` if the path does not exist.
+    Make the path absolute, resolve any ".." sequences.
+    Do not resolve symlinks, as it would interfere with
+    'exclude' patterns.
+    Raise `InvalidPath` if the path does not exist.
     """
+    path = Path(os.path.abspath(path))
     try:
-        path = path.resolve()  # resolve symlinks
         path_exists = path.exists()
     except OSError:  # Catch "OSError: [WinError 123]" on Windows  # pragma: no cover
         path_exists = False

src/mdformat/_conf.py

@@ -10,6 +10,7 @@
     "wrap": "keep",
     "number": False,
     "end_of_line": "lf",
+    "exclude": [],
 }
 
 
@@ -24,12 +25,12 @@ class InvalidConfError(Exception):
 
 
 @functools.lru_cache()
-def read_toml_opts(conf_dir: Path) -> Mapping:
+def read_toml_opts(conf_dir: Path) -> tuple[Mapping, Path | None]:
     conf_path = conf_dir / ".mdformat.toml"
     if not conf_path.is_file():
         parent_dir = conf_dir.parent
         if conf_dir == parent_dir:
-            return {}
+            return {}, None
         return read_toml_opts(parent_dir)
 
     with open(conf_path, "rb") as f:
@@ -41,10 +42,10 @@ def read_toml_opts(conf_dir: Path) -> Mapping:
     _validate_keys(toml_opts, conf_path)
     _validate_values(toml_opts, conf_path)
 
-    return toml_opts
+    return toml_opts, conf_path
 
 
-def _validate_values(opts: Mapping, conf_path: Path) -> None:
+def _validate_values(opts: Mapping, conf_path: Path) -> None:  # noqa: C901
     if "wrap" in opts:
         wrap_value = opts["wrap"]
         if not (
@@ -58,6 +59,12 @@ def _validate_values(opts: Mapping, conf_path: Path) -> None:
     if "number" in opts:
         if not isinstance(opts["number"], bool):
             raise InvalidConfError(f"Invalid 'number' value in {conf_path}")
+    if "exclude" in opts:
+        if not isinstance(opts["exclude"], list):
+            raise InvalidConfError(f"Invalid 'exclude' value in {conf_path}")
+        for pattern in opts["exclude"]:
+            if not isinstance(pattern, str):
+                raise InvalidConfError(f"Invalid 'exclude' value in {conf_path}")
 
 
 def _validate_keys(opts: Mapping, conf_path: Path) -> None: