Merge branch 'add-feature-discover'

README.md

@@ -134,6 +134,161 @@ names where the year is contained in parentheses, as in:
     >>> list(searchMovieWithYear('Star Wars (1977)'))
     [<Movie 'Star Wars: Episode IV - A New Hope' (1977)>, <Movie 'The Making of 'Star Wars'' (1977)>]
 
+Discovering:
+------------
+
+The `discoverTv()` and `discoverMovie()` methods accepts multiple `kwargs`,
+which tells TMDB to filter the tvshows or movies depending on that keywords.
+The search methods provided by the python3-tmdb3 module return list-like
+structures that will automatically grab new pages as needed, as we do with
+the search methods.
+
+> As a side note:
+> - `discoverTv()`: returns a list-like structure of `Series` instances
+> - `discoverMovie()`: returns a list-like structure of `Movie` instances
+
+**discoverTv `kwargs`**:
+************************
+
+* `sort_by`:
+    - vote_average.desc
+    - vote_average.asc
+    - first_air_date.desc
+    - first_air_date.asc
+    - popularity.desc
+    - popularity.asc
+
+* `first_air_date_year`: A string in the format `yyyy-mm-dd`
+
+* `with_genres`: Comma separated value of genre ids that you want to include in
+the results
+
+* `with_networks`: Comma separated value of network ids that you want to
+include in the results
+
+* `without_genres`: Comma separated value of genre ids that you want to exclude
+from the results
+
+* `without_keywords`: Exclude items with certain keywords. You can comma and
+pipe separate these values to create an 'AND' or 'OR' logic
+
+* `air_date_gte`: Filter and only include TV shows that have a air date (by
+looking at all episodes) that is greater or equal to the specified value
+
+* `air_date_lte`: Filter and only include TV shows that have a air date (by
+looking at all episodes) that is less than or equal to the specified value
+
+
+* `first_air_date_gte`: Filter and only include TV shows that have a original
+air date that is greater or equal to the specified value
+
+* `first_air_date_lte`: Filter and only include TV shows that have a original
+air date that is less than or equal to the specified value
+
+* `vote_average_gte`: Filter and only include movies that have a rating that is
+greater or equal to the specified value
+
+* `vote_count_gte`: Filter and only include movies that have a rating that is
+less than or equal to the specified value
+
+* `with_runtime_gte`: Filter and only include TV shows with an episode runtime
+that is greater than or equal to a value
+
+* `with_runtime_lte`: Filter and only include TV shows with an episode runtime
+that is less than or equal to a value
+
+**discoverMovie `kwargs`**:
+***************************
+
+* `region`: Specify a ISO 3166-1 code to filter release dates. Must be uppercase.
+
+
+* `sort_by`:
+    - popularity.asc
+    - popularity.desc
+    - release_date.asc
+    - release_date.desc
+    - revenue.asc
+    - revenue.desc
+    - primary_release_date.asc
+    - primary_release_date.desc
+    - original_title.asc
+    - original_title.desc
+    - vote_average.asc
+    - vote_average.desc
+    - vote_count.asc
+    - vote_count.desc
+
+* `include_adult`: A filter and include or exclude adult movies.  (true/false)
+
+* `primary_release_year`: A filter to limit the results to a specific primary
+
+* `primary_release_date_gte`: Filter and only include movies that have a
+primary release date that is greater or equal to the specified value.
+
+* `primary_release_date_lte`: Filter and only include movies that have a
+primary release date that is less than or equal to the specified value.
+
+* `release_date_gte`: Filter and only include movies that have a release date
+(looking at all release dates) that is greater or equal to the specified
+value.
+
+* `release_date_lte`: Filter and only include movies that have a release date
+(looking at all release dates) that is less than or equal to the specified
+value.
+
+* `vote_count_gte`: Filter and only include movies that have a vote count that
+is greater or equal to the specified value.
+
+* `vote_count_lte`: Filter and only include movies that have a vote count that
+is less than or equal to the specified value.
+
+* `vote_average_gte`: Filter and only include movies that have a rating that
+is greater or equal to the specified value.
+
+* `vote_average_lte`: Filter and only include movies that have a rating that
+is less than or equal to the specified value.
+
+* `with_cast`: A comma separated list of person ID's. Only include movies that
+have one of the ID's added as an actor.
+
+* `with_crew`: A comma separated list of person ID's. Only include movies that
+have one of the ID's added as a crew member.
+
+* `with_companies`: A comma separated list of production company ID's. Only
+include movies that have one of the ID's added as a production company.
+
+* `with_genres`: Comma separated value of genre ids that you want to include
+in the results.
+
+* `with_keywords`: A comma separated list of keyword ID's. Only include movies
+that have one of the ID's added as a keyword.
+
+* `with_people`: A comma separated list of person ID's. Only include movies
+that have one of the ID's added as a either a actor or a crew member.
+
+* `year`: A filter to limit the results to a specific year (looking at all
+release dates).
+
+* `without_genres`: Comma separated value of genre ids that you want to
+exclude from the results.
+
+* `with_runtime_gte`: Filter and only include movies that have a runtime that
+is greater or equal to a value.
+
+* `with_runtime_lte`: Filter and only include movies that have a runtime that
+is less than or equal to a value.
+
+* `with_release_type`: Specify a comma (AND) or pipe (OR) separated value to
+filter release types by. These release types map to the same values found on
+the movie release date method (minimum: 1, maximum: 6)
+
+* `with_original_language`: Specify an ISO 639-1 string to filter results by
+their original language value.
+
+* `without_keywords`: Exclude items with certain keywords. You can comma and
+pipe separate these values to create an 'AND' or 'OR' logic.
+
 
 Direct Queries
 --------------

