assertpy2 2.0.0__py3-none-any.whl

assertpy2/extracting.py

@@ -0,0 +1,233 @@
+# Copyright (c) 2015-2019, Activision Publishing, Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without modification,
+# are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice, this
+# list of conditions and the following disclaimer.
+#
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+# this list of conditions and the following disclaimer in the documentation
+# and/or other materials provided with the distribution.
+#
+# 3. Neither the name of the copyright holder nor the names of its contributors
+# may be used to endorse or promote products derived from this software without
+# specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+# ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+# ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+from __future__ import annotations
+
+import collections.abc
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+__tracebackhide__ = True
+
+
+class ExtractingMixin:
+    """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, **kwargs) -> 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: see below
+
+        Keyword Args:
+            filter: extract only those items where filter is truthy
+            sort: 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 (now with the extracted list as the val) to chain to the next assertion
+        """
+        if not isinstance(self.val, collections.abc.Iterable):
+            raise TypeError("val is not iterable")
+        if isinstance(self.val, str):
+            raise TypeError("val must not be string")
+        if len(names) == 0:
+            raise ValueError("one or more name args must be given")
+
+        def _extract(x, name):
+            if self._check_dict_like(x, check_values=False, return_as_bool=True):
+                if name in x:
+                    return x[name]
+                else:
+                    raise ValueError("item keys %s did not contain key <%s>" % (list(x.keys()), name))
+            elif isinstance(x, tuple) and hasattr(x, "_fields") and type(name) is str:
+                if name in x._fields:
+                    return getattr(x, name)
+                else:  # val has no attribute <foo>
+                    raise ValueError("item attributes %s did no contain attribute <%s>" % (x._fields, name))
+            elif isinstance(x, collections.abc.Iterable):  # FIXME, this does __getitem__, but doesn't check for it...
+                self._check_iterable(x, name="item")
+                return x[name]
+            elif hasattr(x, name):
+                attr = getattr(x, name)
+                if callable(attr):
+                    try:
+                        return attr()
+                    except TypeError:
+                        raise ValueError("item method <%s()> exists, but is not zero-arg method" % name) from None
+                else:
+                    return attr
+            else:
+                raise ValueError("item does not have property or zero-arg method <%s>" % name)
+
+        def _filter(x):
+            if "filter" in kwargs:
+                if isinstance(kwargs["filter"], str):
+                    return bool(_extract(x, kwargs["filter"]))
+                elif self._check_dict_like(kwargs["filter"], check_values=False, return_as_bool=True):
+                    for k in kwargs["filter"]:
+                        if isinstance(k, str) and _extract(x, k) != kwargs["filter"][k]:
+                            return False
+                    return True
+                elif callable(kwargs["filter"]):
+                    return kwargs["filter"](x)
+                return kwargs["filter"] is None
+            return True
+
+        def _sort(x):
+            if "sort" in kwargs:
+                if isinstance(kwargs["sort"], str):
+                    return _extract(x, kwargs["sort"])
+                elif isinstance(kwargs["sort"], collections.abc.Iterable):
+                    items = []
+                    for k in kwargs["sort"]:
+                        if isinstance(k, str):
+                            items.append(_extract(x, k))
+                    return tuple(items)
+                elif callable(kwargs["sort"]):
+                    return kwargs["sort"](x)
+            return 0
+
+        extracted = []
+        for i in sorted(self.val, key=lambda x: _sort(x)):
+            if _filter(i):
+                items = [_extract(i, name) for name in names]
+                extracted.append(tuple(items) if len(items) > 1 else items[0])
+
+        # chain on with _extracted_ list (don't chain to self!)
+        return self.builder(extracted, self.description, self.kind)

assertpy2/file.py

