Sound

API Reference - Sound

Complete API reference for the wolpie.sound module.

play_sound

Attributes

logger module-attribute

logger = getLogger(__name__)

DEFAULT_DING_FILE module-attribute

DEFAULT_DING_FILE = parent / 'ding.mp3'

SUPPORTED_PLATFORMS module-attribute

SUPPORTED_PLATFORMS = ['Windows']

play_sound module-attribute

play_sound = _play_sound

Classes

PlaySoundError

Bases: Exception

PlaySoundInterface

Bases: ABC

WinPlaySound

Bases: PlaySoundInterface

NotImplementedPlaySound

Bases: PlaySoundInterface

Functions

ding

ding(sound=DEFAULT_DING_FILE)

A context manager that plays a "ding" sound when the block of code inside the context manager finishes executing.

If if fails to play the "ding", it won't raise any errors. After all.. the whole idea of this context manager is to notify you when a long running function is done. Imagine you wait 2 hours just for the nice sound file to fail. And you have to start from scratch. No thanks.

Warning

This function is only officially supported on Windows.

Uses play_sound under the hood.

Example

from wolpie import ding
import time

# plays the default "ding" sound after the block finishes
with ding():
    time.sleep(10)  # Simulate some long running function

# or if you have a cooler ding:
with ding("path/to/cooler/ding.mp3"):
    time.sleep(10)  # Simulate some long running function

Tip

If you want sound files, consider https://pixabay.com/sound-effects/search

Parameters:

Name	Type	Description	Default
sound	str | Path	The sound file to play. Defaults to a built-in "ding" sound.	DEFAULT_DING_FILE

Yields:

Type	Description
None	Nothing.

Source code in src/wolpie/sound/play_sound.py

@contextmanager
def ding(
    sound: str | Path = DEFAULT_DING_FILE,
) -> Generator[None, None, None]:
    """A context manager that plays a "ding" sound when the block of code inside the context manager finishes executing.

    If if fails to play the "ding", it won't raise any errors. After all.. the whole idea of this context
    manager is to notify you when a long running function is done. Imagine you wait 2 hours
    just for the nice sound file to fail. And you have to start from scratch. No thanks.

    Warning:
        This function is only officially supported on Windows.

    Uses `play_sound` under the hood.

    Example:
        ```python
        from wolpie import ding
        import time

        # plays the default "ding" sound after the block finishes
        with ding():
            time.sleep(10)  # Simulate some long running function

        # or if you have a cooler ding:
        with ding("path/to/cooler/ding.mp3"):
            time.sleep(10)  # Simulate some long running function
        ```

    Tip:
        If you want sound files, consider https://pixabay.com/sound-effects/search

    Args:
        sound: The sound file to play. Defaults to a built-in "ding" sound.

    Yields:
        Nothing.
    """
    try:
        yield
    finally:
        try:
            play_sound(sound, block=True)
        except Exception as e:
            logger.warning(f"Failed to play sound {sound}: {e}")