Installation prevented on PEP 668 Compliant Systems (e.g. Debian 12 Bookworm)

My system info

Raspberry Pi CM4 inside ReSeed terminal running Debian Bookworm 64bit. OS/Python info:

sudoer@hostname:~/ $ lsb_release -d | tail -n 1
Description:    Debian GNU/Linux 12 (bookworm)
sudoer@hostname:~/ $ pip3 --version
pip 23.0.1 from /usr/lib/python3/dist-packages/pip (python 3.11)
sudoer@hostname:~/ $ python --version
Python 3.11.2

Problem

On Raspberry Pi systems running the latest stable Debian (Bookworm 12), the sudo pip3 install seeed-python-reterminal installation procedure does not work:

sudoer@hostname:~/ $ sudo pip3 install seeed-python-reterminal
error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.

    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
    sure you have python3-full installed.

    For more information visit http://rptl.io/venv

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

The reason why can be found in the raspberry pi docs, see Python on Raspberry Pi

From Bookworm onwards, packages installed via pip must be installed into a Python Virtual Environment using venv. This has been introduced by the Python community, not by Raspberry Pi; see PEP 668 for more details.

PEP 668 essentially recommends that system python packages should be installed using the system package manager, while user python packages should be installed inside a venv.

Since seeed-python-reterminal requires access to system-level files, and since there is no debian release of the package, the correct installation workflow is unclear.

Proposals

Here are a couple ideas for changes to the installation instructions/workflow that should fix this problem.

I've included output from the README User LEDS Test script to show that these solutions should work.

Add instruction to use `--breaks-system-packages` flag

This is the fastest but least robust solution. Should look like this:

sudoer@hostname: $ sudo pip3 install seeed-python-reterminal --break-system-packages
Looking in indexes: https://pypi.org/simple, https://www.piwheels.org/simple
Collecting seeed-python-reterminal
  Downloading https://www.piwheels.org/simple/seeed-python-reterminal/seeed_python_reterminal-0.5-py3-none-any.whl (7.2 kB)
Requirement already satisfied: evdev in /usr/lib/python3/dist-packages (from seeed-python-reterminal) (1.6.1)
Installing collected packages: seeed-python-reterminal
Successfully installed seeed-python-reterminal-0.5
WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv

Then:

sudoer@hostname:~/ $ sudo python ./user-leds-test.py 
STA ON, USR OFF
STA OFF, USR ON
STA RED, USR OFF
STA OFF, USR OFF

Create and install local `.deb` of Seeed_Python_Reterminal

This would replace the "Install from Source" instructions, and remove the warning statements of using --breaks-system-packages.

There are many ways to do this, here's one using stdeb:

# Install debian dependencies
sudoer@hostname:~/ $ sudo apt install stdeb dh-python

# Download source
sudoer@hostname:~/ $ git clone https://github.com/Seeed-Studio/Seeed_Python_ReTerminal && cd ./Seeed_Python_ReTerminal

# Create .deb
sudoer@hostname:~/Seeed_Python_ReTerminal $ python3 setup.py --command-packages=stdeb.command debianize
sudoer@hostname:~/Seeed_Python_ReTerminal dpkg-buildpackage -b -us -uc

# Install .deb
sudoer@hostname:~/Seeed_Python_ReTerminal sudo apt install ../python3-seeed-python-reterminal

Then:

sudoer@hostname:~/ $ sudo python ./user-leds-test.py 
STA ON, USR OFF
STA OFF, USR ON
STA RED, USR OFF
STA OFF, USR OFF

Distribute debian package

If there are any Debian Maintainers interested in maintaining this package, I think distributing a Debian package would be the most robust solution in the long run. I am not a Debian Maintainer.

The workflow would be:

sudo apt install python3-seeed-python-reterminal

Update documentation to recommend venv like PEP668 does

The only issue with using venv is the need for root access to /sys/ folders, but that can be resolved, and users should be directed to this workflow anyway.

The following workflow works:

$ python -m venv --system-site-packages env 
$ source env/bin/activate
(env) $ pip install seeed-python-reterminal
(env) $ sudo $(which python) ./user-leds-test.py 
STA ON, USR OFF
STA OFF, USR ON
STA RED, USR OFF
STA OFF, USR OFF

Seeed-Studio / Seeed_Python_ReTerminal