wwdtm 3.1.0

Library used to query data from copy of Wait Wait Stats Database.

Note: The authoritative version of this repository now resides on Codeberg as wwdtm and mirrors changes to GitHub. Going forward, issues and pull requests should be created on Codeberg rather than GitHub.

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.

Starting with version 3.0.0, the minimum required version of the Wat Wait Stats Database is 4.7.0, which includes all panelist decimal score-related columns.

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:

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.

python -m build

Known Issues

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

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.

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.

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.

License

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

Although this library interfaces with MySQL Connector/Python, licensed under version 2 of the GNU General Public License (GPLv2) and is also subject to the terms included in Universal FOSS Exception, version 1.0. The exception permits this library to be licensed under an OSI-approved or a license categorized as “free” by the Free Software Foundation (FSF), such as Apache License 2.0.