Feat file info

docs/examples.md

@@ -2,6 +2,8 @@
 
 Здесь собраны практические примеры использования MaxAPI для различных задач.
 
+Смотри так же примеры в (maxapi/examples)[https://github.com/love-apples/maxapi/tree/main/examples]
+
 ## Эхо-бот
 
 Простейший пример бота, который повторяет все текстовые сообщения:
@@ -993,6 +995,108 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
+## Инспекция файлов
+
+Для получения расширенной метаинформации о файле (формат, размер, MIME-тип, размеры
+изображения, длительность видео) без полной загрузки файла используется `UrlStr.get_info()`.
+Скачиваются только необходимоей количество байт для определения параметров медиа
+с начала файла и иногда с конца.
+
+```python
+import asyncio
+import logging
+
+from maxapi import Bot, Dispatcher, F
+from maxapi.filters.command import Command
+from maxapi.types import MessageCreated
+
+logging.basicConfig(level=logging.INFO)
+
+bot = Bot()
+dp = Dispatcher()
+
+
+@dp.message_created(Command('info'))
+async def cmd_info(event: MessageCreated):
+    replied = event.message.link.message if event.message.link else None
+    if not replied or not replied.attachments:
+        await event.message.answer('Ответьте на сообщение с файлом.')
+        return
+
+    first = replied.attachments[0]
+    url = first.url if hasattr(first, 'url') else None
+    if not url:
+        await event.message.answer('Вложение не содержит URL.')
+        return
+
+    # get_info() всегда возвращает FileInfo (в т.ч. при ошибке)
+    info = await url.get_info()
+
+    if info.status == "error":
+        await event.message.answer(f'Ошибка: {info.parse_note}')
+        return
+
+    # str(info) — человекочитаемый вывод
+    await event.message.answer(
+        f"{info}"
+        f"\nДля определения параметров файла было скачано {url.inspector.downloaded_human}"
+    )
+
+    # Докачка файла через существующее соединение
+    # Напишите собственные условия для скачивания
+    if info.mime_type.startswith("video") and info.height > 320:
+        await event.message.answer("Файл подходит. Сохраняю...")
+        path = await url.full_file_save("files/downloads_directory")
+        await event.message.answer(f'Сохранён в {path}')
+
+
+async def main():
+    await dp.start_polling(bot)
+
+
+if __name__ == '__main__':
+    asyncio.run(main())
+```
+
+Если у вас есть URL как обычная строка (не из вложения), используйте
+свободную функцию `inspect_url`:
+
+```python
+from maxapi.utils import inspect_url
+
+info = await inspect_url('https://example.com/video.mp4', timeout=10)
+print(info.format)   # "MP4"
+print(info.width)    # 1920
+print(info.height)   # 1080
+print(info.duration) # 10.0
+print(info.status)   # "ok"
+print(info)
+# Имя файла: video.mp4
+# Размер: 12,5 Мб
+# Формат: MP4
+# Размеры: 1920х1080 пикс
+# Длительность: 10 сек
+# Частота кадров: 25 к/с
+# Аудио: 48000 Гц
+# Битрейт (средний): 10240 кбит/с
+
+# Для аудио файлов моджет быть:
+# Битрейт (номинальный): 320 кбит/с"
+```
+Аналогичным способом можно проанализировать байты и файлы с диска.
+Например если вы уже скачали файл через bot.download_file(url)
+или bot.download_bytes(url)
+
+```python
+from maxapi.utils import inspect_bytes, inspect_file
+
+info = await inspect_bytes(bytes_or_bytes_io)
+print(info)
+info = await inspect_file(file_path_str_or_Path)
+print(info)
+```
+
+
 ## Webhook
 
 ### Высокоуровневый подход

docs/guides/file_inspector.md

@@ -0,0 +1,165 @@
+# Получение метаинформации о медиафайлах
+
+Библиотека `maxapi` позволяет извлекать метаданные медиафайлов (формат, размеры, длительность, битрейт) по URL **без полной загрузки**, локальному пути или байтам в памяти.
+Анализирует сигнатуры и заголовки в первых и последних байтах файла. Скачивает минимум данных, докачивает
+только если не хватило.
+
+Это полезно для:
+
+- Быстрой проверки типа файла перед скачиванием.
+- Получения размеров изображений/видео для отображения в UI.
+- Определения длительности аудио/видео для превью.
+
+## Поддерживаемые форматы
+
+FileInspector распознает метаданные для популярных медиаформатов:
+* Изображения: JPEG, PNG, GIF, WebP (VP8/VP8L/VP8X)
+* Видео: MP4/MOV, AVI, MKV, WEBM, OGV
+* Аудио: MP3, AAC, WAV, WMA, FLAC, OGG, M4A
+
+Для каждого формата извлекаются поля (если доступно):
+width, height, duration, fps, sample_rate, bitrate
+
+## Быстрый старт: `bot.get_file_info()`
+
+Самый простой способ — использовать метод `bot.get_file_info()`, который принимает URL файла и возвращает `FileInfo`:
+
+```python
+from maxapi import Bot
+
+bot = Bot(token="YOUR_TOKEN")
+
+# Получаем метаинформацию о файле по URL
+info = await bot.get_file_info(
+    "https://example.com/video.mp4",
+    timeout=10,  # таймаут в секундах (опционально)
+)
+
+print(info)
+
+# Или отдельно по интересующим полям
+print(f"Формат: {info.format}")
+print(f"Размеры: {info.width}x{info.height}")
+print(f"Длительность: {info.duration} сек")
+print(f"Статус: {info.status}")  # ok, partial или error
+if info.status != "ok":
+    print(f"  Комментарий парсера: {info.parse_note}")
+```
+
+## Анализ файла на диске или байт в памяти
+
+```python
+from maxapi.utils import FileInspector
+inspector = FileInspector()
+file_info = await inspector.inspect_file("/path/to/video.avi")
+file_info = await inspector.inspect_bytes(downloaded_bytes)
+# Следующий метод интегрирован в bot.get_file_info(url)
+file_info = await inspector.inspect_url("https://example.com/photo.jpg")
+```
+
+FileInspector можно использовать повторно для других файлов.
+При этом он помнит последние скачанные данные и последний FileInfo:
+
+```python
+if inspector.last_file_info:
+    print(inspector.last_file_info)
+    print("Скачано начало файла", len(inspector.last_head), "байт")
+    if inspector.last_tail:
+        print("Скачано конца файла", len(inspector.last_tail), "байт")
+```
+
+## Обработка статусов
+
+Метод возвращает FileInfo со статусом:
+* `ok` — все ключевые метаданные успешно извлечены.
+* `partial` — часть данных получена, но чего-то не хватает (например, длительность для MP4 с moov в конце файла).
+* `error` — произошла ошибка (сеть, HTML-страница вместо файла) и не удалось определить даже размер файла.
+
+```python
+info = await bot.get_file_info(url)
+
+if info.status == "ok":
+    print(f"Полные метаданные: {info.format}, {info.width}x{info.height}")
+elif info.status == "partial":
+    print(f"Частичные данные: {info.format}, примечание: {info.parse_note}")
+else:
+    print(f"Ошибка: {info.parse_note}")
+```
+
+## Как это работает?
+
+FileInspector использует частичную загрузку:
+* HEAD-запрос для получения Content-Type и Content-Length.
+* Скачивание хвоста 64 КБ — для форматов, где метаданные в конце (MP4 с moov в конце,
+  OGG с длительностью в последней грануле).
+* Чтение начала файла от 4 до 256 КБ в зависимости от формата.
+
+Если сервер не поддерживает Range-запросы, FileInspector адаптируется и работает с тем, что есть,
+возвращая статус partial при невозможности определить некоторые поля.
+
+## Безопасность и авторизация
+
+Если вы передаете aiohttp.ClientSession с заголовками авторизации (Authorization, Cookie), они не будут отправлены на сторонние домены по умолчанию. Это защита от утечки токенов.
+Чтобы разрешить отправку авторизации на внешний URL:
+
+```python
+from maxapi.utils import FileInspector
+inspector = FileInspector()
+info = await inspector.inspect_url(
+    "https://external.com/private.mp4",
+    session=session_with_auth,
+    allow_external_auth=True,  # явно разрешаем
+)
+```
+
+Доверенные домены (**oneme.ru**, **okcdn.ru**) всегда принимают авторизацию без этого флага.
+
+## Пример в боте: команда /info
+
+Добавим команду, которая показывает метаинформацию о файле из reply-сообщения:
+
+```python
+import asyncio
+from maxapi import Bot, Dispatcher
+from maxapi.types import Message
+
+bot = Bot(token="ваш_токен")
+dp = Dispatcher()
+
+@dp.message_created(commands=["info"])
+async def cmd_info(event: MessageCreated):
+    replied_body = event.message.link.message if event.message.link else None
+    if not replied_body or not replied_body.attachments:
+        await event.message.answer("ℹ️ Ответьте этой командой на сообщение с файлом.")
+        return
+
+    first_url = None
+    # Получаем URL вложений до первого успеха
+    if replied_body.attachments:
+        for att in replied_body.attachments:
+            if hasattr(att, "url"):
+                file_info = await bot.get_file_info(att.url)
+                if file_info.status == "ok":
+                    # Собрать отдельные интересующие поля
+                    # text = f"Формат: {file_info.format}\n"
+                    # if file_info.width and file_info.height:
+                    #     text += f"Размеры: {file_info.width}x{file_info.height}\n"
+                    # if file_info.duration:
+                    #     text += f"Длительность: {file_info.duration} сек\n"
+                    # if file_info.sample_rate:
+                    #     text += f"Частота сэмплов: {file_info.sample_rate} Гц\n"
+                    # text += f"Статус: {file_info.status}"
+                    # Или просто:
+                    text = str(file_info)
+                    await event.message.answer(text)
+                    return
+
+    await event.message.answer("Вложение не найдено")
+    return
+
+
+if __name__ == '__main__':
+    asyncio.run(dp.start_polling(bot))
+```
+
+Более подробный пример (05_media_bot.py)[https://github.com/love-apples/maxapi/blob/main/examples/05_media_bot.py]

docs/utils/file_inspector.md

@@ -0,0 +1,8 @@
+# File Inspector
+
+::: maxapi.utils.file_inspector
+    options:
+        show_root_heading: true
+        members_order: source
+        filters:
+            - "!^_"