add pyproject.toml and update docs (#1001)

note this removes the old cross compile script

ref #1000

* update docs

.github/workflows/doxygen.yml

@@ -50,5 +50,5 @@ jobs:
  uses: nRF24/.github/.github/workflows/build_docs.yaml@main
  with:
  deploy-gh-pages: ${{ github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/master') }}
- doxygen-version: '1.11.0'
+ doxygen-version: '1.12.0'
  secrets: inherit

cspell.config.yaml

@@ -269,6 +269,7 @@ words:
  - vect
  - venv
  - vfpv
+ - virtualenv
  - vpfv
  - VSPI
  - Wcast

docs/cross_compile.md

@@ -61,40 +61,3 @@ Following prerequisites need to be assured:
  ```shell
  make upload
  ```
-
-## Cross compilation steps for python wrapper
-
-### Prerequisites
-
-- Python setuptools must be installed on both target and cross-compilation machines
- ```shell
- sudo pip install setuptools
- ```
- or
- ```shell
- sudo apt-get install python-setuptools
- ```
-
-### Installation steps
-
-1. Assure having libboost-python-dev library in your cross-compilation environment. Alternatively, you can install it into your target machine and copy /usr and /lib directories to the cross-compilation machine.
- For example
- ```shell
- mkdir -p rpi_root && rsync -a pi@target_linux_host:/usr :/lib rpi_root
- export CFLAGS="--sysroot=/your/dir/rpi_root -I/your/dir/rpi_root/usr/include/python2.7/"
- ```
-2. Build the python wrapper
- ```shell
- cd pyRF24
- ./setup.py build --compiler=crossunix
- ```
-3. Make the egg package
- ```shell
- ./setup.py bdist_egg --plat-name=cross
- ```
- `dist/RF24-<version>-cross.egg` should be created.
-4. Upload it to the target machine and install there:
- ```shell
- scp dist/RF24-*-cross.egg pi@target_linux_host:
- ssh pi@target_linux_host 'sudo easy_install RF24-*-cross.egg'
- ```

docs/python_wrapper.md

@@ -17,7 +17,7 @@ We recommend using the newer [pyRF24 package](https:/nRF24/pyRF24)
 8. includes typing stub files for type checking tools like mypy
 
 The only reason that you should need to keep using these older individual python
-wrappers is if you must to use python v3.6 or older.
+wrappers is if you must use python v3.6 or older.
 
 You **cannot** use these individual wrappers in combination with the pyRF24 package.
 @endparblock
@@ -33,6 +33,19 @@ python wrapper(s) to work.
 @note The interrupt_configure.py example uses the
 [gpiod library](https://pypi.org/project/gpiod) to watch the radio's IRQ pin.
 
+> [!warning]
+> Recent updates to pip mandate that users manage a python virtual environment.
+> This is good practice because it avoids the risk that installing a package with pip will
+> mess up a system-installed package.
+>
+> For information about using up a python virtual environment, see the official
+> [instructions using the python standard library `venv`](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/)
+> (which is a minimized variant of
+> [the `virtualenv` library](https://virtualenv.pypa.io/en/stable/index.html)).
+>
+> There's also a note at the end of these instructions that talks about
+> using `sudo` within a python virtual environment.
+
 ### Python2
 
 ```shell
@@ -51,23 +64,17 @@ python -m pip install --upgrade pip setuptools
 sudo apt-get install python3-dev libboost-python-dev python3-pip
 ```
 
-Next, install some up-to-date python3 packages.
-
-```shell
-python3 -m pip install --upgrade pip setuptools
-```
-
 ## Installation
 
-@note Only step 2 has to be repeated if installing the python wrappers for
-RF24Network and RF24Mesh libraries. The prerequisites stated above still apply
-to each library.
+> [!note]
+> If using **older versions of RF24* libraries** with python3,
+> the setup.py script needed a manually created symlink for the boost.python library.
+> ```shell
+> sudo ln -s $(ls /usr/lib/$(ls /usr/lib/gcc | tail -1)/libboost_python3*.so | tail -1) /usr/lib/$(ls /usr/lib/gcc | tail -1)/libboost_python3.so
+> ```
+> This is no longer needed with the latest versions of RF24 libraries.
 
-1. For python3, setup.py needs a manually created symlink for the boost.python library:
- ```shell
- sudo ln -s $(ls /usr/lib/$(ls /usr/lib/gcc | tail -1)/libboost_python3*.so | tail -1) /usr/lib/$(ls /usr/lib/gcc | tail -1)/libboost_python3.so
- ```
-2. Install the library.
+1. Install the library.
 
  This step needs to be executed from the appropriate directory of
  the cloned RF24* repository:
@@ -77,10 +84,6 @@ to each library.
 
  When in the correct directory, run the following command:
  ```shell
- python setup.py install
- ```
- or for python3
- ```shell
  python3 -m pip install -v .
  ```
  @note Building/installing takes several minutes on arm-based machines.
@@ -90,7 +93,7 @@ to each library.
  See the additional [Platform Support pages](pages.html) for information on connecting your hardware.
 
  See the included [\*.py files in the "examples_linux" folder](examples.html) for usage information.
-3. Running the Example
+2. Running the Example
 
  The python examples location differ for each RF24* repositories.
  - navigate to *examples_linux* directory in the RF24 cloned repository

pyRF24/README.md

@@ -0,0 +1,25 @@
+# Individual python wrapper
+
+> [!warning]
+> This python wrapper for the RF24 C++ library was not intended
+> for distribution on pypi.org. Any such attempts to publish this package
+> is unauthorized and unofficial.
+
+## Use pyRF24 instead
+
+We recommend using the newer [pyRF24](https:/nRF24/pyRF24) package
+[available from pypi](https://pypi.org/project/pyrf24/) because
+
+1. it is [practically drop-in compatible](https://nrf24.github.io/pyRF24/#migrating-to-pyrf24)
+2. easier to install or get updates with popular package managers like pip
+3. does not require the C++ libraries to be installed -- it uses its own isolated binaries
+4. includes wrappers for RF24, RF24Network, RF24Mesh libraries
+5. includes a new [fake BLE implementation](https://nrf24.github.io/pyRF24/ble_api.html)
+6. has its own [dedicated documentation](https://nRF24.github.io/pyRF24)
+7. is compatible with python's builtin `help()`
+8. includes typing stub files for type checking tools like mypy
+
+The only reason that you should need to keep using these older individual python
+wrappers is if you must use python v3.6 or older.
+
+You **cannot** use these individual wrappers in combination with the pyRF24 package.

pyRF24/pyproject.toml

@@ -0,0 +1,15 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "RF24"
+classifiers = [
+ "Programming Language :: Python :: 2",
+ "Programming Language :: Python :: 3",
+ "Programming Language :: C++",
+ "License :: OSI Approved :: GNU General Public License v2 (GPLv2)",
+]
+license = {text = "GNU General Public License v2 (GPLv2)"}
+readme = {file = "README.md", content-type = "text/markdown"}
+dynamic = ["version"] # version is set in setup.py

pyRF24/setup.py

@@ -3,7 +3,6 @@
 import os
 from sys import version_info
 from setuptools import setup, Extension
-import crossunixccompiler
 
 version = ""
 cflags = os.getenv("CFLAGS", "")
@@ -74,33 +73,13 @@
 os.environ["CFLAGS"] = cflags
 
 # get the proper boost.python lib symlink name according to version of python
-if version_info >= (3,):
- BOOST_LIB = "boost_python3"
-else:
- BOOST_LIB = "boost_python"
-
-crossunixccompiler.register()
-
-long_description = """
-.. warning:: This python wrapper for the RF24 C++ library was not intended
- for distribution on pypi.org. If you're reading this, then this package
- is likely unauthorized or unofficial.
-"""
+BOOST_LIB = "boost_python" + (
+ "" if version_info < (3,) else "%d%d" % (version_info.major, version_info.minor)
+)
 
 
 setup(
- name="RF24",
  version=version,
- license="GPLv2",
- license_files=(os.path.join(git_dir, "LICENSE"),),
- long_description=long_description,
- long_description_content_type="text/x-rst",
- classifiers=[
- "Programming Language :: Python :: 2",
- "Programming Language :: Python :: 3",
- "Programming Language :: C++",
- "License :: OSI Approved :: GNU General Public License v2 (GPLv2)",
- ],
  ext_modules=[
  Extension(
  "RF24",