lovely-assertions 0.1.0__py3-none-any.whl

lovely_assertions/__init__.py

@@ -0,0 +1,177 @@
+"""Fluent, strictly-typed assertions for Python tests.
+
+``lovely-assertions`` competes with pytest's ``assert`` rewriting on the two axes
+where it has nothing to offer: **typed discoverability** -- ``expect(x).`` proposes
+only the assertions that are valid for ``x`` -- and **real narrowing** --
+``expect(raw).is_not_none().subject`` is a ``str`` as far as the type checker is
+concerned.
+
+::
+
+    from lovely_assertions import expect
+
+    expect(order.total).is_greater_than(0, because="an empty basket cannot ship")
+    expect(response.headers).contains_key("etag")
+
+:func:`expect` chooses the subject type from the value, so only the assertions
+that make sense for it are offered; every assertion returns a subject, so they
+chain; every failure is a sentence naming the bug rather than a diff to interpret.
+``because=`` is appended to that sentence and is never interpolated into it.
+
+Around that: :func:`soft_assertions` gathers several failures into one report
+instead of stopping at the first, :func:`expect_raises` and :func:`expect_warns`
+put an exception or a warning under the same fluent API, :func:`formatting` widens
+how much a message may print for one block, and :func:`register_formatter` decides
+how a domain type reads inside one. :func:`register` attaches a subject class to
+a type of your own, and :func:`custom_assertion` marks an assertion you wrote so
+its failures still name the caller's variable rather than a local of yours.
+
+Zero runtime dependencies, Python 3.13+, ``py.typed``.
+"""
+
+#: The distribution's version, and the only place it is written down.
+#:
+#: A string literal rather than a call to ``importlib.metadata.version()``: that
+#: reads the installed distribution's metadata off disk, which costs more than
+#: everything else this package does at import time and would be paid by every
+#: program that imports it to run one assertion. The build backend reads this very
+#: line to version the wheel, so the string here and the distribution's recorded
+#: version cannot disagree.
+#:
+#: The trailing marker is not decoration: release-please's generic updater rewrites
+#: the line carrying it, which is how the version derived from the commit log lands
+#: here rather than being typed by hand. Remove it and releases silently stop
+#: bumping this file while still tagging.
+#:
+#: It reads ``0.0.0`` because nothing has been published to PyPI yet, and this
+#: line records the last *released* version rather than the next one. The release
+#: pull request is where the next one is proposed.
+__version__ = "0.1.0"  # x-release-please-version
+
+from lovely_assertions._core import Expect, Found, SoftScope, soft_assertions
+from lovely_assertions._equivalence import Equivalency, close_within, equivalency
+from lovely_assertions._exceptions import AssertionFailure
+from lovely_assertions._formatters import (
+    IterableFormatter,
+    ObjectFormatter,
+    ValueFormatter,
+    format_value,
+    register_formatter,
+)
+from lovely_assertions._formatting import FormattingOptions, current_formatting, formatting
+
+# `_matching` wires itself up at import time: a subject that refuses
+# `expect(<a matcher>)` and says where the matcher belongs instead, and a formatter
+# that renders matchers inside a failure message. Neither happens unless something
+# imports the module, so re-exporting the matchers here is what installs both for
+# every user.
+from lovely_assertions._matching import (
+    any_instance_of,
+    anything,
+    close_to,
+    containing,
+    is_matcher,
+    matching,
+    one_of,
+    string_containing,
+    string_matching,
+)
+from lovely_assertions._names import custom_assertion
+from lovely_assertions._occurrence import (
+    Occurrence,
+    at_least,
+    at_most,
+    exactly,
+    less_than,
+    more_than,
+    once,
+    twice,
+)
+from lovely_assertions._subjects import (
+    BoolExpect,
+    CallableExpect,
+    CollectionExpect,
+    DateExpect,
+    DateTimeExpect,
+    EnumExpect,
+    MappingExpect,
+    MockExpect,
+    NumericExpect,
+    OrderedExpect,
+    PathExpect,
+    PurePathExpect,
+    RaisedExpect,
+    SequenceExpect,
+    StringExpect,
+    TimeDeltaExpect,
+    TimeExpect,
+    TypeExpect,
+    WithinDelta,
+    expect,
+    expect_raises,
+    is_mock,
+    register,
+)
+from lovely_assertions._warnings import WarnedExpect, expect_warns
+
+__all__ = [
+    "AssertionFailure",
+    "BoolExpect",
+    "CallableExpect",
+    "CollectionExpect",
+    "DateExpect",
+    "DateTimeExpect",
+    "EnumExpect",
+    "Equivalency",
+    "Expect",
+    "FormattingOptions",
+    "Found",
+    "IterableFormatter",
+    "MappingExpect",
+    "MockExpect",
+    "NumericExpect",
+    "ObjectFormatter",
+    "Occurrence",
+    "OrderedExpect",
+    "PathExpect",
+    "PurePathExpect",
+    "RaisedExpect",
+    "SequenceExpect",
+    "SoftScope",
+    "StringExpect",
+    "TimeDeltaExpect",
+    "TimeExpect",
+    "TypeExpect",
+    "ValueFormatter",
+    "WarnedExpect",
+    "WithinDelta",
+    "any_instance_of",
+    "anything",
+    "at_least",
+    "at_most",
+    "close_to",
+    "close_within",
+    "containing",
+    "current_formatting",
+    "custom_assertion",
+    "equivalency",
+    "exactly",
+    "expect",
+    "expect_raises",
+    "expect_warns",
+    "format_value",
+    "formatting",
+    "is_matcher",
+    "is_mock",
+    "less_than",
+    "matching",
+    "more_than",
+    "once",
+    "one_of",
+    "register",
+    "register_formatter",
+    "soft_assertions",
+    "string_containing",
+    "string_matching",
+    "twice",
+]

