assertpy 2.35.0__py3-none-any.whl

assertpy/extracting.py

@@ -0,0 +1,266 @@
+from __future__ import annotations
+
+import collections.abc
+import difflib
+import inspect
+from typing import TYPE_CHECKING, cast
+
+from ._engine._equality import mapping_shaped
+from ._engine._introspection import is_model_dump_object, is_namedtuple
+from ._engine._mixin_base import _MixinBase
+from ._engine._require import argument, refuse, reject_unknown_kwargs, require_type, verdict
+
+_EXTRACTING_OPTIONS = frozenset({"filter", "sort"})
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from ._engine._compat import Self
+    from ._engine._introspection import MappingLike
+
+__tracebackhide__ = True
+
+
+_OURS = "_assertpy_extracting"
+
+
+def _extraction_error(message: str) -> ValueError:
+    """A ``ValueError`` tagged as this module's own.
+
+    The localization wrapper re-raises only tagged errors, so a ``ValueError`` raised by user code (a
+    property that fails, say) keeps its own traceback instead of being swallowed. The visible type
+    stays ``ValueError``, exactly as before.
+    """
+    error = ValueError(message)
+    setattr(error, _OURS, True)
+    return error
+
+
+class ExtractingMixin(_MixinBase):
+    """Collection flattening mixin.
+
+    It is often necessary to test collections of objects.  Use the ``extracting()`` helper to
+    reduce the collection on a given attribute.  Reduce a list of objects:
+
+        alice = Person('Alice', 'Alpha')
+        bob = Person('Bob', 'Bravo')
+        people = [alice, bob]
+
+        assert_that(people).extracting('first_name').is_equal_to(['Alice', 'Bob'])
+        assert_that(people).extracting('first_name').contains('Alice', 'Bob')
+        assert_that(people).extracting('first_name').does_not_contain('Charlie')
+
+    Additionally, the ``extracting()`` helper can accept a list of attributes to be extracted, and
+    will flatten them into a list of tuples.  Reduce a list of objects on multiple attributes:
+
+        assert_that(people).extracting('first_name', 'last_name').contains(('Alice', 'Alpha'), ('Bob', 'Bravo'))
+
+    Also, ``extracting()`` works on not just attributes, but also properties, and even
+    zero-argument methods.  Reduce a list of object on properties and zero-arg methods:
+
+        assert_that(people).extracting('name').contains('Alice Alpha', 'Bob Bravo')
+        assert_that(people).extracting('say_hello').contains('Hello, Alice!', 'Hello, Bob!')
+
+    And ``extracting()`` even works on *dict-like* objects.  Reduce a list of dicts on key:
+
+        alice = {'first_name': 'Alice', 'last_name': 'Alpha'}
+        bob = {'first_name': 'Bob', 'last_name': 'Bravo'}
+        people = [alice, bob]
+
+        assert_that(people).extracting('first_name').contains('Alice', 'Bob')
+
+    **Filtering**
+
+    The ``extracting()`` helper can include a *filter* to keep only those items for which the given
+    *filter* is truthy.  For example:
+
+        users = [
+            {'user': 'Alice', 'age': 36, 'active': True},
+            {'user': 'Bob', 'age': 40, 'active': False},
+            {'user': 'Charlie', 'age': 13, 'active': True}
+        ]
+
+        # filter the active users
+        assert_that(users).extracting('user', filter='active').is_equal_to(['Alice', 'Charlie'])
+
+    The *filter* can be a *dict-like* object and the extracted items are kept if and only if all
+    corresponding key-value pairs are equal:
+
+        assert_that(users).extracting('user', filter={'active': False}).is_equal_to(['Bob'])
+        assert_that(users).extracting('user', filter={'age': 36, 'active': True}).is_equal_to(['Alice'])
+
+    Or a *filter* can be any function (including an in-line ``lambda``) that accepts as its single
+    argument each item in the collection, and the extracted items are kept if the function
+    evaluates to ``True``:
+
+        assert_that(users).extracting('user', filter=lambda x: x['age'] > 20)
+            .is_equal_to(['Alice', 'Bob'])
+
+    **Sorting**
+
+    The ``extracting()`` helper can include a *sort* to enforce order on the extracted items.
+
+    The *sort* can be the name of a key (or attribute, or property, or zero-argument method) and
+    the extracted items are ordered by the corresponding values:
+
+        assert_that(users).extracting('user', sort='age').is_equal_to(['Charlie', 'Alice', 'Bob'])
+
+    The *sort* can be an iterable of names and the extracted items are ordered by
+    corresponding value of the first name, ties are broken by the corresponding values of the
+    second name, and so on:
+
+        assert_that(users).extracting('user', sort=['active', 'age']).is_equal_to(['Bob', 'Charlie', 'Alice'])
+
+    The *sort* can be any function (including an in-line ``lambda``) that accepts as its single
+    argument each item in the collection, and the extracted items are ordered by the corresponding
+    function return values:
+
+        assert_that(users).extracting('user', sort=lambda x: -x['age']).is_equal_to(['Bob', 'Alice', 'Charlie'])
+    """
+
+    def extracting(self, *names: object, **kwargs: object) -> Self:
+        """Asserts that val is iterable, then extracts the named attributes, properties, or
+        zero-arg methods into a list (or list of tuples if multiple names are given).
+
+        Args:
+            *names: the attribute to be extracted (or property or zero-arg method)
+            **kwargs (object): see below
+
+        Keyword Args:
+            filter (str | dict | Callable | None): extract only those items where filter is truthy
+            sort (str | Iterable | Callable | None): order the extracted items by the sort key
+
+        Examples:
+            Usage:
+
+                alice = User('Alice', 20, True)
+                bob = User('Bob', 30, False)
+                charlie = User('Charlie', 10, True)
+                users = [alice, bob, charlie]
+
+                assert_that(users).extracting('user').contains('Alice', 'Bob', 'Charlie')
+
+            Works with *dict-like* objects too:
+
+                users = [
+                    {'user': 'Alice', 'age': 20, 'active': True},
+                    {'user': 'Bob', 'age': 30, 'active': False},
+                    {'user': 'Charlie', 'age': 10, 'active': True}
+                ]
+
+                assert_that(people).extracting('user').contains('Alice', 'Bob', 'Charlie')
+
+            Filter:
+
+                assert_that(users).extracting('user', filter='active').is_equal_to(['Alice', 'Charlie'])
+
+            Sort:
+
+                assert_that(users).extracting('user', sort='age').is_equal_to(['Charlie', 'Alice', 'Bob'])
+
+        Returns:
+            AssertionBuilder: returns a new instance (extracted list as val) to chain the next assertion
+        """
+        reject_unknown_kwargs(kwargs, _EXTRACTING_OPTIONS, "extracting")
+        require_type(self.val, collections.abc.Iterable, "iterable")
+        if isinstance(self.val, str):
+            refuse(self.val, "a collection rather than a string")
+        if len(names) == 0:
+            raise ValueError("one or more name args must be given")
+
+        def _attr_value(item, name):
+            attr = getattr(item, name)
+            if not callable(attr):
+                return attr
+            try:
+                inspect.signature(attr).bind()
+            except TypeError:  # the callable needs arguments, so it is not a zero-arg method
+                raise _extraction_error(f"item method <{name}()> exists, but is not zero-arg method") from None
+            except ValueError:  # some builtins expose no introspectable signature; fall back to calling
+                pass
+            return attr()  # a TypeError from here comes from the method body, not an arity mismatch
+
+        def _extract(item, name):
+            if mapping_shaped(item, check_values=False):
+                if name in item:
+                    return item[name]
+                raise _extraction_error(f"item keys {list(item.keys())} did not contain key <{name}>")
+            if is_namedtuple(item) and type(name) is str:
+                if name in item._fields:
+                    return getattr(item, name)
+                if hasattr(item, name):  # a property or zero-arg method on the NamedTuple subclass
+                    return _attr_value(item, name)
+                raise _extraction_error(f"item attributes {item._fields} did not contain attribute <{name}>")
+            if isinstance(item, collections.abc.Iterable) and not is_model_dump_object(item):
+                self._check_iterable(item, name="item")
+                return item[name]
+            try:
+                return _attr_value(item, name)
+            except AttributeError as exc:
+                # hasattr() reports a raising accessor as a missing one, and the two want different messages
+                if hasattr(type(item), name):
+                    raise _extraction_error(
+                        f"item has property or zero-arg method <{name}>, but reading it raised AttributeError: {exc}"
+                    ) from exc
+                try:
+                    available = sorted(attr for attr in dir(item) if not attr.startswith("_"))
+                except Exception:  # a broken __dir__ must not replace the real diagnostic with its own
+                    available = []
+                # one suggestion: measured typos score ~0.9 while wrong neighbours sit at ~0.65
+                close = difflib.get_close_matches(str(name), available, n=1)
+                hint = f"; did you mean {close[0]!r}?" if close else ""
+                raise _extraction_error(f"item does not have property or zero-arg method <{name}>{hint}") from None
+
+        def _filter(item):
+            if "filter" in kwargs:
+                chosen = kwargs["filter"]
+                if isinstance(chosen, str):
+                    return bool(_extract(item, chosen))
+                elif mapping_shaped(chosen, check_values=False):
+                    mapping = cast("MappingLike", chosen)
+                    return all(_extract(item, key) == mapping[key] for key in mapping if isinstance(key, str))
+                elif callable(chosen):
+                    return cast("Callable[[object], object]", chosen)(item)
+                elif chosen is None:
+                    return True
+                refuse(chosen, "a str, a dict, or a callable", subject=argument("filter"))
+            return True
+
+        def _sort(item):
+            # an explicit `sort=None` means no ordering, and 0 is a stable no-op for it
+            sort = kwargs["sort"]
+            if isinstance(sort, str):
+                return _extract(item, sort)
+            if isinstance(sort, collections.abc.Iterable):
+                return tuple(_extract(item, key) for key in sort if isinstance(key, str))
+            if callable(sort):
+                return cast("Callable[[object], object]", sort)(item)
+            if sort is None:
+                return 0
+            # silently returning unsorted items would surface as a confusing order mismatch further down the chain
+            refuse(sort, "a str, an iterable, or a callable", subject=argument("sort"))
+
+        # only pay the sort when one was requested, so the extractor sees the source at the same point
+        source = sorted(self._walked(), key=_sort) if "sort" in kwargs else self._walked()
+        extracted = []
+        # counted here: the walk spends a generator, and asking a spent one said an emptied source had been empty
+        seen = 0
+        for index, item in enumerate(source):
+            seen += 1
+            if verdict(_filter(item), subject="the filter"):
+                try:
+                    extracted_values = [_extract(item, name) for name in names]
+                except ValueError as exc:
+                    if not getattr(exc, _OURS, False):
+                        raise
+                    localized = f"{exc} (at index {index}, item is <{type(item).__name__}>)"
+                    raise _extraction_error(localized) from exc.__cause__
+                extracted.append(tuple(extracted_values) if len(extracted_values) > 1 else extracted_values[0])
+
+        return self.builder(
+            extracted,
+            self.description,
+            self.kind,
+            logger=self.logger,
+            origin=f"extracting() produced {len(extracted)} of {seen} items",
+        )

