winipedia-utils 0.1.39__py3-none-any.whl → 0.1.40__py3-none-any.whl

winipedia_utils/pyside/ui/pages/browser.py

@@ -14,11 +14,17 @@ class Browser(BasePage):
 
     @final
     def setup(self) -> None:
-        """Setup the UI."""
-        # add a download button in the top right
+        """Setup the UI.
+
+        Initializes the browser page by adding a browser widget to the layout.
+        """
         self.add_brwoser()
 
     @final
     def add_brwoser(self) -> None:
-        """Add a browser to surfe the web."""
+        """Add a browser to surf the web.
+
+        Creates and adds a BrowserWidget instance to the vertical layout,
+        enabling web browsing functionality within the page.
+        """
         self.browser = BrowserWidget(self.v_layout)

winipedia_utils/pyside/ui/pages/player.py

@@ -3,8 +3,12 @@
 This module contains the player page class for the VideoVault application.
 """
 
+from abc import abstractmethod
+from collections.abc import Callable
 from pathlib import Path
-from typing import final
+from typing import Any, final
+
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
 
 from winipedia_utils.pyside.ui.pages.base.base import Base as BasePage
 from winipedia_utils.pyside.ui.widgets.media_player import MediaPlayer
@@ -13,15 +17,58 @@ from winipedia_utils.pyside.ui.widgets.media_player import MediaPlayer
 class Player(BasePage):
     """Player page for the VideoVault application."""
 
+    @abstractmethod
+    def start_playback(self, path: Path) -> None:
+        """Start the playback.
+
+        Args:
+            path: The file path to start playback for.
+        """
+
     @final
     def setup(self) -> None:
-        """Setup the UI."""
+        """Setup the UI.
+
+        Initializes the media player widget and adds it to the layout.
+        """
         self.media_player = MediaPlayer(self.v_layout)
 
     @final
-    def play_file(self, path: Path) -> None:
-        """Play the video."""
+    def play_file_from_func(
+        self, play_func: Callable[..., Any], path: Path, **kwargs: Any
+    ) -> None:
+        """Play a file using the specified function.
+
+        Sets the current page to player and calls the provided play function
+        with the given path and additional arguments.
+
+        Args:
+            play_func: The function to call for playing the file.
+            path: The file path to play.
+            **kwargs: Additional keyword arguments to pass to the play function.
+        """
         # set current page to player
         self.set_current_page(self.__class__)
         # Stop current playback and clean up resources
-        self.media_player.play_file(path)
+        play_func(path, **kwargs)
+
+    @final
+    def play_file(self, path: Path) -> None:
+        """Play a regular video file.
+
+        Args:
+            path: The file path to play.
+        """
+        self.play_file_from_func(self.media_player.play_file, path)
+
+    @final
+    def play_encrypted_file(self, path: Path, aes_gcm: AESGCM) -> None:
+        """Play an encrypted video file.
+
+        Args:
+            path: The encrypted file path to play.
+            aes_gcm: The AES-GCM cipher instance for decryption.
+        """
+        self.play_file_from_func(
+            self.media_player.play_encrypted_file, path, aes_gcm=aes_gcm
+        )

winipedia_utils/pyside/ui/widgets/browser.py

@@ -26,7 +26,13 @@ class Browser(QWebEngineView):
     """Browser class that creates a simple ready to use browser and not just a view."""
 
     def __init__(self, parent_layout: QLayout, *args: Any, **kwargs: Any) -> None:
-        """Initialize the browser."""
+        """Initialize the browser.
+
+        Args:
+            parent_layout: The parent layout to add the browser widget to.
+            *args: Additional positional arguments passed to parent constructor.
+            **kwargs: Additional keyword arguments passed to parent constructor.
+        """
         super().__init__(*args, **kwargs)
         self.parent_layout = parent_layout
         self.make_widget()
@@ -34,7 +40,11 @@ class Browser(QWebEngineView):
         self.load_first_url()
 
     def make_address_bar(self) -> None:
-        """Make the address bar."""
+        """Make the address bar.
+
+        Creates a horizontal layout containing back button, forward button,
+        address input field, and go button for browser navigation.
+        """
         self.address_bar_layout = QHBoxLayout()
 
         # Add back button
@@ -65,12 +75,19 @@ class Browser(QWebEngineView):
         self.browser_layout.addLayout(self.address_bar_layout)
 
     def navigate_to_url(self) -> None:
-        """Navigate to the URL entered in the address bar."""
+        """Navigate to the URL entered in the address bar.
+
+        Takes the URL from the address bar text field and loads it in the browser.
+        """
         url = self.address_bar.text()
         self.load(QUrl(url))
 
     def make_widget(self) -> None:
-        """Make the widget."""
+        """Make the widget.
+
+        Creates the main browser widget with vertical layout, sets size policy,
+        creates the address bar, and adds components to the parent layout.
+        """
         self.browser_widget = QWidget()
         self.browser_layout = QVBoxLayout(self.browser_widget)
         self.set_size_policy()
@@ -79,53 +96,99 @@ class Browser(QWebEngineView):
         self.parent_layout.addWidget(self.browser_widget)
 
     def set_size_policy(self) -> None:
-        """Set the size policy."""
+        """Set the size policy.
+
+        Sets the browser to expand in both horizontal and vertical directions.
+        """
         self.setSizePolicy(QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Expanding)
 
     def connect_signals(self) -> None:
-        """Connect the signals."""
+        """Connect the signals.
+
+        Connects load finished signal and cookie added signal handlers.
+        """
         self.connect_load_finished_signal()
         self.connect_on_cookie_added_signal()
 
     def connect_load_finished_signal(self) -> None:
-        """Connect the load finished signal."""
-        self.loadFinished.connect(self.on_load_finished)
+        """Connect the load finished signal.
 
