pyferrite 0.0.2

Pure-Rust reader/writer for Python ML artefacts (npy, npz, pickle, pt, joblib, hdf5) with ndarray and polars interop, lazy streaming and user-controlled numeric down-casting.
Documentation
# Ошибки и проверки

## Перечисление `Error`

| Вариант | Когда возникает |
|---|---|
| `Io(std::io::Error)` | Файл не удалось открыть, прочитать или записать |
| `Format(String)` | Байты не соответствуют заявленному формату либо файл обрезан |
| `Unsupported(String)` | Настоящая возможность формата, которую крейт не реализует; называется явно |
| `Cast(String)` | Значение не пережило бы сужающее преобразование при `CastPolicy::Strict` |
| `InvalidArgument(String)` | Сам запрос бессмысленен: строка в `.npy`, неизвестное расширение, выделение сверх `max_alloc` |
| `Shape { expected, got }` | Объявленная форма не соответствует данным |
| `Pickle(String)` | Испорченный поток pickle или отвергнутое глобальное имя |
| `Compression(String)` | Сжатый элемент не удалось распаковать либо выключена возможность `deflate` |
| `Exhausted` | Потоковый читатель вышел за конец данных |

`Error` реализует `Display` и `std::error::Error` вручную — крейты с
процедурными макросами не подтягиваются, — поэтому он сочетается с `anyhow`,
`thiserror` или обычным `Box<dyn Error>`.

## Проверки при записи

В задании на эту библиотеку требовалось, чтобы строка никогда не записывалась
там, где ожидается массив. Эта проверка и несколько других выполняются до
создания файла, поэтому отклонённая запись не оставляет следов:

```rust,no_run
# use pyferrite::prelude::*;
let e = write("x.npy", &Value::Str("hello".into())).unwrap_err();
assert!(format!("{e}").contains("npy"));
// invalid argument: `.npy` stores a single array; `str` is not one.
// Use `.npz`, `.pkl` or `.h5` for containers.
```

Что проверяется:

- **Пригодность контейнера.** `.npy` хранит ровно один массив. Все остальные
  форматы принимают вложенность.
- **Тип элементов.** Разнородный список не может стать числовым массивом, и в
  ошибке сказано, какой элемент этому помешал.
- **Форма.** У `WriteOptions::shape` должно быть то же число элементов, что и у
  данных, иначе будет `Error::Shape { expected, got }`. Именно это позволяет
  записать `[1, 6]`, а не `[6]`, когда numpy должен увидеть вектор-строку.
- **Выразимость.** Писатель HDF5 отказывается от типа, который не умеет
  выразить, а не подменяет его тихо другим.
- **Имена ссылок.** Имена в HDF5 не могут быть пустыми и содержать `/` или NUL.
- **Полнота.** `LazyWriter::finish` падает, если пришло меньше элементов, чем
  было объявлено.

## Безопасность pickle

Распаковка произвольных данных в Python исполняет произвольный код. Эта
библиотека — нет: у машины попросту нет механизма, чтобы что-либо вызвать.

1. **Белый список.** `REDUCE` и `NEWOBJ` разрешаются по фиксированной таблице
   конструкторов numpy, torch, `collections` и `_codecs`. Каждый реализован как
   функция на Rust, строящая соответствующее `Value`.
2. **Чёрный список.** `os`, `sys`, `subprocess`, `builtins.eval`,
   `builtins.exec` и их родня отвергаются с ошибкой, называющей модуль, если
   не установлен `allow_unknown_globals`. С ним они инертно сохраняются, как
   любой другой класс, чтобы подозрительный файл можно было изучить.
3. **Инертный захват.** Всё прочее становится `PyObject`, хранящим модуль, имя
   класса и аргументы конструктора. Ничего не выполняется. Объект можно
   изучить, изменить и записать обратно.
4. **Ограниченное выделение памяти.** Каждая длина, прочитанная из файла,
   сверяется с `ReadOptions::max_alloc` до того, как что-либо резервируется,
   поэтому заголовок, заявляющий петабайт, падает сразу.

```rust,no_run
# use pyferrite::prelude::*;
// Pickle, вызывающий os.system, отвергается, а не исполняется.
let e = read("suspicious.pkl").unwrap_err();
assert!(format!("{e}").contains("os"));
```

Это делает чтение недоверенной контрольной точки заметно безопаснее, чем
`pickle.load`, — хотя «безопаснее» не значит «безопасно», и файл из неизвестного
источника по-прежнему заслуживает подозрения.

## Устойчивость

Обрезанные и испорченные файлы дают ошибки, а не панику. Каждое чтение курсора
проверяется по границам, каждая длина сверяется с остатком входных данных, а у
обходчика заголовков объектов есть защита от циклов. Набор тестов покрывает
обрезание на нескольких смещениях и откровенный мусор для всех шести форматов.