piwave 2.0.3__py3-none-any.whl → 2.0.5__py3-none-any.whl

piwave/__init__.py

@@ -1,3 +1,5 @@
 # piwave/__init__.py
 
-from .piwave import PiWave
+from .piwave import PiWave
+
+__all__ = ["PiWave"]

piwave/piwave.py

@@ -1,4 +1,4 @@
-# piwave/piwave.py
+# piwave/pw.py
 # pi_fm_rds is required !!! Check https://github.com/ChristopheJacquet/PiFmRds
 
 import os
@@ -112,6 +112,30 @@ class PiWave:
                  debug: bool = False,
                  on_track_change: Optional[Callable] = None,
                  on_error: Optional[Callable] = None):
+        """Initialize PiWave FM transmitter.
+
+        :param frequency: FM frequency to broadcast on (80.0-108.0 MHz)
+        :type frequency: float
+        :param ps: Program Service name (max 8 characters)
+        :type ps: str
+        :param rt: Radio Text message (max 64 characters)
+        :type rt: str
+        :param pi: Program Identification code (4 hex digits)
+        :type pi: str
+        :param loop: Whether to loop the playlist when it ends
+        :type loop: bool
+        :param debug: Enable debug logging
+        :type debug: bool
+        :param on_track_change: Callback function called when track changes
+        :type on_track_change: Optional[Callable]
+        :param on_error: Callback function called when an error occurs
+        :type on_error: Optional[Callable]
+        :raises PiWaveError: If not running on Raspberry Pi or without root privileges
+        
+        .. note::
+           This class requires pi_fm_rds to be installed and accessible.
+           Must be run on a Raspberry Pi with root privileges.
+        """
         
         self.debug = debug
         self.frequency = frequency
@@ -422,6 +446,21 @@ class PiWave:
         os._exit(0)
 
     def add_files(self, files: List[str]) -> bool:
+        """Add audio files to the playlist.
+
+        :param files: List of file paths or URLs to add to the playlist
+        :type files: List[str]
+        :return: True if at least one file was successfully added, False otherwise
+        :rtype: bool
+        
+        .. note::
+           Files are automatically converted to WAV format if needed.
+           URLs are supported for streaming audio.
+        
+        Example:
+            >>> pw.add_files(['song1.mp3', 'song2.wav', 'http://stream.url'])
+        """
+
         converted_files = []
         
         for file_path in files:
@@ -442,6 +481,21 @@ class PiWave:
         return False
 
     def play(self, files: Optional[List[str]] = None) -> bool:
+        """Start playing the playlist or specified files.
+
+        :param files: Optional list of files to play. If provided, replaces current playlist
+        :type files: Optional[List[str]]
+        :return: True if playback started successfully, False otherwise
+        :rtype: bool
+        
+        .. note::
+           If no files are specified, plays the current playlist.
+           Automatically stops any current playback before starting.
+        
+        Example:
+            >>> pw.play(['song1.mp3', 'song2.wav'])  # Play specific files
+            >>> pw.play()  # Play current playlist
+        """
         if files:
             self.playlist.clear()
             self.current_index = 0
@@ -467,45 +521,129 @@ class PiWave:
         return True
 
     def stop(self):
+        """Stop all playback and streaming.
+
+        Stops the current playback, kills all related processes, and resets the player state.
+        This method is safe to call multiple times.
+        
+        Example:
+            >>> pw.stop()
+        """
         if not self.is_playing:
             return
         
-        Log.warning("Stopping playback")
+        Log.warning("Stopping playback...")
+
         self.is_stopped = True
         self.stop_event.set()
-        
-        self._stop_current_process()
-        
+
+        if self.current_process:
+            try:
+                os.killpg(os.getpgid(self.current_process.pid), signal.SIGTERM)
+                self.current_process.wait(timeout=5)
+            except Exception:
+                pass
+            finally:
+                self.current_process = None
+
+        if self.stream_process:
+            try:
+                os.killpg(os.getpgid(self.stream_process.pid), signal.SIGTERM)
+                self.stream_process.wait(timeout=5)
+            except Exception:
+                pass
+            finally:
+                self.stream_process = None
+
         if self.playback_thread and self.playback_thread.is_alive():
             self.playback_thread.join(timeout=5)
