circuitpython-stubs 9.2.6__tar.gz → 10.0.0a2__tar.gz

circuitpython_stubs-10.0.0a2/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: circuitpython-stubs
+Version: 10.0.0a2
+Summary: PEP 561 type stubs for CircuitPython
+Home-page: https://github.com/adafruit/circuitpython
+Author-email: circuitpython@adafruit.com
+Maintainer: CircuitPythonistas
+Maintainer-email: circuitpython@adafruit.com
+License: MIT
+Dynamic: author-email
+Dynamic: home-page
+Dynamic: license
+Dynamic: maintainer
+Dynamic: maintainer-email
+Dynamic: summary

circuitpython_stubs-10.0.0a2/_stage/__init__.pyi

@@ -0,0 +1,105 @@
+"""C-level helpers for animation of sprites on a stage
+
+The `_stage` module contains native code to speed-up the ``stage``
+`library <https://github.com/python-ugame/circuitpython-stage>`_."""
+
+from __future__ import annotations
+
+from typing import List
+
+import busdisplay
+from circuitpython_typing import ReadableBuffer, WriteableBuffer
+
+def render(
+    x0: int,
+    y0: int,
+    x1: int,
+    y1: int,
+    layers: List[Layer],
+    buffer: WriteableBuffer,
+    display: busdisplay.BusDisplay,
+    scale: int,
+    background: int,
+) -> None:
+    """Render and send to the display a fragment of the screen.
+
+    :param int x0: Left edge of the fragment.
+    :param int y0: Top edge of the fragment.
+    :param int x1: Right edge of the fragment.
+    :param int y1: Bottom edge of the fragment.
+    :param layers: A list of the :py:class:`~_stage.Layer` objects.
+    :type layers: list[Layer]
+    :param ~circuitpython_typing.WriteableBuffer buffer: A buffer to use for rendering.
+    :param ~busdisplay.BusDisplay display: The display to use.
+    :param int scale: How many times should the image be scaled up.
+    :param int background: What color to display when nothing is there.
+
+    There are also no sanity checks, outside of the basic overflow
+    checking. The caller is responsible for making the passed parameters
+    valid.
+
+    This function is intended for internal use in the ``stage`` library
+    and all the necessary checks are performed there."""
+
+class Layer:
+    """Keep information about a single layer of graphics"""
+
+    def __init__(
+        self,
+        width: int,
+        height: int,
+        graphic: ReadableBuffer,
+        palette: ReadableBuffer,
+        grid: ReadableBuffer,
+    ) -> None:
+        """Keep internal information about a layer of graphics (either a
+        ``Grid`` or a ``Sprite``) in a format suitable for fast rendering
+        with the ``render()`` function.
+
+        :param int width: The width of the grid in tiles, or 1 for sprites.
+        :param int height: The height of the grid in tiles, or 1 for sprites.
+        :param ~circuitpython_typing.ReadableBuffer graphic: The graphic data of the tiles.
+        :param ~circuitpython_typing.ReadableBuffer palette: The color palette to be used.
+        :param ~circuitpython_typing.ReadableBuffer grid: The contents of the grid map.
+
+        This class is intended for internal use in the ``stage`` library and
+        it shouldn't be used on its own."""
+        ...
+
+    def move(self, x: int, y: int) -> None:
+        """Set the offset of the layer to the specified values."""
+        ...
+
+    def frame(self, frame: int, rotation: int) -> None:
+        """Set the animation frame of the sprite, and optionally rotation its
+        graphic."""
+        ...
+
+class Text:
+    """Keep information about a single grid of text"""
+
+    def __init__(
+        self,
+        width: int,
+        height: int,
+        font: ReadableBuffer,
+        palette: ReadableBuffer,
+        chars: ReadableBuffer,
+    ) -> None:
+        """Keep internal information about a grid of text
+        in a format suitable for fast rendering
+        with the ``render()`` function.
+
+        :param int width: The width of the grid in tiles, or 1 for sprites.
+        :param int height: The height of the grid in tiles, or 1 for sprites.
+        :param ~circuitpython_typing.ReadableBuffer font: The font data of the characters.
+        :param ~circuitpython_typing.ReadableBuffer palette: The color palette to be used.
+        :param ~circuitpython_typing.ReadableBuffer chars: The contents of the character grid.
+
+        This class is intended for internal use in the ``stage`` library and
+        it shouldn't be used on its own."""
+        ...
+
+    def move(self, x: int, y: int) -> None:
+        """Set the offset of the text to the specified values."""
+        ...

