fishertools 0.2.1__py3-none-any.whl

fishertools/safe/collections.py

@@ -0,0 +1,242 @@
+"""
+Safe collection operations for beginners.
+
+This module provides safe versions of common collection operations
+that prevent typical mistakes and provide helpful error messages.
+"""
+
+from typing import Any, Optional, Union, List, Dict, Tuple
+
+
+def safe_get(collection: Union[List, Tuple, Dict, str], index: Union[int, str], default: Any = None) -> Any:
+    """
+    Safely get an element from a collection by index or key.
+    
+    Предотвращает ошибки IndexError и KeyError, возвращая значение по умолчанию
+    вместо исключения. Подходит для списков, кортежей, словарей и строк.
+    
+    Args:
+        collection: Коллекция (список, кортеж, словарь или строка)
+        index: Индекс (для списков/кортежей/строк) или ключ (для словарей)
+        default: Значение по умолчанию, если элемент не найден
+        
+    Returns:
+        Элемент коллекции или значение по умолчанию
+        
+    Raises:
+        SafeUtilityError: If collection is None or unsupported type
+        
+    Examples:
+        >>> safe_get([1, 2, 3], 1)
+        2
+        >>> safe_get([1, 2, 3], 10, "не найдено")
+        'не найдено'
+        >>> safe_get({"name": "Иван"}, "name")
+        'Иван'
+        >>> safe_get({"name": "Иван"}, "age", 0)
+        0
+    """
+    from ..errors.exceptions import SafeUtilityError
+    
+    if collection is None:
+        raise SafeUtilityError("Коллекция не может быть None. Передайте список, кортеж, словарь или строку.", 
+                             utility_name="safe_get")
+    
+    # Для словарей используем get()
+    if isinstance(collection, dict):
+        return collection.get(index, default)
+    
+    # Для списков, кортежей и строк проверяем индекс
+    if isinstance(collection, (list, tuple, str)):
+        if not isinstance(index, int):
+            raise SafeUtilityError(f"Для {type(collection).__name__} индекс должен быть числом, получен {type(index).__name__}", 
+                                 utility_name="safe_get")
+        
+        if 0 <= index < len(collection):
+            return collection[index]
+        else:
+            return default
+    
+    # Неподдерживаемый тип коллекции
+    raise SafeUtilityError(f"Неподдерживаемый тип коллекции: {type(collection).__name__}. "
+                         f"Поддерживаются: list, tuple, dict, str", 
+                         utility_name="safe_get")
+
+
+def safe_divide(a: Union[int, float], b: Union[int, float], default: Union[int, float] = 0) -> Union[int, float]:
+    """
+    Safely divide two numbers with zero division handling.
+    
+    Предотвращает ошибку ZeroDivisionError, возвращая значение по умолчанию
+    при делении на ноль.
+    
+    Args:
+        a: Делимое (число)
+        b: Делитель (число)
+        default: Значение по умолчанию при делении на ноль
+        
+    Returns:
+        Результат деления или значение по умолчанию
+        
+    Raises:
+        SafeUtilityError: If arguments are not numbers
+        
+    Examples:
+        >>> safe_divide(10, 2)
+        5.0
+        >>> safe_divide(10, 0)
+        0
+        >>> safe_divide(10, 0, -1)
+        -1
+    """
+    from ..errors.exceptions import SafeUtilityError
+    import math
+    
+    # Проверяем типы входных данных
+    if not isinstance(a, (int, float)):
+        raise SafeUtilityError(f"Делимое должно быть числом, получен {type(a).__name__}", 
+                             utility_name="safe_divide")
+    
+    if not isinstance(b, (int, float)):
+        raise SafeUtilityError(f"Делитель должен быть числом, получен {type(b).__name__}", 
+                             utility_name="safe_divide")
+    
+    if not isinstance(default, (int, float)):
+        raise SafeUtilityError(f"Значение по умолчанию должно быть числом, получен {type(default).__name__}", 
+                             utility_name="safe_divide")
+    
+    # Проверяем деление на ноль
+    if b == 0:
+        return default
+    
+    # Выполняем деление
+    result = a / b
+    
+    # Проверяем на бесконечность или NaN
+    if math.isinf(result) or math.isnan(result):
+        return default
+    
+    return result
+
+
+def safe_max(collection: Union[List, Tuple], default: Any = None) -> Any:
+    """
+    Safely find maximum value in a collection.
+    
+    Предотвращает ошибку ValueError при пустой коллекции.
+    
+    Args:
+        collection: Коллекция чисел
+        default: Значение по умолчанию для пустой коллекции
+        
+    Returns:
+        Максимальное значение или значение по умолчанию
+        
+    Raises:
+        SafeUtilityError: If collection is not a list or tuple, or elements are not comparable
+        
+    Examples:
+        >>> safe_max([1, 5, 3])
+        5
+        >>> safe_max([])
+        None
+        >>> safe_max([], 0)
+        0
+    """
+    from ..errors.exceptions import SafeUtilityError
+    
+    if not isinstance(collection, (list, tuple)):
+        raise SafeUtilityError(f"Коллекция должна быть списком или кортежем, получен {type(collection).__name__}", 
+                             utility_name="safe_max")
+    
+    if len(collection) == 0:
+        return default
+    
+    try:
+        return max(collection)
+    except TypeError as e:
+        raise SafeUtilityError(f"Не удалось найти максимум: {str(e)}. "
+                             f"Убедитесь, что все элементы коллекции сравнимы.", 
+                             utility_name="safe_max", original_error=e)
+
+
+def safe_min(collection: Union[List, Tuple], default: Any = None) -> Any:
+    """
+    Safely find minimum value in a collection.
+    
+    Предотвращает ошибку ValueError при пустой коллекции.
+    
+    Args:
+        collection: Коллекция чисел
+        default: Значение по умолчанию для пустой коллекции
+        
+    Returns:
+        Минимальное значение или значение по умолчанию
+        
+    Raises:
+        SafeUtilityError: If collection is not a list or tuple, or elements are not comparable
+        
+    Examples:
+        >>> safe_min([1, 5, 3])
+        1
+        >>> safe_min([])
+        None
+        >>> safe_min([], 0)
+        0
+    """
+    from ..errors.exceptions import SafeUtilityError
+    
+    if not isinstance(collection, (list, tuple)):
+        raise SafeUtilityError(f"Коллекция должна быть списком или кортежем, получен {type(collection).__name__}", 
+                             utility_name="safe_min")
+    
+    if len(collection) == 0:
+        return default
+    
+    try:
+        return min(collection)
+    except TypeError as e:
+        raise SafeUtilityError(f"Не удалось найти минимум: {str(e)}. "
+                             f"Убедитесь, что все элементы коллекции сравнимы.", 
+                             utility_name="safe_min", original_error=e)
+
+
+def safe_sum(collection: Union[List, Tuple], default: Union[int, float] = 0) -> Union[int, float]:
+    """
+    Safely calculate sum of a collection.
+    
+    Предотвращает ошибки при пустой коллекции или несовместимых типах.
+    
+    Args:
+        collection: Коллекция чисел
+        default: Значение по умолчанию для пустой коллекции
+        
+    Returns:
+        Сумма элементов или значение по умолчанию
+        
+    Raises:
+        SafeUtilityError: If collection is not a list or tuple, or elements are not numbers
+        
+    Examples:
+        >>> safe_sum([1, 2, 3])
+        6
+        >>> safe_sum([])
+        0
+        >>> safe_sum([], 10)
+        10
+    """
+    from ..errors.exceptions import SafeUtilityError
+    
+    if not isinstance(collection, (list, tuple)):
+        raise SafeUtilityError(f"Коллекция должна быть списком или кортежем, получен {type(collection).__name__}", 
+                             utility_name="safe_sum")
+    
+    if len(collection) == 0:
+        return default
+    
+    try:
+        return sum(collection)
+    except TypeError as e:
+        raise SafeUtilityError(f"Не удалось вычислить сумму: {str(e)}. "
+                             f"Убедитесь, что все элементы коллекции являются числами.", 
+                             utility_name="safe_sum", original_error=e)

