TonieToolbox 0.5.1__py3-none-any.whl → 0.6.0a1__py3-none-any.whl

TonieToolbox/ogg_page.py

@@ -18,12 +18,12 @@ from .logger import get_logger
 logger = get_logger('ogg_page')
 
 
-def create_crc_table():
+def create_crc_table() -> list[int]:
     """
     Create a CRC lookup table for OGG page checksums.
     
     Returns:
-        list: CRC32 lookup table for OGG pages
+        list[int]: CRC32 lookup table for OGG pages
     """
     logger.debug("Creating CRC table for OGG page checksums")
     table = []
@@ -39,12 +39,12 @@ def create_crc_table():
 CRC_TABLE = create_crc_table()
 
 
-def crc32(bytestream):
+def crc32(bytestream: bytes) -> int:
     """
     Calculate a CRC32 checksum for the given bytestream.
     
     Args:
-        bytestream: Bytes to calculate the CRC for
+        bytestream (bytes): Bytes to calculate the CRC for
         
     Returns:
         int: CRC32 checksum
@@ -64,7 +64,7 @@ class OggPage:
     with particular focus on features needed for Tonie compatibility.
     """
     
-    def __init__(self, filehandle):
+    def __init__(self, filehandle) -> None:
         """
         Initialize a new OggPage.
         
@@ -88,7 +88,7 @@ class OggPage:
         self.parse_header(filehandle)
         self.parse_segments(filehandle)
 
-    def parse_header(self, filehandle):
+    def parse_header(self, filehandle) -> None:
         """
         Parse the OGG page header.
         
@@ -108,7 +108,7 @@ class OggPage:
         logger.trace("Parsed OGG header - Page #%d, Type: %d, Granule: %d, Serial: %d, Segments: %d",
                    self.page_no, self.page_type, self.granule_position, self.serial_no, self.segment_count)
 
-    def parse_segments(self, filehandle):
+    def parse_segments(self, filehandle) -> None:
         """
         Parse the segments in this OGG page.
         
@@ -133,12 +133,12 @@ class OggPage:
             logger.error("Found an opus packet spanning OGG pages, which is not supported")
             raise RuntimeError("Found an opus packet spanning ogg pages. This is not supported yet.")
 
-    def correct_values(self, last_granule):
+    def correct_values(self, last_granule: int) -> None:
         """
         Correct the granule position and checksum for this page.
         
         Args:
-            last_granule: Last granule position
+            last_granule (int): Last granule position
             
         Raises:
             RuntimeError: If there are too many segments in the page
@@ -160,7 +160,7 @@ class OggPage:
         logger.trace("Corrected OGG page values: Page #%d, Segments: %d, Granule: %d", 
                    self.page_no, self.segment_count, self.granule_position)
 
-    def calc_checksum(self):
+    def calc_checksum(self) -> int:
         """
         Calculate the checksum for this page.
         
@@ -178,7 +178,7 @@ class OggPage:
         logger.trace("Calculated checksum for page #%d: 0x%X", self.page_no, checksum)
         return checksum
 
-    def get_page_size(self):
+    def get_page_size(self) -> int:
         """
         Get the total size of this page in bytes.
         
@@ -190,7 +190,7 @@ class OggPage:
             size = size + len(segment.data)
         return size
 
-    def get_size_of_first_opus_packet(self):
+    def get_size_of_first_opus_packet(self) -> int:
         """
         Get the size of the first opus packet in bytes.
         
@@ -208,7 +208,7 @@ class OggPage:
             i = i + 1
         return size
 
-    def get_segment_count_of_first_opus_packet(self):
+    def get_segment_count_of_first_opus_packet(self) -> int:
         """
         Get the number of segments in the first opus packet.
         
@@ -224,14 +224,14 @@ class OggPage:
             count = count + 1
         return count
 
-    def insert_empty_segment(self, index_after, spanning_packet=False, first_packet=False):
+    def insert_empty_segment(self, index_after: int, spanning_packet: bool = False, first_packet: bool = False) -> None:
         """
         Insert an empty segment after the specified index.
         
         Args:
-            index_after: Index to insert the segment after
-            spanning_packet: Whether this segment belongs to a packet that spans pages
-            first_packet: Whether this is the first segment of a packet
+            index_after (int): Index to insert the segment after
+            spanning_packet (bool): Whether this segment belongs to a packet that spans pages
+            first_packet (bool): Whether this is the first segment of a packet
         """
         logger.trace("Inserting empty segment after index %d (spanning: %s, first: %s)",
                    index_after, spanning_packet, first_packet)
@@ -242,12 +242,12 @@ class OggPage:
         segment.data = bytes()
         self.segments.insert(index_after + 1, segment)
 
