pytest-devtools 1.0.0__tar.gz

pytest_devtools-1.0.0/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 natelandau
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

pytest_devtools-1.0.0/PKG-INFO

@@ -0,0 +1,285 @@
+Metadata-Version: 2.3
+Name: pytest-devtools
+Version: 1.0.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>
+License: MIT License
+         
+         Copyright (c) 2026 natelandau
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+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.2
+Requires-Dist: rich>=14.3.2
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# 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.0.0/README.md

@@ -0,0 +1,258 @@
+# 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.0.0/pyproject.toml

@@ -0,0 +1,134 @@
+[project]
+    authors = [{ name = "Nathaniel Landau", email = "github@natelandau.com" }]
+    classifiers = [
+        "Framework :: Pytest",
+        "Intended Audience :: Developers",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Programming Language :: Python :: 3.13",
+        "Programming Language :: Python :: 3.14",
+        "Topic :: Software Development :: Testing",
+    ]
+    dependencies = ["pytest>=9.0.2", "rich>=14.3.2"]
+    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.11"
+    version = "1.0.0"
+
+    [project.entry-points.pytest11]
+        pytest-devtools = "devtools.plugin"
+
+[build-system]
+    build-backend = "uv_build"
+    requires      = ["uv_build>=0.10.0,<0.11.0"]
+
+[tool.uv.build-backend]
+    module-name = "devtools"
+
+[dependency-groups]
+    dev = [
+        "commitizen>=4.13.7",
+        "duty>=1.9.0",
+        "prek>=0.3.2",
+        "pytest-clarity>=1.0.1",
+        "pytest-mock>=3.15.1",
+        "pytest-repeat>=0.9.4",
+        "pytest-sugar>=1.1.1",
+        "pytest-xdist>=3.8.0",
+        "ruff>=0.15.0",
+        "ty>=0.0.15",
+        "typos>=1.43.4",
+        "yamllint>=1.38.0",
+    ]
+
+[tool.commitizen]
+    bump_message               = "bump(release): v$current_version → v$new_version"
+    changelog_merge_prerelease = true
+    tag_format                 = "v$version"
+    update_changelog_on_bump   = true
+    version                    = "0.1.0"
+    version_provider           = "uv"
+
+[tool.pytest.ini_options]
+
+    addopts        = "--color=yes --doctest-modules --strict-config --strict-markers -n auto --dist loadfile"
+    cache_dir      = ".cache/pytest"
+    filterwarnings = ['error', 'ignore:.*Pydantic.*:UserWarning', 'ignore::DeprecationWarning:']
+    markers        = ["serial"]
+    testpaths      = ["tests"]
+    xfail_strict   = true
+
+[tool.ruff] # https://github.com/charliermarsh/ruff
+
+    exclude        = [".cache", ".dev", ".git", ".venv", ".worktrees", "_build", "_site", "build", "dist"]
+    fix            = true
+    line-length    = 100
+    output-format  = "grouped"
+    src            = ["src", "tests"]
+    target-version = "py311"
+    [tool.ruff.lint]
+        ignore = [
+            "ANN002", # Missing type annotation for `*args`
+            "ANN003", # Missing type annotation for `**kwargs`
+            "ANN204", # missing return type annotation for special method `__init__`
+            "ANN401", # Dynamically typed expressions (typing.Any) are disallowed,`
+            "B006",   # mutable-argument-default
+            "B008",   # function-call-in-default-argument
+            "COM812", # Trailing comma missing"
+            "CPY001", # Missing copyright notice at top of file
+            "D107",   # undocumented-public-init
+            "E501",   # line-too-long
+            "FIX002", # Line contains TODO, consider resolving the issue
+            "S311",   # suspicious-non-cryptographic-random-usage
+            "TD001",  # invalid-todo-tag
+            "TD002",  # Missing author in TODO
+            "TD003",  # Missing issue link on the line following this TODO
+        ]
+        per-file-ignores = { "tests/**/*.py" = [
+            "A002",
+            "A003",
+            "ANN001",  # Missing type annotation for function argument `cls`
+            "ANN002",  # Missing type annotation for `*args`
+            "ANN003",  # Missing type annotation for `**kwargs`
+            "ANN201",  # Missing return type annotation
+            "ARG001",  # Unused function argument
+            "ARG002",  # Unused method argument
+            "ARG005",  # Unused lambda argument
+            "D",       # Docstring rules relaxed in tests
+            "ERA001",  # Commented out code
+            "F403",
+            "F405",    # May be undefined from type imports
+            "FBT001",  # Boolean-typed positional argument in function definition
+            "PGH003",  # Use specific rule codes when ignoring type issues
+            "PLC0415", # Imports should be at top of file
+            "PLR0913",
+            "PLR2004",
+            "PT011",   # set the `match` parameter or use a more specific exception
+            "S101",
+            "SLF001",  # Calling private method
+            "W292",    # No blank line at end of file - included b/c cursor struggles to add a trailing newline and burns through requests trying to fix this linting error.
+        ] }
+        select = ["ALL"]
+        unfixable = [
+            "ERA001", # Commented out code
+            "F401",   # unused-import
+            "F841",   # unused-variable
+        ]
+
+        [tool.ruff.lint.mccabe]
+            # Unlike Flake8, default to a complexity level of 10.
+            max-complexity = 10
+
+        [tool.ruff.lint.pydocstyle]
+            convention = "google"
+
+        [tool.ruff.lint.pylint]
+            max-args = 6
+
+    [tool.ruff.format]
+        indent-style              = "space"
+        line-ending               = "auto"
+        quote-style               = "double"
+        skip-magic-trailing-comma = false

