# JsonReader

Умный читатель и валидатор JSON-файлов с поддержкой потокового чтения и расширенной мета-информацией. Предоставляет безопасный интерфейс для работы с JSON-файлами любого размера.

## Особенности

- **🔍 Валидация синтаксиса** — проверка корректности JSON перед загрузкой
- **📊 Мета-информация** — размер, хеш, даты создания/изменения, количество строк
- **⚡ Два режима работы** — обычный (до ~50 МБ) и потоковый (для больших файлов)
- **🔄 Ленивая загрузка** — данные читаются только при первом обращении
- **📝 Статические методы записи** — сериализация с поддержкой Pydantic, Path и сложных структур
- **🔒 Атомарная запись** — предотвращение частичной записи при сбоях

## Быстрый старт

### Базовое использование

```python
from json_reader import JsonReader

# Создание читателя
reader = JsonReader("data.json")

# Проверка валидности
if reader.is_valid:
    print(f"Файл валиден, размер: {reader.size_mb} МБ")
    
    # Ленивая загрузка данных
    data = reader.data
    print(f"Тип данных: {reader.data_type}")
    print(f"Количество элементов: {reader.length}")
else:
    print(f"Ошибка: {reader.validation_error}")

# Полная информация о файле
print(reader.info())
```

### Потоковый режим для больших файлов

```python
# Для файлов больше 50 МБ
reader = JsonReader("large_data.json", use_stream=True)

if reader.is_valid:
    # Итеративная обработка без полной загрузки в память
    for item in reader.iter_items():
        process_item(item)
```

### Запись JSON-файлов

```python
data = {"users": [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]}

# Красивая запись с форматированием
JsonReader.write_pretty(data, "output.json")

# Компактная запись
JsonReader.write_compact(data, "compact_output.json")

# Кастомная запись
JsonReader.write(data, "custom.json", indent=4, ensure_ascii=True)
```

## API Reference

### Конструктор

#### `JsonReader(file_path: Union[str, Path], use_stream: bool = False)`

Создает экземпляр читателя JSON-файла.

**Параметры:**
- `file_path` — путь к JSON-файлу
- `use_stream` — использовать потоковую валидацию (для файлов >50 МБ)

**Исключения:**
- `ValueError` — если `use_stream=True`, но `ijson` не установлен
- `FileNotFoundError` — если файл не существует

### Свойства файла

#### `path: Path`
Полный путь к файлу.

#### `name: str`
Имя файла с расширением.

#### `stem: str`
Имя файла без расширения.

#### `size_bytes: int`
Размер файла в байтах.

#### `size_mb: float`
Размер файла в мегабайтах.

#### `created_at: Optional[datetime]`
Дата создания файла.

#### `modified_at: Optional[datetime]`
Дата последнего изменения.

#### `sha256: str`
SHA-256 хеш содержимого файла.

### Валидация и данные

#### `is_valid: bool`
Проверяет валидность JSON-файла.

#### `validation_error: Optional[str]`
Сообщение об ошибке валидации.

#### `data: Any`
Лениво загружает и возвращает содержимое JSON.

**Исключения:**
- `ValueError` — при ошибках парсинга JSON
- `OSError` — при ошибках чтения файла

#### `data_type: Optional[str]`
Тип корневого элемента ('dict', 'list', 'str' и т.д.).

#### `length: Optional[int]`
Длина корневого элемента (для list/dict/str).

### Методы

#### `validate_structure(required_keys: Optional[List[str]] = None) -> bool`
Проверяет наличие обязательных ключей в JSON-объекте.

**Параметры:**
- `required_keys` — список обязательных ключей

**Исключения:**
- `ValueError` — если файл невалиден или корень не объект

```python
# Проверка структуры
if reader.validate_structure(["users", "metadata"]):
    print("Структура соответствует требованиям")
```

#### `iter_items(prefix: str = '') -> Generator[Any, None, None]`
Потоковое чтение элементов (требует `use_stream=True`).

```python
# Для массивов
for item in reader.iter_items():
    print(item)

# Для объектов
for key, value in reader.iter_items():
    print(f"{key}: {value}")
```

#### `info() -> Dict[str, Any]`
Возвращает полную мета-информацию о файле.

```python
info = reader.info()
print(f"""
Path: {info['path']}
Valid: {info['valid']}
Type: {info['type']}
Size: {info['size_mb']} MB
SHA256: {info['sha256']}
""")
```

### Статические методы записи

#### `JsonReader.write(data, file_path, indent=2, ensure_ascii=False, create_parents=True, atomic=True)`
Универсальный метод записи JSON с поддержкой сложных структур.

**Поддерживает:**
- Pydantic модели (v1/v2)
- Объекты Path
- Словари с int-ключами
- Множества (set)

#### `JsonReader.write_pretty(data, file_path)`
Форматированная запись с отступами.

#### `JsonReader.write_compact(data, file_path)`
Компактная запись без форматирования.

## Примеры использования

### Мониторинг изменений файла

```python
reader1 = JsonReader("config.json")
original_hash = reader1.sha256

# После некоторых операций...
reader2 = JsonReader("config.json")
if reader2.sha256 != original_hash:
    print("Файл был изменен!")
```

### Пакетная обработка JSON-файлов

```python
from pathlib import Path

json_files = Path("data/").glob("*.json")

for file_path in json_files:
    reader = JsonReader(file_path)
    if reader.is_valid and reader.data_type == "list":
        print(f"{file_path.name}: {reader.length} элементов")
```

### Валидация конфигурационных файлов

```python
def validate_config(file_path: str) -> bool:
    reader = JsonReader(file_path)
    
    if not reader.is_valid:
        print(f"Invalid JSON: {reader.validation_error}")
        return False
    
    try:
        return reader.validate_structure(["version", "settings", "users"])
    except ValueError as e:
        print(f"Structure error: {e}")
        return False
```

## Особенности работы

### Режимы валидации

- **Обычный режим** (`use_stream=False`) — полная загрузка в память, быстрая проверка
- **Потоковый режим** (`use_stream=True`) — постепенная проверка без полной загрузки

### Производительность

| Размер файла | Рекомендуемый режим | Требования |
|--------------|---------------------|------------|
| До 50 МБ | Обычный | Стандартная библиотека |
| 50+ МБ | Потоковый | `pip install ijson` |

### Обработка ошибок

Все методы корректно обрабатывают:
- Отсутствующие файлы
- Невалидный JSON
- Проблемы с кодировкой
- Ошибки доступа
