fishertools 0.2.0__tar.gz

fishertools-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 f1sherFM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fishertools-0.2.0/PKG-INFO

@@ -0,0 +1,256 @@
+Metadata-Version: 2.4
+Name: fishertools
+Version: 0.2.0
+Summary: Fishertools - инструменты, которые делают Python удобнее и безопаснее для новичков
+Home-page: https://github.com/f1sherFM/My_1st_library_python
+Author: f1sherFM
+Author-email: f1sherFM <kirillka229top@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/f1sherFM/My_1st_library_python
+Project-URL: Repository, https://github.com/f1sherFM/My_1st_library_python
+Project-URL: Issues, https://github.com/f1sherFM/My_1st_library_python/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Requires-Dist: click>=8.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: hypothesis>=6.0.0; extra == "dev"
+Requires-Dist: black>=24.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.8.0; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# Fishertools
+
+**Инструменты, которые делают Python удобнее и безопаснее для новичков**
+
+Fishertools - это Python библиотека, созданная специально для начинающих разработчиков. Она предоставляет понятные объяснения ошибок, безопасные утилиты и обучающие инструменты.
+
+## 🎯 Основные возможности
+
+### 🚨 Объяснение ошибок Python
+Получайте понятные объяснения ошибок на русском языке с советами по исправлению:
+
+```python
+from fishertools import explain_error
+
+try:
+    numbers = [1, 2, 3]
+    print(numbers[10])
+except Exception as e:
+    explain_error(e)
+```
+
+**Вывод:**
+```
+🚨 Ошибка Python: IndexError
+
+═══ Сообщение об ошибке ═══
+  list index out of range
+
+═══ Что это означает ═══
+  Вы пытаетесь получить элемент списка по индексу, которого не существует.
+  Индексы в Python начинаются с 0, а максимальный индекс равен длине списка минус 1.
+
+═══ Как исправить ═══
+  Проверьте длину списка перед обращением к элементу или используйте
+  безопасные методы получения элементов.
+
+═══ Пример ═══
+┌─ Правильный код ─┐
+    numbers = [1, 2, 3]
+    if len(numbers) > 10:
+        print(numbers[10])
+    else:
+        print("Индекс слишком большой!")
+└───────────────────┘
+```
+
+### 🛡️ Безопасные утилиты
+Функции, которые предотвращают типичные ошибки новичков:
+
+```python
+from fishertools.safe import safe_get, safe_divide, safe_read_file
+
+# Безопасное получение элемента
+numbers = [1, 2, 3]
+result = safe_get(numbers, 10, "не найден")  # "не найден"
+
+# Безопасное деление
+result = safe_divide(10, 0, 0)  # 0 вместо ошибки
+
+# Безопасное чтение файла
+content = safe_read_file("file.txt", default="файл не найден")
+```
+
+### 📚 Обучающие инструменты
+Изучайте Python на примерах и лучших практиках:
+
+```python
+from fishertools.learn import show_best_practice, generate_example
+
+# Показать лучшие практики
+show_best_practice("variables")
+
+# Сгенерировать пример кода
+example = generate_example("functions")
+print(example)
+```
+
+### 🔄 Обратная совместимость
+Все полезные функции из предыдущих версий сохранены:
+
+```python
+from fishertools.legacy import hash_string, generate_password, QuickConfig
+
+# Старые функции работают как прежде
+password = generate_password(12)
+hash_value = hash_string("my_string")
+config = QuickConfig({"debug": True})
+```
+
+## 📦 Установка
+
+```bash
+pip install fishertools
+```
+
+Или из исходников:
+```bash
+git clone https://github.com/f1sherFM/My_1st_library_python.git
+cd My_1st_library_python
+pip install -e .
+```
+
+## 🚀 Быстрый старт
+
+```python
+from fishertools import explain_error
+
+# Основная функция - объяснение ошибок
+try:
+    result = 10 / 0
+except Exception as e:
+    explain_error(e)
+
+# Безопасные утилиты
+from fishertools.safe import safe_get, safe_divide
+safe_result = safe_get([1, 2, 3], 5, "default")
+
+# Обучающие инструменты  
+from fishertools.learn import show_best_practice
+show_best_practice("functions")
+```
+
+## 📖 Документация
+
+### Поддерживаемые типы ошибок
+
+Fishertools объясняет следующие типы ошибок Python:
+
+- **TypeError** - ошибки типов данных
+- **ValueError** - неправильные значения
+- **AttributeError** - отсутствующие атрибуты
+- **IndexError** - выход за границы списка
+- **KeyError** - отсутствующие ключи словаря
+- **ImportError** - проблемы с импортом модулей
+- **SyntaxError** - синтаксические ошибки
+
+### Безопасные утилиты
+
+- `safe_get(collection, index, default)` - безопасное получение элемента
+- `safe_divide(a, b, default)` - деление без ошибки на ноль
+- `safe_max(collection, default)` - максимум из коллекции
+- `safe_min(collection, default)` - минимум из коллекции
+- `safe_sum(collection, default)` - сумма элементов
+- `safe_read_file(path, default)` - чтение файла без ошибок
+
+### Обучающие функции
+
+- `show_best_practice(topic)` - показать лучшие практики
+- `generate_example(concept)` - сгенерировать пример кода
+- `list_available_concepts()` - список доступных концепций
+- `list_available_topics()` - список доступных тем
+
+## 🧪 Тестирование
+
+Библиотека покрыта comprehensive тестами:
+
+```bash
+# Запуск всех тестов
+pytest
+
+# Запуск property-based тестов
+pytest -k "property"
+
+# Запуск с покрытием
+pytest --cov=fishertools
+```
+
+## 🛠️ Разработка
+
+```bash
+# Установка для разработки
+pip install -e ".[dev]"
+
+# Форматирование кода
+black fishertools tests
+
+# Проверка типов
+mypy fishertools
+
+# Линтинг
+ruff check fishertools
+```
+
+## 📋 Требования
+
+- Python 3.8+
+- requests >= 2.25.0
+- click >= 8.0.0
+
+Для разработки:
+- pytest >= 8.0.0
+- hypothesis >= 6.0.0 (для property-based тестов)
+- black >= 24.0.0
+- ruff >= 0.1.0
+- mypy >= 1.8.0
+
+## 🤝 Вклад в проект
+
+Мы приветствуем вклад в развитие проекта! Пожалуйста:
+
+1. Форкните репозиторий
+2. Создайте ветку для новой функции
+3. Добавьте тесты для новой функциональности
+4. Убедитесь, что все тесты проходят
+5. Создайте Pull Request
+
+## 📄 Лицензия
+
+MIT License - см. файл [LICENSE](LICENSE)
+
+## 🙏 Благодарности
+
+Спасибо всем, кто помогает делать Python более доступным для новичков!
+
+---
+
+**Fishertools** - потому что каждый заслуживает понятные инструменты для изучения программирования! 🐍✨

