assertpy2 2.3.4__tar.gz → 2.3.6__tar.gz

assertpy2-2.3.6/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing
+
+Contributions of docs, tests, or code are welcome.
+
+## Workflow
+
+1. Fork the repo
+2. Clone your fork (`git clone <your_fork_url>`)
+3. Create a branch (`git checkout -b my_branch`)
+4. Install dependencies: `uv sync`
+5. Make your changes
+6. Run the [verification pipeline](#verification-pipeline) and fix any issues
+7. Commit using [Conventional Commits](#commit-style)
+8. Push your branch (`git push origin my_branch`)
+9. Open a [Pull Request](http://github.com/Solganis/assertpy2/pulls)
+
+Read more about how pulls work on GitHub's [About pull requests](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) page.
+
+## Requirements
+
+- Python 3.10+
+- [uv](https://docs.astral.sh/uv/) as the package manager
+
+## Verification pipeline
+
+Run all checks before submitting a PR. Every step must pass.
+
+```bash
+# lint
+uv run ruff check assertpy2/ tests/
+
+# format
+uv run ruff format --check assertpy2/ tests/
+
+# type check
+uv run ty check
+
+# tests with coverage (must be 100%)
+uv run pytest tests/ -v --cov=assertpy2 --cov-report=term-missing
+```
+
+CI requires 100% code coverage.
+
+## Commit style
+
+Use [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`, etc.
+
+## Tests
+
+Write tests for every new feature or bug fix. Use `assertpy2` assertions in tests.

{assertpy2-2.3.4 → assertpy2-2.3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assertpy2
-Version: 2.3.4
+Version: 2.3.6
 Summary: Fluent assertion library for Python with composable matchers, structural matching, and full type safety
 Project-URL: Homepage, https://github.com/Solganis/assertpy2
 Project-URL: Repository, https://github.com/Solganis/assertpy2
@@ -160,8 +160,10 @@ assert_that(items).is_type_of(list).is_length(3).contains("admin")
 
 ## Features
 
-- [**Composable matchers**](docs/api.md#composable-matchers): `match.greater_than(5)`, `match.is_uuid()`, combine with `&`, `|`, `~` operators.
+- [**Composable matchers**](docs/api.md#composable-matchers): `match.greater_than(5)`, `match.is_uuid()`, combine with `&`, `|`, `~`. Also work with plain `assert ==`.
 - [**Structural matching**](docs/api.md#structural-matching): `matches_structure()` for declarative dict/API response validation.
+- [**Universal negation**](docs/api.md#universal-negation): `.not_` inverts any assertion without dedicated `is_not_*` methods.
+- [**Collection pipeline**](docs/api.md#collection-pipeline): `filtered_on()`, `mapped()`, `flat_mapped()`, `first()`, `last()`, `element()`, `single()` for transforming collections before assertions.
 - [**Async assertions**](docs/api.md#async-assertions): `eventually()` with polling/retry for async and eventual consistency testing.
 - [**Structured errors**](docs/api.md#structured-errors): `AssertionFailure` with `.actual`, `.expected`, `.diff` attributes, pytest plugin with rich diff output.
 - **Typed overloads**: `assert_that()` returns type-specific Protocols, IDE shows only relevant methods per type.
@@ -204,6 +206,15 @@ assert_that("hello").satisfies(~match.equal_to("world"))
 assert_that(150).satisfies(match.is_negative() | match.greater_than(100))
 ```
 
+Matchers also support `==` directly, so you can use them with plain `assert` or mix into dicts and lists:
+
+```py
+from assertpy2 import match
+
+assert 42 == match.is_positive()
+assert {"id": 5, "name": "Alice"} == {"id": match.is_positive(), "name": match.is_non_empty_string()}
+```
+
 Available matchers: `equal_to`, `greater_than`, `greater_than_or_equal_to`, `less_than`, `less_than_or_equal_to`, `between`, `close_to`, `is_none`, `is_not_none`, `is_instance_of`, `has_length`, `is_empty`, `is_not_empty`, `is_positive`, `is_negative`, `is_zero`, `is_even`, `is_odd`, `is_divisible_by`, `is_callable`, `is_in`, `has_property`, `contains_string`, `matches_regex`, `is_uuid`, `is_non_empty_string`, `ignore`, `each_item`, `structure`.
 
 
@@ -309,6 +320,38 @@ DiffResult(kind='dict', entries=[DiffEntry(path='b', actual=2, expected=99)])
 
 ## More features
 
+### Universal negation
+
+Invert any assertion with `.not_`:
+
+```py
+assert_that(5).not_.is_none()
+assert_that("abc123").not_.is_alpha()
+assert_that([3, 1, 2]).not_.is_sorted()
+assert_that(value).described_as("check").not_.is_none().is_positive()
+```
+
+Works with soft assertions and warn mode.
+
+### Collection pipeline
+
+Transform collections before asserting:
+
+```py
+orders = [Order("DONE", 100), Order("FAILED", 50), Order("DONE", 200)]
+
+assert_that(orders).filtered_on(lambda o: o.status == "FAILED").is_length(1)
+assert_that(orders).mapped(lambda o: o.total).contains(100, 200)
+assert_that(orders).first().has_status("DONE")
+assert_that(orders).element(1).has_status("FAILED")
+assert_that([42]).single().is_equal_to(42)
+
+# chaining pipeline steps
+assert_that(items).filtered_on(match.is_positive()).mapped(str).contains("1")
+```
+
+Available methods: `filtered_on()`, `mapped()`, `flat_mapped()`, `first()`, `last()`, `element()`, `single()`.
+
 ### Dict comparison with ignore/include
 
 ```py
@@ -483,19 +526,3 @@ See the [comparison table](#comparison) above for feature differences with other
 Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
 
 
-## License
-
-All files are licensed under the BSD 3-Clause License as follows:
-
-> 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.

{assertpy2-2.3.4 → assertpy2-2.3.6}/README.md

@@ -125,8 +125,10 @@ assert_that(items).is_type_of(list).is_length(3).contains("admin")
 
 ## Features
 
-- [**Composable matchers**](docs/api.md#composable-matchers): `match.greater_than(5)`, `match.is_uuid()`, combine with `&`, `|`, `~` operators.
+- [**Composable matchers**](docs/api.md#composable-matchers): `match.greater_than(5)`, `match.is_uuid()`, combine with `&`, `|`, `~`. Also work with plain `assert ==`.
 - [**Structural matching**](docs/api.md#structural-matching): `matches_structure()` for declarative dict/API response validation.
+- [**Universal negation**](docs/api.md#universal-negation): `.not_` inverts any assertion without dedicated `is_not_*` methods.
+- [**Collection pipeline**](docs/api.md#collection-pipeline): `filtered_on()`, `mapped()`, `flat_mapped()`, `first()`, `last()`, `element()`, `single()` for transforming collections before assertions.
 - [**Async assertions**](docs/api.md#async-assertions): `eventually()` with polling/retry for async and eventual consistency testing.
 - [**Structured errors**](docs/api.md#structured-errors): `AssertionFailure` with `.actual`, `.expected`, `.diff` attributes, pytest plugin with rich diff output.
 - **Typed overloads**: `assert_that()` returns type-specific Protocols, IDE shows only relevant methods per type.
@@ -169,6 +171,15 @@ assert_that("hello").satisfies(~match.equal_to("world"))
 assert_that(150).satisfies(match.is_negative() | match.greater_than(100))
 ```
 
+Matchers also support `==` directly, so you can use them with plain `assert` or mix into dicts and lists:
+
+```py
+from assertpy2 import match
+
+assert 42 == match.is_positive()
+assert {"id": 5, "name": "Alice"} == {"id": match.is_positive(), "name": match.is_non_empty_string()}
+```
+
 Available matchers: `equal_to`, `greater_than`, `greater_than_or_equal_to`, `less_than`, `less_than_or_equal_to`, `between`, `close_to`, `is_none`, `is_not_none`, `is_instance_of`, `has_length`, `is_empty`, `is_not_empty`, `is_positive`, `is_negative`, `is_zero`, `is_even`, `is_odd`, `is_divisible_by`, `is_callable`, `is_in`, `has_property`, `contains_string`, `matches_regex`, `is_uuid`, `is_non_empty_string`, `ignore`, `each_item`, `structure`.
 
 
@@ -274,6 +285,38 @@ DiffResult(kind='dict', entries=[DiffEntry(path='b', actual=2, expected=99)])
 
 ## More features
 
+### Universal negation
+
+Invert any assertion with `.not_`:
+
+```py
+assert_that(5).not_.is_none()
+assert_that("abc123").not_.is_alpha()
+assert_that([3, 1, 2]).not_.is_sorted()
+assert_that(value).described_as("check").not_.is_none().is_positive()
+```
+
+Works with soft assertions and warn mode.
+
+### Collection pipeline
+
+Transform collections before asserting:
+
+```py
+orders = [Order("DONE", 100), Order("FAILED", 50), Order("DONE", 200)]
+
+assert_that(orders).filtered_on(lambda o: o.status == "FAILED").is_length(1)
+assert_that(orders).mapped(lambda o: o.total).contains(100, 200)
+assert_that(orders).first().has_status("DONE")
+assert_that(orders).element(1).has_status("FAILED")
+assert_that([42]).single().is_equal_to(42)
+
+# chaining pipeline steps
+assert_that(items).filtered_on(match.is_positive()).mapped(str).contains("1")
+```
+
+Available methods: `filtered_on()`, `mapped()`, `flat_mapped()`, `first()`, `last()`, `element()`, `single()`.
+
 ### Dict comparison with ignore/include
 
 ```py
@@ -448,19 +491,3 @@ See the [comparison table](#comparison) above for feature differences with other
 Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
 
 
-## License
-
-All files are licensed under the BSD 3-Clause License as follows:
-
-> 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.

{assertpy2-2.3.4 → assertpy2-2.3.6}/assertpy2/__init__.py

@@ -1,4 +1,5 @@
 from .assertpy import (
+    NegatedBuilder,
     WarningLoggingAdapter,
     __version__,
     add_extension,
@@ -20,6 +21,7 @@ __all__ = [
     "DiffEntry",
     "DiffResult",
     "Matcher",
+    "NegatedBuilder",
     "WarningLoggingAdapter",
     "__version__",
     "add_extension",

{assertpy2-2.3.4 → assertpy2-2.3.6}/assertpy2/_typing.py

@@ -8,6 +8,7 @@ if TYPE_CHECKING:
 
     from typing_extensions import Self
 
+    from .assertpy import NegatedBuilder
     from .async_assertions import AsyncAssertionBuilder
     from .matchers import Matcher
 
@@ -35,6 +36,9 @@ if TYPE_CHECKING:
         def is_not_in(self, *items: object) -> Self: ...
         # SnapshotMixin
         def snapshot(self, id: str | None = ..., path: str = ...) -> Self: ...
+        # NegatedBuilder
+        @property
+        def not_(self) -> NegatedBuilder: ...
 
     class _StringAssertion(_CoreAssertion, Protocol):
         """Assertions available for ``str`` values."""
@@ -129,6 +133,14 @@ if TYPE_CHECKING:
         def any_satisfy(self, matcher: Matcher | Callable[..., bool]) -> Self: ...
         def all_satisfy(self, matcher: Matcher | Callable[..., bool]) -> Self: ...
         def none_satisfy(self, matcher: Matcher | Callable[..., bool]) -> Self: ...
+        # CollectionMixin - pipeline
+        def filtered_on(self, predicate: Callable[..., bool]) -> Self: ...
+        def mapped(self, func: Callable[..., object]) -> Self: ...
+        def flat_mapped(self, func: Callable[..., object]) -> Self: ...
+        def first(self) -> Self: ...
+        def last(self) -> Self: ...
+        def element(self, index: int) -> Self: ...
+        def single(self) -> Self: ...
 
     class _DictAssertion(_CoreAssertion, Protocol):
         """Assertions available for ``dict`` values."""

{assertpy2-2.3.4 → assertpy2-2.3.6}/assertpy2/assertpy.py

@@ -1,31 +1,3 @@
-# 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.
-
 """Assertion library for python unit testing with a fluent API"""
 
 from __future__ import annotations
@@ -37,13 +9,12 @@ import logging
 import os
 import sys
 import types
-from collections.abc import Iterator
+from collections.abc import Callable, Iterator
 from typing import TYPE_CHECKING, overload
 
 if TYPE_CHECKING:
     import datetime
     import pathlib
-    from collections.abc import Callable
 
     from typing_extensions import Self
 
@@ -73,7 +44,7 @@ from .numeric import NumericMixin
 from .snapshot import SnapshotMixin
 from .string import StringMixin
 
-__version__ = "2.3.4"
+__version__ = "2.3.6"
 
 __tracebackhide__ = True  # clean tracebacks via py.test integration
 contextlib.__tracebackhide__ = True  # ty: ignore[unresolved-attribute]  # pytest monkey-patch
@@ -397,7 +368,6 @@ def _builder(val, description="", kind=None, expected=None, logger=None):
     """Internal helper to build a new :class:`AssertionBuilder` instance and glue on any extension methods."""
     ab = AssertionBuilder(val, description, kind, expected, logger)
     if _extensions:
-        # glue extension method onto new builder instance
         for name, func in _extensions.items():
             meth = types.MethodType(func, ab)
             setattr(ab, name, meth)
@@ -410,13 +380,11 @@ class WarningLoggingAdapter(logging.LoggerAdapter):
 
     def process(self, msg, kwargs):
         def _unwind(frame):
-            # walk all the frames
             frames = []
             while frame:
                 frames.append((frame.f_code.co_filename, frame.f_lineno))
                 frame = frame.f_back
 
-            # in reverse, find the first assertpy frame (and return the previous one)
             prev = None
             for frame in reversed(
                 frames
@@ -439,6 +407,65 @@ _logger.addHandler(_handler)
 _default_logger = WarningLoggingAdapter(_logger, None)
 
 
+class NegatedBuilder:
+    """Proxy that inverts the next assertion. Created by ``assert_that(val).not_``."""
+
+    def __init__(self, builder: AssertionBuilder) -> None:
+        self._builder = builder
+
+    def __getattr__(self, name: str) -> object:
+        attr = getattr(self._builder, name)
+        if not callable(attr):
+            return attr
+
+        def _negated(*args: object, **kwargs: object) -> AssertionBuilder:
+            if self._builder.kind == "soft":
+                return self._negated_soft(name, attr, *args, **kwargs)
+            if self._builder.kind == "warn":
+                return self._negated_warn(name, attr, *args, **kwargs)
+            return self._negated_strict(name, attr, *args, **kwargs)
+
+        return _negated
+
+    def _make_msg(self, name: str) -> str:
+        desc = f"[{self._builder.description}] " if self._builder.description else ""
+        return f"{desc}Expected <{self._builder.val}> to NOT satisfy: {name}()"
+
+    def _negated_strict(
+        self, name: str, attr: Callable[..., object], *args: object, **kwargs: object
+    ) -> AssertionBuilder:
+        try:
+            attr(*args, **kwargs)
+        except (AssertionError, AssertionFailure):
+            return self._builder
+        raise AssertionError(self._make_msg(name))
+
+    def _negated_soft(
+        self, name: str, attr: Callable[..., object], *args: object, **kwargs: object
+    ) -> AssertionBuilder:
+        err_list = _soft_err.get()
+        before = len(err_list)
+        attr(*args, **kwargs)
+        if len(err_list) > before:
+            del err_list[before:]
+            return self._builder
+        err_list.append(self._make_msg(name))
+        return self._builder
+
+    def _negated_warn(
+        self, name: str, attr: Callable[..., object], *args: object, **kwargs: object
+    ) -> AssertionBuilder:
+        self._builder.kind = None
+        try:
+            attr(*args, **kwargs)
+        except (AssertionError, AssertionFailure):
+            return self._builder
+        finally:
+            self._builder.kind = "warn"
+        self._builder.logger.warning(self._make_msg(name))
+        return self._builder
+
+
 class AssertionBuilder(
     StringMixin,
     SnapshotMixin,
@@ -477,6 +504,11 @@ class AssertionBuilder(
         self.logger = logger if logger else _default_logger
         self._not_expected = False
 
+    @property
+    def not_(self) -> NegatedBuilder:
+        """Invert the next assertion in the chain."""
+        return NegatedBuilder(self)
+
     def builder(self, val, description="", kind=None, expected=None, logger=None):
         """Helper to build a new :class:`AssertionBuilder` instance. Use this only if not chaining to ``self``.
 

{assertpy2-2.3.4 → assertpy2-2.3.6}/assertpy2/base.py

@@ -1,31 +1,3 @@
-# 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

{assertpy2-2.3.4 → assertpy2-2.3.6}/assertpy2/collection.py

@@ -1,37 +1,11 @@
-# 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
-from typing import TYPE_CHECKING
+from collections.abc import Callable, Iterable
+from typing import TYPE_CHECKING, Any
 
 from ._mixin_base import _MixinBase
+from .matchers import BaseMatcher
 
 if TYPE_CHECKING:
     from typing_extensions import Self
@@ -118,7 +92,6 @@ class CollectionMixin(_MixinBase):
 
         missing = []
         if hasattr(self.val, "keys") and callable(self.val.keys) and hasattr(self.val, "__getitem__"):
-            # flatten superset dicts
             superdict = {}
             for idx, j in enumerate(supersets):
                 self._check_dict_like(j, check_values=False, name=f"arg #{idx + 1}")
@@ -136,7 +109,6 @@ class CollectionMixin(_MixinBase):
                     f"but {self._fmt_items(missing)} {'was' if len(missing) == 1 else 'were'} missing."
                 )
         else:
-            # flatten supersets
             superset = set()
             for j in supersets:
                 try:
@@ -207,3 +179,151 @@ class CollectionMixin(_MixinBase):
             prev = x
 
         return self
+
+    def filtered_on(self, predicate: Callable[[Any], bool]) -> Self:
+        """Returns a new builder with elements matching the predicate.
+
+        Args:
+            predicate: callable or Matcher. If a Matcher, uses ``predicate.matches(item)``.
+
+        Examples:
+            Usage::
+
+                assert_that([1, -2, 3]).filtered_on(lambda x: x > 0).is_length(2)
+                assert_that(items).filtered_on(match.is_positive()).is_not_empty()
+
+        Returns:
+            AssertionBuilder: returns a new instance with the filtered list as val
+        """
+        if not isinstance(self.val, collections.abc.Iterable):
+            raise TypeError("val is not iterable")
+        if isinstance(predicate, BaseMatcher):
+            filtered = [item for item in self.val if predicate.matches(item)]
+        else:
+            filtered = [item for item in self.val if predicate(item)]
+        return self.builder(filtered, self.description, self.kind)
+
+    def mapped(self, func: Callable[[Any], Any]) -> Self:
+        """Returns a new builder with each element transformed by func.
+
+        Args:
+            func: callable applied to each element.
+
+        Examples:
+            Usage::
+
+                assert_that(["a", "b"]).mapped(str.upper).contains("A")
+
+        Returns:
+            AssertionBuilder: returns a new instance with the mapped list as val
+        """
+        if not isinstance(self.val, collections.abc.Iterable):
+            raise TypeError("val is not iterable")
+        return self.builder([func(item) for item in self.val], self.description, self.kind)
+
+    def flat_mapped(self, func: Callable[[Any], Iterable[Any]]) -> Self:
+        """Returns a new builder with each element expanded and flattened by func.
+
+        Args:
+            func: callable returning an iterable for each element.
+
+        Examples:
+            Usage::
+
+                assert_that(["ab", "cd"]).flat_mapped(list).contains("a", "c")
+
+        Returns:
+            AssertionBuilder: returns a new instance with the flattened list as val
+        """
+        if not isinstance(self.val, collections.abc.Iterable):
+            raise TypeError("val is not iterable")
+        return self.builder([x for item in self.val for x in func(item)], self.description, self.kind)
+
+    def first(self) -> Self:
+        """Returns a new builder with the first element of val.
+
+        Examples:
+            Usage::
+
+                assert_that([10, 20, 30]).first().is_equal_to(10)
+
+        Returns:
+            AssertionBuilder: returns a new instance with the first element as val
+
+        Raises:
+            ValueError: if val is empty
+        """
+        if not isinstance(self.val, collections.abc.Iterable):
+            raise TypeError("val is not iterable")
+        items = list(self.val)
+        if not items:
+            raise ValueError("Expected non-empty iterable, but was empty.")
+        return self.builder(items[0], self.description, self.kind)
+
+    def last(self) -> Self:
+        """Returns a new builder with the last element of val.
+
+        Examples:
+            Usage::
+
+                assert_that([10, 20, 30]).last().is_equal_to(30)
+
+        Returns:
+            AssertionBuilder: returns a new instance with the last element as val
+
+        Raises:
+            ValueError: if val is empty
+        """
+        if not isinstance(self.val, collections.abc.Iterable):
+            raise TypeError("val is not iterable")
+        items = list(self.val)
+        if not items:
+            raise ValueError("Expected non-empty iterable, but was empty.")
+        return self.builder(items[-1], self.description, self.kind)
+
+    def element(self, index: int) -> Self:
+        """Returns a new builder with the element at the given index.
+
+        Args:
+            index: zero-based index.
+
+        Examples:
+            Usage::
+
+                assert_that([10, 20, 30]).element(1).is_equal_to(20)
+
+        Returns:
+            AssertionBuilder: returns a new instance with the selected element as val
+
+        Raises:
+            IndexError: if index is out of range
+        """
+        if not isinstance(self.val, collections.abc.Iterable):
+            raise TypeError("val is not iterable")
+        items = list(self.val)
+        if index < 0 or index >= len(items):
+            raise IndexError(f"Expected index {index} to be in range [0, {len(items)}), but was out of range.")
+        return self.builder(items[index], self.description, self.kind)
+
+    def single(self) -> Self:
+        """Returns a new builder with the only element of val.
+
+        Examples:
+            Usage::
+
+                assert_that([42]).single().is_equal_to(42)
+
+        Returns:
+            AssertionBuilder: returns a new instance with the single element as val
+
+        Raises:
+            ValueError: if val is empty or has more than one element
+        """
+        if not isinstance(self.val, collections.abc.Iterable):
+            raise TypeError("val is not iterable")
+        items = list(self.val)
+        if not items:
+            raise ValueError("Expected iterable with single element, but was empty.")
+        if len(items) > 1:
+            raise ValueError(f"Expected iterable with single element, but had {len(items)} elements.")
+        return self.builder(items[0], self.description, self.kind)