Enhancement / Doc: Single source of truth for minimum Python version

[pushfoo]

Enhancement request:

What should be added/changed?

We should use a single source of truth for the minimum Python version.

What would it help with?

In 10 months, 3.7 is reaching EOL. If we make the proposed fix now, we'll never have to go through multiple doc pages to update the minimum python version again.

Potential Fixes

tl;dr I can do the same thing I did for pyglet if you want this done fast

Option 1 : The same thing I did for pyglet

I implemented a crude version of this proposal for pyglet: pyglet/pyglet#668. I could do the same for arcade.

Option 2: Option 1 + Add a maximum version

I mentioned maximum version because shapely has issues on 3.11, but I don't know if it's a hard requirement or just an optional one.

If we want to get fancy, we could also do something like this in arcade's __init__.py:

class Version(tuple):
   """A tuple that renders versions neatly to strings.
   
   In addition to printing neatly, constants declared with it can also
   be imported and compared against in other files. This would allow
   for centralizing control over minimum interpreter versions for 
   specific features.

   It works with string.format and f-strings, but does not work with
   % interpolation.
   """
    def __new__(cls, *args):
        return tuple.__new__(cls, args)

    def __str__(self) -> str:
        result = []
        for val in self:
            result.append(str(val))

        return '.'.join(result)

It was overkill for pyglet since they don't need to track a maximum Python version.

Option 3: Explore additional dependencies

We could also try using sphinx extensions or other dependencies. This might be overkill since we don't offer partial support for Python versions.

[pvcraven]

The min/max sounds like a good idea. We have historically run into issues around this and I see no reason that won't continue to be an issue.

[pushfoo]

tl;dr Would printing a warning be an acceptable way of dealing with exceeding max version?

I think my initial writeup made a flawed assumption because we may actually offer a form of partial support for Python versions due to shapely being a semi-optional dependency, even if the python-only collision is buggy right now.

From what I remember, all options other than a warning require workarounds while developing or installing.

Approach	Problem created
Pip-side restriction	Can't install on versions higher than max Python version
Hard crash when Py > max	Requires additional complexity to override it

[pvcraven]

I'd support a warning for a too-new python version. The python-only collision was just fixed in the development branch. It just isn't as fast as Shapely.

I think a hard error would be bad.

[gran4]

Python 3.11 is 30% faster than previous versions, it should be used in resource heavy games. What are the problems with shapely and 3.11?

[pushfoo]

Python 3.11 is 30% faster than previous versions, it should be used in resource heavy games

Not everyone has that option.

What are the problems with shapely and 3.11?

I'm not sure if it's still an issue. EDIT: Shapely isn't used in 3.X at all, so it doesn't matter going forward. See this comment.

As to this issue, I've done some more Sphinx experimentation and I'm pretty sure we could safely apply it in arcade. However, there's something I want to double check before I start adding it.

@pvcraven is there a particular reason for keeping the VERSION + version.py files we use at the moment? We use them in a few places like the PyPI build script, but this seems redundant given we have pyproject.toml. Do you have any objections to refactoring that?

[pvcraven]

No objections to a refactor. The auto bump code I think required it's own file.

[einarf]

What's the status on this one?

[pushfoo]

TL;DR: Much closer than before, still requires some additional work.

Clear To-Dos

• Set up substitution rules in the Sphinx's conf.py
• Swap out Python versions in the doc
• Make sure the substitutions aren't breaking things + smooth out the inevitable weird gotchas
• (ideally) clean up my old prototype for self-documenting substitutions currently live at: https://fontknife.readthedocs.io/en/main/contributing/substitutions.html

The Rest

What We Have Now

We switched to manual bump in #2581, which reduces brittleness. I'd rather keep it in the pyproject.toml, but PyPA and readthedocs may prefer it in files.

Also, Pymunk looks like the only slow binary dependency we have right now:

arcade/pyproject.toml

Lines 22 to 27 in 46ce22d

	dependencies = [
	"pyglet~=2.1.0",
	"pillow~=11.0.0",
	"pymunk~=6.9.0",
	"pytiled-parser~=2.2.9",
	]

Pillow seems almost guaranteed to have a same-day release for new Python versions.

Maybe Warn for Untested Python Versions?

If we make Pymunk an optional import (#2454 but not just in packaging), then there'd be nothing holding us back from just warning that this Python version hasn't been tested. If we feel fancy, we would gate it behind some assert trick like pyglet does for their debug warnings.

This post on the Python discourse and other seem to agree on avoiding version caps.

[einarf]

Why not make this part of the release checklist instead? The min version should really only be mention one place in the docs. Same goes for version.

Coming up with creative ways to automate these small things can lead to more work than just doing it manually.