***********************
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
============

Starting with version 2.5.0, the minimum supported version of Python has been
changed from Python 3.8 to 3.10. All versions prior to 3.10 will no longer
be supported.

Testing for this library has been done using Python 3.10 and 3.12.

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
