***********************
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.21.0, the minimum supported version of Python has been
changed from Python 3.10 to 3.12. All versions prior to 3.12 will no longer
be supported.

Testing for this library has been done using Python 3.12 and preliminary testing
has been started for Python 3.13.

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.

Starting with version 2.21.0, experimental support has been added for MariaDB
versions 11.8 and 12.0. Test runs have been run successfully against a MariaDB
Server 11.8 and 12.0 running on Debian 13. Versions prior to 11.8 have not and
will not be tested.

If you are planning to use MariaDB instead of MySQL, it is recommended that
version 11.8 is used over 12 due to the former being on a stable release train
while the latter is on a rolling release train. Rolling releases can introduce
regressions or breaking changes that are generally avoided with stable releases.

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

Versioning
==========

This project does its best to follow `Semantic Versioning 2.0.0`_ starting with
version 2.0 of the library. There have been some semantic versioning errors made
since the initial release of version 2.0.

.. _Semantic Versioning 2.0.0: https://semver.org/spec/v2.0.0.html

Contributing
============

If you would like to contribute to this project, please refer to the
`Contributing Guidelines`_ file in this repository.

AI Generated Code
-----------------

Please note that this project does not accept pull requests or bugfixes that
include code that has been partially or wholly generated using AI.

.. _Contributing Guidelines: https://github.com/questionlp/wwdtm/blob/main/CONTRIBUTING.md

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

The Code of Conduct for this project is adapted from the Contributor Covenant,
version 3.0, permanently available at: https://www.contributor-covenant.org/version/3/0/.

The adapted version with instructions on how to report possible violations are
available in the `Code of Conduct`_ file in this repository.

.. _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
