piwave 2.0.3__tar.gz → 2.0.5__tar.gz

{piwave-2.0.3 → piwave-2.0.5}/PKG-INFO

@@ -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.3 → piwave-2.0.5}/README.md

@@ -15,11 +15,6 @@
 - 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/piwave/__init__.py

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

{piwave-2.0.3 → piwave-2.0.5}/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 → piwave-2.0.5}/piwave.egg-info/PKG-INFO

@@ -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.3 → piwave-2.0.5}/piwave.egg-info/SOURCES.txt

@@ -1,5 +1,7 @@
 LICENSE
 README.md
+pyproject.toml
+setup.cfg
 setup.py
 piwave/__init__.py
 piwave/piwave.py

{piwave-2.0.3 → piwave-2.0.5}/piwave.egg-info/requires.txt

@@ -1,4 +1,3 @@
-pathlib
 
 [dev]
 pytest>=6.0

piwave-2.0.5/pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"

piwave-2.0.5/setup.cfg

@@ -0,0 +1,39 @@
+[metadata]
+name = piwave
+version = 2.0.5
+description = A python module to broadcast radio waves with your Raspberry Pi.
+long_description = file: README.md
+long_description_content_type = text/markdown
+author = Douxx
+author_email = douxx@douxx.tech
+url = https://github.com/douxxtech/piwave
+license = GPL-3.0-or-later
+keywords = raspberry pi, radio, fm, rds, streaming, audio, broadcast
+classifiers = 
+	Development Status :: 5 - Production/Stable
+	Intended Audience :: Developers
+	Topic :: Software Development :: Libraries :: Python Modules
+	Programming Language :: Python :: 3
+	License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+	Operating System :: POSIX :: Linux
+project_urls = 
+	Bug Reports = https://github.com/douxxtech/piwave/issues
+	Source = https://github.com/douxxtech/piwave
+
+[options]
+packages = find:
+include_package_data = True
+install_requires = 
+python_requires = >=3.7
+
+[options.extras_require]
+dev = 
+	pytest>=6.0
+	pytest-cov>=2.0
+	black>=22.0
+	flake8>=4.0
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

piwave-2.0.5/setup.py

@@ -0,0 +1,3 @@
+from setuptools import setup
+
+setup()

piwave-2.0.3/piwave/__init__.py

@@ -1,3 +0,0 @@
-# piwave/__init__.py
-
-from .piwave import PiWave

piwave-2.0.3/setup.cfg

@@ -1,4 +0,0 @@
-[egg_info]
-tag_build = 
-tag_date = 0
-

piwave-2.0.3/setup.py

@@ -1,38 +0,0 @@
-# setup.py
-
-from setuptools import setup, find_packages
-
-setup(
-    name="piwave",
-    version="2.0.3",
-    description="A python module to broacast radio waves with your Raspberry Pi.",
-    long_description=open('README.md').read(),
-    long_description_content_type='text/markdown',
-    author="Douxx",
-    author_email="douxx@douxx.tech",
-    url="https://github.com/douxxtech/piwave",
-    packages=find_packages(),
-    include_package_data=True,
-    install_requires=[
-        "pathlib",
-    ],
-    extras_require={
-        "dev": [
-            "pytest>=6.0",
-            "pytest-cov>=2.0",
-            "black>=22.0",
-            "flake8>=4.0",
-        ],
-    },
-    classifiers=[
-        "Programming Language :: Python :: 3",
-        "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
-        "Operating System :: POSIX :: Linux",
-    ],
-    python_requires='>=3.7',
-    keywords="raspberry pi, radio, fm, rds, streaming, audio, broadcast",
-    project_urls={
-        "Bug Reports": "https://github.com/douxxtech/piwave/issues",
-        "Source": "https://github.com/douxxtech/piwave",
-    }
-)