pi-usereq 0.49.0 → 0.51.0

package/tests/fixtures/fixture_python.py

@@ -1,502 +0,0 @@
-#!/usr/bin/env python3
-"""!
-@file fixture_python.py
-@brief Comprehensive Python test fixture for parser validation.
-@details Covers classes, protocols, decorators, generators, async functions, and rich Doxygen-tagged constructs used to validate extraction workflows and deterministic parser behavior.
-"""
-import asyncio  #!< @brief Async IO support. @details Used for async test fixtures. # noqa: F401
-import os  #!< @brief OS interface module. @details Provides OS-dependent functionality. # noqa: F401
-import sys  #!< @brief System-specific parameters. @see sys.exit() for exit handling.
-from pathlib import Path  #!< @brief Object-oriented filesystem paths. @note Preferred over os.path. # noqa: F401
-from typing import (
-    Optional, List, Dict, Union, Protocol,
-    TypeVar, Generic, Iterator, AsyncIterator
-)
-from dataclasses import dataclass, field
-from abc import ABC, abstractmethod
-from contextlib import contextmanager
-
-MAX_RETRIES = 3  #!< @brief Maximum retry attempts. @details Applied to network operations. @warning Tune per use case. @satisfies retry-policy
-DEFAULT_TIMEOUT = 30.0  #!< @brief Default timeout in seconds. @note For I/O operations.
-_INTERNAL_CACHE: Dict[str, int] = {}  #!< @brief Internal cache dict. @deprecated Use lru_cache instead.
-
-T = TypeVar("T")
-
-
-@dataclass(slots=True)
-class Config:
-    """Configuration data holder for the application.
-
-    @brief Stores key-value pairs with optional default fallback.
-    @details Dataclass-based configuration with validation.
-    @note Immutable after creation when frozen=True is used.
-    @see __post_init__() for validation logic.
-    """
-    name: str
-    values: Dict[str, str] = field(default_factory=dict)
-    debug: bool = False
-
-    def get(self, key: str, default: str = "") -> str:
-        """Retrieve a configuration value by key.
-
-        @param key The configuration key to look up.
-        @param default Fallback value if key is missing.
-        @return The configuration value or default.
-        """
-        # Check primary values first
-        if key in self.values:
-            return self.values[key]
-        # Fallback to default
-        return default
-
-    def __post_init__(self) -> None:
-        """Validate configuration after initialization.
-
-        @brief Ensures name is non-empty and normalizes values.
-        @raises ValueError If name is empty or whitespace.
-        """
-        if not self.name.strip():
-            raise ValueError("Config name cannot be empty")
-
-
-class MyClass:
-    """Class docstring for MyClass.
-
-    @brief Base class demonstrating various Python constructs.
-    @details Includes nested classes, properties, and static methods.
-    """
-
-    class InnerHelper:
-        """Nested helper class for internal data grouping.
-
-        @brief Handles auxiliary computations within MyClass scope.
-        """
-        def __init__(self, tag: str):
-            """Initialize the helper with a tag identifier.
-
-            @param tag Short label for categorization.
-            """
-            self.tag = tag
-
-        def describe(self) -> str:
-            """Return a formatted description of this helper.
-
-            @return String combining class name and tag.
-            """
-            return f"Helper({self.tag})"
-
-    def __init__(self, name: str, retries: int = MAX_RETRIES):
-        """Initialize MyClass with a name and retry count.
-
-        @param name Identifier for this instance.
-        @param retries Maximum retry attempts; defaults to MAX_RETRIES.
-        """
-        self._name = name
-        self._retries = retries
-        # Internal counter tracks invocation count
-        self._call_count = 0
-
-    @property
-    def name(self) -> str:
-        """Read-only property exposing the instance name.
-
-        @return The name string set during initialization.
-        """
-        return self._name
-
-    @name.setter
-    def name(self, value: str) -> None:
-        """Set the instance name after validation.
-
-        @param value New name; must be non-empty.
-        @raises ValueError If value is empty.
-        """
-        if not value:
-            raise ValueError("Name cannot be empty")
-        self._name = value
-
-    @staticmethod
-    def create_default() -> "MyClass":
-        """Factory method to build a MyClass with default settings.
-
-        @return A new MyClass instance with name='default'.
-        """
-        return MyClass("default")
-
-    @classmethod
-    def from_dict(cls, data: dict) -> "MyClass":
-        """Construct a MyClass from a dictionary payload.
-
-        @param data Dictionary with 'name' and optional 'retries' keys.
-        @return A new instance populated from data.
-        @raises KeyError If 'name' key is missing.
-        """
-        return cls(
-            name=data["name"],
-            retries=data.get("retries", MAX_RETRIES),
-        )
-
-    def process(self, items: List[str], *, verbose: bool = False) -> Optional[str]:
-        """Process a list of string items with optional logging.
-
-        @param items List of strings to process sequentially.
-        @param verbose Enable detailed logging when True.
-        @return The first valid item found or None if all are empty.
-        """
-        self._call_count += 1
-        for item in items:
-            # Skip empty entries
-            if not item.strip():
-                continue
-            if verbose:
-                print(f"Processing: {item}")
-            # Conditional return on first valid item
-            return item if len(item) > 1 else item.upper()
-        return None
-
-    def compute(self, x: int, y: int) -> int:
-        """Compute a value using conditional assignment on return.
-
-        @param x First operand.
-        @param y Second operand.
-        @return Sum if both positive, difference otherwise.
-        """
-        # Ternary return with compound condition
-        return (x + y) if (x > 0 and y > 0) else abs(x - y)
-
-
-class AbstractProcessor(ABC):
-    """Abstract base class for all data processors.
-
-    @brief Defines the interface that concrete processors must implement.
-    @details ABC-based interface with abstract methods.
-    @note Subclasses must implement execute() and execute_async().
-    @see ConcreteProcessor for a working implementation.
-    @sa ABC documentation for abstract base class patterns.
-    """
-
-    @abstractmethod
-    def execute(self, data: bytes) -> bool:
-        """Execute processing on raw byte data.
-
-        @param data The raw input bytes to process.
-        @return True if processing succeeded, False otherwise.
-        """
-        ...
-
-    @abstractmethod
-    async def execute_async(self, data: bytes) -> bool:
-        """Asynchronous variant of execute.
-
-        @param data The raw input bytes to process.
-        @return True if processing succeeded.
-        """
-        ...
-
-
-class ConcreteProcessor(AbstractProcessor):
-    """Concrete implementation of AbstractProcessor.
-
-    @brief Processes byte data by decoding and validating content.
-    @details Implements synchronous and async execute methods.
-    @note Thread-safe for read operations.
-    @see AbstractProcessor for interface definition.
-    """
-
-    def execute(self, data: bytes) -> bool:
-        """Decode and validate byte data synchronously.
-
-        @param data Raw bytes, expected UTF-8 encoded text.
-        @return True if decoding and validation succeed.
-        @raises UnicodeDecodeError Propagated if data is not valid UTF-8.
-        """
-        try:
-            text = data.decode("utf-8")
-            # Validate non-empty after decode
-            return bool(text.strip())
-        except UnicodeDecodeError:
-            return False
-        finally:
-            # Ensure cleanup regardless of outcome
-            pass
-
-    async def execute_async(self, data: bytes) -> bool:
-        """Async decode and validate byte data.
-
-        @param data Raw bytes to process asynchronously.
-        @return True if valid content found.
-        """
-        return self.execute(data)
-
-
-class GenericContainer(Generic[T]):
-    """Generic container holding items of type T.
-
-    @brief Type-safe collection with iteration and lookup support.
-    @details Generic collection with find and iteration.
-    @tparam T The element type stored in this container.
-    @note Implements __iter__ for iteration protocol.
-    @see typing.Generic for generics documentation.
-    """
-
-    def __init__(self) -> None:
-        """Initialize an empty container."""
-        self._items: List[T] = []
-
-    def add(self, item: T) -> None:
-        """Append an item to the container.
-
-        @param item Element of type T to add.
-        """
-        self._items.append(item)
-
-    def __iter__(self) -> Iterator[T]:
-        """Iterate over contained items.
-
-        @return Iterator yielding items of type T.
-        """
-        yield from self._items
-
-    def find(self, predicate) -> Optional[T]:
-        """Find the first item matching a predicate function.
-
-        @param predicate Callable accepting T and returning bool.
-        @return The first matching item or None.
-        """
-        for item in self._items:
-            if predicate(item):
-                return item
-        return None
-
-
-class Renderable(Protocol):
-    """Protocol defining objects that can render to string.
-
-    @brief Structural typing interface for render-capable objects.
-    """
-
-    def render(self) -> str:
-        """Produce a string representation.
-
-        @return Rendered string output.
-        """
-        ...
-
-
-@property  # type: ignore[arg-type]  #!< @brief Property decorator. @details Converts function to property.
-def regular_function(x: int) -> int:
-    """Simple function demonstrating decorator and return.
-
-    @param x Input integer value.
-    @return The input value unchanged.
-    """
-    return x
-
-
-def function_with_walrus(data: List[int]) -> Optional[int]:
-    """Demonstrate the walrus operator in conditional expressions.
-
-    @param data List of integers to scan.
-    @return The first value greater than 10, or None.
-    """
-    # Walrus operator assigns and tests in one expression
-    if (n := next((x for x in data if x > 10), None)) is not None:
-        return n
-    return None
-
-
-def multi_return_paths(value: int) -> Union[str, int, None]:
-    """Function with multiple return paths and match statement.
-
-    @param value Integer selector for branching logic.
-    @return A string, integer, or None depending on value.
-    """
-    match value:
-        case 0:
-            return "zero"
-        case n if n < 0:
-            # Negative values return absolute
-            return abs(n)
-        case n if n > 100:
-            return None
-        case _:
-            return str(value)
-
-
-def generator_function(limit: int) -> Iterator[int]:
-    """Generator yielding squared values up to a limit.
-
-    @param limit Upper bound (exclusive) for generation.
-    @yield Squared integers from 0 to limit-1.
-    """
-    for i in range(limit):
-        # Yield computed square
-        yield i * i
-
-
-async def async_generator(items: List[str]) -> AsyncIterator[str]:
-    """Async generator that yields processed strings.
-
-    @param items Source strings to process.
-    @yield Upper-cased non-empty strings.
-    """
-    for item in items:
-        if item.strip():
-            yield item.upper()
-
-
-@contextmanager  #!< @brief Context manager decorator. @see contextlib.contextmanager
-def managed_resource(path: str):
-    """Context manager for safe resource acquisition and release.
-
-    @param path File system path to the resource.
-    @yield The opened file handle.
-    @raises IOError If the resource cannot be opened.
-    """
-    f = open(path, "r")
-    try:
-        yield f
-    finally:
-        f.close()
-
-
-def closure_factory(multiplier: int):
-    """Create a closure that multiplies its argument.
-
-    @param multiplier The fixed multiplier for the returned function.
-    @return A callable that multiplies input by multiplier.
-    """
-    def inner(x: int) -> int:
-        """Inner closure performing the multiplication.
-
-        @param x Value to multiply.
-        @return Product of x and the captured multiplier.
-        """
-        # Captures multiplier from enclosing scope
-        return x * multiplier
-    return inner
-
-
-def uses_unpacking(*args: int, **kwargs: str) -> Dict[str, Union[int, str]]:
-    """Demonstrate variadic arguments and unpacking.
-
-    @param args Positional integer arguments.
-    @param kwargs Named string arguments.
-    @return Combined dictionary of all arguments.
-    """
-    result: Dict[str, Union[int, str]] = {}
-    for i, val in enumerate(args):
-        result[f"arg_{i}"] = val
-    result.update(kwargs)
-    return result
-
-
-# Lambda assigned to a variable for inline transforms
-transform = lambda x: x * 2 + 1  # noqa: E731
-
-# List comprehension with conditional filtering
-EVEN_SQUARES = [x ** 2 for x in range(20) if x % 2 == 0]
-
-
-async def async_function():
-    """Standalone async coroutine awaiting a no-op.
-
-    @brief Minimal async function for testing async detection.
-    """
-    await asyncio.sleep(0)
-
-
-def deeply_nested_logic(matrix: List[List[int]]) -> int:
-    """Process a matrix with deeply nested control flow.
-
-    @param matrix 2D list of integers.
-    @return Cumulative sum of positive even values.
-    """
-    total = 0
-    for row in matrix:
-        for val in row:
-            if val > 0:
-                if val % 2 == 0:
-                    # Accumulate positive evens
-                    total += val
-                else:
-                    continue
-            else:
-                # Skip non-positive values
-                pass
-    return total
-
-
-def exception_handling_example(path: str) -> Optional[str]:
-    """Demonstrate comprehensive exception handling patterns.
-
-    @param path File path to attempt reading.
-    @return File contents or None on failure.
-    """
-    try:
-        with open(path, "r") as f:
-            content = f.read()
-        if not content:
-            raise ValueError("Empty file")
-        return content
-    except FileNotFoundError:
-        # File does not exist
-        return None
-    except (PermissionError, OSError) as e:  # noqa: F841
-        # Access denied or OS-level error
-        sys.exit(1)
-    except Exception:
-        raise
-    finally:
-        # Cleanup runs regardless of outcome
-        pass
-
-# coverage extension pre-line comment
-MAX_BATCH = 64  # inline extension comment
-# another variable comment
-CACHE_LIMIT = 128
-"""coverage extension multiline comment for parser fixtures"""
-MAX_USERS = 500
-
-# REQ-COVER-SRS-231 START
-# @REQ-COVER-SRS-231 block 1
-# @brief Coverage helper construct 1.
-# @details Provides deterministic fixture-level Doxygen coverage block 1.
-# @param value Input value for helper construct 1.
-# @return Output value for helper construct 1.
-def req_cover_py_1(value: int) -> int:
-    return value + 1
-
-# @REQ-COVER-SRS-231 block 2
-# @brief Coverage helper construct 2.
-# @details Provides deterministic fixture-level Doxygen coverage block 2.
-# @param value Input value for helper construct 2.
-# @return Output value for helper construct 2.
-def req_cover_py_2(value: int) -> int:
-    return value + 2
-
-# @REQ-COVER-SRS-231 block 3
-# @brief Coverage helper construct 3.
-# @details Provides deterministic fixture-level Doxygen coverage block 3.
-# @param value Input value for helper construct 3.
-# @return Output value for helper construct 3.
-def req_cover_py_3(value: int) -> int:
-    return value + 3
-
-# @REQ-COVER-SRS-231 block 4
-# @brief Coverage helper construct 4.
-# @details Provides deterministic fixture-level Doxygen coverage block 4.
-# @param value Input value for helper construct 4.
-# @return Output value for helper construct 4.
-def req_cover_py_4(value: int) -> int:
-    return value + 4
-
-# @REQ-COVER-SRS-231 block 5
-# @brief Coverage helper construct 5.
-# @details Provides deterministic fixture-level Doxygen coverage block 5.
-# @param value Input value for helper construct 5.
-# @return Output value for helper construct 5.
-def req_cover_py_5(value: int) -> int:
-    return value + 5
-
-# REQ-COVER-SRS-231 END