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

TonieToolbox/teddycloud.py

@@ -19,27 +19,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 +87,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 +104,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 +175,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 +185,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 +195,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 +205,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 +215,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 +225,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 +237,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 +257,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 +277,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 +297,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
         """

TonieToolbox/tonie_analysis.py

@@ -11,12 +11,13 @@ from .ogg_page import OggPage
 from .logger import get_logger
 
 logger = get_logger('tonie_analysis')
-def format_time(ts):
+
+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 +25,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 +38,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 +57,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 +165,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 +229,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 +316,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 +413,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 +573,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 +688,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

TonieToolbox/tonie_file.py

@@ -18,14 +18,14 @@ from .logger import get_logger
 logger = get_logger('tonie_file')
 
 
-def toniefile_comment_add(buffer, length, comment_str):
+def toniefile_comment_add(buffer: bytearray, length: int, comment_str: str) -> int:
     """
     Add a comment string to an Opus comment packet buffer.
     
     Args:
-        buffer: Bytearray buffer to add comment to
-        length: Current position in the buffer
-        comment_str: Comment string to add
+        buffer (bytearray): Bytearray buffer to add comment to
+        length (int): Current position in the buffer
+        comment_str (str): Comment string to add
         
     Returns:
         int: New position in the buffer after adding comment
@@ -44,7 +44,7 @@ def toniefile_comment_add(buffer, length, comment_str):
     return length
 
 
-def check_identification_header(page):
+def check_identification_header(page) -> None:
     """
     Check if a page contains a valid Opus identification header.
     
@@ -77,16 +77,16 @@ def check_identification_header(page):
     logger.debug("Opus identification header is valid")
 
 
-def prepare_opus_tags(page, custom_tags=False, bitrate=64, vbr=True, opus_binary=None):
+def prepare_opus_tags(page, custom_tags: bool = False, bitrate: int = 64, vbr: bool = True, opus_binary: str = None) -> OggPage:
     """
     Prepare standard Opus tags for a Tonie file.
     
     Args:
         page: OggPage to modify
-        custom_tags: Whether to use custom TonieToolbox tags instead of default ones
-        bitrate: Actual bitrate used for encoding
-        vbr: Whether variable bitrate was used
-        opus_binary: Path to opusenc binary for version detection
+        custom_tags (bool): Whether to use custom TonieToolbox tags instead of default ones
+        bitrate (int): Actual bitrate used for encoding
+        vbr (bool): Whether variable bitrate was used
+        opus_binary (str | None): Path to opusenc binary for version detection
         
     Returns:
         OggPage: Modified page with Tonie-compatible Opus tags
