like() variants

AGENTS.md

@@ -5,6 +5,7 @@
 - **Done means green**: a change is only complete when `./happy.sh` exits 0; do not commit until it does.
 - **No unrelated failures**: if `./happy.sh` fails on something unrelated to your changes, do NOT assume it is a pre-existing problem and proceed anyway. Stop immediately and ask the user how to proceed.
 - **Docs for everything public**: new functionality or public API changes must have accompanying docs in `docs/*.rst`
+- **Keep the api.rst comparers list current**: the `Comparing` > `Comparers` list in `docs/api.rst` is hand-curated (not an `automodule`). When you add a `compare_*` comparer to `comparers.py`, add a matching `.. autofunction::` entry there, otherwise it silently goes undocumented.
 - **No em-dashes or parenthetical asides in prose**: in `docs/*.rst` prose and Python docstrings, never use em-dashes, and never tuck a clause inside parentheses; rephrase with commas or separate sentences. This does not apply to code comments or agent-facing notes such as this file, where both are fine.
 - **No stacked headings in docs**: a heading in `docs/*.rst` must be followed by prose, never immediately by a sub-heading. Add a short lead-in or merge the levels.
 - **Type-annotate public APIs**: all public functions and classes need type annotations; mypy is the gate
@@ -39,7 +40,7 @@ uv build                                           # build sdist + wheel
 
 `src/testfixtures/`: all source. Key modules:
 
-- `comparison.py`: `compare()`, `diff()`, `Comparison`, `StringComparison`, `RoundComparison`, etc.
+- `comparison.py`: `compare()`, `diff()`, `Comparison`, `TextComparison`, `RoundComparison`, etc.
 - `replace.py`: `Replacer`, `replace()` decorators
 - `logcapture.py`: `LogCapture`
 - `datetime.py`: `mock_datetime`, `mock_date`, `mock_time`

README.rst

@@ -22,9 +22,9 @@ The areas of testing this package can help with are listed below:
 The ``compare`` function gives readable feedback when results aren't as expected,
 with clear diffs for deeply nested data structures and for objects that don't
 normally support comparison. This includes first-class support for pandas and
-polars dataframes and numpy arrays. Flexible placeholder objects and helpers
+polars dataframes and numpy arrays. Flexible placeholder objects and matchers
 such as ``like``, ``sequence``, ``generator``, ``Comparison``, ``RoundComparison``,
-``RangeComparison``, ``StringComparison`` and ``SequenceComparison`` let you assert that only part
+``RangeComparison``, ``TextComparison`` and ``SequenceComparison`` let you assert that only part
 of a value matters, that a number is within a range or rounded to a precision, or
 that a string matches a pattern.
 

docs/api.rst

@@ -3,60 +3,27 @@ API Reference
 
 .. currentmodule:: testfixtures
 
+.. Register module targets that docstrings and the changelog cross-reference,
+   without rendering their (empty) module docstrings.
+.. module:: testfixtures.comparison
 
-Comparisons
------------
+.. module:: testfixtures.comparers
 
-.. autofunction:: compare
-
-.. autoclass:: Comparison
-
-.. autofunction:: testfixtures.like
-
-.. autoclass:: MappingComparison
-   :members:
-
-.. autoclass:: Permutation
-   :members:
-
-.. autoclass:: RoundComparison
-   :members:
-
-.. autoclass:: RangeComparison
-   :members:
-
-.. autoclass:: SequenceComparison
-   :members:
-
-.. autofunction:: testfixtures.sequence
-
-.. autofunction:: testfixtures.contains
-
-.. autofunction:: testfixtures.unordered
-
-.. autofunction:: testfixtures.mapping
-
-.. autoclass:: Subset
-   :members:
-
-.. autoclass:: StringComparison
-   :members:
+.. currentmodule:: testfixtures
 
 
-testfixtures.comparison
-~~~~~~~~~~~~~~~~~~~~~~~
+Comparing
+---------
 
-.. automodule:: testfixtures.comparison
+.. autofunction:: compare
 
 .. autofunction:: testfixtures.comparison.register
 
 .. autoclass:: testfixtures.comparison.CompareContext
    :members:
 
