=============
RandomSources
=============

RandomSources is a Python module, providing multiple implementations of
Python's random-number generator interface backed by remote random-number
sources. It provides simple, drop-in style replacements for Random with data
provided by the ANU Quantum Random Numbers server (generated by measuring
quantum fluctuations of the vacuum) and by random.org (generated by measuring
atmospheric noise). Typical usage looks like this::

    >>> import randomSources
    
    >>> qRandom = randomSources.QuantumRandom()
    >>> print qRandom.random()
    0.799872387678
    >>> print qRandom.randint(1, 20)
    4
    
    >>> randomDotOrg = randomSources.RandomDotOrg()
    >>> randomDotOrg.checkBitQuota()
    990178
    >>> print randomDotOrg.random()
    0.951470705142
    >>> print randomDotOrg.random(4)
    [0.5996488097316547, 0.40146785806967766, 0.9956706001515375, 0.345638811037305]
    >>> randomDotOrg.checkBitQuota()
    989910
    >>> print randomDotOrg.randint(1, 20)
    1
    >>> print randomDotOrg.randint(1, 20, 12)
    [6, 10, 13, 20, 3, 14, 5, 3, 10, 18, 20, 14]
    >>> randomDotOrg.checkBitQuota()
    989780

Note that random.org provides a bit quota limited per IP per 24 hours; many
functions therefore provide an optional final parameter 'n' to simulate
multiple calls, allowing the system to merge some smaller requests in order to
minimize bit waste. Towards the same goal, the RandomDotOrg class prefers to
subdivide fetches, sending multiple smaller requests when it can prevent waste.

On the other hand, the ANU Quantum Random Numbers server has no bit limit;
therefore, the QuantumRandom class fetches 16 KB at a time to serve small
requests, minimizing requests to the server. Larger requests are fetched
dynamically.

As of version 0.1.0, these objects are *not* thread-safe.

Credits
=======

Much of the code of this module is derived directly from the Python 2.7 source
for the Random class and its subclasses, rendering this a derivative work.
Thanks to the Python Software Foundation and its BDFL, Guido van Rossum.

In addition, significant inspiration (and some direct code) was taken from the
quantumrandom (http://github.com/lmacken/quantumrandom) and randomdotorg
(http://code.google.com/p/randomdotorg/) modules, especially as basic reference
for the APIs of their respective random-number sources. Thanks and attribution
are therefore due to Luke Macken (author of quantumrandom) and Clovis Fabricio
(author of randomdotorg).

License
=======

This module is licensed under the GNU GPL version 3, as a derivative work of
the randomdotorg module. This is confirmed compatible with both the Python
Software Foundation License, covering Python 2.7, and the MIT License, covering
the quantumrandom module.

If permission is granted by Clovis Fabricio, this module will be relicensed
under the Python Software Foundation License, or, if that is not acceptable,
under the GNU LGPL version 3.
