Skip to main content

🎲 simplibs-randomize

PyPI Python Licence

Generate realistic test data effortlessly from Type Hints.

A zero-friction Python library for generating randomized mock values directly from type annotations, custom domain types, and generic structures. Fully configurable, extensible, and isolated.

from simplibs.randomize import randomize

randomize(int)                         # -> 42
randomize(list[str])                   # -> ["alpha", "bravo", "charlie"]
randomize(dict[str, Union[int, bool]]) # -> {"key_x": 105, "key_y": True}

🧭 The Core Philosophy

Writing realistic test fixtures or mock data generation code is often tedious and error-prone. Developers repeatedly build ad-hoc custom generators or wrestle with overly rigid mocking frameworks.

simplibs-randomize bridges this gap by acting as a Type-Aware Randomization Engine. Pass any standard Python type, generic type hint (Union, Literal, Optional), or custom class, and receive a valid instance instantly. It ships with a single, ready-to-use global registry for everyday defaults while giving you fine-grained, context-safe local overrides whenever your tests demand precision.


📦 Installation

pip install simplibs-randomize

🚀 Quick Start in 60 Seconds

Level 1: Standalone Generators

Every randomizer can be called directly and independently — no setup required, and every parameter is optional.

from simplibs.randomize import randomize_int, randomize_str

age = randomize_int(min_value=18, max_value=99)
username = randomize_str(min_length=5, max_length=12)

Level 2: Type-Driven Generation

Don't want to remember which function belongs to which type? Pass any type hint to randomize() and let the library figure out the rest — including nested, generic structures.

from simplibs.randomize import randomize

user_id = randomize(int)
tags = randomize(list[str])
payload = randomize(dict[str, list[Union[int, bool]]])

Level 3: Bulk Generation

Need several values at once? bulk_randomizer handles both positional and dictionary-shaped requests.

from simplibs.randomize import bulk_randomizer

payload = bulk_randomizer({
    "user_id": int,
    "username": (str, {"min_length": 5}),
    "is_active": bool,
})
# -> {"user_id": 482, "username": "aX9qL", "is_active": True}

🛠️ The Architecture: 3 Pillars

┌────────────────────────────────┐
│          Randomizers           │ ◄── Standalone & type-aware generator functions
└──────────────┬─────────────────┘
               │
               ▼
┌────────────────────────────────┐
│            Registry            │ ◄── RANDOMIZERS singleton, RegistryBase, LocalRegistry
└──────────────┬─────────────────┘
               │
               ▼
┌────────────────────────────────┐
│         Core Functions         │ ◄── get_randomizer, randomize, bulk_randomizer
└────────────────────────────────┘

1. Randomizers (The Generators)

Every value-generating function in the library, grouped into Standalone (primitives, special, temporal), Type-Aware (collections, structural), and Meta types — each documented individually with parameters, defaults, examples, and full source.

➡️ README_DEFAULT_RANDOMIZERS

Every one of them is also indexed in the quick-reference table below.

2. Registry (The Storage & Scoping Layer)

The system that maps types to randomizer callables, resolves user overrides before falling back to defaults, and supports fully isolated local scopes via context managers.

  • RegistryBase — the shared abstract foundation (MutableMapping + context-manager logic).
    ➡️ README_REGISTRY_BASE

  • RandomizersRegistry — the concrete class behind the global RANDOMIZERS singleton, also usable as a fully standalone registry.
    ➡️ README_RANDOMIZERS_REGISTRY

  • LocalRegistry — isolated, scoped overrides with transparent global fallback.
    ➡️ README_LOCAL_REGISTRY

  • The RANDOMIZERS singleton & context state (_CURRENT_REGISTRY, get_current_registry) — how the active registry is resolved automatically, everywhere in the library.
    ➡️ README_STATE

  • ALL_DEFAULT — the full built-in dictionary structure every registry falls back to.
    ➡️ randomizers/README_ALL_DEFAULT

3. Core Functions (The Entry Points)

The three top-level functions tying everything together: get_randomizer (resolution), randomize (resolution + execution), and bulk_randomizer (batch processing).

➡️ README_MAIN_FUNCTIONS


📖 Randomizer Quick Reference

Every built-in randomizer, its parameters, and their defaults. For the full description, examples, and implementation of each one, see README_DEFAULT_RANDOMIZERS.

1. Standalone Randomizers

1.1 Primitives

