Utility Functions

def download_file(url: str, local_filename: str = None) -> str:
    """
    Download a file from URL to local filesystem with progress tracking.
    
    Parameters:
    - url: URL to download from
    - local_filename: Optional local filename (derived from URL if None)
    
    Returns:
    - Local filename of downloaded file
    
    Features:
    - Progress bar display using tqdm
    - Automatic filename detection from Content-Disposition header
    - Resume support for partial downloads
    - Proper handling of redirects and authentication
    """

def extract_file(url: str, to_dir: str = ".") -> Any:
    """
    Download and extract compressed files (tar, zip, 7z) in one operation.
    
    Parameters:
    - url: URL of compressed file to download and extract
    - to_dir: Target directory for extraction (default: current directory)
    
    Returns:
    - Extraction results and file list
    
    Supported formats:
    - TAR archives (.tar, .tar.gz, .tar.bz2, .tar.xz)
    - ZIP archives (.zip)
    - 7-Zip archives (.7z)
    
    Security:
    - Path traversal protection for all archive types
    - Safe extraction with directory bounds checking
    """

def extract_tar(buffer: io.BytesIO, to_dir: str) -> None:
    """
    Extract TAR archive from BytesIO buffer with safety checks.
    
    Parameters:
    - buffer: BytesIO buffer containing TAR data
    - to_dir: Target extraction directory
    
    Security features:
    - Path traversal attack prevention
    - Symbolic link attack protection
    - Size bomb protection
    """

def extract_zip(buffer: io.BytesIO, to_dir: str) -> None:
    """
    Extract ZIP archive from BytesIO buffer.
    
    Parameters:
    - buffer: BytesIO buffer containing ZIP data  
    - to_dir: Target extraction directory
    
    Features:
    - Unicode filename support
    - Directory structure preservation
    - Executable permission handling on Unix systems
    """

def extract_7z(buffer: io.BytesIO, to_dir: str) -> None:
    """
    Extract 7-Zip archive from BytesIO buffer.
    
    Parameters:
    - buffer: BytesIO buffer containing 7z data
    - to_dir: Target extraction directory
    
    Requires:
    - py7zr library for 7-Zip support
    """

def check_if_tar_safe(tar_file: tarfile.TarFile) -> bool:
    """
    Verify TAR file safety against path traversal attacks.
    
    Parameters:
    - tar_file: Open TarFile object to check
    
    Returns:
    - True if archive is safe to extract, False otherwise
    
    Checks for:
    - Path traversal attempts (../ sequences)
    - Absolute path entries
    - Symbolic link attacks
    """

def is_file_ext_not_compatible_with_os(file_ext: str) -> bool:
    """
    Check if file extension is incompatible with current operating system.
    
    Parameters:
    - file_ext: File extension to check (with or without leading dot)
    
    Returns:
    - True if extension is incompatible with current OS
    """

def is_asset_name_compatible_with_platform(asset_name: str) -> bool:
    """
    Determine if asset name indicates compatibility with current platform.
    
    Parameters:
    - asset_name: Asset or filename to analyze
    
    Returns:
    - True if asset appears compatible with current platform
    
    Analyzes:
    - Operating system indicators (windows, linux, macos, darwin)
    - Architecture indicators (x86, x64, arm, aarch64)
    - Package format compatibility
    """

def is_not_compatible_to_distro(asset_ext: str) -> bool:
    """
    Check if asset extension is incompatible with current Linux distribution.
    
    Parameters:
    - asset_ext: Asset file extension
    
    Returns:
    - True if incompatible with current distribution
    
    Considers:
    - RPM vs DEB package formats
    - Distribution-specific package types
    - Current system's package manager
    """

def is_not_compatible_bitness(asset_name: str) -> bool:
    """
    Check if asset bitness (32/64-bit) is incompatible with current system.
    
    Parameters:
    - asset_name: Asset filename to analyze
    
    Returns:
    - True if bitness is incompatible
    """

def asset_does_not_belong_to_machine(asset_name: str) -> bool:
    """
    Comprehensive compatibility check for asset against current machine.
    
    Parameters:
    - asset_name: Asset filename to analyze
    
    Returns:
    - True if asset is incompatible with current machine
    
    Combines all compatibility checks:
    - Operating system compatibility
    - Architecture compatibility  
    - Distribution compatibility
    - Bitness compatibility
    """