-    def on_load_finished(self, _ok: bool) -> None:  # noqa: FBT001
-        """Handle the load finished signal."""
+        Connects the loadStarted signal to the on_load_started handler.
+        """
+        self.loadStarted.connect(self.on_load_started)
+
+    def on_load_started(self, _ok: bool) -> None:  # noqa: FBT001
+        """Handle the load finished signal.
+
+        Args:
+            _ok: Boolean indicating if the load was successful (unused).
+        """
         self.update_address_bar(self.url())
 
     def update_address_bar(self, url: QUrl) -> None:
-        """Update the address bar with the current URL."""
+        """Update the address bar with the current URL.
+
+        Args:
+            url: The QUrl to display in the address bar.
+        """
         self.address_bar.setText(url.toString())
 
     def connect_on_cookie_added_signal(self) -> None:
-        """Connect the on cookie added signal."""
+        """Connect the on cookie added signal.
+
+        Initializes the cookies dictionary and connects the cookieAdded signal
+        to the on_cookie_added handler.
+        """
         self.cookies: dict[str, list[QNetworkCookie]] = defaultdict(list)
         self.page().profile().cookieStore().cookieAdded.connect(self.on_cookie_added)
 
     def on_cookie_added(self, cookie: Any) -> None:
-        """Handle the on cookie added signal."""
+        """Handle the on cookie added signal.
+
+        Args:
+            cookie: The QNetworkCookie that was added.
+        """
         self.cookies[cookie.domain()].append(cookie)
 
     def load_first_url(self) -> None:
-        """Load the first URL."""
+        """Load the first URL.
+
+        Loads Google's homepage as the initial page when the browser starts.
+        """
         self.load(QUrl("https://www.google.com/"))
 
     @property
     def http_cookies(self) -> dict[str, list[Cookie]]:
-        """Get the http cookies for the given URL."""
+        """Get the http cookies for all domains.
+
+        Returns:
+            Dictionary mapping domain names to lists of http.cookiejar.Cookie objects.
+        """
         return {
             domain: self.qcookies_to_httpcookies(qcookies)
             for domain, qcookies in self.cookies.items()
         }
 
     def qcookies_to_httpcookies(self, qcookies: list[QNetworkCookie]) -> list[Cookie]:
-        """Convert a list of QNetworkCookies to a CookieJar."""
+        """Convert a list of QNetworkCookies to http.cookiejar.Cookie objects.
+
+        Args:
+            qcookies: List of QNetworkCookie objects to convert.
+
+        Returns:
+            List of converted http.cookiejar.Cookie objects.
+        """
         return [self.qcookie_to_httpcookie(q_cookie) for q_cookie in qcookies]
 
     def qcookie_to_httpcookie(self, qcookie: QNetworkCookie) -> Cookie:
-        """Convert a QNetworkCookie to a http.cookiejar.Cookie."""
+        """Convert a QNetworkCookie to a http.cookiejar.Cookie.
+
+        Args:
+            qcookie: The QNetworkCookie to convert.
+
+        Returns:
+            The converted http.cookiejar.Cookie object.
+        """
         name = bytes(qcookie.name().data()).decode()
         value = bytes(qcookie.value().data()).decode()
         domain = qcookie.domain()
@@ -157,10 +220,24 @@ class Browser(QWebEngineView):
         )
 
     def get_domain_cookies(self, domain: str) -> list[QNetworkCookie]:
-        """Get the cookies for the given domain."""
+        """Get the cookies for the given domain.
+
+        Args:
+            domain: The domain to get cookies for.
+
+        Returns:
+            List of QNetworkCookie objects for the specified domain.
+        """
         return self.cookies[domain]
 
     def get_domain_http_cookies(self, domain: str) -> list[Cookie]:
-        """Get the http cookies for the given domain."""
+        """Get the http cookies for the given domain.
+
+        Args:
+            domain: The domain to get cookies for.
+
+        Returns:
+            List of http.cookiejar.Cookie objects for the specified domain.
+        """
         cookies = self.get_domain_cookies(domain)
         return self.qcookies_to_httpcookies(cookies)

winipedia_utils/pyside/ui/widgets/clickable_widget.py

@@ -1,3 +1,9 @@
+"""Clickable widget module.
+
+This module contains clickable widget classes that emit signals when clicked.
+Provides both regular QWidget and QVideoWidget variants with click functionality.
+"""
+
 from typing import Any
 
 from PySide6.QtCore import Qt, Signal
@@ -6,24 +12,46 @@ from PySide6.QtWidgets import QWidget
 
 
 class ClickableWidget(QWidget):
-    """Widget that can be clicked."""
+    """Widget that can be clicked.
+
+    A QWidget subclass that emits a clicked signal when the left mouse
+    button is pressed on the widget.
+    """
 
     clicked = Signal()
 
     def mousePressEvent(self, event: Any) -> None:  # noqa: N802
-        """Handle mouse press event."""
+        """Handle mouse press event.
+
+        Emits the clicked signal when the left mouse button is pressed
+        and passes the event to the parent class.
+
+        Args:
+            event: The mouse press event containing button and position information.
+        """
         if event.button() == Qt.MouseButton.LeftButton:
             self.clicked.emit()
         super().mousePressEvent(event)
 
 
 class ClickableVideoWidget(QVideoWidget):
-    """Video widget that can be clicked."""
+    """Video widget that can be clicked.
+
+    A QVideoWidget subclass that emits a clicked signal when the left mouse
+    button is pressed on the video widget.
+    """
 
     clicked = Signal()
 
     def mousePressEvent(self, event: Any) -> None:  # noqa: N802
-        """Handle mouse press event."""
+        """Handle mouse press event.
+
+        Emits the clicked signal when the left mouse button is pressed
+        and passes the event to the parent class.
+
+        Args:
+            event: The mouse press event containing button and position information.
+        """
         if event.button() == Qt.MouseButton.LeftButton:
             self.clicked.emit()
         super().mousePressEvent(event)

winipedia_utils/pyside/ui/widgets/media_player.py

@@ -9,6 +9,7 @@ from functools import partial
 from pathlib import Path
 from typing import Any
 
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
 from PySide6.QtCore import Qt, QTimer, QUrl
 from PySide6.QtMultimedia import QAudioOutput, QMediaPlayer
 from PySide6.QtWidgets import (
@@ -22,7 +23,11 @@ from PySide6.QtWidgets import (
     QWidget,
 )
 
-from winipedia_utils.pyside.core.py_qiodevice import PyQFile, PyQIODevice
+from winipedia_utils.pyside.core.py_qiodevice import (
+    EncryptedPyQFile,
+    PyQFile,
+    PyQIODevice,
+)
 from winipedia_utils.pyside.ui.base.base import Base as BaseUI
 from winipedia_utils.pyside.ui.widgets.clickable_widget import ClickableVideoWidget
 
@@ -31,13 +36,23 @@ class MediaPlayer(QMediaPlayer):
     """Media player class."""
 
     def __init__(self, parent_layout: QLayout, *args: Any, **kwargs: Any) -> None:
-        """Initialize the media player."""
+        """Initialize the media player.
+
+        Args:
+            parent_layout: The parent layout to add the media player widget to.
+            *args: Additional positional arguments passed to parent constructor.
+            **kwargs: Additional keyword arguments passed to parent constructor.
+        """
         super().__init__(*args, **kwargs)
         self.parent_layout = parent_layout
         self.make_widget()
 
     def make_widget(self) -> None:
-        """Make the widget."""
+        """Make the widget.
+
+        Creates the main media player widget with vertical layout, adds media controls
+        above and below the video widget, and creates the video widget itself.
+        """
         self.media_player_widget = QWidget()
         self.media_player_layout = QVBoxLayout(self.media_player_widget)
         self.parent_layout.addWidget(self.media_player_widget)
@@ -46,7 +61,11 @@ class MediaPlayer(QMediaPlayer):
         self.add_media_controls_below()
 
     def make_video_widget(self) -> None:
-        """Make the video widget."""
+        """Make the video widget.
+
+        Creates a clickable video widget with expanding size policy, sets up
+        audio output, and connects the click signal to toggle media controls.
+        """
         self.video_widget = ClickableVideoWidget()
         self.video_widget.clicked.connect(self.on_video_clicked)
         self.video_widget.setSizePolicy(
@@ -60,24 +79,37 @@ class MediaPlayer(QMediaPlayer):
         self.media_player_layout.addWidget(self.video_widget)
 
     def on_video_clicked(self) -> None:
-        """Handle video widget click."""
+        """Handle video widget click.
+
+        Toggles the visibility of media controls when the video widget is clicked.
+        """
         if self.media_controls_widget_above.isVisible():
             self.hide_media_controls()
             return
         self.show_media_controls()
 
     def show_media_controls(self) -> None:
-        """Show media controls."""
+        """Show media controls.
+
+        Makes both the above and below media control widgets visible.
+        """
         self.media_controls_widget_above.show()
         self.media_controls_widget_below.show()
 
     def hide_media_controls(self) -> None:
-        """Hide media controls."""
+        """Hide media controls.
+
+        Hides both the above and below media control widgets.
+        """
         self.media_controls_widget_above.hide()
         self.media_controls_widget_below.hide()
 
     def add_media_controls_above(self) -> None:
-        """Add media controls above the video."""
+        """Add media controls above the video.
+
+        Creates the top control bar with left, center, and right sections,
+        then adds speed, volume, playback, and fullscreen controls.
+        """
         # main above widget
         self.media_controls_widget_above = QWidget()
         self.media_controls_layout_above = QHBoxLayout(self.media_controls_widget_above)
@@ -106,14 +138,21 @@ class MediaPlayer(QMediaPlayer):
         self.add_fullscreen_control()
 
     def add_media_controls_below(self) -> None:
-        """Add media controls below the video."""
+        """Add media controls below the video.
+
+        Creates the bottom control bar and adds the progress control slider.
+        """
         self.media_controls_widget_below = QWidget()
         self.media_controls_layout_below = QHBoxLayout(self.media_controls_widget_below)
         self.media_player_layout.addWidget(self.media_controls_widget_below)
         self.add_progress_control()
 
     def add_playback_control(self) -> None:
-        """Add playback control."""
+        """Add playback control.
+
+        Creates a play/pause button with appropriate icons and connects it
+        to the toggle_playback method. Adds the button to the center controls.
+        """
         self.play_icon = BaseUI.get_svg_icon("play_icon")
         self.pause_icon = BaseUI.get_svg_icon("pause_icon")
         # Pause symbol: ⏸ (U+23F8)
@@ -124,7 +163,11 @@ class MediaPlayer(QMediaPlayer):
         self.center_controls_layout.addWidget(self.playback_button)
 
     def toggle_playback(self) -> None:
-        """Toggle playback."""
+        """Toggle playback.
+
+        Switches between play and pause states, updating the button icon
+        accordingly based on the current playback state.
+        """
         if self.playbackState() == QMediaPlayer.PlaybackState.PlayingState:
             self.pause()
             self.playback_button.setIcon(self.play_icon)
@@ -135,7 +178,8 @@ class MediaPlayer(QMediaPlayer):
     def add_speed_control(self) -> None:
         """Add speed control.
 
