Apply various suggestions from code review

- Minor fixups and adjustments
- Update several docstrings to PEP 257 style, with an imperative
  description as the first line
- Simplify `rewrite_comes_from` by making it always a callable

Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) <wk.cvs.github@sydorenko.org.ua>

Author: sirosen

piptools/_compat/pip_compat.py

@@ -87,12 +87,12 @@ def parse_requirements(
     comes_from_stdin: bool = False,
 ) -> Iterator[InstallRequirement]:
     # the `comes_from` data will be rewritten in different ways in different conditions
-    # each rewrite rule is expressible as a str->str function or as a static replacement
-    rewrite_comes_from: Callable[[str], str] | str
+    # each rewrite rule is expressible as a str->str function
+    rewrite_comes_from: Callable[[str], str]
 
     if comes_from_stdin:
         # if data is coming from stdin, then `comes_from="-r -"`
-        rewrite_comes_from = "-r -"
+        rewrite_comes_from = _rewrite_comes_from_to_hardcoded_stdin_value
     elif pathlib.Path(filename).is_absolute():
         # if the input path is absolute, just normalize paths to posix-style
         rewrite_comes_from = _normalize_comes_from_location
@@ -113,28 +113,32 @@ def parse_requirements(
             install_req.link = file_link
         install_req = copy_install_requirement(install_req)
 
-        if isinstance(rewrite_comes_from, str):
-            install_req.comes_from = rewrite_comes_from
-        else:
-            install_req.comes_from = rewrite_comes_from(install_req.comes_from)
+        install_req.comes_from = rewrite_comes_from(install_req.comes_from)
 
         yield install_req
 
 
+def _rewrite_comes_from_to_hardcoded_stdin_value(_: str, /) -> str:
+    """Produce the hardcoded ``comes_from`` value for stdin."""
+    return "-r -"
+
+
 def _relativize_comes_from_location(original_comes_from: str, /) -> str:
     """
+    Convert a ``comes_from`` path to a relative posix path.
+
     This is the rewrite rule used when ``-r`` or ``-c`` appears in
     ``comes_from`` data with an absolute path.
 
-    The ``-r`` or ``-c`` qualifier is retained, and the path is relativized
-    with respect to the CWD.
+    The ``-r`` or ``-c`` qualifier is retained, the path is relativized
+    with respect to the CWD, and the path is converted to posix style.
     """
     # require `-r` or `-c` as the source
     if not original_comes_from.startswith(("-r ", "-c ")):
         return original_comes_from
 
     # split on the space
-    prefix, _, suffix = original_comes_from.partition(" ")
+    prefix, space_sep, suffix = original_comes_from.partition(" ")
 
     file_path = pathlib.Path(suffix)
 
@@ -144,26 +148,30 @@ def _relativize_comes_from_location(original_comes_from: str, /) -> str:
 
     # make it relative to the current working dir
     suffix = file_path.relative_to(pathlib.Path.cwd()).as_posix()
-    return f"{prefix} {suffix}"
+    return f"{prefix}{space_sep}{suffix}"
 
 
 def _normalize_comes_from_location(original_comes_from: str, /) -> str:
     """
+    Convert a ``comes_from`` path to a posix-style path.
+
     This is the rewrite rule when ``-r`` or ``-c`` appears in ``comes_from``
-    data and the input path was absolute, meaning we should not relativize the locations.
+    data and the input path was absolute, meaning we should not relativize the
+    locations.
 
-    Instead, we apply minimal normalization, ensuring that posix-style paths are used.
+    The ``-r`` or ``-c`` qualifier is retained, and the path is converted to
+    posix style.
     """
     # require `-r` or `-c` as the source
     if not original_comes_from.startswith(("-r ", "-c ")):
         return original_comes_from
 
     # split on the space
-    prefix, _, suffix = original_comes_from.partition(" ")
+    prefix, space_sep, suffix = original_comes_from.partition(" ")
 
     # convert to a posix-style path
     suffix = pathlib.Path(suffix).as_posix()
-    return f"{prefix} {suffix}"
+    return f"{prefix}{space_sep}{suffix}"
 
 
 def create_wheel_cache(cache_dir: str, format_control: str | None = None) -> WheelCache:

tests/test_cli_compile.py

@@ -84,9 +84,9 @@ def populate(self, tmp_path: pathlib.Path) -> None:
     def get_path_to(self, filename: str) -> str:
         """Given a filename, find the (first) path to that filename in the contents."""
         return next(
-            k
-            for k in self.contents.keys()
-            if (k == filename) or k.endswith(f"/{filename}")
+            stub_file_path
+            for stub_file_path in self.contents
+            if (stub_file_path == filename) or stub_file_path.endswith(f"/{filename}")
         )
 
 
@@ -3891,7 +3891,9 @@ def test_stdout_should_not_be_read_when_stdin_is_not_a_plain_file(
     assert out.exit_code == 0, out
 
 
-@pytest.mark.parametrize("input_path_absolute", (True, False))
+@pytest.mark.parametrize(
+    "input_path_absolute", (True, False), ids=("absolute-input", "relative-input")
+)
 @pytest.mark.parametrize(
     "test_files_collection",
     (
@@ -3922,23 +3924,22 @@ def test_second_order_requirements_path_handling(
     test_files_collection,
 ):
     """
-    Given nested requirements files, the internal requirements will be written
-    in the output, and it will be absolute or relative depending only on
-    whether or not the initial path was absolute or relative.
+    Test normalization of ``-r`` includes in output.
+
+    Given nested requirements files, the internal requirements file path will
+    be written in the output, and it will be absolute or relative depending
+    only on whether or not the initial path was absolute or relative.
     """
     test_files_collection.populate(tmp_path)
 
     # the input path is given on the CLI as absolute or relative
     # and this determines the expected output path as well
-    if input_path_absolute:
-        input_path = (tmp_path / "requirements.in").as_posix()
-        output_path = (tmp_path / "requirements2.in").as_posix()
-    else:
-        input_path = "requirements.in"
-        output_path = "requirements2.in"
+    input_dir_path = tmp_path if input_path_absolute else pathlib.Path(".")
+    input_path = (input_dir_path / "requirements.in").as_posix()
+    output_path = (input_dir_path / "requirements2.in").as_posix()
 
-    with monkeypatch.context() as m:
-        m.chdir(tmp_path)
+    with monkeypatch.context() as revertable_ctx:
+        revertable_ctx.chdir(tmp_path)
 
         out = runner.invoke(
             cli,
@@ -3998,13 +3999,11 @@ def test_second_order_requirements_relative_path_in_separate_dir(
     pip_produces_absolute_paths,
 ):
     """
-    As in the above test, nested requirements file path handling.
-    But in this case, the primary variable is the relative location of the two
-    requirements.
+    Test normalization of ``-r`` includes when the requirements files are in
+    distinct directories.
 
-    The expectation is that the output path will be relative to the current
-    working directory, *not* relative to the dir containing the initial
-    requirements file.
+    Confirm that the output path will be relative to the current working
+    directory.
     """
     test_files_collection.populate(tmp_path)
     # the input is the path to 'requirements.in' relative to the starting dir
@@ -4021,8 +4020,8 @@ def test_second_order_requirements_relative_path_in_separate_dir(
             pathlib.Path(input_path).parent / ("../" * relative_segments) / output_path
         ).as_posix()
 
-    with monkeypatch.context() as m:
-        m.chdir(tmp_path)
+    with monkeypatch.context() as revertable_ctx:
+        revertable_ctx.chdir(tmp_path)
         out = runner.invoke(
             cli,
             [