- - - - - Randomizer - - - - - - - - - - - - - - - Parameters (default) - - - - - - - - - -
randomize_bool true_probability: float = 0.5
randomize_bytes min_length: int = 5
max_length: int = 15
randomize_decimal min_value: float = 0.0
max_value: float = 1000.0
exponent: int = -2
randomize_float min_value: float = 0.0
max_value: float = 1000.0
ndigits: int = 2
randomize_int min_value: int = 0
max_value: int = 1000
randomize_str min_length: int = 5
max_length: int = 15
alphabet: str = ascii_letters + digits

1.2 Special

- - - - - Randomizer - - - - - - - - - - - - - - - Parameters (default) - - - - - - - - - -
randomize_path directory: str = "/tmp"
extension: str = ".txt"
name_length: int = 10
randomize_uuid — (no parameters)

1.3 Temporal

- - - - - Randomizer - - - - - - - - - - - - - - - Parameters (default) - - - - - - - - - -
randomize_date start: date = date(2020, 1, 1)
end: date = date(2025, 12, 31)
randomize_datetime start: datetime = datetime(2020, 1, 1)
end: datetime = datetime(2025, 12, 31)
randomize_time min_hour: int = 0
max_hour: int = 23
randomize_timedelta min_seconds: int = 0
max_seconds: int = 2592000 (30 days)

2. Type-Aware Randomizers

2.1 Collections

- - - - - Randomizer - - - - - - - - - - - - - - - Parameters (default) - - - - - - - - - -
randomize_dict dict_type: Any = dict
min_length: int = 1
max_length: int = 5
randomize_list list_type: Any = list
min_length: int = 1
max_length: int = 5
randomize_set set_type: Any = set[str]
min_length: int = 1
max_length: int = 5
max_attempts: int = 50
randomize_tuple tuple_type: Any = tuple
min_length: int = 1
max_length: int = 5

2.2 Structural

- - - - - Randomizer - - - - - - - - - - - - - - - Parameters (default) - - - - - - - - - -
randomize_enum enum_type: type[Enum] = Enum
exclude: Iterable[Enum] | None = None
randomize_literal literal_type: Any = Literal
randomize_union union_type: Any = UnionType
none_probability: float = 0.3

3. Meta Types

- - - - - Randomizer - - - - - - - - - - - - - - - Parameters (default) - - - - - - - - - -
randomize_any *choices: Any
validate: bool = True
get_none — (no parameters)

🗂️ The RANDOMIZERS Singleton & Registry Classes

Every randomizer lookup goes through a registry. By default, that's the global RANDOMIZERS singleton — a ready-to-use instance you can treat as a dictionary, or manage through explicit helper functions:

from simplibs.randomize.registry import RANDOMIZERS, add_randomizer

# Dictionary-style
RANDOMIZERS[str] = lambda: "custom-value"

# Or via the exported helper functions
add_randomizer(str, lambda: "custom-value")

When you need isolation — in tests, or for a specific code path — LocalRegistry lets you override behavior temporarily without touching the global state, while still transparently seeing any global overrides:

from simplibs.randomize.registry.classes import LocalRegistry

with LocalRegistry() as reg:
    reg.add(str, lambda: "TEST_OVERRIDE")
    value = reg.randomize(str)  # -> "TEST_OVERRIDE"

# Global RANDOMIZERS is untouched outside the `with` block

This all works without ever having to pass a registry object around explicitly — every core function automatically resolves "whichever registry is currently active" behind the scenes.

➡️ Full class-by-class, method-by-method breakdown, plus the singleton and context-state mechanics:


🏷️ Building Custom Randomizers: value_type_name

When writing your own randomizers — especially ones that need to know which type hint they were actually resolved for (containers, unions, or any generic-aware generator) — you don't need to pass that information manually through kwargs. The @value_type_name decorator marks a parameter to receive it automatically.

from simplibs.randomize.tools.decorator import value_type_name

@value_type_name("my_type")
def randomize_my_container(my_type: Any = None, *, min_length: int = 1) -> Any:
    ...

Once decorated, calling randomize(my_type_hint) automatically injects my_type_hint into the my_type parameter — unless you've already supplied it explicitly, in which case your value always wins.

Under the hood:

