Metadata-Version: 2.4
Name: aiogram-mediagroup-handle
Version: 0.1.0
Summary: aiogram media group observer
Author-email: andrei-samofalov <andrei.e.samofalov@gmail.com>
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: aiogram>=3
Description-Content-Type: text/markdown

# aiogram-mediagroup-handle

**aiogram plugin for handling media groups**

This library supports **aiogram v3 and above**.

## Overview

`aiogram-mediagroup-handle` leverages FSMStorage from the aiogram dispatcher to collect and store media files in FSM data using `media_group_id`. It comes with some utilities:
- **MediaGroupFilter** – A filter to detect media groups
- **MediaGroupMiddleware** – Middleware for handling media groups
- **MediaGroup** – A lightweight dataclass accessible in aiogram handlers

### MediaGroup Dataclass
```python
from dataclasses import dataclass, field
import typing as t
from aiogram.types import PhotoSize, Audio, Document, Video
from aiogram.enums import ContentType

@dataclass
class MediaGroup:
    """Lightweight media group representation."""
    caption: t.Optional[str] = None
    photos: list[list[PhotoSize]] = field(default_factory=list)
    audio: list[Audio] = field(default_factory=list)
    documents: list[Document] = field(default_factory=list)
    video: list[Video] = field(default_factory=list)

    @property
    def content_type(self) -> str:
        """Returns the content type of the media group."""
        if self.photos:
            return ContentType.PHOTO
        if self.documents:
            return ContentType.DOCUMENT
        if self.audio:
            return ContentType.AUDIO
        if self.video:
            return ContentType.VIDEO
        return ContentType.UNKNOWN
```

## Usage

### Registering the Observer
```python
import aiogram
from aiogram_mediagroup_handle import MediaGroupObserver

dp = aiogram.Dispatcher(...)
observer = MediaGroupObserver()
observer.register(dp)
```

### Handling Media Groups
```python
from aiogram import Router
from aiogram.types import Message
from aiogram.fsm.context import FSMContext
from aiogram_mediagroup_handle import MediaGroupFilter, MediaGroup

router = Router()

@router.message(MediaGroupFilter())
async def media_group_handler(message: Message, state: FSMContext):
    data = await state.get_data()
    media_data: MediaGroup = data[message.media_group_id]
    # Process the media group data here
```

## Installation
```sh
pip install aiogram-mediagroup-handle
```

## License
[MIT License](LICENSE)

