From 8ba1b6fc58eb711fa5d472ae7c7ac438c0ea23e7 Mon Sep 17 00:00:00 2001 From: Alec Delaney Date: Wed, 12 Jan 2022 11:36:56 -0500 Subject: [PATCH 1/6] Add type annotations --- adafruit_24lc32.py | 33 ++++++++++++++++++++------------- 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/adafruit_24lc32.py b/adafruit_24lc32.py index dda7ad3..57c54ac 100644 --- a/adafruit_24lc32.py +++ b/adafruit_24lc32.py @@ -31,6 +31,13 @@ import time from micropython import const +try: + from typing import Optional, Union, Sequence + from digitalio import DigitalInOut + from busio import I2C +except ImportError: + pass + __version__ = "0.0.0-auto.0" __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_24LC32.git" @@ -42,7 +49,7 @@ class EEPROM: Driver base for the EEPROM Breakout. """ - def __init__(self, max_size, write_protect=False, wp_pin=None): + def __init__(self, max_size: int, write_protect: bool = False, wp_pin: Optional[DigitalInOut] = None) -> None: self._max_size = max_size self._wp = write_protect self._wraparound = False @@ -55,7 +62,7 @@ def __init__(self, max_size, write_protect=False, wp_pin=None): self._wp_pin = wp_pin @property - def write_wraparound(self): + def write_wraparound(self) -> bool: """Determines if sequential writes will wrapaound highest memory address (``len(EEPROM) - 1``) address. If ``False``, and a requested write will extend beyond the maximum size, an exception is raised. @@ -63,13 +70,13 @@ def write_wraparound(self): return self._wraparound @write_wraparound.setter - def write_wraparound(self, value): if not value in (True, False): + def write_wraparound(self, value: bool) -> None: raise ValueError("Write wraparound must be 'True' or 'False'.") self._wraparound = value @property - def write_protected(self): + def write_protected(self) -> bool: """The status of write protection. Default value on initialization is ``False``. When a ``WP`` pin is supplied during initialization, or using @@ -80,7 +87,7 @@ def write_protected(self): """ return self._wp if self._wp_pin is None else self._wp_pin.value - def __len__(self): + def __len__(self) -> int: """The size of the current EEPROM chip. This is one more than the highest address location that can be read or written to. .. code-block:: python @@ -92,7 +99,7 @@ def __len__(self): """ return self._max_size - def __getitem__(self, address): + def __getitem__(self, address: Union[int, slice]) -> bytearray: """Read the value at the given index, or values in a slice. .. code-block:: python # read single index @@ -130,7 +137,7 @@ def __getitem__(self, address): return read_buffer - def __setitem__(self, address, value): + def __setitem__(self, address: Union[int, slice], value: Union[int, Sequence[int]]) -> None: """Write the value at the given starting index. .. code-block:: python # write single index @@ -176,11 +183,11 @@ def __setitem__(self, address, value): self._write(address.start, value, self._wraparound) - def _read_address(self, address, read_buffer): + def _read_address(self, address: int, read_buffer: bytearray) -> bytearray: # Implemented by subclass raise NotImplementedError - def _write(self, start_address, data, wraparound): + def _write(self, start_address: int, data: Union[int, Sequence[int]], wraparound: bool) -> None: # Implemened by subclass raise NotImplementedError @@ -196,7 +203,7 @@ class EEPROM_I2C(EEPROM): """ # pylint: disable=too-many-arguments - def __init__(self, i2c_bus, address=0x50, write_protect=False, wp_pin=None): + def __init__(self, i2c_bus: I2C, address: int = 0x50, write_protect: bool = False, wp_pin: Optional[DigitalInOut] = None) -> None: from adafruit_bus_device.i2c_device import ( # pylint: disable=import-outside-toplevel I2CDevice as i2cdev, ) @@ -204,7 +211,7 @@ def __init__(self, i2c_bus, address=0x50, write_protect=False, wp_pin=None): self._i2c = i2cdev(i2c_bus, address) super().__init__(_MAX_SIZE_I2C, write_protect, wp_pin) - def _read_address(self, address, read_buffer): + def _read_address(self, address: int, read_buffer: bytearray) -> bytearray: write_buffer = bytearray(2) write_buffer[0] = address >> 8 write_buffer[1] = address & 0xFF @@ -212,7 +219,7 @@ def _read_address(self, address, read_buffer): i2c.write_then_readinto(write_buffer, read_buffer) return read_buffer - def _write(self, start_address, data, wraparound=False): + def _write(self, start_address: int, data: Union[int, Sequence[int]], wraparound: bool = False) -> None: # Decided against using the chip's "Page Write", since that would require # doubling the memory usage by creating a buffer that includes the passed # in data so that it can be sent all in one `i2c.write`. The single-write @@ -248,8 +255,8 @@ def _write(self, start_address, data, wraparound=False): # pylint: disable=no-member @EEPROM.write_protected.setter - def write_protected(self, value): if value not in (True, False): + def write_protected(self, value: bool) -> None: raise ValueError("Write protected value must be 'True' or 'False'.") self._wp = value if not self._wp_pin is None: From df9654986035c77d885b75d1c3604f39d2c764df Mon Sep 17 00:00:00 2001 From: Alec Delaney Date: Wed, 12 Jan 2022 11:37:18 -0500 Subject: [PATCH 2/6] Change to use isinstance() --- adafruit_24lc32.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/adafruit_24lc32.py b/adafruit_24lc32.py index 57c54ac..648b18d 100644 --- a/adafruit_24lc32.py +++ b/adafruit_24lc32.py @@ -70,8 +70,8 @@ def write_wraparound(self) -> bool: return self._wraparound @write_wraparound.setter - if not value in (True, False): def write_wraparound(self, value: bool) -> None: + if not isinstance(value, bool): raise ValueError("Write wraparound must be 'True' or 'False'.") self._wraparound = value @@ -255,8 +255,8 @@ def _write(self, start_address: int, data: Union[int, Sequence[int]], wraparound # pylint: disable=no-member @EEPROM.write_protected.setter - if value not in (True, False): def write_protected(self, value: bool) -> None: + if not isinstance(value, bool): raise ValueError("Write protected value must be 'True' or 'False'.") self._wp = value if not self._wp_pin is None: From de00d48e8930603dbdfe1f317ec826cb0e6f0fc6 Mon Sep 17 00:00:00 2001 From: Alec Delaney Date: Wed, 12 Jan 2022 11:44:12 -0500 Subject: [PATCH 3/6] Fix code blocks and Sphinx params --- adafruit_24lc32.py | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/adafruit_24lc32.py b/adafruit_24lc32.py index 648b18d..9922dd0 100644 --- a/adafruit_24lc32.py +++ b/adafruit_24lc32.py @@ -47,6 +47,11 @@ class EEPROM: """ Driver base for the EEPROM Breakout. + + :param int max_size: The maximum size of the EEPROM + :param bool write_protect: Turns on/off initial write protection + :param DigitalInOut wp_pin: (Optional) Physical pin connected to the ``WP`` breakout pin. + Must be a ``DigitalInOut`` object. """ def __init__(self, max_size: int, write_protect: bool = False, wp_pin: Optional[DigitalInOut] = None) -> None: @@ -79,9 +84,11 @@ def write_wraparound(self, value: bool) -> None: def write_protected(self) -> bool: """The status of write protection. Default value on initialization is ``False``. + When a ``WP`` pin is supplied during initialization, or using ``write_protect_pin``, the status is tied to that pin and enables hardware-level protection. + When no ``WP`` pin is supplied, protection is only at the software level in this library. """ @@ -90,7 +97,9 @@ def write_protected(self) -> bool: def __len__(self) -> int: """The size of the current EEPROM chip. This is one more than the highest address location that can be read or written to. + .. code-block:: python + eeprom = adafruit_24lc32.EEPROM_I2C() # size returned by len() len(eeprom) @@ -101,7 +110,9 @@ def __len__(self) -> int: def __getitem__(self, address: Union[int, slice]) -> bytearray: """Read the value at the given index, or values in a slice. + .. code-block:: python + # read single index eeprom[0] # read values 0 thru 9 with a slice @@ -139,7 +150,9 @@ def __getitem__(self, address: Union[int, slice]) -> bytearray: def __setitem__(self, address: Union[int, slice], value: Union[int, Sequence[int]]) -> None: """Write the value at the given starting index. + .. code-block:: python + # write single index eeprom[0] = 1 # write values 0 thru 4 with a list @@ -194,12 +207,13 @@ def _write(self, start_address: int, data: Union[int, Sequence[int]], wraparound class EEPROM_I2C(EEPROM): """I2C class for EEPROM. - :param: ~busio.I2C i2c_bus: The I2C bus the EEPROM is connected to. - :param: int address: I2C address of EEPROM. Default address is ``0x50``. - :param: bool write_protect: Turns on/off initial write protection. - Default is ``False``. - :param: wp_pin: (Optional) Physical pin connected to the ``WP`` breakout pin. - Must be a ``digitalio.DigitalInOut`` object. + + :param ~busio.I2C i2c_bus: The I2C bus the EEPROM is connected to. + :param int address: I2C address of EEPROM. Default address is ``0x50``. + :param bool write_protect: Turns on/off initial write protection. + Default is ``False``. + :param wp_pin: (Optional) Physical pin connected to the ``WP`` breakout pin. + Must be a ``DigitalInOut`` object. """ # pylint: disable=too-many-arguments From 1d3a83bb3b97f88e13c77854eb309662b301b583 Mon Sep 17 00:00:00 2001 From: Alec Delaney Date: Wed, 12 Jan 2022 11:44:51 -0500 Subject: [PATCH 4/6] Reformatted per pre-commit --- adafruit_24lc32.py | 32 ++++++++++++++++++++++++++------ 1 file changed, 26 insertions(+), 6 deletions(-) diff --git a/adafruit_24lc32.py b/adafruit_24lc32.py index 9922dd0..3c47eaf 100644 --- a/adafruit_24lc32.py +++ b/adafruit_24lc32.py @@ -54,7 +54,12 @@ class EEPROM: Must be a ``DigitalInOut`` object. """ - def __init__(self, max_size: int, write_protect: bool = False, wp_pin: Optional[DigitalInOut] = None) -> None: + def __init__( + self, + max_size: int, + write_protect: bool = False, + wp_pin: Optional[DigitalInOut] = None, + ) -> None: self._max_size = max_size self._wp = write_protect self._wraparound = False @@ -97,7 +102,7 @@ def write_protected(self) -> bool: def __len__(self) -> int: """The size of the current EEPROM chip. This is one more than the highest address location that can be read or written to. - + .. code-block:: python eeprom = adafruit_24lc32.EEPROM_I2C() @@ -148,7 +153,9 @@ def __getitem__(self, address: Union[int, slice]) -> bytearray: return read_buffer - def __setitem__(self, address: Union[int, slice], value: Union[int, Sequence[int]]) -> None: + def __setitem__( + self, address: Union[int, slice], value: Union[int, Sequence[int]] + ) -> None: """Write the value at the given starting index. .. code-block:: python @@ -200,7 +207,9 @@ def _read_address(self, address: int, read_buffer: bytearray) -> bytearray: # Implemented by subclass raise NotImplementedError - def _write(self, start_address: int, data: Union[int, Sequence[int]], wraparound: bool) -> None: + def _write( + self, start_address: int, data: Union[int, Sequence[int]], wraparound: bool + ) -> None: # Implemened by subclass raise NotImplementedError @@ -217,7 +226,13 @@ class EEPROM_I2C(EEPROM): """ # pylint: disable=too-many-arguments - def __init__(self, i2c_bus: I2C, address: int = 0x50, write_protect: bool = False, wp_pin: Optional[DigitalInOut] = None) -> None: + def __init__( + self, + i2c_bus: I2C, + address: int = 0x50, + write_protect: bool = False, + wp_pin: Optional[DigitalInOut] = None, + ) -> None: from adafruit_bus_device.i2c_device import ( # pylint: disable=import-outside-toplevel I2CDevice as i2cdev, ) @@ -233,7 +248,12 @@ def _read_address(self, address: int, read_buffer: bytearray) -> bytearray: i2c.write_then_readinto(write_buffer, read_buffer) return read_buffer - def _write(self, start_address: int, data: Union[int, Sequence[int]], wraparound: bool = False) -> None: + def _write( + self, + start_address: int, + data: Union[int, Sequence[int]], + wraparound: bool = False, + ) -> None: # Decided against using the chip's "Page Write", since that would require # doubling the memory usage by creating a buffer that includes the passed # in data so that it can be sent all in one `i2c.write`. The single-write From 2edc0a61f0a7286056a101b20d1eadb31d5a8330 Mon Sep 17 00:00:00 2001 From: Alec Delaney Date: Wed, 12 Jan 2022 11:45:52 -0500 Subject: [PATCH 5/6] Added space after write() --- adafruit_24lc32.py | 1 + 1 file changed, 1 insertion(+) diff --git a/adafruit_24lc32.py b/adafruit_24lc32.py index 3c47eaf..297e046 100644 --- a/adafruit_24lc32.py +++ b/adafruit_24lc32.py @@ -254,6 +254,7 @@ def _write( data: Union[int, Sequence[int]], wraparound: bool = False, ) -> None: + # Decided against using the chip's "Page Write", since that would require # doubling the memory usage by creating a buffer that includes the passed # in data so that it can be sent all in one `i2c.write`. The single-write From 62aff88857aec50ca942a2a9c9a61bd2bccbda9e Mon Sep 17 00:00:00 2001 From: Alec Delaney Date: Wed, 12 Jan 2022 11:49:34 -0500 Subject: [PATCH 6/6] Reformatted per pre-commit --- adafruit_24lc32.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adafruit_24lc32.py b/adafruit_24lc32.py index 297e046..3e78369 100644 --- a/adafruit_24lc32.py +++ b/adafruit_24lc32.py @@ -254,7 +254,7 @@ def _write( data: Union[int, Sequence[int]], wraparound: bool = False, ) -> None: - + # Decided against using the chip's "Page Write", since that would require # doubling the memory usage by creating a buffer that includes the passed # in data so that it can be sent all in one `i2c.write`. The single-write