tests/data/movie_discover_company_1.json

@@ -0,0 +1,45 @@
+{
+  "page": 1,
+  "total_results": 2,
+  "total_pages": 1,
+  "results": [
+    {
+      "vote_count": 11270,
+      "id": 11,
+      "video": false,
+      "vote_average": 8.2,
+      "title": "Star Wars",
+      "popularity": 46.877,
+      "poster_path": "/btTdmkgIvOi0FFip1sPuZI2oQG6.jpg",
+      "original_language": "en",
+      "original_title": "Star Wars",
+      "genre_ids": [
+        12,
+        28,
+        878
+      ],
+      "backdrop_path": "/4iJfYYoQzZcONB9hNzg0J0wWyPH.jpg",
+      "adult": false,
+      "overview": "Princess Leia is captured and held hostage by the evil Imperial forces in their effort to take over the galactic Empire. Venturesome Luke Skywalker and dashing captain Han Solo team together with the loveable robot duo R2-D2 and C-3PO to rescue the beautiful princess and restore peace and justice in the Empire.",
+      "release_date": "1977-05-25"
+    },
+    {
+      "vote_count": 21,
+      "id": 72694,
+      "video": false,
+      "vote_average": 7.2,
+      "title": "The Making of 'Star Wars'",
+      "popularity": 1.931,
+      "poster_path": "/WgsInarGqxj5a33H1oO1IJACDU.jpg",
+      "original_language": "en",
+      "original_title": "The Making of 'Star Wars'",
+      "genre_ids": [
+        99
+      ],
+      "backdrop_path": "/oxWdpHHrdGaB3ZK4JpBnEQ8msrp.jpg",
+      "adult": false,
+      "overview": "Ever wonder how they ever managed to make a movie like Star Wars? Well, bickering droid duo C-3PO and R2-D2 host this tour of the mind of creator George Lucas and what inspired him to make the movie. Even interviewed are the cast and crew, even features scenes of when C-3PO, R2-D2, and Darth Vader planted their footprints (or in R2's case, tread-prints) into cement. Also discussed is Star Wars mania, how fans loved the movie, collected the merchandise and danced the disco music. Also shown are behind-the-scenes looks at the movie, as well as how difficult each effect was in doing since they didn't have the convenience of computer animation back then.",
+      "release_date": "1977-09-16"
+    }
+  ]
+}