os-craft 0.1.0__tar.gz

os_craft-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

os_craft-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

os_craft-0.1.0/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.5
+Name: os-craft
+Version: 0.1.0
+Summary: Легковесные, надежные утилиты для взаимодействия Python-приложений с ОС
+Author-email: Oleg Suvorinov <suvorinovoleg@yandex.ru>
+License: MIT
+Keywords: asyncio,infrastructure,os,shutdown,signals
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# os-craft
+
+![Python Versions](https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12%20|%203.13%20|%203.14-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+![PyPI Status](https://img.shields.io/badge/pypi-coming_soon-orange)
+![Tests](https://img.shields.io/badge/tests-passing-brightgreen)
+
+**RU:** Легковесные, надежные и типизированные утилиты для взаимодействия Python-приложений с операционной системой.  
+**EN:** Lightweight, robust, and strictly typed utilities for seamless Python-to-OS interaction.
+
+---
+
+## 🚀 Installation / Установка
+
+```bash
+# Рекомендуемый способ (через uv - молниеносный пакетный менеджер)
+uv add os-craft
+
+# Классический способ
+pip install os-craft
+```
+
+## 🛡️ Core Feature: Graceful Shutdown Manager
+### Почему это важно? (Why it matters)
+Когда оркестратор (Kubernetes, systemd) или пользователь нажимает Ctrl+C, ОС отправляет процессу сигнал SIGTERM или SIGINT. По умолчанию Python просто прерывает выполнение. Если в этот момент ваша программа:
+
+    Писала данные в базу данных → транзакция оборвется, данные могут повредиться.
+    Обрабатывала фоновую задачу → результат будет потерян.
+    Держала открытые файловые дескрипторы → возможны утечки ресурсов.
+
+ShutdownManager из os-craft перехватывает эти сигналы и гарантирует упорядоченное (LIFO), ограниченное по времени (timeout) и безопасное освобождение ресурсов. После завершения всех хуков процесс автоматически завершается с кодом выхода 0.
+
+### Quick Start / Быстрый старт
+
+```python
+import asyncio
+import logging
+from os_craft import ShutdownManager
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+async def close_database():
+    """Пример хука: безопасное закрытие соединения с БД."""
+    logger.info("Закрываем соединения с БД...")
+    await asyncio.sleep(1)  # Имитация работы
+    logger.info("БД безопасно отключена.")
+
+async def stop_background_worker():
+    """Пример хука: остановка фонового воркера."""
+    logger.info("Останавливаем фоновый воркер...")
+    await asyncio.sleep(0.5)  # Имитация завершения текущей задачи
+    logger.info("Воркер остановлен.")
+
+async def main():
+    # 1. Создаем менеджер с общим таймаутом 5 секунд
+    manager = ShutdownManager(total_timeout=5.0)
+    
+    # 2. Регистрируем хуки. Они выполняются в обратном порядке (LIFO).
+    # Сначала остановим воркера, потом закроем БД.
+    manager.add_hook(close_database)
+    manager.add_hook(stop_background_worker)
+    
+    # 3. Подписываемся на сигналы ОС (SIGINT, SIGTERM)
+    loop = asyncio.get_running_loop()
+    manager.attach_to_signals(loop)
+    
+    logger.info("Приложение запущено. Нажмите Ctrl+C для корректного завершения.")
+    
+    # Имитация долгой работы приложения
+    try:
+        while True:
+            await asyncio.sleep(1)
+    except asyncio.CancelledError:
+        pass  # Ожидаем, пока manager завершит все хуки
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+#### Что произойдет при нажатии Ctrl+C:
+
+    1. INFO | Получен сигнал остановки ОС. Инициируем graceful shutdown...
+    2. INFO | Начинаем graceful shutdown. Зарегистрировано хуков: 2
+    3. INFO | Выполняем хук: stop_background_worker (доступно 5.00s)
+    4. INFO | Останавливаем фоновый воркер...
+    5. INFO | Воркер остановлен.
+    6. INFO | Выполняем хук: close_database (доступно 4.50s)
+    7. INFO | Закрываем соединения с БД...
+    8. INFO | БД безопасно отключена.
+    9.INFO | Процесс graceful shutdown успешно завершен.
+
+После этого процесс автоматически завершится с кодом выхода 0.
+
+## 📖 Real-World Example: FastAPI Integration
+
+Полный пример интеграции с FastAPI (с фоновыми задачами и имитацией БД) доступен в директории examples/fastapi_graceful_shutdown.py.
+Запуск:
+
+```bash
+    uv run python examples/fastapi_graceful_shutdown.py
+```
+
+Проверка:
+
+    1. Откройте другой терминал: curl http://127.0.0.1:8000/
+    2. Вернитесь в терминал с сервером и нажмите Ctrl+C
+    3. Наблюдайте за корректным завершением всех ресурсов
+ 
+## ⚙️ Технические детали (Technical Details)
+
+1. LIFO Execution Order (Порядок LIFO)
+
+    Хуки выполняются в порядке "последний добавлен — первый выполнен". Это критично для корректного освобождения ресурсов:
+
+    * Сначала останавливаем прием новых задач (закрываем порт веб-сервера).
+    * Затем дожидаемся завершения текущих операций.
+    * Только потом закрываем соединения с базами данных и кэшем.
+
+
+1. Unified Timeout (Единый таймаут)
+
+    Вместо таймаута на каждый хук используется общий таймаут на весь процесс shutdown. Это предотвращает ситуацию, когда первый хук "съедает" все время, а на важные последние хуки (закрытие БД) времени не остается.
+    Если общий таймаут превышен, выполнение оставшихся хуков прерывается, и процесс завершается.
+
+1. Async/Sync Agnostic (Поддержка синхронного и асинхронного кода)
+
+    Менеджер автоматически определяет тип функции через inspect.iscoroutinefunction:
+
+    * Async-хуки выполняются напрямую с await.
+    * Sync-хуки выполняются в loop.run_in_executor, чтобы никогда не блокировать asyncio event loop, даже если разработчик написал тяжелую синхронную операцию.
+
+1. Fail-Safe Design (Отказоустойчивость)
+    
+    Если один из хуков выбрасывает исключение или превышает таймаут, ShutdownManager:
+
+    * Логирует ошибку.
+    * Продолжает выполнение следующих хуков.
+    * Никогда не прерывает весь процесс очистки из-за одной ошибки.
+
+1. Automatic Process Termination (Автоматическое завершение процесса)
+
+    
+1. OS Signal Handling (Обработка сигналов ОС)
+
+    Менеджер подписывается на:
+
+    * SIGINT (Ctrl+C) — для локальной разработки.
+    * SIGTERM (сигнал 15) — для продакшена (Kubernetes, systemd, Docker).
+
+    > ⚠️ Важно: Сигнал SIGKILL (сигнал 9, kill -9) невозможно перехватить. Это защита ОС от зависших процессов. Всегда проектируйте систему так, чтобы она могла пережить внезапное завершение (например, используйте транзакции в БД).
+    
+    
+## 🧪 Development / Разработка
+
+Мы используем uv для молниеносного управления зависимостями и сборки.
+
+### Установка окружения
+
+```bash
+# Клонирование репозитория
+git clone <repository_url>
+cd os-craft
+
+# Установка зависимостей (создаст .venv и установит все пакеты)
+uv sync
+
+# Установка пакета в editable-режиме (для локальной разработки)
+uv pip install -e .
+```
+
+### Запуск тестов
+```bash
+uv run pytest -v
+```
+
+### Проверка типов и линтинг
+```bash
+# Проверка типов (строгий режим)
+uv run mypy src/os_craft
+
+# Линтер (автоматическое исправление проблем)
+uv run ruff check . --fix
+```
+### Сборка пакета
+```bash
+uv build
+```
+Это создаст папку dist/ с .tar.gz и .whl файлами, готовыми для публикации на PyPI.
+
+## 🏗️ Project Structure / Структура проекта
+
+    os-craft/
+    ├── pyproject.toml          # Конфигурация проекта, зависимостей и инструментов
+    ├── uv.lock                 # Lock-файл для воспроизводимых сборок
+    ├── README.md               # Этот файл
+    ├── LICENSE                 # MIT License
+    ├── src/
+    │   └── os_craft/
+    │       ├── __init__.py     # Публичный API пакета
+    │       ├── shutdown.py     # ShutdownManager
+    │       └── py.typed        # Маркер для mypy (PEP 561)
+    ├── tests/
+    │   └── test_shutdown.py    # Тесты для ShutdownManager
+    └── examples/
+        └── fastapi_graceful_shutdown.py  # Пример интеграции с FastAPI
+
+## 🤝 Contributing / Участие в разработке
+
+Мы приветствуем вклад в развитие проекта! Если вы нашли баг или хотите добавить новую утилиту:
+
+    1. Форкните репозиторий.
+    2. Создайте ветку для вашей фичи: git checkout -b feature/amazing-feature
+    3. Убедитесь, что все тесты проходят: uv run pytest
+    4. Проверьте линтер и типы: uv run ruff check . && uv run mypy src/os_craft
+    5. Сделайте коммит: git commit -m 'Add amazing feature'
+    6. Отправьте в main: git push origin feature/amazing-feature
+    7. Откройте Pull Request.
+    
+## 📄 License / Лицензия
+
+MIT License. Свободно используйте в коммерческих и open-source проектах.
+См. файл LICENSE для подробностей.
+
+## 🙏 Acknowledgments / Благодарности
+
+Проект создан с любовью к чистому коду, принципу KISS и уважению к разработчикам, которые хотят писать надежные Python-приложения.
+Спасибо сообществу Python за потрясающие инструменты: asyncio, contextvars, uv, ruff, mypy.
+
+**RU:** Если у вас есть вопросы или предложения, открывайте Issue или пишите в обсуждения.
+**EN:** If you have any questions or suggestions, feel free to open an Issue or start a Discussion.

os_craft-0.1.0/README.md

@@ -0,0 +1,230 @@
+# os-craft
+
+![Python Versions](https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12%20|%203.13%20|%203.14-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+![PyPI Status](https://img.shields.io/badge/pypi-coming_soon-orange)
+![Tests](https://img.shields.io/badge/tests-passing-brightgreen)
+
+**RU:** Легковесные, надежные и типизированные утилиты для взаимодействия Python-приложений с операционной системой.  
+**EN:** Lightweight, robust, and strictly typed utilities for seamless Python-to-OS interaction.
+
+---
+
+## 🚀 Installation / Установка
+
+```bash
+# Рекомендуемый способ (через uv - молниеносный пакетный менеджер)
+uv add os-craft
+
+# Классический способ
+pip install os-craft
+```
+
+## 🛡️ Core Feature: Graceful Shutdown Manager
+### Почему это важно? (Why it matters)
+Когда оркестратор (Kubernetes, systemd) или пользователь нажимает Ctrl+C, ОС отправляет процессу сигнал SIGTERM или SIGINT. По умолчанию Python просто прерывает выполнение. Если в этот момент ваша программа:
+
+    Писала данные в базу данных → транзакция оборвется, данные могут повредиться.
+    Обрабатывала фоновую задачу → результат будет потерян.
+    Держала открытые файловые дескрипторы → возможны утечки ресурсов.
+
+ShutdownManager из os-craft перехватывает эти сигналы и гарантирует упорядоченное (LIFO), ограниченное по времени (timeout) и безопасное освобождение ресурсов. После завершения всех хуков процесс автоматически завершается с кодом выхода 0.
+
+### Quick Start / Быстрый старт
+
+```python
+import asyncio
+import logging
+from os_craft import ShutdownManager
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+async def close_database():
+    """Пример хука: безопасное закрытие соединения с БД."""
+    logger.info("Закрываем соединения с БД...")
+    await asyncio.sleep(1)  # Имитация работы
+    logger.info("БД безопасно отключена.")
+
+async def stop_background_worker():
+    """Пример хука: остановка фонового воркера."""
+    logger.info("Останавливаем фоновый воркер...")
+    await asyncio.sleep(0.5)  # Имитация завершения текущей задачи
+    logger.info("Воркер остановлен.")
+
+async def main():
+    # 1. Создаем менеджер с общим таймаутом 5 секунд
+    manager = ShutdownManager(total_timeout=5.0)
+    
+    # 2. Регистрируем хуки. Они выполняются в обратном порядке (LIFO).
+    # Сначала остановим воркера, потом закроем БД.
+    manager.add_hook(close_database)
+    manager.add_hook(stop_background_worker)
+    
+    # 3. Подписываемся на сигналы ОС (SIGINT, SIGTERM)
+    loop = asyncio.get_running_loop()
+    manager.attach_to_signals(loop)
+    
+    logger.info("Приложение запущено. Нажмите Ctrl+C для корректного завершения.")
+    
+    # Имитация долгой работы приложения
+    try:
+        while True:
+            await asyncio.sleep(1)
+    except asyncio.CancelledError:
+        pass  # Ожидаем, пока manager завершит все хуки
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+#### Что произойдет при нажатии Ctrl+C:
+
+    1. INFO | Получен сигнал остановки ОС. Инициируем graceful shutdown...
+    2. INFO | Начинаем graceful shutdown. Зарегистрировано хуков: 2
+    3. INFO | Выполняем хук: stop_background_worker (доступно 5.00s)
+    4. INFO | Останавливаем фоновый воркер...
+    5. INFO | Воркер остановлен.
+    6. INFO | Выполняем хук: close_database (доступно 4.50s)
+    7. INFO | Закрываем соединения с БД...
+    8. INFO | БД безопасно отключена.
+    9.INFO | Процесс graceful shutdown успешно завершен.
+
+После этого процесс автоматически завершится с кодом выхода 0.
+
+## 📖 Real-World Example: FastAPI Integration
+
+Полный пример интеграции с FastAPI (с фоновыми задачами и имитацией БД) доступен в директории examples/fastapi_graceful_shutdown.py.
+Запуск:
+
+```bash
+    uv run python examples/fastapi_graceful_shutdown.py
+```
+
+Проверка:
+
+    1. Откройте другой терминал: curl http://127.0.0.1:8000/
+    2. Вернитесь в терминал с сервером и нажмите Ctrl+C
+    3. Наблюдайте за корректным завершением всех ресурсов
+ 
+## ⚙️ Технические детали (Technical Details)
+
+1. LIFO Execution Order (Порядок LIFO)
+
+    Хуки выполняются в порядке "последний добавлен — первый выполнен". Это критично для корректного освобождения ресурсов:
+
+    * Сначала останавливаем прием новых задач (закрываем порт веб-сервера).
+    * Затем дожидаемся завершения текущих операций.
+    * Только потом закрываем соединения с базами данных и кэшем.
+
+
+1. Unified Timeout (Единый таймаут)
+
+    Вместо таймаута на каждый хук используется общий таймаут на весь процесс shutdown. Это предотвращает ситуацию, когда первый хук "съедает" все время, а на важные последние хуки (закрытие БД) времени не остается.
+    Если общий таймаут превышен, выполнение оставшихся хуков прерывается, и процесс завершается.
+
+1. Async/Sync Agnostic (Поддержка синхронного и асинхронного кода)
+
+    Менеджер автоматически определяет тип функции через inspect.iscoroutinefunction:
+
+    * Async-хуки выполняются напрямую с await.
+    * Sync-хуки выполняются в loop.run_in_executor, чтобы никогда не блокировать asyncio event loop, даже если разработчик написал тяжелую синхронную операцию.
+
+1. Fail-Safe Design (Отказоустойчивость)
+    
+    Если один из хуков выбрасывает исключение или превышает таймаут, ShutdownManager:
+
+    * Логирует ошибку.
+    * Продолжает выполнение следующих хуков.
+    * Никогда не прерывает весь процесс очистки из-за одной ошибки.
+
+1. Automatic Process Termination (Автоматическое завершение процесса)
+
+    
+1. OS Signal Handling (Обработка сигналов ОС)
+
+    Менеджер подписывается на:
+
+    * SIGINT (Ctrl+C) — для локальной разработки.
+    * SIGTERM (сигнал 15) — для продакшена (Kubernetes, systemd, Docker).
+
+    > ⚠️ Важно: Сигнал SIGKILL (сигнал 9, kill -9) невозможно перехватить. Это защита ОС от зависших процессов. Всегда проектируйте систему так, чтобы она могла пережить внезапное завершение (например, используйте транзакции в БД).
+    
+    
+## 🧪 Development / Разработка
+
+Мы используем uv для молниеносного управления зависимостями и сборки.
+
+### Установка окружения
+
+```bash
+# Клонирование репозитория
+git clone <repository_url>
+cd os-craft
+
+# Установка зависимостей (создаст .venv и установит все пакеты)
+uv sync
+
+# Установка пакета в editable-режиме (для локальной разработки)
+uv pip install -e .
+```
+
+### Запуск тестов
+```bash
+uv run pytest -v
+```
+
+### Проверка типов и линтинг
+```bash
+# Проверка типов (строгий режим)
+uv run mypy src/os_craft
+
+# Линтер (автоматическое исправление проблем)
+uv run ruff check . --fix
+```
+### Сборка пакета
+```bash
+uv build
+```
+Это создаст папку dist/ с .tar.gz и .whl файлами, готовыми для публикации на PyPI.
+
+## 🏗️ Project Structure / Структура проекта
+
+    os-craft/
+    ├── pyproject.toml          # Конфигурация проекта, зависимостей и инструментов
+    ├── uv.lock                 # Lock-файл для воспроизводимых сборок
+    ├── README.md               # Этот файл
+    ├── LICENSE                 # MIT License
+    ├── src/
+    │   └── os_craft/
+    │       ├── __init__.py     # Публичный API пакета
+    │       ├── shutdown.py     # ShutdownManager
+    │       └── py.typed        # Маркер для mypy (PEP 561)
+    ├── tests/
+    │   └── test_shutdown.py    # Тесты для ShutdownManager
+    └── examples/
+        └── fastapi_graceful_shutdown.py  # Пример интеграции с FastAPI
+
+## 🤝 Contributing / Участие в разработке
+
+Мы приветствуем вклад в развитие проекта! Если вы нашли баг или хотите добавить новую утилиту:
+
+    1. Форкните репозиторий.
+    2. Создайте ветку для вашей фичи: git checkout -b feature/amazing-feature
+    3. Убедитесь, что все тесты проходят: uv run pytest
+    4. Проверьте линтер и типы: uv run ruff check . && uv run mypy src/os_craft
+    5. Сделайте коммит: git commit -m 'Add amazing feature'
+    6. Отправьте в main: git push origin feature/amazing-feature
+    7. Откройте Pull Request.
+    
+## 📄 License / Лицензия
+
+MIT License. Свободно используйте в коммерческих и open-source проектах.
+См. файл LICENSE для подробностей.
+
+## 🙏 Acknowledgments / Благодарности
+
+Проект создан с любовью к чистому коду, принципу KISS и уважению к разработчикам, которые хотят писать надежные Python-приложения.
+Спасибо сообществу Python за потрясающие инструменты: asyncio, contextvars, uv, ruff, mypy.
+
+**RU:** Если у вас есть вопросы или предложения, открывайте Issue или пишите в обсуждения.
+**EN:** If you have any questions or suggestions, feel free to open an Issue or start a Discussion.

os_craft-0.1.0/examples/fastapi_graceful_shutdown.py

@@ -0,0 +1,160 @@
+"""
+Пример интеграции os-craft с FastAPI для грациозного завершения работы.
+
+Этот скрипт демонстрирует, как корректно завершать:
+1. HTTP-сервер (Uvicorn).
+2. Фоновые периодические задачи (например, воркеры или очистка кэша).
+3. "Соединения с базой данных" (имитация).
+
+Запуск:
+    uv run python examples/fastapi_graceful_shutdown.py
+
+Проверка работы:
+    1. Запустите скрипт.
+    2. В другом терминале выполните: curl http://127.0.0.1:8000/
+    3. Нажмите Ctrl+C в терминале со скриптом.
+    4. Наблюдайте за логами: вы увидите, как система дожидается завершения 
+       текущих операций перед полным остановом, вместо резкого обрыва.
+"""
+
+import asyncio
+import logging
+import signal
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+import uvicorn
+
+# Импортируем наш менеджер. В реальном проекте это будет: from os_craft import ShutdownManager
+# import sys
+# from pathlib import Path
+# sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
+from os_craft import ShutdownManager
+
+# Настраиваем красивое логирование, чтобы видеть процесс shutdown в реальном времени
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s | %(levelname)-8s | %(name)s | %(message)s",
+    datefmt="%H:%M:%S"
+)
+logger = logging.getLogger("example_app")
+
+
+# --- Имитация внешних ресурсов ---
+
+class MockDatabase:
+    """Имитация пула соединений с базой данных."""
+    def __init__(self):
+        self.is_connected = False
+
+    async def connect(self):
+        logger.info("🔌 Подключение к базе данных...")
+        await asyncio.sleep(0.5) # Имитация задержки сети
+        self.is_connected = True
+        logger.info("✅ База данных подключена.")
+
+    async def disconnect(self):
+        logger.info("🔌 Закрытие соединений с базой данных...")
+        await asyncio.sleep(1.0) # Имитация безопасного закрытия транзакций
+        self.is_connected = False
+        logger.info("✅ База данных отключена безопасно.")
+
+db = MockDatabase()
+
+
+async def background_worker():
+    """
+    Имитация фоновой задачи (например, обработка очереди сообщений).
+    Эта задача должна корректно завершиться при получении сигнала остановки,
+    а не быть убита посередине обработки.
+    """
+    logger.info("⚙️ Фоновый воркер запущен.")
+    try:
+        while True:
+            logger.info("🔄 Воркер обрабатывает задачу...")
+            await asyncio.sleep(2.0) # Имитация полезной работы
+    except asyncio.CancelledError:
+        # НЕОЧЕВИДНОЕ РЕШЕНИЕ: Мы ловим CancelledError, чтобы завершить 
+        # текущую "итерацию" чисто, прежде чем выйти из цикла.
+        logger.info("🛑 Воркер получил сигнал отмены. Завершаем текущую задачу...")
+        await asyncio.sleep(0.5) # Имитация сохранения прогресса
+        logger.info("✅ Воркер корректно остановлен.")
+        raise # Пробрасываем дальше, чтобы asyncio знал, что задача отменена
+
+
+# --- Интеграция с FastAPI и os-craft ---
+
+# Создаем экземпляр менеджера. 
+# Таймаут 5 секунд: если за это время не успеем закрыться, ОС нас убьет (SIGKILL).
+shutdown_manager = ShutdownManager(total_timeout=5.0)
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """
+    Lifespan контекст FastAPI (замена устаревшим @app.on_event("startup")).
+    Здесь мы инициализируем ресурсы и регистрируем хуки завершения.
+    """
+    # 1. Инициализация при старте
+    await db.connect()
+    
+    # Запускаем фоновую задачу и сохраняем ссылку на неё, чтобы потом отменить
+    worker_task = asyncio.create_task(background_worker(), name="background_worker")
+    
+    # 2. Регистрация хуков завершения (ВАЖНО: порядок имеет значение!)
+    # Хуки выполняются в обратном порядке (LIFO). 
+    # Сначала мы должны остановить воркера, потом закрыть БД.
+    
+    # Хук 2 (выполнится вторым): закрытие БД
+    shutdown_manager.add_hook(db.disconnect)
+    
+    # Хук 1 (выполнится первым): отмена фоновой задачи
+    def cancel_worker():
+        logger.info("🛑 Инициируем отмену фонового воркера...")
+        worker_task.cancel()
+    
+    shutdown_manager.add_hook(cancel_worker)
+
+    # 3. Подписка на сигналы ОС (SIGTERM, SIGINT)
+    # Мы делаем это здесь, потому что event loop уже запущен FastAPI
+    loop = asyncio.get_running_loop()
+    shutdown_manager.attach_to_signals(loop)
+
+    logger.info("🚀 Приложение полностью готово к работе!")
+
+    yield # Здесь управление передается FastAPI/Uvicorn
+
+    # Этот блок выполнится после yield, но мы делегируем реальную очистку 
+    # нашему shutdown_manager, чтобы централизовать логику и таймауты.
+    logger.info("🔄 Завершение работы приложения через lifespan...")
+    await shutdown_manager._execute_hooks()
+
+
+# Инициализация приложения с нашим lifespan
+app = FastAPI(
+    title="os-craft FastAPI Example",
+    description="Демонстрация грациозного завершения работы с помощью os-craft",
+    version="0.1.0",
+    lifespan=lifespan
+)
+
+
+@app.get("/")
+async def root():
+    """Простой эндпоинт для проверки работоспособности."""
+    if db.is_connected:
+        return {"status": "ok", "message": "Сервер работает и подключен к БД"}
+    return {"status": "error", "message": "База данных недоступна"}
+
+
+if __name__ == "__main__":
+    # Запускаем Uvicorn. 
+    # workers=1 важен для примера, чтобы логи не перемешивались и shutdown был предсказуемым.
+    # В продакшене с os-craft лучше использовать gunicorn с uvicorn workers, 
+    # но логика graceful shutdown на уровне процесса останется той же.
+    uvicorn.run(
+        app,
+        host="127.0.0.1",
+        port=8000,
+        log_level="info",
+        workers=1
+    )