From 97a88905b7f0f513bd480fe630e43798aba22c74 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Barrois?= Date: Wed, 18 Feb 2015 22:00:01 +0100 Subject: Enable resetting factory.fuzzy's random generator (Closes #175, #185). Users may now call ``factory.fuzzy.get_random_state()`` to retrieve the current random generator's state (isolated from the one used in Python's ``random``). That state can then be reinjected with ``factory.fuzzy.set_random_state(state)``. --- docs/changelog.rst | 4 ++++ docs/fuzzy.rst | 30 ++++++++++++++++++++++++++++++ 2 files changed, 34 insertions(+) (limited to 'docs') diff --git a/docs/changelog.rst b/docs/changelog.rst index 018ec60..ebe9930 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -7,6 +7,10 @@ ChangeLog 2.5.0 (master) -------------- +*New:* + + - Add support for getting/setting :mod:`factory.fuzzy`'s random state (see :issue:`175`, :issue:`185`). + *Deprecation:* - Remove deprecated features from :ref:`v2.4.0` diff --git a/docs/fuzzy.rst b/docs/fuzzy.rst index 1480419..0658652 100644 --- a/docs/fuzzy.rst +++ b/docs/fuzzy.rst @@ -338,3 +338,33 @@ They should inherit from the :class:`BaseFuzzyAttribute` class, and override its The method responsible for generating random values. *Must* be overridden in subclasses. + + +Managing randomness +------------------- + +Using :mod:`random` in factories allows to "fuzz" a program efficiently. +However, it's sometimes required to *reproduce* a failing test. + +:mod:`factory.fuzzy` uses a separate instance of :class:`random.Random`, +and provides a few helpers for this: + +.. method:: get_random_state() + + Call :meth:`get_random_state` to retrieve the random generator's current + state. + +.. method:: set_random_state(state) + + Use :meth:`set_random_state` to set a custom state into the random generator + (fetched from :meth:`get_random_state` in a previous run, for instance) + +.. method:: reseed_random(seed) + + The :meth:`reseed_random` function allows to load a chosen seed into the random generator. + + +Custom :class:`BaseFuzzyAttribute` subclasses **SHOULD** +use :obj:`factory.fuzzy._random` foras a randomness source; this ensures that +data they generate can be regenerated using the simple state from +:meth:`get_random_state`. -- cgit v1.2.3