Урок за Python и API за филми
Създайте малък Python инструмент за командния ред, който приема заглавие на филм, търси го и с едно допълнително извикване взема детайли, актьори и рейтинги. Нужни са Python 3.10 или по-нов, библиотеката requests и ключ за amodb. Отнема около 15 минути и завършва с цялостен скрипт.
Ще създадете movie.py, инструмент за командния ред. Подавате му заглавие, той търси, взема първото съвпадение и отпечатва година, продължителност, жанрове, главните актьори, рейтинга от IMDb и URL адрес на постер. Нужни са Python 3.10 или по-нов, библиотеката requests и ключ за amodb. Отделете 15 минути.
Стъпка 1: Вземете API ключ
amodb е предплатен и без безплатен план, затова първо изберете план на страницата с цените. Плановете за 20, 40 и 120 заявки в минута връщат едни и същи данни. После създайте ключ в личния си профил. Ключът е 32 шестнайсетични символа с малки букви.
Експортирайте го като променлива на средата, за да остане извън изходния ви код:
В Windows PowerShell същият ред е $env:AMODB_.
export AMODB_KEY="YOUR_API_KEY"Стъпка 2: Подгответе проекта
Създайте виртуална среда и инсталирайте requests:
В Windows изпълнете .venv\Scripts\activate вместо втория ред.
python -m venv .venv
source .venv/bin/activate
pip install requestsСтъпка 3: Изпратете първата заявка
Ендпойнтът за търсене е GET /3/search/movie с параметър query. Този фрагмент отпечатва HTTP статуса и id на най-доброто съвпадение. Винаги подавайте timeout, защото requests по подразбиране чака безкрайно.
Отговорът има формата на TMDB: масив results, подреден по релевантност, плюс page и total_results. Вижте търсене за всички филтри.
import os
import requests
res = requests.get(
"https://api.amodb.dev/3/search/movie",
params={"query": "fight club", "language": "en-US"},
headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
timeout=10,
)
print(res.status_code, res.json()["results"][0]["id"])Стъпка 4: Вземете детайли, актьори и рейтинги
Резултатите от търсенето са кратки. Ползвайте id с GET / и добавете append_, за да получите актьорите и оценките от IMDb, Kinopoisk, Metacritic, Rotten Tomatoes и TMDB в същата заявка. Всяка оценка е обект с value и votes или null, когато източникът не е известен, затова проверявайте, преди да отпечатате. Подробности има на страниците филми и рейтинги. В крайния скрипт session е requests.Session, който вече носи заглавката Authorization.
params = {"language": "en-US", "append_to_response": "credits,ratings"}
movie = session.get(f"{BASE}/movie/{movie_id}", params=params, timeout=10).json()
imdb = (movie.get("ratings") or {}).get("imdb")Стъпка 5: Обработка на грешки и лимити
Проверете статуса, преди да разчетете тялото. Грешките ползват тялото на TMDB със status_code и status_message.
| Статус | Значение | Какво прави скриптът |
|---|---|---|
| 401 | Невалиден или спрян ключ | Спира и казва да проверите AMODB_KEY. Повторението не помага. |
| 404 | Няма такъв id | Отпечатва status_message. |
| 429 | Надхвърлени заявки в минута | Спи Retry-After секунди (най-много 30), после повтаря до два пъти. |
| 504 | Изтекло време на бекенда | Отпечатва се като грешка. Стартирайте командата отново. |
| Мрежова грешка | Няма връзка или изтекло време | Хваща се като requests.RequestException и се съобщава. |
Цикълът за повторения е кратък:
Още кодове са изброени на страницата грешки, а правилата за прозореца са на страницата лимити на заявките.
for attempt in range(3):
res = session.get(url, params=params, timeout=10)
if res.status_code != 429 or attempt == 2:
break
time.sleep(min(int(res.headers.get("Retry-After", "1")), 30))Стъпка 6: Кеширайте отговорите на диска
Edge държи детайлите 6 часа, а търсенето 10 минути. Собственият ви кеш спестява мрежовото пътуване и не харчи заявки от лимита ви. Крайният скрипт записва всеки отговор във файл, наименуван по хеш на пътя и параметрите, и го ползва повторно, докато е по-млад от TTL.
Стъпка 7: Цялата програма
Запазете това като movie.py и стартирайте python movie.py "fight club".
import hashlib
import json
import os
import sys
import time
from pathlib import Path
import requests
BASE = "https://api.amodb.dev/3"
POSTER = "https://img.amodb.dev/t/p/w342"
CACHE_DIR = Path.home() / ".cache" / "amodb-movie-cli"
SEARCH_TTL = 10 * 60
DETAILS_TTL = 6 * 60 * 60
class ApiError(Exception):
pass
def error_message(res):
try:
return res.json()["status_message"]
except (ValueError, KeyError):
return res.reason
def get(session, path, params, ttl):
CACHE_DIR.mkdir(parents=True, exist_ok=True)
stamp = f"{path}?{json.dumps(params, sort_keys=True)}"
cache_file = CACHE_DIR / (hashlib.sha256(stamp.encode()).hexdigest() + ".json")
if cache_file.exists() and time.time() - cache_file.stat().st_mtime < ttl:
return json.loads(cache_file.read_text(encoding="utf-8"))
for attempt in range(3):
try:
res = session.get(BASE + path, params=params, timeout=10)
except requests.RequestException as exc:
raise ApiError(f"network error: {exc}") from exc
if res.status_code != 429 or attempt == 2:
break
time.sleep(min(int(res.headers.get("Retry-After", "1")), 30))
if res.status_code == 401:
raise ApiError("401: the key is invalid or suspended. Check AMODB_KEY.")
if res.status_code != 200:
raise ApiError(f"{res.status_code}: {error_message(res)}")
cache_file.write_text(res.text, encoding="utf-8")
return res.json()
def search_movie(session, title):
data = get(session, "/search/movie", {"query": title, "language": "en-US"}, SEARCH_TTL)
if not data["results"]:
raise ApiError(f"no movie found for {title!r}")
return data["results"][0]["id"]
def movie_details(session, movie_id):
params = {"language": "en-US", "append_to_response": "credits,ratings"}
return get(session, f"/movie/{movie_id}", params, DETAILS_TTL)
def print_card(movie):
year = (movie.get("release_date") or "")[:4] or "unknown year"
genres = ", ".join(g["name"] for g in movie["genres"])
cast = ", ".join(p["name"] for p in movie["credits"]["cast"][:3])
imdb = (movie.get("ratings") or {}).get("imdb")
print(f"{movie['title']} ({year}), {movie.get('runtime') or '?'} min")
print(f"Genres: {genres or 'none listed'}")
print(f"Cast: {cast or 'none listed'}")
print(f"IMDb: {imdb['value']} ({imdb['votes']} votes)" if imdb else "IMDb: not known")
if movie.get("poster_path"):
print(f"Poster: {POSTER}{movie['poster_path']}")
print(movie.get("overview") or "No overview in this language.")
def main():
if len(sys.argv) < 2:
sys.exit('Usage: python movie.py "fight club"')
key = os.environ.get("AMODB_KEY")
if not key:
sys.exit("Set AMODB_KEY first.")
session = requests.Session()
session.headers["Authorization"] = f"Bearer {key}"
try:
movie_id = search_movie(session, " ".join(sys.argv[1:]))
print_card(movie_details(session, movie_id))
except ApiError as exc:
sys.exit(f"error: {exc}")
if __name__ == "__main__":
main()Следващи стъпки
- Отпечатайте постер в друг размер. Хостът за изображения приема всеки от размерите, изброени на страницата изображения, и не иска ключ.
- Добавете филтър
yearкъм заявката за търсене или преминете към откриване по филтри за филтрирани списъци. - Покажете индикатор за настроение до рейтинга, като добавите
moodsкъмappend_to_response. Всеки запис вmoods.resultsимаnameиavgпо скала от 0 до 10. - Прочетете бърз старт за същия процес с curl, после опитайте урока за JavaScript за пакетна версия.