-    def get_opus_packet_size(self, seg_start):
+    def get_opus_packet_size(self, seg_start: int) -> int:
         """
         Get the size of the opus packet starting at the specified segment index.
         
         Args:
-            seg_start: Starting segment index
+            seg_start (int): Starting segment index
             
         Returns:
             int: Size of the opus packet in bytes
@@ -259,12 +259,12 @@ class OggPage:
             seg_start = seg_start + 1
         return size
 
-    def get_segment_count_of_packet_at(self, seg_start):
+    def get_segment_count_of_packet_at(self, seg_start: int) -> int:
         """
         Get the number of segments in the packet starting at the specified segment index.
         
         Args:
-            seg_start: Starting segment index
+            seg_start (int): Starting segment index
             
         Returns:
             int: Number of segments
@@ -274,13 +274,13 @@ class OggPage:
             seg_end = seg_end + 1
         return seg_end - seg_start
 
-    def redistribute_packet_data_at(self, seg_start, pad_count):
+    def redistribute_packet_data_at(self, seg_start: int, pad_count: int) -> None:
         """
         Redistribute packet data starting at the specified segment index.
         
         Args:
-            seg_start: Starting segment index
-            pad_count: Number of padding bytes to add
+            seg_start (int): Starting segment index
+            pad_count (int): Number of padding bytes to add
         """
         logger.trace("Redistributing packet data at segment %d with %d padding bytes", 
                    seg_start, pad_count)
@@ -316,14 +316,14 @@ class OggPage:
         logger.trace("Redistribution complete, %d segments used", seg_count)
         assert len(full_data) == 0
 
-    def convert_packet_to_framepacking_three_and_pad(self, seg_start, pad=False, count=0):
+    def convert_packet_to_framepacking_three_and_pad(self, seg_start: int, pad: bool = False, count: int = 0) -> None:
         """
         Convert the packet to framepacking three mode and add padding if required.
         
         Args:
-            seg_start: Starting segment index
-            pad: Whether to add padding
-            count: Number of padding bytes to add
+            seg_start (int): Starting segment index
+            pad (bool): Whether to add padding
+            count (int): Number of padding bytes to add
             
         Raises:
             AssertionError: If the segment is not the first packet
@@ -336,13 +336,13 @@ class OggPage:
             self.segments[seg_start].set_pad_count(count)
         self.redistribute_packet_data_at(seg_start, count)
 
-    def calc_actual_padding_value(self, seg_start, bytes_needed):
+    def calc_actual_padding_value(self, seg_start: int, bytes_needed: int) -> int:
         """
         Calculate the actual padding value needed for the packet.
         
         Args:
-            seg_start: Starting segment index
-            bytes_needed: Number of bytes needed for padding
+            seg_start (int): Starting segment index
+            bytes_needed (int): Number of bytes needed for padding
             
         Returns:
             int: Actual padding value or a special return code
@@ -426,13 +426,13 @@ class OggPage:
             logger.trace("Calculated actual padding value: %d", result)
             return result
 
-    def pad(self, pad_to, idx_offset=-1):
+    def pad(self, pad_to: int, idx_offset: int = -1) -> None:
         """
         Pad the page to the specified size.
         
         Args:
-            pad_to: Target size to pad to
-            idx_offset: Index offset to start from, defaults to last segment
+            pad_to (int): Target size to pad to
+            idx_offset (int): Index offset to start from, defaults to last segment
             
         Raises:
             RuntimeError: If beginning of last packet cannot be found
@@ -490,7 +490,7 @@ class OggPage:
                        final_size, pad_to)
         assert final_size == pad_to
 
-    def pad_one_byte(self):
+    def pad_one_byte(self) -> None:
         """
         Add one byte of padding to the page.
         
@@ -515,7 +515,7 @@ class OggPage:
             logger.trace("Converting packet to framepacking 3")
             self.convert_packet_to_framepacking_three_and_pad(i)
 
-    def write_page(self, filehandle, sha1=None):
+    def write_page(self, filehandle, sha1=None) -> None:
         """
         Write the page to a file handle.
         
@@ -537,12 +537,12 @@ class OggPage:
             segment.write(filehandle)
 
     @staticmethod
-    def from_page(other_page):
+    def from_page(other_page: 'OggPage') -> 'OggPage':
         """
         Create a new OggPage based on another page.
         
         Args:
-            other_page: Source page to copy from
+            other_page (OggPage): Source page to copy from
             
         Returns:
             OggPage: New page with copied properties
@@ -560,7 +560,7 @@ class OggPage:
         return new_page
 
     @staticmethod
-    def seek_to_page_header(filehandle):
+    def seek_to_page_header(filehandle) -> bool:
         """
         Seek to the next OGG page header in a file.
         

TonieToolbox/opus_packet.py

@@ -18,15 +18,15 @@ class OpusPacket:
     with particular focus on features needed for Tonie compatibility.
     """
     
