Feature: Add pagination to User.get_watched_movies (#115)

Author: glensc

tests/mock_data/users.json

@@ -612,6 +612,15 @@
             }
         ]
     },
+    "users/sean/watched/movies?page=1&limit=1": {
+        "GET": [
+            {
+                "plays":4,
+                "last_watched_at":"2014-10-11T17:00:54.000Z",
+                "movie":{"title":"Batman Begins","year":2005,"ids":{"trakt":6,"slug":"batman-begins-2005","imdb":"tt0372784","tmdb":272}}
+            }
+        ]
+    },
     "users/sean/watched/shows": {
         "GET": [
             {

tests/test_users.py

@@ -1,4 +1,5 @@
 # -*- coding: utf-8 -*-
+import pytest
 from trakt.movies import Movie
 from trakt.people import Person
 from trakt.tv import TVEpisode, TVSeason, TVShow
@@ -132,6 +133,35 @@ def test_get_watched_movies():
     assert all([isinstance(m, Movie) for m in watched_movies])
 
 
+def test_get_watched_movies_with_pagination():
+    sean = User('sean')
+    watched_movies = sean.get_watched_movies(page=1, limit=1)
+    assert isinstance(watched_movies, list)
+    assert len(watched_movies) == 1
+    assert isinstance(watched_movies[0], Movie)
+    assert watched_movies[0].title == 'Batman Begins'
+
+
+def test_get_watched_movies_invalid_page():
+    sean = User('sean')
+    with pytest.raises(ValueError):
+        sean.get_watched_movies(page='bad')
+    with pytest.raises(ValueError):
+        sean.get_watched_movies(page=0)
+    with pytest.raises(ValueError):
+        sean.get_watched_movies(page=True)
+
+
+def test_get_watched_movies_invalid_limit():
+    sean = User('sean')
+    with pytest.raises(ValueError):
+        sean.get_watched_movies(limit='bad')
+    with pytest.raises(ValueError):
+        sean.get_watched_movies(limit=-1)
+    with pytest.raises(ValueError):
+        sean.get_watched_movies(limit=False)
+
+
 def test_stats():
     sean = User('sean')
     assert isinstance(sean.get_stats(), dict)

tests/test_utils.py

@@ -2,7 +2,8 @@
 """unit tests for the trakt.utils module"""
 from datetime import datetime
 
-from trakt.utils import airs_date, extract_ids, now, slugify, timestamp
+from trakt.utils import (airs_date, build_uri, extract_ids, now, slugify,
+                         timestamp)
 
 
 def test_slugify():
@@ -61,3 +62,35 @@ def test_extract_ids():
     input_dict = {'ids': ids}
     result = extract_ids(input_dict)
     assert result == ids
+
+
+def test_build_uri():
+    """verify that uri query params are appended correctly"""
+    assert build_uri('users/{user}/watched/movies', user='sean') == \
+        'users/sean/watched/movies'
+    assert build_uri('shows/popular', page=2, limit=10) == \
+        'shows/popular?page=2&limit=10'
+    assert build_uri('shows/popular?extended={extended}', extended='full',
+                     page=2) == 'shows/popular?extended=full&page=2'
+
+
+def test_build_uri_pagination_validation():
+    """verify that pagination params are validated by the helper"""
+    from pytest import raises
+
+    with raises(ValueError, match='page must be a positive integer'):
+        build_uri('shows/popular', page=0)
+
+    with raises(ValueError, match='limit must be a valid integer'):
+        build_uri('shows/popular', limit='invalid')
+
+
+def test_validate_pagination_param_rejects_bools_and_fractional_floats():
+    """verify pagination validation rejects values that should not coerce"""
+    from pytest import raises
+
+    with raises(ValueError, match='page must be a valid integer'):
+        build_uri('shows/popular', page=True)
+
+    with raises(ValueError, match='limit must be a valid integer'):
+        build_uri('shows/popular', limit=1.5)

trakt/users.py

@@ -9,7 +9,7 @@
 from trakt.movies import Movie
 from trakt.people import Person
 from trakt.tv import TVEpisode, TVSeason, TVShow
-from trakt.utils import slugify
+from trakt.utils import build_uri, slugify
 
 __author__ = 'Jon Nappi'
 __all__ = ['User', 'UserList', 'PublicList', 'Request', 'follow', 'get_all_requests',
@@ -523,15 +523,21 @@ def _build_watched_movies(self, data):
         return watched_movies
 
     @get
-    def get_watched_movies(self):
-        """Watched progress for all :class:`Movie` objects for this
-        :class:`User`.
+    def get_watched_movies(self, page=None, limit=None):
+        """Watched progress for :class:`Movie` objects for this :class:`User`.
 
-        :return: List of :class:`Movie` instances
+        :param page: Optional page number for pagination.
+        :param limit: Optional number of items per page.
+        :return: List of :class:`Movie` instances for the requested page
         """
-        data = yield 'users/{user}/watched/movies'.format(
-            user=slugify(self.username)
+        uri = build_uri(
+            'users/{user}/watched/movies',
+            user=slugify(self.username),
+            page=page,
+            limit=limit,
         )
+
+        data = yield uri
         yield self._build_watched_movies(data)
 
     @property

trakt/utils.py

@@ -2,9 +2,11 @@
 import re
 import unicodedata
 from datetime import datetime, timezone
+from urllib.parse import urlencode
 
-__author__ = 'Jon Nappi'
-__all__ = ['slugify', 'airs_date', 'now', 'timestamp', 'extract_ids']
+__author__ = 'Jon Nappi, Elan Ruusamäe'
+__all__ = ['slugify', 'airs_date', 'now', 'timestamp', 'extract_ids',
+           'build_uri']
 
 
 def slugify(value):
@@ -56,3 +58,54 @@ def extract_ids(id_dict):
     """
     id_dict.update(id_dict.pop('ids', {}))
     return id_dict
+
+
+def _validate_pagination_param(name, value):
+    """Validate and coerce a pagination parameter to a positive integer.
+
+    :param name: Parameter name used in error messages.
+    :param value: Value to validate.
+    :return: The validated integer value.
+    :raises ValueError: If value is not a valid positive integer.
+    """
+
+    try:
+        # bool is a subclass of int; reject it explicitly to avoid accepting True/False.
+        if isinstance(value, bool):
+            raise ValueError
+
+        # Avoid silently truncating noninteger floats (e.g., 1.9 -> 1).
+        if isinstance(value, float) and not value.is_integer():
+            raise ValueError
+
+        value = int(value)
+    except (TypeError, ValueError):
+        raise ValueError(f'{name} must be a valid integer')
+
+    if value < 1:
+        raise ValueError(f'{name} must be a positive integer')
+
+    return value
+
+
+def build_uri(uri, page=None, limit=None, **params):
+    """Format *uri* and append pagination query parameters.
+
+    ``page`` and ``limit`` are validated as positive integers and become query
+    parameters. Remaining keyword arguments are applied via ``str.format`` on
+    *uri*; any ``None`` values are dropped before formatting (so a missing
+    placeholder will raise ``KeyError``).
+    """
+    params = {key: value for key, value in params.items() if value is not None}
+    uri = uri.format(**params)
+
+    query = []
+    if page is not None:
+        query.append(('page', _validate_pagination_param('page', page)))
+    if limit is not None:
+        query.append(('limit', _validate_pagination_param('limit', limit)))
+
+    if query:
+        uri += ('&' if '?' in uri else '?') + urlencode(query)
+
+    return uri