begin docs (#1)

Author: 2bndy5

.readthedocs.yaml

@@ -0,0 +1,33 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+   install:
+     - requirements: docs/requirements.txt
+     - method: pip
+       path: '.'

README.rst

@@ -1,3 +1,8 @@
+.. |rtd-badge| image:: https://readthedocs.org/projects/circuitpython-mocks/badge/?version=latest
+    :target: https://circuitpython-mocks.readthedocs.io/en/latest/
+    :alt: Documentation Status
+
+|rtd-badge|
 
 Read The Docs
 =============

circuitpython_mocks/__init__.py

@@ -4,5 +4,13 @@
 
 @pytest.fixture(autouse=True)
 def monkey_patch_sys_paths(monkeypatch: pytest.MonkeyPatch):
+    """A pytest fixture that monkey patches the Python runtime's import paths, such
+    that this package's mock modules can be imported first (instead from the
+    adafruit-blinka package).
+
+    .. important::
+
+        This fixture is automatically used once imported into the test module.
+    """
     root_pkg = Path(__file__).parent
     monkeypatch.syspath_prepend(str(root_pkg))

circuitpython_mocks/_mixins.py

@@ -40,13 +40,17 @@ def unlock(self):
 
 
 class Expecting:
+    """A base class for the mock classes used to assert expected behaviors."""
     def __init__(self, **kwargs) -> None:
+        #: A double ended queue used to assert expected behavior
         self.expectations: deque[Read | Write | Transfer | SetState | GetState] = (
             deque()
         )
         super().__init__(**kwargs)
 
     def done(self):
+        """A function that asserts all `expectations` have been used.
+        This is automatically called from the destructor."""
         assert not self.expectations, (
             "Some expectations were unused:\n    "
             + "\n    ".join([repr(x) for x in self.expectations])

circuitpython_mocks/board.py

@@ -1,6 +1,7 @@
-"""Mock pins"""
+"""A module that hosts mock pins."""
 
 class Pin:
+    """A dummy type for GPIO pins."""
     pass
 
 

circuitpython_mocks/busio/__init__.py

@@ -1,22 +1,28 @@
+"""A module to mock the data bus transactions."""
+
 from enum import Enum, auto
 import sys
 from typing import List
 
 import circuitpython_typing
 
 from circuitpython_mocks.busio.operations import (
-    Read,
-    Write,
-    Transfer,
+    UARTRead,
+    UARTWrite,
     I2CRead,
     I2CWrite,
     I2CTransfer,
+    SPIRead,
+    SPIWrite,
+    SPITransfer,
 )
 from circuitpython_mocks._mixins import Expecting, Lockable
 from circuitpython_mocks.board import Pin
 
 
 class I2C(Expecting, Lockable):
+    """A mock of `busio.I2C` class."""
+
     def __init__(
         self,
         scl: Pin,
@@ -28,6 +34,8 @@ def __init__(
         super().__init__()
 
     def scan(self) -> List[int]:
+        """Returns an empty list.
+        Use :py:meth:`pytest.MonkeyPatch.setattr()` to change this output."""
         return []
 
     def readfrom_into(
@@ -38,6 +46,9 @@ def readfrom_into(
         start: int = 0,
         end: int = sys.maxsize,
     ) -> None:
+        """A mock imitation of :external:py:meth:`busio.I2C.readfrom_into()`.
+        This function checks against `I2CRead`
+        :py:attr:`~circuitpython_mocks._mixins.Expecting.expectations`"""
         assert self.expectations, "no expectation found for I2C.readfrom_into()"
         op = self.expectations.popleft()
         assert isinstance(op, I2CRead), f"Read operation expected, found {repr(op)}"
@@ -53,6 +64,9 @@ def writeto(
         start: int = 0,
         end: int = sys.maxsize,
     ) -> None:
+        """A mock imitation of :external:py:meth:`busio.I2C.writeto()`.
+        This function checks against `I2CWrite`
+        :py:attr:`~circuitpython_mocks._mixins.Expecting.expectations`"""
         assert self.expectations, "no expectation found for I2C.writeto()"
         op = self.expectations.popleft()
         assert isinstance(op, I2CWrite), f"Read operation expected, found {repr(op)}"
@@ -70,6 +84,9 @@ def writeto_then_readfrom(
         in_start: int = 0,
         in_end: int = sys.maxsize,
     ) -> None:
+        """A mock imitation of :external:py:meth:`busio.I2C.writeto_then_readfrom()`.
+        This function checks against `I2CTransfer`
+        :py:attr:`~circuitpython_mocks._mixins.Expecting.expectations`"""
         assert self.expectations, "no expectation found for I2C.writeto_then_readfrom()"
         op = self.expectations.popleft()
         assert isinstance(
@@ -89,6 +106,7 @@ def __init__(
         MISO: Pin | None = None,
         half_duplex: bool = False,
     ):
+        """A class to mock :external:py:class:`busio.SPI`."""
         super().__init__()
         self._frequency = 1000000
 
@@ -100,10 +118,12 @@ def configure(
         phase: int = 0,
         bits: int = 8,
     ) -> None:
+        """A dummy function to mock :external:py:meth:`busio.SPI.configure()`"""
         self._frequency = baudrate
 
     @property
     def frequency(self) -> int:
+        """Returns the value passed to ``baudrate`` parameter of `configure()`."""
         return self._frequency
 
     def write(
@@ -113,9 +133,12 @@ def write(
         start: int = 0,
         end: int = sys.maxsize,
     ) -> None:
+        """A function that mocks :external:py:meth:`busio.SPI.write()`.
+        This function checks against `SPIWrite`
+        :py:attr:`~circuitpython_mocks._mixins.Expecting.expectations`"""
         assert self.expectations, "no expectation found for SPI.write()"
         op = self.expectations.popleft()
-        assert isinstance(op, Write), f"Read operation expected, found {repr(op)}"
+        assert isinstance(op, SPIWrite), f"Read operation expected, found {repr(op)}"
         op.assert_expected(buffer, start, end)
 
     def readinto(
@@ -126,9 +149,12 @@ def readinto(
         end: int = sys.maxsize,
         write_value: int = 0,
     ) -> None:
+        """A function that mocks :external:py:meth:`busio.SPI.readinto()`.
+        This function checks against `SPIRead`
+        :py:attr:`~circuitpython_mocks._mixins.Expecting.expectations`"""
         assert self.expectations, "no expectation found for SPI.readinto()"
         op = self.expectations.popleft()
-        assert isinstance(op, Read), f"Read operation expected, found {repr(op)}"
+        assert isinstance(op, SPIRead), f"Read operation expected, found {repr(op)}"
         op.assert_response(buffer, start, end)
 
     def write_readinto(
@@ -141,20 +167,23 @@ def write_readinto(
         in_start: int = 0,
         in_end: int = sys.maxsize,
     ) -> None:
+        """A function that mocks :external:py:meth:`busio.SPI.write_readinto()`.
+        This function checks against `SPITransfer`
+        :py:attr:`~circuitpython_mocks._mixins.Expecting.expectations`"""
         assert self.expectations, "no expectation found for I2C.writeto_then_readfrom()"
         op = self.expectations.popleft()
         assert isinstance(
-            op, Transfer
+            op, SPITransfer
         ), f"Transfer operation expected, found {repr(op)}"
         op.assert_transaction(
             out_buffer, in_buffer, out_start, out_end, in_start, in_end
         )
 
 
 class UART(Expecting, Lockable):
-    class Parity(Enum):
-        """Parity Enumeration"""
+    """A class that mocks :external:py:class:`busio.UART`."""
 
+    class Parity(Enum):
         ODD = auto()
         EVEN = auto()
 
@@ -177,35 +206,47 @@ def __init__(
         super().__init__()
 
     def read(self, nbytes: int | None = None) -> bytes | None:
+        """A function that mocks :external:py:meth:`busio.UART.read()`.
+        This function checks against `UARTRead`
+        :py:attr:`~circuitpython_mocks._mixins.Expecting.expectations`"""
         assert self.expectations, "no expectation found for UART.read()"
         op = self.expectations.popleft()
-        assert isinstance(op, Read), f"Read operation expected, found {repr(op)}"
+        assert isinstance(op, UARTRead), f"Read operation expected, found {repr(op)}"
         length = nbytes or len(op.response)
         buffer = bytearray(length)
         op.assert_response(buffer, 0, length)
         return bytes(buffer)
 
     def readinto(self, buf: circuitpython_typing.WriteableBuffer) -> int | None:
+        """A function that mocks :external:py:meth:`busio.UART.readinto()`.
+        This function checks against `UARTRead`
+        :py:attr:`~circuitpython_mocks._mixins.Expecting.expectations`"""
         assert self.expectations, "no expectation found for UART.readinto()"
         op = self.expectations.popleft()
-        assert isinstance(op, Read), f"Read operation expected, found {repr(op)}"
+        assert isinstance(op, UARTRead), f"Read operation expected, found {repr(op)}"
         len_buf = len(op.response)
         op.assert_response(buf, 0, len_buf)
         return len_buf
 
     def readline(self) -> bytes:
+        """A function that mocks :external:py:meth:`busio.UART.readline()`.
+        This function checks against `UARTRead`
+        :py:attr:`~circuitpython_mocks._mixins.Expecting.expectations`"""
         assert self.expectations, "no expectation found for UART.readline()"
         op = self.expectations.popleft()
-        assert isinstance(op, Read), f"Read operation expected, found {repr(op)}"
+        assert isinstance(op, UARTRead), f"Read operation expected, found {repr(op)}"
         len_buf = len(op.response)
         buf = bytearray(len_buf)
         op.assert_response(buf, 0, len_buf)
         return bytes(buf)
 
     def write(self, buf: circuitpython_typing.ReadableBuffer) -> int | None:
+        """A function that mocks :external:py:meth:`busio.UART.write()`.
+        This function checks against `UARTWrite`
+        :py:attr:`~circuitpython_mocks._mixins.Expecting.expectations`"""
         assert self.expectations, "no expectation found for UART.write()"
         op = self.expectations.popleft()
-        assert isinstance(op, Write), f"Read operation expected, found {repr(op)}"
+        assert isinstance(op, UARTWrite), f"Read operation expected, found {repr(op)}"
         len_buf = len(op.expected)
         op.assert_expected(buf, 0, len_buf)
         return len(buf) or None

circuitpython_mocks/busio/operations.py

@@ -3,6 +3,8 @@
 
 
 class Write:
+    """A class to identify a write operation over a data bus."""
+
     def __init__(self, expected: bytearray, **kwargs) -> None:
         self.expected = expected
         super().__init__(**kwargs)
@@ -25,6 +27,8 @@ def assert_expected(
 
 
 class Read:
+    """A class to identify a read operation over a data bus."""
+
     def __init__(self, response: bytearray, **kwargs) -> None:
         self.response = response
         super().__init__(**kwargs)
@@ -48,6 +52,8 @@ def assert_response(
 
 
 class Transfer(Read, Write):
+    """A class to identify a read/write (transfer) operation over a data bus."""
+
     def __init__(self, expected: bytearray, response: bytearray, **kwargs) -> None:
         super().__init__(response=response, expected=expected, **kwargs)
 
@@ -93,6 +99,8 @@ def assert_address(self, address: int):
 
 
 class I2CWrite(Write, _I2CAddress):
+    """A class to identify a write operation over a I2C bus."""
+
     def __init__(self, address: int, expected: bytearray) -> None:
         super().__init__(expected=expected, address=address)
 
@@ -103,6 +111,8 @@ def __repr__(self) -> str:
 
 
 class I2CRead(Read, _I2CAddress):
+    """A class to identify a read operation over a I2C bus."""
+
     def __init__(self, address: int, response: bytearray) -> None:
         super().__init__(response=response, address=address)
 
@@ -113,6 +123,8 @@ def __repr__(self) -> str:
 
 
 class I2CTransfer(Transfer, _I2CAddress):
+    """A class to identify a write operation over a I2C bus."""
+
     def __init__(self, address: int, expected: bytearray, response: bytearray) -> None:
         super().__init__(expected=expected, response=response, address=address)
 
@@ -126,14 +138,20 @@ def __repr__(self) -> str:
 
 
 class SPIRead(Read):
+    """A class to identify a read operation over a SPI bus."""
+
     pass
 
 
 class SPIWrite(Write):
+    """A class to identify a write operation over a SPI bus."""
+
     pass
 
 
 class SPITransfer(Transfer):
+    """A class to identify a read/write (transfer) operation over a SPI bus."""
+
     def assert_transaction(
         self,
         out_buffer: cir_py_types.WriteableBuffer,
@@ -150,3 +168,15 @@ def assert_transaction(
         super().assert_transaction(
             out_buffer, in_buffer, out_start, out_end, in_start, in_end
         )
+
+
+class UARTRead(Read):
+    """A class to identify a read operation over a UART bus."""
+
+    pass
+
+
+class UARTWrite(Write):
+    """A class to identify a write operation over a UART bus."""
+
+    pass

circuitpython_mocks/digitalio/__init__.py

@@ -27,6 +27,7 @@ class Pull(Enum):
 
 
 class DigitalInOut(Expecting, ContextManaged):
+    """A class that mocks :external:py:class:digitalio.DigitalInOut`"""
     def __init__(self, pin: Pin, **kwargs):
         super().__init__(**kwargs)
         self._pin = pin
@@ -65,7 +66,9 @@ def direction(self, value):
 
     @property
     def value(self):
-        """The Digital Pin Value"""
+        """The Digital Pin Value.
+        This property will check against `SetState` and `GetState`
+        :py:attr:`~circuitpython_mocks._mixins.Expecting.expectations`."""
         assert self.expectations, "No expectations found for DigitalInOut.value.getter"
         op = self.expectations.popleft()
         assert isinstance(