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

TonieToolbox/recursive_processor.py

@@ -1,3 +1,4 @@
+#!/usr/bin/python3
 """
 Recursive folder processing functionality for the TonieToolbox package
 """
@@ -11,19 +12,19 @@ import re
 from .audio_conversion import filter_directories
 from .logger import get_logger
 
-logger = get_logger('recursive_processor')
+logger = get_logger(__name__)
 
 
-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 +69,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 +121,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 +141,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 +160,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 +211,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 +290,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

@@ -8,17 +8,16 @@ from .teddycloud import TeddyCloudClient
 import json
 from typing import Optional, Union
 
-logger = get_logger('tags')
+logger = get_logger(__name__)
 
-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")
     

TonieToolbox/teddycloud.py

@@ -9,8 +9,9 @@ import base64
 import ssl
 import socket
 import requests
+import json
 from .logger import get_logger
-logger = get_logger('teddycloud')
+logger = get_logger(__name__)
 DEFAULT_CONNECTION_TIMEOUT = 10
 DEFAULT_READ_TIMEOUT = 15  # seconds
 DEFAULT_MAX_RETRIES = 3
@@ -19,27 +20,33 @@ DEFAULT_RETRY_DELAY = 5  # seconds
 class TeddyCloudClient:
     """Client for interacting with TeddyCloud API."""
     
-    def __init__(self, base_url: str, ignore_ssl_verify: bool = False, 
-                 connection_timeout: int = DEFAULT_CONNECTION_TIMEOUT, 
-                 read_timeout: int = DEFAULT_READ_TIMEOUT, 
-                 max_retries: int = DEFAULT_MAX_RETRIES, 
-                 retry_delay: int = DEFAULT_RETRY_DELAY,
-                 username: str = None, password: str = None,
-                 cert_file: str = None, key_file: str = None):
+    def __init__(
+        self,
+        base_url: str,
+        ignore_ssl_verify: bool = False,
+        connection_timeout: int = DEFAULT_CONNECTION_TIMEOUT,
+        read_timeout: int = DEFAULT_READ_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        retry_delay: int = DEFAULT_RETRY_DELAY,
+        username: str = None,
+        password: str = None,
+        cert_file: str = None,
+        key_file: str = None
+    ) -> None:
         """
         Initialize the TeddyCloud client.
         
         Args:
-            base_url: Base URL of the TeddyCloud instance (e.g., https://teddycloud.example.com)
-            ignore_ssl_verify: If True, SSL certificate verification will be disabled (useful for self-signed certificates)
-            connection_timeout: Timeout for establishing a connection
-            read_timeout: Timeout for reading data from the server
-            max_retries: Maximum number of retries for failed requests
-            retry_delay: Delay between retries
-            username: Username for basic authentication (optional)
-            password: Password for basic authentication (optional)
-            cert_file: Path to client certificate file for certificate-based authentication (optional)
-            key_file: Path to client private key file for certificate-based authentication (optional)
+            base_url (str): Base URL of the TeddyCloud instance (e.g., https://teddycloud.example.com)
+            ignore_ssl_verify (bool): If True, SSL certificate verification will be disabled (useful for self-signed certificates)
+            connection_timeout (int): Timeout for establishing a connection
+            read_timeout (int): Timeout for reading data from the server
+            max_retries (int): Maximum number of retries for failed requests
+            retry_delay (int): Delay between retries
+            username (str | None): Username for basic authentication (optional)
+            password (str | None): Password for basic authentication (optional)
+            cert_file (str | None): Path to client certificate file for certificate-based authentication (optional)
+            key_file (str | None): Path to client private key file for certificate-based authentication (optional)
         """
         self.base_url = base_url.rstrip('/')
         self.ignore_ssl_verify = ignore_ssl_verify
@@ -81,7 +88,7 @@ class TeddyCloudClient:
             except ssl.SSLError as e:
                 raise ValueError(f"Failed to load client certificate: {e}")
                 
-    def _create_request_kwargs(self):
+    def _create_request_kwargs(self) -> dict:
         """
         Create common request keyword arguments for all API calls.
         
@@ -98,18 +105,16 @@ class TeddyCloudClient:
             kwargs['cert'] = self.cert       
         return kwargs
     
-    def _make_request(self, method, endpoint, **kwargs):
+    def _make_request(self, method: str, endpoint: str, **kwargs) -> 'requests.Response':
         """
         Make an HTTP request to the TeddyCloud API with retry logic.
         
         Args:
-            method: HTTP method (GET, POST, etc.)
-            endpoint: API endpoint (without base URL)
+            method (str): HTTP method (GET, POST, etc.)
+            endpoint (str): API endpoint (without base URL)
             **kwargs: Additional arguments to pass to requests
-            
         Returns:
             requests.Response: Response object