-    def __init__(self, filehandle, size=-1, last_size=-1, dont_parse_info=False):
+    def __init__(self, filehandle, size: int = -1, last_size: int = -1, dont_parse_info: bool = False) -> None:
         """
         Initialize a new OpusPacket.
         
         Args:
             filehandle: File handle to read the packet data from, or None to create an empty packet
-            size: Size of the packet in bytes
-            last_size: Size of the previous packet in bytes
-            dont_parse_info: If True, don't parse the packet information even if this is a first packet
+            size (int): Size of the packet in bytes
+            last_size (int): Size of the previous packet in bytes
+            dont_parse_info (bool): If True, don't parse the packet information even if this is a first packet
         """
         self.config_value = None
         self.stereo = None
@@ -51,7 +51,7 @@ class OpusPacket:
         if self.first_packet and not dont_parse_info:
             self.parse_segment_info()
 
-    def get_frame_count(self):
+    def get_frame_count(self) -> int:
         """
         Get the number of frames in this packet based on its framepacking.
         
@@ -68,7 +68,7 @@ class OpusPacket:
             unpacked = struct.unpack("<B", self.data[1:2])
             return unpacked[0] & 63
 
-    def get_padding(self):
+    def get_padding(self) -> int:
         """
         Get the padding count for this packet.
         
@@ -94,7 +94,7 @@ class OpusPacket:
         logger.trace("Packet has %d bytes of padding", total_padding)
         return total_padding
 
-    def get_frame_size(self):
+    def get_frame_size(self) -> float:
         """
         Get the frame size in milliseconds based on the config value.
         
@@ -121,7 +121,7 @@ class OpusPacket:
             logger.error(error_msg)
             raise RuntimeError(error_msg)
 
-    def calc_granule(self):
+    def calc_granule(self) -> float:
         """
         Calculate the granule position for this packet.
         
@@ -133,7 +133,7 @@ class OpusPacket:
                    granule, self.frame_size, self.frame_count)
         return granule
 
-    def parse_segment_info(self):
+    def parse_segment_info(self) -> None:
         """Parse the segment information from the packet data."""
         logger.trace("Parsing segment info from packet data")
         byte = struct.unpack("<B", self.data[0:1])[0]
@@ -148,7 +148,7 @@ class OpusPacket:
         logger.trace("Packet info: config=%d, stereo=%d, framepacking=%d, frame_count=%d, frame_size=%f",
                    self.config_value, self.stereo, self.framepacking, self.frame_count, self.frame_size)
 
-    def write(self, filehandle):
+    def write(self, filehandle) -> None:
         """
         Write the packet data to a file.
         
@@ -159,7 +159,7 @@ class OpusPacket:
             logger.trace("Writing %d bytes of packet data to file", len(self.data))
             filehandle.write(self.data)
 
-    def convert_to_framepacking_three(self):
+    def convert_to_framepacking_three(self) -> None:
         """
         Convert the packet to use framepacking mode 3.
         
@@ -182,12 +182,12 @@ class OpusPacket:
         self.framepacking = 3
         logger.debug("Packet successfully converted to framepacking mode 3")
 
-    def set_pad_count(self, count):
+    def set_pad_count(self, count: int) -> None:
         """
         Set the padding count for this packet.
         
         Args:
-            count: Number of padding bytes to add
+            count (int): Number of padding bytes to add
             
         Raises:
             AssertionError: If the packet is not using framepacking mode 3 or is already padded

TonieToolbox/recursive_processor.py

@@ -14,16 +14,16 @@ from .logger import get_logger
 logger = get_logger('recursive_processor')
 
 
-def find_audio_folders(root_path: str) -> List[Dict[str, any]]:
+def find_audio_folders(root_path: str) -> list[dict[str, any]]:
     """
     Find and return all folders that contain audio files in a recursive manner,
     organized in a way that handles nested folder structures.
     
     Args:
-        root_path: Root directory to start searching from
+        root_path (str): Root directory to start searching from
         
     Returns:
-        List of dictionaries with folder information, including paths and relationships
+        list[dict[str, any]]: List of dictionaries with folder information, including paths and relationships
     """
     logger.info("Finding folders with audio files in: %s", root_path)
     
@@ -68,15 +68,15 @@ def find_audio_folders(root_path: str) -> List[Dict[str, any]]:
     return folder_list
 
 
-def determine_processing_folders(folders: List[Dict[str, any]]) -> List[Dict[str, any]]:
+def determine_processing_folders(folders: list[dict[str, any]]) -> list[dict[str, any]]:
     """
     Determine which folders should be processed based on their position in the hierarchy.
     
     Args:
