pynguin 0.45.0__tar.gz → 0.46.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pynguin
-Version: 0.45.0
+Version: 0.46.0
 Summary: Pynguin is a tool for automated unit test generation for Python
 License: MIT
 Keywords: unit test,random testing,search based,test generation
@@ -82,7 +82,7 @@ is a tool that allows developers to generate unit tests automatically.
 Testing software is often considered to be a tedious task.
 Thus, automated generation techniques have been proposed and mature tools exist—for
 statically typed languages, such as Java.
-There is, however, no fully-automated tool available that produces unit tests for
+There is, however, no fully automated tool available that produces unit tests for
 general-purpose programs in a dynamically typed language.
 Pynguin is, to the best of our knowledge, the first tool that fills this gap
 and allows the automated generation of unit tests for Python programs.
@@ -129,7 +129,7 @@ please report your experiences in using Pynguin to us.
 ## Prerequisites
 
 Before you begin, ensure you have met the following requirements:
-- You have installed Python 3.10 (the support for 3.11, 3.12, 3.13 and 3.14 is experimental).
+- You have installed Python 3.10 (the support for 3.11, 3.12, 3.13, and 3.14 is experimental).
 
   **Attention:** Pynguin now requires at least Python 3.10!  Older versions are no longer
   supported!
@@ -190,13 +190,16 @@ Pynguin is developed at the
 [Chair of Software Engineering II](https://www.fim.uni-passau.de/lehrstuhl-fuer-software-engineering-ii/)
 of the [University of Passau](https://www.uni-passau.de).
 
-Maintainers: [Stephan Lukasczyk](https://github.com/stephanlukasczyk), [Lukas Krodinger](https://github.com/LuKrO2011)
+Maintainer: [Lukas Krodinger](https://github.com/LuKrO2011)
+
+Former Maintainer: [Stephan Lukasczyk](https://codeberg.org/stephanlukasczyk)
 
 Contributors:
 - [Lukas Vögl](https://github.com/lvoegl)
 - [Louis Leppelmann](https://github.com/Tudeldu)
 - [Alexander Wüst](https://github.com/Ravaqor)
 - [Altin Hajdari](https://github.com/AltinHajdari)
+- [Ahmed Abidi](https://github.com/AhmedHedi0)
 - [Abdelillah Aissani](https://github.com/Abassion)
 - [Juan Altmayer Pizzorno](https://github.com/jaltmayerpizzorno)
 - [Lucas Berg](https://github.com/BergLucas)
@@ -215,9 +218,9 @@ Contributors:
 
 ### Development using PyCharm.
 
-If you want to use the PyCharm IDE you have to set up a few things:
+If you want to use the PyCharm IDE, you have to set up a few things:
 1. Import `pynguin` into PyCharm.
-2. Let PyCharm configure configure a virtual environment using `poetry`.
+2. Let PyCharm configure a virtual environment using `poetry`.
 3. Set the default test runner to `pytest`
 4. Set the DocString format to `Google`
 
@@ -226,7 +229,7 @@ If you want to use the PyCharm IDE you have to set up a few things:
 
 This project is licensed under the terms of the [MIT License](LICENSE.rst).
 Pynguin was using the GNU Lesser General Public License (LGPL) until version 0.29.0,
-its licence was changed with version 0.30.0.
+its license was changed with version 0.30.0.
 
 ## Star History
 

{pynguin-0.45.0 → pynguin-0.46.0}/README.md

@@ -18,7 +18,7 @@ is a tool that allows developers to generate unit tests automatically.
 Testing software is often considered to be a tedious task.
 Thus, automated generation techniques have been proposed and mature tools exist—for
 statically typed languages, such as Java.
-There is, however, no fully-automated tool available that produces unit tests for
+There is, however, no fully automated tool available that produces unit tests for
 general-purpose programs in a dynamically typed language.
 Pynguin is, to the best of our knowledge, the first tool that fills this gap
 and allows the automated generation of unit tests for Python programs.
@@ -65,7 +65,7 @@ please report your experiences in using Pynguin to us.
 ## Prerequisites
 
 Before you begin, ensure you have met the following requirements:
-- You have installed Python 3.10 (the support for 3.11, 3.12, 3.13 and 3.14 is experimental).
+- You have installed Python 3.10 (the support for 3.11, 3.12, 3.13, and 3.14 is experimental).
 
   **Attention:** Pynguin now requires at least Python 3.10!  Older versions are no longer
   supported!
@@ -126,13 +126,16 @@ Pynguin is developed at the
 [Chair of Software Engineering II](https://www.fim.uni-passau.de/lehrstuhl-fuer-software-engineering-ii/)
 of the [University of Passau](https://www.uni-passau.de).
 
-Maintainers: [Stephan Lukasczyk](https://github.com/stephanlukasczyk), [Lukas Krodinger](https://github.com/LuKrO2011)
+Maintainer: [Lukas Krodinger](https://github.com/LuKrO2011)
+
+Former Maintainer: [Stephan Lukasczyk](https://codeberg.org/stephanlukasczyk)
 
 Contributors:
 - [Lukas Vögl](https://github.com/lvoegl)
 - [Louis Leppelmann](https://github.com/Tudeldu)
 - [Alexander Wüst](https://github.com/Ravaqor)
 - [Altin Hajdari](https://github.com/AltinHajdari)
+- [Ahmed Abidi](https://github.com/AhmedHedi0)
 - [Abdelillah Aissani](https://github.com/Abassion)
 - [Juan Altmayer Pizzorno](https://github.com/jaltmayerpizzorno)
 - [Lucas Berg](https://github.com/BergLucas)
@@ -151,9 +154,9 @@ Contributors:
 
 ### Development using PyCharm.
 
-If you want to use the PyCharm IDE you have to set up a few things:
+If you want to use the PyCharm IDE, you have to set up a few things:
 1. Import `pynguin` into PyCharm.
-2. Let PyCharm configure configure a virtual environment using `poetry`.
+2. Let PyCharm configure a virtual environment using `poetry`.
 3. Set the default test runner to `pytest`
 4. Set the DocString format to `Google`
 
@@ -162,7 +165,7 @@ If you want to use the PyCharm IDE you have to set up a few things:
 
 This project is licensed under the terms of the [MIT License](LICENSE.rst).
 Pynguin was using the GNU Lesser General Public License (LGPL) until version 0.29.0,
-its licence was changed with version 0.30.0.
+its license was changed with version 0.30.0.
 
 ## Star History
 

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

@@ -4,7 +4,7 @@
 
 [tool.poetry]
 name = "pynguin"
-version = "0.45.0"
+version = "0.46.0"
 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}/src/pynguin/__version__.py

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

pynguin-0.46.0/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}/src/pynguin/analyses/module.py

@@ -19,6 +19,7 @@ import itertools
 import json
 import logging
 import queue
+import re
 import types
 import typing
 from collections import defaultdict
@@ -44,6 +45,7 @@ from pynguin.analyses.type_inference import (
     HintInference,
     InferenceProvider,
     LLMInference,
+    LLMInferenceWithSubtypes,
     NoInference,
     TypeEvalPyInference,
 )
@@ -74,13 +76,12 @@ from pynguin.analyses.typesystem import (
     UnionType,
     Unsupported,
 )
-from pynguin.configuration import TypeInferenceStrategy
+from pynguin.configuration import ElementVisibility, TypeInferenceStrategy
 from pynguin.ga.operators.selection import RandomSelection, RankSelection
 from pynguin.utils import randomness
 from pynguin.utils.exceptions import (
     ConstraintValidationError,
     ConstructionFailedException,
-    CoroutineFoundException,
 )
 from pynguin.utils.generic.genericaccessibleobject import (
     GenericAccessibleObject,
@@ -204,6 +205,27 @@ MODULE_BLACKLIST = frozenset((
 METHOD_BLACKLIST = frozenset(("time.sleep",))
 
 
+def _is_function(element: Any) -> bool:
+    """Whether the element is a module-level function we can analyse.
+
+    Besides plain functions this also accepts callables wrapped by
+    ``functools.cache`` / ``functools.lru_cache`` (a
+    ``functools._lru_cache_wrapper``), for which ``inspect.isfunction`` returns
+    ``False``. Without this a cache-decorated public function would be silently
+    dropped from the test cluster.
+
+    Args:
+        element: The element to check
+
+    Returns:
+        Is the element a (possibly cache-wrapped) function?
+    """
+    return inspect.isfunction(element) or (
+        isinstance(element, functools._lru_cache_wrapper)  # noqa: SLF001
+        and inspect.isfunction(inspect.unwrap(element))
+    )
+
+
 def _is_blacklisted(element: Any) -> bool:
     """Checks if the given element belongs to the blacklist.
 
@@ -226,19 +248,21 @@ def _is_blacklisted(element: Any) -> bool:
                 # Allow some builtin types
                 return False
             return element.__module__ in module_blacklist
-        if inspect.isfunction(element):
+        if _is_function(element):
             # Some modules can be run standalone using a main function or provide a small
             # set of tests ('test'). We don't want to include those functions.
             # Importing certain modules such as inspect, that use or import C-functions can
             # lead to __module__ being None. We want to exclude these functions as well.
+            # Unwrap so cache-wrapped functions are checked against their real name/module.
+            func = inspect.unwrap(element)
             return (
-                element.__module__ is None
-                or element.__module__ in module_blacklist
-                or element.__qualname__.startswith((
+                func.__module__ is None
+                or func.__module__ in module_blacklist
+                or func.__qualname__.startswith((
                     "main",
                     "test",
                 ))
-                or f"{element.__module__}.{element.__qualname__}" in method_blacklist
+                or f"{func.__module__}.{func.__qualname__}" in method_blacklist
             )
     except Exception:  # noqa: BLE001
         LOGGER.warning(
@@ -793,6 +817,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
@@ -1286,6 +1313,51 @@ def __is_private(method_name: str) -> bool:
     return method_name.startswith("__") and not method_name.endswith("__")
 
 
+__NAME_MANGLED_PATTERN = re.compile(r"^_[A-Za-z][A-Za-z0-9]*__\w+$")
+
+
+def __is_name_mangled(name: str) -> bool:
+    """Checks whether ``name`` looks like a name-mangled private attribute.
+
+    Python mangles a class-private name ``__attr`` defined in class ``Foo`` to
+    ``_Foo__attr``. Since the leading underscores of the class name are
+    stripped during mangling, the mangled name always starts with a single
+    underscore, followed by an identifier not starting with an underscore,
+    followed by a double underscore and the (non-dunder) original name.
+
+    Args:
+        name: The name to check.
+
+    Returns:
+        True, if the name looks like a name-mangled private attribute.
+    """
+    return bool(__NAME_MANGLED_PATTERN.fullmatch(name)) and not name.endswith("__")
+
+
+def __should_skip_by_visibility(name: str, *, add_to_test: bool) -> bool:
+    """Determines whether an element should be skipped based on its visibility.
+
+    Args:
+        name: The (unqualified) name of the element.
+        add_to_test: Whether the element belongs to the module under test.
+
+    Returns:
+        True, if the element should be skipped from analysis.
+    """
+    if not add_to_test:
+        # The relaxed visibility handling only applies to the module under test;
+        # non-public elements of dependency modules are always excluded.
+        return __is_private(name) or __is_protected(name)
+
+    match config.configuration.element_visibility:
+        case ElementVisibility.ALL:
+            return False
+        case ElementVisibility.PROTECTED:
+            return __is_private(name) or __is_name_mangled(name)
+        case _:
+            return __is_private(name) or __is_protected(name)
+
+
 def __is_method_defined_in_class(class_: type | types.UnionType, method: object) -> bool:
     return class_ == get_class_that_defined_method(method)
 
@@ -1353,14 +1425,20 @@ def __analyse_function(
     test_cluster: ModuleTestCluster,
     add_to_test: bool,
 ) -> None:
-    if __is_private(func_name) or __is_protected(func_name):
+    if __should_skip_by_visibility(func_name.rpartition(".")[2], add_to_test=add_to_test):
         LOGGER.debug("Skipping function %s from analysis", func_name)
         return
     if inspect.iscoroutinefunction(func) or inspect.isasyncgenfunction(func):
+        # Pynguin cannot execute coroutines (see issue #62 / MR !59), so we skip
+        # them instead of aborting the whole module and still test its
+        # synchronous members.
         if add_to_test:
-            raise CoroutineFoundException("Found coroutine in SUT: %s", func_name)
-        # Coroutine outside the SUT are not problematic, just exclude them.
-        LOGGER.debug("Skipping coroutine %s outside of SUT", func_name)
+            LOGGER.warning(
+                "Skipping coroutine %s: Pynguin only tests the non-async parts of this module.",
+                func_name,
+            )
+        else:
+            LOGGER.debug("Skipping coroutine %s outside of SUT", func_name)
         return
 
     LOGGER.debug("Analysing function %s", func_name)
@@ -1553,18 +1631,23 @@ def __analyse_method(
 ) -> None:
     if (
         __is_annotate(method_name)
-        or __is_private(method_name)
-        or __is_protected(method_name)
+        or __should_skip_by_visibility(method_name.rpartition(".")[2], add_to_test=add_to_test)
         or __is_constructor(method_name)
         or not __is_method_defined_in_class(type_info.raw_type, method)
     ):
         LOGGER.debug("Skipping method %s from analysis", method_name)
         return
     if inspect.iscoroutinefunction(method) or inspect.isasyncgenfunction(method):
+        # Pynguin cannot execute coroutines (see issue #62 / MR !59), so we skip
+        # them instead of aborting the whole module and still test its
+        # synchronous members.
         if add_to_test:
-            raise CoroutineFoundException("Found coroutine in SUT: %s", method_name)
-        # Coroutine outside the SUT are not problematic, just exclude them.
-        LOGGER.debug("Skipping coroutine %s outside of SUT", method_name)
+            LOGGER.warning(
+                "Skipping coroutine %s: Pynguin only tests the non-async parts of this module.",
+                method_name,
+            )
+        else:
+            LOGGER.debug("Skipping coroutine %s outside of SUT", method_name)
         return
 
     LOGGER.debug("Analysing method %s.%s", type_info.full_name, method_name)
@@ -1778,7 +1861,7 @@ def __analyse_included_functions(
     seen_functions: set,
 ) -> None:
     for current in filter(
-        lambda x: inspect.isfunction(x) and not _is_blacklisted(x),
+        lambda x: _is_function(x) and not _is_blacklisted(x),
         vars(module).values(),
     ):
         if current in seen_functions:
@@ -1815,8 +1898,12 @@ def __check_c_modules(
             non_whitelisted_modules.add(module.__name__)
         return non_whitelisted_modules
 
-    # If the module is Python, inspect its members too:
-    for element in vars(module).values():
+    # If the module is Python, inspect its members too.
+    # Snapshot the values first: inspecting a member can mutate the module's
+    # globals (e.g. a PEP 562 module-level ``__getattr__`` that lazily caches
+    # results), which would otherwise raise "dictionary changed size during
+    # iteration" while iterating the live ``__dict__``.
+    for element in list(vars(module).values()):
         if inspect.isfunction(element) or inspect.isclass(element):
             try:
                 inspect.getsource(element)
@@ -1890,6 +1977,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:
@@ -1928,33 +2018,48 @@ def _load_typeevalpy_data() -> ParsedTypeEvalPyData | None:
         return None
 
 
-def _collect_public_callables(module: ModuleType) -> Sequence[Callable[..., Any]]:
-    """Collects a list of all public accessibles in a module."""
-    callables = []
-    seen = set()
-
-    def add(obj):
-        if id(obj) not in seen:
-            callables.append(obj)
-            seen.add(id(obj))
-
+def __collect_module_level_functions(
+    module: ModuleType, add: Callable[[Callable[..., Any]], None]
+) -> None:
     for name, obj in vars(module).items():
-        if name.startswith("_") and name != "__init__":
+        if name != "__init__" and __should_skip_by_visibility(name, add_to_test=True):
             continue
         if inspect.isfunction(obj) and obj.__module__ == module.__name__:
             add(obj)
 
+
+def __collect_class_methods(module: ModuleType, add: Callable[[Callable[..., Any]], None]) -> None:
     for cls_name, cls in vars(module).items():
+        if not inspect.isclass(cls) or cls.__module__ != module.__name__:
+            continue
+        # The private-class filter is only applied for PUBLIC visibility; other
+        # visibility levels never filter classes by name (matching the main
+        # analysis, which does not filter classes based on their name).
         if (
-            cls_name.startswith("_")
-            or not inspect.isclass(cls)
-            or cls.__module__ != module.__name__
+            config.configuration.element_visibility == ElementVisibility.PUBLIC
+            and cls_name.startswith("_")
         ):
             continue
         for meth_name, member in inspect.getmembers(cls, predicate=inspect.isfunction):
-            if not meth_name.startswith("_"):
+            if __is_constructor(meth_name):
+                continue
+            if not __should_skip_by_visibility(meth_name, add_to_test=True):
                 add(member)
 
+
+def _collect_public_callables(module: ModuleType) -> Sequence[Callable[..., Any]]:
+    """Collects a list of all public accessibles in a module."""
+    callables: list[Callable[..., Any]] = []
+    seen: set[int] = set()
+
+    def add(obj: Callable[..., Any]) -> None:
+        if id(obj) not in seen:
+            callables.append(obj)
+            seen.add(id(obj))
+
+    __collect_module_level_functions(module, add)
+    __collect_class_methods(module, add)
+
     return callables
 
 

pynguin-0.46.0/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)