Skip to content

Commit b5219fa

Browse files
Electronic-MangoElectronic-Mango
committed
Update docs regarding new filtering options
1 parent ede5685 commit b5219fa

3 files changed

Lines changed: 78 additions & 58 deletions

File tree

‎docs/caveats.md‎

Lines changed: 0 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -296,20 +296,3 @@ popular_results = popular("US", providers=list(name_to_code_dict.values()))
296296
!!! tip "When this actually might be useful"
297297
This only makes sense if you are already using other functions. To get **just** the
298298
codes use the [`providers`](#providers-function) function instead.
299-
300-
301-
302-
## Filtering by type
303-
304-
Functions [`search`](#search-for-a-title) and [`popular`](#popular-titles) allow for
305-
filtering of returned entries by "types". The types are list of strings (or just a single
306-
string), like `SHOW`, `MOVIE`. You can check
307-
[`examples/`](https://github.com/Electronic-Mango/simple-justwatch-python-api/tree/main/examples)
308-
for field `object_type`, however the only "useful" ones seem `SHOW` and `MOVIE`. You can
309-
use types like `SHOW_EPISODE`, or `SHOW_SEASON`, however they seem to default to "TV
310-
shows" - the same as for type `SHOW`.
311-
312-
!!! warning "Types are not enforced, but must be valid"
313-
While possible types are not enforced by functions in this API, they still **must**
314-
be valid types in JustWatch API. Using unexpected type will result in HTTP error with
315-
code 422.

‎docs/usage.md‎

Lines changed: 32 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -47,23 +47,25 @@ You can check [Exceptions](API Reference/exceptions.md) page for more details.
4747
Most functions have a number of common arguments (in addition to function-specific
4848
ones, like `title` to search for):
4949

50-
| Name | Description |
51-
|-------------|-------------|
52-
| `country` | 2-letter country code for which offers will be returned, e.g., `US`, `GB`, `DE`. |
53-
| `language` | Code for language in responses. It consists of 2 lowercase letters with optional uppercase alphanumeric suffix (e.g., `en`, `en-US`, `de`, `de-CH1901`). |
50+
| Name | Description |
51+
|------|-------------|
52+
| `country` | 2-letter country code for which offers will be returned, e.g., `US`, `GB`, `DE`. |
53+
| `language` | Code for language in responses. It consists of 2 lowercase letters with optional uppercase alphanumeric suffix (e.g., `en`, `en-US`, `de`, `de-CH1901`). |
5454
| `best_only` | Whether to return only "best" offers for each provider instead of, e.g., separate offers for SD, HD, and 4K. |
5555

5656
Functions returning data for multiple titles
5757
([`search`][simplejustwatchapi.justwatch.search],
5858
[`popular`][simplejustwatchapi.justwatch.popular])
59-
also allow for specifying number of elements, basic pagination, and filtering for
60-
specific providers:
59+
also allow for specifying number of elements, basic pagination, and optional filtering:
6160

62-
| Name | Description |
63-
|-------------|-------------|
64-
| `count` | How many entries should be returned. |
65-
| `offset` | Basic "pagination". Offset for the first returned result, i.e. how many first entries should be skipped. Everything is handled on API side, this library isn't doing any filtering. |
66-
| `providers` | Providers (like Netflix, Amazon Prime Video) for which offers should returned. Requires 3-letter "short name". Check [Provider codes](caveats.md#provider-codes) page for an example of how you can get that value.
61+
| Name | Description |
62+
|------|-------------|
63+
| `count` | How many entries should be returned. |
64+
| `offset` | Basic "pagination". Offset for the first returned result, i.e. how many first entries should be skipped. Everything is handled on API side, this library isn't doing any filtering. |
65+
| `providers` | Providers (like Netflix, Amazon Prime Video) for which offers should returned. Requires 3-letter "short name". Check [Provider codes](caveats.md#provider-codes) page for an example of how you can get that value. |
66+
| `min_release_year` | Minimum release year for a title. |
67+
| `max_release_year` | Maximum release year for a title. |
68+
| `object_types` | Types of objects to filter for, such as `SHOW` or `MOVIE`. Check [Additional filtering](#additional-filtering-in-search-and-popular) section for more details. |
6769

6870

6971
### Search for a title
@@ -505,18 +507,31 @@ while results := popular(count=page, offset=i):
505507

506508

507509

508-
### Additional filtering in [`search`](#search-for-a-title) and [`popular`](#popular-titles)
510+
## Additional filtering in [`search`](#search-for-a-title) and [`popular`](#popular-titles)
509511

510512
[`search`](#search-for-a-title) and [`popular`](#popular-titles) functions allow for
511513
additional filtering of returned entries.
512514

513-
| Field | Description |
514-
| ------| ----------- |
515-
| `object_types` | Types like `SHOW` or `MOVIE`. Values are not enforced, but types like `SHOW_EPISODE` or `SHOW_SEASON` return shows anyway; like `SHOW`. While not enforced they **must** be valid types. It can be either a list of strings, or a single string. |
515+
| Argument name | Description |
516+
|---------------|-------------|
516517
| `min_release_year` | Minimum release year. |
517518
| `max_release_year` | Maximum release year. |
519+
| `object_types` | Media types, like `SHOW` or `MOVIE`. |
518520

519-
All filters are optional; when not configured (or set to `None`) the filtering is disabled.
521+
All filters are optional; when not configured (or set to `None`) the filtering is
522+
disabled.
523+
524+
`object_types` is a list of strings (or for one type just a single string),
525+
like `SHOW`, or `MOVIE`. You can check
526+
[`examples/`](https://github.com/Electronic-Mango/simple-justwatch-python-api/tree/main/examples)
527+
for field `object_type`, however the only "useful" ones seem to be `SHOW` and `MOVIE`.
528+
You can use types like `SHOW_EPISODE`, or `SHOW_SEASON`, however they seem to default
529+
to "TV shows" - same as for `SHOW`.
530+
531+
!!! warning "Type values are not enforced, but must be valid"
532+
Possible values for types are not enforced by functions in this API, but they still
533+
**must** be valid types in JustWatch API. Using unexpected type will result in HTTP
534+
error with code 422.
520535

521536
```python
522537
from simplejustwatchapi import popular, search
@@ -531,5 +546,5 @@ movies = search(
531546
max_release_year=2010,
532547
object_types="MOVIE"
533548
)
534-
# object_types with single element can be either a list, or just a string.
549+
# "object_types" with single type can be either a list, or just a string.
535550
```

‎src/simplejustwatchapi/justwatch.py‎

Lines changed: 46 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -9,11 +9,11 @@
99
Most functions have a number of common arguments (in addition to function-specific
1010
ones, like `title` to search for):
1111
12-
| Name | Description |
13-
|-------------|-------------|
14-
| `country` | 2-letter country code for which offers are selected, (e.g., `US`, \
12+
| Name | Description |
13+
|------|-------------|
14+
| `country` | 2-letter country code for which offers are selected, (e.g., `US`, \
1515
`GB`, `DE`). |
16-
| `language` | Code for language in responses. It consists of 2 lowercase letters \
16+
| `language` | Code for language in responses. It consists of 2 lowercase letters \
1717
with optional uppercase alphanumeric suffix (e.g., `en`, `en-US`, \
1818
`de`, `de-CH1901`). |
1919
| `best_only` | Whether to return only "best" offers for each provider instead of, \
@@ -22,13 +22,13 @@
2222
Functions returning data for multiple titles
2323
([`search`][simplejustwatchapi.justwatch.search],
2424
[`popular`][simplejustwatchapi.justwatch.popular])
25-
also allow for specifying number of elements, basic pagination, and filtering for
26-
specific providers:
25+
also allow for specifying number of elements, basic pagination, and additional
26+
filtering:
2727
28-
| Name | Description |
29-
|-------------|-------------|
30-
| `count` | How many entries should be returned. |
31-
| `offset` | Basic "pagination". Offset for the first returned result, i.e. how \
28+
| Name | Description |
29+
|------|-------------|
30+
| `count` | How many entries should be returned. |
31+
| `offset` | Basic "pagination". Offset for the first returned result, i.e. how \
3232
many first entries should be skipped. Everything is handled on API \
3333
side, this library isn't doing any filtering. |
3434
| `providers` | Providers (like Netflix, Amazon Prime Video) for which offers should \
@@ -37,10 +37,8 @@
3737
of how you can get that value. |
3838
| `min_release_year` | Minimum release year of returned titles. |
3939
| `max_release_year` | Maximum release year of returned titles. |
40-
| `object_types` | Types of objects to filter for, it seems that only `SHOW` and \
41-
`MOVIE` are useful, but it's not strictly enforced. Types like \
42-
`SHOW_EPISODE`, or `SHOW_SEASON` can be used but they seem to \
43-
return shows, the same as `SHOW` type. |
40+
| `object_types` | Types of objects to filter for. It seems that only `SHOW` and \
41+
`MOVIE` are useful, but it's not strictly enforced. |
4442
4543
Each function can raise two exceptions:
4644
@@ -158,23 +156,34 @@ def search(
158156
[simplejustwatchapi.justwatch.providers] function.
159157
160158
min_release_year (int | None): Minimum release year of returned titles.
159+
161160
If `None` (the default value), no filtering is done.
162161
163162
max_release_year (int | None): Maximum release year of returned titles.
163+
164164
If `None` (the default value), no filtering is done.
165165
166-
object_types (list[str] | str | None): Types of objects to filter for, it seems
167-
that only `SHOW` and `MOVIE` are useful, but it's not strictly enforced.
168-
Types like `SHOW_EPISODE`, or `SHOW_SEASON` can be used but they seem to
169-
return shows, the same as `SHOW` type. If `None` (the default value), no
170-
filtering is done.
166+
object_types (list[str] | str | None): Types of objects to filter for, like
167+
`SHOW` or `MOVIE`.
168+
169+
It seems that only `SHOW` and `MOVIE` are useful, but it's not strictly
170+
enforced. Types like `SHOW_EPISODE`, or `SHOW_SEASON` can be used, but they
171+
seem to return TV shows, same as `SHOW`.
172+
173+
While the type value is not enforced, it **must** be a valid type, otherwise
174+
API will respond with HTTP status code 422.
175+
176+
For single type it can be a single string, or a list with one string.
177+
178+
If `None` (the default value), no filtering is done.
171179
172180
Returns:
173181
(list[MediaEntry]): List of tuples with details of search results.
174182
175183
Raises:
176184
exceptions.JustWatchApiError: JSON response from API has internal errors, e.g.,
177185
due to invalid language or country code.
186+
178187
exceptions.JustWatchHttpError: HTTP error occurred, e.g., JustWatch API
179188
responded with non-`2xx` status code.
180189
@@ -272,18 +281,27 @@ def popular(
272281
max_release_year (int | None): Maximum release year of returned titles.
273282
If `None` (the default value), no filtering is done.
274283
275-
object_types (list[str] | str | None): Types of objects to filter for, it seems
276-
that only `SHOW` and `MOVIE` are useful, but it's not strictly enforced.
277-
Types like `SHOW_EPISODE`, or `SHOW_SEASON` can be used but they seem to
278-
return shows, the same as `SHOW` type. If `None` (the default value), no
279-
filtering is done.
284+
object_types (list[str] | str | None): Types of objects to filter for, like
285+
`SHOW` or `MOVIE`.
286+
287+
It seems that only `SHOW` and `MOVIE` are useful, but it's not strictly
288+
enforced. Types like `SHOW_EPISODE`, or `SHOW_SEASON` can be used, but they
289+
seem to return TV shows, same as `SHOW`.
290+
291+
While the type value is not enforced, it **must** be a valid type, otherwise
292+
API will respond with HTTP status code 422.
293+
294+
For single type it can be a single string, or a list with one string.
295+
296+
If `None` (the default value), no filtering is done.
280297
281298
Returns:
282299
(list[MediaEntry]): List of tuples with details of popular titles.
283300
284301
Raises:
285302
exceptions.JustWatchApiError: JSON response from API has internal errors, e.g.,
286303
due to invalid language or country code.
304+
287305
exceptions.JustWatchHttpError: HTTP error occurred, e.g., JustWatch API
288306
responded with non-`2xx` status code.
289307
@@ -362,6 +380,7 @@ def details(
362380
Raises:
363381
exceptions.JustWatchApiError: JSON response from API has internal errors, e.g.,
364382
due to invalid language or country code.
383+
365384
exceptions.JustWatchHttpError: HTTP error occurred, e.g., JustWatch API
366385
responded with non-`2xx` status code.
367386
@@ -411,6 +430,7 @@ def seasons(
411430
Raises:
412431
exceptions.JustWatchApiError: JSON response from API has internal errors, e.g.,
413432
due to invalid language or country code.
433+
414434
exceptions.JustWatchHttpError: HTTP error occurred, e.g., JustWatch API
415435
responded with non-`2xx` status code.
416436
@@ -461,6 +481,7 @@ def episodes(
461481
Raises:
462482
exceptions.JustWatchApiError: JSON response from API has internal errors, e.g.,
463483
due to invalid language or country code.
484+
464485
exceptions.JustWatchHttpError: HTTP error occurred, e.g., JustWatch API
465486
responded with non-`2xx` status code.
466487
@@ -530,6 +551,7 @@ def offers_for_countries(
530551
Raises:
531552
exceptions.JustWatchApiError: JSON response from API has internal errors, e.g.,
532553
due to invalid language or country code.
554+
533555
exceptions.JustWatchHttpError: HTTP error occurred, e.g., JustWatch API
534556
responded with non-`2xx` status code.
535557

0 commit comments

Comments
 (0)