-        A button in the top left that on click shows a dropdown to select the speed.
+        Creates a button in the top left that shows a dropdown menu to select
+        playback speed from predefined options (0.2x to 5x).
         """
         self.default_speed = 1
         self.speed_options = [0.2, 0.5, self.default_speed, 1.5, 2, 3, 4, 5]
@@ -149,24 +193,40 @@ class MediaPlayer(QMediaPlayer):
         self.left_controls_layout.addWidget(self.speed_button)
 
     def change_speed(self, speed: float) -> None:
-        """Change playback speed."""
+        """Change playback speed.
+
+        Args:
+            speed: The new playback speed multiplier.
+        """
         self.setPlaybackRate(speed)
         self.speed_button.setText(f"{speed}x")
 
     def add_volume_control(self) -> None:
-        """Add volume control."""
+        """Add volume control.
+
+        Creates a horizontal slider for volume control with range 0-100
+        and connects it to the volume change handler.
+        """
         self.volume_slider = QSlider(Qt.Orientation.Horizontal)
         self.volume_slider.setRange(0, 100)
         self.volume_slider.valueChanged.connect(self.on_volume_changed)
         self.left_controls_layout.addWidget(self.volume_slider)
 
     def on_volume_changed(self, value: int) -> None:
-        """Handle volume slider value change."""
+        """Handle volume slider value change.
+
+        Args:
+            value: The new volume value from 0-100.
+        """
         volume = value / 100.0  # Convert to 0.0-1.0 range
         self.audio_output.setVolume(volume)
 
     def add_fullscreen_control(self) -> None:
-        """Add fullscreen control."""
+        """Add fullscreen control.
+
+        Creates a fullscreen toggle button with appropriate icons and determines
+        which widgets to hide/show when entering/exiting fullscreen mode.
+        """
         self.fullscreen_icon = BaseUI.get_svg_icon("fullscreen_icon")
         self.exit_fullscreen_icon = BaseUI.get_svg_icon("exit_fullscreen_icon")
         self.fullscreen_button = QPushButton()
@@ -187,7 +247,11 @@ class MediaPlayer(QMediaPlayer):
         self.right_controls_layout.addWidget(self.fullscreen_button)
 
     def toggle_fullscreen(self) -> None:
-        """Toggle fullscreen mode."""
+        """Toggle fullscreen mode.
+
+        Switches between fullscreen and windowed mode, hiding/showing other
+        widgets and updating the button icon accordingly.
+        """
         # Get the main window
         main_window = self.media_player_widget.window()
         if main_window.isFullScreen():
@@ -203,7 +267,11 @@ class MediaPlayer(QMediaPlayer):
             self.fullscreen_button.setIcon(self.exit_fullscreen_icon)
 
     def add_progress_control(self) -> None:
-        """Add progress control."""
+        """Add progress control.
+
+        Creates a horizontal progress slider and connects it to media player
+        signals for position updates and user interaction handling.
+        """
         self.progress_slider = QSlider(Qt.Orientation.Horizontal)
         self.media_controls_layout_below.addWidget(self.progress_slider)
 
@@ -218,17 +286,32 @@ class MediaPlayer(QMediaPlayer):
         self.progress_slider.sliderReleased.connect(self.on_slider_released)
 
     def update_slider_position(self, position: int) -> None:
-        """Update the progress slider position."""
+        """Update the progress slider position.
+
+        Args:
+            position: The current media position in milliseconds.
+        """
         # Only update if not being dragged to prevent jumps during manual sliding
         if not self.progress_slider.isSliderDown():
             self.progress_slider.setValue(position)
 
     def set_slider_range(self, duration: int) -> None:
-        """Set the progress slider range based on media duration."""
+        """Set the progress slider range based on media duration.
+
+        Args:
+            duration: The total media duration in milliseconds.
+        """
         self.progress_slider.setRange(0, duration)
 
     def on_slider_moved(self, position: int) -> None:
-        """Set the media position when slider is moved."""
+        """Set the media position when slider is moved.
+
+        Implements throttling to prevent excessive position updates during
+        slider dragging for better performance.
+
+        Args:
+            position: The new position from the slider in milliseconds.
+        """
         current_time = time.time()
         if (
             current_time - self.last_slider_moved_update
@@ -238,13 +321,25 @@ class MediaPlayer(QMediaPlayer):
             self.last_slider_moved_update = current_time
 
     def on_slider_released(self) -> None:
-        """Handle slider release event."""
+        """Handle slider release event.
+
+        Sets the final media position when the user releases the slider.
+        """
         self.setPosition(self.progress_slider.value())
 
     def play_video(
         self, set_source_func: Callable[..., Any], *args: Any, **kwargs: Any
     ) -> None:
-        """Play the video."""
+        """Play the video.
+
+        Stops current playback and starts a new video using the provided
+        source function with a delay to prevent freezing.
+
+        Args:
+            set_source_func: Function to call for setting the video source.
+            *args: Additional positional arguments for the source function.
+            **kwargs: Additional keyword arguments for the source function.
+        """
         self.stop()
 
         # prevents freezing when starting a new video while another is playing
@@ -255,20 +350,48 @@ class MediaPlayer(QMediaPlayer):
     def set_source_and_play(
         self, set_source_func: Callable[..., Any], *args: Any, **kwargs: Any
     ) -> None:
-        """Set the source and play the video."""
+        """Set the source and play the video.
+
+        Args:
+            set_source_func: Function to call for setting the video source.
+            *args: Additional positional arguments for the source function.
+            **kwargs: Additional keyword arguments for the source function.
+        """
         set_source_func(*args, **kwargs)
         self.play()
 
+    def set_source_device(self, io_device: PyQIODevice, source_url: QUrl) -> None:
+        """Set the source device for playback.
+
+        Args:
+            io_device: The PyQIODevice to use as the media source.
+            source_url: The QUrl representing the source location.
+        """
+        self.source_url = source_url
+        self.io_device = io_device
+        self.setSourceDevice(self.io_device, self.source_url)
+
     def play_file(self, path: Path) -> None:
-        """Play the video."""
+        """Play a regular video file.
+
+        Args:
+            path: The file path to the video file to play.
+        """
         self.play_video(
             self.set_source_device,
             io_device=PyQFile(path),
             source_url=QUrl.fromLocalFile(path),
         )
 
-    def set_source_device(self, io_device: PyQIODevice, source_url: QUrl) -> None:
-        """Play the video."""
-        self.source_url = source_url
-        self.io_device = io_device
-        self.setSourceDevice(self.io_device, self.source_url)
+    def play_encrypted_file(self, path: Path, aes_gcm: AESGCM) -> None:
+        """Play an encrypted video file.
+
+        Args:
+            path: The file path to the encrypted video file to play.
+            aes_gcm: The AES-GCM cipher instance for decryption.
+        """
+        self.play_video(
+            self.set_source_device,
+            io_device=EncryptedPyQFile(path, aes_gcm),
+            source_url=QUrl.fromLocalFile(path),
+        )