-        
+
         self.is_playing = False
         Log.success("Playback stopped")
 
     def pause(self):
+        """Pause the current playback.
+
+        Stops the current track but maintains the playlist position.
+        Use :meth:`resume` to continue playback.
+        
+        Example:
+            >>> pw.pause()
+        """
         if self.is_playing:
             self._stop_current_process()
             Log.info("Playback paused")
 
     def resume(self):
+        """Resume playback from the current position.
+
+        Continues playback from where it was paused or stopped.
+        
+        Example:
+            >>> pw.resume()
+        """
         if not self.is_playing and self.playlist:
             self.play()
 
     def next_track(self):
+        """Skip to the next track in the playlist.
+
+        If currently playing, stops the current track and advances to the next one.
+        
+        Example:
+            >>> pw.next_track()
+        """
         if self.is_playing:
             self._stop_current_process()
             self.current_index += 1
 
     def previous_track(self):
+        """Go back to the previous track in the playlist.
+
+        If currently playing, stops the current track and goes to the previous one.
+        Cannot go before the first track.
+        
+        Example:
+            >>> pw.previous_track()
+        """
         if self.is_playing:
             self._stop_current_process()
             self.current_index = max(0, self.current_index - 1)
 
     def set_frequency(self, frequency: float):
+        """Change the FM broadcast frequency.
+
+        :param frequency: New frequency in MHz (typically 88.0-108.0)
+        :type frequency: float
+        
+        .. note::
+           The frequency change will take effect on the next track or broadcast.
+        
+        Example:
+            >>> pw.set_frequency(101.5)
+        """
         self.frequency = frequency
         Log.broadcast_message(f"Frequency changed to {frequency}MHz. Will update on next file's broadcast.")
 
     def get_status(self) -> dict:
+        """Get current status information.
+
+        :return: Dictionary containing current player status
+        :rtype: dict
+        
+        The returned dictionary contains:
+        
+        - **is_playing** (bool): Whether playback is active
+        - **current_index** (int): Current position in playlist
+        - **playlist_length** (int): Total number of items in playlist
+        - **frequency** (float): Current broadcast frequency
+        - **current_file** (str|None): Path of currently playing file
+        
+        Example:
+            >>> status = pw.get_status()
+            >>> print(f"Playing: {status['is_playing']}")
+            >>> print(f"Track {status['current_index'] + 1} of {status['playlist_length']}")
+        """
         return {
             'is_playing': self.is_playing,
             'current_index': self.current_index,
@@ -515,6 +653,14 @@ class PiWave:
         }
 
     def cleanup(self):
+        """Clean up resources and temporary files.
+
+        Stops all playback, removes temporary files, and cleans up system resources.
+        This method is automatically called when the object is destroyed.
+        
+        Example:
+            >>> pw.cleanup()
+        """
         self.stop()
         
         if os.path.exists(self.temp_dir):
@@ -526,9 +672,38 @@ class PiWave:
         self.cleanup()
 
     def send(self, files: List[str]):
+        """Alias for the play method.
+
+        :param files: List of file paths or URLs to play
+        :type files: List[str]
+        :return: True if playback started successfully, False otherwise
+        :rtype: bool
+        
+        .. note::
+           This is an alias for :meth:`play` for backward compatibility.
+        
+        Example:
+            >>> pw.send(['song1.mp3', 'song2.wav'])
+        """
         return self.play(files)
 
     def restart(self):
+        """Restart playback from the beginning of the playlist.
+
+        Resets the current position to the first track and starts playback.
+        Only works if there are files in the playlist.
+        
+        Example:
+            >>> pw.restart()
+        """
         if self.playlist:
             self.current_index = 0
-            self.play()
+            self.play()
+
+if __name__ == "__main__":
+    Log.header("PiWave Radio Module")
+    Log.info("This module is designed to run on a Raspberry Pi with root privileges.")
+    Log.info("Please import this module in your main application to use its features.")
+    Log.info("Exiting PiWave module")
+
+__all__ = ["PiWave"]