@@ -0,0 +1,276 @@
+# Copyright (c) 2015-2019, Activision Publishing, Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without modification,
+# are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice, this
+# list of conditions and the following disclaimer.
+#
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+# this list of conditions and the following disclaimer in the documentation
+# and/or other materials provided with the distribution.
+#
+# 3. Neither the name of the copyright holder nor the names of its contributors
+# may be used to endorse or promote products derived from this software without
+# specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+# ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+# ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+__tracebackhide__ = True
+
+
+def contents_of(file, encoding="utf-8"):
+    """Helper to read the contents of the given file or path into a string with the given encoding.
+
+    Args:
+        file: 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``, other useful encodings are ``ascii`` and ``latin-1``.
+
+    Examples:
+        Usage::
+
+            from assertpy2 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:
+        contents = file.read()
+    except AttributeError:
+        try:
+            with open(file) as fp:
+                contents = fp.read()
+        except TypeError:
+            raise ValueError("val must be file or path, but was type <%s>" % type(file).__name__) from None
+        except OSError:
+            if not isinstance(file, (str, os.PathLike)):
+                raise ValueError("val must be file or path, but was type <%s>" % type(file).__name__) from None
+            raise
+
+    if type(contents) is bytes:
+        return contents.decode(encoding, "replace")
+    try:
+        return contents.decode(encoding, "replace")
+    except AttributeError:
+        pass
+    # if all else fails, just return the contents "as is"
+    return contents
+
+
+class FileMixin:
+    """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
+        """
+        if not isinstance(self.val, (str, os.PathLike)):
+            raise TypeError("val is not a path")
+        if not os.path.exists(self.val):
+            return self.error("Expected <%s> to exist, but was not found." % self.val)
+        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
+        """
+        if not isinstance(self.val, (str, os.PathLike)):
+            raise TypeError("val is not a path")
+        if os.path.exists(self.val):
+            return self.error("Expected <%s> to not exist, but was found." % self.val)
+        return self
+
+    def is_file(self) -> Self:
+        """Asserts that val is a *file* and that it exists.
+
+        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
+        """
+        self.exists()
+        if not os.path.isfile(self.val):
+            return self.error("Expected <%s> to be a file, but was not." % self.val)
+        return self
+
+    def is_directory(self) -> Self:
+        """Asserts that val is a *directory* and that it exists.
+
+        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
+        """
+        self.exists()
+        if not os.path.isdir(self.val):
+            return self.error("Expected <%s> to be a directory, but was not." % self.val)
+        return self
+
+    def is_named(self, filename) -> Self:
+        """Asserts that val is an existing path to a file and that file is named filename.
+
+        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
+        """
+        self.is_file()
+        if not isinstance(filename, (str, os.PathLike)):
+            raise TypeError("given filename arg must be a path")
+        val_filename = os.path.basename(os.path.abspath(self.val))
+        if val_filename != filename:
+            return self.error("Expected filename <%s> to be equal to <%s>, but was not." % (val_filename, filename))
+        return self
+
+    def is_child_of(self, parent) -> Self:
+        """Asserts that val is an existing path to a file and that file is a child of parent.
+
+        Args:
+            parent: the expected parent directory
+
+        Examples:
+            Usage::
+
+                assert_that('/path/to/mydir/myfile.txt').is_child_of('mydir')
+                assert_that('/path/to/mydir/myfile.txt').is_child_of('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, or is **not** a file, or is **not** a child of the given directory
+        """
+        self.is_file()
+        if not isinstance(parent, (str, os.PathLike)):
+            raise TypeError("given parent directory arg must be a path")
+        val_abspath = os.path.abspath(self.val)
+        parent_abspath = os.path.abspath(parent)
+        if not val_abspath.startswith(parent_abspath):
+            return self.error("Expected file <%s> to be a child of <%s>, but was not." % (val_abspath, parent_abspath))
+        return self
+
+    def is_readable(self) -> Self:
+        """Asserts that val is an existing path and is readable.
+
+        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
+        """
+        self.exists()
+        if not os.access(self.val, os.R_OK):
+            return self.error("Expected <%s> to be readable, but was not." % self.val)
+        return self
+
+    def is_writable(self) -> Self:
+        """Asserts that val is an existing path and is writable.
+
+        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
+        """
+        self.exists()
+        if not os.access(self.val, os.W_OK):
+            return self.error("Expected <%s> to be writable, but was not." % self.val)
+        return self
+
+    def is_executable(self) -> Self:
+        """Asserts that val is an existing path and is executable.
+
+        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
+        """
+        self.exists()
+        if not os.access(self.val, os.X_OK):
+            return self.error("Expected <%s> to be executable, but was not." % self.val)
+        return self