circuitpython_stubs-10.0.0a2/aesio/__init__.pyi

@@ -0,0 +1,79 @@
+"""AES encryption routines
+
+The `AES` module contains classes used to implement encryption
+and decryption. It aims to be low overhead in terms of memory.
+
+For more information on AES, refer to `the Wikipedia entry
+<https://en.wikipedia.org/wiki/Advanced_Encryption_Standard>`_.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from circuitpython_typing import ReadableBuffer, WriteableBuffer
+
+MODE_ECB: int
+MODE_CBC: int
+MODE_CTR: int
+
+class AES:
+    """Encrypt and decrypt AES streams"""
+
+    def __init__(
+        self,
+        key: ReadableBuffer,
+        mode: int = 0,
+        IV: Optional[ReadableBuffer] = None,
+        segment_size: int = 8,
+    ) -> None:
+        """Create a new AES state with the given key.
+
+        :param ~circuitpython_typing.ReadableBuffer key: A 16-, 24-, or 32-byte key
+        :param int mode: AES mode to use.  One of: `MODE_ECB`, `MODE_CBC`, or
+                         `MODE_CTR`
+        :param ~circuitpython_typing.ReadableBuffer IV: Initialization vector to use for CBC or CTR mode
+
+        Additional arguments are supported for legacy reasons.
+
+        Encrypting a string::
+
+          import aesio
+          from binascii import hexlify
+
+          key = b'Sixteen byte key'
+          inp = b'CircuitPython!!!' # Note: 16-bytes long
+          outp = bytearray(len(inp))
+          cipher = aesio.AES(key, aesio.MODE_ECB)
+          cipher.encrypt_into(inp, outp)
+          hexlify(outp)"""
+        ...
+
+    def rekey(
+        self,
+        key: ReadableBuffer,
+        IV: Optional[ReadableBuffer] = None,
+    ) -> None:
+        """Update the AES state with the given key.
+
+        :param ~circuitpython_typing.ReadableBuffer key: A 16-, 24-, or 32-byte key
+        :param ~circuitpython_typing.ReadableBuffer IV: Initialization vector to use
+                                                        for CBC or CTR mode"""
+        ...
+
+    def encrypt_into(self, src: ReadableBuffer, dest: WriteableBuffer) -> None:
+        """Encrypt the buffer from ``src`` into ``dest``.
+
+        For ECB mode, the buffers must be 16 bytes long.  For CBC mode, the
+        buffers must be a multiple of 16 bytes, and must be equal length.
+        Any included padding must conform to the required padding style for the given mode.
+        For CTR mode, there are no restrictions.
+        """
+        ...
+
+    def decrypt_into(self, src: ReadableBuffer, dest: WriteableBuffer) -> None:
+        """Decrypt the buffer from ``src`` into ``dest``.
+        For ECB mode, the buffers must be 16 bytes long.  For CBC mode, the
+        buffers must be a multiple of 16 bytes, and must be equal length.  For
+        CTR mode, there are no restrictions."""
+        ...

circuitpython_stubs-10.0.0a2/alarm/time/__init__.pyi

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from typing import Optional
+
+class TimeAlarm:
+    """Trigger an alarm when the specified time is reached."""
+
+    def __init__(
+        self,
+        *,
+        monotonic_time: Optional[float] = None,
+        epoch_time: Optional[int] = None,
+    ) -> None:
+        """Create an alarm that will be triggered when `time.monotonic()` would equal
+        ``monotonic_time``, or when `time.time()` would equal ``epoch_time``.
+        Only one of the two arguments can be given.
+        The alarm is not active until it is passed to an
+        `alarm`-enabling sleep function, such as `alarm.light_sleep_until_alarms()` or
+        `alarm.exit_and_deep_sleep_until_alarms()`.
+
+        If the given time is already in the past, then an exception is raised.
+        If the sleep happens after the given time, then it will wake immediately
+        due to this time alarm.
+
+        Example::
+
+          # Deep sleep for 30 seconds.
+          time_alarm = alarm.time.TimeAlarm(monotonic_time=time.monotonic() + 30)
+          alarm.exit_and_deep_sleep_until_alarms(time_alarm)
+        """
+        ...
+    monotonic_time: float
+    """When this time is reached, the alarm will trigger, based on the `time.monotonic()` clock.
+       The time may be given as ``epoch_time`` in the constructor, but it is returned
+       by this property only as a `time.monotonic()` time.
+       """

circuitpython_stubs-10.0.0a2/analogbufio/__init__.pyi

@@ -0,0 +1,84 @@
+"""Analog Buffered IO Hardware Support
+
+The `analogbufio` module contains classes to provide access to analog-to-digital
+conversion and digital-to-analog (DAC) for multiple value transfer.
+
+All classes change hardware state and should be deinitialized when they
+are no longer needed if the program continues after use. To do so, either
+call :py:meth:`!deinit` or use a context manager. See
+:ref:`lifetime-and-contextmanagers` for more info.
+
+TODO: For the essentials of `analogbufio`, see the `CircuitPython Essentials
+Learn guide <https://learn.adafruit.com/circuitpython-essentials/circuitpython-analogbufio>`_
+
+TODO: For more information on using `analogbufio`, see `this additional Learn guide
+<https://learn.adafruit.com/circuitpython-advanced-analog-inputs-and-outputs>`_
+"""
+
+from __future__ import annotations
+
+import microcontroller
+from circuitpython_typing import WriteableBuffer
+
+class BufferedIn:
+    """Capture multiple analog voltage levels to the supplied buffer
+
+    Usage::
+
+        import board
+        import analogbufio
+        import array
+
+        length = 1000
+        mybuffer = array.array("H", [0x0000] * length)
+        rate = 500000
+        adcbuf = analogbufio.BufferedIn(board.GP26, sample_rate=rate)
+        adcbuf.readinto(mybuffer)
+        adcbuf.deinit()
+        for i in range(length):
+            print(i, mybuffer[i])
+
+        (TODO) The reference voltage varies by platform so use
+        ``reference_voltage`` to read the configured setting.
+        (TODO) Provide mechanism to read CPU Temperature."""
+
+    def __init__(self, pin: microcontroller.Pin, *, sample_rate: int) -> None:
+        """Create a `BufferedIn` on the given pin and given sample rate.
+
+        :param ~microcontroller.Pin pin: the pin to read from
+        :param ~int sample_rate: rate: sampling frequency, in samples per second
+
+        **Limitations**: On many boards with a CYW43 radio module, such as Pico W,
+        GPIO29 (often ``board.A3``) is also used to control the CYW43,
+        and is therefore not available to use as the `BufferedIn` pin.
+        """
+        ...
+
+    def deinit(self) -> None:
+        """Shut down the `BufferedIn` and release the pin for other use."""
+        ...
+
+    def __enter__(self) -> BufferedIn:
+        """No-op used by Context Managers."""
+        ...
+
+    def __exit__(self) -> None:
+        """Automatically deinitializes the hardware when exiting a context. See
+        :ref:`lifetime-and-contextmanagers` for more info."""
+        ...
+
+    def readinto(self, buffer: WriteableBuffer, loop: bool = False) -> int:
+        """Fills the provided buffer with ADC voltage values.
+
+        ADC values will be read into the given buffer at the supplied sample_rate.
+        Depending on the buffer typecode, 'B', 'H', samples are 8-bit byte-arrays or
+        16-bit half-words and are always unsigned.
+        (See https://docs.circuitpython.org/en/latest/docs/library/array.html)
+        For 8-bit samples, the most significant bits of the 12-bit ADC values are kept.
+        For 16-bit samples, if loop=False, the 12-bit ADC values are scaled up to fill the 16 bit range.
+        If loop=True, ADC values are stored without scaling.
+
+        :param ~circuitpython_typing.WriteableBuffer buffer: buffer: A buffer for samples
+        :param ~bool loop: loop: Set to true for continuous conversions, False to fill buffer once then stop
+        """
+        ...

circuitpython_stubs-10.0.0a2/analogio/__init__.pyi

@@ -0,0 +1,126 @@
+"""Analog hardware support
+
+The `analogio` module contains classes to provide access to analog IO
+typically implemented with digital-to-analog (DAC) and analog-to-digital
+(ADC) converters.
+
+All classes change hardware state and should be deinitialized when they
+are no longer needed if the program continues after use. To do so, either
+call :py:meth:`!deinit` or use a context manager. See
+:ref:`lifetime-and-contextmanagers` for more info.
+
+For example::
+
+  import analogio
+  from board import *
+
+  pin = analogio.AnalogIn(A0)
+  print(pin.value)
+  pin.deinit()
+
+This example will initialize the the device, read
+:py:data:`~analogio.AnalogIn.value` and then
+:py:meth:`~analogio.AnalogIn.deinit` the hardware. The last step is optional
+because CircuitPython will do it automatically after the program finishes.
+
+For the essentials of `analogio`, see the `CircuitPython Essentials
+Learn guide <https://learn.adafruit.com/circuitpython-essentials/circuitpython-analog-in>`_
+
+For more information on using `analogio`, see `this additional Learn guide
+<https://learn.adafruit.com/circuitpython-basics-analog-inputs-and-outputs>`_
+"""
+
+from __future__ import annotations
+
+import microcontroller
+
+class AnalogIn:
+    """Read analog voltage levels
+
+    Usage::
+
+       import analogio
+       from board import *
+
+       adc = analogio.AnalogIn(A1)
+       val = adc.value"""
+
+    def __init__(self, pin: microcontroller.Pin) -> None:
+        """Use the AnalogIn on the given pin. The reference voltage varies by
+        platform so use ``reference_voltage`` to read the configured setting.
+
+        :param ~microcontroller.Pin pin: the pin to read from
+
+        **Limitations:** On Espressif ESP32, pins that use ADC2 are not available when WiFi is enabled:
+        the hardware makes use of ADC2.
+        Attempts to use `AnalogIn` in that situation will raise `espidf.IDFError`.
+        On other Espressif chips, ADC2 is available, but is shared with WiFi.
+        WiFi use takes precedence and may temporarily cause `espidf.IDFError` to be raised
+        when you read a value. You can retry the read.
+        """
+        ...
+
+    def deinit(self) -> None:
+        """Turn off the AnalogIn and release the pin for other use."""
+        ...
+
+    def __enter__(self) -> AnalogIn:
+        """No-op used by Context Managers."""
+        ...
+
+    def __exit__(self) -> None:
+        """Automatically deinitializes the hardware when exiting a context. See
+        :ref:`lifetime-and-contextmanagers` for more info."""
+        ...
+    value: int
+    """The value on the analog pin between 0 and 65535 inclusive (16-bit). (read-only)
+
+    Even if the underlying analog to digital converter (ADC) is lower
+    resolution, the value is 16-bit."""
+    reference_voltage: float
+    """The maximum voltage measurable (also known as the reference voltage) as a
+    ``float`` in Volts.  Note the ADC value may not scale to the actual voltage linearly
+    at ends of the analog range."""
+
+class AnalogOut:
+    """Output analog values (a specific voltage).
+
+    **Limitations:** Not available on Nordic, RP2040, Spresense, as there is no on-chip DAC.
+    On Espressif, available only on ESP32 and ESP32-S2; other chips do not have a DAC.
+    On ESP32-S2 boards, GPIO18 (DAC2) is often connected to a pull-up resistor, which causes
+    `unexpected output values in the lower part of the output range
+    <https://github.com/adafruit/circuitpython/issues/7871>`_.
+
+    Example usage::
+
+        import analogio
+        from board import *
+
+        dac = analogio.AnalogOut(A2)                # output on pin A2
+        dac.value = 32768                           # makes A2 1.65V"""
+
+    def __init__(self, pin: microcontroller.Pin) -> None:
+        """Use the AnalogOut on the given pin.
+
+        :param ~microcontroller.Pin pin: the pin to output to
+
+        """
+        ...
+
+    def deinit(self) -> None:
+        """Turn off the AnalogOut and release the pin for other use."""
+        ...
+
+    def __enter__(self) -> AnalogOut:
+        """No-op used by Context Managers."""
+        ...
+
+    def __exit__(self) -> None:
+        """Automatically deinitializes the hardware when exiting a context. See
+        :ref:`lifetime-and-contextmanagers` for more info."""
+        ...
+    value: int
+    """The value on the analog pin between 0 and 65535 inclusive (16-bit). (write-only)
+
+    Even if the underlying digital to analog converter (DAC) is lower
+    resolution, the value is 16-bit."""

circuitpython_stubs-10.0.0a2/audiofilters/__init__.pyi

@@ -0,0 +1,208 @@
+"""Support for audio filter effects
+
+The `audiofilters` module contains classes to provide access to audio filter effects.
+
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Tuple
+
+import circuitpython_typing
+import synthio
+
+class DistortionMode:
+    """The method of distortion used by the `audiofilters.Distortion` effect."""
+
+    CLIP: DistortionMode
+    """Digital distortion effect which cuts off peaks at the top and bottom of the waveform."""
+
+    LOFI: DistortionMode
+    """Low-resolution digital distortion effect (bit depth reduction). You can use it to emulate the sound of early digital audio devices."""
+
+    OVERDRIVE: DistortionMode
+    """Emulates the warm distortion produced by a field effect transistor, which is commonly used in solid-state musical instrument amplifiers. The `audiofilters.Distortion.drive` property has no effect in this mode."""
+
+    WAVESHAPE: DistortionMode
+    """Waveshaper distortions are used mainly by electronic musicians to achieve an extra-abrasive sound."""
+
+class Distortion:
+    """A Distortion effect"""
+
+    def __init__(
+        self,
+        drive: synthio.BlockInput = 0.0,
+        pre_gain: synthio.BlockInput = 0.0,
+        post_gain: synthio.BlockInput = 0.0,
+        mode: DistortionMode = DistortionMode.CLIP,
+        soft_clip: bool = False,
+        mix: synthio.BlockInput = 1.0,
+        buffer_size: int = 512,
+        sample_rate: int = 8000,
+        bits_per_sample: int = 16,
+        samples_signed: bool = True,
+        channel_count: int = 1,
+    ) -> None:
+        """Create a Distortion effect where the original sample is manipulated to create a distorted
+           sound according to the DistortionMode.
+
+           The mix parameter allows you to change how much of the unchanged sample passes through to
+           the output to how much of the effect audio you hear as the output.
+
+        :param synthio.BlockInput drive: Distortion power. Value can range from 0.0 to 1.0.
+        :param synthio.BlockInput pre_gain: Increases or decreases the volume before the effect, in decibels. Value can range from -60 to 60.
+        :param synthio.BlockInput post_gain: Increases or decreases the volume after the effect, in decibels. Value can range from -80 to 24.
+        :param DistortionMode mode: Distortion type.
+        :param bool soft_clip: Whether or not to soft clip (True) or hard clip (False) the output.
+        :param synthio.BlockInput mix: The mix as a ratio of the sample (0.0) to the effect (1.0).
+        :param int buffer_size: The total size in bytes of each of the two playback buffers to use
+        :param int sample_rate: The sample rate to be used
+        :param int channel_count: The number of channels the source samples contain. 1 = mono; 2 = stereo.
+        :param int bits_per_sample: The bits per sample of the effect
+        :param bool samples_signed: Effect is signed (True) or unsigned (False)
+
+        Playing adding a distortion to a synth::
+
+          import time
+          import board
+          import audiobusio
+          import synthio
+          import audiofilters
+
+          audio = audiobusio.I2SOut(bit_clock=board.GP20, word_select=board.GP21, data=board.GP22)
+          synth = synthio.Synthesizer(channel_count=1, sample_rate=44100)
+          effect = audiofilters.Distortion(drive=0.5, mix=1.0, buffer_size=1024, channel_count=1, sample_rate=44100)
+          effect.play(synth)
+          audio.play(effect)
+
+          note = synthio.Note(261)
+          while True:
+              synth.press(note)
+              time.sleep(0.25)
+              synth.release(note)
+              time.sleep(5)"""
+        ...
+
+    def deinit(self) -> None:
+        """Deinitialises the Distortion."""
+        ...
+
+    def __enter__(self) -> Distortion:
+        """No-op used by Context Managers."""
+        ...
+
+    def __exit__(self) -> None:
+        """Automatically deinitializes when exiting a context. See
+        :ref:`lifetime-and-contextmanagers` for more info."""
+        ...
+    drive: synthio.BlockInput
+    """Distortion power. Value can range from 0.0 to 1.0."""
+    pre_gain: synthio.BlockInput
+    """Increases or decreases the volume before the effect, in decibels. Value can range from -60 to 60."""
+    post_gain: synthio.BlockInput
+    """Increases or decreases the volume after the effect, in decibels. Value can range from -80 to 24."""
+    mode: DistortionMode
+    """Distortion type."""
+    soft_clip: bool
+    """Whether or not to soft clip (True) or hard clip (False) the output."""
+    mix: synthio.BlockInput
+    """The rate the filtered signal mix between 0 and 1 where 0 is only sample and 1 is all effect."""
+    playing: bool
+    """True when the effect is playing a sample. (read-only)"""
+
+    def play(
+        self, sample: circuitpython_typing.AudioSample, *, loop: bool = False
+    ) -> None:
+        """Plays the sample once when loop=False and continuously when loop=True.
+        Does not block. Use `playing` to block.
+
+        The sample must match the encoding settings given in the constructor."""
+        ...
+
+    def stop(self) -> None:
+        """Stops playback of the sample."""
+        ...
+
+class Filter:
+    """A Filter effect"""
+
+    def __init__(
+        self,
+        filter: Optional[synthio.Biquad | Tuple[synthio.Biquad]] = None,
+        mix: synthio.BlockInput = 1.0,
+        buffer_size: int = 512,
+        sample_rate: int = 8000,
+        bits_per_sample: int = 16,
+        samples_signed: bool = True,
+        channel_count: int = 1,
+    ) -> None:
+        """Create a Filter effect where the original sample is processed through a biquad filter
+           created by a synthio.Synthesizer object. This can be used to generate a low-pass,
+           high-pass, or band-pass filter.
+
+           The mix parameter allows you to change how much of the unchanged sample passes through to
+           the output to how much of the effect audio you hear as the output.
+
+        :param Optional[synthio.Biquad|Tuple[synthio.Biquad]] filter: A normalized biquad filter object or tuple of normalized biquad filter objects. The sample is processed sequentially by each filter to produce the output samples.
+        :param synthio.BlockInput mix: The mix as a ratio of the sample (0.0) to the effect (1.0).
+        :param int buffer_size: The total size in bytes of each of the two playback buffers to use
+        :param int sample_rate: The sample rate to be used
+        :param int channel_count: The number of channels the source samples contain. 1 = mono; 2 = stereo.
+        :param int bits_per_sample: The bits per sample of the effect
+        :param bool samples_signed: Effect is signed (True) or unsigned (False)
+
+        Playing adding a filter to a synth::
+
+          import time
+          import board
+          import audiobusio
+          import synthio
+          import audiofilters
+
+          audio = audiobusio.I2SOut(bit_clock=board.GP20, word_select=board.GP21, data=board.GP22)
+          synth = synthio.Synthesizer(channel_count=1, sample_rate=44100)
+          effect = audiofilters.Filter(buffer_size=1024, channel_count=1, sample_rate=44100, mix=1.0)
+          effect.filter = synth.low_pass_filter(frequency=2000, Q=1.25)
+          effect.play(synth)
+          audio.play(effect)
+
+          note = synthio.Note(261)
+          while True:
+              synth.press(note)
+              time.sleep(0.25)
+              synth.release(note)
+              time.sleep(5)"""
+        ...
+
+    def deinit(self) -> None:
+        """Deinitialises the Filter."""
+        ...
+
+    def __enter__(self) -> Filter:
+        """No-op used by Context Managers."""
+        ...
+
+    def __exit__(self) -> None:
+        """Automatically deinitializes when exiting a context. See
+        :ref:`lifetime-and-contextmanagers` for more info."""
+        ...
+    filter: synthio.Biquad | Tuple[synthio.Biquad] | None
+    """A normalized biquad filter object or tuple of normalized biquad filter objects. The sample is processed sequentially by each filter to produce the output samples."""
+
+    mix: synthio.BlockInput
+    """The rate the filtered signal mix between 0 and 1 where 0 is only sample and 1 is all effect."""
+    playing: bool
+    """True when the effect is playing a sample. (read-only)"""
+
+    def play(
+        self, sample: circuitpython_typing.AudioSample, *, loop: bool = False
+    ) -> None:
+        """Plays the sample once when loop=False and continuously when loop=True.
+        Does not block. Use `playing` to block.
+
+        The sample must match the encoding settings given in the constructor."""
+        ...
+
+    def stop(self) -> None:
+        """Stops playback of the sample."""
+        ...