From 41e2356f3bb8401963c9b68d357fc0b860ba8b4b Mon Sep 17 00:00:00 2001 From: Stephen Horvath Date: Wed, 17 Jul 2024 14:18:10 +1000 Subject: [PATCH] Minor documentation changes --- README.md | 8 ++++---- cros_ec_python/commands/__init__.py | 2 +- cros_ec_python/constants/__init__.py | 2 +- cros_ec_python/devices/__init__.py | 2 +- cros_ec_python/devices/dev.py | 2 +- cros_ec_python/devices/lpc.py | 9 ++++++++- cros_ec_python/utils/__init__.py | 3 +++ cros_ec_python/utils/devportio.py | 13 +++++++++---- 8 files changed, 28 insertions(+), 13 deletions(-) create mode 100644 cros_ec_python/utils/__init__.py diff --git a/README.md b/README.md index 89b07fc..4fbbe86 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # CrOS_EC_Python -A Python library for interacting with a Chrome OS EC. +A Python library for interacting with a Chrome OS EC. Commonly found in Chromebooks and Framework laptops. -It provides a somewhat low-level interface to the CrOS EC, allowing you to send and receive any EC command, +It provides a somewhat lower-level interface to the CrOS EC, allowing you to send and receive any EC command, and read any byte from the memory map. As well as a higher-level abstracted interface for easy access to some of the more common commands. @@ -30,8 +30,8 @@ which is usually only accessible by root. You can either run your script as root or just manually change the permissions. Read permission is not needed, only write. #### LPC Bus Interface -This library requires access to IO ports with the `CAP_SYS_RAWIO` capability. -It's easiest just to run python as root (use a venv though). +This library requires access to IO ports using the `CAP_SYS_RAWIO` capability. +It's easiest just to run your script as root. ## Documentation diff --git a/cros_ec_python/commands/__init__.py b/cros_ec_python/commands/__init__.py index 51e43ff..4b06ca3 100644 --- a/cros_ec_python/commands/__init__.py +++ b/cros_ec_python/commands/__init__.py @@ -32,4 +32,4 @@ # We can subtract this to get the input back print("Input Echoed:", resp - 0x01020304) ``` -""" \ No newline at end of file +""" diff --git a/cros_ec_python/constants/__init__.py b/cros_ec_python/constants/__init__.py index 75f669b..1bf8c46 100644 --- a/cros_ec_python/constants/__init__.py +++ b/cros_ec_python/constants/__init__.py @@ -27,4 +27,4 @@ tempC = tempK - 273 print(f"Temp Sensor {i}: {tempK}K ({tempC}°C)") ``` -""" \ No newline at end of file +""" diff --git a/cros_ec_python/devices/__init__.py b/cros_ec_python/devices/__init__.py index 0778203..f919c4f 100644 --- a/cros_ec_python/devices/__init__.py +++ b/cros_ec_python/devices/__init__.py @@ -61,4 +61,4 @@ # Output should equal b'EC' assert resp == b'EC' ``` -""" \ No newline at end of file +""" diff --git a/cros_ec_python/devices/dev.py b/cros_ec_python/devices/dev.py index 9169301..2b75170 100644 --- a/cros_ec_python/devices/dev.py +++ b/cros_ec_python/devices/dev.py @@ -72,7 +72,7 @@ def ec_exit(self) -> None: """ Close the file on exit. """ - if self.fd: + if hasattr(self, "fd"): self.fd.close() def command( diff --git a/cros_ec_python/devices/lpc.py b/cros_ec_python/devices/lpc.py index 7fa8397..7baba31 100644 --- a/cros_ec_python/devices/lpc.py +++ b/cros_ec_python/devices/lpc.py @@ -9,7 +9,9 @@ try: import portio + _import_portio_error = None except ImportError as e: + _import_portio_error = e warnings.warn(f"Failed to import portio: {e}, using /dev/port instead.", ImportWarning) from ..utils import devportio as portio @@ -19,12 +21,17 @@ class CrosEcLpc(CrosEcClass): Class to interact with the EC using the LPC interface. """ - def __init__(self, init: bool = True, address: Int32 = None): + def __init__(self, init: bool = True, address: Int32 = None, portio_warn: bool = True): """ Detect and initialise the EC. :param init: Whether to initialise the EC on creation. Default is True. :param address: Specify a custom memmap address, will be detected if not specified. + :param portio_warn: Whether to warn if portio couldn't be imported. Default is True. """ + if portio_warn and _import_portio_error is not None: + warnings.warn(f"Failed to import portio: {_import_portio_error}, using /dev/port instead.", + RuntimeWarning) + self.address = address if init: self.ec_init() diff --git a/cros_ec_python/utils/__init__.py b/cros_ec_python/utils/__init__.py new file mode 100644 index 0000000..ac3bade --- /dev/null +++ b/cros_ec_python/utils/__init__.py @@ -0,0 +1,3 @@ +""" +This submodule contains some utility functions that are used by the library. +""" diff --git a/cros_ec_python/utils/devportio.py b/cros_ec_python/utils/devportio.py index bd99f39..41b1a2c 100644 --- a/cros_ec_python/utils/devportio.py +++ b/cros_ec_python/utils/devportio.py @@ -1,5 +1,10 @@ -# This file provides a way to interact with the /dev/port device file as an alternative to the portio library. -# This is a lot slower than the portio library, but it doesn't require an extra package. +""" +This file provides a way to interact with the `/dev/port` device file +as an alternative to the [portio](https://pypi.org/project/portio/) library. + +This is *a lot* slower than the portio library (especially since `/dev/port` is opened on every function call), +but it doesn't require an extra package. +""" def out_bytes(data: bytes, port: int) -> None: """ @@ -173,13 +178,13 @@ def insl(port: int, data: bytearray, count: int) -> None: def ioperm(port: int, num: int, turn_on: bool) -> None: """ - ioperm stub function. It's not required for /dev/port. + `ioperm` stub function. It's not required for `/dev/port`. """ pass def iopl(level: int) -> None: """ - iopl stub function. It's not required for /dev/port. + `iopl` stub function. It's not required for `/dev/port`. """ pass