-testfixtures.comparers
-~~~~~~~~~~~~~~~~~~~~~~
-
-.. automodule:: testfixtures.comparers
+Comparers
+~~~~~~~~~
 
 .. autofunction:: testfixtures.comparers.compare_simple
 
@@ -82,6 +49,16 @@ testfixtures.comparers
 
 .. autofunction:: testfixtures.comparers.compare_text
 
+.. autofunction:: testfixtures.comparers.compare_bytes
+
+.. autofunction:: testfixtures.comparers.compare_call
+
+.. autofunction:: testfixtures.comparers.compare_partial
+
+.. autofunction:: testfixtures.comparers.compare_path
+
+.. autofunction:: testfixtures.comparers.compare_with_fold
+
 .. autofunction:: testfixtures.comparers.safe_repr
 
 .. autofunction:: testfixtures.comparers.safe_pformat
@@ -90,6 +67,58 @@ testfixtures.comparers
 
 .. currentmodule:: testfixtures
 
+Matchers
+--------
+
+.. autofunction:: testfixtures.like
+
+.. autofunction:: testfixtures.repr_like
+
+.. autofunction:: testfixtures.str_like
+
+.. autofunction:: testfixtures.sequence
+
+.. autofunction:: testfixtures.contains
+
+.. autofunction:: testfixtures.unordered
+
+.. autofunction:: testfixtures.mapping
+
+Comparison objects
+------------------
+
+.. autoclass:: Comparison
+
+.. autoclass:: ReprComparison
+
+.. autoclass:: StrComparison
+
+.. autoclass:: TextComparison
+   :members:
+
+.. autoclass:: SequenceComparison
+   :members:
+
+.. autoclass:: Subset
+   :members:
+
+.. autoclass:: Permutation
+   :members:
+
+.. autoclass:: MappingComparison
+   :members:
+
+.. autoclass:: RangeComparison
+   :members:
+
+.. autoclass:: RoundComparison
+   :members:
+
+.. py:class:: StringComparison
+
+   Deprecated alias for :class:`TextComparison`. Note this is *not* the same as
+   :class:`StrComparison`.
+
 Capturing
 ---------
 

docs/command.rst

@@ -42,9 +42,9 @@ This can be tested as follows:
 
 We can also test what happens if the required argument is not provided. The program name
 :mod:`argparse` puts in its messages varies with how the tests are run, so we use a
-:class:`~testfixtures.StringComparison` to match it:
+:class:`~testfixtures.TextComparison` to match it:
 
->>> from testfixtures import StringComparison as S
+>>> from testfixtures import TextComparison as S
 >>> Command(main).run().check(
 ...     output=S(
 ...         r'usage: .+ \[-h\] message\n'

docs/comparing.rst

@@ -24,7 +24,7 @@ text instead of raising it.
 If, instead of checking for *exact* equality, you want to assert that a value
 merely *matches* a specification, such as a partial object, a number within a range, a
 string matching a pattern, or a sequence in any order, use the flexible
-:ref:`comparison objects and helpers <comparison-objects>`. They slot into the
+:ref:`comparison objects and matchers <comparison-objects>`. They slot into the
 expected side of :func:`compare`, and into plain ``assert`` statements.
 
 Comparing expected and actual
@@ -624,7 +624,7 @@ following:
       trailing_whitespace=False
   )
 
-See :ref:`StringComparison <stringcomparison>` to assert that a string matches a
+See :ref:`TextComparison <textcomparison>` to assert that a string matches a
 regular expression instead of comparing it exactly.
 
 .. _compare-datetime:
@@ -720,7 +720,8 @@ While comparing .name: 'bar' (expected) != 'foo' (actual)
 
 This type of comparison is also used on objects that make use of ``__slots__``.
 
-To compare only some of an object's attributes, see :ref:`ignore-attributes`, or use the partial :func:`like` helper described in :ref:`comparison-objects`.
+To compare only some of an object's attributes, see :ref:`ignore-attributes`, or use the partial
+:func:`like` matcher described in :ref:`comparison-objects`.
 
 .. _comparer-register: