sourcerandom for Python
============

True randomness, with minimal fuss.

Alternate random number generator using sources provided by either True Random Number Generator online services (`RANDOM.org <http://random.orgu>`_ and `qrng.anu.edu.au <http://qrng.anu.edu.au>`_), plaintext uint8 files (separated by whitespace) or collections of ints.

sourcerandom's ``SourceRandom`` class extends ``SystemRandom`` class found in default ``random`` package, and only overwrites the ``getrandbits`` method, meaning all of the functionality of ``random`` package is included and unchanged.

sourcerandom obtains bytes from the given source, which are then used to generate random numbers. The bytes are cached for quick access - the amount of cached bytes can be set by the user.

``OnlineRandomnessSource`` enumerator is provided to easily choose between RANDOM.org (``RANDOM_ORG``) and qrng.anu.edu.au (``QRNG_ANU``).

Since the bytes generated by the online services are truly random (please refer to the services for explanation), they can be theoretically used for cryptography instead of OS sources. However, I hold no responsibility for any problems or damages this may cause.

Async/multithread friendly.

Requires Python 3.5.2 or above, and the ``requests`` package.

Installing
----------

::

    pip install sourcerandom

Usage
----------

::

    import sourcerandom

    # From an online source

    RAND_GEN = sourcerandom.SourceRandom(source=sourcerandom.OnlineRandomnessSource.QRNG_ANU) # Initialize the generator - use the same generator to take advantage of caching

    print(RAND_GEN.randint(0, 20)) # Every method from random package is included

    # From file

    RAND_GEN = sourcerandom.SourceRandom(source="path/to/file") # File has to be a plaintext file with integers from range of 0 to 255 separated by whitespace, path is a simple string, relative to working directory. Files are read in cache_size chunks.

    # From collection

    BYTES_LIST = [ 0, 156, 245, 63, 52 ] # Integers from range of 0 to 255 separated by whitespace

    RAND_GEN = sourcerandom.SourceRandom(source=BYTES_LIST)