fishertools/safe/files.py

@@ -0,0 +1,240 @@
+"""
+Safe file operations for beginners.
+
+This module provides safe file handling utilities that prevent common
+file-related errors and provide helpful error messages.
+"""
+
+import os
+from pathlib import Path
+from typing import Union, Optional, List
+
+
+def safe_read_file(filepath: Union[str, Path], encoding: str = 'utf-8', default: str = '') -> str:
+    """
+    Safely read a file with comprehensive error handling.
+    
+    Предотвращает ошибки FileNotFoundError, PermissionError и UnicodeDecodeError,
+    возвращая значение по умолчанию вместо исключения.
+    
+    Args:
+        filepath: Путь к файлу (строка или Path объект)
+        encoding: Кодировка файла (по умолчанию utf-8)
+        default: Значение по умолчанию при ошибке чтения
+        
+    Returns:
+        Содержимое файла или значение по умолчанию
+        
+    Raises:
+        SafeUtilityError: If filepath is None or invalid type
+        
+    Examples:
+        >>> safe_read_file("example.txt")
+        'содержимое файла'
+        >>> safe_read_file("несуществующий.txt", default="файл не найден")
+        'файл не найден'
+    """
+    from ..errors.exceptions import SafeUtilityError
+    
+    if filepath is None:
+        raise SafeUtilityError("Путь к файлу не может быть None", utility_name="safe_read_file")
+    
+    if not isinstance(filepath, (str, Path)):
+        raise SafeUtilityError(f"Путь к файлу должен быть строкой или Path объектом, получен {type(filepath).__name__}", 
+                             utility_name="safe_read_file")
+    
+    if not isinstance(encoding, str):
+        raise SafeUtilityError(f"Кодировка должна быть строкой, получен {type(encoding).__name__}", 
+                             utility_name="safe_read_file")
+    
+    try:
+        with open(filepath, 'r', encoding=encoding) as file:
+            return file.read()
+    except FileNotFoundError:
+        return default
+    except PermissionError:
+        return default
+    except UnicodeDecodeError:
+        return default
+    except OSError:
+        # Covers other OS-related errors
+        return default
+
+
+def safe_write_file(filepath: Union[str, Path], content: str, encoding: str = 'utf-8', 
+                   create_dirs: bool = True) -> bool:
+    """
+    Safely write content to a file with error handling.
+    
+    Предотвращает ошибки при записи файла и может создавать директории.
+    
+    Args:
+        filepath: Путь к файлу
+        content: Содержимое для записи
+        encoding: Кодировка файла
+        create_dirs: Создавать ли директории если они не существуют
+        
+    Returns:
+        True если запись успешна, False при ошибке
+        
+    Raises:
+        SafeUtilityError: If arguments have invalid types
+        
+    Examples:
+        >>> safe_write_file("output.txt", "Hello World")
+        True
+        >>> safe_write_file("/invalid/path/file.txt", "content", create_dirs=False)
+        False
+    """
+    from ..errors.exceptions import SafeUtilityError
+    
+    if filepath is None:
+        raise SafeUtilityError("Путь к файлу не может быть None", utility_name="safe_write_file")
+    
+    if not isinstance(filepath, (str, Path)):
+        raise SafeUtilityError(f"Путь к файлу должен быть строкой или Path объектом, получен {type(filepath).__name__}", 
+                             utility_name="safe_write_file")
+    
+    if not isinstance(content, str):
+        raise SafeUtilityError(f"Содержимое должно быть строкой, получен {type(content).__name__}", 
+                             utility_name="safe_write_file")
+    
+    if not isinstance(encoding, str):
+        raise SafeUtilityError(f"Кодировка должна быть строкой, получен {type(encoding).__name__}", 
+                             utility_name="safe_write_file")
+    
+    try:
+        filepath = Path(filepath)
+        
+        # Create directories if requested
+        if create_dirs and filepath.parent != filepath:
+            filepath.parent.mkdir(parents=True, exist_ok=True)
+        
+        with open(filepath, 'w', encoding=encoding) as file:
+            file.write(content)
+        return True
+    except (PermissionError, OSError, UnicodeEncodeError):
+        return False
+
+
+def safe_file_exists(filepath: Union[str, Path]) -> bool:
+    """
+    Safely check if a file exists.
+    
+    Предотвращает ошибки при проверке существования файла.
+    
+    Args:
+        filepath: Путь к файлу
+        
+    Returns:
+        True если файл существует, False иначе
+        
+    Raises:
+        SafeUtilityError: If filepath is None or invalid type
+        
+    Examples:
+        >>> safe_file_exists("example.txt")
+        True
+        >>> safe_file_exists("несуществующий.txt")
+        False
+    """
+    from ..errors.exceptions import SafeUtilityError
+    
+    if filepath is None:
+        raise SafeUtilityError("Путь к файлу не может быть None", utility_name="safe_file_exists")
+    
+    if not isinstance(filepath, (str, Path)):
+        raise SafeUtilityError(f"Путь к файлу должен быть строкой или Path объектом, получен {type(filepath).__name__}", 
+                             utility_name="safe_file_exists")
+    
+    try:
+        return Path(filepath).exists() and Path(filepath).is_file()
+    except (OSError, ValueError):
+        return False
+
+
+def safe_get_file_size(filepath: Union[str, Path], default: int = 0) -> int:
+    """
+    Safely get file size in bytes.
+    
+    Предотвращает ошибки при получении размера файла.
+    
+    Args:
+        filepath: Путь к файлу
+        default: Значение по умолчанию при ошибке
+        
+    Returns:
+        Размер файла в байтах или значение по умолчанию
+        
+    Raises:
+        SafeUtilityError: If filepath is None or invalid type
+        
+    Examples:
+        >>> safe_get_file_size("example.txt")
+        1024
+        >>> safe_get_file_size("несуществующий.txt")
+        0
+    """
+    from ..errors.exceptions import SafeUtilityError
+    
+    if filepath is None:
+        raise SafeUtilityError("Путь к файлу не может быть None", utility_name="safe_get_file_size")
+    
+    if not isinstance(filepath, (str, Path)):
+        raise SafeUtilityError(f"Путь к файлу должен быть строкой или Path объектом, получен {type(filepath).__name__}", 
+                             utility_name="safe_get_file_size")
+    
+    try:
+        return Path(filepath).stat().st_size
+    except (OSError, FileNotFoundError):
+        return default
+
+
+def safe_list_files(directory: Union[str, Path], pattern: str = "*", default: Optional[List[str]] = None) -> List[str]:
+    """
+    Safely list files in a directory.
+    
+    Предотвращает ошибки при чтении содержимого директории.
+    
+    Args:
+        directory: Путь к директории
+        pattern: Паттерн для фильтрации файлов (например, "*.txt")
+        default: Значение по умолчанию при ошибке
+        
+    Returns:
+        Список имен файлов или значение по умолчанию
+        
+    Raises:
+        SafeUtilityError: If directory is None or invalid type
+        
+    Examples:
+        >>> safe_list_files(".")
+        ['file1.txt', 'file2.py']
+        >>> safe_list_files("несуществующая_папка")
+        []
+    """
+    from ..errors.exceptions import SafeUtilityError
+    
+    if default is None:
+        default = []
+    
+    if directory is None:
+        raise SafeUtilityError("Путь к директории не может быть None", utility_name="safe_list_files")
+    
+    if not isinstance(directory, (str, Path)):
+        raise SafeUtilityError(f"Путь к директории должен быть строкой или Path объектом, получен {type(directory).__name__}", 
+                             utility_name="safe_list_files")
+    
+    if not isinstance(pattern, str):
+        raise SafeUtilityError(f"Паттерн должен быть строкой, получен {type(pattern).__name__}", 
+                             utility_name="safe_list_files")
+    
+    try:
+        directory_path = Path(directory)
+        if not directory_path.exists() or not directory_path.is_dir():
+            return default
+        
+        files = [f.name for f in directory_path.glob(pattern) if f.is_file()]
+        return sorted(files)
+    except (OSError, ValueError):
+        return default

