os-craft
RU: Легковесные, надежные и типизированные утилиты для взаимодействия Python-приложений с операционной системой.
EN: Lightweight, robust, and strictly typed utilities for seamless Python-to-OS interaction.
📦 Modules / Модули
| Модуль | Назначение | Документация |
|---|---|---|
ShutdownManager |
Graceful shutdown: LIFO-хуки, единый таймаут, корректные exit-коды | docs/shutdown.md |
load_config |
Типизированная загрузка конфига: default → TOML → ENV | docs/config.md |
HotReloadConfig |
Горячая перезагрузка конфигурации без рестарта процесса | docs/config.md |
track_perf / track_block |
Профилирование времени и памяти (tracemalloc) | docs/perf.md |
Подробная документация по каждому модулю живёт в docs/ — там полные примеры, гарантии и технические детали.
🚀 Installation / Установка
# Рекомендуемый способ (через uv - молниеносный пакетный менеджер)
uv add os-craft
# Классический способ
pip install os-craft
⚡ Quick Start / Быстрый старт
import asyncio
import sys
from dataclasses import dataclass, field
from os_craft import ShutdownManager, load_config
@dataclass
class AppConfig:
port: int = 8000
debug: bool = False
allowed_origins: list[str] = field(default_factory=list)
async def close_database():
print(" Закрываем соединения с БД...")
await asyncio.sleep(1)
async def main() -> ShutdownManager:
# Конфигурация: default -> config.toml -> переменные окружения (APP_*)
config = load_config(AppConfig, env_prefix="APP")
print(f" PORT={config.port}, DEBUG={config.debug}")
# Graceful shutdown: хуки выполняются в обратном порядке (LIFO)
manager = ShutdownManager(total_timeout=5.0)
manager.add_hook(close_database)
manager.attach_to_signals() # SIGINT / SIGTERM
try:
while True:
await asyncio.sleep(1)
except asyncio.CancelledError:
pass # менеджер уже завершает хуки
return manager
if __name__ == "__main__":
manager = asyncio.run(main())
sys.exit(manager.exit_code) # 0 - успех, 1 - ошибка в хуке
🏗️ Project Structure / Структура проекта
os-craft/
├── .github/
│ └── workflows/
│ └── ci.yml # CI: ruff, mypy strict, pytest (Python 3.10-3.12)
├── docs/
│ ├── shutdown.md # Документация ShutdownManager
│ ├── config.md # Документация load_config + HotReloadConfig
│ └── perf.md # Документация track_perf / track_block
├── pyproject.toml # Конфигурация проекта, зависимостей и инструментов
├── uv.lock # Lock-файл для воспроизводимых сборок
├── README.md # Этот файл (индекс документации)
├── LICENSE # MIT License
├── .gitignore # Исключения для git (вкл. editor swap-файлы)
├── .python-version # Версия Python для uv
├── src/
│ └── os_craft/
│ ├── __init__.py # Публичный API пакета (версия из metadata)
│ ├── shutdown.py # ShutdownManager (graceful shutdown)
│ ├── config.py # load_config + HotReloadConfig (конфигурация)
│ ├── perf.py # track_perf + track_block (профилирование)
│ └── py.typed # Маркер для mypy (PEP 561)
├── tests/
│ ├── test_shutdown.py # Тесты для ShutdownManager
│ ├── test_config.py # Тесты для load_config
│ ├── test_hot_reload.py # Тесты для HotReloadConfig
│ └── test_perf.py # Тесты для track_perf / track_block
└── examples/
├── fastapi_graceful_shutdown.py # Пример интеграции с FastAPI
├── graceful_shutdown.py # Пример graceful shutdown без FastAPI
├── config_usage.py # Пример load_config
├── config.toml # Демо-конфиг для config_usage
├── hot_reload_usage.py # Пример HotReloadConfig
├── hot_reload.toml # Демо-конфиг для hot_reload_usage
└── perf_usage.py # Пример track_perf / track_block
Все 40 тестов запускаются одной командой: uv run pytest -v
🧪 Development / Разработка
Мы используем uv для молниеносного управления зависимостями и сборки.
Установка окружения
# Клонирование репозитория
git clone https://github.com/suvorinov/os-craft.git
cd os-craft
# Установка зависимостей (создаст .venv и установит все пакеты)
uv sync
# Установка пакета в editable-режиме (для локальной разработки)
uv pip install -e .
Запуск тестов
uv run pytest -v
Тесты покрывают все модули:
tests/test_shutdown.py— порядок LIFO, таймауты, sync/async хуки, идемпотентность, обработка реальных сигналов SIGINT.tests/test_config.py— значения по умолчанию, TOML, ENV-переопределения, приведение типов, обработка ошибок.tests/test_hot_reload.py— горячая перезагрузка конфигурации, коллбэки, отказоустойчивость watcher.tests/test_perf.py— время и память через tracemalloc, декоратор функций и классов, коллбэки-метрики.
Проверка типов и линтинг
# Проверка типов (строгий режим)
uv run mypy src/os_craft
# Линтер (автоматическое исправление проблем)
uv run ruff check . --fix
Сборка пакета
uv build
Это создаст папку dist/ с .tar.gz и .whl файлами, готовыми для публикации на PyPI.
🤝 Contributing / Участие в разработке
Мы приветствуем вклад в развитие проекта! Если вы нашли баг или хотите добавить новую утилиту:
- Форкните репозиторий.
- Создайте ветку для вашей фичи:
git checkout -b feature/amazing-feature - Убедитесь, что все тесты проходят:
uv run pytest - Проверьте линтер и типы:
uv run ruff check . && uv run mypy src/os_craft - Сделайте коммит:
git commit -m 'Add amazing feature' - Отправьте в main:
git push origin feature/amazing-feature - Откройте 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.
Metadata
Release files for os-craft 0.1.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| os_craft-0.1.4.tar.gz | 81.8 kB | Without provenance | Details for os_craft-0.1.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| os_craft-0.1.4-py3-none-any.whl | Python 3 | none | any | Details for os_craft-0.1.4-py3-none-any.whl |
Total release size: 99.9 kB
Release files / os_craft-0.1.4.tar.gz
| Download URL | os_craft-0.1.4.tar.gz |
|---|---|
| Size | 81.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
569d9c2e7878197701727fa1cc1a05b97db1dd07b6b3e739928ab6565aa8de5c
|
|
BLAKE2b-256 checksum How to use checksums |
b91e041479f14aaccaac7af9acc9c4692a78d99d6ed9190cd066e9543449a305
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.13 {"installer":{"name":"uv","version":"0.9.13"},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / os_craft-0.1.4-py3-none-any.whl
| Download URL | os_craft-0.1.4-py3-none-any.whl |
|---|---|
| Size | 18.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a3fbc52de10e421cf61eab6545844ae0742d4893ab32ca9284037c0fe381aa6b
|
|
BLAKE2b-256 checksum How to use checksums |
d75ed3fbdf4573a927ec47bacadbb0192c9af5abe8f78e169f1d91b66ed3e6d6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.13 {"installer":{"name":"uv","version":"0.9.13"},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for os-craft 0.1.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.