fishertools-0.2.0/README.md

@@ -0,0 +1,217 @@
+# Fishertools
+
+**Инструменты, которые делают Python удобнее и безопаснее для новичков**
+
+Fishertools - это Python библиотека, созданная специально для начинающих разработчиков. Она предоставляет понятные объяснения ошибок, безопасные утилиты и обучающие инструменты.
+
+## 🎯 Основные возможности
+
+### 🚨 Объяснение ошибок Python
+Получайте понятные объяснения ошибок на русском языке с советами по исправлению:
+
+```python
+from fishertools import explain_error
+
+try:
+    numbers = [1, 2, 3]
+    print(numbers[10])
+except Exception as e:
+    explain_error(e)
+```
+
+**Вывод:**
+```
+🚨 Ошибка Python: IndexError
+
+═══ Сообщение об ошибке ═══
+  list index out of range
+
+═══ Что это означает ═══
+  Вы пытаетесь получить элемент списка по индексу, которого не существует.
+  Индексы в Python начинаются с 0, а максимальный индекс равен длине списка минус 1.
+
+═══ Как исправить ═══
+  Проверьте длину списка перед обращением к элементу или используйте
+  безопасные методы получения элементов.
+
+═══ Пример ═══
+┌─ Правильный код ─┐
+    numbers = [1, 2, 3]
+    if len(numbers) > 10:
+        print(numbers[10])
+    else:
+        print("Индекс слишком большой!")
+└───────────────────┘
+```
+
+### 🛡️ Безопасные утилиты
+Функции, которые предотвращают типичные ошибки новичков:
+
+```python
+from fishertools.safe import safe_get, safe_divide, safe_read_file
+
+# Безопасное получение элемента
+numbers = [1, 2, 3]
+result = safe_get(numbers, 10, "не найден")  # "не найден"
+
+# Безопасное деление
+result = safe_divide(10, 0, 0)  # 0 вместо ошибки
+
+# Безопасное чтение файла
+content = safe_read_file("file.txt", default="файл не найден")
+```
+
+### 📚 Обучающие инструменты
+Изучайте Python на примерах и лучших практиках:
+
+```python
+from fishertools.learn import show_best_practice, generate_example
+
+# Показать лучшие практики
+show_best_practice("variables")
+
+# Сгенерировать пример кода
+example = generate_example("functions")
+print(example)
+```
+
+### 🔄 Обратная совместимость
+Все полезные функции из предыдущих версий сохранены:
+
+```python
+from fishertools.legacy import hash_string, generate_password, QuickConfig
+
+# Старые функции работают как прежде
+password = generate_password(12)
+hash_value = hash_string("my_string")
+config = QuickConfig({"debug": True})
+```
+
+## 📦 Установка
+
+```bash
+pip install fishertools
+```
+
+Или из исходников:
+```bash
+git clone https://github.com/f1sherFM/My_1st_library_python.git
+cd My_1st_library_python
+pip install -e .
+```
+
+## 🚀 Быстрый старт
+
+```python
+from fishertools import explain_error
+
+# Основная функция - объяснение ошибок
+try:
+    result = 10 / 0
+except Exception as e:
+    explain_error(e)
+
+# Безопасные утилиты
+from fishertools.safe import safe_get, safe_divide
+safe_result = safe_get([1, 2, 3], 5, "default")
+
+# Обучающие инструменты  
+from fishertools.learn import show_best_practice
+show_best_practice("functions")
+```
+
+## 📖 Документация
+
+### Поддерживаемые типы ошибок
+
+Fishertools объясняет следующие типы ошибок Python:
+
+- **TypeError** - ошибки типов данных
+- **ValueError** - неправильные значения
+- **AttributeError** - отсутствующие атрибуты
+- **IndexError** - выход за границы списка
+- **KeyError** - отсутствующие ключи словаря
+- **ImportError** - проблемы с импортом модулей
+- **SyntaxError** - синтаксические ошибки
+
+### Безопасные утилиты
+
+- `safe_get(collection, index, default)` - безопасное получение элемента
+- `safe_divide(a, b, default)` - деление без ошибки на ноль
+- `safe_max(collection, default)` - максимум из коллекции
+- `safe_min(collection, default)` - минимум из коллекции
+- `safe_sum(collection, default)` - сумма элементов
+- `safe_read_file(path, default)` - чтение файла без ошибок
+
+### Обучающие функции
+
+- `show_best_practice(topic)` - показать лучшие практики
+- `generate_example(concept)` - сгенерировать пример кода
+- `list_available_concepts()` - список доступных концепций
+- `list_available_topics()` - список доступных тем
+
+## 🧪 Тестирование
+
+Библиотека покрыта comprehensive тестами:
+
+```bash
+# Запуск всех тестов
+pytest
+
+# Запуск property-based тестов
+pytest -k "property"
+
+# Запуск с покрытием
+pytest --cov=fishertools
+```
+
+## 🛠️ Разработка
+
+```bash
+# Установка для разработки
+pip install -e ".[dev]"
+
+# Форматирование кода
+black fishertools tests
+
+# Проверка типов
+mypy fishertools
+
+# Линтинг
+ruff check fishertools
+```
+
+## 📋 Требования
+
+- Python 3.8+
+- requests >= 2.25.0
+- click >= 8.0.0
+
+Для разработки:
+- pytest >= 8.0.0
+- hypothesis >= 6.0.0 (для property-based тестов)
+- black >= 24.0.0
+- ruff >= 0.1.0
+- mypy >= 1.8.0
+
+## 🤝 Вклад в проект
+
+Мы приветствуем вклад в развитие проекта! Пожалуйста:
+
+1. Форкните репозиторий
+2. Создайте ветку для новой функции
+3. Добавьте тесты для новой функциональности
+4. Убедитесь, что все тесты проходят
+5. Создайте Pull Request
+
+## 📄 Лицензия
+
+MIT License - см. файл [LICENSE](LICENSE)
+
+## 🙏 Благодарности
+
+Спасибо всем, кто помогает делать Python более доступным для новичков!
+
+---
+
+**Fishertools** - потому что каждый заслуживает понятные инструменты для изучения программирования! 🐍✨