@@ -162,19 +162,28 @@ def prepare_opus_tags(page, custom_tags=False, bitrate=64, vbr=True, opus_binary
     return page
 
 
-def copy_first_and_second_page(in_file, out_file, timestamp, sha, use_custom_tags=True, bitrate=64, vbr=True, opus_binary=None):
+def copy_first_and_second_page(
+    in_file,
+    out_file,
+    timestamp: int,
+    sha,
+    use_custom_tags: bool = True,
+    bitrate: int = 64,
+    vbr: bool = True,
+    opus_binary: str = None
+) -> None:
     """
     Copy and modify the first two pages of an Opus file for a Tonie file.
     
     Args:
         in_file: Input file handle
         out_file: Output file handle
-        timestamp: Timestamp to use for the Tonie file
+        timestamp (int): Timestamp to use for the Tonie file
         sha: SHA1 hash object to update with written data
-        use_custom_tags: Whether to use custom TonieToolbox tags
-        bitrate: Actual bitrate used for encoding
-        vbr: Whether VBR was used
-        opus_binary: Path to opusenc binary
+        use_custom_tags (bool): Whether to use custom TonieToolbox tags
+        bitrate (int): Actual bitrate used for encoding
+        vbr (bool): Whether VBR was used
+        opus_binary (str | None): Path to opusenc binary
     """
     logger.debug("Copying first and second pages with timestamp %d", timestamp)
     found = OggPage.seek_to_page_header(in_file)
@@ -202,7 +211,7 @@ def copy_first_and_second_page(in_file, out_file, timestamp, sha, use_custom_tag
     logger.debug("Second page written successfully")
 
 
-def skip_first_two_pages(in_file):
+def skip_first_two_pages(in_file) -> None:
     """
     Skip the first two pages of an Opus file.
     
@@ -235,7 +244,7 @@ def skip_first_two_pages(in_file):
     logger.debug("First two pages skipped successfully")
 
 
-def read_all_remaining_pages(in_file):
+def read_all_remaining_pages(in_file) -> list:
     """
     Read all remaining OGG pages from an input file.
     
@@ -260,19 +269,26 @@ def read_all_remaining_pages(in_file):
     return remaining_pages
 
 
-def resize_pages(old_pages, max_page_size, first_page_size, template_page, last_granule=0, start_no=2,
-                set_last_page_flag=False):
+def resize_pages(
+    old_pages: list,
+    max_page_size: int,
+    first_page_size: int,
+    template_page,
+    last_granule: int = 0,
+    start_no: int = 2,
+    set_last_page_flag: bool = False
+) -> list:
     """
     Resize OGG pages to fit Tonie requirements.
     
     Args:
-        old_pages: List of original OggPage objects
-        max_page_size: Maximum size for pages
-        first_page_size: Size for the first page
+        old_pages (list): List of original OggPage objects
+        max_page_size (int): Maximum size for pages
+        first_page_size (int): Size for the first page
         template_page: Template OggPage to use for creating new pages
-        last_granule: Last granule position
-        start_no: Starting page number
-        set_last_page_flag: Whether to set the last page flag
+        last_granule (int): Last granule position
+        start_no (int): Starting page number
+        set_last_page_flag (bool): Whether to set the last page flag
         
     Returns:
         list: List of resized OggPage objects
@@ -326,14 +342,14 @@ def resize_pages(old_pages, max_page_size, first_page_size, template_page, last_
     return new_pages
 
 
-def fix_tonie_header(out_file, chapters, timestamp, sha):
+def fix_tonie_header(out_file, chapters: list, timestamp: int, sha) -> None:
     """
     Fix the Tonie header in a file.
     
     Args:
         out_file: Output file handle
-        chapters: List of chapter page numbers
-        timestamp: Timestamp for the Tonie file
+        chapters (list): List of chapter page numbers
+        timestamp (int): Timestamp for the Tonie file
         sha: SHA1 hash object with file content
     """
     logger.info("Writing Tonie header with %d chapters and timestamp %d", len(chapters), timestamp)
@@ -362,25 +378,36 @@ def fix_tonie_header(out_file, chapters, timestamp, sha):
     logger.debug("Tonie header written successfully (size: %d bytes)", len(header))
 
 
-def create_tonie_file(output_file, input_files, no_tonie_header=False, user_timestamp=None,
-                     bitrate=96, vbr=True, ffmpeg_binary=None, opus_binary=None, keep_temp=False, auto_download=False, 
-                     use_custom_tags=True, no_mono_conversion=False):
+def create_tonie_file(
+    output_file: str,
+    input_files: list[str],
+    no_tonie_header: bool = False,
+    user_timestamp: str = None,
+    bitrate: int = 96,
+    vbr: bool = True,
+    ffmpeg_binary: str = None,
+    opus_binary: str = None,
+    keep_temp: bool = False,
+    auto_download: bool = False,
+    use_custom_tags: bool = True,
+    no_mono_conversion: bool = False
+) -> None:
     """
     Create a Tonie file from input files.
     
     Args:
-        output_file: Output file path
-        input_files: List of input file paths
-        no_tonie_header: Whether to omit the Tonie header
-        user_timestamp: Custom timestamp to use
-        bitrate: Bitrate for encoding in kbps
-        vbr: Whether to use variable bitrate encoding (True) or constant (False)
-        ffmpeg_binary: Path to ffmpeg binary
-        opus_binary: Path to opusenc binary
-        keep_temp: Whether to keep temporary opus files for testing
-        auto_download: Whether to automatically download dependencies if not found
-        use_custom_tags: Whether to use dynamic comment tags generated with toniefile_comment_add
-        no_mono_conversion: Whether to skip mono conversion during audio processing
+        output_file (str): Output file path
+        input_files (list[str]): List of input file paths
+        no_tonie_header (bool): Whether to omit the Tonie header
+        user_timestamp (str | None): Custom timestamp to use
+        bitrate (int): Bitrate for encoding in kbps
+        vbr (bool): Whether to use variable bitrate encoding (True) or constant (False)
+        ffmpeg_binary (str | None): Path to ffmpeg binary
+        opus_binary (str | None): Path to opusenc binary
+        keep_temp (bool): Whether to keep temporary opus files for testing
+        auto_download (bool): Whether to automatically download dependencies if not found
+        use_custom_tags (bool): Whether to use dynamic comment tags generated with toniefile_comment_add
+        no_mono_conversion (bool): Whether to skip mono conversion during audio processing
     """
     from .audio_conversion import get_opus_tempfile