pynguin 0.45.0__tar.gz → 0.46.0.dev0__tar.gz

{pynguin-0.45.0 → pynguin-0.46.0.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pynguin
-Version: 0.45.0
+Version: 0.46.0.dev0
 Summary: Pynguin is a tool for automated unit test generation for Python
 License: MIT
 Keywords: unit test,random testing,search based,test generation

{pynguin-0.45.0 → pynguin-0.46.0.dev0}/pyproject.toml

@@ -4,7 +4,7 @@
 
 [tool.poetry]
 name = "pynguin"
-version = "0.45.0"
+version = "0.46.0.dev"
 description = "Pynguin is a tool for automated unit test generation for Python"
 authors = [
   "Stephan Lukasczyk <stephan@pynguin.eu>",
@@ -99,6 +99,7 @@ pytest-cov = "^6.1.1"
 pytest-mock = "^3.14.0"
 pytest-picked = "^0.5.1"
 pytest-sugar = "^1.0.0"
+pytest-xdist = "^3.6.0"
 
 [tool.poetry.extras]
 openai = [ "openai", "python-dotenv" ]

{pynguin-0.45.0 → pynguin-0.46.0.dev0}/src/pynguin/__version__.py

@@ -6,4 +6,4 @@
 #
 """Specifies the version of Pynguin."""
 
-__version__ = "0.45.0"
+__version__ = "0.46.0.dev"

pynguin-0.46.0.dev0/src/pynguin/analyses/AGENTS.md

@@ -0,0 +1,114 @@
+<!--
+SPDX-FileCopyrightText: 2019–2026 Pynguin Contributors
+
+SPDX-License-Identifier: CC-BY-4.0
+-->
+
+# Analyses Module
+
+<!-- Parent: ../AGENTS.md -->
+
+The `analyses/` directory contains static analysis components for subject program understanding, including module analysis, type inference, and test cluster generation.
+
+## Overview
+
+This module performs comprehensive program analysis to:
+- Build test clusters from subject program callables
+- Perform type inference on generic types
+- Analyze module structure and complexity
+- Support seeding from existing tests
+
+## Directory Structure
+
+```
+analyses/
+├── constants.py             # Analysis constants and configuration
+├── generator.py             # Test cluster generation from modules
+├── module.py                # Module representation and access
+├── modulecomplexity.py      # Module complexity metrics
+├── seeding.py               # Seed test generation from existing tests
+├── string_subtypes.py       # String type hierarchy analysis
+├── syntaxtree.py            # Abstract syntax tree utilities
+└── type_inference.py        # Generic type inference engine
+├── typesystem.py            # Type system representation
+```
+
+## Core Components
+
+### 1. Module Analysis (module.py)
+- **ModuleAccessor**: Accesses Python modules and their callables
+- Discovers classes, methods, functions within a module
+- Tracks module dependencies and import structure
+- Filters public vs. private members
+
+### 2. Type System (typesystem.py)
+- **GenericType**: Represents generic Python types (List[int], Dict[str, Any])
+- **Type inference**: Resolves type parameters from annotations and usage
+- Handles complex type hierarchies and bounds
+- Supports Union, Optional, generic base classes
+
+### 3. Type Inference (type_inference.py)
+- Infers generic type parameters from class hierarchies
+- Resolves type variables in method signatures
+- Handles substitution of type bounds
+
+### 4. Test Cluster Generation (generator.py)
+- **TestCluster**: Collection of callable descriptions with dependency info
+- Creates from subject module or custom callables
+- Builds dependency graph for method/function calls
+- Tracks class hierarchies for polymorphism
+
+### 5. Seeding (seeding.py)
+- Loads existing tests from files or test suites
+- Extracts test cases for use as initial population
+- Supports multiple test formats
+
+### 6. Complexity Analysis (modulecomplexity.py)
+- Computes module complexity metrics
+- Analyzes cyclomatic complexity
+- Used for search space characterization
+
+## Key Patterns
+
+### Module Access
+```python
+from pynguin.analyses.module import ModuleAccessor
+
+accessor = ModuleAccessor(module)
+callables = accessor.get_all_callables()
+classes = accessor.get_classes()
+```
+
+### Type System
+```python
+from pynguin.analyses.typesystem import GenericType
+
+# Parse complex types
+list_int = GenericType.from_string("List[int]")
+dict_type = GenericType.from_string("Dict[str, Any]")
+```
+
+### Test Cluster
+```python
+from pynguin.analyses.generator import TestClusterGenerator
+
+generator = TestClusterGenerator()
+cluster = generator.generate_cluster(module)
+callables = cluster.get_all_callables()
+```
+
+## Related Modules
+
+- `ga/` - Uses test clusters for search space definition
+- `testcase/` - Test cases use analyzed type information
+- `instrumentation/` - Complements dynamic analysis
+
+## Key Files to Explore
+
+- `typesystem.py` - Complete type system representation
+- `generator.py` - Test cluster generation algorithm
+- `module.py` - Module introspection utilities
+
+---
+
+**Timestamp**: 2026-01-30

{pynguin-0.45.0 → pynguin-0.46.0.dev0}/src/pynguin/analyses/generator.py

@@ -10,18 +10,80 @@ Generators can be either GenericCallableAccessibleObjects or GenericEnum objects
 
 import functools
 import itertools
-from abc import abstractmethod
+from abc import ABC, abstractmethod
 from collections import defaultdict
+from typing import Generic, TypeVar
 
 import pynguin.configuration as config
 from pynguin.analyses.typesystem import AnyType, NoneType, ProperType, TypeSystem, is_primitive_type
-from pynguin.ga.operators.selection import Selectable, SelectionFunction
+from pynguin.utils import randomness
 from pynguin.utils.generic.genericaccessibleobject import (
     GenericAccessibleObject,
     GenericCallableAccessibleObject,
 )
 from pynguin.utils.orderedset import FrozenOrderedSet, OrderedSet
 
+S = TypeVar("S")
+
+
+class Selectable(ABC):
+    """Interface for objects that can be selected based on fitness."""
+
+    @abstractmethod
+    def get_fitness(self) -> float:
+        """Return the fitness value of this selectable object."""
+
+
+class SelectionFunction(ABC, Generic[S]):
+    """Interface for functions that select from a population."""
+
+    @abstractmethod
+    def select(self, population: list[S], number: int = 1) -> list[S]:
+        """Select `number` items from `population`."""
+
+
+class RandomSelection(SelectionFunction[S]):
+    """Selects items uniformly at random."""
+
+    def select(self, population: list[S], number: int = 1) -> list[S]:
+        """Select `number` items from `population`."""
+        return [randomness.RNG.choice(population) for _ in range(number)]
+
+
+class RankSelection(SelectionFunction[S]):
+    """Selects items using linear rank-based probability (lower fitness index = better)."""
+
+    def __init__(self, bias: float = 1.7) -> None:
+        """Initializes the rank selection function.
+
+        Args:
+            bias: The selection bias.
+        """
+        self._bias = bias
+
+    def select(self, population: list[S], number: int = 1) -> list[S]:
+        """Select `number` items from `population`."""
+        n = len(population)
+        if n == 0:
+            return []
+        weights = [
+            max(0.0, (2 - self._bias) + 2 * (self._bias - 1) * (n - 1 - i) / max(n - 1, 1))
+            for i in range(n)
+        ]
+        total = sum(weights)
+        results = []
+        for _ in range(number):
+            r = randomness.RNG.uniform(0, total)
+            cumulative = 0.0
+            selected = population[-1]
+            for i, item in enumerate(population):
+                cumulative += weights[i]
+                if cumulative >= r:
+                    selected = item
+                    break
+            results.append(selected)
+        return results
+
 
 class GeneratorFitnessFunction:
     """Interface for a fitness function for type generators."""

{pynguin-0.45.0 → pynguin-0.46.0.dev0}/src/pynguin/analyses/module.py

@@ -44,6 +44,7 @@ from pynguin.analyses.type_inference import (
     HintInference,
     InferenceProvider,
     LLMInference,
+    LLMInferenceWithSubtypes,
     NoInference,
     TypeEvalPyInference,
 )
@@ -52,7 +53,12 @@ from pynguin.utils.llm import LLMProvider
 if config.configuration.pynguinml.ml_testing_enabled or typing.TYPE_CHECKING:
     import pynguin.utils.pynguinml.ml_testing_resources as tr
 
-from pynguin.analyses.generator import GeneratorProvider, RandomGeneratorProvider
+from pynguin.analyses.generator import (
+    GeneratorProvider,
+    RandomGeneratorProvider,
+    RandomSelection,
+    RankSelection,
+)
 from pynguin.analyses.modulecomplexity import mccabe_complexity
 from pynguin.analyses.syntaxtree import (
     FunctionDescription,
@@ -75,7 +81,6 @@ from pynguin.analyses.typesystem import (
     Unsupported,
 )
 from pynguin.configuration import TypeInferenceStrategy
-from pynguin.ga.operators.selection import RandomSelection, RankSelection
 from pynguin.utils import randomness
 from pynguin.utils.exceptions import (
     ConstraintValidationError,
@@ -100,9 +105,8 @@ if config.configuration.pynguinml.ml_testing_enabled or typing.TYPE_CHECKING:
 
 if typing.TYPE_CHECKING:
     from collections.abc import Callable, Sequence
+    from typing import Any
 
-    import pynguin.ga.algorithms.archive as arch
-    import pynguin.ga.computations as ff
     from pynguin.instrumentation.tracer import SubjectProperties
     from pynguin.utils.pynguinml.mlparameter import MLParameter
 
@@ -793,6 +797,9 @@ class ModuleTestCluster(TestCluster):  # noqa: PLR0904
         # Keep track of all callables, this is only for statistics purposes.
         self.__callables: OrderedSet[GenericCallableAccessibleObject] = OrderedSet()
 
+        # Whether the SUT or any of its transitive imports uses Python's random module.
+        self.sut_uses_random: bool = False
+
     def _setup_generator_selection(self) -> GeneratorProvider:
         if (
             config.configuration.generator_selection.generator_selection_algorithm
@@ -1143,9 +1150,9 @@ class FilteredModuleTestCluster(TestCluster):  # noqa: PLR0904
     def __init__(  # noqa: D107
         self,
         delegate: ModuleTestCluster,
-        archive: arch.Archive,
+        archive: Any,
         subject_properties: SubjectProperties,
-        targets: OrderedSet[ff.TestCaseFitnessFunction],
+        targets: OrderedSet,
     ) -> None:
         self.__delegate = delegate
         self.__subject_properties = subject_properties
@@ -1177,7 +1184,7 @@ class FilteredModuleTestCluster(TestCluster):  # noqa: PLR0904
         archive.add_on_target_covered(self.on_target_covered)
 
     def __get_accessible_object_for_target(
-        self, target: ff.TestCaseFitnessFunction
+        self, target: Any
     ) -> GenericCallableAccessibleObject | None:
         code_object_id: int | None = target.code_object_id
         while code_object_id is not None:
@@ -1190,7 +1197,7 @@ class FilteredModuleTestCluster(TestCluster):  # noqa: PLR0904
             ].parent_code_object_id
         return None
 
-    def on_target_covered(self, target: ff.TestCaseFitnessFunction) -> None:
+    def on_target_covered(self, target: Any) -> None:
         """A callback function to get informed by an archive when a target is covered.
 
         Args:
@@ -1890,6 +1897,9 @@ def get_type_provider(
         case TypeInferenceStrategy.LLM:
             callables = _collect_public_callables(module)
             return LLMInference(callables, LLMProvider.OPENAI, type_system)
+        case TypeInferenceStrategy.LLM_WITH_SUBTYPES:
+            callables = _collect_public_callables(module)
+            return LLMInferenceWithSubtypes(callables, LLMProvider.OPENAI, type_system)
         case TypeInferenceStrategy.TYPE_HINTS:
             return HintInference()
         case TypeInferenceStrategy.NONE:

pynguin-0.46.0.dev0/src/pynguin/analyses/string_subtype_inference.py

@@ -0,0 +1,120 @@
+#  This file is part of Pynguin.
+#
+#  SPDX-FileCopyrightText: 2019–2026 Pynguin Contributors
+#
+#  SPDX-License-Identifier: MIT
+#
+"""Utility for converting LLM subtype inference to StringSubtype instances."""
+
+from __future__ import annotations
+
+import logging
+import re
+
+from pynguin.analyses.typesystem import (
+    CSVString,
+    EmailString,
+    IPv4String,
+    IPv6String,
+    ISOColorString,
+    ISODateString,
+    StringSubtype,
+    URLString,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+# Mapping of Faker method names to corresponding StringSubtype classes
+_GENERATOR_TO_SUBTYPE: dict[str, type[StringSubtype]] = {
+    "email": EmailString,
+    "ipv4": IPv4String,
+    "ipv6": IPv6String,
+    "color": ISOColorString,
+    "csv": CSVString,
+    "date": ISODateString,
+    "url": URLString,
+}
+
+# Mapping of StringSubtype classes to Faker method names
+_SUBTYPE_TO_GENERATOR: dict[type[StringSubtype], str] = {
+    v: k for k, v in _GENERATOR_TO_SUBTYPE.items()
+}
+
+AVAILABLE_GENERATORS: list[str] = list(_GENERATOR_TO_SUBTYPE.keys())
+
+
+def get_subtype_for_generator(generator_name: str) -> StringSubtype | None:
+    """Get a StringSubtype instance for a given Faker generator name."""
+    subtype_class = _GENERATOR_TO_SUBTYPE.get(generator_name)
+    # All registered StringSubtype subclasses have no-arg constructors
+    return subtype_class() if subtype_class else None  # type: ignore[call-arg]
+
+
+def get_generator_for_subtype(subtype: StringSubtype) -> str | None:
+    """Get the Faker generator name for a given StringSubtype instance."""
+    return _SUBTYPE_TO_GENERATOR.get(type(subtype))
+
+
+def has_generator(generator_name: str) -> bool:
+    """Check if a generator name is registered."""
+    return generator_name in _GENERATOR_TO_SUBTYPE
+
+
+def from_string(subtype_str: str) -> StringSubtype | None:
+    """Convert a subtype string into a StringSubtype instance.
+
+    The subtype string can be either:
+    1. A Faker generator name (e.g., "email", "ipv4", "url")
+    2. A custom regex pattern (e.g., "^[a-z]+$")
+
+    Args:
+        subtype_str: The subtype string from LLM inference
+
+    Returns:
+        A StringSubtype instance, or None if conversion fails
+    """
+    if not subtype_str or not isinstance(subtype_str, str):
+        return None
+
+    # First, try to match against known Faker generators
+    if has_generator(subtype_str):
+        subtype = get_subtype_for_generator(subtype_str)
+        if subtype:
+            return subtype
+
+    # Otherwise, try to parse as a custom regex pattern
+    try:
+        # Validate that it's a valid regex by attempting to compile it
+        compiled_regex = re.compile(subtype_str)
+        return StringSubtype(compiled_regex)
+    except re.error as e:
+        _LOGGER.warning(
+            "Failed to parse subtype string '%s' as regex pattern: %s",
+            subtype_str,
+            e,
+        )
+        return None
+
+
+def from_faker_generator(generator_name: str) -> StringSubtype | None:
+    """Create a StringSubtype from a Faker generator name.
+
+    Args:
+        generator_name: The name of the Faker generator
+
+    Returns:
+        A StringSubtype instance, or None if the generator is not registered
+    """
+    return get_subtype_for_generator(generator_name)
+
+
+def to_faker_generator(subtype: StringSubtype) -> str | None:
+    """Get the Faker generator name for a StringSubtype, if available.
+
+    Args:
+        subtype: The StringSubtype instance
+
+    Returns:
+        The Faker generator name, or None if no mapping exists
+    """
+    return get_generator_for_subtype(subtype)