fishertools-0.2.0/fishertools/__init__.py

@@ -0,0 +1,72 @@
+"""
+Fishertools - инструменты, которые делают Python удобнее и безопаснее для новичков
+
+Основная функция:
+    explain_error() - объясняет ошибки Python в понятных словах
+
+Модули:
+    errors - система объяснения ошибок
+    safe - безопасные утилиты для новичков
+    learn - обучающие инструменты
+    legacy - функции для обратной совместимости
+"""
+
+__version__ = "0.2.0"
+__author__ = "f1sherFM"
+
+# Primary API - main interface for users
+from .errors import explain_error
+
+# Exception classes for error handling
+from .errors import (
+    FishertoolsError, ExplanationError, FormattingError, 
+    ConfigurationError, PatternError, SafeUtilityError
+)
+
+# Safe utilities - commonly used beginner-friendly functions
+from .safe import (
+    safe_get, safe_divide, safe_max, safe_min, safe_sum,
+    safe_read_file, safe_write_file, safe_file_exists, 
+    safe_get_file_size, safe_list_files
+)
+
+# Learning tools - educational functions
+from .learn import (
+    generate_example, show_best_practice, 
+    list_available_concepts, list_available_topics
+)
+
+# Legacy imports for backward compatibility
+from . import utils
+from . import decorators  
+from . import helpers
+
+# Module imports for advanced users who want to access specific modules
+from . import errors
+from . import safe
+from . import learn
+from . import legacy
+
+__all__ = [
+    # Primary API - the main function users should import
+    "explain_error",
+    
+    # Exception classes for error handling
+    "FishertoolsError", "ExplanationError", "FormattingError", 
+    "ConfigurationError", "PatternError", "SafeUtilityError",
+    
+    # Safe utilities - direct access to commonly used functions
+    "safe_get", "safe_divide", "safe_max", "safe_min", "safe_sum",
+    "safe_read_file", "safe_write_file", "safe_file_exists", 
+    "safe_get_file_size", "safe_list_files",
+    
+    # Learning tools - direct access to educational functions
+    "generate_example", "show_best_practice", 
+    "list_available_concepts", "list_available_topics",
+    
+    # Legacy modules for backward compatibility
+    "utils", "decorators", "helpers",
+    
+    # New modules for advanced usage
+    "errors", "safe", "learn", "legacy"
+]

