docs: expand README with detailed setup and usage guide

Author: Danex-Exe

docs/README.md

@@ -1,170 +1,233 @@
-Welcome to DBase documentation. For the latest documentation, visit our [GitHub repository](https://github.com/Danex-Exe/dbase).
+# DBase
 
-## Quick Links
+Лёгкая JSON-based библиотека для хранения данных с интерфейсом, похожим на словарь и атрибуты объекта.
 
-- [Full Documentation](https://github.com/Danex-Exe/dbase#readme)
-- [API Reference](#api-reference)
-- [Examples](#examples)
-- [Changelog](https://github.com/Danex-Exe/dbase/blob/main/docs/CHANGELOG.md)
+- Простая запись: `db.user = "alice"` или `db["user"] = "alice"`
+- Автосохранение в файл JSON
+- Контекстный менеджер (`with DataBase(...) as db:`)
+- Временные БД (`is_temp=True`)
+- Опциональное простое шифрование при сохранении (`encryption_key`)
 
-## Installation
+---
+
+## Содержание
+
+1. [Установка](#установка)
+2. [Быстрый старт](#быстрый-старт)
+3. [Как работает хранение](#как-работает-хранение)
+4. [Шифрование данных](#шифрование-данных)
+5. [Основной API](#основной-api)
+6. [Практические примеры](#практические-примеры)
+7. [Запуск тестов и CI/CD](#запуск-тестов-и-cicd)
+8. [Docker и docker-compose](#docker-и-docker-compose)
+9. [Ограничения и рекомендации](#ограничения-и-рекомендации)
+
+---
+
+## Установка
+
+### 1) Установка из PyPI
 
 ```bash
 pip install dbase
 ```
 
-## Basic Example
+Проверка, что модуль установлен:
 
-```python
-from dbase import DataBase
+```bash
+python -c "from dbase import DataBase; print(DataBase)"
+```
 
-# Create or open a database
-db = DataBase(file_path="data.json")
+### 2) Установка для разработки (из исходников)
+
+```bash
+git clone https://github.com/Danex-Exe/dbase.git
+cd dbase
+python -m pip install -e .[dev]
+```
 
-# Store data
-db["name"] = "Alice"
-db.score = 95
+Что это даёт:
+- `-e` — editable mode (изменения в коде сразу доступны без переустановки)
+- `.[dev]` — устанавливает dev-зависимости (pytest, black, flake8, mypy)
 
-# Retrieve data
-print(db["name"])  # Alice
-print(db.score)    # 95
+### 3) Установка в виртуальном окружении (рекомендуется)
 
-# Use as context manager
-with DataBase(file_path="session.json") as session:
-    session.user = "admin"
-    session.timestamp = "2024-01-01"
+```bash
+python -m venv .venv
+source .venv/bin/activate   # Linux/macOS
+# .venv\Scripts\activate   # Windows PowerShell
+pip install --upgrade pip
+pip install dbase
 ```
 
-## API Reference
+---
 
-### DataBase Class
+## Быстрый старт
 
 ```python
-class DataBase(file_path=None, show_logs=True, is_temp=False)
+from dbase import DataBase
+
+# Создать или открыть БД
+with DataBase(file_path="data.json", show_logs=False) as db:
+    db.user = "alice"
+    db["score"] = 95
+
+# Повторно открыть и прочитать
+with DataBase(file_path="data.json", show_logs=False) as db:
+    print(db.user)      # alice
+    print(db["score"])  # 95
 ```
 
-**Parameters:**
-- `file_path` (str, optional): Path to JSON file for persistent storage
-- `show_logs` (bool): Enable/disable logging (default: True)
-- `is_temp` (bool): Create temporary in-memory database (default: False)
+---
 
-**Methods:**
-- `get(key, default=None)`: Get value with fallback
-- `pop(key, default=None)`: Remove and return value
-- `update(**kwargs)`: Update multiple values
-- `clear()`: Remove all data
-- `items()`: Return key-value pairs
-- `keys()`: Return all keys
-- `values()`: Return all values
+## Как работает хранение
 
-## Examples
+- Библиотека хранит публичные ключи/атрибуты в JSON-файле.
+- Защищённые служебные поля (внутренние) не сериализуются.
+- При каждом изменении значения данные сохраняются в файл.
+- Сохранение выполняется атомарно (через временный файл и замену), чтобы уменьшить риск повреждения данных.
 
-### Example 1: Basic CRUD Operations
+---
 
-```python
-db = DataBase("users.json")
+## Шифрование данных
 
-# Create
-db["user1"] = {"name": "Alice", "age": 30}
+Можно включить простое шифрование при сохранении:
 
-# Read
-user = db["user1"]
+```python
+from dbase import DataBase
 
-# Update
-db["user1"]["age"] = 31
+db = DataBase(
+    file_path="secure.json",
+    encryption_key="my-secret-key",
+    show_logs=False,
+)
 
-# Delete
-del db["user1"]
+db.api_token = "token-123"
+db.close()
 ```
 
-### Example 2: Configuration Storage
+Что важно:
+- Шифрование включается **только** если указан `encryption_key`.
+- Для чтения зашифрованного файла нужно открыть БД с тем же ключом.
+- Текущая схема — lightweight (XOR + Base64): подходит для базовой обфускации, но не для хранения высокочувствительных данных.
 
-```python
-config = DataBase("config.json")
+---
+
+## Основной API
 
-# Set configuration
-config.database.host = "localhost"
-config.database.port = 5432
-config.app.debug = True
+### Инициализация
 
-# Get configuration
-host = config.database.host
+```python
+DataBase(
+    file_path: str | None = None,
+    show_logs: bool = True,
+    is_temp: bool = False,
+    encryption_key: str | None = None,
+    auto_cleanup_temp: bool = True,
+)
 ```
 
-### Example 3: Temporary Data
+### Полезные методы
 
-```python
-# Temporary in-memory database
-cache = DataBase(is_temp=True)
+- `get(key, default=None)` — безопасное чтение с fallback
+- `update(**kwargs)` — массовое обновление
+- `pop(key, default=None)` — извлечение и удаление
+- `clear()` — очистка всех пользовательских ключей
+- `items()`, `keys()`, `values()` — как у словаря
+- `close()` — явное закрытие файла (и cleanup temp-файла для `is_temp=True`)
 
-# Store temporary data
-cache.session_token = "abc123"
-cache.timestamp = "2024-01-01T12:00:00"
+### Поддерживаемые операции
 
-# Data is lost when program ends
-```
+- `db.key = value`
+- `db["key"] = value`
+- `value = db.key`
+- `value = db["key"]`
+- `"key" in db`
+- `len(db)`
+- `del db["key"]`
 
-## Best Practices
+---
 
-1. **Use context managers** for automatic cleanup:
-   ```python
-   with DataBase("data.json") as db:
-       # Work with database
-   ```
+## Практические примеры
 
-2. **Handle missing keys** safely:
-   ```python
-   value = db.get("missing_key", default="default_value")
-   ```
+### 1) Настройки приложения
 
-3. **Use appropriate storage**:
-   - Persistent files for long-term storage
-   - Temporary databases for caching
+```python
+from dbase import DataBase
 
-4. **Enable logging** during development:
-   ```python
-   db = DataBase("data.json", show_logs=True)
-   ```
+cfg = DataBase("config.json", show_logs=False)
+cfg.app_name = "my-service"
+cfg.debug = True
+cfg.port = 8080
+cfg.close()
+```
 
+### 2) Временное хранилище
+
+```python
+from dbase import DataBase
+
+with DataBase(is_temp=True, show_logs=False) as cache:
+    cache.session_id = "abc123"
+    cache.ttl = 300
+```
 
-## Encryption (simple)
+### 3) Работа как со словарём
 
 ```python
 from dbase import DataBase
 
-secure_db = DataBase(file_path="secure.json", encryption_key="my-secret-key")
-secure_db.api_token = "token-123"
+db = DataBase("users.json", show_logs=False)
+db["u1"] = {"name": "Alice", "age": 30}
+print(db.get("u1"))
+print(db.keys())
 ```
 
-When `encryption_key` is provided, payload is stored in encrypted form using a lightweight XOR+Base64 scheme (sufficient for basic obfuscation, not for high-security storage).
+---
 
-## Docker
+## Запуск тестов и CI/CD
+
+Локально:
 
 ```bash
-docker compose up --build
+python -m pip install -e .[dev]
+pytest -q
 ```
 
-This runs the test suite inside a container.
+В репозитории настроены GitHub Actions:
+- **CI**: запускает тесты для Python 3.8 / 3.11 / 3.12
+- **CD**: собирает wheel/sdist по тегам `v*`
+
+---
 
-## Troubleshooting
+## Docker и docker-compose
 
-### Common Issues
+### Docker build + test
+
+```bash
+docker build -t dbase:local .
+docker run --rm dbase:local
+```
+
+### docker-compose
+
+```bash
+docker compose up --build
+```
 
-1. **File not found errors**: Ensure the directory exists before creating database
-2. **Permission errors**: Check file permissions
-3. **JSON decode errors**: Verify file contains valid JSON
-4. **Type errors**: Ensure you're using string keys
+Команда запускает тесты проекта в контейнере.
 
-### Getting Help
+---
 
-- Check the [GitHub Issues](https://github.com/Danex-Exe/dbase/issues)
-- Review the source code
-- Submit a bug report with reproduction steps
+## Ограничения и рекомендации
 
-## License
+1. Храните только JSON-сериализуемые значения.
+2. Для production-секретов используйте полноценную криптографию (а не lightweight-обфускацию).
+3. Используйте `with DataBase(...)` или `close()` для корректного завершения работы с файлами.
+4. Для больших объёмов/конкурентной записи рассмотрите переход на СУБД.
 
-MIT License - see LICENSE file for details.
+---
 
-## Support
+## Лицензия
 
-This project is maintained by Daniil Alekseev. For support, please open an issue on GitHub.
+MIT License. Подробности в файле `LICENSE`.