API Reference

StringGen

string_gen.StringGen

StringGen(
    pattern: Union[Pattern, AnyStr],
    seed: SeedType = None,
    *,
    max_repeat: Union[int, None] = None,
    alphabet: Union[str, None] = None,
)

Random string generator driven by a regular expression pattern.

Compiles the given regex and produces random strings that match it. Supports literals, character classes, quantifiers, groups, alternation, anchors, lookahead assertions, and backreferences.

The max_repeat parameter controls the upper bound for unbounded quantifiers (*, +, {n,}). It can be set per-instance via the constructor or globally via :func:configure.

Instances are iterable: iterating yields an infinite stream of random matching strings. Use :meth:stream for a bounded lazy generator.

Instances can be combined with | to concatenate patterns, compared with == against other patterns, and tested for emptiness with bool().

pattern property

pattern: Pattern

Compiled re.Pattern object used for generation.

render

render() -> str

Produce a single random string matching the pattern.

render_list

render_list(count: int) -> List[str]

Produce a list of random strings matching the pattern.

Parameters:

Name	Type	Description	Default
count	int	Number of strings to generate.	required

render_set

render_set(
    count: int, *, max_iteration: int = 100000
) -> Set[str]

Produce a set of unique random strings matching the pattern.

Keeps generating until count unique strings are collected or max_iteration attempts are exhausted.

Parameters:

Name	Type	Description	Default
count	int	Required number of unique strings.	required
max_iteration	int	Maximum generation attempts before giving up.	100000

Raises:

Type	Description
ValueError	If max_iteration is less than count.
StringGenMaxIterationsReachedError	If the iteration limit is reached before collecting enough unique strings.

stream

stream(count: int) -> Iterator[str]

Return a lazy iterator that yields count random matching strings.

Unlike :meth:render_list, strings are generated one at a time and never collected into a list, making stream memory-efficient for large batches.

Parameters:

Name	Type	Description	Default
count	int	Number of strings to yield.	required

Raises:

Type	Description
ValueError	If count is negative. .. code-block:: python gen = StringGen(r"\d{4}") for value in gen.stream(1000): process(value)

count

count() -> Union[int, float]

Return the number of unique strings the pattern can produce.

Returns math.inf for patterns with unbounded quantifiers (*, +, {n,}). The result is cached after the first call.

enumerate

enumerate(
    *, limit: Union[int, None] = None
) -> Iterator[str]

Yield all unique strings the pattern can produce.

For patterns with unbounded quantifiers, limit caps the maximum repetition count. When limit is None the parser's max_repeat value is used.

Parameters:

Name	Type	Description	Default
limit	Union[int, None]	Maximum repetitions for unbounded quantifiers.	None

Raises:

Type	Description
ValueError	If limit is less than 1.

seed

seed(seed: SeedType = None) -> None

Re-seed the internal random number generator.

Calling with the same seed produces the same sequence of rendered strings.

Parameters:

Name	Type	Description	Default
seed	SeedType	Seed value accepted by random.Random.seed.	None

configure

string_gen.configure

configure(
    *,
    max_repeat: Union[int, None] = None,
    alphabet: Union[str, None] = None,
) -> None

Configure global defaults for new StringGen instances.

Settings apply to all subsequently created instances unless overridden in the constructor. Omit a parameter to leave it unchanged.

Parameters:

Name	Type	Description	Default
max_repeat	Union[int, None]	Maximum repetitions for unbounded quantifiers (*, +, {n,}). Must be >= 1. Default is 100.	None
alphabet	Union[str, None]	Custom alphabet string replacing string.ascii_letters in all character categories. Must be a non-empty string.	None

Raises:

Type	Description
ValueError	If max_repeat is less than 1.
TypeError	If alphabet is not a non-empty string.

reset

string_gen.reset

reset() -> None

Reset all global settings to their defaults.

Exceptions

StringGenError

string_gen.StringGenError

Bases: Exception

Base exception for all string-gen errors.

StringGenPatternError

string_gen.StringGenPatternError

StringGenPatternError(
    pattern: Union[Pattern, AnyStr], *args
)

Bases: StringGenError

Exception raised when an invalid regex pattern is provided.

Parameters:

Name	Type	Description	Default
pattern	Union[Pattern, AnyStr]	The pattern that failed to compile.	required

StringGenMaxIterationsReachedError

string_gen.StringGenMaxIterationsReachedError

StringGenMaxIterationsReachedError(
    max_iterations: int, *args
)

Bases: StringGenError

Exception raised when render_set exhausts its iteration budget.

Parameters:

Name	Type	Description	Default
max_iterations	int	The iteration limit that was reached.	required