Small updates (#14)

* doc updates
* update type hints
* update CI
* update submodules
* fix datatype in RF24NetworkWrapper::peek_frame()
* adjust type hint in RF24Network.read() signature

.github/workflows/build.yml

@@ -11,12 +11,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Set up Python
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
-          python-version: 3.9
+          python-version: 3.x
 
       - name: Checkout Current Repo
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
         with:
           submodules: true
           fetch-depth: 0
@@ -74,7 +74,7 @@ jobs:
           publish_dir: ./docs/_build/html
 
       - name: Save distributable wheels as artifacts
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v3
         with:
           name: "pyRF24_pkg_dist"
           path: ${{ github.workspace }}/dist

.github/workflows/release.yml

@@ -10,12 +10,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Set up Python
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
-          python-version: 3.9
+          python-version: 3.x
 
       - name: Checkout Current Repo
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
         with:
           submodules: true
           fetch-depth: 0
@@ -33,10 +33,10 @@ jobs:
           platforms: aarch64
 
       - name: Build wheels with cibuildwheels
-        uses: pypa/cibuildwheel@v2.8.1
+        uses: pypa/cibuildwheel@v2.12.0
         env:
           CIBW_ARCHS_LINUX: aarch64 native
-          CIBW_SKIP: cp36* pp* cp311* *musllinux*
+          CIBW_SKIP: cp36* pp* *musllinux*
 
       - name: Move cross-compiled wheels to dist folder
         run: |
@@ -48,7 +48,7 @@ jobs:
         run: python setup.py sdist
 
       - name: Save distributable wheels as artifacts
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v3
         with:
           name: "pyRF24_pkg_dist"
           path: ${{ github.workspace }}/dist

README.rst

@@ -15,7 +15,7 @@ Introduction
 ============
 
 This is the official home of the python wrappers for the RF24 stack. It is meant for Linux-based
-SoC boards like the Raspberry Pi.
+SoC boards like the Raspberry Pi. Documentation is hosted at http://pyrf24.rtfd.io/.
 
 Pinout
 ~~~~~~
@@ -25,7 +25,7 @@ Pinout
 
 The nRF24L01's CE and IRQ pins can be connected to other GPIO pins on the SoC. The MISO, MOSI, SCK
 are limited to the corresponding counterparts on the SoC's SPI bus. The CSN pin is limited to the
-chosen SPI bus's "Chip Select" options (Also labeled as "CE" pins on many Raspberry Pi pinout
+chosen SPI bus's "Chip Select" options (also labeled as "CE" pins on many Raspberry Pi pinout
 diagrams). The following table shows the default pins used in all the
 `examples <https://pyrf24.readthedocs.io/en/latest/examples.html>`_ for this package.
 
@@ -274,7 +274,9 @@ in various development environments.
 Documentation
 ~~~~~~~~~~~~~
 
-Before submitting contributions, you should make sure that any documentation changes builds
+Each release has corresponding documentation hosted at http://pyrf24.rtfd.io/.
+
+Before submitting contributions, you should make sure that any documentation changes build
 successfully. This can be done locally but **on Linux only**. The documentation of API requires
 this package (& all its latest changes) be installed.
 

docs/_static/custom_material.css