pytest_devtools-1.0.0/src/devtools/__init__.py

@@ -0,0 +1 @@
+"""pytest-devtools package."""

pytest_devtools-1.0.0/src/devtools/capsys_strip.py

@@ -0,0 +1,138 @@
+"""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

pytest_devtools-1.0.0/src/devtools/columns.py

@@ -0,0 +1,76 @@
+"""Set COLUMNS environment variable for test runs.
+
+Prevent code under test (including Rich-based applications) from detecting
+a narrow terminal width and introducing unwanted line wraps in captured output.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pytest
+
+if TYPE_CHECKING:
+    from _pytest.config import Config
+
+DEFAULT_COLUMNS = 180
+
+
+def add_options(parser: pytest.Parser) -> None:
+    """Register CLI options for terminal column width management.
+
+    Args:
+        parser: The pytest option parser to add options to.
+    """
+    group = parser.getgroup("devtools-columns", "Terminal column width")
+    group.addoption(
+        "--columns",
+        action="store",
+        type=int,
+        default=None,
+        help=f"Set COLUMNS environment variable to this value (default: {DEFAULT_COLUMNS})",
+    )
+    parser.addini(
+        "set_columns",
+        type="bool",
+        default=False,
+        help="Enable setting COLUMNS environment variable (default: false)",
+    )
+    parser.addini(
+        "columns",
+        default=str(DEFAULT_COLUMNS),
+        help=f"Value for COLUMNS environment variable (default: {DEFAULT_COLUMNS})",
+    )
+
+
+def _get_columns_value(config: Config) -> int | None:
+    """Determine the COLUMNS value from CLI and ini options.
+
+    Args:
+        config: The pytest config object.
+
+    Returns:
+        The column width to set, or None if columns should not be set.
+    """
+    cli_value: int | None = config.getoption("columns", default=None)
+    if cli_value is not None:
+        return cli_value
+
+    if not config.getini("set_columns"):
+        return None
+
+    ini_value: str = config.getini("columns")
+    return int(ini_value)
+
+
+@pytest.fixture(autouse=True)
+def _set_columns(request: pytest.FixtureRequest, monkeypatch: pytest.MonkeyPatch) -> None:
+    """Set COLUMNS environment variable for each test.
+
+    Args:
+        request: The pytest fixture request object.
+        monkeypatch: The pytest monkeypatch fixture.
+    """
+    columns = _get_columns_value(request.config)
+    if columns is not None:
+        monkeypatch.setenv("COLUMNS", str(columns))