assertpy/file.py

@@ -0,0 +1,324 @@
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, cast
+
+from ._engine._mixin_base import _MixinBase
+from ._engine._require import argument, require_type
+from .errors import _capped
+
+if TYPE_CHECKING:
+    from ._engine._compat import Self
+    from ._engine._introspection import Readable
+
+__tracebackhide__ = True
+
+
+def contents_of(file: str | bytes | os.PathLike[str] | os.PathLike[bytes] | Readable, encoding: str = "utf-8") -> str:
+    """Helper to read the contents of the given file or path into a string with the given encoding.
+
+    Args:
+        file (str | os.PathLike | IO): a *path-like object* (aka a file name) or a *file-like object* (aka a file)
+        encoding (str): the target encoding. Defaults to ``utf-8`` (others: ``ascii``, ``latin-1``).
+
+    Examples:
+        Usage:
+
+            from assertpy import assert_that, contents_of
+
+            contents = contents_of('foo.txt')
+            assert_that(contents).starts_with('foo').ends_with('bar').contains('oob')
+
+    Returns:
+        str: returns the file contents as a string
+
+    Raises:
+        IOError: if file not found
+        TypeError: if file is not a *path-like object* or a *file-like object*
+    """
+    try:
+        # the `except` is what decides this: a path has no `read`, and asking first would not tell us more
+        contents = cast("Readable", file).read()
+    except AttributeError:
+        try:
+            path = cast("str | bytes | os.PathLike[str] | os.PathLike[bytes]", file)
+            with open(path, encoding=encoding, errors="replace") as file_handle:
+                contents = file_handle.read()
+        except TypeError:
+            raise ValueError(f"val must be file or path, but was type <{type(file).__name__}>") from None
+        except OSError:
+            if not isinstance(file, (str, bytes, os.PathLike)):
+                raise ValueError(f"val must be file or path, but was type <{type(file).__name__}>") from None
+            raise
+
+    if isinstance(contents, (bytes, bytearray)):
+        return contents.decode(encoding, "replace")
+    return contents
+
+
+class FileMixin(_MixinBase):
+    """File assertions mixin."""
+
+    def exists(self) -> Self:
+        """Asserts that val is a path and that it exists.
+
+        Examples:
+            Usage:
+
+                assert_that('myfile.txt').exists()
+                assert_that('mydir').exists()
+
+        Returns:
+            AssertionBuilder: returns this instance to chain to the next assertion
+
+        Raises:
+            AssertionError: if val does **not** exist
+        """
+        missing = self._missing()
+        if missing is not None:
+            return self.error(missing)
+        return self
+
+    def does_not_exist(self) -> Self:
+        """Asserts that val is a path and that it does *not* exist.
+
+        Examples:
+            Usage:
+
+                assert_that('missing.txt').does_not_exist()
+                assert_that('missing_dir').does_not_exist()
+
+        Returns:
+            AssertionBuilder: returns this instance to chain to the next assertion
+
+        Raises:
+            AssertionError: if val **does** exist
+        """
+        require_type(self.val, (str, os.PathLike), "a path")
+        if os.path.exists(self.val):
+            return self.error(f"Expected <{_capped(self.val)}> to not exist, but was found.")
+        return self
+
+    def is_file(self) -> Self:
+        """Asserts that val is a *file* and that it exists.
+
+        Nothing at the path is one of the answers rather than a question left unasked, so
+        ``not_.is_file()`` holds for a path that does not exist.
+
+        Examples:
+            Usage:
+
+                assert_that('myfile.txt').is_file()
+
+        Returns:
+            AssertionBuilder: returns this instance to chain to the next assertion
+
+        Raises:
+            AssertionError: if val does **not** exist, or is **not** a file
+        """
+        not_a_file = self._not_a_file()
+        if not_a_file is not None:
+            return self.error(not_a_file)
+        return self
+
+    def is_directory(self) -> Self:
+        """Asserts that val is a *directory* and that it exists.
+
+        Nothing at the path is one of the answers rather than a question left unasked, so
+        ``not_.is_directory()`` holds for a path that does not exist.
+
+        Examples:
+            Usage:
+
+                assert_that('mydir').is_directory()
+
+        Returns:
+            AssertionBuilder: returns this instance to chain to the next assertion
+
+        Raises:
+            AssertionError: if val does **not** exist, or is **not** a directory
+        """
+        missing = self._missing()
+        if missing is not None:
+            return self.error(missing)
+        if not os.path.isdir(self.val):
+            return self.error(f"Expected <{_capped(self.val)}> to be a directory, but was not.")
+        return self
+
+    def is_named(self, filename: str) -> Self:
+        """Asserts that val is an existing path to a file and that file is named filename.
+
+        A path that is not an existing file fails it with or without ``not_``: the name is asked of the file.
+
+        Args:
+            filename: the expected filename
+
+        Examples:
+            Usage:
+
+                assert_that('/path/to/mydir/myfile.txt').is_named('myfile.txt')
+
+        Returns:
+            AssertionBuilder: returns this instance to chain to the next assertion
+
+        Raises:
+            AssertionError: if val does **not** exist, or is **not** a file, or is **not** named the given filename
+            TypeError: if filename is not a path, whatever val is
+        """
+        require_type(filename, (str, os.PathLike), "a path", subject=argument("filename"))
+        if not self._require_file():
+            return self
+        val_filename = os.path.basename(os.path.abspath(self.val))
+        expected_filename = os.fspath(filename)  # normalize an os.PathLike arg to its string form
+        if val_filename == expected_filename:
+            return self
+        return self.error(
+            f"Expected filename <{val_filename}> to be equal to <{expected_filename}>, but was not.",
+            expected=filename,
+        )
+
+    def is_child_of(self, parent: object) -> Self:
+        """Asserts that val is an existing path to a file and that file is a child of parent.
+
+        A path that is not an existing file fails it with or without ``not_``: the parent is asked of the file.
+
+        Args:
+            parent: the expected parent directory
+
+        Examples:
+            Usage:
+
+                assert_that('/path/to/mydir/myfile.txt').is_child_of('/path/to/mydir')
+                assert_that('/path/to/mydir/myfile.txt').is_child_of('/path/to')
+                assert_that('/path/to/mydir/myfile.txt').is_child_of('/path')
+
+        Returns:
+            AssertionBuilder: returns this instance to chain to the next assertion
+
+        Raises:
+            AssertionError: if val does **not** exist, is **not** a file, or is **not** a child of given directory
+            TypeError: if parent is not a path, whatever val is
+        """
+        parent_path = require_type(parent, (str, os.PathLike), "a path", subject=argument("parent directory"))
+        if not self._require_file():
+            return self
+        val_abspath = os.path.abspath(self.val)
+        parent_abspath = os.path.abspath(parent_path)
+        try:
+            is_child = os.path.commonpath([val_abspath, parent_abspath]) == parent_abspath != val_abspath
+        except ValueError:  # pragma: no cover - Windows-only: paths on different drives share no common path
+            is_child = False
+        if not is_child:
+            return self.error(
+                f"Expected file <{val_abspath}> to be a child of <{parent_abspath}>, but was not.", expected=parent_path
+            )
+        return self
+
+    def is_readable(self) -> Self:
+        """Asserts that val is an existing path and is readable.
+
+        A path that does not exist fails it with or without ``not_``: a permission is asked of what is at
+        the path.
+
+        Examples:
+            Usage:
+
+                assert_that('/path/to/file.txt').is_readable()
+
+        Returns:
+            AssertionBuilder: returns this instance to chain to the next assertion
+
+        Raises:
+            AssertionError: if val does **not** exist, or is **not** readable
+        """
+        if not self._require_existing():
+            return self
+        if not os.access(self.val, os.R_OK):
+            return self.error(f"Expected <{_capped(self.val)}> to be readable, but was not.")
+        return self
+
+    def is_writable(self) -> Self:
+        """Asserts that val is an existing path and is writable.
+
+        A path that does not exist fails it with or without ``not_``: a permission is asked of what is at
+        the path.
+
+        Examples:
+            Usage:
+
+                assert_that('/path/to/file.txt').is_writable()
+
+        Returns:
+            AssertionBuilder: returns this instance to chain to the next assertion
+
+        Raises:
+            AssertionError: if val does **not** exist, or is **not** writable
+        """
+        if not self._require_existing():
+            return self
+        if not os.access(self.val, os.W_OK):
+            return self.error(f"Expected <{_capped(self.val)}> to be writable, but was not.")
+        return self
+
+    def is_executable(self) -> Self:
+        """Asserts that val is an existing path and is executable.
+
+        A path that does not exist fails it with or without ``not_``: a permission is asked of what is at
+        the path.
+
+        Examples:
+            Usage:
+
+                assert_that('/path/to/script.sh').is_executable()
+
+        Returns:
+            AssertionBuilder: returns this instance to chain to the next assertion
+
+        Raises:
+            AssertionError: if val does **not** exist, or is **not** executable
+        """
+        if not self._require_existing():
+            return self
+        if not os.access(self.val, os.X_OK):
+            return self.error(f"Expected <{_capped(self.val)}> to be executable, but was not.")
+        return self
+
+    def _missing(self) -> str | None:
+        """The failure for a path that does not exist, or ``None`` when it does.
+
+        Composed once for both of its readings: `exists()` answers with it, and an assertion about what is
+        at the path reports it as the prerequisite its question presupposes.
+        """
+        require_type(self.val, (str, os.PathLike), "a path")
+        if os.path.exists(self.val):
+            return None
+        return f"Expected <{_capped(self.val)}> to exist, but was not found."
+
+    def _not_a_file(self) -> str | None:
+        """The failure for a path that is not an existing file, or ``None`` when it is one."""
+        missing = self._missing()
+        if missing is not None or os.path.isfile(self.val):
+            return missing
+        return f"Expected <{_capped(self.val)}> to be a file, but was not."
+
+    def _require_existing(self) -> bool:
+        """Whether val exists, after reporting as a prerequisite that it does not.
+
+        A permission belongs to what is at the path, so with nothing there the question has no answer.
+        Inverted, a mistyped path passed ``not_.is_readable()`` as a file nobody may read.
+        """
+        missing = self._missing()
+        if missing is not None:
+            self._unmet(missing)
+        return missing is None
+
+    def _require_file(self) -> bool:
+        """Whether val is an existing file, after reporting as a prerequisite that it is not.
+
+        A name and a parent are asked of the file at the path, so a missing path or a directory answers
+        neither the question nor its negation.
+        """
+        not_a_file = self._not_a_file()
+        if not_a_file is not None:
+            self._unmet(not_a_file)
+        return not_a_file is None