***********************
Wait Wait Stats Library
***********************

Overview
========

This project provides a Python library that provides an interface to
retrieve data from a copy of the `Wait Wait Stats Database`_.

If you are in need of a pre-built package to use to build applications, the
library is available at `PyPI`_.

Requirements
============

This version of the library requires a minimum Python version of 3.8 and
has been tested thoroughly with Python 3.8 and 3.10.

In addition to the Python version requirement, the library depends on a copy
of the `Wait Wait Stats Database`_ running on a MySQL Server (or a distribution
of MySQL Server like Percona) running version 8.0 or higher.

Running Tests
=============

Included in this repository are tests that are written for use with ``pytest``.
To run the tests, simply run: ``pytest`` from the root of the repository.

A performance testing script is also included in the repository named,
``perf_test.py`` that tests the core class methods. This script can be used
to create a performance baseline and also used to track changes in performance
between code changes or configuration changes.

Documentation
=============

This project uses `reStructuredText`_ located in docstrings and individual
files for its documentation and makes use of `Sphinx`_ to build an HTML
(and other formats supported by Sphinx) version of documents. To build the
documentation for this project, use ``venv``, ``virtualenv`` or a similar tool
of your choice to create a virtual environment under ``docs/`` and install the
required packages in ``docs/requirements.txt``, including Sphinx and the
`Flask`_ theme.

The documentation style guide closely follows the one documented in the
`Python Developer's Guide`_.

Once the required packages are installed, an HTML version of the documentation
can be generated by running:

.. code-block:: shell

    make html

An online version of the documentation is also available at `docs.wwdt.me`_

Building
========

After tests have been successfully run, any and all documentation updates have
been made, a release wheel can then be created for distribution. To create a
wheel, run the following command with the virtualenv activated.

.. code-block:: bash

    python -m build

Known Issues
============

For documentation on known issues with this project, check out the
`Known Issues`_ documentation on `docs.wwdt.me`_.


.. _PyPI: https://pypi.org/project/wwdtm/
.. _reStructuredText: https://docutils.sourceforge.io/rst.html
.. _Sphinx: https://www.sphinx-doc.org/en/master/
.. _Flask: https://flask.palletsprojects.com/
.. _Python Developer's Guide: https://devguide.python.org/documenting/#style-guide
.. _docs.wwdt.me: https://docs.wwdt.me/
.. _Known Issues: https://docs.wwdt.me/known_issues.html

Code of Conduct
===============

This projects follows version 2.1 of the `Contributor Covenant's`_ Code of
Conduct. A copy of the `Code of Conduct`_ document is included in this
repository.

.. _Contributor Covenant's: https://www.contributor-covenant.org/
.. _Code of Conduct: https://github.com/questionlp/wwdtm/blob/main/CODE_OF_CONDUCT.md

License
=======

This library is licensed under the terms of the `Apache License 2.0`_.

.. _Wait Wait Stats Database: https://github.com/questionlp/wwdtm_database
.. _Apache License 2.0: https://github.com/questionlp/wwdtm/blob/main/LICENSE
