qa-testing-utils 0.0.7__tar.gz → 0.0.8__tar.gz

{qa_testing_utils-0.0.7 → qa_testing_utils-0.0.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: qa-testing-utils
-Version: 0.0.7
+Version: 0.0.8
 Summary: QA testing utilities
 Author-Email: Adrian Herscu <adrian.herscu@gmail.com>
 License: Apache-2.0

{qa_testing_utils-0.0.7 → qa_testing_utils-0.0.8}/pyproject.toml

@@ -31,7 +31,7 @@ dependencies = [
     "more-itertools==10.7.0",
     "returns==0.25.0",
 ]
-version = "0.0.7"
+version = "0.0.8"
 
 [project.license]
 text = "Apache-2.0"

qa_testing_utils-0.0.8/src/qa_testing_utils/__init__.py

@@ -0,0 +1 @@
+__version__ = '0.0.8'

qa_testing_utils-0.0.8/src/qa_testing_utils/conftest_helpers.py

@@ -0,0 +1,47 @@
+# SPDX-FileCopyrightText: 2025 Adrian Herscu
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import inspect
+import logging.config
+from pathlib import Path
+import sys
+from typing import Callable, Optional
+
+import pytest
+
+
+def configure(config: pytest.Config,
+              path: Path = Path(__file__).parent / "logging.ini") -> None:
+    """
+    Configures logging for pytest using a specified INI file, or defaults to internal logging.ini.
+    """
+    caller_module = inspect.getmodule(inspect.stack()[1][0])
+    module_name = caller_module.__name__ if caller_module else "unknown"
+
+    if path.is_file():
+        logging.config.fileConfig(path)
+        logging.info(f"{module_name} loaded logs config from: {path}")
+    else:
+        sys.stderr.write(f"{module_name} couldn't find logs config file {path}")
+
+
+def makereport(
+        item: pytest.Item, call: pytest.CallInfo[None]) -> pytest.TestReport:
+    report = pytest.TestReport.from_item_and_call(item, call)
+
+    if call.when == "call":
+        report.sections.append(('body', get_test_body(item)))
+
+    return report
+
+
+def get_test_body(item: pytest.Item) -> str:
+    function: Optional[Callable[..., None]] = getattr(item, 'function', None)
+    if function is None:
+        return "No function found for this test item."
+
+    try:
+        return inspect.getsource(function)
+    except Exception as e:
+        return f"Could not get source code: {str(e)}"

{qa_testing_utils-0.0.7 → qa_testing_utils-0.0.8}/src/qa_testing_utils/exception_utils.py

@@ -7,7 +7,7 @@ import logging
 from typing import Any, Callable
 
 from returns.maybe import Maybe, Nothing, Some
-from qa_testing_utils.object_utils import Supplier
+from qa_testing_utils.stream_utils import Supplier
 
 
 def safely[T](supplier: Supplier[T]) -> Maybe[T]:

{qa_testing_utils-0.0.7 → qa_testing_utils-0.0.8}/src/qa_testing_utils/file_utils.py

@@ -88,7 +88,7 @@ def stream_file(
         Iterator[bytes]: the binary chunks stream
     """
     with file_path.open('rb') as f:
-        yield from iter(lambda: f.read(chunk_size), EMPTY_BYTE_STRING)
+        yield from iter(lambda: f.read(chunk_size), EMPTY_BYTES)
 
 
 def read_lines(
@@ -180,7 +180,7 @@ def crc32_of(file: BinaryIO, chunk_size: int = DEFAULT_BUFFER_SIZE) -> int:
     return crc_value & 0xFFFFFFFF  # ensure 32-bit unsigned
 
 
-def write_csv(file_path: Path, data_stream: Iterable[dict]):
+def write_csv(file_path: Path, data_stream: Iterable[dict[str, object]]):
     """
     Writes a stream of flattened telemetry packets to a CSV file.
 
@@ -189,8 +189,13 @@ def write_csv(file_path: Path, data_stream: Iterable[dict]):
         data_stream: Iterable of dictionaries representing the rows to be written.
     """
     stream = peekable(data_stream)  # Allow peeking to extract headers
+    try:
+        first_row: dict[str, object] = stream.peek()
+    except StopIteration:
+        # No data to write
+        return
     with file_path.open(mode="w", newline="") as csv_file:
         writer = csv.DictWriter(
-            csv_file, fieldnames=list(stream.peek().keys()))
+            csv_file, fieldnames=list(first_row.keys()))
         writer.writeheader()
         writer.writerows(stream)

{qa_testing_utils-0.0.7 → qa_testing_utils-0.0.8}/src/qa_testing_utils/logger.py

@@ -8,7 +8,7 @@ from functools import cached_property, wraps
 from typing import Callable, ParamSpec, TypeVar, cast, final
 
 import allure
-from qa_testing_utils.string_utils import EMPTY, LF
+from qa_testing_utils.string_utils import EMPTY_STRING, LF
 
 
 def trace[T](value: T) -> T:
@@ -55,7 +55,15 @@ def logger[T:type](cls: T) -> T:
 
 class LoggerMixin:
     """
-    Yet another way of adding logging by deriving from this one.
+    Mixin that provides a `log` property for convenient class-based logging.
+
+    Inherit from this mixin to get a `self.log` logger named after the class.
+    Useful for adding debug/info/error logging to any class without boilerplate.
+
+    Example:
+        class MyClass(LoggerMixin):
+            def do_something(self):
+                self.log.info("Doing something")
     """
     @final
     @cached_property
@@ -91,8 +99,15 @@ R = TypeVar('R')
 
 def traced(func: Callable[P, R]) -> Callable[P, R]:
     """
-    Method decorator that logs the function call with its arguments and the
-    return value.
+    Decorator to log function entry, arguments, and return value at DEBUG level.
+
+    Also adds an Allure step for reporting. Use on methods where tracing is useful
+    for debugging or reporting.
+
+    Example:
+        @traced
+        def my_method(self, x):
+            ...
 
     Args:
         func (Callable[P, R]): The function to be decorated.
@@ -117,7 +132,7 @@ def traced(func: Callable[P, R]) -> Callable[P, R]:
                 f"{", ".join([str(arg) for arg in args[1:]])} "
                 f"{LF.join(
                     f"{key}={str(value)}"
-                    for key, value in kwargs.items()) if kwargs else EMPTY}")
+                    for key, value in kwargs.items()) if kwargs else EMPTY_STRING}")
 
             with allure.step(  # type: ignore
                     f"{func.__name__} "

qa_testing_utils-0.0.8/src/qa_testing_utils/logging.ini

@@ -0,0 +1,35 @@
+; SPDX-FileCopyrightText: 2025 Adrian Herscu
+;
+; SPDX-License-Identifier: Apache-2.0
+
+[handlers]
+; NOTE: each key here must have a handler_xxx section below
+keys=console,overwrite_file
+
+[handler_console]
+class=StreamHandler
+level=DEBUG
+formatter=time_level_thread_name_message
+args=(sys.stdout,)
+
+[handler_overwrite_file]
+class=FileHandler
+level=DEBUG
+formatter=time_level_thread_name_message
+args=('pytest.log', 'w')
+
+[formatters]
+; NOTE: each key here must have a formatter_xxx section below
+keys=time_level_thread_name_message
+
+[formatter_time_level_thread_name_message]
+format=%(asctime)s [%(levelname)-1.1s] [%(threadName)-10.10s]: %(name)-14.14s - %(message)s
+; NOTE don't need milliseconds meanwhile, otherwise append .%03d below
+datefmt=%H:%M:%S
+
+[loggers]
+keys=root
+
+[logger_root]
+level=DEBUG
+handlers=console,overwrite_file

{qa_testing_utils-0.0.7 → qa_testing_utils-0.0.8}/src/qa_testing_utils/matchers.py

@@ -56,6 +56,15 @@ class ContainsStringIgnoringCase(BaseMatcher[str]):
 
 
 def contains_string_ignoring_case(substring: str) -> ContainsStringIgnoringCase:
+    """
+    Creates a matcher that checks if a given string contains the specified substring, ignoring case.
+
+    Args:
+        substring (str): The substring to search for within the target string, case-insensitively.
+
+    Returns:
+        ContainsStringIgnoringCase: A matcher object that evaluates whether the target string contains the specified substring, ignoring case.
+    """
     return ContainsStringIgnoringCase(substring)
 
 
@@ -70,12 +79,11 @@ class IsIteratorYielding[T](BaseMatcher[Iterator[T]]):
 
     @override
     def _matches(self, item: Iterable[T]) -> bool:
-        try:
-            for element in item:
-                if self.element_matcher.matches(element):
-                    return True
-        except TypeError:  # not an iterator
-            pass
+        for element in item:
+            if self.element_matcher.matches(element):
+                return True
+
+        # No matching element found
         return False
 
     @override
@@ -97,14 +105,12 @@ class IsStreamContainingEvery[T](BaseMatcher[Iterator[T]]):
 
     @override
     def _matches(self, item: Iterable[T]) -> bool:
-        try:
-            for element in item:
-                if not self.element_matcher.matches(element):
-                    return False  # One non-matching element means failure
-            return True  # All elements matched
-        except TypeError:  # not an iterator
-            pass
-        return False
+        for element in item:
+            if not self.element_matcher.matches(element):
+                return False  # One non-matching element means failure
+
+        # All elements matched
+        return True
 
     @override
     def describe_to(self, description: Description) -> None:
@@ -124,14 +130,12 @@ class IsIteratorYieldingAll[T](BaseMatcher[Iterator[T]]):
     @override
     def _matches(self, item: Iterable[T]) -> bool:
         unmatched_matchers = set(self.element_matchers)
-        try:
-            for element in item:
-                unmatched_matchers = {
-                    m for m in unmatched_matchers if not m.matches(element)}
-                if not unmatched_matchers:  # All matchers have been satisfied
-                    return True
-        except TypeError:  # not an iterator
-            pass
+        for element in item:
+            unmatched_matchers = {
+                m for m in unmatched_matchers if not m.matches(element)}
+            if not unmatched_matchers:  # All matchers have been satisfied
+                return True
+
         return False
 
     @override
@@ -154,38 +158,31 @@ class IsWithinDates(BaseMatcher[DateOrDateTime]):
         self.end_date = end_date
 
     def _matches(self, item: Optional[DateOrDateTime]) -> bool:
-        if not isinstance(item, (date, datetime)):
+        if item is None:
             return False
 
-        # Convert item to a consistent type for comparison
-        if isinstance(item, datetime):
-            item = item.date() if isinstance(
-                self.start_date, date) or isinstance(
-                self.end_date, date) else item
-        elif isinstance(item, date) and (isinstance(self.start_date, datetime) or isinstance(self.end_date, datetime)):
+        # Normalize item to datetime
+        if not isinstance(item, datetime):
             item = datetime.combine(item, datetime.min.time())
 
-        # Convert start_date and end_date to compatible types if they are not None
-        start = self.start_date
-        if start is not None:
-            start = start.date() if isinstance(
-                start, datetime) and isinstance(item, date) else start
+        # Normalize start_date and end_date to datetime
+        def to_datetime(value: Optional[DateOrDateTime]) -> Optional[datetime]:
+            if value is None:
+                return None
+            return value if isinstance(
+                value, datetime) else datetime.combine(
+                value, datetime.min.time())
 
-        end = self.end_date
-        if end is not None:
-            end = end.date() if isinstance(
-                end, datetime) and isinstance(
-                item, date) else end
+        start = to_datetime(self.start_date)
+        end = to_datetime(self.end_date)
 
-        # Perform the comparison, handling open-ended ranges
-        if start is None and end is not None:
-            return item <= end
-        elif start is not None and end is None:
-            return item >= start
-        elif start is not None and end is not None:
+        if start and end:
             return start <= item <= end
+        if start:
+            return item >= start
+        if end:
+            return item <= end
 
-        # If both start_date and end_date are None, return False (no valid range)
         return False
 
     def describe_to(self, description: Description) -> None:
@@ -201,6 +198,16 @@ class IsWithinDates(BaseMatcher[DateOrDateTime]):
 def within_dates(
         start_date: Optional[DateOrDateTime],
         end_date: Optional[DateOrDateTime]) -> IsWithinDates:
+    """
+    Creates an instance of IsWithinDates to check if a date or datetime value falls within the specified start and end dates.
+
+    Args:
+        start_date (Optional[DateOrDateTime]): The start of the date range. Can be None to indicate no lower bound.
+        end_date (Optional[DateOrDateTime]): The end of the date range. Can be None to indicate no upper bound.
+
+    Returns:
+        IsWithinDates: An instance configured with the provided start and end dates.
+    """
     return IsWithinDates(start_date, end_date)
 
 

{qa_testing_utils-0.0.7 → qa_testing_utils-0.0.8}/src/qa_testing_utils/object_utils.py

@@ -5,13 +5,11 @@
 import threading
 from dataclasses import asdict, fields, is_dataclass, replace
 from enum import Enum
-from typing import (Any, Callable, Dict, Protocol, Type, final)
-
-# TODO: move to stream_utils module
-type Supplier[T] = Callable[[], T]
-type Predicate[T] = Callable[[T], bool]
+from typing import (Any, Dict, Optional, Protocol,
+                    final, runtime_checkable, ClassVar)
 
 
+@runtime_checkable
 class Valid(Protocol):
     """
     Specifies a method for validating objects.
@@ -29,15 +27,20 @@ class Valid(Protocol):
 
 class ImmutableMixin:
     """
-    Enforces immutability by overriding __setattr__ to raise AttributeError.
+    Mixin to enforce immutability after initialization.
 
-    This implementation does not work with the WithMixin if the attributes are
-    initialized with default values.
+    Overrides __setattr__ to raise AttributeError if an attribute is modified after being set.
+    Intended for use with non-dataclasses. For dataclasses, use `@dataclass(frozen=True)`.
 
-    It also does not work when applied to a super type for which the __init__
-    is overridden.
+    Limitations:
+        - Does not work with WithMixin if attributes have default values.
+        - Does not work if applied to a superclass with a custom __init__.
 
-    Use it with non-dataclasses.
+    Example:
+        class MyImmutable(ImmutableMixin):
+            foo: int = 1
+        obj = MyImmutable()
+        obj.foo = 2  # Raises AttributeError
     """
 
     def __setattr__(self, key: str, value: Any) -> None:
@@ -49,19 +52,21 @@ class ImmutableMixin:
 
 class WithMixin:
     '''
-    Supports immutability by copying on change.
-
-    For example, instead of mutating like this::
+    Mixin to support copy-on-change (functional update) for objects.
 
-        obj.field = a_new_value
+    Instead of mutating an object, use `with_()` to create a copy with updated fields:
+        obj2 = obj.with_(field=new_value)
 
-    use::
+    Works with both plain Python classes and dataclasses.
 
-        dup_object_with_changes = obj.with_(field=a_new_value)
+    Example:
+        @dataclass(frozen=True)
+        class Point(WithMixin):
+            x: int
+            y: int
 
-    This will ensure that the changes are applied on a duplicate of `obj`.
-
-    Can be applied on plain Python classes, and on `dataclases` too.
+        p1 = Point(1, 2)
+        p2 = p1.with_(x=3)  # p2 is Point(3, 2)
     '''
     @final
     def with_[T:WithMixin](self: T, **changes: Any) -> T:
@@ -82,18 +87,37 @@ class WithMixin:
 
 
 class ToDictMixin:
+    """
+    Mixin to add serialization methods to dataclasses.
+
+    Provides:
+        - to_dict(): Recursively converts a dataclass (and nested dataclasses) to a dictionary.
+        - flatten(): Flattens nested structure for CSV or flat serialization.
+
+    Example:
+        @dataclass
+        class User(ToDictMixin):
+            name: str
+            age: int
+
+        user = User("Alice", 30)
+        user.to_dict()  # {'name': 'Alice', 'age': 30}
+    """
 
     def to_dict(self) -> Dict[str, Any]:
         """
         Converts a dataclass instance (with nested dataclasses) to a dictionary.
         """
-        def convert(value):
+        from typing import cast
+
+        def convert(value: Any) -> Any:
             if isinstance(value, ToDictMixin):
                 return value.to_dict()
             elif isinstance(value, list):
-                return [convert(v) for v in value]
+                # Provide a type hint for v
+                return [convert(v) for v in cast(list[Any], value)]
             elif isinstance(value, dict):
-                return {k: convert(v) for k, v in value.items()}
+                return {k: convert(v) for k, v in value.items()}  # type: ignore
             return value
 
         if not is_dataclass(self):
@@ -105,20 +129,20 @@ class ToDictMixin:
         """
         Flattens the nested structure into a flat dictionary for CSV serialization.
         """
-        flat_dict = {}
+        flat_dict: Dict[str, Any] = {}
 
-        def flatten_value(key: str, value: Any):
+        def flatten_value(key: str, value: Any) -> None:
             if isinstance(value, ToDictMixin):
                 # Flatten nested ToDictMixin dataclasses
                 nested_flat = value.flatten(prefix=f"{key}_")
                 flat_dict.update(nested_flat)
             elif isinstance(value, list):
                 # Serialize lists as JSON strings or expand into multiple columns
-                for idx, item in enumerate(value):
+                for idx, item in enumerate(value):  # type: ignore
                     flat_dict[f"{key}[{idx}]"] = item
             elif isinstance(value, dict):
                 # Serialize dicts as JSON strings or expand into multiple columns
-                for sub_key, sub_val in value.items():
+                for sub_key, sub_val in value.items():  # type: ignore
                     flat_dict[f"{key}_{sub_key}"] = sub_val
             else:
                 # Directly add non-nested fields
@@ -136,27 +160,41 @@ class ToDictMixin:
 
 class SingletonMeta(type):
     """
-    A thread-safe implementation of a Singleton metaclass.
+    Thread-safe singleton metaclass.
+
+    Ensures only one instance of a class exists per process.
+    Use by setting `metaclass=SingletonMeta` on your class.
     """
-    _instances: Dict[Type['SingletonBase'], 'SingletonBase'] = {}
-    _lock: threading.Lock = threading.Lock()  # Ensure thread-safety
+    _instances: ClassVar[Dict[type, object]] = {}
+    _lock: ClassVar[threading.Lock] = threading.Lock()  # Ensure thread-safety
 
-    def __call__(cls, *args: Any, **kwargs: Any) -> 'SingletonBase':
+    def __call__(
+            cls: type,
+            *args: Any, **kwargs: Any) -> "SingletonBase":
         with SingletonMeta._lock:
             if cls not in SingletonMeta._instances:
-                instance = super().__call__(*args, **kwargs)
+                instance = super().__call__(*args, **kwargs)  # type: ignore
                 SingletonMeta._instances[cls] = instance
-        return SingletonMeta._instances[cls]
+        return SingletonMeta._instances[cls]  # type: ignore[return-value]
 
 
 class SingletonBase(metaclass=SingletonMeta):
     """
     Base class for singletons using SingletonMeta.
+
+    Inherit from this class to make your class a singleton.
     """
     pass
 
 
 class InvalidValueException(ValueError):
+    """
+    Raised when an object fails validation via the Valid protocol.
+
+    Example:
+        if not obj.is_valid():
+            raise InvalidValueException(obj)
+    """
     pass
 
 
@@ -168,18 +206,33 @@ def valid[T:Valid](value: T) -> T:
         value (T:Valid): the object
 
     Raises:
-        TypeError: if the object does not support the Valid protocol
         InvalidValueException: if the object is invalid
 
     Returns:
         T:Valid: the validated object
     """
-    if not (hasattr(value, 'is_valid') and callable(
-            getattr(value, 'is_valid'))):
-        raise TypeError(
-            f"{value.__class__.__name__} does not conform to the Valid protocol")
-
     if value.is_valid():
         return value
-    else:
-        raise InvalidValueException(value)
+
+    raise InvalidValueException(value)
+
+
+def require_not_none[T](
+        value: Optional[T],
+        message: str = "Value must not be None") -> T:
+    """
+    Ensures that the provided value is not None.
+
+    Args:
+        value (Optional[T]): The value to check for None.
+        message (str, optional): The error message to use if value is None. Defaults to "Value must not be None".
+
+    Returns:
+        T: The value, guaranteed to be not None.
+
+    Raises:
+        ValueError: If value is None.
+    """
+    if value is None:
+        raise ValueError(message)
+    return value

qa_testing_utils-0.0.8/src/qa_testing_utils/stream_utils.py

@@ -0,0 +1,51 @@
+# SPDX-FileCopyrightText: 2025 Adrian Herscu
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Callable, Iterator
+
+
+"""
+A generic callable type alias representing a supplier of values of type T.
+
+A Supplier is a function that takes no arguments and returns a value of type T.
+This is useful for lazy evaluation, deferred computation, or providing values on demand.
+
+Example:
+    def random_int_supplier() -> int:
+        import random
+        return random.randint(1, 100)
+
+    supplier: Supplier[int] = random_int_supplier
+"""
+type Supplier[T] = Callable[[], T]
+
+"""
+A generic callable type alias representing a predicate (boolean-valued function) over values of type T.
+
+A Predicate is a function that takes a single argument of type T and returns a boolean.
+It is commonly used for filtering, validation, or conditional logic.
+
+Example:
+    def is_even(n: int) -> bool:
+        return n % 2 == 0
+
+    even_predicate: Predicate[int] = is_even
+"""
+type Predicate[T] = Callable[[T], bool]
+
+
+def process_next[T](i: Iterator[T], p: Predicate[T]) -> Iterator[T]:
+    """
+    Processes next items per specified predicate. Useful for cases in which
+    the first item in a stream decides the meaning of the rest of the items.
+
+    Args:
+        i (Iterator[T]): the iterator to process
+        p (Predicate[T]): the predicate to be applied on `next(i)`
+
+    Returns:
+        Iterator[T]: the original iterator if the predicate evaluated true, \
+            otherwise empty iterator
+    """
+    return i if p(next(i)) else iter([])

{qa_testing_utils-0.0.7 → qa_testing_utils-0.0.8}/src/qa_testing_utils/string_utils.py

@@ -6,12 +6,12 @@ from typing import Callable, Type
 
 from ppretty import ppretty  # type: ignore
 
-EMPTY = ""
+EMPTY_STRING = ""
 SPACE = " "
 DOT = "."
 LF = "\n"
 UTF_8 = "utf-8"
-EMPTY_BYTE_STRING = b''
+EMPTY_BYTES = b''
 
 
 def to_string[T](indent: str = '    ',

{qa_testing_utils-0.0.7 → qa_testing_utils-0.0.8}/src/qa_testing_utils/thread_utils.py

@@ -10,4 +10,9 @@ COMMON_EXECUTOR = concurrent.futures.ThreadPoolExecutor()
 
 
 def sleep_for(duration: timedelta):
+    """
+    Sleep for the specified duration.
+    Args:
+        duration (timedelta): The amount of time to sleep.
+    """
     time.sleep(duration.total_seconds())

qa_testing_utils-0.0.8/tests/exception_utils_tests.py

@@ -0,0 +1,34 @@
+# SPDX-FileCopyrightText: 2025 Adrian Herscu
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Any
+
+from qa_testing_utils.exception_utils import *
+
+
+def should_return_nothing_when_exception_is_raised():
+    def trouble(p: Any) -> str:
+        raise Exception("trouble")
+
+    assert safely(lambda: trouble(7)).value_or("nada") == "nada"
+
+
+def should_return_value_when_no_exception_occurs():
+    def ok() -> int:
+        return 42
+    assert safely(ok).value_or(-1) == 42
+
+
+def should_return_result_when_swallow_decorator_and_no_exception():
+    @swallow
+    def ok(x: int) -> int:
+        return x * 2
+    assert ok(3) == 6
+
+
+def should_return_none_when_swallow_decorator_and_exception():
+    @swallow
+    def fail() -> None:
+        raise RuntimeError("fail!")
+    assert fail() is None

qa_testing_utils-0.0.8/tests/file_utils_tests.py

@@ -0,0 +1,92 @@
+import csv
+from pathlib import Path
+from qa_testing_utils.file_utils import *
+
+
+def should_create_valid_csv(tmp_path: Path) -> None:
+    # Prepare test data
+    data: list[dict[str, object]] = [
+        {"a": 1, "b": "x"},
+        {"a": 2, "b": "y"},
+        {"a": 3, "b": "z"},
+    ]
+    csv_path = tmp_path / "test.csv"
+
+    # Call the function
+    write_csv(csv_path, data)
+
+    # Read back and check
+    with csv_path.open() as f:
+        reader = csv.DictReader(f)
+        rows = list(reader)
+    assert rows == [
+        {"a": "1", "b": "x"},
+        {"a": "2", "b": "y"},
+        {"a": "3", "b": "z"},
+    ]
+
+
+def should_write_empty_csv(tmp_path: Path) -> None:
+    csv_path = tmp_path / "empty.csv"
+    write_csv(csv_path, [])
+    assert not csv_path.exists() or csv_path.read_text() == ""
+
+
+def should_iterable_reader_reads_chunks():
+    data = [b'abc', b'def', b'ghi']
+    reader = IterableReader.from_(data)
+    assert reader.read() == b'abcdefghi'
+    reader.close()
+
+
+def should_stream_file_reads_file(tmp_path: Path):
+    file_path = tmp_path / "test.bin"
+    file_path.write_bytes(b"1234567890")
+    chunks = list(stream_file(file_path, chunk_size=4))
+    assert chunks == [b"1234", b"5678", b"90"]
+
+
+def should_read_lines_handles_split_lines():
+    chunks = [b"hello ", b"world\nthis is", b" a test\nend"]
+    lines = list(read_lines(chunks, encoding="utf-8", eol="\n"))
+    assert lines == ["hello world", "this is a test", "end"]
+
+
+def should_crc32_of_file(tmp_path: Path):
+    file_path = tmp_path / "crc.bin"
+    file_path.write_bytes(b"abc123")
+    with file_path.open("rb") as f:
+        crc = crc32_of(f)
+    import zlib
+    assert crc == zlib.crc32(b"abc123") & 0xFFFFFFFF
+
+
+def should_decompress_xz_stream():
+    import lzma
+    original = [b"hello world"]
+    compressed = [lzma.compress(original[0])]
+    decompressed = list(decompress_xz_stream(compressed))
+    assert b"".join(decompressed) == b"hello world"
+
+
+def should_extract_files_from_tar():
+    import tarfile
+    import io
+    # Create a tar archive in memory
+    file_content = b"testdata"
+    tar_bytes = io.BytesIO()
+    with tarfile.open(fileobj=tar_bytes, mode="w") as tar:
+        info = tarfile.TarInfo(name="file.txt")
+        info.size = len(file_content)
+        tar.addfile(info, io.BytesIO(file_content))
+    tar_bytes.seek(0)
+    # Split tar_bytes into chunks to simulate streaming
+    tar_chunks = list(iter(lambda: tar_bytes.read(4), b""))
+    # Extract files from tar stream
+    files = list(extract_files_from_tar(tar_chunks))
+    assert len(files) == 1
+    tarinfo, data = files[0]
+    assert tarinfo.name == "file.txt"
+    assert data == file_content
+
+# TODO: decompress_xz_stream and extract_files_from_tar require binary test data.

{qa_testing_utils-0.0.7 → qa_testing_utils-0.0.8}/tests/logger_tests.py

@@ -46,3 +46,49 @@ def should_preserve_signature():
 
     print(my_func.__name__)  # Prints: my_func
     print(my_func.__doc__)  # Prints: my documentation
+
+
+def should_return_value_and_log_with_trace():
+    value = trace(123)
+    assert value == 123
+
+
+def should_inject_logger_with_logger_decorator():
+    @logger
+    class Foo:
+        pass
+    f = Foo()
+    # The logger is injected as a property, so we access it via the property
+    log = getattr(f, 'log', None)
+    assert log is not None
+    assert isinstance(log, logging.Logger)
+    assert log.name == 'Foo'
+
+
+def should_provide_log_property_with_logger_mixin():
+    class Bar(LoggerMixin):
+        pass
+    b = Bar()
+    assert hasattr(b, 'log')
+    assert isinstance(b.log, logging.Logger)
+    assert b.log.name == 'Bar'
+
+
+def should_return_value_and_log_with_logger_mixin_trace():
+    class Baz(LoggerMixin):
+        pass
+    b = Baz()
+    value = b.trace('abc')
+    assert value == 'abc'
+
+
+def should_log_entry_and_exit_with_traced_decorator():
+    calls: list[tuple[int, int]] = []
+
+    @traced
+    def foo(x: int, y: int) -> int:
+        calls.append((x, y))
+        return x + y
+    result: int = foo(2, 3)
+    assert result == 5
+    assert calls == [(2, 3)]

{qa_testing_utils-0.0.7 → qa_testing_utils-0.0.8}/tests/matchers_tests.py

@@ -3,7 +3,7 @@
 # SPDX-License-Identifier: Apache-2.0
 
 from datetime import datetime
-from typing import Callable
+from typing import Callable, Union
 
 import attr
 import pytest
@@ -118,7 +118,8 @@ def should_adapt_stream():
     ]
 )
 def should_match_within_dates(
-        test_date: datetime, start_date: Union[datetime, None],
+        test_date: datetime,
+        start_date: Union[datetime, None],
         end_date: Union[datetime, None]):
     assert_that(test_date, within_dates(start_date, end_date))
 
