tmdbpy-wrapper 1.0.0

TMDB v3 API wrapper for Python

TMDB-PY

Python wrapper dla TMDB (The Movie Database) API v3, wzorowany na bibliotece tmdb-ts.

Instalacja

pip install tmdb-py

lub z repozytorium:

pip install -e .

Szybki start

from tmdb_py import TMDB

# Inicjalizacja klienta
tmdb = TMDB('your_access_token')

# Wyszukiwanie filmów
movies = tmdb.search.movies(query='American Pie')
print(movies)

# Szczegóły filmu
movie = tmdb.movies.details(movie_id=9340)
print(movie['title'], movie['overview'])

# Popularne filmy
popular = tmdb.movies.popular(page=1, language='pl-PL')
for movie in popular['results']:
    print(movie['title'])

Funkcjonalności

🔍 Search (3 metody)

# Wyszukiwanie filmów
movies = tmdb.search.movies(
    query='Inception',
    page=1,
    language='en-US',
    include_adult=False,
    year=2010
)

# Wyszukiwanie seriali
tv_shows = tmdb.search.tv_shows(
    query='Breaking Bad',
    page=1,
    language='en-US'
)

# Wyszukiwanie wielokrotne (filmy, seriale, osoby)
results = tmdb.search.multi(
    query='Tom Hanks',
    page=1,
    language='en-US'
)

🎬 Movies (8 metod)

# Szczegóły filmu
movie = tmdb.movies.details(
    movie_id=550,
    append_to_response=['credits', 'videos', 'images'],
    language='en-US'
)

# Obrazy filmu
images = tmdb.movies.images(
    movie_id=550,
    language='en-US',
    include_image_language=['en', 'pl']
)

# Recenzje
reviews = tmdb.movies.reviews(movie_id=550, page=1)

# Podobne filmy
similar = tmdb.movies.similar(movie_id=550, page=1)

# Wideo (zwiastuny, behind the scenes)
videos = tmdb.movies.videos(movie_id=550)

# Filmy obecnie w kinach
now_playing = tmdb.movies.now_playing(language='pl-PL', region='PL')

# Popularne filmy
popular = tmdb.movies.popular(language='pl-PL', page=1)

# Najwyżej oceniane filmy
top_rated = tmdb.movies.top_rated(language='pl-PL', page=1)

📺 TV Shows (7 metod)

# Szczegóły serialu
tv_show = tmdb.tv_shows.details(
    tv_id=1396,
    append_to_response=['credits', 'videos'],
    language='en-US'
)

# Szczegóły sezonu
season = tmdb.tv_shows.season(tv_id=1396, season_number=1)

# Obrazy serialu
images = tmdb.tv_shows.images(tv_id=1396)

# Podobne seriale
similar = tmdb.tv_shows.similar(tv_id=1396, page=1)

# Wideo
videos = tmdb.tv_shows.videos(tv_id=1396)

# Seriale obecnie emitowane
on_air = tmdb.tv_shows.on_the_air(language='en-US', page=1)

# Popularne seriale
popular = tmdb.tv_shows.popular(language='en-US', page=1)

# Najwyżej oceniane seriale
top_rated = tmdb.tv_shows.top_rated(language='en-US', page=1)

📅 TV Seasons (3 metody)

# Szczegóły sezonu
season = tmdb.tv_seasons.details(
    tv_show_id=1396,
    season_number=1,
    append_to_response=['credits', 'videos'],
    language='en-US'
)

# Obrazy sezonu
images = tmdb.tv_seasons.images(
    tv_show_id=1396,
    season_number=1,
    language='en-US'
)

# Wideo sezonu
videos = tmdb.tv_seasons.videos(
    tv_show_id=1396,
    season_number=1,
    language='en-US'
)

🎥 TV Episodes (3 metody)

# Szczegóły odcinka
episode = tmdb.tv_episodes.details(
    tv_show_id=1396,
    season_number=1,
    episode_number=1,
    append_to_response=['credits', 'videos'],
    language='en-US'
)

# Obrazy odcinka
images = tmdb.tv_episodes.images(
    tv_show_id=1396,
    season_number=1,
    episode_number=1,
    language='en-US'
)

# Wideo odcinka
videos = tmdb.tv_episodes.videos(
    tv_show_id=1396,
    season_number=1,
    episode_number=1,
    language='en-US'
)

🔥 Trending (1 metoda)

# Trendy
trending_movies = tmdb.trending.trending(
    media_type='movie',  # 'all', 'movie', 'tv', 'person'
    time_window='week',  # 'day', 'week'
    language='en-US',
    page=1
)

# Trendy - wszystko
trending_all = tmdb.trending.trending(
    media_type='all',
    time_window='day'
)

🎭 Genres (2 metody + helper)

# Gatunki filmów
movie_genres = tmdb.genre.movies(language='pl-PL')

# Gatunki seriali
tv_genres = tmdb.genre.tv_shows(language='pl-PL')

# Helper - pobierz nazwę gatunku po ID
from tmdb_py.endpoints.genre import get_genre_name

genre_name = get_genre_name(28)  # "Action"

Obsługa błędów

from tmdb_py import TMDB, TMDBException, TMDBNotFoundError

tmdb = TMDB('your_access_token')

try:
    movie = tmdb.movies.details(movie_id=999999999)
except TMDBNotFoundError as e:
    print(f"Film nie znaleziony: {e.message}")
except TMDBException as e:
    print(f"Błąd API: {e.message} (kod: {e.status_code})")

Dostępne wyjątki

• TMDBException - bazowy wyjątek
• TMDBAuthenticationError - błąd autentykacji (401)
• TMDBNotFoundError - zasób nie znaleziony (404)
• TMDBValidationError - błąd walidacji (422)
• TMDBRateLimitError - przekroczony limit zapytań (429)
• TMDBServerError - błąd serwera (5xx)

Wymagania

• Python 3.8+
• httpx >= 0.24.0
• pydantic >= 2.0.0

Licencja

MIT

Linki

• TMDB API Documentation
• Oryginalna biblioteka tmdb-ts

Podsumowanie implementacji

✅ Wszystkie 27 metod API zostały zaimplementowane:

• SearchEndpoint: 3 metody
• MoviesEndpoint: 8 metod
• TvShowsEndpoint: 7 metod
• TvSeasonsEndpoint: 3 metody
• TvEpisodesEndpoint: 3 metody
• TrendingEndpoint: 1 metoda
• GenreEndpoint: 2 metody

Przykład użycia - kompletny workflow

from tmdb_py import TMDB

# Inicjalizacja
tmdb = TMDB('eyJhbGciOiJIUzI1NiJ9...')

# 1. Wyszukaj film
search_results = tmdb.search.movies(query='The Matrix')
movie_id = search_results['results'][0]['id']

# 2. Pobierz szczegóły z dodatkowymi informacjami
movie = tmdb.movies.details(
    movie_id=movie_id,
    append_to_response=['credits', 'videos', 'images', 'similar']
)

print(f"Tytuł: {movie['title']}")
print(f"Rok: {movie['release_date'][:4]}")
print(f"Ocena: {movie['vote_average']}/10")

# 3. Pobierz podobne filmy
similar = tmdb.movies.similar(movie_id=movie_id)
print(f"\nPodobne filmy:")
for film in similar['results'][:5]:
    print(f"- {film['title']}")

# 4. Sprawdź trendy
trending = tmdb.trending.trending(media_type='movie', time_window='week')
print(f"\nTrendujące filmy tego tygodnia:")
for film in trending['results'][:5]:
    print(f"- {film['title']}")