tmdbpy-wrapper 1.0.0
TMDB v3 API wrapper for Python
License: MIT
Requires Python: >=3.8
Keywords: tmdb, movies, database, api, python

# TMDB-PY

Python wrapper dla TMDB (The Movie Database) API v3, wzorowany na bibliotece `tmdb-ts`.

## Instalacja

```bash
pip install tmdb-py
```

lub z repozytorium:

```bash
pip install -e .
```

## Szybki start

```python
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)

```python
# 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)

```python
# 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)

```python
# 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)

```python
# 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)

```python
# 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)

```python
# 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)

```python
# 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

```python
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](https://developers.themoviedb.org/3)
- [Oryginalna biblioteka tmdb-ts](https://github.com/blakejoy/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

```python
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']}")
```