def rpm_installed_version(name: str) -> str:
    """
    Get installed version of an RPM package.
    
    Parameters:
    - name: RPM package name
    
    Returns:
    - Version string of installed package or None if not installed
    
    Uses:
    - rpm command-line tool for version queries
    - Handles package name variations and provides
    """

def extract_appimage_desktop_file(appimage_path: str) -> str:
    """
    Extract desktop file from AppImage for system integration.
    
    Parameters:
    - appimage_path: Path to AppImage file
    
    Returns:
    - Desktop file content as string
    
    Features:
    - Mounts AppImage temporarily
    - Extracts .desktop file content
    - Handles AppImage format variations
    - Provides metadata for system integration
    """

def ensure_directory_exists(directory_path: str) -> None:
    """
    Ensure directory exists, creating parent directories as needed.
    
    Parameters:
    - directory_path: Directory path to create
    
    Features:
    - Creates parent directories recursively
    - Handles existing directories gracefully
    - Proper error handling for permission issues
    """

def get_content_disposition_filename(response: requests.Response) -> str:
    """
    Extract filename from HTTP Content-Disposition header.
    
    Parameters:
    - response: requests.Response object
    
    Returns:
    - Extracted filename or None if not found
    
    Handles:
    - Various Content-Disposition header formats
    - Unicode filename encoding
    - Fallback to URL-based filename extraction
    """

from lastversion.utils import download_file, extract_file

# Simple file download
local_file = download_file("https://example.com/software.tar.gz")
print(f"Downloaded to: {local_file}")

# Download with custom filename
download_file("https://example.com/file.zip", "custom-name.zip")

# Download and extract in one operation
extract_file("https://example.com/archive.tar.gz", to_dir="/tmp/extracted")

from lastversion.utils import (
    is_asset_name_compatible_with_platform,
    asset_does_not_belong_to_machine
)

# Check individual assets for compatibility
assets = [
    "software-1.0-linux-x86_64.tar.gz",
    "software-1.0-windows-x64.exe", 
    "software-1.0-macos-arm64.dmg",
]

compatible_assets = []
for asset in assets:
    if is_asset_name_compatible_with_platform(asset):
        compatible_assets.append(asset)

print(f"Compatible assets: {compatible_assets}")

# Comprehensive compatibility check
for asset in assets:
    if not asset_does_not_belong_to_machine(asset):
        print(f"Asset {asset} is compatible with this machine")

import io
from lastversion.utils import extract_tar, check_if_tar_safe
import tarfile

# Safe TAR extraction
with open("archive.tar.gz", "rb") as f:
    buffer = io.BytesIO(f.read())

# Verify archive safety before extraction
with tarfile.open(fileobj=buffer, mode="r:gz") as tar:
    if check_if_tar_safe(tar):
        buffer.seek(0)  # Reset buffer position
        extract_tar(buffer, "/safe/extraction/path")
    else:
        print("Archive contains unsafe paths - extraction blocked")

from lastversion.utils import rpm_installed_version

# Check installed RPM version
current_version = rpm_installed_version("nginx")
if current_version:
    print(f"Nginx version {current_version} is installed")
else:
    print("Nginx is not installed")

# Use with version comparison
from lastversion import has_update
from lastversion.version import Version

if current_version:
    update_available = has_update("nginx/nginx", current_version)
    if update_available:
        print(f"Update available: {current_version} → {update_available}")

from lastversion.utils import extract_appimage_desktop_file
import os

# Extract desktop file for system integration
appimage_path = "/path/to/application.AppImage"
if os.path.exists(appimage_path):
    desktop_content = extract_appimage_desktop_file(appimage_path)
    
    # Save desktop file for system integration
    desktop_file = "/home/user/.local/share/applications/application.desktop"
    with open(desktop_file, "w") as f:
        f.write(desktop_content)

import requests
from lastversion.utils import get_content_disposition_filename

# Download with automatic filename detection
response = requests.get("https://example.com/download", stream=True)
filename = get_content_disposition_filename(response)

if filename:
    print(f"Server suggested filename: {filename}")
else:
    # Fallback to URL-based filename
    filename = "download.bin"

# Save file with detected name
with open(filename, "wb") as f:
    for chunk in response.iter_content(chunk_size=8192):
        f.write(chunk)