move defs shared-bindings/circuitpython_typing to here

Author: dhalbert

circuitpython_typing/__init__.py

@@ -14,31 +14,45 @@
 __version__ = "0.0.0-auto.0"
 __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_Typing.git"
 
-
+import array
 from typing import Union, Optional
 
 # Protocol was introduced in Python 3.8.
 try:
-    from typing import Protocol
+    from typing import Protocol  # pylint: disable=ungrouped-imports
 except ImportError:
     from typing_extensions import Protocol
 
-from array import array
+# Lists below are alphabetized.
 
-ReadableBuffer = Union[bytes, bytearray, memoryview, array]
-"""Classes that implement the readable buffer protocol
-  * `bytes`
-  * `bytearray`
-  * `memoryview`
-  * `array.array`
-"""
+# More added in each conditional import.
+__all__ = [
+    "Alarm",
+    "AudioSample",
+    "ByteStream",
+    "FrameBuffer",
+    "ReadableBuffer",
+    "WriteableBuffer",
+]
 
-WriteableBuffer = Union[bytearray, memoryview, array]
-"""Classes that implement the writeable buffer protocol
-  * `bytearray`
-  * `memoryview`
-  * `array.array`
-"""
+ReadableBuffer = Union[
+    array.array,
+    bytearray,
+    bytes,
+    memoryview,
+    "rgbmatrix.RGBMatrix",
+    "ulab.numpy.ndarray",
+]
+"""Classes that implement the readable buffer protocol."""
+
+WriteableBuffer = Union[
+    array.array,
+    bytearray,
+    memoryview,
+    "rgbmatrix.RGBMatrix",
+    "ulab.numpy.ndarray",
+]
+"""Classes that implement the writeable buffer protocol."""
 
 
 class ByteStream(Protocol):
@@ -63,3 +77,25 @@ def read(self, count: Optional[int] = None) -> Optional[bytes]:
     def write(self, buf: ReadableBuffer) -> Optional[int]:
         """Write the bytes in ``buf`` to the stream."""
         ...
+
+
+# These types may not be in adafruit-blinka, so use the string form instead of a resolved name.
+
+AudioSample = Union[
+    "audiocore.WaveFile",
+    "audiocore.RawSample",
+    "audiomixer.Mixer",
+    "audiomp3.MP3Decoder",
+    "synthio.MidiTrack",
+]
+"""Classes that implement the audiosample protocol.
+You can play these back with `audioio.AudioOut`, `audiobusio.I2SOut` or `audiopwmio.PWMAudioOut`.
+"""
+
+FrameBuffer = Union["rgbmatrix.RGBMatrix"]
+"""Classes that implement the framebuffer protocol."""
+
+Alarm = Union["alarm.pin.PinAlarm", "alarm.time.TimeAlarm"]
+"""Classes that implement alarms for sleeping and asynchronous notification.
+You can use these alarms to wake up from light or deep sleep.
+"""

circuitpython_typing/py.typed

@@ -22,6 +22,21 @@
 
 # Based on https://github.com/python/typeshed/blob/master/stdlib/_socket.pyi
 
+__all__ = [
+    # alphabetized
+    "CircuitPythonSocketType",
+    "CommonCircuitPythonSocketType",
+    "CommonSocketType",
+    "InterfaceType",
+    "LegacyCircuitPythonSocketType",
+    "SSLContextType",
+    "SocketType",
+    "SocketpoolModuleType",
+    "StandardPythonSocketType",
+    "SupportsRecvInto",
+    "SupportsRecvWithFlags",
+]
+
 
 class CommonSocketType(Protocol):
     """Describes the common structure every socket type must have."""

circuitpython_typing/socket.py

@@ -56,4 +56,8 @@
     # You can just specify the packages manually here if your project is
     # simple. Or you can use find_packages().
     packages=["circuitpython_typing"],
+    # Make the types available for mypy type checking. See PEP 561.
+    package_data={
+        "circuitpython_typing": ["py.typed"],
+    },
 )