lovely_assertions/_bool.py

@@ -0,0 +1,127 @@
+"""Assertions for ``bool``.
+
+The shortest catalogue in the library, and the only one where the value in a
+failure message tells the reader nothing new: there are two of them, and the
+assertion already named the one it wanted. So the effort goes elsewhere.
+``implies`` can fail exactly one way -- the subject held and the consequent did
+not -- and its message spells both sides out rather than leaving the reader to
+recall the truth table.
+
+The four value checks are identity, not truthiness: ``is_true`` asks for ``True``
+itself, never for something merely truthy. ``expect()`` routes only an exact
+``bool`` here, so the distinction stays invisible in normal use; it surfaces when
+a subject is built by hand around a ``1`` or a NumPy scalar, and there the strict
+reading reports the bug instead of hiding it. ``implies`` is the one method that
+must read the subject for *truth* rather than for identity -- an implication is
+defined over truth values -- so it reports the value it actually saw instead of
+asserting that it was ``True``.
+"""
+
+from typing import Self
+
+from lovely_assertions._core import Expect
+from lovely_assertions._diff import render_operand
+from lovely_assertions._exceptions import hide_internal_frames
+
+#: pytest reads ``__tracebackhide__`` from a frame's globals, so this one
+#: assignment folds every frame of this module out of an assertion failure's
+#: traceback while leaving them in place for a genuine error. See
+#: :func:`lovely_assertions._exceptions.hide_internal_frames`.
+__tracebackhide__ = hide_internal_frames
+
+__all__ = ["BoolExpect"]
+
+
+class BoolExpect(Expect[bool]):
+    """The subject ``expect()`` hands back for a ``bool``.
+
+    Adds the two value checks, their negations and :meth:`implies` to the generic
+    catalogue; ``is_equal_to``, ``is_not_equal_to`` and the rest are inherited
+    from :class:`Expect`. Every method returns the subject, so calls chain.
+    """
+
+    __slots__ = ()
+
+    # -- the two values ----------------------------------------------------
+    def is_true(self, *, because: str = "") -> Self:
+        """Assert the subject is ``True``.
+
+        Identity, not truthiness: a subject that is merely truthy -- a ``1``, a
+        non-empty string, a NumPy scalar -- fails, and the failure prints what was
+        actually there. Returns the subject, so the call chains. For a plain
+        ``bool`` this and :meth:`is_not_false` make the same claim; reach for this
+        one to state what the value is.
+        """
+        if self._subject is True:
+            return self
+        return self._fail(f"to be True, but was {render_operand(self._subject)}", because)
+
+    def is_false(self, *, because: str = "") -> Self:
+        """Assert the subject is ``False``.
+
+        Identity, not falsiness: a ``0``, a ``None`` or an empty container -- which
+        reaches here only through a hand-built subject -- fails rather than passing
+        quietly. Returns the subject, so the call chains. For a plain ``bool`` this
+        and :meth:`is_not_true` make the same claim; reach for this one to state
+        what the value is.
+        """
+        if self._subject is False:
+            return self
+        return self._fail(f"to be False, but was {render_operand(self._subject)}", because)
+
+    def is_not_true(self, *, because: str = "") -> Self:
+        """Assert the subject is not ``True``.
+
+        For a plain ``bool`` this is :meth:`is_false` wearing another name, and
+        both are kept because they read differently at the call site: one states
+        what the value is, the other what it must not have become -- the shape a
+        "the flag was never set" check wants. It is also where FluentAssertions'
+        ``NotBeTrue`` lands, where the distinction is real because a nullable
+        ``bool?`` can be neither. A Python ``bool | None`` falls back to the
+        generic subject rather than reaching this class, so that case does not
+        survive the trip -- but the name it is looked up under does. Returns the
+        subject, so the call chains.
+        """
+        if self._subject is not True:
+            return self
+        return self._fail("not to be True, but it was", because)
+
+    def is_not_false(self, *, because: str = "") -> Self:
+        """Assert the subject is not ``False``.
+
+        The mirror of :meth:`is_not_true`. For a plain ``bool`` it makes the same
+        claim as :meth:`is_true`, under a name that reads as "it must not have been
+        switched off". Returns the subject, so the call chains.
+        """
+        if self._subject is not False:
+            return self
+        return self._fail("not to be False, but it was", because)
+
+    # -- logic -------------------------------------------------------------
+    def implies(self, consequent: bool, /, *, because: str = "") -> Self:
+        """Assert the material implication ``subject -> consequent``.
+
+        It holds unless the subject is true and ``consequent`` is not, so three
+        of the four rows pass -- including both rows where the subject is false,
+        which is the part that surprises people reading a failure.
+
+        ``consequent`` is a value, not a callable: it is evaluated by the caller
+        before the assertion runs, so this asserts a relationship between two
+        booleans already in hand rather than deferring one of them.
+
+        Both sides are reported as they were found. The failing row is always
+        "the subject held", but *what* held is worth printing: a subject that
+        reached here as a ``1`` or a ``"yes"`` is a finding, and a message that
+        answered ``True`` for all three would hide it.
+
+        This is the one method here that reads the subject for truth rather than
+        for identity, since an implication is defined over truth values. Returns
+        the subject, so the call chains.
+        """
+        if not self._subject or consequent:
+            return self
+        return self._fail(
+            f"to imply the consequent, but was {render_operand(self._subject)} "
+            f"while the consequent was {render_operand(consequent)}",
+            because,
+        )