Python module for Random.org JSON API

## Project description

PyRando

=======

PyRando is a Python 3 module for interacting with the [random.org](https://random.org) JSON API. PyRando can generate random values using basic methods as well as digitally signed random values using the signed methods.

PyRando is compatible with Python 3.6+.

Installation

============

To install pyrando, use `pip3`:

$ pip3 install pyrando

Getting Started

===============

To interact with random.org, you will first need to get an api key. Go to [api.random.org](https://api.random.org/json-rpc/1/) and click on *Get a Beta Key*. Once you have an API key, using PyRando is quite straightforward.

For example:

>>> from pyrando import PyRando

>>> pr = PyRando('YOUR_API_KEY')

>>> pr.integers(5, 0, 10)

[0, 7, 10, 3, 5]

Basic Methods

=============

### Integers

The `integers` method generates true random integers within a user-defined range. Integer requests take up to four positional arguments:

* `n` - How many random integers you need. Must be within the [1,1e4] range

* `min` - The lower boundary for the range. Must be within the [-1e9,1e9] range

* `max` - The upper boundary for the range. Must be within the [-1e9,1e9] range

* `base` (optional) - If not provided, the default `base` is set to 10. Allowed values for base are 2, 8, 10, and 16

Examples:

pr.integers(10, 1, 6)

pr.integers(10, 1, 100, 2)

### Decimals

The `decimals` method generates true random decimal fractions from a uniform distribution across the [0,1] interval with a user-defined number of decimal places. Decimal requests take three positional arguments:

* `n` - How many random decimal fractions you need. Must be within the [1,1e4] range

* `decimalPlaces` - The number of decimal places to use. Must be within the [1,20] range

Example:

pr.decimals(10, 8)

### Gaussians

The `gaussians` method generates true random numbers from a Gaussian distribution. Integer requests take four positional arguments:

* `n` - How many random numbers you need

* `mean` - The distributions mean. Must be within the [1,1e4] range

* `standardDeviation` - The distributions standard deviation. Must be with the [-1e6,1e6] range

* `significantDigits` - The number of significant digits to use. Must be within the [2,20] range

Example:

pr.gaussians(4, 0.0, 1.0, 8)

### Strings

The `strings` method generates true random strings. String requests take three positional arguments:

* `n` - How many random strings you need. Must be within the [1,1e4] range

* `length` - The length of each string. Must bbe within the [1,20] range. All strings will be of the same length

* `characters` - A string that contains the set of characters that are allowed to occur in the random stings. The maximum number of characters is 80

Example:

pr.strings(10, 20, 'abcdefghijklmnopqrstuvwxyz')

### UUIDs

The `uuids` method generates version 4 true random UUIDs. UUID requests take a single positional argument:

* `n` - How many random UUIDs you need. Must be within the [1,1e3] range

Example:

pr.uuids(1)

### Blobs

The `blobs` method generates BLOBs containing true random data. Blob requests take up to three positional argument:

* `n` - How many random blobs you need. Must be within the [1,100] range

* `size` - The size of each blob, measured in bits. Must be within the [1,1048576] range and divisible by 8. The total size of all requested blobs much not exceed 1,048,576 bits (128KiB)

* `format` - Specifies the format in which the blobs will be returned. Values allowed are `base64` and `hex`. If not value is provided, the default value of `base64` is used.

Examples:

pr.blobs(1, 2048)

pr.blobs(1, 1024, 'hex')

### Usage

The `usage` method returns information related to the usage of a given API.

Example:

pr.usage()

Signed Methods

==============

Usage of signed methods is quite similar to that of basic methods. For example, to use signed methods you could input the commands as follows:

>>> pr.signed_integers(10, 1, 6)

>>> pr.signed_decimals(10, 8)

>>> pr.signed_gaussians(4, 0.0, 1.0, 8)

>>> pr.signed_strings(10, 20, 'abcdefghijklmnopqrstuvwxyz')

>>> pr.signed_uuids(1)

>>> pr.signed_blobs(1, 2048)

exi

The difference between basic methods and signed methods is the response. Instead of just a list with the random values, signed methods return a dictionary with values for the following keys `data`, `random`, and `signature`. The `random` and `signature` values can be used to authenticate signed values.

To verify a response, use the `verify_signature` method. The method take the `random` and `signature` values as arguments and responds with a boolean value of either `True` or `False`. For example:

>>> signed_ints = pr.signed_integers(10, 1, 6)

>>> pr.verify_signature(signed_ints['random'], signed_ints['signature'])

True

=======

PyRando is a Python 3 module for interacting with the [random.org](https://random.org) JSON API. PyRando can generate random values using basic methods as well as digitally signed random values using the signed methods.

PyRando is compatible with Python 3.6+.

Installation

============

To install pyrando, use `pip3`:

$ pip3 install pyrando

Getting Started

===============

To interact with random.org, you will first need to get an api key. Go to [api.random.org](https://api.random.org/json-rpc/1/) and click on *Get a Beta Key*. Once you have an API key, using PyRando is quite straightforward.

For example:

>>> from pyrando import PyRando

>>> pr = PyRando('YOUR_API_KEY')

>>> pr.integers(5, 0, 10)

[0, 7, 10, 3, 5]

Basic Methods

=============

### Integers

The `integers` method generates true random integers within a user-defined range. Integer requests take up to four positional arguments:

* `n` - How many random integers you need. Must be within the [1,1e4] range

* `min` - The lower boundary for the range. Must be within the [-1e9,1e9] range

* `max` - The upper boundary for the range. Must be within the [-1e9,1e9] range

* `base` (optional) - If not provided, the default `base` is set to 10. Allowed values for base are 2, 8, 10, and 16

Examples:

pr.integers(10, 1, 6)

pr.integers(10, 1, 100, 2)

### Decimals

The `decimals` method generates true random decimal fractions from a uniform distribution across the [0,1] interval with a user-defined number of decimal places. Decimal requests take three positional arguments:

* `n` - How many random decimal fractions you need. Must be within the [1,1e4] range

* `decimalPlaces` - The number of decimal places to use. Must be within the [1,20] range

Example:

pr.decimals(10, 8)

### Gaussians

The `gaussians` method generates true random numbers from a Gaussian distribution. Integer requests take four positional arguments:

* `n` - How many random numbers you need

* `mean` - The distributions mean. Must be within the [1,1e4] range

* `standardDeviation` - The distributions standard deviation. Must be with the [-1e6,1e6] range

* `significantDigits` - The number of significant digits to use. Must be within the [2,20] range

Example:

pr.gaussians(4, 0.0, 1.0, 8)

### Strings

The `strings` method generates true random strings. String requests take three positional arguments:

* `n` - How many random strings you need. Must be within the [1,1e4] range

* `length` - The length of each string. Must bbe within the [1,20] range. All strings will be of the same length

* `characters` - A string that contains the set of characters that are allowed to occur in the random stings. The maximum number of characters is 80

Example:

pr.strings(10, 20, 'abcdefghijklmnopqrstuvwxyz')

### UUIDs

The `uuids` method generates version 4 true random UUIDs. UUID requests take a single positional argument:

* `n` - How many random UUIDs you need. Must be within the [1,1e3] range

Example:

pr.uuids(1)

### Blobs

The `blobs` method generates BLOBs containing true random data. Blob requests take up to three positional argument:

* `n` - How many random blobs you need. Must be within the [1,100] range

* `size` - The size of each blob, measured in bits. Must be within the [1,1048576] range and divisible by 8. The total size of all requested blobs much not exceed 1,048,576 bits (128KiB)

* `format` - Specifies the format in which the blobs will be returned. Values allowed are `base64` and `hex`. If not value is provided, the default value of `base64` is used.

Examples:

pr.blobs(1, 2048)

pr.blobs(1, 1024, 'hex')

### Usage

The `usage` method returns information related to the usage of a given API.

Example:

pr.usage()

Signed Methods

==============

Usage of signed methods is quite similar to that of basic methods. For example, to use signed methods you could input the commands as follows:

>>> pr.signed_integers(10, 1, 6)

>>> pr.signed_decimals(10, 8)

>>> pr.signed_gaussians(4, 0.0, 1.0, 8)

>>> pr.signed_strings(10, 20, 'abcdefghijklmnopqrstuvwxyz')

>>> pr.signed_uuids(1)

>>> pr.signed_blobs(1, 2048)

exi

The difference between basic methods and signed methods is the response. Instead of just a list with the random values, signed methods return a dictionary with values for the following keys `data`, `random`, and `signature`. The `random` and `signature` values can be used to authenticate signed values.

To verify a response, use the `verify_signature` method. The method take the `random` and `signature` values as arguments and responds with a boolean value of either `True` or `False`. For example:

>>> signed_ints = pr.signed_integers(10, 1, 6)

>>> pr.verify_signature(signed_ints['random'], signed_ints['signature'])

True

## Project details

## Release history Release notifications

## Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help | File type | Python version | Upload date |
---|---|---|---|

pyrando-0.3.0.tar.gz (4.9 kB) Copy SHA256 hash SHA256 | Source | None |