-            
         Raises:
             requests.exceptions.RequestException: If request fails after all retries
         """
@@ -171,7 +176,7 @@ class TeddyCloudClient:
 
     # ------------- GET API Methods -------------
     
-    def get_tonies_custom_json(self):
+    def get_tonies_custom_json(self) -> dict:
         """
         Get custom Tonies JSON data from the TeddyCloud server.
         
@@ -181,7 +186,7 @@ class TeddyCloudClient:
         response = self._make_request('GET', '/api/toniesCustomJson')
         return response.json()
     
-    def get_tonies_json(self):
+    def get_tonies_json(self) -> dict:
         """
         Get Tonies JSON data from the TeddyCloud server.
         
@@ -191,7 +196,7 @@ class TeddyCloudClient:
         response = self._make_request('GET', '/api/toniesJson')
         return response.json()
     
-    def get_tag_index(self):
+    def get_tag_index(self) -> dict:
         """
         Get tag index data from the TeddyCloud server.
         
@@ -201,7 +206,7 @@ class TeddyCloudClient:
         response = self._make_request('GET', '/api/getTagIndex')
         return response.json()    
     
-    def get_file_index(self):
+    def get_file_index(self) -> dict:
         """
         Get file index data from the TeddyCloud server.
         
@@ -211,7 +216,7 @@ class TeddyCloudClient:
         response = self._make_request('GET', '/api/fileIndex')
         return response.json()
     
-    def get_file_index_v2(self):
+    def get_file_index_v2(self) -> dict:
         """
         Get version 2 file index data from the TeddyCloud server.
         
@@ -221,7 +226,7 @@ class TeddyCloudClient:
         response = self._make_request('GET', '/api/fileIndexV2')
         return response.json()
     
-    def get_tonieboxes_json(self):
+    def get_tonieboxes_json(self) -> dict:
         """
         Get Tonieboxes JSON data from the TeddyCloud server.
         
@@ -233,15 +238,14 @@ class TeddyCloudClient:
     
     # ------------- POST API Methods -------------
     
-    def create_directory(self, path, overlay=None, special=None):
+    def create_directory(self, path: str, overlay: str = None, special: str = None) -> str:
         """
         Create a directory on the TeddyCloud server.
         
         Args:
-            path: Directory path to create
-            overlay: Settings overlay ID (optional)
-            special: Special folder source, only 'library' supported yet (optional)
-            
+            path (str): Directory path to create
+            overlay (str | None): Settings overlay ID (optional)
+            special (str | None): Special folder source, only 'library' supported yet (optional)
         Returns:
             str: Response message from server (usually "OK")
         """
@@ -254,15 +258,14 @@ class TeddyCloudClient:
         response = self._make_request('POST', '/api/dirCreate', params=params, data=path)
         return response.text
     
-    def delete_directory(self, path, overlay=None, special=None):
+    def delete_directory(self, path: str, overlay: str = None, special: str = None) -> str:
         """
         Delete a directory from the TeddyCloud server.
         
         Args:
-            path: Directory path to delete
-            overlay: Settings overlay ID (optional)
-            special: Special folder source, only 'library' supported yet (optional)
-            
+            path (str): Directory path to delete
+            overlay (str | None): Settings overlay ID (optional)
+            special (str | None): Special folder source, only 'library' supported yet (optional)
         Returns:
             str: Response message from server (usually "OK")
         """
@@ -275,15 +278,14 @@ class TeddyCloudClient:
         response = self._make_request('POST', '/api/dirDelete', params=params, data=path)
         return response.text
     
-    def delete_file(self, path, overlay=None, special=None):
+    def delete_file(self, path: str, overlay: str = None, special: str = None) -> str:
         """
         Delete a file from the TeddyCloud server.
         
         Args:
-            path: File path to delete
-            overlay: Settings overlay ID (optional)
-            special: Special folder source, only 'library' supported yet (optional)
-            
+            path (str): File path to delete
+            overlay (str | None): Settings overlay ID (optional)
+            special (str | None): Special folder source, only 'library' supported yet (optional)
         Returns:
             str: Response message from server (usually "OK")
         """
@@ -296,16 +298,15 @@ class TeddyCloudClient:
         response = self._make_request('POST', '/api/fileDelete', params=params, data=path)
         return response.text
     
-    def upload_file(self, file_path, destination_path=None, overlay=None, special=None):
+    def upload_file(self, file_path: str, destination_path: str = None, overlay: str = None, special: str = None) -> dict:
         """
         Upload a file to the TeddyCloud server.
         
         Args:
