qa-testing-utils 0.1.0__tar.gz

qa_testing_utils-0.1.0/.gitignore

@@ -0,0 +1,89 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Hatch & Python environments
+.hatch/
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# VSCode settings (optional: keep .vscode/settings.json)
+.vscode/*
+!.vscode/settings.json
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+*.egg
+MANIFEST
+
+# PyInstaller
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+.pytest_cache/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+htmlcov/
+
+# Mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre / Pytype
+.pyre/
+.pytype/
+
+# Ruff
+.ruff_cache/
+
+# Debugging & development
+*.log
+
+# Notebook / IPython
+.ipynb_checkpoints
+profile_default/
+ipython_config.py
+
+# JupyterLite / Sphinx / docs
+docs/_build/
+site/
+
+# Cython
+cython_debug/
+
+# Other tools & IDEs
+.ropeproject
+.spyderproject
+.spyproject
+
+# JetBrains / PyCharm (optional - uncomment to ignore everything)
+#.idea/
+
+# Miscellaneous
+*.pypirc
+UNKNOWN.egg-info/

qa_testing_utils-0.1.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: qa-testing-utils
+Version: 0.1.0
+Summary: Testing utilities library for QA automation
+Author-email: Adrian Herscu <adrian.herscu@gmail.com>
+Requires-Python: >=3.13
+Requires-Dist: allure-pytest
+Requires-Dist: more-itertools
+Requires-Dist: ppretty
+Requires-Dist: pyfunctional
+Requires-Dist: pyhamcrest
+Requires-Dist: returns
+Description-Content-Type: text/markdown
+
+# qa-testing-utils

qa_testing_utils-0.1.0/README.md

@@ -0,0 +1 @@
+# qa-testing-utils

qa_testing_utils-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "qa-testing-utils"
+version = "0.1.0"
+description = "Testing utilities library for QA automation"
+authors = [{ name = "Adrian Herscu", email = "adrian.herscu@gmail.com" }]
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+  "PyHamcrest",
+  "pyfunctional",
+  "ppretty",
+  "allure-pytest",
+  "more-itertools",
+  "returns"
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/qa/testing/utils"]
+
+[tool.hatch.envs.default]
+path = ".hatch/envs/default"
+dependencies = [
+  "pytest",
+  "pytest-cov",
+  "mypy",
+  "isort",
+  "autopep8"
+]
+
+[tool.hatch.envs.default.scripts]
+test = "pytest"
+lint = "mypy src"
+format = "autopep8 --in-place --recursive src"

qa_testing_utils-0.1.0/src/qa/testing/utils/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2025 Adrian Herscu
+#
+# SPDX-License-Identifier: Apache-2.0

qa_testing_utils-0.1.0/src/qa/testing/utils/exception_utils.py

@@ -0,0 +1,50 @@
+# SPDX-FileCopyrightText: 2025 Adrian Herscu
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import functools
+import logging
+from typing import Any, Callable
+
+from returns.maybe import Maybe, Nothing, Some
+from qa.testing.utils.object_utils import Supplier
+
+
+def safely[T](supplier: Supplier[T]) -> Maybe[T]:
+    """
+    Calls a function safely, wrapping its result in Maybe, and swallowing any exceptions.
+    The function should be a no-argument callable::
+
+        safely(lambda: call_something_that_may_fail(params))
+
+    Args:
+        supplier (Supplier[T]): The supplier to be called.
+
+    Returns:
+        Maybe[T]: The result wrapped in Maybe, or Nothing if an exception occurs.
+    """
+    try:
+        result = supplier()
+        return Some(result)
+    except Exception as e:
+        logging.exception(f"Exception occurred: {e}")
+        return Nothing
+
+
+def swallow(func: Callable[..., Any]) -> Callable[..., Any]:
+    """
+    Decorates a function to swallow any exceptions.
+
+    If an exception will occur, None will be returned.
+
+    Args:
+        func (Callable): the function, supplied by the run-time
+
+    Returns:
+        Callable: the decorated function
+    """
+    @functools.wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        return safely(lambda: func(*args, **kwargs)).value_or(None)
+
+    return wrapper

qa_testing_utils-0.1.0/src/qa/testing/utils/exceptions.py

@@ -0,0 +1,12 @@
+# SPDX-FileCopyrightText: 2025 Adrian Herscu
+#
+# SPDX-License-Identifier: Apache-2.0
+
+class TestException(Exception):
+    """
+    Marks an exception raised by tests infrastructure. Useful to differentiate
+    between unexpected run-time exceptions, which should be handled as
+    programming errors, and legitimate run-time exceptions such as time-out,
+    not found, etc. The former might be handled via a retry mechanism.
+    """
+    pass

qa_testing_utils-0.1.0/src/qa/testing/utils/file_utils.py

@@ -0,0 +1,196 @@
+# SPDX-FileCopyrightText: 2025 Adrian Herscu
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import csv
+from io import DEFAULT_BUFFER_SIZE, BufferedReader, RawIOBase
+from lzma import LZMADecompressor
+from pathlib import Path
+from tarfile import TarInfo, open
+from typing import BinaryIO, Iterable, Iterator, Tuple, final, override
+from zlib import crc32
+
+from more_itertools import peekable
+from qa.testing.utils.logger import *
+from qa.testing.utils.object_utils import *
+from qa.testing.utils.string_utils import *
+
+LAUNCHING_DIR = Path.cwd()
+
+
+@final
+class IterableReader(RawIOBase, LoggerMixin, ImmutableMixin):
+    """
+    I/O read-only stream over iterable of bytes, enabling streaming mode.
+    """
+
+    def __init__(self, chunks: Iterable[bytes]):
+        self._chunks = iter(chunks)
+        self._accumulated_buffer = bytearray()
+
+    @override
+    def readable(self) -> bool:
+        return True
+
+    @override
+    def readinto(self, output_buffer: memoryview) -> int:  # type: ignore
+        # consume chunks, accumulating their bytes up to size of output buffer
+        while len(self._accumulated_buffer) < len(output_buffer) \
+                and (chunk := next(self._chunks, None)) is not None:
+            self.log.debug(f"buffered chunk with length={len(chunk)}")
+            self._accumulated_buffer.extend(chunk)
+
+        # consume accumulated bytes up to size of output buffer
+        consumed_bytes = min(len(self._accumulated_buffer), len(output_buffer))
+        output_buffer[:consumed_bytes] = self._accumulated_buffer[:consumed_bytes]
+
+        # delete consumed bytes, shifting left the accumulated buffer
+        del self._accumulated_buffer[:consumed_bytes]
+
+        self.log.debug(f"consumed {consumed_bytes} bytes")
+        return consumed_bytes
+
+    @staticmethod
+    def from_(
+            chunks: Iterable[bytes],
+            buffer_size: int = DEFAULT_BUFFER_SIZE) -> BinaryIO:
+        """
+        Converts a stream of binary chunks into a BufferedReader.
+
+        You should ensure closing.
+
+        Args:
+            chunks (Iterable[bytes]): stream of binary chunks
+
+        Returns:
+            io.BufferedReader: buffered reader around stream of binary chunks.
+        """
+        return BufferedReader(IterableReader(chunks), buffer_size)
+
+
+# TODO perhaps there should be a writable stream to iterator utility too...
+
+
+def stream_file(
+        file_path: Path,
+        chunk_size: int = DEFAULT_BUFFER_SIZE) -> Iterator[bytes]:
+    """
+    Streams a binary file from disk into an iterator.
+
+    If the iterator is not consumed, the file will be closed when the iterator
+    will be garbage collected.
+
+    Args:
+        file_path (Path): path to file
+        chunk_size (int, optional): the chunk size. Defaults to 8192.
+
+    Yields:
+        Iterator[bytes]: the binary chunks stream
+    """
+    with file_path.open('rb') as f:
+        yield from iter(lambda: f.read(chunk_size), EMPTY_BYTE_STRING)
+
+
+def read_lines(
+        byte_stream: Iterable[bytes],
+        encoding: str = UTF_8,
+        eol: str = LF) -> Iterator[str]:
+    """
+    Converts a stream of binary chunks into stream of text lines.
+    Handles cases where lines are split across chunks.
+
+    Args:
+        byte_stream (Iterable[bytes]): the binary (chunks) stream
+        encoding (str, optional): expected text encoding. Defaults to 'utf-8'.
+        eol (str, optional): expected line-ending. Default to LF.
+
+    Yields:
+        Iterator[str]: stream of text lines, not terminated by EOL marker
+    """
+    has_content = False
+    buffer = bytearray()
+    eol_bytes = eol.encode(encoding)
+
+    for chunk in byte_stream:
+        print(DOT, end=SPACE)
+        has_content = True
+        buffer.extend(chunk)
+        *lines, buffer = buffer.split(eol_bytes)  # keep partial line in buffer
+        trace(f"streaming {len(lines)} lines; leftover {len(buffer)} chars")
+        yield from (line.decode(encoding) for line in lines)
+
+    if buffer:  # yield the leftover
+        yield buffer.decode(encoding)
+
+    if not has_content:
+        trace("no lines")
+
+
+def decompress_xz_stream(compressed_chunks: Iterable[bytes]) -> Iterator[bytes]:
+    """
+    Decompresses XZ stream.
+
+    Args:
+        compressed_chunks (Iterable[bytes]): stream of binary compressed chunks
+
+    Yields:
+        Iterator[bytes]: the decompressed stream
+    """
+    decompressor = LZMADecompressor()
+    return map(decompressor.decompress, compressed_chunks)
+
+
+def extract_files_from_tar(tar_chunks: Iterable[bytes]) -> Iterator[Tuple[TarInfo, bytes]]:
+    """
+    Extracts files from decompressed TAR stream.
+
+    Args:
+        tar_chunks (Iterable[bytes]): stream of decompressed TAR chunks
+
+    Yields:
+        Iterator[Tuple[tarfile.TarInfo, bytes]]: \
+            streams tuples of meta-data and data for each file
+    """
+    with open(fileobj=IterableReader.from_(tar_chunks),
+              mode='r|*') as tar:
+        for member in tar:
+            if member.isfile():
+                extracted_file = tar.extractfile(member)
+                if extracted_file:
+                    yield member, extracted_file.read()
+
+
+def crc32_of(file: BinaryIO, chunk_size: int = DEFAULT_BUFFER_SIZE) -> int:
+    """
+    Calculate the CRC of a binary stream from its current position to its tail,
+    using chunked reading.
+
+    Args:
+        file (BinaryIO): The file object to read data from, starting from its current position.
+        chunk_size (int): The size of chunks to read at a time (default is 8192).
+
+    Returns:
+        int: Calculated CRC value of the remaining file content.
+    """
+    crc_value = 0
+
+    while chunk := file.read(chunk_size):
+        crc_value = crc32(chunk, crc_value)
+
+    return crc_value & 0xFFFFFFFF  # ensure 32-bit unsigned
+
+
+def write_csv(file_path: Path, data_stream: Iterable[dict]):
+    """
+    Writes a stream of flattened telemetry packets to a CSV file.
+
+    Args:
+        file_path: Path to the CSV file to be written.
+        data_stream: Iterable of dictionaries representing the rows to be written.
+    """
+    stream = peekable(data_stream)  # Allow peeking to extract headers
+    with file_path.open(mode="w", newline="") as csv_file:
+        writer = csv.DictWriter(
+            csv_file, fieldnames=list(stream.peek().keys()))
+        writer.writeheader()
+        writer.writerows(stream)

qa_testing_utils-0.1.0/src/qa/testing/utils/logger.py

@@ -0,0 +1,140 @@
+# SPDX-FileCopyrightText: 2025 Adrian Herscu
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import inspect
+import logging
+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
+
+
+def trace[T](value: T) -> T:
+    """Logs at debug level using the invoking module name as the logger."""
+    frame = inspect.currentframe()
+    try:
+        if frame is not None:
+            caller_frame = frame.f_back
+            if caller_frame is not None:
+                caller_module = inspect.getmodule(caller_frame)
+                logger_name = caller_module.__name__ if caller_module else '__main__'
+                logger = logging.getLogger(logger_name)
+                logger.debug(f"=== {value}")
+            else:
+                logging.getLogger(__name__).debug(f"=== {value}")
+        else:
+            logging.getLogger(__name__).debug(f"=== {value}")
+    finally:
+        del frame
+
+    return value
+
+
+def logger[T:type](cls: T) -> T:
+    """
+    Class decorator that injects a logger into annotated class.
+
+    Args:
+        cls (type): automatically provided by the runtime
+
+    Returns:
+        _type_: the decorated class
+    """
+    cls._logger = logging.getLogger(cls.__name__)
+
+    @property
+    def log(self: T) -> logging.Logger:
+        return cast(logging.Logger, getattr(self, '_logger', None))
+
+    cls.log = log
+
+    return cls
+
+
+class LoggerMixin:
+    """
+    Yet another way of adding logging by deriving from this one.
+    """
+    @final
+    @cached_property
+    def log(self) -> logging.Logger:
+        return logging.getLogger(self.__class__.__name__)
+
+    @final
+    def trace[T](self, value: T) -> T:
+        """
+        Logs value at DEBUG level using this logger.
+
+        Use to log something as a value, usually in a lambda expression::
+
+            then.eventually_assert_that(
+                lambda: self.trace(...call some API...),
+                greater_that(0)) \
+
+                .and_....other verifications may follow...
+
+        Args:
+            value (T): the value
+
+        Returns:
+            T: the value
+        """
+        self.log.debug(f"=== {value}")
+        return value
+
+
+P = ParamSpec('P')
+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.
+
+    Args:
+        func (Callable[P, R]): The function to be decorated.
+        *args (Any): Positional arguments to be passed to the function.
+        **kwargs (Any): Keyword arguments to be passed to the function.
+
+    Returns:
+        Callable[P, R]: The result of the function call.
+    """
+    @wraps(func)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        # NOTE: each time a decorated function is called this logic will be
+        # re-evaluated.
+        signature = inspect.signature(func)
+        parameters = list(signature.parameters.keys())
+
+        if parameters and parameters[0] == 'self' and len(args) > 0:
+            instance = args[0]
+            logger = logging.getLogger(f"{instance.__class__.__name__}")
+            logger.debug(
+                f">>> {func.__name__} "
+                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}")
+
+            with allure.step(  # type: ignore
+                    f"{func.__name__} "
+                    f"{', '.join([str(arg) for arg in args[1:]])}"):
+                result = func(*args, **kwargs)
+
+            if result == instance:
+                logger.debug(f"<<< {func.__name__}")
+            else:
+                logger.debug(f"<<< {func.__name__} {result}")
+
+            return result
+        else:
+            logger = logging.getLogger(func.__name__)
+            logger.debug(f">>> {func.__name__} {args} {kwargs}")
+            result = func(*args, **kwargs)
+            logger.debug(f"<<< {func.__name__} {result}")
+            return result
+
+    return wrapper