Metadata-Version: 2.1
Name: pytest-rng
Version: 1.0.0
Summary: Fixtures for seeding tests and making randomness reproducible
Home-page: https://www.nengo.ai/pytest-rng
Author: Applied Brain Research
Author-email: info@appliedbrainresearch.com
License: MIT license
Description: **********
        pytest-rng
        **********
        
        ``pytest-rng`` provides fixtures for
        ensuring "randomness" in your tests is reproducible
        from one run to the next.
        It also allows the seed for all tests to be changed if requested,
        to help ensure that test successes are not dependent on
        particular random number seeds.
        
        - Use the ``rng`` fixture to get a pre-seeded random number generator (RNG)
          that exposes NumPy's `~numpy.random.mtrand.RandomState` interface.
        
        - Use the ``seed`` fixture to get an integer seed
          that can be used to initialize your own RNG.
        
        The following example prints the same four random numbers
        every time the test is run.
        
        .. code-block:: python
        
           import numpy as np
        
           def test_rectification(rng, seed):
               print(rng.uniform(-1, 1, size=3))
               print(seed)
        
        To use these fixtures, install with
        
        .. code-block:: bash
        
           pip install pytest-rng
        
        Once installed, you can use these fixtures like any other fixture:
        add ``rng`` or ``seed`` to the arguments of a test function or class.
        
        Seed generation
        ===============
        
        For the ``seed`` fixture, we generate a seed by doing the following:
        
        1. Concatenate the test's ``nodeid`` and a ``salt`` value, if provided.
        2. Hash that string to yield an integer seed.
        
        For the ``rng`` fixture, we also add the string ``"rng"`` to the ``salt``
        value before generating the seed as above.
        The seed is used to instantiate a `~numpy.random.mtrand.RandomState`,
        which is returned.
        
        .. note:: We add ``"rng"`` to the salt to ensure that random numbers
                  are different when using the ``rng`` fixture
                  and when manually instantiating a ``RandomState``
                  with the ``seed`` fixture.
        
        salt
        ====
        
        ``salt`` is a string that is added to the test's ``nodeid``
        in order to change the seed for all tests.
        It is advantageous to change seeds regularly to ensure that
        your test suite is robust to different seeds.
        
        The salt value can be specified in a configuration file
        like ``setup.cfg`` or ``pytest.ini``.
        
        .. code-block:: ini
        
           [tool:pytest]
        
           rng_salt = v0.3.0
        
        The salt value can also be specified through the command line.
        
        .. code-block:: bash
        
           pytest --rng-salt "v0.4.0"
        
        The salt value passed through the command line takes precedence
        over the value set in the configuration file
        so that you can change seeds on-the-fly.
        
        ~~~~~
        
        See the full
        `documentation <https://www.nengo.ai/pytest-rng>`__
        for more details.
        
        ***************
        Release History
        ***************
        
        .. Changelog entries should follow this format:
        
           version (release date)
           ======================
        
           **section**
        
           - One-line description of change (link to Github issue/PR)
        
        .. Changes should be organized in one of several sections:
        
           - Added
           - Changed
           - Deprecated
           - Removed
           - Fixed
        
        1.0.0 (August 8, 2019)
        ======================
        
        Initial release of ``pytest-rng``!
        Thanks to all of the contributors for making this possible!
        
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Pytest
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Requires-Python: >=3.5
Provides-Extra: all
Provides-Extra: docs
Provides-Extra: tests
Provides-Extra: optional
