Metadata-Version: 2.1
Name: coinflip
Version: 0.1.1
Summary: Randomness testing for humans
Home-page: https://github.com/Honno/coinflip
License: BSD-3-Clause
Keywords: rng,nist,rngtest,randomness,randomness-testing
Author: Matthew Barber
Author-email: quitesimplymatt@gmail.com
Requires-Python: >=3.7,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Provides-Extra: docs
Provides-Extra: refimpl
Provides-Extra: test
Requires-Dist: Jinja2 (>=2.11.2,<3.0.0)
Requires-Dist: altair (>=4.1.0,<5.0.0)
Requires-Dist: click (>=7.1.2,<8.0.0)
Requires-Dist: hypothesis (>=5.41.2,<6.0.0); extra == "test"
Requires-Dist: more-itertools (>=8.6.0,<9.0.0); extra == "refimpl"
Requires-Dist: numpy (>=1.19.4,<2.0.0)
Requires-Dist: pandas (>=1.1.4,<2.0.0)
Requires-Dist: pytest (>=6.1.2,<7.0.0); extra == "test"
Requires-Dist: pytest-timeout (>=1.4.2,<2.0.0); extra == "test"
Requires-Dist: rich (>=9.2.0,<10.0.0)
Requires-Dist: scipy (>=1.5.4,<2.0.0)
Requires-Dist: sphinx (>=3,<4); extra == "docs"
Requires-Dist: sphinx-click (>=2.5.0,<3.0.0); extra == "docs"
Requires-Dist: sphinx-rtd-theme (>=0.5.0,<0.6.0); extra == "docs"
Requires-Dist: tox (>=3.20.1,<4.0.0); extra == "test"
Requires-Dist: typing-extensions (>=3.7.4,<4.0.0)
Project-URL: Documentation, https://coinflip.readthedocs.io/
Project-URL: Repository, https://github.com/Honno/coinflip
Description-Content-Type: text/x-rst

========
coinflip
========

Randomness testing for humans

|build| |docs| |license| |version| |supported-versions| |hypothesis| |black|

*coinflip* aims to implement the tests recommended by `NIST SP800-22
<https://csrc.nist.gov/publications/detail/sp/800-22/rev-1a/final>`_
to check random number generators for randomness.  A user-friendly command-line
interface provided allows you to ``run`` the tests on your data, and
subsequently ``report`` on the results by generating informational HTML
documents.

``coinflip.randtests`` acts as the `public API
<https://coinflip.readthedocs.io/en/latest/reference/randtests/index.html>`_
for `notebook users <https://jupyter.org/index.html>`_ and developers to use
the randomness tests directly. The tests are implemented as general solutions,
meaning they accept basically any sequence with two distinct elements!

.. image:: https://raw.githubusercontent.com/Honno/coinflip/report/.video_files/thumb/thumb_thumb.png
   :target: http://www.youtube.com/watch?v=0xrWG3Ki9Z8

Setup
=====

You can get the latest release of coinflip from PyPI.

.. code-block:: console

    $ pip install coinflip

Alternatively you can get the (unstable) development version straight from
GitHub.

.. code-block:: console

    $ pip install git+https://github.com/Honno/coinflip

If that means nothing to you, no fret! Please continue reading the instructions
below.

Install Python 3.7+
-------------------

Cross-platform installation instructions for Python  are available at
`realpython.com/installing-python/ <https://realpython.com/installing-python/>`_.

Note ``coinflip`` only works on **Python 3.7 or above**. Make sure you have
Python 3.7 (or higher) by checking the version of your installation:

.. code-block:: console

    $ python --version
    Python 3.7.X

Clone repository
----------------

You can clone the source code via `Git
<https://www.freecodecamp.org/news/what-is-git-and-how-to-use-it-c341b049ae61/>`_:

.. code-block:: console

    $ git clone https://github.com/Honno/coinflip


Install coinflip
----------------

Enter the directory *coinflip* is downloaded to:

.. code-block:: console

   $ cd coinflip

You can install *coinflip* via the ``pip`` module:

.. code-block:: console

    $ pip install -e .

`pip <https://realpython.com/what-is-pip/>`_ is the standard package manager for
Python, which should of installed automatically when installing Python 3.7+.

Trial run
---------

Try running the randomness tests on an automatically generated binary sequence:

.. code-block:: console

    $ coinflip example-run

If the command ``coinflip`` is "not found", you may need to add your local
binaries folder to your shell's path. For example, in bash you would do the
following:

.. code-block:: console

    $ echo "export PATH=~/.local/bin:$PATH" >> ~/.bash_profile
    $ source ~/.bash_profile

In the worst case, you can execute commands via ``python -m``:

.. code-block:: console

    $ python -m coinflip example-run


Quick start
===========

Randomness tests can be ran over your RNG output via the ``run`` command.

.. code-block:: console

    $ coinflip run DATA OUT
    ...

``DATA`` is the path to newline-delimited text file that contains a binary
sequence. An example file to use is available on `my gist
<https://gist.github.com/Honno/dd6f3527e588428fa17a999042e3c6e8>`_.
Alternatively, raw binary files can be read as bitstreams via the ``--binary``
flag

``OUT`` is the path where you want the results to be saved. The results will be
saved as a `pickle <https://docs.python.org/3/library/pickle.html>`_-serialised
file, which can be viewed again via the ``read`` command. Additionally you can
generate informational HTML reports from the results via the ``report`` command,
but note that the reports are currently very lacking.

Output should comprise of the sequence parsed from ``DATA``, test-specific result
summaries, and a final overall summary table.

.. |build| image:: https://img.shields.io/github/workflow/status/Honno/coinflip/Test
    :target: https://github.com/Honno/coinflip/actions?query=workflow%3ATest
    :alt: GitHub Workflow Status

.. |docs| image:: https://readthedocs.org/projects/coinflip/badge/?style=flat
    :target: https://readthedocs.org/projects/coinflip
    :alt: Documentation Status

.. |hypothesis| image:: https://img.shields.io/badge/hypothesis-tested-brightgreen.svg
   :alt: Tested with Hypothesis
   :target: https://hypothesis.readthedocs.io

.. |version| image:: https://img.shields.io/pypi/v/coinflip.svg
    :alt: PyPI package latest release
    :target: https://pypi.org/project/coinflip

.. |supported-versions| image:: https://img.shields.io/badge/python-3.7%2B-informational
    :alt: Supported versions
    :target: https://pypi.org/project/coinflip

.. |supported-implementations| image:: https://img.shields.io/pypi/implementation/coinflip.svg
    :alt: Supported implementations
    :target: https://pypi.org/project/coinflip

.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
    :alt: Code style
    :target: https://github.com/psf/black

.. |license| image:: https://img.shields.io/badge/license-BSD-blueviolet
    :alt: License
    :target: https://github.com/Honno/coinflip/blob/master/LICENSE.md

