pytest-devtools 1.1.0__tar.gz → 1.2.0__tar.gz

{pytest_devtools-1.1.0 → pytest_devtools-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pytest-devtools
-Version: 1.1.0
+Version: 1.2.0
 Summary: Pytest plugin providing debug fixtures, ANSI-stripped capsys, whitespace-visible assertions, and terminal column management.
 Author: Nathaniel Landau
 Author-email: Nathaniel Landau <github@natelandau.com>
@@ -21,39 +21,42 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Testing
-Requires-Dist: pytest>=9.0.3
+Requires-Dist: pytest>=7
 Requires-Dist: rich>=15.0.0
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 
 # pytest-devtools
 
-Small pytest plugin that provides some niceties for writing and debugging tests.
+[![Automated Tests](https://github.com/natelandau/pytest-devtools/actions/workflows/automated-tests.yml/badge.svg)](https://github.com/natelandau/pytest-devtools/actions/workflows/automated-tests.yml)
+[![codecov](https://codecov.io/gh/natelandau/pytest-devtools/graph/badge.svg)](https://codecov.io/gh/natelandau/pytest-devtools)
+
+A pytest plugin that smooths over a few common annoyances when writing and debugging tests.
 
 ## Features
 
--   **Debug fixture** -- Pretty-print variables, paths, and data structures with Rich. Output appears only when tests fail (or always with `--print-debug`).
--   **ANSI-stripped capsys** -- Automatically strip ANSI escape sequences from captured output so assertions don't break on color codes.
--   **Visible whitespace** -- Replace invisible whitespace characters (tabs, trailing spaces, carriage returns, newlines) with Unicode symbols in assertion failure diffs.
--   **Terminal column width** -- Optionally set the `COLUMNS` environment variable so Rich and other terminal-aware libraries don't introduce unwanted line wraps.
+- **Debug fixture**: pretty-prints variables, paths, and data structures with [Rich](https://rich.readthedocs.io/), and only shows the output when a test fails.
+- **Stripped `capsys` output**: removes ANSI escape codes (and optionally the `tmp_path` prefix) from captured stdout/stderr so assertions stay readable.
+- **Visible whitespace in diffs**: replaces tabs, trailing spaces, carriage returns, and newlines with Unicode symbols when an assertion fails.
+- **Terminal column width control**: sets `COLUMNS` for every test so libraries that auto-wrap (Rich, Click, etc.) produce stable output.
 
 ## Installation
 
 ```bash
-# Using uv
+# uv
 uv add pytest-devtools
 
-# Using pip
+# pip
 pip install pytest-devtools
 ```
 
-**Requirements:** Python 3.11+ and pytest 7.0+
+**Requirements:** Python 3.10+ and pytest 7.0+.
 
-The plugin activates automatically once installed. No `conftest.py` changes are needed.
+The plugin registers itself through the `pytest11` entry point, so no `conftest.py` changes are needed.
 
 ## Debug Fixture
 
-The `debug` fixture gives you a callable that pretty-prints any Python object using Rich. Output is collected during the test and flushed to stderr only when the test fails.
+The `debug` fixture is a callable that pretty-prints any Python object using Rich. Output is buffered during the test and written to stderr only if the test fails (or always, with `--print-debug`).
 
 ### Basic Usage
 
@@ -69,7 +72,7 @@ def test_user_creation(debug, tmp_path):
     assert user["name"] == "Alice"
 ```
 
-On failure, stderr shows the Rich-formatted output between rule separators:
+When the test fails, stderr shows the buffered output between rule separators:
 
 ```
 ──────────────────────────── Debug ─────────────────────────────
@@ -79,7 +82,7 @@ On failure, stderr shows the Rich-formatted output between rule separators:
 
 ### Multiple Values and Titles
 
-Pass multiple arguments in a single call, and use `title` to label sections:
+Pass several arguments in a single call, and use `title` to label the section:
 
 ```python
 def test_transform(debug):
@@ -90,7 +93,7 @@ def test_transform(debug):
 
 ### Per-Call Options
 
-Every option can be overridden on a per-call basis:
+Override any option on a single call:
 
 ```python
 def test_deep_structure(debug, tmp_path):
@@ -114,10 +117,10 @@ def test_deep_structure(debug, tmp_path):
 
 ### Path Handling
 
-When you pass a `pathlib.Path` to `debug`:
+When you pass a `pathlib.Path`:
 
--   **tmp_path stripping** (default: on) -- If the path is inside `tmp_path`, only the relative portion is shown. A path like `/var/folders/.../pytest-1234/test_foo0/subdir/file.txt` displays as `subdir/file.txt`.
--   **Directory listing** (default: off) -- When enabled and the path is a directory, a Rich tree shows the full directory contents recursively.
+- `tmp_path` stripping (default: on). If the path is inside `tmp_path`, only the relative portion is shown. A path like `/var/folders/.../pytest-1234/test_foo0/subdir/file.txt` displays as `subdir/file.txt`.
+- Directory listing (default: off). When enabled and the path is a directory, a Rich tree shows the directory contents recursively.
 
 ### CLI Options
 
@@ -149,30 +152,34 @@ debug_show_type = false
 
 ### Option Precedence
 
-Per-call arguments take highest priority, then CLI flags, then INI settings:
+Per-call arguments win, then CLI flags, then INI settings:
 
 ```
 per-call override  >  CLI flag  >  INI option  >  built-in default
 ```
 
-## ANSI-Stripped capsys
+## Stripped `capsys` Output
 
-By default, `capsys.readouterr()` returns output with ANSI escape sequences removed. This makes assertions simpler when testing code that uses colored output (Rich, Click, Colorama, etc.).
+The plugin overrides the built-in `capsys` fixture so that `readouterr()` returns post-processed strings. Two transformations are available:
 
-### Basic Usage
+- ANSI escape stripping (default: on)
+- `tmp_path` prefix stripping (default: off, opt-in)
+
+Both can be disabled or enabled independently, and they compose when both are active.
+
+### ANSI Escape Stripping
+
+Tests that exercise code printing colored output (Rich, Click, Colorama, etc.) usually don't care about the escape codes. By default, they're removed before you see the captured string:
 
 ```python
 def test_greeting(capsys):
-    # Imagine this function uses Rich to print colored output
     print("\x1b[32mHello, world!\x1b[0m")
 
     captured = capsys.readouterr()
-    assert captured.out == "Hello, world!\n"  # No ANSI codes to worry about
+    assert captured.out == "Hello, world!\n"
 ```
 
-### Keeping ANSI Codes
-
-For tests that need to verify color output, disable stripping per-test with a marker:
+To keep the codes for a single test, mark it with `@pytest.mark.keep_ansi`:
 
 ```python
 import pytest
@@ -184,22 +191,54 @@ def test_color_codes(capsys):
     assert "\x1b[32m" in captured.out
 ```
 
-Or disable stripping globally with a CLI flag:
+To turn stripping off globally:
 
 ```bash
 pytest --no-strip-ansi
 ```
 
-### INI Option
+### `tmp_path` Stripping
+
+Code that prints a `tmp_path`-rooted file produces output like `/var/folders/.../pytest-1234/test_foo0/file.txt`, which is awkward to assert on. Opt in to capsys `tmp_path` stripping to collapse those prefixes to their relative portion:
+
+```python
+def test_writes_log(capsys, tmp_path):
+    log = tmp_path / "app.log"
+    print(f"wrote {log}")
+
+    captured = capsys.readouterr()
+    assert captured.out == "wrote app.log\n"
+```
+
+Enable it for one run:
+
+```bash
+pytest --capsys-strip-tmp-path
+```
+
+Or globally in `pyproject.toml`:
+
+```toml
+[tool.pytest.ini_options]
+capsys_strip_tmp_path = true
+```
+
+`--no-capsys-strip-tmp-path` overrides the INI setting for a single run. Stripping applies to both `captured.out` and `captured.err`.
+
+> [!NOTE]
+> When both transformations are active, ANSI codes are stripped first, then `tmp_path` prefixes. The order matters only if your output mixes the two, but the combined result is what you'd expect.
+
+### INI Options
 
 ```toml
 [tool.pytest.ini_options]
-strip_ansi = false
+strip_ansi = true                # default: true
+capsys_strip_tmp_path = false    # default: false
 ```
 
 ## Visible Whitespace in Assertions
 
-When two strings differ only by whitespace, pytest's default diff is hard to read. This plugin replaces invisible characters with visible Unicode symbols in assertion failure output.
+When two strings differ only in whitespace, pytest's default diff is hard to read. This plugin replaces invisible characters with visible Unicode symbols in the assertion failure message.
 
 ### Symbol Reference
 
@@ -231,20 +270,21 @@ Whitespace-visible comparison:
 
 ### Disabling
 
-Disable with the `--no-show-whitespace` CLI flag or in INI:
+Use the `--no-show-whitespace` CLI flag, or set the INI option:
 
 ```toml
 [tool.pytest.ini_options]
 show_whitespace = false
 ```
 
-> **Note:** Whitespace visibility only activates for `==` comparisons between strings, and only when the replacement actually changes the display. Non-string comparisons and strings without special whitespace are unaffected.
+> [!NOTE]
+> Whitespace visibility activates only for `==` comparisons between strings, and only when the replacement actually changes how the string displays. Non-string comparisons and strings without notable whitespace are unaffected.
 
 ## Terminal Column Width
 
-Many terminal-aware libraries (Rich, Click, etc.) detect the terminal width at runtime. In test environments, the detected width is often very small, causing unwanted line wraps in captured output. This plugin can set the `COLUMNS` environment variable for every test to prevent this.
+Many terminal-aware libraries (Rich, Click, etc.) detect terminal width at runtime. In test environments, the detected width is often very small, which causes unwanted line wraps in captured output. This plugin can set the `COLUMNS` environment variable for every test to keep output stable.
 
-This feature is **disabled by default**. Enable it with the `--columns` CLI flag or via INI options.
+The feature is **disabled by default**. Enable it with the `--columns` CLI flag or via INI options.
 
 ### CLI Option
 
@@ -256,26 +296,27 @@ pytest --columns=180
 
 ### INI Options
 
-Enable permanently in `pyproject.toml`:
+Enable it permanently in `pyproject.toml`:
 
 ```toml
 [tool.pytest.ini_options]
-set_columns = true   # Enable the feature
-columns = 180        # Value to set (default when enabled)
+set_columns = true   # turn the feature on
+columns = 180        # value to set when enabled
 ```
 
 The `--columns` CLI flag overrides the INI `columns` value when both are present.
 
 ## Configuration Summary
 
-All features can be configured via CLI flags, `pyproject.toml` INI options, or (for the debug fixture) per-call arguments.
+Every feature is configurable through CLI flags and `pyproject.toml` INI options. The debug fixture additionally supports per-call arguments.
 
-| Feature            | Enabled by default     | Enable/Disable with                                 |
-| ------------------ | ---------------------- | --------------------------------------------------- |
-| Debug fixture      | Output on failure only | N/A (always available)                              |
-| ANSI stripping     | Yes                    | `--no-strip-ansi` or `strip_ansi = false`           |
-| Visible whitespace | Yes                    | `--no-show-whitespace` or `show_whitespace = false` |
-| Column width       | No                     | `--columns=N` or `set_columns = true`               |
+| Feature                | Default               | Toggle with                                                       |
+| ---------------------- | --------------------- | ----------------------------------------------------------------- |
+| Debug fixture          | Output on failure     | Always available; `--print-debug` to also show on success         |
+| ANSI stripping         | On                    | `--no-strip-ansi` or `strip_ansi = false`                         |
+| `tmp_path` in `capsys` | Off                   | `--capsys-strip-tmp-path` or `capsys_strip_tmp_path = true`       |
+| Visible whitespace     | On                    | `--no-show-whitespace` or `show_whitespace = false`               |
+| Column width           | Off                   | `--columns=N` or `set_columns = true`                             |
 
 ## AI Policy
 

pytest_devtools-1.2.0/README.md

@@ -0,0 +1,299 @@
+# pytest-devtools
+
+[![Automated Tests](https://github.com/natelandau/pytest-devtools/actions/workflows/automated-tests.yml/badge.svg)](https://github.com/natelandau/pytest-devtools/actions/workflows/automated-tests.yml)
+[![codecov](https://codecov.io/gh/natelandau/pytest-devtools/graph/badge.svg)](https://codecov.io/gh/natelandau/pytest-devtools)
+
+A pytest plugin that smooths over a few common annoyances when writing and debugging tests.
+
+## Features
+
+- **Debug fixture**: pretty-prints variables, paths, and data structures with [Rich](https://rich.readthedocs.io/), and only shows the output when a test fails.
+- **Stripped `capsys` output**: removes ANSI escape codes (and optionally the `tmp_path` prefix) from captured stdout/stderr so assertions stay readable.
+- **Visible whitespace in diffs**: replaces tabs, trailing spaces, carriage returns, and newlines with Unicode symbols when an assertion fails.
+- **Terminal column width control**: sets `COLUMNS` for every test so libraries that auto-wrap (Rich, Click, etc.) produce stable output.
+
+## Installation
+
+```bash
+# uv
+uv add pytest-devtools
+
+# pip
+pip install pytest-devtools
+```
+
+**Requirements:** Python 3.10+ and pytest 7.0+.
+
+The plugin registers itself through the `pytest11` entry point, so no `conftest.py` changes are needed.
+
+## Debug Fixture
+
+The `debug` fixture is a callable that pretty-prints any Python object using Rich. Output is buffered during the test and written to stderr only if the test fails (or always, with `--print-debug`).
+
+### Basic Usage
+
+```python
+def test_user_creation(debug, tmp_path):
+    user = {"name": "Alice", "roles": ["admin", "editor"]}
+    debug(user)
+
+    config_path = tmp_path / "config.toml"
+    config_path.write_text("[settings]\nverbose = true")
+    debug(config_path)
+
+    assert user["name"] == "Alice"
+```
+
+When the test fails, stderr shows the buffered output between rule separators:
+
+```
+──────────────────────────── Debug ─────────────────────────────
+{'name': 'Alice', 'roles': ['admin', 'editor']}
+──────────────────────────── Debug ─────────────────────────────
+```
+
+### Multiple Values and Titles
+
+Pass several arguments in a single call, and use `title` to label the section:
+
+```python
+def test_transform(debug):
+    before = [1, 2, 3]
+    after = [x * 2 for x in before]
+    debug(before, after, title="Transform")
+```
+
+### Per-Call Options
+
+Override any option on a single call:
+
+```python
+def test_deep_structure(debug, tmp_path):
+    nested = {"a": {"b": {"c": {"d": "deep"}}}}
+
+    # Limit nesting depth
+    debug(nested, max_depth=2)
+
+    # Limit collection length
+    debug(list(range(100)), max_length=5)
+
+    # Show type annotations
+    debug(nested, show_type=True)
+
+    # Show directory tree for Path objects
+    debug(tmp_path, list_dir_contents=True)
+
+    # Disable tmp_path prefix stripping
+    debug(tmp_path / "output.txt", strip_tmp_path=False)
+```
+
+### Path Handling
+
+When you pass a `pathlib.Path`:
+
+- `tmp_path` stripping (default: on). If the path is inside `tmp_path`, only the relative portion is shown. A path like `/var/folders/.../pytest-1234/test_foo0/subdir/file.txt` displays as `subdir/file.txt`.
+- Directory listing (default: off). When enabled and the path is a directory, a Rich tree shows the directory contents recursively.
+
+### CLI Options
+
+| Flag                           | Description                                         |
+| ------------------------------ | --------------------------------------------------- |
+| `--print-debug`                | Always show debug output, even on passing tests     |
+| `--debug-strip-tmp-path`       | Strip `tmp_path` prefix from Path objects (default) |
+| `--no-debug-strip-tmp-path`    | Show full absolute paths                            |
+| `--debug-list-dir-contents`    | Show directory tree for Path directories            |
+| `--no-debug-list-dir-contents` | Don't list directory contents (default)             |
+| `--debug-max-depth=N`          | Limit nesting depth in pretty-printed output        |
+| `--debug-max-length=N`         | Limit collection length in pretty-printed output    |
+| `--debug-show-type`            | Show type annotations above each value              |
+| `--no-debug-show-type`         | Don't show type annotations (default)               |
+
+### INI Options
+
+Add these to `pyproject.toml` under `[tool.pytest.ini_options]`:
+
+```toml
+[tool.pytest.ini_options]
+print_debug = true
+debug_strip_tmp_path = true
+debug_list_dir_contents = false
+debug_max_depth = 4
+debug_max_length = 20
+debug_show_type = false
+```
+
+### Option Precedence
+
+Per-call arguments win, then CLI flags, then INI settings:
+
+```
+per-call override  >  CLI flag  >  INI option  >  built-in default
+```
+
+## Stripped `capsys` Output
+
+The plugin overrides the built-in `capsys` fixture so that `readouterr()` returns post-processed strings. Two transformations are available:
+
+- ANSI escape stripping (default: on)
+- `tmp_path` prefix stripping (default: off, opt-in)
+
+Both can be disabled or enabled independently, and they compose when both are active.
+
+### ANSI Escape Stripping
+
+Tests that exercise code printing colored output (Rich, Click, Colorama, etc.) usually don't care about the escape codes. By default, they're removed before you see the captured string:
+
+```python
+def test_greeting(capsys):
+    print("\x1b[32mHello, world!\x1b[0m")
+
+    captured = capsys.readouterr()
+    assert captured.out == "Hello, world!\n"
+```
+
+To keep the codes for a single test, mark it with `@pytest.mark.keep_ansi`:
+
+```python
+import pytest
+
+@pytest.mark.keep_ansi
+def test_color_codes(capsys):
+    print("\x1b[32mgreen\x1b[0m")
+    captured = capsys.readouterr()
+    assert "\x1b[32m" in captured.out
+```
+
+To turn stripping off globally:
+
+```bash
+pytest --no-strip-ansi
+```
+
+### `tmp_path` Stripping
+
+Code that prints a `tmp_path`-rooted file produces output like `/var/folders/.../pytest-1234/test_foo0/file.txt`, which is awkward to assert on. Opt in to capsys `tmp_path` stripping to collapse those prefixes to their relative portion:
+
+```python
+def test_writes_log(capsys, tmp_path):
+    log = tmp_path / "app.log"
+    print(f"wrote {log}")
+
+    captured = capsys.readouterr()
+    assert captured.out == "wrote app.log\n"
+```
+
+Enable it for one run:
+
+```bash
+pytest --capsys-strip-tmp-path
+```
+
+Or globally in `pyproject.toml`:
+
+```toml
+[tool.pytest.ini_options]
+capsys_strip_tmp_path = true
+```
+
+`--no-capsys-strip-tmp-path` overrides the INI setting for a single run. Stripping applies to both `captured.out` and `captured.err`.
+
+> [!NOTE]
+> When both transformations are active, ANSI codes are stripped first, then `tmp_path` prefixes. The order matters only if your output mixes the two, but the combined result is what you'd expect.
+
+### INI Options
+
+```toml
+[tool.pytest.ini_options]
+strip_ansi = true                # default: true
+capsys_strip_tmp_path = false    # default: false
+```
+
+## Visible Whitespace in Assertions
+
+When two strings differ only in whitespace, pytest's default diff is hard to read. This plugin replaces invisible characters with visible Unicode symbols in the assertion failure message.
+
+### Symbol Reference
+
+| Character              | Symbol | Name             |
+| ---------------------- | ------ | ---------------- |
+| Trailing space         | `·`    | Middle dot       |
+| Tab (`\t`)             | `→`    | Rightwards arrow |
+| Carriage return (`\r`) | `←`    | Leftwards arrow  |
+| Newline (`\n`)         | `↵`    | Return symbol    |
+
+### Example Output
+
+For a test like:
+
+```python
+def test_output():
+    assert "hello " == "hello"
+```
+
+The failure message shows:
+
+```
+AssertionError: 'hello·' == 'hello'
+
+Whitespace-visible comparison:
+  Left:  'hello·'
+  Right: 'hello'
+```
+
+### Disabling
+
+Use the `--no-show-whitespace` CLI flag, or set the INI option:
+
+```toml
+[tool.pytest.ini_options]
+show_whitespace = false
+```
+
+> [!NOTE]
+> Whitespace visibility activates only for `==` comparisons between strings, and only when the replacement actually changes how the string displays. Non-string comparisons and strings without notable whitespace are unaffected.
+
+## Terminal Column Width
+
+Many terminal-aware libraries (Rich, Click, etc.) detect terminal width at runtime. In test environments, the detected width is often very small, which causes unwanted line wraps in captured output. This plugin can set the `COLUMNS` environment variable for every test to keep output stable.
+
+The feature is **disabled by default**. Enable it with the `--columns` CLI flag or via INI options.
+
+### CLI Option
+
+Set `COLUMNS` for a single run:
+
+```bash
+pytest --columns=180
+```
+
+### INI Options
+
+Enable it permanently in `pyproject.toml`:
+
+```toml
+[tool.pytest.ini_options]
+set_columns = true   # turn the feature on
+columns = 180        # value to set when enabled
+```
+
+The `--columns` CLI flag overrides the INI `columns` value when both are present.
+
+## Configuration Summary
+
+Every feature is configurable through CLI flags and `pyproject.toml` INI options. The debug fixture additionally supports per-call arguments.
+
+| Feature                | Default               | Toggle with                                                       |
+| ---------------------- | --------------------- | ----------------------------------------------------------------- |
+| Debug fixture          | Output on failure     | Always available; `--print-debug` to also show on success         |
+| ANSI stripping         | On                    | `--no-strip-ansi` or `strip_ansi = false`                         |
+| `tmp_path` in `capsys` | Off                   | `--capsys-strip-tmp-path` or `capsys_strip_tmp_path = true`       |
+| Visible whitespace     | On                    | `--no-show-whitespace` or `show_whitespace = false`               |
+| Column width           | Off                   | `--columns=N` or `set_columns = true`                             |
+
+## AI Policy
+
+All AI generated content is and always will be meticulously reviewed and approved by the author.
+
+## License
+
+MIT

{pytest_devtools-1.1.0 → pytest_devtools-1.2.0}/pyproject.toml

@@ -10,13 +10,13 @@
         "Programming Language :: Python :: 3.14",
         "Topic :: Software Development :: Testing",
     ]
-    dependencies = ["pytest>=9.0.3", "rich>=15.0.0"]
+    dependencies = ["pytest>=7", "rich>=15.0.0"]
     description = "Pytest plugin providing debug fixtures, ANSI-stripped capsys, whitespace-visible assertions, and terminal column management."
     license = { file = "LICENSE" }
     name = "pytest-devtools"
     readme = "README.md"
     requires-python = ">=3.10"
-    version = "1.1.0"
+    version = "1.2.0"
 
     [project.entry-points.pytest11]
         pytest-devtools = "devtools.plugin"
@@ -31,18 +31,18 @@
 [dependency-groups]
     dev = [
         "commitizen>=4.15.0",
+        "coverage>=7.13.5",
         "duty>=1.9.0",
         "prek>=0.3.11",
         "pytest-clarity>=1.0.1",
+        "pytest-cov>=7.1.0",
         "pytest-mock>=3.15.1",
         "pytest-repeat>=0.9.4",
-        "pytest-sugar>=1.1.1",
-        "pytest-xdist>=3.8.0",
         "ruff>=0.15.12",
         "ty>=0.0.34",
         "typos>=1.46.0",
         "yamllint>=1.38.0",
-    ]
+]
 
 [tool.commitizen]
     bump_message               = "bump(release): v$current_version → v$new_version"
@@ -54,13 +54,40 @@
 
 [tool.pytest.ini_options]
 
-    addopts        = "--color=yes --doctest-modules --strict-config --strict-markers -n auto --dist loadfile"
+    addopts        = "--color=yes --doctest-modules --strict-config --strict-markers"
     cache_dir      = ".cache/pytest"
     filterwarnings = ['error', 'ignore:.*Pydantic.*:UserWarning', 'ignore::DeprecationWarning:']
     markers        = ["serial"]
     testpaths      = ["tests"]
     xfail_strict   = true
 
+[tool.coverage.report] # https://coverage.readthedocs.io/en/latest/config.html#report
+    exclude_lines = [
+        'assert_never',
+        'def __repr__',
+        'except [\w\s\._]+ as .*:',
+        'if TYPE_CHECKING:',
+        'if __name__ == .__main__.:',
+        'if typing.TYPE_CHECKING:',
+        'pragma: no cover',
+        'raise cappa\.Exit',
+    ]
+    fail_under = 20
+    # omit = ["src/neatfile/constants.py"]
+    precision    = 1
+    show_missing = true
+    skip_covered = true
+    skip_empty   = true
+
+[tool.coverage.run]
+    branch       = true
+    command_line = "--module pytest"
+    data_file    = ".cache/.coverage"
+    source       = ["src"]
+
+[tool.coverage.xml]
+    output = ".cache/coverage.xml"
+
 [tool.ruff] # https://github.com/charliermarsh/ruff
 
     exclude        = [".cache", ".dev", ".git", ".venv", ".worktrees", "_build", "_site", "build", "dist"]

pytest_devtools-1.2.0/src/devtools/_options.py

@@ -0,0 +1,38 @@
+"""Shared option resolution for pytest-devtools features."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    import pytest
+
+
+def resolve_option(
+    request: pytest.FixtureRequest,
+    name: str,
+    per_call: bool | int | None = None,  # noqa: FBT001
+) -> Any:
+    """Resolve a config option using per-call > CLI > INI precedence.
+
+    Per-call takes priority, then CLI flag, then INI option. Use a single
+    ``name`` for both the ``getoption`` dest and the INI key so call sites
+    only have to spell the option once.
+
+    Args:
+        request: The pytest fixture request.
+        name: The option name (matching both getoption dest and ini key).
+        per_call: The per-call override value, or None to fall through to
+            CLI/INI resolution.
+
+    Returns:
+        The resolved option value.
+    """
+    if per_call is not None:
+        return per_call
+
+    cli_value = request.config.getoption(name, default=None)
+    if cli_value is not None:
+        return cli_value
+
+    return request.config.getini(name)

pytest_devtools-1.2.0/src/devtools/capsys_strip.py

@@ -0,0 +1,196 @@
+"""ANSI escape sequence stripping for capsys captured output.
+
+Override pytest's built-in capsys fixture to automatically strip ANSI escape
+sequences from captured stdout and stderr, making assertions against captured
+output simpler and more reliable.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import re
+from typing import TYPE_CHECKING, Any
+
+import pytest
+from _pytest.capture import CaptureFixture, CaptureResult
+
+from devtools._options import resolve_option
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from _pytest.config import Config
+
+ANSI_PATTERN = re.compile(r"\x1b\[[0-9;]*m")
+
+
+def strip_ansi(text: str) -> str:
+    """Remove ANSI escape sequences from a string.
+
+    Args:
+        text: The string potentially containing ANSI escape sequences.
+
+    Returns:
+        The string with all ANSI SGR sequences removed.
+    """
+    return ANSI_PATTERN.sub("", text)
+
+
+def strip_tmp_path(text: str, tmp_path: Path) -> str:
+    """Remove tmp_path prefix occurrences from a string.
+
+    Strip both ``str(tmp_path) + "/"`` and bare ``str(tmp_path)`` so that paths
+    nested under ``tmp_path`` collapse to their relative portion (matching the
+    behavior of the ``debug`` fixture's tmp_path stripping).
+
+    Args:
+        text: The captured output string.
+        tmp_path: The pytest ``tmp_path`` fixture value to strip.
+
+    Returns:
+        The string with tmp_path prefixes removed.
+    """
+    tmp_str = str(tmp_path)
+    return text.replace(f"{tmp_str}/", "").replace(tmp_str, "")
+
+
+def add_options(parser: pytest.Parser) -> None:
+    """Register CLI options for ANSI stripping.
+
+    Args:
+        parser: The pytest option parser to add options to.
+    """
+    group = parser.getgroup("devtools-capsys", "ANSI stripping for capsys")
+    group.addoption(
+        "--no-strip-ansi",
+        action="store_true",
+        default=False,
+        help="Disable automatic ANSI escape sequence stripping from capsys output",
+    )
+    group.addoption(
+        "--capsys-strip-tmp-path",
+        action="store_true",
+        default=None,
+        dest="capsys_strip_tmp_path",
+        help="Strip tmp_path prefix from capsys output (default: false)",
+    )
+    group.addoption(
+        "--no-capsys-strip-tmp-path",
+        action="store_false",
+        dest="capsys_strip_tmp_path",
+        help="Don't strip tmp_path prefix from capsys output",
+    )
+    parser.addini(
+        "strip_ansi",
+        type="bool",
+        default=True,
+        help="Enable/disable ANSI stripping from capsys output (default: true)",
+    )
+    parser.addini(
+        "capsys_strip_tmp_path",
+        type="bool",
+        default=False,
+        help="Strip tmp_path prefix from capsys output (default: false)",
+    )
+
+
+def configure(config: Config) -> None:
+    """Register the keep_ansi marker.
+
+    Args:
+        config: The pytest config object.
+    """
+    config.addinivalue_line(
+        "markers",
+        "keep_ansi: disable ANSI stripping from capsys for this test",
+    )
+
+
+def _should_strip_ansi(request: pytest.FixtureRequest) -> bool:
+    """Determine whether ANSI stripping should be applied for this test.
+
+    Args:
+        request: The pytest fixture request object.
+
+    Returns:
+        True if ANSI codes should be stripped, False otherwise.
+    """
+    if request.config.getoption("no_strip_ansi", default=False):
+        return False
+
+    if not request.config.getini("strip_ansi"):
+        return False
+
+    return not request.node.get_closest_marker("keep_ansi")
+
+
+class StrippedCaptureFixture:
+    """Wrapper around CaptureFixture that strips noise from readouterr() results.
+
+    Delegate all attribute access to the underlying CaptureFixture, intercepting
+    only readouterr() to optionally strip ANSI escape sequences and/or the
+    tmp_path prefix from captured stdout/stderr.
+    """
+
+    def __init__(
+        self,
+        original: CaptureFixture[str],
+        *,
+        request: pytest.FixtureRequest,
+        ansi: bool,
+        tmp_path: bool,
+    ) -> None:
+        self._original = original
+        self._request = request
+        self._strip_ansi_enabled = ansi
+        self._strip_tmp_path_enabled = tmp_path
+
+    def readouterr(self) -> CaptureResult[str]:
+        """Read captured output, applying configured post-processing."""
+        result = self._original.readouterr()
+        out, err = result.out, result.err
+
+        if self._strip_ansi_enabled:
+            out = strip_ansi(out)
+            err = strip_ansi(err)
+
+        if self._strip_tmp_path_enabled:
+            tmp_path: Path | None = None
+            with contextlib.suppress(pytest.FixtureLookupError):
+                tmp_path = self._request.getfixturevalue("tmp_path")
+            if tmp_path is not None:
+                out = strip_tmp_path(out, tmp_path)
+                err = strip_tmp_path(err, tmp_path)
+
+        return CaptureResult(out=out, err=err)
+
+    def __getattr__(self, name: str) -> Any:
+        """Delegate attribute access to the wrapped capsys fixture."""
+        return getattr(self._original, name)
+
+
+@pytest.fixture
+def capsys(
+    request: pytest.FixtureRequest,
+    capsys: CaptureFixture[str],
+) -> CaptureFixture[str] | StrippedCaptureFixture:
+    """Override built-in capsys to optionally strip ANSI and/or tmp_path.
+
+    When either ANSI stripping (default on) or tmp_path stripping (default off)
+    is enabled, wrap the original capsys fixture so that readouterr() returns
+    post-processed output.
+
+    Args:
+        request: The pytest fixture request object.
+        capsys: The original pytest capsys fixture.
+
+    Returns:
+        Either the original capsys or a wrapped version that post-processes output.
+    """
+    ansi = _should_strip_ansi(request)
+    tmp_path = bool(resolve_option(request, "capsys_strip_tmp_path"))
+
+    if not ansi and not tmp_path:
+        return capsys
+
+    return StrippedCaptureFixture(capsys, request=request, ansi=ansi, tmp_path=tmp_path)

{pytest_devtools-1.1.0 → pytest_devtools-1.2.0}/src/devtools/debug_fixture.py

@@ -20,6 +20,8 @@ from rich.console import Console
 from rich.pretty import pretty_repr
 from rich.tree import Tree
 
+from devtools._options import resolve_option
+
 phase_report_key = pytest.StashKey[dict[str, pytest.CollectReport]]()
 
 
@@ -97,33 +99,6 @@ def add_options(parser: pytest.Parser) -> None:
     parser.addini("debug_show_type", type="bool", default=False, help="Show type annotations")
 
 
-def _resolve_option(
-    request: pytest.FixtureRequest,
-    name: str,
-    per_call: bool | int | None,  # noqa: FBT001
-) -> Any:
-    """Resolve a config option with per-call override.
-
-    Per-call value takes precedence, then CLI flag, then ini option.
-
-    Args:
-        request: The pytest fixture request.
-        name: The option name (matching both getoption dest and ini key).
-        per_call: The per-call override value, or None to use global default.
-
-    Returns:
-        The resolved option value.
-    """
-    if per_call is not None:
-        return per_call
-
-    cli_value = request.config.getoption(name, default=None)
-    if cli_value is not None:
-        return cli_value
-
-    return request.config.getini(name)
-
-
 def _build_dir_tree(path: Path, base_name: str) -> Tree:
     """Build a Rich Tree showing directory contents.
 
@@ -176,13 +151,13 @@ class DebugPrinter:
             max_length: Override global max_length setting.
             show_type: Override global show_type setting.
         """
-        resolved_strip = _resolve_option(self._request, "debug_strip_tmp_path", strip_tmp_path)
-        resolved_list_dir = _resolve_option(
+        resolved_strip = resolve_option(self._request, "debug_strip_tmp_path", strip_tmp_path)
+        resolved_list_dir = resolve_option(
             self._request, "debug_list_dir_contents", list_dir_contents
         )
-        resolved_depth_raw = _resolve_option(self._request, "debug_max_depth", max_depth)
-        resolved_length_raw = _resolve_option(self._request, "debug_max_length", max_length)
-        resolved_show_type = _resolve_option(self._request, "debug_show_type", show_type)
+        resolved_depth_raw = resolve_option(self._request, "debug_max_depth", max_depth)
+        resolved_length_raw = resolve_option(self._request, "debug_max_length", max_length)
+        resolved_show_type = resolve_option(self._request, "debug_show_type", show_type)
 
         resolved_depth = int(resolved_depth_raw) if resolved_depth_raw else None
         resolved_length = int(resolved_length_raw) if resolved_length_raw else None

pytest_devtools-1.1.0/README.md

@@ -1,258 +0,0 @@
-# pytest-devtools
-
-Small pytest plugin that provides some niceties for writing and debugging tests.
-
-## Features
-
--   **Debug fixture** -- Pretty-print variables, paths, and data structures with Rich. Output appears only when tests fail (or always with `--print-debug`).
--   **ANSI-stripped capsys** -- Automatically strip ANSI escape sequences from captured output so assertions don't break on color codes.
--   **Visible whitespace** -- Replace invisible whitespace characters (tabs, trailing spaces, carriage returns, newlines) with Unicode symbols in assertion failure diffs.
--   **Terminal column width** -- Optionally set the `COLUMNS` environment variable so Rich and other terminal-aware libraries don't introduce unwanted line wraps.
-
-## Installation
-
-```bash
-# Using uv
-uv add pytest-devtools
-
-# Using pip
-pip install pytest-devtools
-```
-
-**Requirements:** Python 3.11+ and pytest 7.0+
-
-The plugin activates automatically once installed. No `conftest.py` changes are needed.
-
-## Debug Fixture
-
-The `debug` fixture gives you a callable that pretty-prints any Python object using Rich. Output is collected during the test and flushed to stderr only when the test fails.
-
-### Basic Usage
-
-```python
-def test_user_creation(debug, tmp_path):
-    user = {"name": "Alice", "roles": ["admin", "editor"]}
-    debug(user)
-
-    config_path = tmp_path / "config.toml"
-    config_path.write_text("[settings]\nverbose = true")
-    debug(config_path)
-
-    assert user["name"] == "Alice"
-```
-
-On failure, stderr shows the Rich-formatted output between rule separators:
-
-```
-──────────────────────────── Debug ─────────────────────────────
-{'name': 'Alice', 'roles': ['admin', 'editor']}
-──────────────────────────── Debug ─────────────────────────────
-```
-
-### Multiple Values and Titles
-
-Pass multiple arguments in a single call, and use `title` to label sections:
-
-```python
-def test_transform(debug):
-    before = [1, 2, 3]
-    after = [x * 2 for x in before]
-    debug(before, after, title="Transform")
-```
-
-### Per-Call Options
-
-Every option can be overridden on a per-call basis:
-
-```python
-def test_deep_structure(debug, tmp_path):
-    nested = {"a": {"b": {"c": {"d": "deep"}}}}
-
-    # Limit nesting depth
-    debug(nested, max_depth=2)
-
-    # Limit collection length
-    debug(list(range(100)), max_length=5)
-
-    # Show type annotations
-    debug(nested, show_type=True)
-
-    # Show directory tree for Path objects
-    debug(tmp_path, list_dir_contents=True)
-
-    # Disable tmp_path prefix stripping
-    debug(tmp_path / "output.txt", strip_tmp_path=False)
-```
-
-### Path Handling
-
-When you pass a `pathlib.Path` to `debug`:
-
--   **tmp_path stripping** (default: on) -- If the path is inside `tmp_path`, only the relative portion is shown. A path like `/var/folders/.../pytest-1234/test_foo0/subdir/file.txt` displays as `subdir/file.txt`.
--   **Directory listing** (default: off) -- When enabled and the path is a directory, a Rich tree shows the full directory contents recursively.
-
-### CLI Options
-
-| Flag                           | Description                                         |
-| ------------------------------ | --------------------------------------------------- |
-| `--print-debug`                | Always show debug output, even on passing tests     |
-| `--debug-strip-tmp-path`       | Strip `tmp_path` prefix from Path objects (default) |
-| `--no-debug-strip-tmp-path`    | Show full absolute paths                            |
-| `--debug-list-dir-contents`    | Show directory tree for Path directories            |
-| `--no-debug-list-dir-contents` | Don't list directory contents (default)             |
-| `--debug-max-depth=N`          | Limit nesting depth in pretty-printed output        |
-| `--debug-max-length=N`         | Limit collection length in pretty-printed output    |
-| `--debug-show-type`            | Show type annotations above each value              |
-| `--no-debug-show-type`         | Don't show type annotations (default)               |
-
-### INI Options
-
-Add these to `pyproject.toml` under `[tool.pytest.ini_options]`:
-
-```toml
-[tool.pytest.ini_options]
-print_debug = true
-debug_strip_tmp_path = true
-debug_list_dir_contents = false
-debug_max_depth = 4
-debug_max_length = 20
-debug_show_type = false
-```
-
-### Option Precedence
-
-Per-call arguments take highest priority, then CLI flags, then INI settings:
-
-```
-per-call override  >  CLI flag  >  INI option  >  built-in default
-```
-
-## ANSI-Stripped capsys
-
-By default, `capsys.readouterr()` returns output with ANSI escape sequences removed. This makes assertions simpler when testing code that uses colored output (Rich, Click, Colorama, etc.).
-
-### Basic Usage
-
-```python
-def test_greeting(capsys):
-    # Imagine this function uses Rich to print colored output
-    print("\x1b[32mHello, world!\x1b[0m")
-
-    captured = capsys.readouterr()
-    assert captured.out == "Hello, world!\n"  # No ANSI codes to worry about
-```
-
-### Keeping ANSI Codes
-
-For tests that need to verify color output, disable stripping per-test with a marker:
-
-```python
-import pytest
-
-@pytest.mark.keep_ansi
-def test_color_codes(capsys):
-    print("\x1b[32mgreen\x1b[0m")
-    captured = capsys.readouterr()
-    assert "\x1b[32m" in captured.out
-```
-
-Or disable stripping globally with a CLI flag:
-
-```bash
-pytest --no-strip-ansi
-```
-
-### INI Option
-
-```toml
-[tool.pytest.ini_options]
-strip_ansi = false
-```
-
-## Visible Whitespace in Assertions
-
-When two strings differ only by whitespace, pytest's default diff is hard to read. This plugin replaces invisible characters with visible Unicode symbols in assertion failure output.
-
-### Symbol Reference
-
-| Character              | Symbol | Name             |
-| ---------------------- | ------ | ---------------- |
-| Trailing space         | `·`    | Middle dot       |
-| Tab (`\t`)             | `→`    | Rightwards arrow |
-| Carriage return (`\r`) | `←`    | Leftwards arrow  |
-| Newline (`\n`)         | `↵`    | Return symbol    |
-
-### Example Output
-
-For a test like:
-
-```python
-def test_output():
-    assert "hello " == "hello"
-```
-
-The failure message shows:
-
-```
-AssertionError: 'hello·' == 'hello'
-
-Whitespace-visible comparison:
-  Left:  'hello·'
-  Right: 'hello'
-```
-
-### Disabling
-
-Disable with the `--no-show-whitespace` CLI flag or in INI:
-
-```toml
-[tool.pytest.ini_options]
-show_whitespace = false
-```
-
-> **Note:** Whitespace visibility only activates for `==` comparisons between strings, and only when the replacement actually changes the display. Non-string comparisons and strings without special whitespace are unaffected.
-
-## Terminal Column Width
-
-Many terminal-aware libraries (Rich, Click, etc.) detect the terminal width at runtime. In test environments, the detected width is often very small, causing unwanted line wraps in captured output. This plugin can set the `COLUMNS` environment variable for every test to prevent this.
-
-This feature is **disabled by default**. Enable it with the `--columns` CLI flag or via INI options.
-
-### CLI Option
-
-Set `COLUMNS` for a single run:
-
-```bash
-pytest --columns=180
-```
-
-### INI Options
-
-Enable permanently in `pyproject.toml`:
-
-```toml
-[tool.pytest.ini_options]
-set_columns = true   # Enable the feature
-columns = 180        # Value to set (default when enabled)
-```
-
-The `--columns` CLI flag overrides the INI `columns` value when both are present.
-
-## Configuration Summary
-
-All features can be configured via CLI flags, `pyproject.toml` INI options, or (for the debug fixture) per-call arguments.
-
-| Feature            | Enabled by default     | Enable/Disable with                                 |
-| ------------------ | ---------------------- | --------------------------------------------------- |
-| Debug fixture      | Output on failure only | N/A (always available)                              |
-| ANSI stripping     | Yes                    | `--no-strip-ansi` or `strip_ansi = false`           |
-| Visible whitespace | Yes                    | `--no-show-whitespace` or `show_whitespace = false` |
-| Column width       | No                     | `--columns=N` or `set_columns = true`               |
-
-## AI Policy
-
-All AI generated content is and always will be meticulously reviewed and approved by the author.
-
-## License
-
-MIT

pytest_devtools-1.1.0/src/devtools/capsys_strip.py

@@ -1,138 +0,0 @@
-"""ANSI escape sequence stripping for capsys captured output.
-
-Override pytest's built-in capsys fixture to automatically strip ANSI escape
-sequences from captured stdout and stderr, making assertions against captured
-output simpler and more reliable.
-"""
-
-from __future__ import annotations
-
-import re
-from typing import TYPE_CHECKING, Any
-
-import pytest
-from _pytest.capture import CaptureFixture, CaptureResult
-
-if TYPE_CHECKING:
-    from _pytest.config import Config
-
-ANSI_PATTERN = re.compile(r"\x1b\[[0-9;]*m")
-
-
-def strip_ansi(text: str) -> str:
-    """Remove ANSI escape sequences from a string.
-
-    Args:
-        text: The string potentially containing ANSI escape sequences.
-
-    Returns:
-        The string with all ANSI SGR sequences removed.
-    """
-    return ANSI_PATTERN.sub("", text)
-
-
-def add_options(parser: pytest.Parser) -> None:
-    """Register CLI options for ANSI stripping.
-
-    Args:
-        parser: The pytest option parser to add options to.
-    """
-    group = parser.getgroup("devtools-capsys", "ANSI stripping for capsys")
-    group.addoption(
-        "--no-strip-ansi",
-        action="store_true",
-        default=False,
-        help="Disable automatic ANSI escape sequence stripping from capsys output",
-    )
-    parser.addini(
-        "strip_ansi",
-        type="bool",
-        default=True,
-        help="Enable/disable ANSI stripping from capsys output (default: true)",
-    )
-
-
-def configure(config: Config) -> None:
-    """Register the keep_ansi marker.
-
-    Args:
-        config: The pytest config object.
-    """
-    config.addinivalue_line(
-        "markers",
-        "keep_ansi: disable ANSI stripping from capsys for this test",
-    )
-
-
-def _should_strip(request: pytest.FixtureRequest) -> bool:
-    """Determine whether ANSI stripping should be applied for this test.
-
-    Args:
-        request: The pytest fixture request object.
-
-    Returns:
-        True if ANSI codes should be stripped, False otherwise.
-    """
-    if request.config.getoption("no_strip_ansi", default=False):
-        return False
-
-    if not request.config.getini("strip_ansi"):
-        return False
-
-    return not request.node.get_closest_marker("keep_ansi")
-
-
-class StrippedCaptureFixture:
-    """Wrapper around CaptureFixture that strips ANSI from readouterr() results.
-
-    Delegate all attribute access to the underlying CaptureFixture, intercepting
-    only readouterr() to strip ANSI escape sequences.
-    """
-
-    def __init__(self, original: CaptureFixture[str]) -> None:
-        self._original = original
-
-    def readouterr(self) -> CaptureResult[str]:
-        """Read and strip ANSI from captured output.
-
-        Returns:
-            CaptureResult with ANSI sequences removed from both out and err.
-        """
-        result = self._original.readouterr()
-        return CaptureResult(
-            out=strip_ansi(result.out),
-            err=strip_ansi(result.err),
-        )
-
-    def __getattr__(self, name: str) -> Any:
-        """Delegate all other attribute access to the original fixture.
-
-        Args:
-            name: The attribute name to look up.
-
-        Returns:
-            The attribute from the original CaptureFixture.
-        """
-        return getattr(self._original, name)
-
-
-@pytest.fixture
-def capsys(
-    request: pytest.FixtureRequest,
-    capsys: CaptureFixture[str],
-) -> CaptureFixture[str] | StrippedCaptureFixture:
-    """Override built-in capsys to optionally strip ANSI escape sequences.
-
-    When ANSI stripping is enabled (the default), wrap the original capsys
-    fixture so that readouterr() returns output with ANSI codes removed.
-
-    Args:
-        request: The pytest fixture request object.
-        capsys: The original pytest capsys fixture.
-
-    Returns:
-        Either the original capsys or a wrapped version that strips ANSI codes.
-    """
-    if _should_strip(request):
-        return StrippedCaptureFixture(capsys)
-    return capsys