{piwave-2.0.3.dist-info → piwave-2.0.5.dist-info}/METADATA

@@ -1,38 +1,29 @@
 Metadata-Version: 2.4
 Name: piwave
-Version: 2.0.3
-Summary: A python module to broacast radio waves with your Raspberry Pi.
+Version: 2.0.5
+Summary: A python module to broadcast radio waves with your Raspberry Pi.
 Home-page: https://github.com/douxxtech/piwave
 Author: Douxx
 Author-email: douxx@douxx.tech
+License: GPL-3.0-or-later
 Project-URL: Bug Reports, https://github.com/douxxtech/piwave/issues
 Project-URL: Source, https://github.com/douxxtech/piwave
 Keywords: raspberry pi,radio,fm,rds,streaming,audio,broadcast
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
 Classifier: Operating System :: POSIX :: Linux
 Requires-Python: >=3.7
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: pathlib
 Provides-Extra: dev
 Requires-Dist: pytest>=6.0; extra == "dev"
 Requires-Dist: pytest-cov>=2.0; extra == "dev"
 Requires-Dist: black>=22.0; extra == "dev"
 Requires-Dist: flake8>=4.0; extra == "dev"
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: keywords
 Dynamic: license-file
-Dynamic: project-url
-Dynamic: provides-extra
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
 
 <div align=center>
 <img alt="PiWave image" src="https://piwave.xyz/static/img/logo.png"/>
@@ -51,11 +42,6 @@ Dynamic: summary
 - Supports streaming from URLs.
 - Better error handling and event callbacks.
 - Non-blocking playback with threading.
-- Temporary file management for streamed content.
-
-> [!NOTE]
-> Are you looking for a minimal GUI for PiWave?
-> Take a look at the [PiWave WebGUI](https://github.com/douxxtech/piwave-webgui)
 
 ## Hardware Installation
 

piwave-2.0.5.dist-info/RECORD

@@ -0,0 +1,7 @@
+piwave/__init__.py,sha256=tAmruZvneieh6fgkf7chKzOX9Q6fEB-5Jt9FJ7Fl5xQ,74
+piwave/piwave.py,sha256=NzSCOGaHCEquWYQvxlaYvnn4zRfx13vuCWBX6ETPEXA,24378
+piwave-2.0.5.dist-info/licenses/LICENSE,sha256=IwGE9guuL-ryRPEKi6wFPI_zOhg7zDZbTYuHbSt_SAk,35823
+piwave-2.0.5.dist-info/METADATA,sha256=ANndDO8Kds5p9NZZD1ZMEVTBzxs3ZU2o59-QCBhf_YQ,6768
+piwave-2.0.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+piwave-2.0.5.dist-info/top_level.txt,sha256=xUbZ7Rk6OymSdDxmb9bfO8N-avJ9VYxP41GnXfwKYi8,7
+piwave-2.0.5.dist-info/RECORD,,

piwave-2.0.3.dist-info/RECORD

@@ -1,7 +0,0 @@
-piwave/__init__.py,sha256=lYEG0hZ7Khm0mMbVjVNLatI9YnKrHo_P5SWkN8eXmBk,50
-piwave/piwave.py,sha256=oyxm0ggPtiHuca2TdsEjHN4hFAzRTVAnYEjaea0iQ-c,18031
-piwave-2.0.3.dist-info/licenses/LICENSE,sha256=IwGE9guuL-ryRPEKi6wFPI_zOhg7zDZbTYuHbSt_SAk,35823
-piwave-2.0.3.dist-info/METADATA,sha256=G8Z7lH8sSlwaIAiVwljZJrRwJx66m66FbZrhweBQ_vw,7041
-piwave-2.0.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-piwave-2.0.3.dist-info/top_level.txt,sha256=xUbZ7Rk6OymSdDxmb9bfO8N-avJ9VYxP41GnXfwKYi8,7
-piwave-2.0.3.dist-info/RECORD,,