Merge pull request #223 from dhalbert/shorter-imports

allow shorter imports; update examples to match

Author: dhalbert

adafruit_esp32spi/__init__.py

@@ -0,0 +1,13 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 Dan Halbert for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+
+# Allow
+# import adafruit_esp32spi
+# from adafruit_esp32spi.ESP_SPIcontrol
+# etc.
+# instead of the more verbose
+# import adafruit_esp32pi.adafruit_esp32spi
+# etc.
+
+from .adafruit_esp32spi import *

adafruit_esp32spi/socketpool.py

@@ -0,0 +1,10 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 Dan Halbert for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+
+# Allow
+# from adafruit_esp32pi.socketpool import SocketPool
+# instead of the more verbose
+# from adafruit_esp32pi.adafruit_esp32spi_socketpool import SocketPool
+
+from .adafruit_esp32spi_socketpool import *

adafruit_esp32spi/wifimanager.py

@@ -0,0 +1,10 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 Dan Halbert for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+
+# Allow imports like
+# from adafruit_esp32pi.wifimanager import WiFiManager
+# instead of the more verbose
+# from adafruit_esp32pi.adafruit_esp32spi_wifimanager import WiFiManager
+
+from .adafruit_esp32spi_wifimanager import *

docs/api.rst

@@ -1,19 +1,68 @@
-
-.. If you created a package, create one automodule per module in the package.
-
-.. If your library file(s) are nested in a directory (e.g. /adafruit_foo/foo.py)
-.. use this format as the module name: "adafruit_foo.foo"
-
 API Reference
 #############
 
 .. automodule:: adafruit_esp32spi.adafruit_esp32spi
+
+.. note::
+   As of version 11.0.0, it simpler to import this library and its submodules
+   The examples in this documentation use the new import names.
+   The old import names are still available, but are deprecated and may be removed in a future release.
+
+Before version 11.0.0, the library was structured like this (not all components are shown):
+
+* ``adafruit_esp32spi``
+
+  * ``adafruit_esp32spi``
+
+    * ``ESP32_SPIcontrol``
+
+  * ``adafruit_esp32spi_socketpool``
+
+    * ``SocketPool``
+
+  * ``adafruit_esp32spi_wifimanager``
+
+    * ``WiFiManager``
+
+.. code:: python
+
+    # Old import scheme
+    from adafruit_esp32spi import adafruit_esp32spi
+    from adafruit_esp32spi.adafruit_esp32spi_socketpool import SocketPool
+    from adafruit_esp32spi.adafruit_esp32spi_wifimanager import WiFiManager
+
+Now, the duplicated top-most name is not needed, and there are shorter names for the submodules.
+
+* ``adafruit_esp32spi``
+
+  * ``ESP32_SPIcontrol``
+
+  * ``socketpool``
+
+    * ``SocketPool``
+
+  * ``wifimanager``
+
+    * ``WiFiManager``
+
+.. code:: python
+
+    # New import scheme
+    import adafruit_esp32spi
+    from adafruit_esp32spi.socketpool import SocketPool
+    from adafruit_esp32spi.wifimanager import WiFiManager
+
+
+.. automodule:: adafruit_esp32spi
+   :imported-members:
    :members:
 
-.. automodule:: adafruit_esp32spi.adafruit_esp32spi_socketpool
+.. automodule:: adafruit_esp32spi.socketpool
+   :imported-members:
    :members:
 
-.. automodule:: adafruit_esp32spi.adafruit_esp32spi_wifimanager
+.. automodule:: adafruit_esp32spi.wifimanager
+   :imported-members:
    :members:
 
 .. automodule:: adafruit_esp32spi.digitalio

examples/esp32spi_aio_post.py

@@ -9,8 +9,8 @@
 import neopixel
 from digitalio import DigitalInOut
 
-from adafruit_esp32spi import adafruit_esp32spi
-from adafruit_esp32spi.adafruit_esp32spi_wifimanager import WiFiManager
+import adafruit_esp32spi
+from adafruit_esp32spi.wifimanager import WiFiManager
 
 print("ESP32 SPI webclient test")
 

examples/esp32spi_cheerlights.py

@@ -10,8 +10,8 @@
 import neopixel
 from digitalio import DigitalInOut
 
-from adafruit_esp32spi import adafruit_esp32spi
-from adafruit_esp32spi.adafruit_esp32spi_wifimanager import WiFiManager
+import adafruit_esp32spi
+from adafruit_esp32spi.wifimanager import WiFiManager
 
 # Get wifi details and more from a settings.toml file
 # tokens used by this Demo: CIRCUITPY_WIFI_SSID, CIRCUITPY_WIFI_PASSWORD

examples/esp32spi_ipconfig.py

@@ -8,8 +8,8 @@
 import busio
 from digitalio import DigitalInOut
 
-import adafruit_esp32spi.adafruit_esp32spi_socketpool as socketpool
-from adafruit_esp32spi import adafruit_esp32spi
+import adafruit_esp32spi
+from adafruit_esp32spi import socketpool
 
 # Get wifi details and more from a settings.toml file
 # tokens used by this Demo: CIRCUITPY_WIFI_SSID, CIRCUITPY_WIFI_PASSWORD

examples/esp32spi_localtime.py

@@ -10,8 +10,8 @@
 import rtc
 from digitalio import DigitalInOut
 
-from adafruit_esp32spi import adafruit_esp32spi
-from adafruit_esp32spi.adafruit_esp32spi_wifimanager import WiFiManager
+adafruit_esp32spi
+from adafruit_esp32spi.wifimanager import WiFiManager
 
 # Get wifi details and more from a settings.toml file
 # tokens used by this Demo: CIRCUITPY_WIFI_SSID, CIRCUITPY_WIFI_PASSWORD

examples/esp32spi_simpletest.py

@@ -9,7 +9,7 @@
 import busio
 from digitalio import DigitalInOut
 
-from adafruit_esp32spi import adafruit_esp32spi
+import adafruit_esp32spi
 
 # Get wifi details and more from a settings.toml file
 # tokens used by this Demo: CIRCUITPY_WIFI_SSID, CIRCUITPY_WIFI_PASSWORD

examples/esp32spi_simpletest_rp2040.py

@@ -9,7 +9,7 @@
 import busio
 from digitalio import DigitalInOut
 
-from adafruit_esp32spi import adafruit_esp32spi
+import adafruit_esp32spi
 
 # Get wifi details and more from a settings.toml file
 # tokens used by this Demo: CIRCUITPY_WIFI_SSID, CIRCUITPY_WIFI_PASSWORD