-            file_path: Local path to the file to upload
-            destination_path: Server path where to write the file to (optional)
-            overlay: Settings overlay ID (optional)
-            special: Special folder source, only 'library' supported yet (optional)
-            
+            file_path (str): Local path to the file to upload
+            destination_path (str | None): Server path where to write the file to (optional)
+            overlay (str | None): Settings overlay ID (optional)
+            special (str | None): Special folder source, only 'library' supported yet (optional)
         Returns:
             dict: JSON response from server
         """
@@ -334,3 +335,115 @@ class TeddyCloudClient:
             }
     
     # ------------- Custom API Methods -------------
+
+    def _get_paths_cache_file(self) -> str:
+        """
+        Get the path to the paths cache file.
+        
+        Returns:
+            str: Path to the paths cache file
+        """
+        cache_dir = os.path.join(os.path.expanduser("~"), ".tonietoolbox")
+        os.makedirs(cache_dir, exist_ok=True)
+        return os.path.join(cache_dir, "paths.json")
+    
+    def _load_paths_cache(self) -> set:
+        """
+        Load the paths cache from the cache file.
+        
+        Returns:
+            set: Set of existing directory paths
+        """
+        cache_file = self._get_paths_cache_file()
+        try:
+            if os.path.exists(cache_file):
+                with open(cache_file, 'r', encoding='utf-8') as f:
+                    paths_data = json.load(f)
+                    # Convert to set for faster lookups
+                    return set(paths_data.get('paths', []))
+            return set()
+        except Exception as e:
+            logger.warning(f"Failed to load paths cache: {e}")
+            return set()
+    
+    def _save_paths_cache(self, paths: set) -> None:
+        """
+        Save the paths cache to the cache file.
+        
+        Args:
+            paths (set): Set of directory paths to save
+        """
+        cache_file = self._get_paths_cache_file()
+        try:
+            paths_data = {'paths': list(paths)}
+            with open(cache_file, 'w', encoding='utf-8') as f:
+                json.dump(paths_data, f, indent=2)
+            logger.debug(f"Saved {len(paths)} paths to cache file")
+        except Exception as e:
+            logger.warning(f"Failed to save paths cache: {e}")
+    
+    def create_directories_recursive(self, path: str, overlay: str = None, special: str = "library") -> str:
+        """
+        Create directories recursively on the TeddyCloud server.
+
+        This function handles both cases:
+        - Directories that already exist (prevents 500 errors)
+        - Parent directories that don't exist yet (creates them first)
+        
+        This optimized version uses a local paths cache instead of querying the file index,
+        since the file index might not represent the correct folders.
+
+        Args:
+            path (str): Directory path to create (can contain multiple levels)
+            overlay (str | None): Settings overlay ID (optional)
+            special (str | None): Special folder source, only 'library' supported yet (optional)
+
+        Returns:
+            str: Response message from server
+        """
+        path = path.replace('\\', '/').strip('/')
+        if not path:
+            return "Path is empty"
+        existing_dirs = self._load_paths_cache()
+        logger.debug(f"Loaded {len(existing_dirs)} existing paths from cache")
+        path_components = path.split('/')
+        current_path = ""
+        result = "OK"
+        paths_updated = False
+        for component in path_components:
+            if current_path:
+                current_path += f"/{component}"
+            else:
+                current_path = component
+            if current_path in existing_dirs:
+                logger.debug(f"Directory '{current_path}' exists in paths cache, skipping creation")
+                continue
+
+            try:
+                result = self.create_directory(current_path, overlay, special)
+                logger.debug(f"Created directory: {current_path}")
+                # Add the newly created directory to our cache
+                existing_dirs.add(current_path)
+                paths_updated = True
+            except requests.exceptions.HTTPError as e:
+                # If it's a 500 error, likely the directory already exists
+                if e.response.status_code == 500:
+                    if "already exists" in e.response.text.lower():
+                        logger.debug(f"Directory '{current_path}' already exists, continuing")
+                        # Add to our cache for future operations
+                        existing_dirs.add(current_path)
+                        paths_updated = True
+                    else:
+                        # Log the actual error message but continue anyway
+                        # This allows us to continue even if the error is something else
+                        logger.warning(f"Warning while creating '{current_path}': {str(e)}")
+                else:
+                    # Re-raise for other HTTP errors
+                    logger.error(f"Failed to create directory '{current_path}': {str(e)}")
+                    raise
+        
+        # Save updated paths cache if any changes were made
+        if paths_updated:
+            self._save_paths_cache(existing_dirs)
+                
+        return result

TonieToolbox/tonie_analysis.py

@@ -1,3 +1,4 @@
+#!/usr/bin/python3
 """
 Functions for analyzing Tonie files
 """
@@ -10,13 +11,14 @@ from  . import tonie_header_pb2
 from .ogg_page import OggPage
 from .logger import get_logger
 
-logger = get_logger('tonie_analysis')
-def format_time(ts):
+logger = get_logger(__name__)
+
+def format_time(ts: float) -> str:
     """
     Format a timestamp as a human-readable date and time string.
     
     Args:
