This Telegram bot is a tesk task application, powered by aiogram v3, tortoise-orm and a simple async TMDB wrapper.

• Takes you straight into action, no typing needed.

• Find movies by name, any language. Get a short summary, along with the trailer link, if available.

• Get a paginated preview of current trending movies.

• Add any movie you see to your personal favourites. View them in a concise list.

• 🟢 API responses are saved to both the database and in-memory LRU/TTL cache to avoid frequent refetching.
• 🟢 The user flow is designed to be as minimally annoying as possible, both in DMs and public chats.
• 🟢 Proper error and timeout handling. It gets the job done, at least.
• 🟢 Rich logging
• 🟢 No third-party synchronous TMDB API wrappers used.
• 🟢 API responses. I don't trust them, at all! _(c) A lot of stuff is None-checked and otherwise validated.

• 🔴 The output of /favourites can exceed the character limit at some point, so I probably should've introduced a paginator.
• 🔴 DB_URL variable should be split into multiple components, the password being one of them. I don't feel like installing postgres, though, so I won't bother.

Rename .env.example to .env and set the following variables:

• BOT_TOKEN (ask @BotFather)
• TMDB_AUTH_TOKEN (you can get one here, you need the long one)
• DB_URL (the default is fine)

The project uses the uv manager. If you have it installed, just run the main file.

$ uv run src/main.py

It will automatically create a virtual environment and install the dependencies.

Otherwise, you can do it manually

$ python -m venv .venv
$ . .venv/bin/activate
(.venv) $ pip install .
(.venv) $ python src/main.py

To run with a custom log level once, use LOG:

$ LOG=debug uv run src/main.py
(.venv) $ LOG=debug python src/main.py

For persistence, change the default inside .env.