@@ -126,12 +127,46 @@ def should_match_within_dates(
 @pytest.mark.parametrize(
     "test_date, start_date, end_date",
     [
+        (None, datetime(2023, 1, 1), datetime(2023, 12, 31)),
         (datetime(2022, 12, 31), datetime(2023, 1, 1), datetime(2023, 12, 31)),
         (datetime(2024, 1, 1), datetime(2023, 1, 1), datetime(2023, 12, 31)),
     ]
 )
 def should_fail_not_within_dates(
-        test_date: datetime, start_date: Union[datetime, None],
+        test_date: datetime,
+        start_date: Union[datetime, None],
         end_date: Union[datetime, None]):
     with pytest.raises(AssertionError):
         assert_that(test_date, within_dates(start_date, end_date))
+
+
+def should_match_contains_string_ignoring_case():
+    assert_that("Hello World", contains_string_ignoring_case("hello"))
+    assert_that("Hello World", contains_string_ignoring_case("WORLD"))
+    # Should fail if not present
+    with pytest.raises(AssertionError):
+        assert_that("Hello World", contains_string_ignoring_case("bye"))
+
+
+def should_match_iterator_yielding():
+    # Should match if any element matches
+    assert_that(iter([1, 2, 3]), yields_item(2))
+    # Should fail if none match
+    with pytest.raises(AssertionError):
+        assert_that(iter([1, 2, 3]), yields_item(5))
+
+
+def should_match_stream_containing_every():
+    # Should match if all elements match
+    assert_that(iter([2, 2, 2]), yields_every(2))
+    # Should fail if any element does not match
+    with pytest.raises(AssertionError):
+        assert_that(iter([2, 2, 3]), yields_every(2))
+
+
+def should_match_iterator_yielding_all():
+    # Should match if all specified items are yielded at least once
+    assert_that(iter([1, 2, 3]), yields_items([1, 2]))
+    # Should fail if any specified item is not yielded
+    with pytest.raises(AssertionError):
+        assert_that(iter([1, 2, 3]), yields_items([1, 4]))

{qa_testing_utils-0.0.7 → qa_testing_utils-0.0.8}/tests/object_utils_tests.py

@@ -111,3 +111,42 @@ def should_be_singleton():
 
     assert BarSingleton(1) == BarSingleton(2)
     assert BarSingleton(3).i == 1  # type: ignore
+
+
+def should_convert_to_dict_and_flatten():
+    from dataclasses import dataclass
+
+    @dataclass
+    class Address(ToDictMixin):
+        city: str
+        zip: int
+
+    @dataclass
+    class User(ToDictMixin):
+        name: str
+        age: int
+        address: Address
+        tags: list[str]
+        meta: dict[str, int]
+    user = User(
+        "Alice", 30, Address("London", 12345),
+        ["a", "b"],
+        {"score": 10})
+    # to_dict
+    d = user.to_dict()
+    assert d == {
+        "name": "Alice",
+        "age": 30,
+        "address": {"city": "London", "zip": 12345},
+        "tags": ["a", "b"],
+        "meta": {"score": 10}
+    }
+    # flatten
+    flat = user.flatten()
+    assert flat["name"] == "Alice"
+    assert flat["age"] == 30
+    assert flat["address_city"] == "London"
+    assert flat["address_zip"] == 12345
+    assert flat["tags[0]"] == "a"
+    assert flat["tags[1]"] == "b"
+    assert flat["meta_score"] == 10

{qa_testing_utils-0.0.7 → qa_testing_utils-0.0.8}/tests/self_tests.py

@@ -25,10 +25,12 @@ class SelfTests(LoggerMixin):
         self.log.debug(f"after {method}")
 
     def should_print(self):
+        """Test that print statement works (placeholder/self-test)."""
         print("hello")
 
     @traced
     def should_assert_true(self):
+        """Test that a traced assertion passes (decorator coverage)."""
         assert True
 
     # @pytest.mark.skip
@@ -65,6 +67,7 @@ class SelfTests(LoggerMixin):
                     is_("Foo(id=1, mandatory='present', name='kuku')"))
 
     def should_retry(self):