-        folders: List of folder dictionaries with hierarchy information
+        folders (list[dict[str, any]]): List of folder dictionaries with hierarchy information
         
     Returns:
-        List of folders that should be processed (filtered)
+        list[dict[str, any]]: List of folders that should be processed (filtered)
     """
     # We'll use a set to track which folders we've decided to process
     to_process = set()
@@ -120,15 +120,15 @@ def determine_processing_folders(folders: List[Dict[str, any]]) -> List[Dict[str
     return result
 
 
-def get_folder_audio_files(folder_path: str) -> List[str]:
+def get_folder_audio_files(folder_path: str) -> list[str]:
     """
     Get all audio files in a specific folder.
     
     Args:
-        folder_path: Path to folder
+        folder_path (str): Path to folder
         
     Returns:
-        List of paths to audio files in natural sort order
+        list[str]: List of paths to audio files in natural sort order
     """
     audio_files = glob.glob(os.path.join(folder_path, "*"))
     filtered_files = filter_directories(audio_files)
@@ -140,15 +140,15 @@ def get_folder_audio_files(folder_path: str) -> List[str]:
     return sorted_files
 
 
-def natural_sort(file_list: List[str]) -> List[str]:
+def natural_sort(file_list: list[str]) -> list[str]:
     """
     Sort a list of files in natural order (so that 2 comes before 10).
     
     Args:
-        file_list: List of file paths
+        file_list (list[str]): List of file paths
         
     Returns:
-        Naturally sorted list of file paths
+        list[str]: Naturally sorted list of file paths
     """
     def convert(text):
         return int(text) if text.isdigit() else text.lower()
@@ -159,16 +159,16 @@ def natural_sort(file_list: List[str]) -> List[str]:
     return sorted(file_list, key=alphanum_key)
 
 
-def extract_folder_meta(folder_path: str) -> Dict[str, str]:
+def extract_folder_meta(folder_path: str) -> dict[str, str]:
     """
     Extract metadata from folder name.
     Common format might be: "YYYY - NNN - Title"
     
     Args:
-        folder_path: Path to folder
+        folder_path (str): Path to folder
         
     Returns:
-        Dictionary with extracted metadata (year, number, title)
+        dict[str, str]: Dictionary with extracted metadata (year, number, title)
     """
     folder_name = os.path.basename(folder_path)
     logger.debug("Extracting metadata from folder: %s", folder_name)
@@ -210,12 +210,12 @@ def get_folder_name_from_metadata(folder_path: str, use_media_tags: bool = False
     and optionally audio file metadata.
     
     Args:
-        folder_path: Path to folder
-        use_media_tags: Whether to use media tags from audio files if available
-        template: Optional template for formatting output name using media tags
+        folder_path (str): Path to folder
+        use_media_tags (bool): Whether to use media tags from audio files if available
+        template (str | None): Optional template for formatting output name using media tags
         
     Returns:
-        String with cleaned output name
+        str: String with cleaned output name
     """
     folder_meta = extract_folder_meta(folder_path)
     output_name = None    
@@ -289,17 +289,17 @@ def get_folder_name_from_metadata(folder_path: str, use_media_tags: bool = False
     return output_name
 
 
-def process_recursive_folders(root_path, use_media_tags=False, name_template=None):
+def process_recursive_folders(root_path: str, use_media_tags: bool = False, name_template: str = None) -> list[tuple[str, str, list[str]]]:
     """
     Process folders recursively for audio files to create Tonie files.
     
     Args:
         root_path (str): The root path to start processing from
         use_media_tags (bool): Whether to use media tags for naming
-        name_template (str): Template for naming files using media tags
+        name_template (str | None): Template for naming files using media tags
     
     Returns:
-        list: A list of tuples (output_name, folder_path, audio_files)
+        list[tuple[str, str, list[str]]]: A list of tuples (output_name, folder_path, audio_files)
     """
     logger = get_logger("recursive_processor")
     logger.info("Processing folders recursively: %s", root_path)

TonieToolbox/tags.py

@@ -10,15 +10,14 @@ from typing import Optional, Union
 
 logger = get_logger('tags')
 
-def get_tags(client: TeddyCloudClient) -> bool:
+def get_tags(client: 'TeddyCloudClient') -> bool:
     """
     Get and display tags from a TeddyCloud instance.
     
     Args:
-        client: TeddyCloudClient instance to use for API communication
-        
+        client (TeddyCloudClient): TeddyCloudClient instance to use for API communication
     Returns:
-        True if tags were retrieved successfully, False otherwise
+        bool: True if tags were retrieved successfully, False otherwise
     """
     logger.info("Getting tags from TeddyCloud using provided client")