# uqrng_direct.client

Helper functions for interacting with QRNG through GRPC client

class uqrng_direct.client.UqrngClient(ip_address: str = 'localhost', port: str = '50051', simulator: bool = False, distribution: int = 2)

  Bases: `object`

  Client which provides access to QCI uqrng server interactions.

  Parameters:

    - ip_address – ip address of grpc server

    - port – port of grpc server

    - stub – the grpc stub that is created in the class

    - channel – the grpc channel

  Note:

    stub used in all functions is a grpc server object

  ip_address: str = 'localhost'
  port: str = '50051'
  simulator: bool = False
  distribution: int = 2
  stub = None
  channel = None
  GetEntropy(bits_of_entropy: int, wait: bool = False, timeout: int = 0) → bytes

    Streams random bits from uqrng device to client as bytes.

    Parameters:

      - bits_of_entropy – the number of bits to stream to the client

      - wait – whether to wait for device to become available

      - timeout – seconds to wait for QRNG device to become available. If is less than or equal to 0 than waits indefinitely.

    Returns:

      bitstring as bytes from the entropy source

    Note:

      Will return as `UNAVAILABLE` with the following message when is in use ‘QRNG currently in use’.

  GetNoise(number_of_samples_requested: int, wait: bool = False, timeout: int = 0) → List[int]

    Random numbers from entropy source from device w/out post-processing.

    Parameters:

      - number_of_samples_requested – amount of random numbers requested

      - wait – whether to wait for device to become available to sample

      - timeout – seconds to wait for QRNG device to become available. If is less than or equal to 0 than waits indefinitely.

    Returns:

      a list of integers in range 0-99,999

    Note:

      Will return as `UNAVAILABLE` with the following message when is in use ‘QRNG currently in use’.

  HealthTest(wait: bool = True) → resultNIST | StatusDict

    Runs all tests from National Institute of Standards and Technology (NIST) Statistical Test Suite for random and pseudo random numbers NIST SP 800-22 version 2.1.1. When run HealthTests are queued until the device becomes idle All tests are run with the default parameters. The NIST tests are run on 10 bitstreams of 1 million samples each. A full list of the tests that are as follows:

    > - [01] Frequency

    > - [02] Block Frequency

    > - [03] Cumulative Sums

    > - [04] Runs

    > - [05] Longest Run of Ones

    > - [06] Rank

    > - [07] Discrete Fourier Transform

    > - [08] Nonperiodic Template Matchings

    > - [09] Overlapping Template Matchings

    > - [10] Universal Statistical

    > - [11] Approximate Entropy

    > - [12] Random Excursions

    > - [13] Random Excursions Variant

    > - [14] Serial

    > - [15] Linear Complexity

    For more information go here.

    Parameters:

      wait – bool indicating whether or not to wait for completion.

    Returns:

      a dictionary of type `utils.resultNIST` if wait for results else .utils.StatusDict

    Note:

      Occasional failures may occur for any given test. Only repeated failures for a given test or many tests failing simulatenously indicate that the device entropy source is malfunctioning.

  FetchHealthTest() → resultNIST

    Fetches most recent health test results from server

    Returns:

      a dict of NIST testing results `resultNIST`

  ScheduleHealthTest(test_interval_mins: int) → StatusDict

    Sets health test interval for running all health tests on the device. Results for scheduled health tests can be retrieved by calling `UqrngClient.FetchHealthTest()`.

    Parameters:

      test_interval_mins – the number of minutes between automated runs for NIST-STS must be a positive integer if set to 0 indicates that the user wishes to not run any further health checks while the device is in operation. This is the default interval that is set on device startup.

    Returns:

      a dict of class `utils.StatusDict` which indicates whether health test was successfully scheduled.

    Note:

      Restarting the device will remove any previous scheduling of health tests set by users prior to powering down, the device will revert to it’s default settings which is to run one health test at start up with no scheduled follow ups.

  SystemStatus() → StatusDict

    Indicates whether the uQRNG device is idle or processing a request.

    Returns:

      a member of `utils.SysStatus` of type `utils.StatusDict`

  SystemInfo() → SystemInfoDict

    Requests current system information.

    Returns:

      a dict of type `utils.SystemInfoDict`

# uqrng_direct.utils

class uqrng_direct.utils.resultNISTdetail

  Bases: `TypedDict`

  Dictionary containing detailed results from NIST-STS returned within `resultNIST` generated by either `UqrngClient.FetchHealthTest()` or `UqrngClient.HealthTest()`.

  Parameters:

    - test_name – a list of names for randomness tests

    - p_value – a list of p_values associated with the tests.

    - proportion – a list of proportion of pass vs fail for test.

    - passed – list of bools with passing tests indicated by True and failing tests returning False.

    - elapsed_time_mins – returns time in fractional mins since last health check was completed.

  test_name: List[str]
  p_value: List[float]
  proportion: List[float]
  passed: List[bool]
  elapsed_time_mins: float

class uqrng_direct.utils.resultNIST

  Bases: `TypedDict`

  Dictionary containing results summary from NIST-STS generated by `UqrngClient.FetchHealthTest()` or `UqrngClient.HealthTest()`.

  Parameters:

    - all_pass – indicates whether all tests in health check passed if any test failed then returns False.

    - tests_detail – detailed test results of form `resultNISTdetail`

    - summary_table – a string formatted to print as a table which summarizes the randomness test detailed results.

  all_pass: bool
  tests_detail: resultNISTdetail
  summary_table: str

class uqrng_direct.utils.SystemInfoDict

  Bases: `TypedDict`

  Dictionary structure for `client.UqrngClient.SystemInfo()`

  Parameters:

    - device_name – the type of device

    - server_version – the current semantic version for the device server

    - test_interval_mins – current number of minutes between consecutive health test for server. For information on how this value is set see `client.UqrngClient.ScheduleHealthTest()`.

  device_type: str
  server_version: str
  test_interval_mins: int

class uqrng_direct.utils.SysStatus

  Bases: `object`

  Status codes for system paired with their descriptions.

  IDLE = {'status_code': 0, 'status_desc': 'IDLE'}
  SAMPLING = {'status_code': 1, 'status_desc': 'SAMPLING'}

class uqrng_direct.utils.StatusDict

  Bases: `TypedDict`

  Status message

  Parameters:

    - status_code – integer code for response

    - status_desc – description for status code

  status_code: int
  status_desc: str

uqrng_direct.utils.message_to_dict(grpc_message) → dict

  Convert a gRPC message to a dictionary.

uqrng_direct.utils.create_summary_table(detail_result: resultNISTdetail) → str

uqrng_direct.utils.check_qrng_busy_error(rpc_err: RpcError)

  Utility function used in waiting loop to determine if error is from busy or another RPC error which can’t be handled

  Parameters:

    rpc_error – RpcError to check

  Returns:

    bool whether error is from QRNG is in use