def value_type_name(param_name: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
    """Decorator marking a function parameter to receive the target value type automatically."""

    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:

        # 1. Input validation
        if not isinstance(param_name, str):
            raise_param_name_is_not_str(param_name, func)

        # 2. Attach parameter metadata attribute
        func._value_type_name = param_name

        # 3. Return the modified callable
        return func

    return decorator

This is exactly the mechanism randomize() itself relies on internally for every built-in type-aware randomizer (randomize_dict, randomize_list, randomize_union, ...) — see README_MAIN_FUNCTIONS for the injection logic on the calling side.


⚠️ Exceptions

Every exception raised by simplibs-randomize is built on top of simplibs.exception.SimpleException — meaning failures don't just crash, they explain what went wrong, what was expected, and how to fix it, instead of a bare traceback.

The library's single base exception is RandomizeError:

from simplibs.exception import SimpleException

class RandomizeError(SimpleException):
    """Base exception class for all errors originating from the SimpleRandom library."""

    # Skip internal library frames when generating error location metadata.
    # This ensures that error messages point to user code rather than internal
    # implementation details, unless no user-level frames remain.
    _skip_locations = ("simplibs/random",)

Every error raised internally passes through RandomizeError, so it's always catchable that way. On top of that, individual call sites can additionally pass a native exception type (e.g. TypeError, KeyError) via exception=.... SimpleException then dynamically injects that type into the raised exception's inheritance chain — so the same error becomes catchable both as RandomizeError and as the native type you'd naturally expect:

raise RandomizeError(
    error_name="UNSUPPORTED CHOICE TYPES",
    label="choices",
    value=unknown_types,
    problem="The provided choices contain unsupported types for Any.",
    expected="Registered types in global scope.",
    how_to_fix="Register the type first, e.g. RANDOMIZERS.add(MyType, my_randomizer).",
    exception=TypeError,
)

# Catchable both ways:
try:
    ...
except RandomizeError:
    ...
except TypeError:
    ...

If a call site doesn't pass exception=... at all, the error is still fully catchable via RandomizeError alone.


🧩 A Note on Scope

simplibs-randomize deliberately ships with a solid, well-tested core rather than an exhaustive catalogue of every possible type under the sun. It covers the primitives, collections, and structural constructs you'll actually reach for day to day — and the registry/override system exists precisely so you can extend it with your own domain-specific randomizers as your needs grow, without ever having to modify the library itself. Think of it as a skeleton built to be used immediately and built upon.


☯️ About simplibs

All libraries in the simplibs (Simple Libraries) ecosystem share a common engineering philosophy:

  • Dyslexia-friendly: We actively minimize cognitive load. Code is atomized into small, self-contained units, files are named directly after the logical task they perform, and explanations describe why something is designed, not just what it is.
  • Programmer's Zen: Nothing should be missing, and nothing should be superfluous. We value clean execution paths and robust, understandable code architectures over rushed, messy feature sets.
  • Defensive Style: We actively anticipate edge cases and failure modes so that only safe operational paths remain. Our code is built to degrade gracefully rather than crash unexpectedly.
  • Minimalism: Find the most direct path to the goal in as few operational steps as possible without taking shortcuts on safety, readability, or completeness.
  • Code as Craft: Code should be pleasant to look at, readable at a glance, and evoke structural harmony. We treat software engineering as a precision trade.

🤝 Contributing & Community

This is an open-source project built with love and care. We strongly believe in community collaboration and welcome any feedback, bug reports, or feature ideas!

  • Want to contribute? Feel free to open an Issue or submit a Pull Request.
  • Want to get in touch? If you'd like to discuss the project further, collaborate, or just say hello, feel free to open a GitHub Issue or start a Discussion.

📝 License

This library is released under the MIT License. Build great things!


▲ Back to Top

Metadata

Release files for simplibs-randomize 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for simplibs-randomize 0.1.1
File Size Uploaded Provenance Actions
simplibs_randomize-0.1.1.tar.gz 97.3 kB Without provenance Details for simplibs_randomize-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for simplibs-randomize 0.1.1
File Interpreter ABI Platform Actions
simplibs_randomize-0.1.1-py3-none-any.whl Python 3 none any Details for simplibs_randomize-0.1.1-py3-none-any.whl

Total release size: 291.0 kB

Release files / simplibs_randomize-0.1.1.tar.gz

Download URL simplibs_randomize-0.1.1.tar.gz
Size 97.3 kB
Tags Source
SHA-256 checksum
How to use checksums
a3ce3f4c9e45c569e0ce41e5de7190a84475466634896bd2f684cb7de5ec3326
BLAKE2b-256 checksum
How to use checksums
19c16ef82535f7dd2cb06c04e4376663a656166127cbed3df93eb2639c5cb41c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.9

Release files / simplibs_randomize-0.1.1-py3-none-any.whl

Download URL simplibs_randomize-0.1.1-py3-none-any.whl
Size 193.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ba4203aff2b6751e4d2481b482cc9229f4673701b79c09a8d4615852e4bb114b
BLAKE2b-256 checksum
How to use checksums
b84220fcc4ef4f73d9520be2768a7e6647ff42c8d4da46639d6b077c7259cd86
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.9

Security for simplibs-randomize 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page