Draft: Add modern Python tools

[tiliv]

Rationale:
I have been waiting for 10 years for Ren'py to support python 3. We shall show no weakness. We will assume everything is python 3 & renpy 8.

This PR was not interesting before renpy 8, because the system was based on ancient python. Now we're on Python 3.9 and life is pretty again.

Misc:
This version of the template is hardcoding renpy-8.0.1-sdk in the pyproject.toml, which I'd like to avoid, if it becomes practical. Compatibility is not especially concerning, so hardcoding is unreasonable except for the mechanics of having no env variables in pyproject.toml. Not sure if an .env file is fixing this or not. Pytest is very hard to modify the path for. My initial attempt was to use importlib to read the sdk named in our .renpy-sdk hint, and nothing to do with sys.path seems to have an effect.

Poetry

https://python-poetry.org/

Modern python project management with virtualenv support and a dependency lock file.

# macOS
brew install poetry
# Windows
(Invoke-WebRequest -Uri https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py -UseBasicParsing).Content | python -

When the files in the PR are present, use poetry install to install optional development support packages needed for pytest and coverage.

When working in your project directory from the command line, always be sure to activate a shell for it:

poetry shell  # this is the equivalent of `source .venv/bin/activate` and similar tricks
python
>>> # you're in the isolated python shell that poetry installed!

If you enjoy npm, yarn, and similar tools, you can use poetry similar to npx:

poetry run python

If you want custom commands, they have to launch a function in a python module:

# pyproject.toml
[tool.poetry.scripts]
cli = "cli:root"
my-cmd = "my_python_module:a_function_name"

Click

https://click.palletsprojects.com/en/8.1.x/quickstart/#screencast-and-examples

Click is a simple framework for declaring a fully automatic command line interface out of a python file. The default cli.py file has been added to pyproject.toml as a Poetry script, so that you have an obvious place to make new commands.

The default cli.py features are not strictly required--the developer can always freely run the tools that the cli invokes--but this provides a unified location for such commands, and self-documents how you can interact with the installed tools. Better yet, if you want to swap out or add tools, all you have to do is edit cli.py. The command names are not special, emphasized by their generic names instead of using the literal tool names.

You can run cli.py directly, or as a poetry script with poetry run cli. Poetry's pyproject.toml is already configured to know that the script "cli" points to cli.py, and the Click help takes over from there, allowing all the normal command line arguments:

# with poetry
poetry run cli test game/test_something_specific.py

# with python, requires that you're activated your venv, e.g., `poetry shell`
python -m cli test game/test_something_specific.py
python cli.py test game/test_something_specific.py

# with ./cli helper shell script
./cli test game/test_something_specific.py

All of these funnel you to running cli.py in exactly the same way, so the arguments are the same for any approach.

If you prefer to launch tasks with your editor UI, you can ask it to run with any of these strategies and it'll work just fine.

Note that the default commands are not adding or modifying any arguments to the underlying tool, so you'll get exactly the same behavior as configured in your pyproject.toml file, which controls default arguments to those tools.

If you want to use the cli to pass additional new arguments, these commands have support for adding a -- between the command and your override arguments.

Pytest

https://docs.pytest.org/en/latest/contents.html

Pytest provides a simple runner called pytest. This is also the name of an importable module in python code that enables sending data fixtures, marking tests for multiple runs, and helps with setup/teardown tasks.

Tests with pytest are just files and functions or classes that adhere to naming patterns. Files and function should start with test_* and classes should begin with Test*. Changing these is possible in pyproject.toml

Test files can be created anywhere.

Declare conftest.py for common fixtures and helpers that should be loaded for all test files in the same folder or deeper.

Coverage

https://coverage.readthedocs.io/en/latest/

Coverage offers a runner that will collect stats about which code is executed and which is not. Traditionally this is useful in combination with a testing framework, to get an idea of how much code you've tested. Your "coverage" is the percentage of your code that is tested.

A support plugin for pytest called pytest-cov allows coverage to activate automatically when pytest --cov is run.

You can run coverage directly, but you would need an entry point that will run some code. You won't have to do this unless you're really interested in generating off-the-cuff coverage reports in alternate styles (html, etc)

Pdoc

https://pdoc.dev/docs/pdoc.html#quickstart

Pdoc is a no-configuration documentation generator from your python files (not renpy files--yet?).

.vscode/settings.json

• pytest debug launcher

WIP

test runner for test_*.rpy files

[tiliv]

Bootstrapping renpy didn't pan out on the first go. We can import the renpy code in test files and loose python utilities, but it's not configured and quickly runs into obvious bootstrapping failures with pyx and compiled files.