Minor documentation changes

Author: Steve-Tech

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
 

cros_ec_python/commands/__init__.py

@@ -32,4 +32,4 @@
 # We can subtract this to get the input back
 print("Input Echoed:", resp - 0x01020304)
 ```
-"""
+"""

cros_ec_python/constants/__init__.py

@@ -27,4 +27,4 @@
     tempC = tempK - 273
     print(f"Temp Sensor {i}: {tempK}K ({tempC}°C)")
 ```
-"""
+"""

cros_ec_python/devices/__init__.py

@@ -61,4 +61,4 @@
 # Output should equal b'EC'
 assert resp == b'EC'
 ```
-"""
+"""

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(

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()

cros_ec_python/utils/__init__.py

@@ -0,0 +1,3 @@
+"""
+This submodule contains some utility functions that are used by the library.
+"""

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