fishertools-0.2.0/fishertools/decorators.py

@@ -0,0 +1,93 @@
+"""
+Полезные декораторы для отладки, профилирования и других задач
+"""
+
+import time
+import functools
+from typing import Any, Callable
+
+
+def timer(func: Callable) -> Callable:
+    """Декоратор для измерения времени выполнения функции"""
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        start_time = time.time()
+        result = func(*args, **kwargs)
+        end_time = time.time()
+        print(f"{func.__name__} выполнилась за {end_time - start_time:.4f} секунд")
+        return result
+    return wrapper
+
+
+def debug(func: Callable) -> Callable:
+    """Декоратор для отладки - выводит аргументы и результат функции"""
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        print(f"Вызов {func.__name__} с аргументами: args={args}, kwargs={kwargs}")
+        result = func(*args, **kwargs)
+        print(f"{func.__name__} вернула: {result}")
+        return result
+    return wrapper
+
+
+def retry(max_attempts: int = 3, delay: float = 1.0):
+    """Декоратор для повторных попыток выполнения функции при ошибке"""
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            for attempt in range(max_attempts):
+                try:
+                    return func(*args, **kwargs)
+                except Exception as e:
+                    if attempt == max_attempts - 1:
+                        raise e
+                    print(f"Попытка {attempt + 1} не удалась: {e}. Повтор через {delay} сек...")
+                    time.sleep(delay)
+        return wrapper
+    return decorator
+
+
+def cache_result(func: Callable) -> Callable:
+    """Простой декоратор для кеширования результатов функции"""
+    cache = {}
+    
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        # Создаем ключ из аргументов
+        key = str(args) + str(sorted(kwargs.items()))
+        
+        if key in cache:
+            print(f"Результат {func.__name__} взят из кеша")
+            return cache[key]
+        
+        result = func(*args, **kwargs)
+        cache[key] = result
+        return result
+    
+    return wrapper
+
+
+def validate_types(**expected_types):
+    """Декоратор для проверки типов аргументов функции"""
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            # Получаем имена параметров функции
+            import inspect
+            sig = inspect.signature(func)
+            bound_args = sig.bind(*args, **kwargs)
+            bound_args.apply_defaults()
+            
+            # Проверяем типы
+            for param_name, expected_type in expected_types.items():
+                if param_name in bound_args.arguments:
+                    value = bound_args.arguments[param_name]
+                    if not isinstance(value, expected_type):
+                        raise TypeError(
+                            f"Параметр '{param_name}' должен быть типа {expected_type.__name__}, "
+                            f"получен {type(value).__name__}"
+                        )
+            
+            return func(*args, **kwargs)
+        return wrapper
+    return decorator

fishertools-0.2.0/fishertools/errors/__init__.py

@@ -0,0 +1,23 @@
+"""
+Error explanation system for fishertools.
+
+This module provides tools to explain Python errors in simple, understandable terms
+for beginners learning Python.
+"""
+
+from .explainer import ErrorExplainer, explain_error
+from .patterns import ErrorPattern
+from .formatters import ConsoleFormatter, PlainFormatter, JsonFormatter, get_formatter
+from .models import ErrorExplanation, ExplainerConfig
+from .exceptions import (
+    FishertoolsError, ExplanationError, FormattingError, 
+    ConfigurationError, PatternError, SafeUtilityError
+)
+
+__all__ = [
+    "ErrorExplainer", "explain_error", "ErrorPattern", 
+    "ConsoleFormatter", "PlainFormatter", "JsonFormatter", "get_formatter",
+    "ErrorExplanation", "ExplainerConfig",
+    "FishertoolsError", "ExplanationError", "FormattingError", 
+    "ConfigurationError", "PatternError", "SafeUtilityError"
+]