pytest_devtools-1.0.0/src/devtools/debug_fixture.py

@@ -0,0 +1,263 @@
+"""Debug fixture for pretty-printing variables using Rich.
+
+Provide a callable fixture that collects Rich-formatted debug output during
+a test and displays it on failure (or always with --print-debug).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import sys
+from io import StringIO
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+import pytest
+from rich.console import Console
+from rich.pretty import pretty_repr
+from rich.tree import Tree
+
+phase_report_key = pytest.StashKey[dict[str, pytest.CollectReport]]()
+
+
+def add_options(parser: pytest.Parser) -> None:
+    """Register CLI options for the debug fixture.
+
+    Args:
+        parser: The pytest option parser to add options to.
+    """
+    group = parser.getgroup("devtools-debug", "Debug fixture options")
+    group.addoption(
+        "--print-debug",
+        action="store_true",
+        default=False,
+        help="Always show debug output, not just on test failure",
+    )
+    group.addoption(
+        "--debug-strip-tmp-path",
+        action="store_true",
+        default=None,
+        dest="debug_strip_tmp_path",
+        help="Strip tmp_path prefix from Path objects (default: true)",
+    )
+    group.addoption(
+        "--no-debug-strip-tmp-path",
+        action="store_false",
+        dest="debug_strip_tmp_path",
+        help="Don't strip tmp_path prefix from Path objects",
+    )
+    group.addoption(
+        "--debug-list-dir-contents",
+        action="store_true",
+        default=None,
+        dest="debug_list_dir_contents",
+        help="List directory contents for Path directories (default: false)",
+    )
+    group.addoption(
+        "--no-debug-list-dir-contents",
+        action="store_false",
+        dest="debug_list_dir_contents",
+        help="Don't list directory contents",
+    )
+    group.addoption(
+        "--debug-max-depth",
+        action="store",
+        type=int,
+        default=None,
+        help="Max nesting depth for debug pretty-printing",
+    )
+    group.addoption(
+        "--debug-max-length",
+        action="store",
+        type=int,
+        default=None,
+        help="Max collection length for debug pretty-printing",
+    )
+    group.addoption(
+        "--debug-show-type",
+        action="store_true",
+        default=None,
+        dest="debug_show_type",
+        help="Show type annotations in debug output",
+    )
+    group.addoption(
+        "--no-debug-show-type",
+        action="store_false",
+        dest="debug_show_type",
+        help="Don't show type annotations in debug output",
+    )
+    parser.addini("print_debug", type="bool", default=False, help="Always show debug output")
+    parser.addini("debug_strip_tmp_path", type="bool", default=True, help="Strip tmp_path prefix")
+    parser.addini("debug_list_dir_contents", type="bool", default=False, help="List dir contents")
+    parser.addini("debug_max_depth", default="", help="Max nesting depth")
+    parser.addini("debug_max_length", default="", help="Max collection length")
+    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.
+
+    Args:
+        path: The directory path to list.
+        base_name: The display name for the root of the tree.
+
+    Returns:
+        A Rich Tree object representing the directory structure.
+    """
+    tree = Tree(f"{base_name}/")
+    for child in sorted(path.iterdir()):
+        if child.is_dir():
+            subtree = _build_dir_tree(child, child.name)
+            tree.add(subtree)
+        else:
+            tree.add(child.name)
+    return tree
+
+
+class DebugPrinter:
+    """Callable debug printer that collects Rich-formatted output.
+
+    Collect formatted output during a test and flush it to stderr on
+    demand (on test failure or when --print-debug is active).
+    """
+
+    def __init__(self, request: pytest.FixtureRequest) -> None:
+        self._request = request
+        self._entries: list[str] = []
+
+    def __call__(
+        self,
+        *args: Any,
+        title: str | None = None,
+        strip_tmp_path: bool | None = None,
+        list_dir_contents: bool | None = None,
+        max_depth: int | None = None,
+        max_length: int | None = None,
+        show_type: bool | None = None,
+    ) -> None:
+        """Pretty-print one or more values and store the output.
+
+        Args:
+            *args: Objects to pretty-print.
+            title: Optional title for the Console.rule() separators.
+            strip_tmp_path: Override global strip_tmp_path setting.
+            list_dir_contents: Override global list_dir_contents setting.
+            max_depth: Override global max_depth setting.
+            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(
+            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 = int(resolved_depth_raw) if resolved_depth_raw else None
+        resolved_length = int(resolved_length_raw) if resolved_length_raw else None
+
+        tmp_path: Path | None = None
+        if resolved_strip:
+            with contextlib.suppress(pytest.FixtureLookupError):
+                tmp_path = self._request.getfixturevalue("tmp_path")
+
+        buf = StringIO()
+        console = Console(file=buf, force_terminal=True)
+
+        rule_title = title or "Debug"
+        console.rule(rule_title)
+
+        for arg in args:
+            if resolved_show_type:
+                console.print(f"[dim]({type(arg).__name__})[/dim]")
+
+            if isinstance(arg, Path):
+                display_path = arg
+                if tmp_path and resolved_strip:
+                    with contextlib.suppress(ValueError):
+                        display_path = arg.relative_to(tmp_path)
+
+                if arg.is_dir() and resolved_list_dir:
+                    dir_tree = _build_dir_tree(arg, str(display_path))
+                    console.print(dir_tree)
+                else:
+                    console.print(str(display_path))
+            else:
+                formatted = pretty_repr(
+                    arg,
+                    max_depth=resolved_depth,
+                    max_length=resolved_length,
+                )
+                console.print(formatted)
+
+        closing_title = f"/{title}" if title else "Debug"
+        console.rule(closing_title)
+
+        self._entries.append(buf.getvalue())
+
+    def flush(self) -> None:
+        """Write all collected debug entries to stderr."""
+        if self._entries:
+            output = "\n".join(self._entries)
+            sys.stderr.write(output)
+            sys.stderr.flush()
+
+
+@pytest.fixture
+def debug(request: pytest.FixtureRequest) -> Generator[DebugPrinter, None, None]:
+    """Provide a callable debug printer for pretty-printing variables.
+
+    Collect Rich-formatted output during the test. On teardown, flush
+    the output to stderr if the test failed or --print-debug is active.
+
+    Args:
+        request: The pytest fixture request.
+
+    Yields:
+        A callable DebugPrinter instance.
+    """
+    printer = DebugPrinter(request)
+    yield printer
+
+    always_print = request.config.getoption("print_debug", default=False) or request.config.getini(
+        "print_debug"
+    )
+
+    if always_print:
+        printer.flush()
+        return
+
+    report = request.node.stash.get(phase_report_key, {})
+    if report.get("call") and report["call"].failed:
+        printer.flush()

pytest_devtools-1.0.0/src/devtools/plugin.py

@@ -0,0 +1,68 @@
+"""Central hook registration for pytest-devtools plugin."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pytest
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+from devtools import capsys_strip, columns, debug_fixture, whitespace
+from devtools.capsys_strip import capsys as capsys  # noqa: PLC0414
+from devtools.columns import _set_columns as _set_columns  # noqa: PLC0414
+from devtools.debug_fixture import debug as debug  # noqa: PLC0414
+from devtools.debug_fixture import phase_report_key
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    """Register CLI options for all pytest-devtools features."""
+    columns.add_options(parser)
+    capsys_strip.add_options(parser)
+    whitespace.add_options(parser)
+    debug_fixture.add_options(parser)
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    """Register markers for all pytest-devtools features."""
+    capsys_strip.configure(config)
+
+
+@pytest.hookimpl(wrapper=True, tryfirst=True)
+def pytest_runtest_makereport(
+    item: pytest.Item,
+    call: pytest.CallInfo[None],  # noqa: ARG001
+) -> Generator[None, pytest.TestReport, pytest.TestReport]:
+    """Store test phase reports for debug fixture teardown access.
+
+    Args:
+        item: The test item.
+        call: The call information.
+
+    Returns:
+        The test report.
+    """
+    rep = yield
+    item.stash.setdefault(phase_report_key, {})[rep.when] = rep
+    return rep
+
+
+def pytest_assertrepr_compare(
+    config: pytest.Config,
+    op: str,
+    left: object,
+    right: object,
+) -> list[str] | None:
+    """Delegate assertion comparison to whitespace module.
+
+    Args:
+        config: The pytest config object.
+        op: The comparison operator.
+        left: The left operand.
+        right: The right operand.
+
+    Returns:
+        Custom explanation lines or None for default behavior.
+    """
+    return whitespace.pytest_assertrepr_compare(config, op, left, right)