-        ts: Timestamp to format
+        ts (float): Timestamp to format
         
     Returns:
         str: Formatted date and time string
@@ -24,12 +26,12 @@ def format_time(ts):
     return datetime.datetime.fromtimestamp(ts, datetime.timezone.utc).strftime('%Y-%m-%d %H:%M:%S')
 
 
-def format_hex(data):
+def format_hex(data: bytes) -> str:
     """
     Format binary data as a hex string.
     
     Args:
-        data: Binary data to format
+        data (bytes): Binary data to format
         
     Returns:
         str: Formatted hex string
@@ -37,13 +39,13 @@ def format_hex(data):
     return "".join(format(x, "02X") for x in data)
 
 
-def granule_to_time_string(granule, sample_rate=1):
+def granule_to_time_string(granule: int, sample_rate: int = 1) -> str:
     """
     Convert a granule position to a time string.
     
     Args:
-        granule: Granule position
-        sample_rate: Sample rate in Hz
+        granule (int): Granule position
+        sample_rate (int): Sample rate in Hz
         
     Returns:
         str: Formatted time string (HH:MM:SS.FF)
@@ -56,7 +58,7 @@ def granule_to_time_string(granule, sample_rate=1):
     return "{:02d}:{:02d}:{:02d}.{:02d}".format(hours, minutes, seconds, fraction)
 
 
-def get_header_info(in_file):
+def get_header_info(in_file) -> tuple:
     """
     Get header information from a Tonie file.
     
@@ -164,15 +166,15 @@ def get_header_info(in_file):
     )
 
 
-def get_audio_info(in_file, sample_rate, tonie_header, header_size):
+def get_audio_info(in_file, sample_rate: int, tonie_header, header_size: int) -> tuple:
     """
     Get audio information from a Tonie file.
     
     Args:
         in_file: Input file handle
-        sample_rate: Sample rate in Hz
+        sample_rate (int): Sample rate in Hz
         tonie_header: Tonie header object
-        header_size: Header size in bytes
+        header_size (int): Header size in bytes
         
     Returns:
         tuple: Page count, alignment OK flag, page size OK flag, total time, chapter times
@@ -228,12 +230,12 @@ def get_audio_info(in_file, sample_rate, tonie_header, header_size):
     return page_count, alignment_okay, page_size_okay, total_time, chapter_times
 
 
-def check_tonie_file(filename):
+def check_tonie_file(filename: str) -> bool:
     """
     Check if a file is a valid Tonie file and display information about it.
     
     Args:
-        filename: Path to the file to check
+        filename (str): Path to the file to check
         
     Returns:
         bool: True if the file is valid, False otherwise
@@ -315,13 +317,13 @@ def check_tonie_file(filename):
     return all_ok
 
 
-def split_to_opus_files(filename, output=None):
+def split_to_opus_files(filename: str, output: str = None) -> None:
     """
     Split a Tonie file into individual Opus files.
     
     Args:
-        filename: Path to the Tonie file
-        output: Output directory path (optional)
+        filename (str): Path to the Tonie file
+        output (str | None): Output directory path (optional)
     """
     logger.info("Splitting Tonie file into individual Opus tracks: %s", filename)
     
@@ -412,14 +414,14 @@ def split_to_opus_files(filename, output=None):
         logger.info("Successfully split Tonie file into %d individual tracks", len(tonie_header.chapterPages))
 
 
-def compare_taf_files(file1, file2, detailed=False):
+def compare_taf_files(file1: str, file2: str, detailed: bool = False) -> bool:
     """
     Compare two .taf files for debugging purposes.
     
     Args:
-        file1: Path to the first .taf file
-        file2: Path to the second .taf file
-        detailed: Whether to show detailed comparison results
+        file1 (str): Path to the first .taf file
+        file2 (str): Path to the second .taf file
+        detailed (bool): Whether to show detailed comparison results
         
     Returns:
         bool: True if files are equivalent, False otherwise
@@ -572,7 +574,7 @@ def compare_taf_files(file1, file2, detailed=False):
         logger.info("Files comparison result: Equivalent")
         return True
 
-def get_header_info_cli(in_file):
+def get_header_info_cli(in_file) -> tuple:
     """
     Get header information from a Tonie file.
     
@@ -687,12 +689,12 @@ def get_header_info_cli(in_file):
         return (0, tonie_header_pb2.TonieHeader(), 0, 0, None, False, 0, 0, 0, 0, {}, False)
 
 
-def check_tonie_file_cli(filename):
+def check_tonie_file_cli(filename: str) -> bool:
     """
     Check if a file is a valid Tonie file
     
     Args:
-        filename: Path to the file to check
+        filename (str): Path to the file to check
         
     Returns:
         bool: True if the file is valid, False otherwise