fishertools/safe/strings.py

@@ -0,0 +1,15 @@
+"""
+Safe string operations for beginners.
+
+This module will contain safe string handling utilities.
+Implementation will be completed in task 7.
+"""
+
+
+def safe_string_operations():
+    """
+    Placeholder for safe string operations.
+    
+    Implementation will be completed in task 7.
+    """
+    pass

fishertools/utils.py

@@ -0,0 +1,57 @@
+"""
+Утилиты для работы с файлами, данными и другими частыми задачами
+"""
+
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+def read_json(filepath: str) -> Dict[str, Any]:
+    """Читает JSON файл и возвращает словарь"""
+    with open(filepath, 'r', encoding='utf-8') as f:
+        return json.load(f)
+
+
+def write_json(data: Dict[str, Any], filepath: str, indent: int = 2) -> None:
+    """Записывает данные в JSON файл"""
+    with open(filepath, 'w', encoding='utf-8') as f:
+        json.dump(data, f, ensure_ascii=False, indent=indent)
+
+
+def ensure_dir(path: str) -> None:
+    """Создает директорию если она не существует"""
+    Path(path).mkdir(parents=True, exist_ok=True)
+
+
+def get_file_size(filepath: str) -> int:
+    """Возвращает размер файла в байтах"""
+    return os.path.getsize(filepath)
+
+
+def list_files(directory: str, extension: Optional[str] = None) -> List[str]:
+    """Возвращает список файлов в директории с опциональной фильтрацией по расширению"""
+    path = Path(directory)
+    if extension:
+        pattern = f"*.{extension.lstrip('.')}"
+        return [str(f) for f in path.glob(pattern)]
+    return [str(f) for f in path.iterdir() if f.is_file()]
+
+
+def timestamp() -> str:
+    """Возвращает текущую временную метку в читаемом формате"""
+    return time.strftime("%Y-%m-%d %H:%M:%S")
+
+
+def flatten_dict(d: Dict[str, Any], parent_key: str = '', sep: str = '.') -> Dict[str, Any]:
+    """Превращает вложенный словарь в плоский"""
+    items = []
+    for k, v in d.items():
+        new_key = f"{parent_key}{sep}{k}" if parent_key else k
+        if isinstance(v, dict):
+            items.extend(flatten_dict(v, new_key, sep=sep).items())
+        else:
+            items.append((new_key, v))
+    return dict(items)