pytest_devtools-1.0.0/src/devtools/whitespace.py

@@ -0,0 +1,112 @@
+"""Make invisible whitespace characters visible in assertion failure diffs.
+
+Replace tabs, carriage returns, trailing spaces, and newlines with visible
+Unicode symbols so that whitespace-only differences in string comparisons
+are immediately obvious in pytest assertion output.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import pytest
+
+TRAILING_SPACES_PATTERN = re.compile(r" +$", re.MULTILINE)
+
+
+def add_options(parser: pytest.Parser) -> None:
+    """Register CLI options for whitespace visibility.
+
+    Args:
+        parser: The pytest option parser to add options to.
+    """
+    group = parser.getgroup("devtools-whitespace", "Whitespace visibility in assertions")
+    group.addoption(
+        "--no-show-whitespace",
+        action="store_true",
+        default=False,
+        help="Disable visible whitespace symbols in assertion failure diffs",
+    )
+    parser.addini(
+        "show_whitespace",
+        type="bool",
+        default=True,
+        help="Enable/disable whitespace visibility in assertion diffs (default: true)",
+    )
+
+
+def _is_enabled(config: pytest.Config) -> bool:
+    """Check whether whitespace visibility is enabled.
+
+    Args:
+        config: The pytest config object.
+
+    Returns:
+        True if whitespace visibility is enabled.
+    """
+    if config.getoption("no_show_whitespace", default=False):
+        return False
+
+    return config.getini("show_whitespace")
+
+
+def make_whitespace_visible(text: str) -> str:
+    """Replace invisible whitespace characters with visible symbols.
+
+    Replace tabs with arrows, carriage returns with left arrows, trailing
+    spaces with middle dots, and newlines with return symbols.
+
+    Args:
+        text: The string in which to make whitespace visible.
+
+    Returns:
+        The string with whitespace characters replaced by visible symbols.
+    """
+    text = text.replace("\t", "\u2192")
+    text = text.replace("\r", "\u2190")
+    text = TRAILING_SPACES_PATTERN.sub(lambda m: "\u00b7" * len(m.group()), text)
+    return text.replace("\n", "\u21b5\n")
+
+
+def pytest_assertrepr_compare(
+    config: pytest.Config,
+    op: str,
+    left: object,
+    right: object,
+) -> list[str] | None:
+    """Provide custom assertion failure output with visible whitespace.
+
+    When comparing strings with ==, generate comparison lines that show
+    invisible whitespace as visible Unicode symbols.
+
+    Args:
+        config: The pytest config object.
+        op: The comparison operator (e.g. "==").
+        left: The left operand.
+        right: The right operand.
+
+    Returns:
+        A list of explanation strings, or None to use default behavior.
+    """
+    if not _is_enabled(config):
+        return None
+
+    if op != "==" or not isinstance(left, str) or not isinstance(right, str):
+        return None
+
+    visible_left = make_whitespace_visible(left)
+    visible_right = make_whitespace_visible(right)
+
+    # Only activate if whitespace replacement actually changed something
+    if visible_left == left and visible_right == right:
+        return None
+
+    return [
+        f"'{visible_left}' == '{visible_right}'",
+        "",
+        "Whitespace-visible comparison:",
+        f"  Left:  '{visible_left}'",
+        f"  Right: '{visible_right}'",
+    ]