Repository: joke2k/faker

Issue:
Access to the Generator.random
It would be nice if one could gain access to the Generator.random variable so that one could save/set the state.  I realize I can pass in the seed, but one currently has no way of gathering what the seed/state is if using the automatically generated seed.  I don't want to use a fixed seed, but I do want to log/print the seed used _if_ the tests fail.

That is, I'd like to be able to do something like:  `faker.generator.getstate()` (which gets the random state w/o exposing random) or `faker.generator.random.getstate()` (which gives access to the random variable)

For now, the workaround appears to be to create a Faker object with your own Generator.

Discussion:

Patch:
diff --git a/README.rst b/README.rst
index 4dc04a86..0941dbda 100644
--- a/README.rst
+++ b/README.rst
@@ -263,13 +263,26 @@ How to use with factory-boy
         title = factory.LazyAttribute(lambda x: faker.sentence(nb_words=4))
         author_name = factory.LazyAttribute(lambda x: faker.name())
 
+Accessing the `random` instance
+-------------------------------
+
+The ``.random`` property on the generator returns the instance of ``random.Random``
+used to generate the values:
+
+__ code:: python
+
+    from faker import Faker
+    fake = Faker()
+    fake.random
+    fake.random.getstate()
+
 Seeding the Generator
 ---------------------
 
 When using Faker for unit testing, you will often want to generate the same
-data set. The generator offers a  ``seed()`` method, which seeds the random
-number generator. Calling the same script twice with the same seed produces the
-same results.
+data set. For convenience, the generator also provide a ``seed()`` method, which
+seeds the random number generator. Calling the same script twice with the same
+seed produces the same results.
 
 .. code:: python
 
@@ -280,8 +293,20 @@ same results.
     print fake.name()
     > Margaret Boehm
 
+The code above is equivalent to the following:
+
+.. code:: python
+
+    from faker import Faker
+    fake = Faker()
+    faker.random.seed(4321)
+
+    print fake.name()
+    > Margaret Boehm
+
 Tests
 -----
+
 Installing dependencies:
 
 .. code:: bash
diff --git a/docs/index.rst b/docs/index.rst
index 601d474d..7e96203c 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -264,13 +264,26 @@ How to use with factory-boy
         title = factory.LazyAttribute(lambda x: faker.sentence(nb_words=4))
         author_name = factory.LazyAttribute(lambda x: faker.name())
 
+Accessing the `random` instance
+-------------------------------
+
+The ``.random`` property on the generator returns the instance of ``random.Random``
+used to generate the values:
+
+__ code:: python
+
+    from faker import Faker
+    fake = Faker()
+    fake.random
+    fake.random.getstate()
+
 Seeding the Generator
 ---------------------
 
 When using Faker for unit testing, you will often want to generate the same
-data set. The generator offers a  ``seed()`` method, which seeds the random
-number generator. Calling the same script twice with the same seed produces the
-same results.
+data set. For convenience, the generator also provide a ``seed()`` method, which
+seeds the random number generator. Calling the same script twice with the same
+seed produces the same results.
 
 .. code:: python
 
@@ -281,6 +294,17 @@ same results.
     print fake.name()
     > Margaret Boehm
 
+The code above is equivalent to the following:
+
+.. code:: python
+
+    from faker import Faker
+    fake = Faker()
+    faker.random.seed(4321)
+
+    print fake.name()
+    > Margaret Boehm
+
 Tests
 -----
 
diff --git a/faker/generator.py b/faker/generator.py
index 95dfac2a..74034cb4 100644
--- a/faker/generator.py
+++ b/faker/generator.py
@@ -50,6 +50,10 @@ class Generator(object):
         """Returns added providers."""
         return self.providers
 
+    @property
+    def random(self):
+        return random
+
     def seed(self, seed=None):
         """Calls random.seed"""
         random.seed(seed)


Test patch:
diff --git a/faker/tests/__init__.py b/faker/tests/__init__.py
index 6502a448..5dc22528 100644
--- a/faker/tests/__init__.py
+++ b/faker/tests/__init__.py
@@ -518,6 +518,12 @@ class GeneratorTestCase(unittest.TestCase):
     def setUp(self):
         self.generator = Generator()
 
+    @patch('random.getstate')
+    def test_get_random(self, mock_system_random):
+        random_instance = self.generator.random
+        random_instance.getstate()
+        self.assertFalse(mock_system_random.called)
+
     @patch('random.seed')
     def test_random_seed_doesnt_seed_system_random(self, mock_system_random):
         self.generator.seed(0)