Toucan tournament MVP calculator

This is a coding test resolution provided by Roberto Pastor Muela for a technical practical. This technical practical has been approached by the creation of a Python library named toucan-mvp-calculator, which can easily be extended and reused for similar tournaments.

Simple example

The following example shows how to use the toucan-mvp-calculator to process a directory in which the match files for the Toucan tournament have been stored:

import os

from toucan.mvp.calculator import ToucanTournament

# Provide the path to your files directory...
# We will assume in this example that it is stored in an
# environment variable called MY_TOUCAN_TOURNAMENT_FILES_DIRECTORY
DATA_PATH = os.environ.get("MY_TOUCAN_TOURNAMENT_FILES_DIRECTORY")

# Create the tournament
tournament = ToucanTournament("ReferenceTournament")

# Process the tournament files
tournament.process_tournament(DATA_PATH)

# Figure out who is the MVP!
print("And the MVP is...\n")
print(tournament.mvp)

How to install toucan-mvp-calculator

1. Start by cloning the repository.

2. Create a fresh-clean Python environment and activate it:

   # Create a virtual environment
   python -m venv .venv
   
   # Activate it in a POSIX system
   source .venv/bin/activate
   
   # Activate it in Windows CMD environment
   .venv\Scripts\activate.bat
   
   # Activate it in Windows Powershell
   .venv\Scripts\Activate.ps1

3. Make sure you have the latest required build system and tools:

   python -m pip install -U pip

4. Install the project in editable mode from the root of the uncompressed directory:

   python -m pip install -e .

5. EXTRA: you can also install the test and documentation build requirements by running instead the following:

   python -m pip install -e .[tests,doc]

How to run the tests

This project takes advantage of pytest. This tool allows to automate the run of unit tests on Python. Also, other additional tools are used for ensuring a proper code coverage (i.e. pytest-cov).

If you want to run the tests, just do as follows:

# Install the library with tests requirements
pip install -e .[tests]

# Launch the test suite
pytest

Currently, the status of the code coverage is as follows:

---------- coverage: platform win32, python 3.10.4-final-0 ------------
Name                                      Stmts   Miss  Cover   Missing
-----------------------------------------------------------------------
src\toucan\mvp\calculator\__init__.py         5      0   100%
src\toucan\mvp\calculator\discipline.py      19      0   100%
src\toucan\mvp\calculator\errors.py           3      0   100%
src\toucan\mvp\calculator\players.py         49      0   100%
src\toucan\mvp\calculator\tournament.py      62      0   100%
-----------------------------------------------------------------------
TOTAL                                       138      0   100%

Building documentation

To build the documentation locally you need to follow these steps at the root directory of the repository:

# Install the library with doc requirements
pip install -e .[doc]

# Navigate to the documentation directory
cd doc

# On Linux, run
make html

# On Windows, run
.\make.bat html

After the build completes the HTML documentation locates itself in the _builds/html directory and you can load the index.html into a web browser. To clean the documentation you can execute this command:

# On Linux, run
make clean

# On Windows, run
.\make.bat clean

Code style

Code style checks use pre-commit. Install this tool and activate it executing the following commands:

python -m pip install pre-commit
pre-commit install

Then, you can make used of the available configuration file .pre-commit-config.yml, which will be automatically detected by pre-commit:

pre-commit run --all-files --show-diff-on-failure

Its current status is as follows:

black....................................................................Passed
isort....................................................................Passed
flake8...................................................................Passed
codespell................................................................Passed
pydocstyle...............................................................Passed