@@ -1,51 +1,3 @@
-.md-typeset .admonition,
-.md-typeset details {
-  font-size: 0.75rem;
-}
-
-.md-typeset .admonition.tip>.admonition-title::before,
-.md-typeset .admonition.hint>.admonition-title::before {
-  mask-image: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12,3L1,9L12,15L21,10.09V17H23V9M5,13.18V17.18L12,21L19,17.18V13.18L12,17L5,13.18Z" /></svg>');
-}
-
-.md-typeset .admonition.seealso>.admonition-title::before {
-  mask-image: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><path d="M572.52 241.4C518.29 135.59 410.93 64 288 64S57.68 135.64 3.48 241.41a32.35 32.35 0 0 0 0 29.19C57.71 376.41 165.07 448 288 448s230.32-71.64 284.52-177.41a32.35 32.35 0 0 0 0-29.19zM288 400a144 144 0 1 1 144-144 143.93 143.93 0 0 1-144 144zm0-240a95.31 95.31 0 0 0-25.31 3.79 47.85 47.85 0 0 1-66.9 66.9A95.78 95.78 0 1 0 288 160z"/></svg>');
-  background-color: hsl(301, 100%, 63%);
-}
-
-.md-typeset .admonition.seealso {
-  border-left: .2rem solid hsl(301, 100%, 63%);
-}
-
-.md-typeset .admonition.seealso>.admonition-title {
-  background-color: hsla(287, 100%, 63%, 0.25);
-}
-
-.md-typeset .admonition.important>.admonition-title::before {
-  mask-image: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><path d="M256 8C119.043 8 8 119.083 8 256c0 136.997 111.043 248 248 248s248-111.003 248-248C504 119.083 392.957 8 256 8zm0 110c23.196 0 42 18.804 42 42s-18.804 42-42 42-42-18.804-42-42 18.804-42 42-42zm56 254c0 6.627-5.373 12-12 12h-88c-6.627 0-12-5.373-12-12v-24c0-6.627 5.373-12 12-12h12v-64h-12c-6.627 0-12-5.373-12-12v-24c0-6.627 5.373-12 12-12h64c6.627 0 12 5.373 12 12v100h12c6.627 0 12 5.373 12 12v24z"/></svg>');
-  background-color: hsl(123, 100%, 63%);
-}
-
-.md-typeset .admonition.important {
-  border-left: .2rem solid hsl(123, 100%, 63%);
-}
-
-.md-typeset .admonition.important>.admonition-title {
-  background-color: hsla(123, 100%, 63%, 0.25);
-}
-
-.md-typeset .admonition.warning>.admonition-title::before {
-  background-color: hsl(0, 100%, 63%);
-}
-
-.md-typeset .admonition.warning {
-  border-left: .2rem solid hsl(0, 100%, 63%);
-}
-
-.md-typeset .admonition.warning>.admonition-title {
-  background-color: hsla(0, 100%, 63%, 0.25);
-}
-
 html .md-nav--primary .md-nav__title--site .md-nav__button {
   top: 0;
   left: 0;
@@ -54,8 +6,8 @@ html .md-nav--primary .md-nav__title--site .md-nav__button {
 }
 
 thead {
-  background-color: var(--md-default-fg-color--light);
-  color: var(--md-primary-bg-color);
+	background-color: var(--md-default-fg-color--light);
+	color: var(--md-primary-bg-color);
 }
 
 .md-nav__title .md-nav__button.md-logo img, .md-nav__title .md-nav__button.md-logo svg {
@@ -66,23 +18,3 @@ thead {
 .md-header__button.md-logo img, .md-header__button.md-logo svg {
   width: auto;
 }
-
-/* CSS for Remark admonitions (translated by breathe from doxygen's @remark(s) cmd */
-:root {
-  --md-admonition-icon--remark: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 0 24 24" width="24px"><path d="M0 0h24v24H0z" fill="none"/><path d="M19 3H5c-1.1 0-2 .9-2 2v14c0 1.1.9 2 2 2h14c1.1 0 2-.9 2-2V5c0-1.1-.9-2-2-2zm-5 14H7v-2h7v2zm3-4H7v-2h10v2zm0-4H7V7h10v2z"/></svg>')
-}
-
-.md-typeset .admonition.remark {
-  border-color: rgb(116, 66, 255);
-}
-
-.md-typeset .remark > .admonition-title {
-  background-color: rgba(116, 66, 255, 0.1);
-  border-color: rgb(116, 66, 255);
-}
-
-.md-typeset .remark > .admonition-title::before {
-  background-color: rgb(116, 66, 255);
-  -webkit-mask-image: var(--md-admonition-icon--remark);
-        mask-image: var(--md-admonition-icon--remark);
-}

docs/conf.py

@@ -107,6 +107,42 @@
     ("py:parameter", dict(include_in_toc=False)),
 ]
 
+sphinx_immaterial_custom_admonitions = [
+    {
+        "name": "warning",
+        "color": (255, 66, 66),
+        "icon": "octicons/alert-24",
+        "override": True,
+    },
+    {
+        "name": "note",
+        "icon": "octicons/pencil-24",
+        "override": True,
+    },
+    {
+        "name": "seealso",
+        "color": (255, 66, 252),
+        "icon": "octicons/eye-24",
+        "title": "See Also",
+        "override": True,
+    },
+    {
+        "name": "hint",
+        "icon": "material/school",
+        "override": True,
+    },
+    {
+        "name": "tip",
+        "icon": "material/school",
+        "override": True,
+    },
+    {
+        "name": "important",
+        "icon": "material/school",
+        "override": True,
+    },
+]
+
 python_type_aliases = {
     "pyrf24.rf24.rf24_datarate_e": "rf24_datarate_e",
 }

docs/requirements.txt

@@ -1 +1,2 @@
+sphinx<6.0
 sphinx-immaterial

requirements-dev.txt

@@ -1,3 +1,4 @@
 pylint
 mypy
-cpp-linter
+cpp-linter
+black

src/pyRF24.cpp

@@ -1097,7 +1097,7 @@ PYBIND11_MODULE(rf24, m)
         // *****************************************************************************
 
         .def_property("payload_size", &RF24Wrapper::getPayloadSize, &RF24Wrapper::setPayloadSize, R"docstr(
-            This `int` attribute represents the radio's static payload lengths.
+            This `int` attribute represents the radio's static payload lengths. Maximum length is 32 bytes; minimum is 1 byte.
 
             .. note:: This attribute is only used when the radio's `dynamic_payloads` feature is disabled
                 (which is disabled by default).

src/pyRF24Network.cpp

@@ -60,10 +60,10 @@ class RF24NetworkWrapper : public RF24Network
         return RF24Network::peek(header);
     }
 
-    std::tuple<RF24NetworkHeader, py::bytearray> peek_frame(uint8_t maxlen = MAX_PAYLOAD_SIZE)
+    std::tuple<RF24NetworkHeader, py::bytearray> peek_frame(uint16_t maxlen = MAX_PAYLOAD_SIZE)
     {
         RF24NetworkHeader header;
-        maxlen = static_cast<uint8_t>(rf24_min(maxlen, RF24Network::peek(header)));
+        maxlen = static_cast<uint16_t>(rf24_min(maxlen, RF24Network::peek(header)));
         char* buf = new char[maxlen + 1];
         RF24Network::peek(header, buf, maxlen);
         py::bytearray py_ba = py::bytearray(buf, maxlen);
@@ -326,12 +326,13 @@ PYBIND11_MODULE(rf24_network, m)
         // *****************************************************************************
 
         .def("read", &RF24NetworkWrapper::read, R"docstr(
-            read(maxlen: int = 144) -> Tuple[RF24NetworkHeader, bytearray]
+            read(maxlen: int = MAX_PAYLOAD_SIZE) -> Tuple[RF24NetworkHeader, bytearray]
 
             Fetch the next available frame received by the network node. This differs from `peek()` as it removes the frame from the queue.
 
-            :param int maxlen: The maximum length of the frame's message to be returned. If this parameter is unspecified, then the entire
-                length of the frame's message is returned.
+            :param int maxlen: The maximum length of the frame's message to be returned. If this parameter is unspecified or greater than
+                the actual frame's message size, then only the frame's full message size is used. Defaults to
+                :py:attr:`~pyrf24.rf24_network.MAX_PAYLOAD_SIZE`.
 
             :Returns: A `tuple` in which
 
@@ -344,7 +345,7 @@ PYBIND11_MODULE(rf24_network, m)
 
         .def("peek", &RF24NetworkWrapper::peek_header, R"docstr(
             peek(header: RF24NetworkHeader) -> int \
-            peek(maxlen: int) -> Tuple[RF24NetworkHeader, bytearray]
+            peek(maxlen: int = MAX_PAYLOAD_SIZE) -> Tuple[RF24NetworkHeader, bytearray]
             To fetch the next available frame's header received by the network node, the parameter and return type is as follows:
 
             :param RF24NetworkHeader header: The object to save the header information to.
@@ -358,7 +359,8 @@ PYBIND11_MODULE(rf24_network, m)
             To fetch the next available frame received by the network node, the parameter and return type is as follows:
 
             :param int maxlen: The maximum length of the message to fetch. If this parameter is unspecified or greater than
-                the actual frame's message size, then only the frame's full message size is used.
+                the actual frame's message size, then only the frame's full message size is used. Defaults to
+                :py:attr:`~pyrf24.rf24_network.MAX_PAYLOAD_SIZE`.
 
             :Returns: A 2-tuple containing the frame's header (of type `RF24NetworkHeader`) and the frame's message (of type `bytearray`).
         )docstr",

src/pyrf24/fake_ble.py

@@ -383,7 +383,9 @@ def __init__(self, radio: RF24):
             This attribute is exposed for debugging purposes.
         """
 
-    def begin(self, ce_pin: int = None, csn_pin: int = None) -> bool:
+    def begin(
+        self, ce_pin: Optional[int] = None, csn_pin: Optional[int] = None
+    ) -> bool:
         """Initialize the radio using BLE specifications.
 
         Internally, this function also calls :meth:`~pyrf24.rf24.RF24.begin()`, so
@@ -747,7 +749,7 @@ class TemperatureServiceData(ServiceData):
     def __init__(self):
         super().__init__(TEMPERATURE_UUID)
 
-    @property
+    @property  # type: ignore[override]
     def data(self) -> float:
         """This attribute is a `float` value."""
         return struct.unpack("<i", self._data[:3] + b"\0")[0] * 10**-2
@@ -777,7 +779,7 @@ class BatteryServiceData(ServiceData):
     def __init__(self):
         super().__init__(BATTERY_UUID)
 
-    @property
+    @property  # type: ignore[override]
     def data(self) -> int:
         """The attribute is a 1-byte unsigned `int` value."""
         return int(self._data[0])
@@ -828,7 +830,7 @@ def pa_level_at_1_meter(self, value: Union[bytes, bytearray, int]):
     def uuid(self) -> bytes:
         return self._type[:2]
 
-    @property
+    @property  # type: ignore[override]
     def data(self) -> str:
         """This attribute is a `str` of URL data."""
         value = self._data.decode()