Metadata-Version: 2.1
Name: dingpy
Version: 1.0.6
Summary: parameter name standardize
Home-page: https://github.com/tinahbu/dingpy
Author: Tina Bu
Author-email: tina.hongbu@gmail.com
License: MIT license
Description: # DingPy 🛎 
        
        [![GitHub license](https://img.shields.io/github/license/tinahbu/dingpy)](https://github.com/tinahbu/dingpy/blob/master/LICENSE)
        [![pypi](https://img.shields.io/badge/pypi-1.0.0-blue)](https://pypi.org/project/dingpy/)
        
        A Python package that plays an audio alert when your program finishes, especially helpful for long running jobs and impatient developers.
        
        ## Examples 
        
        ```
        import dingpy
        
        dingpy.ding()  # plays the default alarm 'japanese_temple_bell'
        
        # to use a different alarm sound:
        dingpy.ding(sound='music_box')
        
        # to list all available alarms
        dingpy.list_alarms()
        ```
        
        ## Alarm Options
        
        `Dingpy` comes pre-loaded with 10 royalty free alarm sounds (downloaded from http://soundbible.com/) and you can choose which one to use via the `sound` parameter.
        
        - `'beep'`
        - `'bell_tibetan'`
        - `'birds'`
        - `'clock_chimes'`
        - `'computer_magic'`
        - `'japanese_temple_bell'`
        - `'music_box'`
        - `'school_bell'`
        - `'service_bell'`
        - `'tinkle'`
        
        The 10 audio files are packaged and downloaded when you install `dingpy`. You can further customize `dingpy` by asking it to use a mp3 file from your local directory via the `path` parameter:
        
        ```
        dingpy.ding(path='/absolute_path_to_file/sound.mp3')
        ```
        
        If you'd like to contribute your mp3 file for other `dingpy` users to access, you can upload it to the public `dingpy` s3 bucket:
        
        ```
        # sound_name needs to be globally unique
        dingpy.upload_alarm(
            file_path='/absolute_path_to_file/sound.mp3', 
            sound_name='beeep') 
        
        # verify that your upload is successful by calling list_alarms again
        # and tell it to look for all alarms 
        # (without all=True list_alarms will only return the 10 pre-built sounds)
        dingpy.list_alarms(all=True)
        ```
        
        After your mp3 file is uploaded, they can be used by other people if they pass in the sound name and set the `s3` parameter to be `True`:
        
        ```
        dingpy.ding(sound='beeep', s3=True)
        ```
        
        Note that the mp3 file will be downloaded each time `dingpy.ding()` is called. 
        
        To delete an uploaded alarm (the 10 pre-loaded alarms can't be deleted):
        
        ```
        dingpy.delete_alarm('beeep')
        ```
        
        ## Installation 
        
        `DingPy` can be installed via `pip` like this
        
        ```
        $ pip install dingpy
        ```
        
        or from the source code like this
        
        ```
        $ pip install git+https://github.com/tinahbu/dingpy.git
        ```
        
        or this
        
        ```
        $ git clone git@github.com:tinahbu/dingpy.git
        $ cd dingpy
        $ python setup.py install
        ```
        
        ## Prerequisite
        
        For the `pydub` library to work with non-`wav` files like `mp3`, you will need to have `ffmpeg` or `libav` installed locally.
        
        ```
        $ # install ffmpeg
        $ # for Mac
        $ brew install ffmpeg --with-theora
        $ 
        $ # for Linux
        $ apt-get install ffmpeg libavcodec-extra
        ```
        
        ```
        $ # install libav
        $ # for Mac
        $ brew install libav --with-libvorbis --with-sdl --with-theora
        $ 
        $ # for Linux
        $ apt-get install libav-tools libavcodec-extra
        ```
        
        As stated above, the 10 default alarms are packaged with `dingpy` but user uploaded alarms are hosted in a public s3 bucket. So if you'd like to use the customization feature you will have to have aws cli configured. To do that, follow the doc [here](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html).
        
        `dingpy` only works with Python3.
        
        ## Future Work
        
        - Make available on conda
        - Support other audio formats besides mp3
        - Support text to speech alerts
        - Integrate with `pync` to send MacOS notifications 
        - Local ding for jobs running on remote machines
        
        
        ## Inspirations <a name="inspirations"></a>
        
        I always wanted a Python package that notifies me with a ding when my code completes so I can go about doing other work in the meantime. I couldn't really find one after quite some research so I decided to create `dingpy` for myself. And hopefully it will be helpful to you as well. That being said, if most of your work happens in the terminal or if you prefer to have a pop-up MacOS notification than an audible alarm, do checkout the projects below:
        
        - [`pync`](https://pypi.org/project/pync/) a Python package to send MacOS notifications (Mac only) (it claims to offer sound notification with the pop-up notification but I couldn't make it work)
        - [`ding`](https://github.com/xxv/ding/) a CLI alarm tool for local and remote jobs (it seems that you will have to provide your own alarm audio file and keep a terminal open running this code the whole time for the alarm to work. not a python package that can be imported)
        - [`woof`](https://github.com/msbarry/woof) a set of CLI tools to send notifications (options: music, growl notification, text message, tweet, twitter DM, email, and text-to-speech) (Mac only) (have to save alarm audio locally and modify bash profile to set proper paths, only works in the terminal)
        - [`notify2`](https://bitbucket.org/takluyver/pynotify2/src) a Python package that sends a MacOS notification (seems not maintained, after installation I got import error for `dbus` and wasn't able to install `dbus` properlly to test it out)
        
        
Keywords: notification,alarm,alert
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Description-Content-Type: text/markdown