+        """Test retry logic for a function that may fail multiple times."""
         retry_policy = retry(
             stop=stop_after_attempt(1000),
             wait=wait_fixed(timedelta(milliseconds=1)),

{qa_testing_utils-0.0.7 → qa_testing_utils-0.0.8}/tests/stream_utils_tests.py

@@ -2,17 +2,19 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+# NOTE: there is another streaming library named pystreamapi.
+# In contrast with pyfunctional it is type annotated.
+# However, it eagerly consumes its underlying stream, defeating its purpose...
+# ISSUE see https://github.com/PickwickSoft/pystreamapi/issues/94
+# hence, we'll ignore type warnings:
+# type: ignore
+
 from typing import Iterator
 
 from functional import seq
 from more_itertools import peekable
 from qa_testing_utils.stream_utils import *
 
-# NOTE: there is another streaming library named pystreamapi.
-# In contrast with pyfunctional it is type annotated.
-# However, it eagerly consumes its underlying stream, defeating its purpose...
-# ISSUE see https://github.com/PickwickSoft/pystreamapi/issues/94
-
 
 def gen() -> Iterator[int]:
     yield -1

qa_testing_utils-0.0.8/tests/thread_utils_tests.py

@@ -0,0 +1,16 @@
+# SPDX-FileCopyrightText: 2025 Adrian Herscu
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from datetime import timedelta
+from qa_testing_utils.thread_utils import sleep_for
+import time
+
+
+def should_sleep_for_specified_duration():
+    start = time.monotonic()
+    sleep_for(timedelta(milliseconds=120))
+    elapsed = time.monotonic() - start
+    # Allow some tolerance for timing imprecision
+    assert elapsed >= 0.11
+    assert elapsed < 0.5

qa_testing_utils-0.0.8/tests/tuple_utils_tests.py

@@ -0,0 +1,44 @@
+# SPDX-FileCopyrightText: 2025 Adrian Herscu
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import attr
+from hamcrest import assert_that, is_  # type: ignore
+from qa_testing_utils.tuple_utils import *
+
+
+def should_assert_from_tuple():
+    @attr.define
+    class Foo(FromTupleMixin):
+        id: int
+        name: str
+
+    assert_that(str(Foo.from_tuple((1, "kuku"))),
+                is_("Foo(id=1, name='kuku')"))
+
+
+def should_assert_from_tuple_with_frozen_dataclass():
+    import dataclasses
+
+    @dataclasses.dataclass(frozen=True)
+    class Bar(FromTupleMixin):
+        x: int
+        y: str
+    bar = Bar.from_tuple((42, "baz"))
+    assert bar.x == 42
+    assert bar.y == "baz"
+    assert isinstance(bar, Bar)
+
+
+def should_assert_from_tuple_with_vanilla_class():
+    class Baz(FromTupleMixin):
+        a: int
+        b: str
+
+        def __init__(self, a: int, b: str):
+            self.a = a
+            self.b = b
+    baz = Baz.from_tuple((7, "qux"))
+    assert baz.a == 7
+    assert baz.b == "qux"
+    assert isinstance(baz, Baz)

qa_testing_utils-0.0.7/src/qa_testing_utils/__init__.py

@@ -1 +0,0 @@
-__version__ = '0.0.7'

qa_testing_utils-0.0.7/src/qa_testing_utils/stream_utils.py

@@ -1,24 +0,0 @@
-# SPDX-FileCopyrightText: 2025 Adrian Herscu
-#
-# SPDX-License-Identifier: Apache-2.0
-
-from typing import Iterator
-
-from qa_testing_utils.object_utils import Predicate
-
-
-def process_next[T](i: Iterator[T], p: Predicate[T]) -> Iterator[T]:
-    # DELETEME -- not needed so far
-    """
-    Processes next items per specified predicate. Useful, for cases in which
-    first item in a stream decides the meaning of rest of items.
-
-    Args:
-        i (Iterator[T]): the iterator to process
-        p (Predicate[T]): the predicate to be applied on `next(i)`
-
-    Returns:
-        Iterator[T]: the original iterator if the predicate evaluated true, \
-            otherwise empty iterator
-    """
-    return i if p(next(i)) else iter([])

qa_testing_utils-0.0.7/tests/exception_utils_tests.py

@@ -1,14 +0,0 @@
-# SPDX-FileCopyrightText: 2025 Adrian Herscu
-#
-# SPDX-License-Identifier: Apache-2.0
-
-from typing import Any
-
-from qa_testing_utils.exception_utils import *
-
-
-def should_swallow_exception():
-    def trouble(p: Any) -> str:
-        raise Exception("trouble")
-
-    assert safely(lambda: trouble(7)).value_or("nada") == "nada"

qa_testing_utils-0.0.7/tests/tuple_utils_tests.py

@@ -1,17 +0,0 @@
-# SPDX-FileCopyrightText: 2025 Adrian Herscu
-#
-# SPDX-License-Identifier: Apache-2.0
-
-import attr
-from hamcrest import assert_that, is_  # type: ignore
-from qa_testing_utils.tuple_utils import *
-
-
-def should_assert_from_tuple():
-    @attr.define
-    class Foo(FromTupleMixin):
-        id: int
-        name: str
-
-    assert_that(str(Foo.from_tuple((1, "kuku"))),
-                is_("Foo(id=1, name='kuku')"))